From 6f66e7603c9c75f1ab2872457e465bb00b56d596 Mon Sep 17 00:00:00 2001 From: Steve Siano Date: Thu, 24 Dec 2020 06:51:36 -0800 Subject: [PATCH] docs: add a note about compiling the example (#2737) * docs: mention PYTHONPATH in installing.rst When pybind11 is included as a submodule, the user needs to update their Python module search path. Otherwise, the first c++ compilation command in docs/basics.rst will fail. * docs: add a note about compiling the example This note shows how to modify the compilation command for the example when the pybind11 source has been included as a Git submodule. * docs: add a note about compiling the example Added an internal link to the docs * docs: updated a note about compiling the example Also updated the command substitution syntax for consistency --- docs/basics.rst | 9 ++++++++- docs/compiling.rst | 6 +++--- docs/installing.rst | 2 ++ 3 files changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/basics.rst b/docs/basics.rst index b9d386c3f..0b1d85cfd 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -136,7 +136,14 @@ On Linux, the above example can be compiled 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` + $ c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix) + +.. note:: + + If you used :ref:`include_as_a_submodule` to get the pybind11 source, then + use ``$(python3-config --includes) -Iextern/pybind11/include`` instead of + ``$(python3 -m pybind11 --includes)`` in the above compilation, as + explained in :ref:`building_manually`. For more details on the required compiler flags on Linux and macOS, see :ref:`building_manually`. For complete cross-platform compilation instructions, diff --git a/docs/compiling.rst b/docs/compiling.rst index 1b9de43ce..b16fb9c46 100644 --- a/docs/compiling.rst +++ b/docs/compiling.rst @@ -565,7 +565,7 @@ On Linux, you can compile an example such as the one given in .. code-block:: bash - $ c++ -O3 -Wall -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix` + $ 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``). @@ -577,7 +577,7 @@ using ``pip`` or ``conda``. If it hasn't, you can also manually specify ``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```. +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``. @@ -588,7 +588,7 @@ 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` + $ 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 diff --git a/docs/installing.rst b/docs/installing.rst index 9ef231e40..30b9f1853 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -8,6 +8,8 @@ There are several ways to get the pybind11 source, which lives at developers recommend one of the first three ways listed here, submodule, PyPI, or conda-forge, for obtaining pybind11. +.. _include_as_a_submodule: + Include as a submodule ======================