Python API to bob.extension¶

This section includes information for using the Python API of bob.extension.

Functions¶

A custom build class for Pkg-config based extensions

bob.extension.check_packages(packages)[source]¶

Checks if the requirements for the given packages are satisfied.

:param list of str: Each representing a requirement that

must be statistfied. Package requirements can be set like this:

"pkg > VERSION"

In this case, the package version should be greater than the given version number. Comparisons are done using distutils.version.LooseVersion. You can use other comparators such as <, <=, >= or ==. If no version number is given, then we only require that the package is installed.

Raises:	`RuntimeError` – in case requirements are not satisfied. This means either not finding a package if no version number is specified or verifying that the package version does not match the required version by the builder.

bob.extension.generate_self_macros(extname, version)[source]¶: Generates standard macros with library, module names and prefix

bob.extension.reorganize_isystem(args)[source]¶: Re-organizes the -isystem includes so that more specific paths come first

bob.extension.normalize_requirements(requirements)[source]¶: Normalizes the requirements keeping only the most tight

bob.extension.get_bob_libraries(bob_packages)[source]¶: Returns a list of include directories, libraries and library directories for the given bob libraries.

bob.extension.get_full_libname(name, path=None, version=None)[source]¶: Generates the name of the library from the given name, path and version.

bob.extension.load_bob_library(name, _file_)[source]¶

Loads the bob Library for the given package name in the given version (if given). The _file_ parameter is expected to be the __file__ member of the main __init__.py of the package. It is used to determine the directory, where the library should be loaded from.

Keyword parameters

name: The name of the bob package to load the library from, e.g. bob.core
_file_: The __file__ member of the __init__.py file in which the library is loaded.

class bob.extension.Extension(name, sources, **kwargs)[source]¶

Bases: setuptools.extension.Extension

Extension building with pkg-config packages.

See the documentation for distutils.extension.Extension for more details on input parameters.

class bob.extension.Library(name, sources, version, bob_packages=[], packages=[], boost_modules=[], include_dirs=[], system_include_dirs=[], libraries=[], library_dirs=[], define_macros=[])[source]¶

Bases: bob.extension.Extension

A class to compile a pure C++ code library used within and outside an extension using CMake.

compile(build_directory, compiler=None, stdout=None)[source]¶: This function will automatically create a CMakeLists.txt file in the package_directory including the required information. Afterwards, the library is built using CMake in the given build_directory. The build type is automatically taken from the debug option in the buildout.cfg. To change the compiler, use the compiler parameter.

class bob.extension.CMakeListsGenerator(name, sources, target_directory, version='1.0.0', include_directories=[], system_include_directories=[], libraries=[], library_directories=[], macros=[])[source]¶

Generates a CMakeLists.txt file for the given sources, include directories and libraries.

generate(source_directory, build_directory)[source]¶: Generates the CMakeLists.txt file in the given directory.

bob.extension.DistutilsExtension¶: alias of Extension

class bob.extension.boost(requirement='')[source]¶

A class for capturing configuration information from boost

Example usage:

>>> from bob.extension import boost
>>> pkg = boost('>= 1.35')
>>> pkg.include_directory
'...'
>>> pkg.version
'...'

You can also use this class to retrieve information about installed Boost libraries and link information:

>>> from bob.extension import boost
>>> pkg = boost('>= 1.35')
>>> pkg.libconfig(['python', 'system'])
(...)

libconfig(modules, only_static=False, templates=['boost_%(name)s-mt-%(py)s', 'boost_%(name)s-%(py)s', 'boost_%(name)s-mt', 'boost_%(name)s'])[source]¶

Returns a tuple containing the library configuration for requested modules.

This function respects the path location where the include files for Boost are installed.

Parameters:

modules (list of strings)

A list of string specifying the requested libraries to search for. For example, to search for libboost_mpi.so, pass only mpi.

static (bool)

A boolean, indicating if we should try only to search for static versions of the libraries. If not set, any would do.

templates (list of template strings)

