Probing Toolchain

Replacing buildsystems like autoconf or cmake may require compile time inspection of the toolchain to determine sizes of types, the availability of header files, or similar. The ProbeToolchain class exists to allow these questions to be answered.

from setuptools_dso import DSO, ProbeToolchain

def define_DSOS(cmd):
    mymacros = []
    probe = ProbeToolchain()

    if probe.check_include('linux/sonet.h'):
        mymacros += [('ENABLE_OBSCURE_FEATURE', None)]

    return [DSO('dsodemo.lib.demo',
        ['src/foo.c', 'src/bar.cpp'],
        define_macros = mymacros,
        ...)]

setup(
    ...
    x_dsos = define_DSOS, # lazy DSOs list to avoid redundant probing
    zip_safe = False,
)

Toolchain Classification

ProbeToolchain.info is a probe.ToolchainInfo object based on compiler specific predefined preprocessor macros.

from setuptools_dso import ProbeToolchain

probe = ProbeToolchain()
if probe.info.compiler=='gcc' and probe.info.compiler_version<(4,9,4):
    print("GCC version is too old")
class setuptools_dso.ProbeToolchain(verbose=False, compiler=None, headers=None, define_macros=None)

Inspection of compiler

Parameters:

  • verbose (bool) – If True, enable additional prints

  • compiler (str) – If not None, select non-default compiler toolchain

  • headers (list) – List of headers to include during all test compilations

  • define_macros (list) – List of (macro, value) tuples to define during all test compilations

check_include(header, **kws)

Return true if the header may be included

Parameters:

  • header (str) – Header file name

  • language (str) – Source code language: ‘c’ or ‘c++’

  • define_macros (list) – Extra macro definitions.

  • include_dirs (list) – Extra directories to search for headers

  • extra_preargs (list) – Extra arguments to pass to the compiler

  • extra_postargs (list) – Extra arguments to pass to the compiler

check_includes(headers, **kws)

Return true if all of the headers may be included (in order)

Parameters:

  • headers (list) – List of header file names

  • language (str) – Source code language: ‘c’ or ‘c++’

  • define_macros (list) – Extra macro definitions.

  • include_dirs (list) – Extra directories to search for headers

  • extra_preargs (list) – Extra arguments to pass to the compiler

  • extra_postargs (list) – Extra arguments to pass to the compiler

check_member(struct, member, headers=None, **kws)

Return True if the given structure has the named member

Parameters:

  • struct (str) – Structure name

  • member (str) – Member name

  • headers (list) – List of headers to include during all test compilations

  • language (str) – Source code language: ‘c’ or ‘c++’

  • define_macros (list) – Extra macro definitions.

  • include_dirs (list) – Extra directories to search for headers

  • extra_preargs (list) – Extra arguments to pass to the compiler

  • extra_postargs (list) – Extra arguments to pass to the compiler

check_symbol(symname, headers=None, **kws)

Return True if symbol name (macro, variable, or function) is defined/delcared

Parameters:

  • symname (str) – Symbol name

  • headers (list) – List of headers to include during all test compilations

  • language (str) – Source code language: ‘c’ or ‘c++’

  • define_macros (list) – Extra macro definitions.

  • include_dirs (list) – Extra directories to search for headers

  • extra_preargs (list) – Extra arguments to pass to the compiler

  • extra_postargs (list) – Extra arguments to pass to the compiler

compile(src, language='c', define_macros=None, **kws)

Compile provided source code and return path to resulting object file

Returns:

Path string to object file in temporary location.

Parameters:

  • src (str) – Source code string

  • language (str) – Source code language: ‘c’ or ‘c++’

  • define_macros (list) – Extra macro definitions.

  • include_dirs (list) – Extra directories to search for headers

  • extra_preargs (list) – Extra arguments to pass to the compiler

  • extra_postargs (list) – Extra arguments to pass to the compiler

eval_macros(macros, headers=None, define_macros=None, language='c', **kws)

Expand C/C++ preprocessor macros.

For undefined macros, None is returned. For defined macros a string is returned. When evaluating multiple macros, the order of the macros argument is preserved in the OrderedDict which is returned.

Returns:

An OrderedDict mapping to string (if defined) or None (if not defined)

Parameters:

  • macros (str|list) – A macro name string, or a list of such strings

  • headers (list) – List of headers to include during all test compilations

  • define_macros (list) – Extra macro definitions.

  • language (str) – Source code language: ‘c’ or ‘c++’ (Added in 2.9)

  • include_dirs (list) – Extra directories to search for headers

  • extra_preargs (list) – Extra arguments to pass to the compiler

  • extra_postargs (list) – Extra arguments to pass to the compiler

property info

Inspect toolchain

Returns:

A probe.ToolchainInfo

sizeof(typename, headers=None, **kws)

Return size in bytes of provided typename

Parameters:

  • typename (str) – Header file name

  • headers (list) – List of headers to include during all test compilations

  • language (str) – Source code language: ‘c’ or ‘c++’

  • define_macros (list) – Extra macro definitions.

  • include_dirs (list) – Extra directories to search for headers

  • extra_preargs (list) – Extra arguments to pass to the compiler

  • extra_postargs (list) – Extra arguments to pass to the compiler

try_compile(src, **kws)

Return True if provided source code compiles

Parameters:

  • src (str) – Source code string

  • language (str) – Source code language: ‘c’ or ‘c++’

  • define_macros (list) – Extra macro definitions.

  • include_dirs (list) – Extra directories to search for headers

  • extra_preargs (list) – Extra arguments to pass to the compiler

  • extra_postargs (list) – Extra arguments to pass to the compiler

class setuptools_dso.probe.ToolchainInfo(TC)

Information about a compiler toolchain

address_width = 0

Width in bits of a virtual address. aka. 8*sizeof(void*)

Known values: 32, 64

compiler = None

Compiler implementation name

Possible values; ‘clang’, ‘gcc’, ‘msvc’

compiler_type = None

Directly copied from distutils.ccompiler.CCompiler.compiler_type

Known values include: ‘bcpp’, ‘cygwin’, ‘mingw’, ‘msvc’, ‘unix’

compiler_version = None

Compiler release version as a tuple of integers suitible for comparison

eg. for GCC: (4,9,2), clang: (11,0,1), msvc: (19,0,24245)

endian = None

Target byte order for multi-byte values

Known values: “little”, “big”

gnuish = False

True when compiler is clang or gcc

target_arch = None

Target CPU architecture

Known values: “aarch64”, “arm32”, “amd64”, “i386”

target_os = None

Target OS runtime environment

Known values: “cygwin”, “linux”, “osx”, “windows”