diff options
Diffstat (limited to 'ext/pybind11/docs/compiling.rst')
| -rw-r--r-- | ext/pybind11/docs/compiling.rst | 124 |
1 files changed, 106 insertions, 18 deletions
diff --git a/ext/pybind11/docs/compiling.rst b/ext/pybind11/docs/compiling.rst index c7053dbf9..b5d6ce948 100644 --- a/ext/pybind11/docs/compiling.rst +++ b/ext/pybind11/docs/compiling.rst @@ -1,3 +1,5 @@ +.. _compiling: + Build systems ############# @@ -14,10 +16,10 @@ the [python_example]_ repository. 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]_ 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 @@ -74,13 +76,15 @@ removes this target from the default build (see CMake docs for details). Since pybind11 is a template library, ``pybind11_add_module`` adds compiler flags to ensure high quality code generation without bloat arising from long -symbol names and duplication of code in different translation units. The -additional flags enable LTO (Link Time Optimization), set default visibility -to *hidden* and strip unneeded symbols. See the :ref:`FAQ entry <faq:symhidden>` -for a more detailed explanation. These optimizations are never applied in -``Debug`` mode. If ``NO_EXTRAS`` is given, they will always be disabled, even -in ``Release`` mode. However, this will result in code bloat and is generally -not recommended. +symbol names and duplication of code in different translation units. It +sets default visibility to *hidden*, which is required for some pybind11 +features and functionality when attempting to load multiple pybind11 modules +compiled under different pybind11 versions. It also adds additional flags +enabling LTO (Link Time Optimization) and strip unneeded symbols. See the +:ref:`FAQ entry <faq:symhidden>` for a more detailed explanation. These +latter optimizations are never applied in ``Debug`` mode. If ``NO_EXTRAS`` is +given, they will always be disabled, even in ``Release`` mode. However, this +will result in code bloat and is generally not recommended. As stated above, LTO is enabled by default. Some newer compilers also support different flavors of LTO such as `ThinLTO`_. Setting ``THIN_LTO`` will cause @@ -92,17 +96,28 @@ regular LTO if ``-flto=thin`` is not available. Configuration variables ----------------------- -By default, pybind11 will compile modules with the latest C++ standard -available on the target compiler. To override this, the standard flag can -be given explicitly in ``PYBIND11_CPP_STANDARD``: +By default, pybind11 will compile modules with the C++14 standard, if available +on the target compiler, falling back to C++11 if C++14 support is not +available. Note, however, that this default is subject to change: future +pybind11 releases are expected to migrate to newer C++ standards as they become +available. To override this, the standard flag can be given explicitly in +``PYBIND11_CPP_STANDARD``: .. code-block:: cmake + # Use just one of these: + # GCC/clang: set(PYBIND11_CPP_STANDARD -std=c++11) + set(PYBIND11_CPP_STANDARD -std=c++14) + set(PYBIND11_CPP_STANDARD -std=c++1z) # Experimental C++17 support + # MSVC: + set(PYBIND11_CPP_STANDARD /std:c++14) + set(PYBIND11_CPP_STANDARD /std:c++latest) # Enables some MSVC C++17 features + add_subdirectory(pybind11) # or find_package(pybind11) Note that this and all other configuration variables must be set **before** the -call to ``add_subdiretory`` or ``find_package``. The variables can also be set +call to ``add_subdirectory`` or ``find_package``. The variables can also be set when calling CMake from the command line using the ``-D<variable>=<value>`` flag. The target Python version can be selected by setting ``PYBIND11_PYTHON_VERSION`` @@ -170,11 +185,84 @@ to an independently constructed (through ``add_library``, not flags (i.e. this is up to you). These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL`` - and ``/LTCG`` on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC - (``-fvisibility=hidden``) and .OBJ files with many sections on Visual Studio - (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an + and ``/LTCG`` on Visual Studio) and .OBJ files with many sections on Visual + Studio (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an explanation on why these are needed. +Embedding the Python interpreter +-------------------------------- + +In addition to extension modules, pybind11 also supports embedding Python into +a C++ executable or library. In CMake, simply link with the ``pybind11::embed`` +target. It provides everything needed to get the interpreter running. The Python +headers and libraries are attached to the target. Unlike ``pybind11::module``, +there is no need to manually set any additional properties here. For more +information about usage in C++, see :doc:`/advanced/embedding`. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(example) + + find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11) + + add_executable(example main.cpp) + target_link_libraries(example PRIVATE pybind11::embed) + +.. _building_manually: + +Building manually +================= + +pybind11 is a header-only library, hence it is not necessary to link against +any special libraries and there are no intermediate (magic) translation steps. + +On Linux, you can compile an example such as the one given in +:ref:`simple_example` using the following command: + +.. code-block:: bash + + $ c++ -O3 -Wall -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix` + +The flags given here assume that you're using Python 3. For Python 2, just +change the executable appropriately (to ``python`` or ``python2``). + +The ``python3 -m pybind11 --includes`` command fetches the include paths for +both pybind11 and Python headers. This assumes that pybind11 has been installed +using ``pip`` or ``conda``. If it hasn't, you can also manually specify +``-I <path-to-pybind11>/include`` together with the Python includes path +``python3-config --includes``. + +Note that Python 2.7 modules don't use a special suffix, so you should simply +use ``example.so`` instead of ``example`python3-config --extension-suffix```. +Besides, the ``--extension-suffix`` option may or may not be available, depending +on the distribution; in the latter case, the module extension can be manually +set to ``.so``. + +On Mac OS: the build command is almost the same but it also requires passing +the ``-undefined dynamic_lookup`` flag so as to ignore missing symbols when +building the module: + +.. code-block:: bash + + $ c++ -O3 -Wall -shared -std=c++11 -undefined dynamic_lookup `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix` + +In general, it is advisable to include several additional build parameters +that can considerably reduce the size of the created binary. Refer to section +:ref:`cmake` for a detailed example of a suitable cross-platform CMake-based +build system that works on all platforms including Windows. + +.. note:: + + On Linux and macOS, it's better to (intentionally) not link against + ``libpython``. The symbols will be resolved when the extension library + is loaded into a Python binary. This is preferable because you might + have several different installations of a given Python version (e.g. the + system-provided Python, and one that ships with a piece of commercial + software). In this way, the plugin will work with both versions, instead + of possibly importing a second Python library into a process that already + contains one (which will lead to a segfault). + Generating binding code automatically ===================================== |