A list that defines in which order to search for libraries on the default search path, defined by self.include_directory. Tune this list if you have compiled specific versions of Boost with support to multi-threading (-mt), debug (-g), STLPORT (-p) or required to insert compiler, the underlying thread API used or your own namespace.

Here are the keywords you can use:

%(name)s: resolves to the module name you are searching for
%(ver)s: resolves to the current boost version string (e.g. '1.50.0')
%(py)s: resolves to the string 'pyXY' where XY represent the major and minor versions of the current python interpreter.

Example templates:

'boost_%(name)s-mt'
'boost_%(name)s'
'boost_%(name)s-gcc43-%(ver)s'

Returns:

directories (list of strings): A list of directories indicating where the libraries are installed
libs (list of strings): A list of strings indicating the names of the libraries you can use

macros()[source]¶

Returns package availability and version number macros

This method returns a python list with 2 macros indicating package availability and a version number, using standard GNU compatible names. Example:

>>> from bob.extension import boost
>>> pkg = boost('>= 1.34')
>>> pkg.macros()
[('HAVE_BOOST', '1'), ('BOOST_VERSION', '"..."')]

bob.extension.find_executable(name, subpaths=None, prefixes=None)[source]¶

Finds an executable on the file system. Returns all candidates.

This method will find all occurrences of a given name on the file system and will return them to the user.

If the environment variable BOB_PREFIX_PATH is set, then it is considered a unix path list that is prepended to the list of prefixes to search for. The environment variable has the highest priority on the search order. The order on the variable for each path is respected.

Parameters:

name, str: The name of the executable to be found.
subpaths, str list: A list of subpaths to be appended to each prefix for the search. For example, if you specificy ['foo', 'bar'] for this parameter, then search on os.path.join(prefixes[0], 'foo'), os.path.join(prefixes[0], 'bar'), and so on.
prefixes, str list: A list of prefixes that will be searched prioritarily to the DEFAULT_PREFIXES defined in this module.

Returns a list of filenames that exist on the filesystem, matching your description.

bob.extension.find_library(name, version=None, subpaths=None, prefixes=None, only_static=False)[source]¶

Finds a library file on the file system. Returns all candidates.

This method will find all occurrences of a given name on the file system and will return them to the user.

If the environment variable BOB_PREFIX_PATH is set, then it is considered a unix path list that is prepended to the list of prefixes to search for. The environment variable has the highest priority on the search order. The order on the variable for each path is respected.

Parameters:

name, str: The name of the module to be found. If you’d like to find libz.so, for example, specify "z". For libmath.so, specify "math".
version, str: The version of the library we are searching for. If not specified, then look only for the default names, such as libz.so and the such.
subpaths, str list: A list of subpaths to be appended to each prefix for the search. For example, if you specificy ['foo', 'bar'] for this parameter, then search on os.path.join(prefixes[0], 'foo'), os.path.join(prefixes[0], 'bar'), and so on.
prefixes, str list: A list of prefixes that will be searched prioritarily to the DEFAULT_PREFIXES defined in this module.
static (bool): A boolean, indicating if we should try only to search for static versions of the libraries. If not set, any would do.

Returns a list of filenames that exist on the filesystem, matching your description.

class bob.extension.pkgconfig(name, paths=None)[source]¶

A class for capturing configuration information from pkg-config

Example usage:

>>> from bob.extension import pkgconfig
>>> blitz = pkgconfig('blitz')
>>> blitz.include_directories()
[...]
>>> blitz.library_directories()
[...]

If the package does not exist, a RuntimeError is raised. All calls to any methods of a pkgconfig object are translated into a subprocess call that queries for that specific information. If pkg-config fails, a RuntimeError is raised.

cflags_other()[source]¶

Returns a pre-processed dictionary containing compilation options.

Equivalent command line version:

$ PKG_CONFIG_PATH=<paths> pkg-config --cflags-only-other <name>

The returned dictionary contains two entries extra_compile_args and define_macros. The define_macros entries are ready for deployment in the setup() function of your package.

