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
diff --git a/docs/basics.rst b/docs/basics.rst
index b9d386c..0b1d85c 100644
--- a/docs/basics.rst
+++ b/docs/basics.rst
@@ -136,7 +136,14 @@
.. 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 1b9de43..b16fb9c 100644
--- a/docs/compiling.rst
+++ b/docs/compiling.rst
@@ -565,7 +565,7 @@
.. 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 @@
``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 @@
.. 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 9ef231e..30b9f18 100644
--- a/docs/installing.rst
+++ b/docs/installing.rst
@@ -8,6 +8,8 @@
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
======================