compiling.rst revision 12037
111986Sandreas.sandberg@arm.comBuild systems 211986Sandreas.sandberg@arm.com############# 311986Sandreas.sandberg@arm.com 411986Sandreas.sandberg@arm.comBuilding with setuptools 511986Sandreas.sandberg@arm.com======================== 611986Sandreas.sandberg@arm.com 711986Sandreas.sandberg@arm.comFor projects on PyPI, building with setuptools is the way to go. Sylvain Corlay 811986Sandreas.sandberg@arm.comhas kindly provided an example project which shows how to set up everything, 911986Sandreas.sandberg@arm.comincluding automatic generation of documentation using Sphinx. Please refer to 1011986Sandreas.sandberg@arm.comthe [python_example]_ repository. 1111986Sandreas.sandberg@arm.com 1211986Sandreas.sandberg@arm.com.. [python_example] https://github.com/pybind/python_example 1311986Sandreas.sandberg@arm.com 1411986Sandreas.sandberg@arm.comBuilding with cppimport 1511986Sandreas.sandberg@arm.com======================== 1611986Sandreas.sandberg@arm.com 1711986Sandreas.sandberg@arm.com cppimport is a small Python import hook that determines whether there is a C++ 1811986Sandreas.sandberg@arm.com source file whose name matches the requested module. If there is, the file is 1911986Sandreas.sandberg@arm.com compiled as a Python extension using pybind11 and placed in the same folder as 2011986Sandreas.sandberg@arm.com the C++ source file. Python is then able to find the module and load it. 2111986Sandreas.sandberg@arm.com 2211986Sandreas.sandberg@arm.com.. [cppimport] https://github.com/tbenthompson/cppimport 2311986Sandreas.sandberg@arm.com 2411986Sandreas.sandberg@arm.com.. _cmake: 2511986Sandreas.sandberg@arm.com 2611986Sandreas.sandberg@arm.comBuilding with CMake 2711986Sandreas.sandberg@arm.com=================== 2811986Sandreas.sandberg@arm.com 2911986Sandreas.sandberg@arm.comFor C++ codebases that have an existing CMake-based build system, a Python 3011986Sandreas.sandberg@arm.comextension module can be created with just a few lines of code: 3111986Sandreas.sandberg@arm.com 3211986Sandreas.sandberg@arm.com.. code-block:: cmake 3311986Sandreas.sandberg@arm.com 3411986Sandreas.sandberg@arm.com cmake_minimum_required(VERSION 2.8.12) 3511986Sandreas.sandberg@arm.com project(example) 3611986Sandreas.sandberg@arm.com 3711986Sandreas.sandberg@arm.com add_subdirectory(pybind11) 3811986Sandreas.sandberg@arm.com pybind11_add_module(example example.cpp) 3911986Sandreas.sandberg@arm.com 4011986Sandreas.sandberg@arm.comThis assumes that the pybind11 repository is located in a subdirectory named 4111986Sandreas.sandberg@arm.com:file:`pybind11` and that the code is located in a file named :file:`example.cpp`. 4212037Sandreas.sandberg@arm.comThe CMake command ``add_subdirectory`` will import the pybind11 project which 4312037Sandreas.sandberg@arm.comprovides the ``pybind11_add_module`` function. It will take care of all the 4412037Sandreas.sandberg@arm.comdetails needed to build a Python extension module on any platform. 4511986Sandreas.sandberg@arm.com 4611986Sandreas.sandberg@arm.comA working sample project, including a way to invoke CMake from :file:`setup.py` for 4711986Sandreas.sandberg@arm.comPyPI integration, can be found in the [cmake_example]_ repository. 4811986Sandreas.sandberg@arm.com 4911986Sandreas.sandberg@arm.com.. [cmake_example] https://github.com/pybind/cmake_example 5011986Sandreas.sandberg@arm.com 5112037Sandreas.sandberg@arm.compybind11_add_module 5212037Sandreas.sandberg@arm.com------------------- 5311986Sandreas.sandberg@arm.com 5412037Sandreas.sandberg@arm.comTo ease the creation of Python extension modules, pybind11 provides a CMake 5512037Sandreas.sandberg@arm.comfunction with the following signature: 5612037Sandreas.sandberg@arm.com 5712037Sandreas.sandberg@arm.com.. code-block:: cmake 5812037Sandreas.sandberg@arm.com 5912037Sandreas.sandberg@arm.com pybind11_add_module(<name> [MODULE | SHARED] [EXCLUDE_FROM_ALL] 6012037Sandreas.sandberg@arm.com [NO_EXTRAS] [THIN_LTO] source1 [source2 ...]) 6112037Sandreas.sandberg@arm.com 6212037Sandreas.sandberg@arm.comThis function behaves very much like CMake's builtin ``add_library`` (in fact, 6312037Sandreas.sandberg@arm.comit's a wrapper function around that command). It will add a library target 6412037Sandreas.sandberg@arm.comcalled ``<name>`` to be built from the listed source files. In addition, it 6512037Sandreas.sandberg@arm.comwill take care of all the Python-specific compiler and linker flags as well 6612037Sandreas.sandberg@arm.comas the OS- and Python-version-specific file extension. The produced target 6712037Sandreas.sandberg@arm.com``<name>`` can be further manipulated with regular CMake commands. 6812037Sandreas.sandberg@arm.com 6912037Sandreas.sandberg@arm.com``MODULE`` or ``SHARED`` may be given to specify the type of library. If no 7012037Sandreas.sandberg@arm.comtype is given, ``MODULE`` is used by default which ensures the creation of a 7112037Sandreas.sandberg@arm.comPython-exclusive module. Specifying ``SHARED`` will create a more traditional 7212037Sandreas.sandberg@arm.comdynamic library which can also be linked from elsewhere. ``EXCLUDE_FROM_ALL`` 7312037Sandreas.sandberg@arm.comremoves this target from the default build (see CMake docs for details). 7412037Sandreas.sandberg@arm.com 7512037Sandreas.sandberg@arm.comSince pybind11 is a template library, ``pybind11_add_module`` adds compiler 7612037Sandreas.sandberg@arm.comflags to ensure high quality code generation without bloat arising from long 7712037Sandreas.sandberg@arm.comsymbol names and duplication of code in different translation units. The 7812037Sandreas.sandberg@arm.comadditional flags enable LTO (Link Time Optimization), set default visibility 7912037Sandreas.sandberg@arm.comto *hidden* and strip unneeded symbols. See the :ref:`FAQ entry <faq:symhidden>` 8012037Sandreas.sandberg@arm.comfor a more detailed explanation. These optimizations are never applied in 8112037Sandreas.sandberg@arm.com``Debug`` mode. If ``NO_EXTRAS`` is given, they will always be disabled, even 8212037Sandreas.sandberg@arm.comin ``Release`` mode. However, this will result in code bloat and is generally 8312037Sandreas.sandberg@arm.comnot recommended. 8412037Sandreas.sandberg@arm.com 8512037Sandreas.sandberg@arm.comAs stated above, LTO is enabled by default. Some newer compilers also support 8612037Sandreas.sandberg@arm.comdifferent flavors of LTO such as `ThinLTO`_. Setting ``THIN_LTO`` will cause 8712037Sandreas.sandberg@arm.comthe function to prefer this flavor if available. The function falls back to 8812037Sandreas.sandberg@arm.comregular LTO if ``-flto=thin`` is not available. 8912037Sandreas.sandberg@arm.com 9012037Sandreas.sandberg@arm.com.. _ThinLTO: http://clang.llvm.org/docs/ThinLTO.html 9112037Sandreas.sandberg@arm.com 9212037Sandreas.sandberg@arm.comConfiguration variables 9312037Sandreas.sandberg@arm.com----------------------- 9412037Sandreas.sandberg@arm.com 9512037Sandreas.sandberg@arm.comBy default, pybind11 will compile modules with the latest C++ standard 9612037Sandreas.sandberg@arm.comavailable on the target compiler. To override this, the standard flag can 9712037Sandreas.sandberg@arm.combe given explicitly in ``PYBIND11_CPP_STANDARD``: 9812037Sandreas.sandberg@arm.com 9912037Sandreas.sandberg@arm.com.. code-block:: cmake 10012037Sandreas.sandberg@arm.com 10112037Sandreas.sandberg@arm.com set(PYBIND11_CPP_STANDARD -std=c++11) 10212037Sandreas.sandberg@arm.com add_subdirectory(pybind11) # or find_package(pybind11) 10312037Sandreas.sandberg@arm.com 10412037Sandreas.sandberg@arm.comNote that this and all other configuration variables must be set **before** the 10512037Sandreas.sandberg@arm.comcall to ``add_subdiretory`` or ``find_package``. The variables can also be set 10612037Sandreas.sandberg@arm.comwhen calling CMake from the command line using the ``-D<variable>=<value>`` flag. 10712037Sandreas.sandberg@arm.com 10812037Sandreas.sandberg@arm.comThe target Python version can be selected by setting ``PYBIND11_PYTHON_VERSION`` 10912037Sandreas.sandberg@arm.comor an exact Python installation can be specified with ``PYTHON_EXECUTABLE``. 11012037Sandreas.sandberg@arm.comFor example: 11112037Sandreas.sandberg@arm.com 11212037Sandreas.sandberg@arm.com.. code-block:: bash 11312037Sandreas.sandberg@arm.com 11412037Sandreas.sandberg@arm.com cmake -DPYBIND11_PYTHON_VERSION=3.6 .. 11512037Sandreas.sandberg@arm.com # or 11612037Sandreas.sandberg@arm.com cmake -DPYTHON_EXECUTABLE=path/to/python .. 11712037Sandreas.sandberg@arm.com 11812037Sandreas.sandberg@arm.comfind_package vs. add_subdirectory 11912037Sandreas.sandberg@arm.com--------------------------------- 12012037Sandreas.sandberg@arm.com 12112037Sandreas.sandberg@arm.comFor CMake-based projects that don't include the pybind11 repository internally, 12212037Sandreas.sandberg@arm.coman external installation can be detected through ``find_package(pybind11)``. 12312037Sandreas.sandberg@arm.comSee the `Config file`_ docstring for details of relevant CMake variables. 12411986Sandreas.sandberg@arm.com 12511986Sandreas.sandberg@arm.com.. code-block:: cmake 12611986Sandreas.sandberg@arm.com 12711986Sandreas.sandberg@arm.com cmake_minimum_required(VERSION 2.8.12) 12811986Sandreas.sandberg@arm.com project(example) 12911986Sandreas.sandberg@arm.com 13011986Sandreas.sandberg@arm.com find_package(pybind11 REQUIRED) 13111986Sandreas.sandberg@arm.com pybind11_add_module(example example.cpp) 13211986Sandreas.sandberg@arm.com 13312037Sandreas.sandberg@arm.comOnce detected, the aforementioned ``pybind11_add_module`` can be employed as 13412037Sandreas.sandberg@arm.combefore. The function usage and configuration variables are identical no matter 13512037Sandreas.sandberg@arm.comif pybind11 is added as a subdirectory or found as an installed package. You 13612037Sandreas.sandberg@arm.comcan refer to the same [cmake_example]_ repository for a full sample project 13712037Sandreas.sandberg@arm.com-- just swap out ``add_subdirectory`` for ``find_package``. 13811986Sandreas.sandberg@arm.com 13912037Sandreas.sandberg@arm.com.. _Config file: https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in 14012037Sandreas.sandberg@arm.com 14112037Sandreas.sandberg@arm.comAdvanced: interface library target 14212037Sandreas.sandberg@arm.com---------------------------------- 14312037Sandreas.sandberg@arm.com 14412037Sandreas.sandberg@arm.comWhen using a version of CMake greater than 3.0, pybind11 can additionally 14512037Sandreas.sandberg@arm.combe used as a special *interface library* . The target ``pybind11::module`` 14612037Sandreas.sandberg@arm.comis available with pybind11 headers, Python headers and libraries as needed, 14712037Sandreas.sandberg@arm.comand C++ compile definitions attached. This target is suitable for linking 14812037Sandreas.sandberg@arm.comto an independently constructed (through ``add_library``, not 14912037Sandreas.sandberg@arm.com``pybind11_add_module``) target in the consuming project. 15011986Sandreas.sandberg@arm.com 15111986Sandreas.sandberg@arm.com.. code-block:: cmake 15211986Sandreas.sandberg@arm.com 15311986Sandreas.sandberg@arm.com cmake_minimum_required(VERSION 3.0) 15411986Sandreas.sandberg@arm.com project(example) 15511986Sandreas.sandberg@arm.com 15612037Sandreas.sandberg@arm.com find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11) 15712037Sandreas.sandberg@arm.com 15811986Sandreas.sandberg@arm.com add_library(example MODULE main.cpp) 15912037Sandreas.sandberg@arm.com target_link_libraries(example PRIVATE pybind11::module) 16011986Sandreas.sandberg@arm.com set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}" 16111986Sandreas.sandberg@arm.com SUFFIX "${PYTHON_MODULE_EXTENSION}") 16211986Sandreas.sandberg@arm.com 16311986Sandreas.sandberg@arm.com.. warning:: 16411986Sandreas.sandberg@arm.com 16511986Sandreas.sandberg@arm.com Since pybind11 is a metatemplate library, it is crucial that certain 16611986Sandreas.sandberg@arm.com compiler flags are provided to ensure high quality code generation. In 16711986Sandreas.sandberg@arm.com contrast to the ``pybind11_add_module()`` command, the CMake interface 16811986Sandreas.sandberg@arm.com library only provides the *minimal* set of parameters to ensure that the 16911986Sandreas.sandberg@arm.com code using pybind11 compiles, but it does **not** pass these extra compiler 17011986Sandreas.sandberg@arm.com flags (i.e. this is up to you). 17111986Sandreas.sandberg@arm.com 17211986Sandreas.sandberg@arm.com These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL`` 17311986Sandreas.sandberg@arm.com and ``/LTCG`` on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC 17411986Sandreas.sandberg@arm.com (``-fvisibility=hidden``) and .OBJ files with many sections on Visual Studio 17511986Sandreas.sandberg@arm.com (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an 17611986Sandreas.sandberg@arm.com explanation on why these are needed. 17711986Sandreas.sandberg@arm.com 17812037Sandreas.sandberg@arm.comGenerating binding code automatically 17912037Sandreas.sandberg@arm.com===================================== 18011986Sandreas.sandberg@arm.com 18112037Sandreas.sandberg@arm.comThe ``Binder`` project is a tool for automatic generation of pybind11 binding 18212037Sandreas.sandberg@arm.comcode by introspecting existing C++ codebases using LLVM/Clang. See the 18312037Sandreas.sandberg@arm.com[binder]_ documentation for details. 18412037Sandreas.sandberg@arm.com 18512037Sandreas.sandberg@arm.com.. [binder] http://cppbinder.readthedocs.io/en/latest/about.html 186