Reference§

Below are listed all the builtin functions and properties available to bfg9000 scripts (build.bfg and options.bfg). Most are only available to build.bfg files, since that's where most of the build configuration logic belongs, but some may be used in options.bfg. Consult each function to see its availability.

General§

Representing paths§

While all platforms have paths, their representation varies from platform to platform. bfg9000 smooths over these differences by providing a cross-platform representation of paths. Both POSIX- and Windows-style paths are supported and will be translated to a standard internal representation before being emitted to build scripts in their platform-specific form. Thus, foo/bar and foo\bar are equivalent to bfg9000.

Note

While absolute paths are rarely needed in a build.bfg script, it's still possible to use them. However, there are some caveats: 1) POSIX-style absolute paths will refer to that (absolute) path on the current drive, 2) Windows-style absolute paths will fail to work on POSIX systems, and 3) Windows-style paths with a drive letter and a relative path (e.g. C:foo) are unsupported by bfg9000.

File types§

Files used in a build.bfg script are divided by their types (e.g. source code, header files, etc). All files from the source directory which are referenced in the build.bfg script will automatically be added to the source distribution when it's built.

In most cases, you can simply pass a string to functions expecting a file type; the string will automatically be converted to a file object of the appropriate type. However, in some cases, you may wish to explicitly create a file object. This can be useful, for instance, when running commands that take a source file as an argument, e.g. in the following snippet:

command('script', cmd=['python', source_file('script.py')])

Using source_file here allows you to specify that the file is found in the source directory, rather than the build directory.

directory(name, [include], [exclude], [filter])§

Availability: build.bfg

Create a reference to an existing directory named name. This allows you to refer to an arbitrary subfolder of your source directory. The arguments include, exclude, and filter are as per find_files. Any matching files will be added to the project's source distribution.

extra_dist([files], [dirs])§

Availability: build.bfg

Add extra files and dirs to the list of recognized source files. This lets you reference files that are part of the source distribution but which have no impact on the build proper (e.g. READMEs).

generic_file(name)§

Availability: build.bfg

Create a reference to an existing file named name.

header_directory(name, [include], [exclude], [filter], [system])§

Availability: build.bfg

Create a reference to a directory named name containing header files for the project. This can then be used in the include argument when compiling a source file. The arguments include, exclude, and filter are as per find_files. Any matching files will be added to the project's source distribution.

If system is True, this directory will be treated as a system directory for compilers that support this.

header_file(name)§

Availability: build.bfg

Create a reference to an existing header named name. This is useful if you'd like to install a single header file for your project.

module_def_file(name)§

Availability: build.bfg

Create a reference to an existing module-definition file named name. Module-definition files are sometimes used when building libraries on Windows.

source_file(name, [lang])§

Availability: build.bfg

Create a reference to an existing source file named name. If lang is not specified, the language of the file is inferred from its extension.

Build steps§

Availability: build.bfg

Build steps define rules to create an output (usually a file) from zero or more inputs (also usually files). As you may expect, if the output doesn't exist, the step is run to generate it. Each input is a dependency on the output, and any changes to an input will result in a rebuild. This includes headers #included by any of the source files, but does not include files external to the project (i.e. packages).

In addition, all build steps have the ability to define extra dependencies via the extra_deps argument. These can be files or other build steps, and changes to them will trigger a rebuild as with the build's inputs.

Build steps also allow setting a custom description. This can be used to provide a friendlier message for the Ninja backend to show when building that step.

Finally, build steps which produce a file can also be used like the file types described above to refer to prebuilt files already in the source tree (e.g. static libraries provided in binary form by a vendor). This is described in more detail for each step below.

Note

For build steps which produce a file, the exact name of the output file is determined by the platform you're running on. For instance, when building an executable file named "foo" on Windows, the resulting file will be foo.exe.

build_step(name, cmd|cmds, [environment], [type], [args], [kwargs], [extra_deps], [description])§

Availability: build.bfg

Create a custom build step that produces a file named name by running an arbitrary command (cmd or cmds). name may either be a single file name or a list of file names. For a description of the arguments cmd, cmds, and environment, see command below.

