From c79706ff4ce591df2151db5504d3c224f3c9965f Mon Sep 17 00:00:00 2001 From: Andreas Sandberg Date: Mon, 27 Feb 2017 13:17:51 +0000 Subject: ext: Add pybind rev f4b81b3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: I52e4fc9ebf2f59da57d8cf8f3e37cc79598c2f5f Signed-off-by: Andreas Sandberg Reviewed-by: Andreas Hansson Reviewed-by: Curtis Dunham Reviewed-on: https://gem5-review.googlesource.com/2229 Reviewed-by: Tony Gutierrez Reviewed-by: Jason Lowe-Power Reviewed-by: Pierre-Yves Péneau --- ext/pybind11/docs/compiling.rst | 116 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 ext/pybind11/docs/compiling.rst (limited to 'ext/pybind11/docs/compiling.rst') diff --git a/ext/pybind11/docs/compiling.rst b/ext/pybind11/docs/compiling.rst new file mode 100644 index 000000000..35768fe45 --- /dev/null +++ b/ext/pybind11/docs/compiling.rst @@ -0,0 +1,116 @@ +Build systems +############# + +Building with setuptools +======================== + +For projects on PyPI, building with setuptools is the way to go. Sylvain Corlay +has kindly provided an example project which shows how to set up everything, +including automatic generation of documentation using Sphinx. Please refer to +the [python_example]_ repository. + +.. [python_example] https://github.com/pybind/python_example + +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] https://github.com/tbenthompson/cppimport + +.. _cmake: + +Building with CMake +=================== + +For C++ codebases that have an existing CMake-based build system, a Python +extension module can be created with just a few lines of code: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 2.8.12) + project(example) + + add_subdirectory(pybind11) + pybind11_add_module(example example.cpp) + +This assumes that the pybind11 repository is located in a subdirectory named +:file:`pybind11` and that the code is located in a file named :file:`example.cpp`. +The CMake command ``add_subdirectory`` will import a function with the signature +``pybind11_add_module( source1 [source2 ...])``. It will take care of all +the details needed to build a Python extension module on any platform. + +The target Python version can be selected by setting the ``PYBIND11_PYTHON_VERSION`` +variable before adding the pybind11 subdirectory. Alternatively, an exact Python +installation can be specified by setting ``PYTHON_EXECUTABLE``. + +A working sample project, including a way to invoke CMake from :file:`setup.py` for +PyPI integration, can be found in the [cmake_example]_ repository. + +.. [cmake_example] https://github.com/pybind/cmake_example + +For CMake-based projects that don't include the pybind11 +repository internally, an external installation can be detected +through `find_package(pybind11 ... CONFIG ...)`. See the `Config file +`_ +docstring for details of relevant CMake variables. + +Once detected, and after setting any variables to guide Python and +C++ standard detection, the aforementioned ``pybind11_add_module`` +wrapper to ``add_library`` can be employed as described above (after +``include(pybind11Tools)``). This procedure is available when using CMake +>= 2.8.12. A working example can be found at [test_installed_module]_ . + +.. code-block:: cmake + + cmake_minimum_required(VERSION 2.8.12) + project(example) + + find_package(pybind11 REQUIRED) + pybind11_add_module(example example.cpp) + +.. [test_installed_module] https://github.com/pybind/pybind11/blob/master/tests/test_installed_module/CMakeLists.txt + +When using a version of CMake greater than 3.0, pybind11 can +additionally be used as a special *interface library* following the +call to ``find_package``. CMake variables to guide Python and C++ +standard detection should be set *before* ``find_package``. When +``find_package`` returns, the target ``pybind11::pybind11`` is +available with pybind11 headers, Python headers and libraries as +needed, and C++ compile definitions attached. This target is suitable +for linking to an independently constructed (through ``add_library``, +not ``pybind11_add_module``) target in the consuming project. A working +example can be found at [test_installed_target]_ . + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(example) + + add_library(example MODULE main.cpp) + + find_package(pybind11 REQUIRED) + target_link_libraries(example PRIVATE pybind11::pybind11) + set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}" + SUFFIX "${PYTHON_MODULE_EXTENSION}") + +.. warning:: + + Since pybind11 is a metatemplate library, it is crucial that certain + compiler flags are provided to ensure high quality code generation. In + contrast to the ``pybind11_add_module()`` command, the CMake interface + library only provides the *minimal* set of parameters to ensure that the + code using pybind11 compiles, but it does **not** pass these extra compiler + 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 ` contains an + explanation on why these are needed. + +.. [test_installed_target] https://github.com/pybind/pybind11/blob/master/tests/test_installed_target/CMakeLists.txt + -- cgit v1.2.3