Skip to content

Latest commit

 

History

History
115 lines (82 loc) · 4.27 KB

ext_modules.rst

File metadata and controls

115 lines (82 loc) · 4.27 KB
Raw

Building Extension Modules

Setuptools can build C/C++ extension modules. The keyword argument ext_modules of setup() should be a list of instances of the setuptools.Extension class.

For example, let's consider a simple project with only one extension module:

<project_folder>
├── pyproject.toml
└── foo.c

and all project metadata configuration in the pyproject.toml file:

# pyproject.toml
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "mylib-foo"  # as it would appear on PyPI
version = "0.42"

To instruct setuptools to compile the foo.c file into the extension module mylib.foo, we need to add a setup.py file similar to the following:

from setuptools import Extension, setup

setup(
    ext_modules=[
        Extension(
            name="mylib.foo",  # as it would be imported
                               # may include packages/namespaces separated by `.`

            sources=["foo.c"], # all sources are compiled into a single binary file
        ),
    ]
)

You can find more information on the Python docs about C/C++ extensions. Alternatively, you might also be interested in learn about Cython.

If you plan to distribute a package that uses extensions across multiple platforms, cibuildwheel can also be helpful.

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:

  • 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.

The resulting command line is then processed by the compiler and linker. 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 LIBRARY_PATH (in left-to-right order).

Important

All files used to compile your extension need to be available on the system in the moment setuptools builds your project, so please make sure to include some documentation on how users can obtain operating system level dependencies (e.g. compilers and external binary libraries/artifacts).

You will also need to make sure that all auxiliary files that are contained inside your project (e.g. C headers authored by you or your team) are configured to be included in your sdist <Source Distribution (or "sdist")>. Please have a look on our section on Controlling files in the distribution.

API Reference

setuptools.Extension