compiling.rst revision 11986
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`. 4211986Sandreas.sandberg@arm.comThe CMake command ``add_subdirectory`` will import a function with the signature 4311986Sandreas.sandberg@arm.com``pybind11_add_module(<name> source1 [source2 ...])``. It will take care of all 4411986Sandreas.sandberg@arm.comthe details needed to build a Python extension module on any platform. 4511986Sandreas.sandberg@arm.com 4611986Sandreas.sandberg@arm.comThe target Python version can be selected by setting the ``PYBIND11_PYTHON_VERSION`` 4711986Sandreas.sandberg@arm.comvariable before adding the pybind11 subdirectory. Alternatively, an exact Python 4811986Sandreas.sandberg@arm.cominstallation can be specified by setting ``PYTHON_EXECUTABLE``. 4911986Sandreas.sandberg@arm.com 5011986Sandreas.sandberg@arm.comA working sample project, including a way to invoke CMake from :file:`setup.py` for 5111986Sandreas.sandberg@arm.comPyPI integration, can be found in the [cmake_example]_ repository. 5211986Sandreas.sandberg@arm.com 5311986Sandreas.sandberg@arm.com.. [cmake_example] https://github.com/pybind/cmake_example 5411986Sandreas.sandberg@arm.com 5511986Sandreas.sandberg@arm.comFor CMake-based projects that don't include the pybind11 5611986Sandreas.sandberg@arm.comrepository internally, an external installation can be detected 5711986Sandreas.sandberg@arm.comthrough `find_package(pybind11 ... CONFIG ...)`. See the `Config file 5811986Sandreas.sandberg@arm.com<https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in>`_ 5911986Sandreas.sandberg@arm.comdocstring for details of relevant CMake variables. 6011986Sandreas.sandberg@arm.com 6111986Sandreas.sandberg@arm.comOnce detected, and after setting any variables to guide Python and 6211986Sandreas.sandberg@arm.comC++ standard detection, the aforementioned ``pybind11_add_module`` 6311986Sandreas.sandberg@arm.comwrapper to ``add_library`` can be employed as described above (after 6411986Sandreas.sandberg@arm.com``include(pybind11Tools)``). This procedure is available when using CMake 6511986Sandreas.sandberg@arm.com>= 2.8.12. A working example can be found at [test_installed_module]_ . 6611986Sandreas.sandberg@arm.com 6711986Sandreas.sandberg@arm.com.. code-block:: cmake 6811986Sandreas.sandberg@arm.com 6911986Sandreas.sandberg@arm.com cmake_minimum_required(VERSION 2.8.12) 7011986Sandreas.sandberg@arm.com project(example) 7111986Sandreas.sandberg@arm.com 7211986Sandreas.sandberg@arm.com find_package(pybind11 REQUIRED) 7311986Sandreas.sandberg@arm.com pybind11_add_module(example example.cpp) 7411986Sandreas.sandberg@arm.com 7511986Sandreas.sandberg@arm.com.. [test_installed_module] https://github.com/pybind/pybind11/blob/master/tests/test_installed_module/CMakeLists.txt 7611986Sandreas.sandberg@arm.com 7711986Sandreas.sandberg@arm.comWhen using a version of CMake greater than 3.0, pybind11 can 7811986Sandreas.sandberg@arm.comadditionally be used as a special *interface library* following the 7911986Sandreas.sandberg@arm.comcall to ``find_package``. CMake variables to guide Python and C++ 8011986Sandreas.sandberg@arm.comstandard detection should be set *before* ``find_package``. When 8111986Sandreas.sandberg@arm.com``find_package`` returns, the target ``pybind11::pybind11`` is 8211986Sandreas.sandberg@arm.comavailable with pybind11 headers, Python headers and libraries as 8311986Sandreas.sandberg@arm.comneeded, and C++ compile definitions attached. This target is suitable 8411986Sandreas.sandberg@arm.comfor linking to an independently constructed (through ``add_library``, 8511986Sandreas.sandberg@arm.comnot ``pybind11_add_module``) target in the consuming project. A working 8611986Sandreas.sandberg@arm.comexample can be found at [test_installed_target]_ . 8711986Sandreas.sandberg@arm.com 8811986Sandreas.sandberg@arm.com.. code-block:: cmake 8911986Sandreas.sandberg@arm.com 9011986Sandreas.sandberg@arm.com cmake_minimum_required(VERSION 3.0) 9111986Sandreas.sandberg@arm.com project(example) 9211986Sandreas.sandberg@arm.com 9311986Sandreas.sandberg@arm.com add_library(example MODULE main.cpp) 9411986Sandreas.sandberg@arm.com 9511986Sandreas.sandberg@arm.com find_package(pybind11 REQUIRED) 9611986Sandreas.sandberg@arm.com target_link_libraries(example PRIVATE pybind11::pybind11) 9711986Sandreas.sandberg@arm.com set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}" 9811986Sandreas.sandberg@arm.com SUFFIX "${PYTHON_MODULE_EXTENSION}") 9911986Sandreas.sandberg@arm.com 10011986Sandreas.sandberg@arm.com.. warning:: 10111986Sandreas.sandberg@arm.com 10211986Sandreas.sandberg@arm.com Since pybind11 is a metatemplate library, it is crucial that certain 10311986Sandreas.sandberg@arm.com compiler flags are provided to ensure high quality code generation. In 10411986Sandreas.sandberg@arm.com contrast to the ``pybind11_add_module()`` command, the CMake interface 10511986Sandreas.sandberg@arm.com library only provides the *minimal* set of parameters to ensure that the 10611986Sandreas.sandberg@arm.com code using pybind11 compiles, but it does **not** pass these extra compiler 10711986Sandreas.sandberg@arm.com flags (i.e. this is up to you). 10811986Sandreas.sandberg@arm.com 10911986Sandreas.sandberg@arm.com These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL`` 11011986Sandreas.sandberg@arm.com and ``/LTCG`` on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC 11111986Sandreas.sandberg@arm.com (``-fvisibility=hidden``) and .OBJ files with many sections on Visual Studio 11211986Sandreas.sandberg@arm.com (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an 11311986Sandreas.sandberg@arm.com explanation on why these are needed. 11411986Sandreas.sandberg@arm.com 11511986Sandreas.sandberg@arm.com.. [test_installed_target] https://github.com/pybind/pybind11/blob/master/tests/test_installed_target/CMakeLists.txt 11611986Sandreas.sandberg@arm.com 117