extra_link_args()[source]¶

Returns a pre-processed list containing extra link arguments.

Equivalent command line version:

$ PKG_CONFIG_PATH=<paths> pkg-config --libs-only-other <name>

include_directories()[source]¶

Returns a pre-processed list containing include directories.

Equivalent command line version:

$ PKG_CONFIG_PATH=<paths> pkg-config --cflags-only-I <name>

libraries()[source]¶

Returns a pre-processed list containing libraries to link against

Equivalent command line version:

$ PKG_CONFIG_PATH=<paths> pkg-config --libs-only-l <name>

library_directories()[source]¶

Returns a pre-processed list containing library directories.

Equivalent command line version:

$ PKG_CONFIG_PATH=<paths> pkg-config --libs-only-L <name>

other_libraries()[source]¶

Returns a pre-processed list containing libraries to link against

Equivalent command line version:

$ PKG_CONFIG_PATH=<paths> pkg-config --libs-only-other <name>

package_macros()[source]¶

Returns package availability and version number macros

This method returns a python list with 2 macros indicating package availability and a version number, using standard GNU compatible names. For example, if the package is named foo and its version is 1.4, this command would return:

>>> from bob.extension import pkgconfig
>>> blitz = pkgconfig('blitz')
>>> blitz.package_macros()
[('HAVE_BLITZ', '1'), ('BLITZ_VERSION', '"..."')]

variable(name)[source]¶

Returns a variable with a specific name (if it exists)

Equivalent command line version:

$ PKG_CONFIG_PATH=<paths> pkg-config --variable=<variable-name> <name>

Warning

If a variable does not exist in a package, pkg-config does not signal an error. Instead, it returns an empty string. So, do we.

variable_names()[source]¶

Returns a list with all variable names know to this package

Equivalent command line version:

$ PKG_CONFIG_PATH=<paths> pkg-config --print-variables <name>

bob.extension.uniq(seq, idfun=None)[source]¶: Very fast, order preserving uniq function

bob.extension.uniq_paths(seq)[source]¶: Uniq’fy a list of paths taking into consideration their real paths

class bob.extension.build_ext(dist, **kw)[source]¶

Bases: setuptools.command.build_ext.build_ext

Compile the C++ :py:class`Library`’s using CMake, and the python extensions afterwards

See the documentation for distutils.command.build_ext for more information.

announce(msg, level=1)¶: If the current verbosity level is of greater than or equal to ‘level’ print ‘msg’ to stdout.

boolean_options = ['inplace', 'debug', 'force', 'swig-cpp', 'user', 'cython-cplus', 'cython-create-listing', 'cython-line-directives', 'cython-c-in-temp', 'cython-gdb', 'pyrex-cplus', 'pyrex-create-listing', 'pyrex-line-directives', 'pyrex-c-in-temp', 'pyrex-gdb']¶

build_extensions()[source]¶

check_extensions_list(extensions)[source]¶

Ensure that the list of extensions (presumably provided as a command option ‘extensions’) is valid, i.e. it is a list of Extension objects. We also support the old-style list of 2-tuples, where the tuples are (ext_name, build_info), which are converted to Extension instances here.

Raise DistutilsSetupError if the structure is invalid anywhere; just returns otherwise.

command_consumes_arguments = False¶

copy_extensions_to_source()¶

copy_file(infile, outfile, preserve_mode=1, preserve_times=1, link=None, level=1)¶: Copy a file respecting verbose, dry-run and force flags. (The former two default to whatever is in the Distribution object, and the latter defaults to false for commands that don’t define it.)

copy_tree(infile, outfile, preserve_mode=1, preserve_times=1, preserve_symlinks=0, level=1)¶: Copy an entire directory tree respecting verbose, dry-run, and force flags.

cython_sources(sources, extension)[source]¶: Walk the list of source files in ‘sources’, looking for Cython source files (.pyx and .py). Run Cython on all that are found, and return a modified ‘sources’ list with Cython source files replaced by the generated C (or C++) files.