By default, this function return a source_file; you can adjust this with the type argument. This should be either 1) a function returning a file object, or 2) an object with a .type attribute that meets the criteria of (1). You can also pass args and kwargs to forward arguments along to this function.

command(name, cmd|cmds, [environment], [extra_deps], [description])§

Availability: build.bfg

Create a build step named name that runs a list of arbitrary commands, specified in either cmd or cmds; cmd takes a single command, whereas cmds takes a list of commands. Each command may be a string to be parsed according to shell rules, a file object (such as an executable), or a list of arguments to be passed directly to the process.

You may also pass a dict to environment to set environment variables for the commands. These override any environment variables set on the command line.

executable(name, [files, ..., [extra_deps], [description]])§

Availability: build.bfg

Create a build step that builds an executable file named name. files is the list of source (or object) files to link. If an element of files is a source file (or a plain string), this function will implicitly call object_file on it.

The following arguments may also be specified:

If neither files nor libs is specified, this function merely references an existing executable file (a precompiled binary, a shell script, etc) somewhere on the filesystem. In this case, name is the exact name of the file, relative to the source directory. This allows you to refer to existing executables for other functions. In addition, the following arguments may be specified:

This build step recognizes the dynamic linking environment variables and the compiler environment variable (e.g. CC) for the relevant language.

Note

When passing options to the linker via link_options, these options will be passed to whatever executable is typically used to link object files for the source language; in particular, this means that when using a tool like GCC to build your project, any linker options that need to be forwarded on to ld should be prepended with '-Wl,'.

library(name, [files, ..., [extra_deps], [description]])§

Availability: build.bfg

Create a build step that builds a shared library named name. Its arguments are the same as the superset of shared_library and static_library, with the following additional argument:

Like with executable, if files isn't specified, this function merely references an existing library somewhere on the filesystem. In this case, name must be specified and is the exact name of the file, relative to the source directory. You may also pass in the format argument as with executable.

If name refers to a dual-use library, this function will return the library subtype as specified in kind (e.g. passing 'shared' will return the shared version of the library).

This build step recognizes the dynamic linking environment variables or the static linking environment variables, as well as the compiler environment variable (e.g. CC) for the relevant language.

Warning

By convention, MSVC uses the same filenames for static libraries as for import libs for shared libraries. As a result, if both shared and static library builds are enabled with MSVC, bfg9000 will fall back to building only the shared library.

object_file([name], [file, ..., [extra_deps], [description]])§

Availability: build.bfg

Create a build step that compiles a source file named file to an object file named name; if name is not specified, it takes the file name in file without the extension.

The following arguments may also be specified:

If file isn't specified, this function merely references an existing object file somewhere on the filesystem. In this case, name must be specified and is the exact name of the file, relative to the source directory. In addition, the following arguments may be specified:

This build step recognizes the compilation environment variables for the relevant language.

object_files(files, ..., [extra_deps], [description])§

Availability: build.bfg

Create a compilation build step for each of the files in files; this is equivalent to calling object_file for each element in files.

In addition, object_files returns a special list that allows you to index into it using the filename of one of the source files listed in files. This makes it easy to extract a single object file to use in other places, e.g. test code. For example:

objs = object_files(['foo.cpp', 'bar.cpp'])
release_exe = executable('release', objs)

foo_obj = objs['foo.cpp']
test_exe = executable('test', ['test.cpp', foo_obj])

precompiled_header([name], [file, ..., [extra_deps], [description]])§

Availability: build.bfg

Create a build step that generates a precompiled header, which can be used to speed up the compilation of object files. If name is not specified, it is inferred from the value of file; the exact name varies based on the compiler being used, but typically looks like header.hpp.pch for cc-like compilers and header.pch for MSVC-like compilers.

The arguments for precompiled_header are the same as for object_file, with the following additional argument:

If file isn't specified, this function merely references an existing precompiled header somewhere on the filesystem. In this case, name must be specified and is the exact name of the file, relative to the source directory. In addition, the following argument may be specified:

