compiling.rst revision 12037:d28054ac6ec9
112855Sgabeblack@google.comBuild systems 212855Sgabeblack@google.com############# 312855Sgabeblack@google.com 412855Sgabeblack@google.comBuilding with setuptools 512855Sgabeblack@google.com======================== 612855Sgabeblack@google.com 712855Sgabeblack@google.comFor projects on PyPI, building with setuptools is the way to go. Sylvain Corlay 812855Sgabeblack@google.comhas kindly provided an example project which shows how to set up everything, 912855Sgabeblack@google.comincluding automatic generation of documentation using Sphinx. Please refer to 1012855Sgabeblack@google.comthe [python_example]_ repository. 1112855Sgabeblack@google.com 1212855Sgabeblack@google.com.. [python_example] https://github.com/pybind/python_example 1312855Sgabeblack@google.com 1412855Sgabeblack@google.comBuilding with cppimport 1512855Sgabeblack@google.com======================== 1612855Sgabeblack@google.com 1712855Sgabeblack@google.com cppimport is a small Python import hook that determines whether there is a C++ 1812855Sgabeblack@google.com source file whose name matches the requested module. If there is, the file is 1912855Sgabeblack@google.com compiled as a Python extension using pybind11 and placed in the same folder as 2012855Sgabeblack@google.com the C++ source file. Python is then able to find the module and load it. 2112855Sgabeblack@google.com 2212855Sgabeblack@google.com.. [cppimport] https://github.com/tbenthompson/cppimport 2312855Sgabeblack@google.com 2412855Sgabeblack@google.com.. _cmake: 2512855Sgabeblack@google.com 2612855Sgabeblack@google.comBuilding with CMake 2712855Sgabeblack@google.com=================== 2812855Sgabeblack@google.com 2912855Sgabeblack@google.comFor C++ codebases that have an existing CMake-based build system, a Python 3012855Sgabeblack@google.comextension module can be created with just a few lines of code: 3112855Sgabeblack@google.com 3212855Sgabeblack@google.com.. code-block:: cmake 3312855Sgabeblack@google.com 3412855Sgabeblack@google.com cmake_minimum_required(VERSION 2.8.12) 3512855Sgabeblack@google.com project(example) 3612855Sgabeblack@google.com 3712855Sgabeblack@google.com add_subdirectory(pybind11) 3812855Sgabeblack@google.com pybind11_add_module(example example.cpp) 3912855Sgabeblack@google.com 4012855Sgabeblack@google.comThis assumes that the pybind11 repository is located in a subdirectory named 4112855Sgabeblack@google.com:file:`pybind11` and that the code is located in a file named :file:`example.cpp`. 4212855Sgabeblack@google.comThe CMake command ``add_subdirectory`` will import the pybind11 project which 4312855Sgabeblack@google.comprovides the ``pybind11_add_module`` function. It will take care of all the 4412855Sgabeblack@google.comdetails needed to build a Python extension module on any platform. 4512855Sgabeblack@google.com 4612855Sgabeblack@google.comA working sample project, including a way to invoke CMake from :file:`setup.py` for 4712855Sgabeblack@google.comPyPI integration, can be found in the [cmake_example]_ repository. 4812855Sgabeblack@google.com 4912855Sgabeblack@google.com.. [cmake_example] https://github.com/pybind/cmake_example 5012855Sgabeblack@google.com 5112855Sgabeblack@google.compybind11_add_module 5212855Sgabeblack@google.com------------------- 5312855Sgabeblack@google.com 5412855Sgabeblack@google.comTo ease the creation of Python extension modules, pybind11 provides a CMake 5512855Sgabeblack@google.comfunction with the following signature: 5612855Sgabeblack@google.com 5712855Sgabeblack@google.com.. code-block:: cmake 5812855Sgabeblack@google.com 5912855Sgabeblack@google.com pybind11_add_module(<name> [MODULE | SHARED] [EXCLUDE_FROM_ALL] 6012855Sgabeblack@google.com [NO_EXTRAS] [THIN_LTO] source1 [source2 ...]) 6112855Sgabeblack@google.com 6212855Sgabeblack@google.comThis function behaves very much like CMake's builtin ``add_library`` (in fact, 6312855Sgabeblack@google.comit's a wrapper function around that command). It will add a library target 6412855Sgabeblack@google.comcalled ``<name>`` to be built from the listed source files. In addition, it 6512855Sgabeblack@google.comwill take care of all the Python-specific compiler and linker flags as well 6612855Sgabeblack@google.comas the OS- and Python-version-specific file extension. The produced target 6712855Sgabeblack@google.com``<name>`` can be further manipulated with regular CMake commands. 6812855Sgabeblack@google.com 6912855Sgabeblack@google.com``MODULE`` or ``SHARED`` may be given to specify the type of library. If no 7012855Sgabeblack@google.comtype is given, ``MODULE`` is used by default which ensures the creation of a 71Python-exclusive module. Specifying ``SHARED`` will create a more traditional 72dynamic library which can also be linked from elsewhere. ``EXCLUDE_FROM_ALL`` 73removes this target from the default build (see CMake docs for details). 74 75Since pybind11 is a template library, ``pybind11_add_module`` adds compiler 76flags to ensure high quality code generation without bloat arising from long 77symbol names and duplication of code in different translation units. The 78additional flags enable LTO (Link Time Optimization), set default visibility 79to *hidden* and strip unneeded symbols. See the :ref:`FAQ entry <faq:symhidden>` 80for a more detailed explanation. These optimizations are never applied in 81``Debug`` mode. If ``NO_EXTRAS`` is given, they will always be disabled, even 82in ``Release`` mode. However, this will result in code bloat and is generally 83not recommended. 84 85As stated above, LTO is enabled by default. Some newer compilers also support 86different flavors of LTO such as `ThinLTO`_. Setting ``THIN_LTO`` will cause 87the function to prefer this flavor if available. The function falls back to 88regular LTO if ``-flto=thin`` is not available. 89 90.. _ThinLTO: http://clang.llvm.org/docs/ThinLTO.html 91 92Configuration variables 93----------------------- 94 95By default, pybind11 will compile modules with the latest C++ standard 96available on the target compiler. To override this, the standard flag can 97be given explicitly in ``PYBIND11_CPP_STANDARD``: 98 99.. code-block:: cmake 100 101 set(PYBIND11_CPP_STANDARD -std=c++11) 102 add_subdirectory(pybind11) # or find_package(pybind11) 103 104Note that this and all other configuration variables must be set **before** the 105call to ``add_subdiretory`` or ``find_package``. The variables can also be set 106when calling CMake from the command line using the ``-D<variable>=<value>`` flag. 107 108The target Python version can be selected by setting ``PYBIND11_PYTHON_VERSION`` 109or an exact Python installation can be specified with ``PYTHON_EXECUTABLE``. 110For example: 111 112.. code-block:: bash 113 114 cmake -DPYBIND11_PYTHON_VERSION=3.6 .. 115 # or 116 cmake -DPYTHON_EXECUTABLE=path/to/python .. 117 118find_package vs. add_subdirectory 119--------------------------------- 120 121For CMake-based projects that don't include the pybind11 repository internally, 122an external installation can be detected through ``find_package(pybind11)``. 123See the `Config file`_ docstring for details of relevant CMake variables. 124 125.. code-block:: cmake 126 127 cmake_minimum_required(VERSION 2.8.12) 128 project(example) 129 130 find_package(pybind11 REQUIRED) 131 pybind11_add_module(example example.cpp) 132 133Once detected, the aforementioned ``pybind11_add_module`` can be employed as 134before. The function usage and configuration variables are identical no matter 135if pybind11 is added as a subdirectory or found as an installed package. You 136can refer to the same [cmake_example]_ repository for a full sample project 137-- just swap out ``add_subdirectory`` for ``find_package``. 138 139.. _Config file: https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in 140 141Advanced: interface library target 142---------------------------------- 143 144When using a version of CMake greater than 3.0, pybind11 can additionally 145be used as a special *interface library* . The target ``pybind11::module`` 146is available with pybind11 headers, Python headers and libraries as needed, 147and C++ compile definitions attached. This target is suitable for linking 148to an independently constructed (through ``add_library``, not 149``pybind11_add_module``) target in the consuming project. 150 151.. code-block:: cmake 152 153 cmake_minimum_required(VERSION 3.0) 154 project(example) 155 156 find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11) 157 158 add_library(example MODULE main.cpp) 159 target_link_libraries(example PRIVATE pybind11::module) 160 set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}" 161 SUFFIX "${PYTHON_MODULE_EXTENSION}") 162 163.. warning:: 164 165 Since pybind11 is a metatemplate library, it is crucial that certain 166 compiler flags are provided to ensure high quality code generation. In 167 contrast to the ``pybind11_add_module()`` command, the CMake interface 168 library only provides the *minimal* set of parameters to ensure that the 169 code using pybind11 compiles, but it does **not** pass these extra compiler 170 flags (i.e. this is up to you). 171 172 These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL`` 173 and ``/LTCG`` on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC 174 (``-fvisibility=hidden``) and .OBJ files with many sections on Visual Studio 175 (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an 176 explanation on why these are needed. 177 178Generating binding code automatically 179===================================== 180 181The ``Binder`` project is a tool for automatic generation of pybind11 binding 182code by introspecting existing C++ codebases using LLVM/Clang. See the 183[binder]_ documentation for details. 184 185.. [binder] http://cppbinder.readthedocs.io/en/latest/about.html 186