debug_print(msg)¶: Print ‘msg’ to stdout if the global DEBUG (taken from the DISTUTILS_DEBUG environment variable) flag is true.

description = 'build C/C++ and Cython extensions (compile/link to build directory)'¶

dump_options(header=None, indent='')¶

ensure_dirname(option)¶

ensure_filename(option)¶: Ensure that ‘option’ is the name of an existing file.

ensure_finalized()¶

ensure_string(option, default=None)¶: Ensure that ‘option’ is a string; if not defined, set it to ‘default’.

ensure_string_list(option)¶: Ensure that ‘option’ is a list of strings. If ‘option’ is currently a string, we split it either on /,s*/ or /s+/, so “foo bar baz”, “foo,bar,baz”, and “foo, bar baz” all become [“foo”, “bar”, “baz”].

execute(func, args, msg=None, level=1)¶

find_swig()[source]¶: Return the name of the SWIG executable. On Unix, this is just “swig” – it should be in the PATH. Tries a bit harder on Windows.

get_command_name()¶

get_export_symbols(ext)¶

get_ext_fullname(ext_name)[source]¶

Returns the fullname of a given extension name.

Adds the package. prefix

get_ext_fullpath(ext_name)[source]¶

Returns the path of the filename for a given extension.

The file is located in build_lib or directly in the package (inplace option).

get_finalized_command(command, create=1)¶: Wrapper around Distribution’s ‘get_command_obj()’ method: find (create if necessary and ‘create’ is true) the command object for ‘command’, call its ‘ensure_finalized()’ method, and return the finalized command object.

get_libraries(ext)[source]¶: Return the list of libraries to link against when building a shared extension. On most platforms, this is just ‘ext.libraries’; on Windows and OS/2, we add the Python library (eg. python20.dll).

get_outputs()¶

get_source_files()[source]¶

get_sub_commands()¶: Determine the sub-commands that are relevant in the current distribution (ie., that need to be run). This is based on the ‘sub_commands’ class attribute: each tuple in that list may include a method that we call to determine if the subcommand needs to be run for the current distribution. Return a list of command names.

help_options = [('help-compiler', None, 'list available compilers', <function show_compilers>)]¶

initialize_options()¶

links_to_dynamic(ext)¶: Return true if ‘ext’ links to a dynamic lib in the same package

make_archive(base_name, format, root_dir=None, base_dir=None, owner=None, group=None)¶

make_file(infiles, outfile, func, args, exec_msg=None, skip_msg=None, level=1)¶: Special case of ‘execute()’ for operations that process one or more input files and generate one output file. Works just like ‘execute()’, except the operation is skipped and a different message printed if ‘outfile’ already exists and is newer than all files listed in ‘infiles’. If the command defined ‘self.force’, and it is true, then the command is unconditionally run – does no timestamp checks.

mkpath(name, mode=511)¶

move_file(src, dst, level=1)¶: Move a file respecting dry-run flag.

reinitialize_command(command, reinit_subcommands=0, **kw)¶

run_command(command)¶: Run some other command: uses the ‘run_command()’ method of Distribution, which creates and finalizes the command object if necessary and then invokes its ‘run()’ method.

sep_by = " (separated by ':')"¶

set_undefined_options(src_cmd, *option_pairs)¶: Set the values of any “undefined” options from corresponding option values in some other command object. “Undefined” here means “is None”, which is the convention used to indicate that an option has not been changed between ‘initialize_options()’ and ‘finalize_options()’. Usually called from ‘finalize_options()’ for options that depend on some other command rather than another option of the same command. ‘src_cmd’ is the other command from which option values will be taken (a command object will be created for it if necessary); the remaining arguments are ‘(src_option,dst_option)’ tuples which mean “take the value of ‘src_option’ in the ‘src_cmd’ command object, and copy it to ‘dst_option’ in the current command object”.

setup_shlib_compiler()¶

spawn(cmd, search_path=1, level=1)¶: Spawn an external command respecting dry-run flag.