Warning

The exact behavior of precompiled headers varies according to the compiler you're using. In GCC and Clang, the header to be precompiled must be the first file #included in each source file. In MSVC, the resulting precompiled header is actually compiled within the context of a particular source file and will contain all the code up to and including the header in question.

shared_library(name, [files, ..., [extra_deps], [description]])§

Availability: build.bfg

Create a build step that builds a shared library named name. Its arguments are the same as executable, with the following additional arguments:

Like with executable, if files isn't specified, this function merely references an existing shared library somewhere on the filesystem. In this case, name must be specified and is the exact name of the file, relative to the source directory. You may also pass in the format argument as with executable.

If name refers to a dual-use library, this function will return the shared version of the library.

This build step recognizes the dynamic linking environment variables and the compiler environment variable (e.g. CC) for the relevant language.

Note

On Windows, this produces two files for native-runtime languages (e.g. C or C++): name.dll and name.lib. The latter is the import library, used when linking to this library.

Additionally for native languages on Windows, this step will add a preprocessor macro named LIB<NAME>_EXPORTS that can be used for declaring public symbols. See Building libraries on Windows for an example of how to use this macro in your code.

static_library(name, [files, ..., [extra_deps], [description]])§

Availability: build.bfg

Create a build step that builds a static library named name. Its arguments are the same as executable, with the following additional argument:

Other link-related arguments (link_options, libs, and libraries from packages) have no direct effect on this build step. Instead, they're cached and forwarded on to any dynamic linking step that uses this static library.

Like with executable, if files isn't specified, this function merely references an existing shared library somewhere on the filesystem. In this case, name must be specified and is the exact name of the file, relative to the source directory. In addition, the following arguments may be specified:

If name refers to a dual-use library, this function will return the static version of the library.

This build step recognizes the static linking environment variables.

Note

On Windows, this step will add a preprocessor macro on Windows named LIB<NAME>_STATIC that can be used for declaring public symbols. See Building libraries on Windows for an example of how to use this macro in your code.

whole_archive(name, [files, ..., [extra_deps]])§

Availability: build.bfg

Create a build step that builds a whole-archive named name. Whole archives ensures that every object file in the library is included, rather than just the ones whose symbols are referenced. This is typically used to turn a static library into a shared library.

whole_archive's arguments are the same as for static_library. In addition, you can pass an existing static library to whole_archive to convert it into a whole archive.

Grouping rules§

alias(name, [deps])§

Availability: build.bfg

Create a build step named name that performs no actions on its own. Instead, it just runs its dependencies listed in deps as necessary. This build step is useful for grouping common steps together.

default(...)§

Availability: build.bfg

Specify a list of build steps that should be run by default when building. These are all accumulated into the all target. If default is never called, all executables and libraries not passed to test will be built by default.

install(...)§

Availability: build.bfg

Specify a list of files that need to be installed for the project to work. Each will be installed to the appropriate location based on its type, e.g. header files will go in $PREFIX/include by default on POSIX systems. These are all accumulated into the install target. If there are any runtime dependencies for a file (such as shared libraries you just built), they will be installed as well.

Note

When explicitly listing a target, all the files for that target will be installed. For instance, on Windows, this means that passing in a shared library will install the DLL and the import library.

This rule recognizes the following environment variables: DESTDIR, INSTALL, INSTALL_NAME_TOOL, MKDIR_P, PATCHELF.

Semantic options§

Semantic options are a collection of objects that allow a build to define options in a tool-agnostic way. These options will automatically be converted to the appropriate string form for the tool when generating the build file.

opts.debug()§

Produce debugging information for the built object in the default debugging format.

opts.define(name, [value])§

Create a preprocessor macro named name and with an optional value value. Note that if you'd like the value to be a string literal, you need to escape the string like so:

opts.define('MY_MACRO', '"This is a string, isn\'t it?"')

opts.optimize(...)§

Set the level of optimization for the compiler employ; multiple values can be specified at once, e.g. opts.optimize('speed, 'linktime). The possible warning values are:

opts.sanitize()§

