diff options
| -rw-r--r-- | docs/userguide/ext_modules.rst | 70 |
1 files changed, 40 insertions, 30 deletions
diff --git a/docs/userguide/ext_modules.rst b/docs/userguide/ext_modules.rst index 129307f8..a63ada82 100644 --- a/docs/userguide/ext_modules.rst +++ b/docs/userguide/ext_modules.rst @@ -3,9 +3,8 @@ Building Extension Modules ========================== Setuptools can build C/C++ extension modules. The keyword argument -``ext_modules`` of :func:`setup` should be a list of instances of the -`Extension class -<https://github.com/pypa/setuptools/blob/main/setuptools/_distutils/extension.py>`_. +``ext_modules`` of ``setup`` should be a list of instances of the +:class:`setuptools.Extension` class. Compiler and linker options @@ -13,37 +12,48 @@ 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 ``CC``, ``CXX``, ``CCSHARED``, - ``LDSHARED``, and ``CFLAGS``, - * the environment variables :envvar:`CC`, :envvar:`CPP`, - :envvar:`CXX`, :envvar:`LDSHARED` and :envvar:`LDFLAGS`, - :envvar:`CFLAGS`, :envvar:`CPPFLAGS`, :envvar:`LDFLAGS`, - * the :class:`Extension` attributes ``include_dirs``, - ``library_dirs``, ``extra_compile_args``, ``extra_link_args``, - ``runtime_library_dirs``. +compiler and linker options from various sources: + +.. Reference: `test_customize_compiler` in distutils/tests/test_sysconfig.py + +* the ``sysconfig`` variables ``CC``, ``CXX``, ``CCSHARED``, + ``LDSHARED``, and ``CFLAGS``, +* the environment variables ``CC``, ``CPP``, + ``CXX``, ``LDSHARED`` and ``LDFLAGS``, + ``CFLAGS``, ``CPPFLAGS``, ``LDFLAGS``, +* the ``Extension`` attributes ``include_dirs``, + ``library_dirs``, ``extra_compile_args``, ``extra_link_args``, + ``runtime_library_dirs``. .. 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). +According to the GCC manual sections on `directory options`_ and +`environment variables`_, 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 ``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 ``C_INCLUDE_PATH`` (for C) and ``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). +* first, in directories given by ``-L`` options (in left-to-right order), +* then, in directories given by the environment variable ``LIBRARY_PATH`` (in left-to-right order). + + +---- + +API Reference +------------- + +.. autoclass:: setuptools.Extension + + +.. _Python docs about C/C++ extensions: https://docs.python.org/3/extending/extending.html +.. _Cython: https://cython.readthedocs.io/en/stable/index.html +.. _directory options: https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html +.. _environment variables: https://gcc.gnu.org/onlinedocs/gcc/Environment-Variables.html> |