Compiler and linker options¶

The commandbuild_ext builds C/C++ extension modules. It createsa command line for running the compiler and linker by combiningcompiler and linker options from various sources:

• thesysconfig variablesCC,CXX,CCSHARED,LDSHARED, andCFLAGS,

• the environment variablesCC,CPP,CXX,LDSHARED andCFLAGS,CPPFLAGS,LDFLAGS,

• theExtension attributesinclude_dirs,library_dirs,extra_compile_args,extra_link_args,runtime_library_dirs.

Specifically, if the environment variablesCC,CPP,CXX, andLDSHAREDare set, they will be used instead of thesysconfig variables of the same names.

The compiler options appear in the command line in the following order:

• first, the options provided by the environment variablesCFLAGS andCPPFLAGS,

• then, the options provided by thesysconfig variableCCSHARED,

• then, a-I option for each element ofExtension.include_dirs,

• finally, the options provided byExtension.extra_compile_args.

The linker options appear in the command line in the following order:

• first, the options provided by environment variables andsysconfig variables,

• then, a-L option for each element ofExtension.library_dirs,

• then, a linker-specific option like-Wl,-rpath for each element ofExtension.runtime_library_dirs,

• finally, the options provided byExtension.extra_link_args.

The resulting command line is then processed by the compiler and linker.According to the GCC manual sections ondirectory options andenvironment 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 variableCPATH (in left-to-right order),

• then, in directories given by-isystem options (in left-to-right order),

• then, in directories given by the environment variableC_INCLUDE_PATH (for C) andCPLUS_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 variableLIBRARY_PATH (in left-to-right order).

Distributing Extensions compiled with Cython¶

When yourCython extension modulesare declared using thesetuptools.Extensionclass,setuptools will detect at build timewhether Cython is installed or not.

If Cython is present, thensetuptools will use it to build the.pyx files.Otherwise,setuptools will try to find and compile the equivalent.c files(instead of.pyx). These files can be generated using thecython command line tool.

You can ensure that Cython is always automatically installed into the buildenvironment by including it as abuild dependency inyourpyproject.toml:

[build-system]requires=[# ...,"cython",]

Alternatively, you can include the.c code that is pre-compiled by Cythoninto your source distribution, alongside the original.pyx files (thismight save a few seconds when building from ansdist).To improve version compatibility, you probably also want to include current.c files in yourrevision control system, and rebuild them wheneveryou check changes in for the.pyx source files.This will ensure that people tracking your project will be able to build itwithout installing Cython, and that there will be no variation due to smalldifferences in the generate C files.Please checkout our docs onControlling files in the distribution formore information.

Extension API Reference¶

classsetuptools.Extension(name:str,sources:Iterable[str|PathLike[str]],*args,py_limited_api:bool=False,**kw)¶

Describes a single extension module.

This means that all source files will be compiled into a single binary file<modulepath>.<suffix> (with<modulepath> derived fromname and<suffix> defined by one of the values inimportlib.machinery.EXTENSION_SUFFIXES).

In the case.pyx files are passed assourcesandCython isnotinstalled in the build environment,setuptools may also try to look for theequivalent.cpp or.c files.

Parameters:

• name (str) – the full name of the extension, including any packages – ie.not a filename or pathname, but Python dotted name

• sources (Iterable[str |os.PathLike[str]]) – iterable of source filenames, (except strings, which could be misinterpretedas a single filename), relative to the distribution root(where the setup script lives), in Unix form (slash-separated)for portability. Source files may be C, C++, SWIG (.i),platform-specific resource files, or whatever else is recognizedby the “build_ext” command as source for a Python extension.

• include_dirs (list[str]) – list of directories to search for C/C++ header files (in Unixform for portability)

• define_macros (list[tuple[str,str|None]]) – list of macros to define; each macro is defined using a 2-tuple:the first item corresponding to the name of the macro and the seconditem either a string with its value or None todefine it without a particular value (equivalent of “#defineFOO” in source or -DFOO on Unix C compiler command line)

• undef_macros (list[str]) – list of macros to undefine explicitly

• library_dirs (list[str]) – list of directories to search for C/C++ libraries at link time

• libraries (list[str]) – list of library names (not filenames or paths) to link against

• runtime_library_dirs (list[str]) – list of directories to search for C/C++ libraries at run time(for shared extensions, this is when the extension is loaded).Setting this will cause an exception during build on Windowsplatforms.

• extra_objects (list[str]) – list of extra files to link with (eg. object files not impliedby ‘sources’, static library that must be explicitly specified,binary resource files, etc.)

• extra_compile_args (list[str]) – any extra platform- and compiler-specific information to usewhen compiling the source files in ‘sources’. For platforms andcompilers where “command line” makes sense, this is typically alist of command-line arguments, but for other platforms it couldbe anything.

• extra_link_args (list[str]) – any extra platform- and compiler-specific information to usewhen linking object files together to create the extension (orto create a new static Python interpreter). Similarinterpretation as for ‘extra_compile_args’.

• export_symbols (list[str]) – list of symbols to be exported from a shared extension. Notused on all platforms, and not generally necessary for Pythonextensions, which typically export exactly one symbol: “init” +extension_name.

• swig_opts (list[str]) – any extra options to pass to SWIG if a source file has the .iextension.

• depends (list[str]) – list of files that the extension depends on

• language (str) – extension language (i.e. “c”, “c++”, “objc”). Will be detectedfrom the source extensions if not provided.

• optional (bool) – specifies that a build failure in the extension should not abort thebuild process, but simply not install the failing extension.

• py_limited_api (bool) – opt-in flag for the usage ofPython’s limited API.

Raises:

setuptools.errors.PlatformError – ifruntime_library_dirs isspecified on Windows. (since v63)

Notes

Declarative configuration of extension modules viapyproject.toml wasintroduced recently and is still considered experimental.Therefore it might change in future versions ofsetuptools.