summaryrefslogtreecommitdiff
path: root/ext/pybind11/docs/compiling.rst
diff options
context:
space:
mode:
authorJason Lowe-Power <jason@lowepower.com>2017-11-17 17:02:05 -0800
committerJason Lowe-Power <jason@lowepower.com>2017-12-14 00:27:59 +0000
commitf07d5069d86e31ecf195664850f79fb00c445bd3 (patch)
treef54ac06896fa828f873d199a0e9b25bd94911c79 /ext/pybind11/docs/compiling.rst
parent3f64b374c49491f18dc2ca538ed8c8597e4aac83 (diff)
downloadgem5-f07d5069d86e31ecf195664850f79fb00c445bd3.tar.xz
ext: Upgrade PyBind11 to version 2.2.1
This upgrade is necessary for pybind to build with GCC 7.2. We still need to add the patch for stl.h. MSC_FULL_VER change is no longer needed. See https://gem5-review.googlesource.com/c/public/gem5/+/2230 Change-Id: I806729217d022070583994c2dfcaa74476aef30f Signed-off-by: Jason Lowe-Power <jason@lowepower.com> Reviewed-on: https://gem5-review.googlesource.com/5801 Reviewed-by: Andreas Sandberg <andreas.sandberg@arm.com> Maintainer: Andreas Sandberg <andreas.sandberg@arm.com>
Diffstat (limited to 'ext/pybind11/docs/compiling.rst')
-rw-r--r--ext/pybind11/docs/compiling.rst124
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
=====================================