docs/userguide/ext_modules.rst: New

1 files changed, 40 insertions, 0 deletions

diff --git a/docs/userguide/ext_modules.rst b/docs/userguide/ext_modules.rst
new file mode 100644
index 00000000..7819ed4b
--- /dev/null
+++ b/docs/userguide/ext_modules.rst
@@ -0,0 +1,40 @@
+==========================
+Building Extension Modules
+==========================
+
+Compiler and linker options
+===========================
+
+The command ``build_ext`` builds C/C++ extension modules.  It creates
+a command line for running the compiler and linker by combining
+compiler and linker options from various sources, as specified by
+`test_customize_compiler
+<https://github.com/pypa/setuptools/blob/main/setuptools/_distutils/tests/test_sysconfig.py>`_:
+
+ * the ``sysconfig`` variables ``CFLAGS`` and ``LDFLAGS``,
+ * the environment variables :envvar:`CC`, :envvar:`CPP`,
+   :envvar:`CXX`, :envvar:`LDSHARED` and :envvar:`LDFLAGS`,
+   :envvar:`CFLAGS`, :envvar:`CPPFLAGS`, :envvar:`LDFLAGS`,
+ * the :class:`Extension` options.
+
+.. Ignoring AR, ARFLAGS, RANLIB here because they are used by the (obsolete?) build_clib, not build_ext.
+
+The resulting command line is then processed by the compiler and linker.
+According to the GCC manual sections on `directory options
+<https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html>`_ and
+`environment variables
+<https://gcc.gnu.org/onlinedocs/gcc/Environment-Variables.html`_, the
+C/C++ compiler searches for files named in ``#include <file>``
+directives in the following order:
+
+ * first, in directories given by ``-I`` options (in left-to-right order),
+ * then, in directories given by the environment variable :envvar:`CPATH` (in left-to-right order),
+ * then, in directories given by ``-isystem`` options (in left-to-right order),
+ * then, in directories given by the environment variable :envvar:`C_INCLUDE_PATH` (for C) and :envvar:`CPLUS_INCLUDE_PATH` (for C++),
+ * then, in standard system directories,
+ * finally, in directories given by ``-idirafter`` options (in left-to-right order).
+
+The linker searches for libraries in the following order:
+
+ * first, in directories given by ``-L`` options (in left-to-right order),
+ * then, in directories given by the environment variable :envvar:`LIBRARY_PATH` (in left-to-right order).