Enable run-time sanitization checks when compiling a particular source file; this is equivalent to -fsanitize=address on GCC-like compilers and /RTC1 on MSVC.

opts.std(value)§

Specify the version of the language's standard (e.g. "c++14") to use when building.

opts.warning(...)§

Set the level of warnings for the compiler to emit when compiling; multiple values can be specified at once, e.g. opts.warning('all', 'error'). The possible warning values are:

Global options§

global_options(options, lang)§

Availability: build.bfg

Specify some options (either as a string or list) to use for all compilation steps for the language (or list of languages) lang.

Availability: build.bfg

Specify some options (either as a string or list) to use for all link steps for a given family of languages (or a list of families) and linking mode.

By default family is 'native', used for C, C++, and other languages using the same linking process. You can also specify 'jvm' for JVM-based languages (Java, Scala). mode may be either 'dynamic' (the default) to modify executables and shared libraries or 'static' to modify static libraries.

Note

As with the link_options argument for executable() and shared_library(), dynamic link options will be passed to whatever executable is typically used to link object files for the source language; in particular, this means that when using a tool like GCC to build your project, any linker options that need to be forwarded on to ld should be prepended with '-Wl,'.

Test rules§

These rules help you define automated tests that can all be run via the test target. For simple cases, you should only need the test rule, but you can also wrap your tests with a separate driver using test_driver.

For cases where you only want to build the tests, not run them, you can use the tests target.

test(test, [environment|driver])§

Availability: build.bfg

Create a single test. cmd is the base command (possibly with arguments) to run; this works much like the cmd argument in the command built-in. You can also pass temporary environment variables as a dict via environment, or specify a test driver to add this test file to via driver.

test_driver(cmd, [environment|parent], [wrap_children])§

Availability: build.bfg

Create a test driver which can run a series of tests, specified as command-line arguments to the driver. cmd is the base command (possibly with arguments) to run; this works much like the cmd argument in the command built-in. You can also pass temporary environment variables as a dict with environment, or specify a parent test driver to wrap this driver via parent.

Finally, you can specify wrap_children to determine how tests using this driver are run. If true, each test will be wrapped by env.run_arguments; if false (the default), tests will be used as-is.

test_deps(...)§

Availability: build.bfg

Specify a list of extra dependencies which must be satisfied when building the tests via the tests target.

Package resolvers§

boost_package([name], [version])§

Availability: build.bfg

Search for a Boost library. You can specify name (as a string or a list) to specify a specific Boost library (or libraries); for instance, 'program_options'. For header-only libraries, you can omit name. If version is specified, it will ensure that the installed version of Boost meets the version requirement; it must be formatted as a Python version specifier.

If this function is unable to find the specified Boost library, it will raise a PackageResolutionError. If the library is found but doesn't match the required version, a PackageVersionError will be raised instead.

This rule recognizes the following environment variables: BOOST_ROOT, BOOST_INCLUDEDIR, BOOST_LIBRARYDIR, CPATH, INCLUDE, LIB, LIBRARY_PATH.

framework(name, [suffix])§

Reference a macOS framework named name with the optional suffix suffix. Though not a "package" in name, this can be used wherever packages are accepted.

package(name, [version], [lang], [kind], [headers], [libs])§

Availability: build.bfg

Search for a package named name. lang is the source language of the library ('c' by default); this will affect how the package is resolved. For native libraries (C, C++, Fortran, etc), this will use pkg-config to resolve the package if it's installed. Otherwise (or if pkg-config can't find the package), this will check the system's default library locations. If this function is unable to find the package, it will raise a PackageResolutionError.

You can also specify kind to one of 'any' (the default), 'shared', or 'static'. This allows you to restrict the search to find only static versions of a library, for example.

If version is specified, it will (if possible) ensure that the installed version of the package meets the version requirement; it must be formatted as a Python version specifier. If this check fails, a PackageVersionError will be raised.

