compiling.rst revision 11986:c12e4625ab56 
1Build systems
2#############
3
4Building with setuptools
5========================
6
7For projects on PyPI, building with setuptools is the way to go. Sylvain Corlay
8has kindly provided an example project which shows how to set up everything,
9including automatic generation of documentation using Sphinx. Please refer to
10the [python_example]_ repository.
11
12.. [python_example] https://github.com/pybind/python_example
13
14Building with cppimport
15========================
16
17 cppimport is a small Python import hook that determines whether there is a C++
18 source file whose name matches the requested module. If there is, the file is
19 compiled as a Python extension using pybind11 and placed in the same folder as
20 the C++ source file. Python is then able to find the module and load it.
21
22.. [cppimport] https://github.com/tbenthompson/cppimport
23
24.. _cmake:
25
26Building with CMake
27===================
28
29For C++ codebases that have an existing CMake-based build system, a Python
30extension module can be created with just a few lines of code:
31
32.. code-block:: cmake
33
34    cmake_minimum_required(VERSION 2.8.12)
35    project(example)
36
37    add_subdirectory(pybind11)
38    pybind11_add_module(example example.cpp)
39
40This assumes that the pybind11 repository is located in a subdirectory named
41:file:`pybind11` and that the code is located in a file named :file:`example.cpp`.
42The CMake command ``add_subdirectory`` will import a function with the signature
43``pybind11_add_module(<name> source1 [source2 ...])``. It will take care of all
44the details needed to build a Python extension module on any platform.
45
46The target Python version can be selected by setting the ``PYBIND11_PYTHON_VERSION``
47variable before adding the pybind11 subdirectory. Alternatively, an exact Python
48installation can be specified by setting ``PYTHON_EXECUTABLE``.
49
50A working sample project, including a way to invoke CMake from :file:`setup.py` for
51PyPI integration, can be found in the [cmake_example]_  repository.
52
53.. [cmake_example] https://github.com/pybind/cmake_example
54
55For CMake-based projects that don't include the pybind11
56repository internally, an external installation can be detected
57through `find_package(pybind11 ... CONFIG ...)`. See the `Config file
58<https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in>`_
59docstring for details of relevant CMake variables.
60
61Once detected, and after setting any variables to guide Python and
62C++ standard detection, the aforementioned ``pybind11_add_module``
63wrapper to ``add_library`` can be employed as described above (after
64``include(pybind11Tools)``). This procedure is available when using CMake
65>= 2.8.12. A working example can be found at [test_installed_module]_ .
66
67.. code-block:: cmake
68
69    cmake_minimum_required(VERSION 2.8.12)
70    project(example)
71
72    find_package(pybind11 REQUIRED)
73    pybind11_add_module(example example.cpp)
74
75.. [test_installed_module] https://github.com/pybind/pybind11/blob/master/tests/test_installed_module/CMakeLists.txt
76
77When using a version of CMake greater than 3.0, pybind11 can
78additionally be used as a special *interface library* following the
79call to ``find_package``. CMake variables to guide Python and C++
80standard detection should be set *before* ``find_package``. When
81``find_package`` returns, the target ``pybind11::pybind11`` is
82available with pybind11 headers, Python headers and libraries as
83needed, and C++ compile definitions attached. This target is suitable
84for linking to an independently constructed (through ``add_library``,
85not ``pybind11_add_module``) target in the consuming project. A working
86example can be found at [test_installed_target]_ .
87
88.. code-block:: cmake
89
90    cmake_minimum_required(VERSION 3.0)
91    project(example)
92
93    add_library(example MODULE main.cpp)
94
95    find_package(pybind11 REQUIRED)
96    target_link_libraries(example PRIVATE pybind11::pybind11)
97    set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}"
98                                             SUFFIX "${PYTHON_MODULE_EXTENSION}")
99
100.. warning::
101
102    Since pybind11 is a metatemplate library, it is crucial that certain
103    compiler flags are provided to ensure high quality code generation. In
104    contrast to the ``pybind11_add_module()`` command, the CMake interface
105    library only provides the *minimal* set of parameters to ensure that the
106    code using pybind11 compiles, but it does **not** pass these extra compiler
107    flags (i.e. this is up to you).
108
109    These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL``
110    and ``/LTCG`` on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC
111    (``-fvisibility=hidden``) and .OBJ files with many sections on Visual Studio
112    (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an
113    explanation on why these are needed.
114
115.. [test_installed_target] https://github.com/pybind/pybind11/blob/master/tests/test_installed_target/CMakeLists.txt
116
117