compiling.rst 1.98 KB
Newer Older
Wenzel Jakob's avatar
Wenzel Jakob committed
1
2
3
4
5
6
7
8
9
Build systems
#############

Building with setuptools
========================

For projects on PyPI, building with setuptools is the way to go. Sylvain Corlay
has kindly provided an example project which shows how to set up everything,
including automatic generation of documentation using Sphinx. Please refer to
Wenzel Jakob's avatar
Wenzel Jakob committed
10
the [python_example]_ repository.
Wenzel Jakob's avatar
Wenzel Jakob committed
11

Wenzel Jakob's avatar
Wenzel Jakob committed
12
.. [python_example] https://github.com/pybind/python_example
Wenzel Jakob's avatar
Wenzel Jakob committed
13

14
15
16
17
18
19
20
21
22
23
Building with cppimport
========================

 cppimport is a small Python import hook that determines whether there is a C++
 source file whose name matches the requested module. If there is, the file is
 compiled as a Python extension using pybind11 and placed in the same folder as
 the C++ source file. Python is then able to find the module and load it.

.. [cppimport] https://github.com/tbenthompson/cppimport

24
25
26
27
28
.. _cmake:

Building with CMake
===================

Wenzel Jakob's avatar
Wenzel Jakob committed
29
For C++ codebases that have an existing CMake-based build system, a Python
30
extension module can be created with just a few lines of code:
31
32
33

.. code-block:: cmake

34
    cmake_minimum_required(VERSION 2.8.12)
35
36
    project(example)

37
38
39
    add_subdirectory(pybind11)
    pybind11_add_module(example example.cpp)

Wenzel Jakob's avatar
Wenzel Jakob committed
40
This assumes that the pybind11 repository is located in a subdirectory named
41
42
43
44
45
:file:`pybind11` and that the code is located in a file named :file:`example.cpp`.
The CMake command ``add_subdirectory`` will import a function with the signature
``pybind11_add_module(<name> source1 [source2 ...])``. It will take care of all
the details needed to build a Python extension module on any platform.

Wenzel Jakob's avatar
Wenzel Jakob committed
46
47
The target Python version can be selected by setting the ``PYBIND11_PYTHON_VERSION``
variable before adding the pybind11 subdirectory. Alternatively, an exact Python
48
49
50
51
52
installation can be specified by setting ``PYTHON_EXECUTABLE``.

A working sample project, including a way to invoke CMake from :file:`setup.py` for
PyPI integration, can be found in the [cmake_example]_  repository.

Wenzel Jakob's avatar
Wenzel Jakob committed
53
.. [cmake_example] https://github.com/pybind/cmake_example