The headers and libs arguments can be used as fallbacks when pkg-config fails to resolve the package. headers allows you to specify a header file (or list thereof) that you need to use in your source files. This will search for the header files and add the appropriate include directories to your build configuration. libs lets you list any library names that are part of this package; by default, this is set to the package's name. You can also pass None to libs in order to explicitly indicate that the library is header-only.

This rule recognizes the following environment variables: CLASSPATH, CPATH, INCLUDE, LIB, LIBRARY_PATH, PKG_CONFIG.

Note

This function can also be used to refer to the pthread library. On many Unix-like systems, instead of using -lpthread during the link step, it's preferred to use -pthread during compilation and linking. Using package('pthread') will handle this automatically.

pkg_config([name], [desc_name], [desc], [url], [version], [requires], [requires_private], [conflicts], [includes], [libs], [libs_private], [options], [link_options], [link_options_private], [auto_fill])§

Availability: build.bfg

Create pkg-config information for this project and install it along with the rest of the installed files. All of these arguments are optional and will be automatically inferred from the rest of the build where possible. Unless otherwise noted, these arguments correspond directly to the fields in the pkg-config .pc file.

If auto_fill is true (the default), this function will automatically fill in default values for the following fields:

system_executable(name)§

Availability: build.bfg

Search for an executable named name somewhere in the system's PATH.

This rule recognizes the following environment variables: PATH, PATHEXT.

Environment§

Occasionally, build scripts need to directly query aspects of the environment. In bfg9000, this is performed with the environment object and its various members.

Environment object§

The environment, env, is a special object that encapsulates information about the system outside of bfg9000. It's used internally for nearly all platform-specific code, but it can also help in build.bfg (or options.bfg!) files when you encounter some unavoidable issue with multiplatform compatibility.

Note

This listing doesn't cover all available functions on the environment, since many are only useful to internal code. However, the most relevant ones for build.bfg files are shown below.

env.builder(lang)§

Return the builder used by bfg9000 for a particular language lang.

env.execute(args, [env], [env_update], [shell], [stdout], [stderr], [returncode])§

Execute the command-line arguments in args and return the output. If shell is true, args should be a string that will be interpreted by the system's shell; if not (the default), it should be a series of arguments.

You can also set env to be a dictionary of environment variables to pass to the child process. If env_update is true (the default), these will be added to the environment variables in env.varables; otherwise, env represents all the environment variables to pass to the child process.

stdout and stderr are env.Mode values that describe how (or if) output should be redirected. By default, both are set to Mode.normal.

Finally, returncode specifies the expected return code from the subprocess. This is 0 by default, and may be either a number, a list of numbers, or 'any' to match any return code. If the return code fails to match, a CalledProcessError will be thrown.

env.getvar(name, [default])§

Equivalent to env.variables.get(name, default).

env.host_platform§

Return the host platform used for the build.

env.Mode§

An enumeration of output modes for env.execute and env.run. Possible values are:

env.run_arguments(args, [lang])§

Generate the arguments needed to run the command in args. If args is a file type (or a list beginning with a file type) such as an executable, it will be prepended with the runner for lang as needed. If lang is None, the language will be determined by the language of args's first element.

env.run(args, [lang], [env], [env_update], [stdout], [stderr], [returncode])§

Run a command, generating any arguments needed to perform the operation. Equivalent to env.execute(env.run_arguments(arg, lang), ...).

env.target_platform§

Return the target platform used for the build.

env.variables§

A dict of all the environment variables as they were defined when the build was first configured.

Builders§

Builder objects represent the toolset used to build executables and libraries for a particular source language. They can be retrieved via env.builder. While builder objects are primarily suited to bfg's internals, there are still a few useful properties for build.bfg files:

builder.flavor§

The "flavor" of the builder, i.e. the kind of command-line interface it has. Possible values are 'cc', 'msvc', and 'jvm'.

builder.brand§

The brand of the builder, i.e. the command name people use for it. Currently, for languages in the C family (including Fortran), this is one of 'gcc', 'clang', 'msvc', or 'unknown'. For languages in the Java family, this is one of 'oracle', 'openjdk', 'epfl' (for Scala), or 'unknown'.

builder.version§

