Skip to content

Commit 6f66e76

Browse files
authored
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
1 parent 635e3fc commit 6f66e76

File tree

3 files changed

+13
-4
lines changed

3 files changed

+13
-4
lines changed

docs/basics.rst

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,14 @@ On Linux, the above example can be compiled using the following command:
136136

137137
.. code-block:: bash
138138
139-
$ c++ -O3 -Wall -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix`
139+
$ c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix)
140+
141+
.. note::
142+
143+
If you used :ref:`include_as_a_submodule` to get the pybind11 source, then
144+
use ``$(python3-config --includes) -Iextern/pybind11/include`` instead of
145+
``$(python3 -m pybind11 --includes)`` in the above compilation, as
146+
explained in :ref:`building_manually`.
140147

141148
For more details on the required compiler flags on Linux and macOS, see
142149
:ref:`building_manually`. For complete cross-platform compilation instructions,

docs/compiling.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -565,7 +565,7 @@ On Linux, you can compile an example such as the one given in
565565

566566
.. code-block:: bash
567567
568-
$ c++ -O3 -Wall -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix`
568+
$ c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix)
569569
570570
The flags given here assume that you're using Python 3. For Python 2, just
571571
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
577577
``python3-config --includes``.
578578

579579
Note that Python 2.7 modules don't use a special suffix, so you should simply
580-
use ``example.so`` instead of ``example`python3-config --extension-suffix```.
580+
use ``example.so`` instead of ``example$(python3-config --extension-suffix)``.
581581
Besides, the ``--extension-suffix`` option may or may not be available, depending
582582
on the distribution; in the latter case, the module extension can be manually
583583
set to ``.so``.
@@ -588,7 +588,7 @@ building the module:
588588

589589
.. code-block:: bash
590590
591-
$ c++ -O3 -Wall -shared -std=c++11 -undefined dynamic_lookup `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix`
591+
$ c++ -O3 -Wall -shared -std=c++11 -undefined dynamic_lookup $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix)
592592
593593
In general, it is advisable to include several additional build parameters
594594
that can considerably reduce the size of the created binary. Refer to section

docs/installing.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ There are several ways to get the pybind11 source, which lives at
88
developers recommend one of the first three ways listed here, submodule, PyPI,
99
or conda-forge, for obtaining pybind11.
1010

11+
.. _include_as_a_submodule:
12+
1113
Include as a submodule
1214
======================
1315

0 commit comments

Comments
 (0)