sub_commands = []¶

swig_sources(sources, extension)[source]¶: Walk the list of source files in ‘sources’, looking for SWIG interface (.i) files. Run SWIG on all that are found, and return a modified ‘sources’ list with SWIG source files replaced by the generated C (or C++) files.

user_options = [('build-lib=', 'b', 'directory for compiled extension modules'), ('build-temp=', 't', 'directory for temporary files (build by-products)'), ('plat-name=', 'p', 'platform name to cross-compile for, if supported (default: linux-x86_64)'), ('inplace', 'i', 'ignore build-lib and put compiled extensions into the source directory alongside your pure Python modules'), ('include-dirs=', 'I', "list of directories to search for header files (separated by ':')"), ('define=', 'D', 'C preprocessor macros to define'), ('undef=', 'U', 'C preprocessor macros to undefine'), ('libraries=', 'l', 'external C libraries to link with'), ('library-dirs=', 'L', "directories to search for external C libraries (separated by ':')"), ('rpath=', 'R', 'directories to search for shared C libraries at runtime'), ('link-objects=', 'O', 'extra explicit link objects to include in the link'), ('debug', 'g', 'compile/link with debugging information'), ('force', 'f', 'forcibly build everything (ignore file timestamps)'), ('compiler=', 'c', 'specify the compiler type'), ('swig-cpp', None, 'make SWIG create C++ files (default is C)'), ('swig-opts=', None, 'list of SWIG command line options'), ('swig=', None, 'path to the SWIG executable'), ('user', None, 'add user include, library and rpath'), ('cython-cplus', None, 'generate C++ source files'), ('cython-create-listing', None, 'write errors to a listing file'), ('cython-line-directives', None, 'emit source line directives'), ('cython-include-dirs=', None, "path to the Cython include files (separated by ':')"), ('cython-c-in-temp', None, 'put generated C files in temp directory'), ('cython-gen-pxi', None, 'generate .pxi file for public declarations'), ('cython-directives=', None, 'compiler directive overrides'), ('cython-gdb', None, 'generate debug information for cygdb'), ('cython-compile-time-env', None, 'cython compile time environment'), ('pyrex-cplus', None, 'generate C++ source files'), ('pyrex-create-listing', None, 'write errors to a listing file'), ('pyrex-line-directives', None, 'emit source line directives'), ('pyrex-include-dirs=', None, "path to the Cython include files (separated by ':')"), ('pyrex-c-in-temp', None, 'put generated C files in temp directory'), ('pyrex-gen-pxi', None, 'generate .pxi file for public declarations'), ('pyrex-directives=', None, 'compiler directive overrides'), ('pyrex-gdb', None, 'generate debug information for cygdb')]¶

warn(msg)¶

write_stub(output_dir, ext, compile=False)¶

finalize_options()[source]¶

run()[source]¶: Iterates through the list of Extension packages and reorders them, so that the Library’s come first

build_extension(ext)[source]¶

Builds the given extension.

When the extension is of type Library, it compiles the library with CMake, otherwise the default compilation mechanism is used. Afterwards, it adds the according library, and the include and library directories of the Library’s, so that other Extensions can find the newly generated lib.

get_ext_filename(fullname)[source]¶: Returns the library path for the given name

bob.extension.get_config(package='bob.extension', externals=None, api_version=None)[source]¶

Returns a string containing the configuration information for the given package name. By default, it returns the configuration of this package.

This function can be reused by other packages. If these packages have external C or C++ dependencies, the externals dictionary can be specified. Also, if the package provides an API version, it can be specified.

Keyword parameters:

package: The name of the package to get the configuration information from. Usually, the __name__ of the package.
externals: A dictionary of external C or C++ dependencies, with the dep``endent package name as key, and a free ``description as value.
api_version: The API version of the package, if any.

Scripts¶

bob.extension.scripts.dependency_graph(command_line_options=None)¶

bob.extension.scripts.new_version(command_line_options=None)¶