The version of the builder (specifically, the version of the primary compiler for the builder). May be None if bfg9000 was unable to detect the version.

builder.lang§

The language of the source files that this builder is designed for.

builder.object_format§

The object format that the builder outputs, e.g. 'elf', 'coff', or 'jvm'.

builder.compiler§

The compiler used with this builder.

builder.pch_compiler§

The compiler used to build precompiled headers with this builder. May be None for languages or toolsets that don't support precompiled headers.

builder.linker(mode)§

The linker used with this builder. mode is one of 'executable', 'shared_library', or 'static_library' Its public properties are the same as compiler.

cc-like builders also support a mode of 'raw', which returns an object representing the actual linker, such as ld.

builder.runner§

The runner used with files built by this builder (e.g. java). This may be None for languages which have no runner, such as C and C++.

Compilers§

Builder objects represent the specific used to compile a source file (generally into an object file).

compiler.flavor§

The "flavor" of the compiler, i.e. the kind of command-line interface it has; e.g. 'cc', 'msvc'.

compiler.brand§

The brand of the compiler; typically the same as builder.brand.

compiler.version§

The version of the compiler; typically the same as builder.version.

compiler.language§

The language of the compiler; typically the same as builder.language.

compiler.command§

The command to run when invoking this compiler, e.g. g++-4.9.

Platforms§

Platform objects represent the platform that the project is being compiled for.

platform.family§

The family of the platform. Either 'posix' or 'windows'.

platform.genus§

The sub-type of the platform, e.g. 'linux', darwin', or 'winnt'.

platform.name§

An alias for platform.species.

platform.species§

The specific name of the platform, e.g. 'linux', 'macos', or 'winnt'.

Utilities§

argument(names..., [action], [nargs], [const], [default], [type], [choices], [required], [help], [metavar], [dest])§

Availability: options.bfg

Define how a particular command-line argument will be parsed. names is a sequence of argument names; these will be prefixed with -- and --x- for parsing. For example, passing 'foo' will add --foo and --x-foo as possible command-line arguments.

All other arguments to this function have the same behavior as in argparse.ArgumentParser.add_argument(), with the exception of action, which accepts two extra values:

argv§

Availability: build.bfg

Retrieve the set of user-defined arguments passed to bfg9000; this is an argparse.Namespace object.

__bfg9000__§

Availability: build.bfg, options.bfg, and <toolchain>.bfg

A dictionary containing all the builtin functions and global variables defined by bfg9000. This can be useful for feature detection or accessing builtins shadowed by a local variable.

bfg9000_required_version([version], [python_version])§

Availability: build.bfg, options.bfg, and <toolchain>.bfg

Set the required version for bfg9000 and/or the required python_version. Each of these is a standard Python version specifier. If the actual versions don't match the specifiers, a VersionError is raised.

bfg9000_version§

Availability: build.bfg, options.bfg, and <toolchain>.bfg

Return the current version of bfg9000. This can be useful if you want to optionally support a feature only available in certain versions of bfg.

debug(message, [show_stack])§

Log a debug message with the value message. If show_stack is true (the default), show the stack trace where the message was logged from.

Note

Debug messages are hidden by default; pass --debug on the command line to them.

filter_by_platform(name, path, type)§

Availability: build.bfg

Return FindResult.include if path is a filename that should be included for the target platform, and FindResult.not_now otherwise. File (or directory) names like PLATFORM or foo_PLATFORM.cpp are excluded if PLATFORM is a known platform name that doesn't match the target platform. Known platform names are: 'posix','linux', 'darwin', 'cygwin', 'windows', 'winnt', 'win9x', 'msdos'.

This is the default filter for find_files.

FindResult§

Availability: build.bfg

An enum to be used as the result of a filter function for find_files. The possible enum values are:

find_files([path], [name], [type], [extra], [exclude], [flat], [filter], [cache], [dist], [as_object])§

Availability: build.bfg

Find files in path whose name matches the glob (or list of globs) name. The following arguments may be specified:

The cache argument is particularly important. It allows you to add or remove source files and not have to worry about manually rerunning bfg9000.

info(message, [show_stack])§

Log an informational message with the value message. If show_stack is true, show the stack trace where the message was logged from.

project(name, [version])§

Availability: build.bfg

Set the name (and optionally the version) of the project. If you don't call this function to specify a project name, it defaults to the name of the project's source directory. This is primarily useful for creating source distributions.

warning(message)§

Log a warning with the value message and the stack trace where the warning was emitted.

Toolchain§

compiler(names, lang)§

Availability: <toolchain>.bfg

Set the compiler to use for the language lang. names is a string representing the path to the compiler (resolved as with which) or a list of possible paths (as strings or lists or strings). If strict is true, compiler will raise an IOError if an executable cannot be found; if false, it will use the first candidate.

compile_options(options, lang)§

Availability: <toolchain>.bfg

Set compilation options to use for the language lang. options is either a string of all the options or a list of strings, one element per option.

Note

Semantic options aren't supported here; instead, you should use the appropriate option strings for the compiler to be used.

environ§

Availability: <toolchain>.bfg

A dict of the current environment variables, suitable for getting/setting.

install_dirs([...])§

Availability: <toolchain>.bfg

Set the installation directories for this toolchain. Arguments to this function should be keyword args with one of the following names: prefix, exec_prefix, bindir, libdir, or includedir.

Note

Any installation directory set here overrides directories set on the command line.

lib_options(options, [format], [mode])§

Availability: <toolchain>.bfg

Set lib options to use for the format format (defaults to 'native') and mode mode (defaults to 'dynamic'). options is either a string of all the options or a list of strings, one element per option. Unlike link_options, this is used to specify options which appear at the end of a linker command (like $LDLIBS).

linker(names, [format], [mode])§

Availability: <toolchain>.bfg

Set the link to use for the format format (defaults to 'native') and mode mode (defaults to 'dynamic'). names is a string representing the path to the linker (resolved as with which) or a list of possible paths (as strings or lists or strings). If strict is true, linker will raise an IOError if an executable cannot be found; if false, it will use the first candidate.

Availability: <toolchain>.bfg

Set link options to use for the format format (defaults to 'native') and mode mode (defaults to 'dynamic'). options is either a string of all the options or a list of strings, one element per option.

runner(names, lang)§

Availability: <toolchain>.bfg

Set the runner to use for the language lang, if that language supports runners (e.g. Java, Scala, or a scripting language). names is a string representing the path to the compiler (resolved as with which) or a list of possible paths (as strings or lists or strings). If strict is true, compiler will raise an IOError if an executable cannot be found; if false, it will use the first candidate.

target_platform([platform], [arch])§

Availability: <toolchain>.bfg

Set the target platform of this build to platform and the architecture to arch. If either is not specified, the host system's platform/arch will be used.

The following platforms are recognized: 'android', 'cygwin', 'ios', 'linux', 'macos', 'win9x', and 'winnt'. Other platforms (e.g. 'freebsd') can be specified, and will be treated as generic POSIX platforms.

which(names, [resolve], [strict])§

Availability: <toolchain>.bfg

Find the best option for an executable named by names. names can be a string resolved as with the PATH environment variable in the shell, or else a list of names (as strings or lists of strings). If names contains a list-of-lists, the inner list represents a series of arguments to pass to the executable when running it.

If strict is true (the default), which will raise an IOError if an executable cannot be found; if false, it will return the first candidate as a string.

Exceptions§

CalledProcessError§

Availability: build.bfg and options.bfg

An exception raised when a subprocess fails to execute successfully. This is just an alias for the standard Python error subprocess.CalledProcessError.

PackageResolutionError§

Availability: build.bfg and options.bfg

An exception raised when a package resolution function is unable to find the specified package.

PackageVersionError§

Availability: build.bfg and options.bfg

An exception raised when a package resolution function found the specified package, but its version doesn't match the version specifier. Derived from both PackageResolutionError and VersionError.

VersionError§

Availability: build.bfg and options.bfg

An exception raised when a version fails to match the supplied version specifier.