Builtin Functions§

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.

In addition, you can terminate a path with / (or \) to ensure that it's treated as a directory; this affects the behavior of some builtins, such as auto_file.

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) on Windows, 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 objects§

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 object; 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=[source_file('script.py')])

Using source_file here allows you to specify that the file is a source code file found in the source directory, rather than the build directory. Further, since the file is a Python script, it can be executed as part of a command step.

In addition to the functions listed in this section below, build steps which generate a file can also be used to produce source files of that type (see each step's documentation for details).

Note

By default, when creating a file object in the source directory, it will automatically be added to the project's source distribution. To disable this, you can specify dist=False when creating the file object.

auto_file(name, [lang], *, [dist])§

Create a reference to an existing file named name. This function will try to automatically determine the file's kind based on its extension: source_file; header_file; or, if the extension is not recognized, generic_file. If lang is specified, files with an unrecognized extension will always be treated as source_files.

If name ends with a /, auto_file will create a directory instead or, if lang is specified, a header_directory.

Note

This function is primarily useful for writing generic code that works with multiple kinds of files; when creating a reference to a specific, known file, the concrete function listed above should be used instead.

directory(name, [include], *, [extra], [exclude], [filter], [dist], [cache])§

Availability: build.bfg

Create a reference to an existing directory named name; if name is a file object, create a reference to the directory containing that file. The arguments include, extra, exclude, filter, dist, and cache are forwarded to find_files; if neither include nor extra are specified, find_files will not be called. 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, *, [dist])§

Availability: build.bfg

Create a reference to an existing file named name.

header_directory(name, [include], [lang], *, [extra], [exclude], [filter], [system], [dist], [cache])§

Availability: build.bfg

Create a reference to a directory named name containing header files for the project (if name is a file object, create a reference to the directory containing that file). This can then be used in the include argument when compiling a source file. The arguments include, extra, exclude, filter, dist, and cache are forwarded to find_files, as with directory.

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

header_file(name, [lang], *, [dist])§

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. If lang is not specified, the language of the file is inferred from its extension.

man_page(name, *, [level], [compress], [dist], [extra_deps], [description])§

Availability: build.bfg

Create a reference to an existing man page named name at the specified level; if level is unspecified, guess it by the first character of the extension of name.

If compress is true, add a build step to gzip the man page and return the compressed file. If compress is 'auto' (the default), gzip the man page only if the gzip command is found on the system.

module_def_file(name, *, [dist])§

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], *, [dist])§

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§

Build steps describe how to create a target output (usually a file) from zero or more inputs (usually files or other build steps). As you may expect, if the output is a file and it's either out of date or 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).

Most build steps also have the ability to define additional 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.

Further, many 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.

File steps§

Naturally, the most common type of build step is one that generates a file. These are responsible for compiling object files, linking executables and libraries, and so on. In addition, all of these steps can be used like the file object functions 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 file steps, 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.

copy_file([name], file, *, [mode], [directory], [extra_deps], [description])§

Availability: build.bfg

Create a build step that copies a file named file to a destination named name; if name is not specified, this function will use the filename in file as a base (this is primarily useful for copying a file from the source directory to the build directory). mode specifies how the file should be copied: 'copy' (the default), 'symlink', or 'hardlink'.

You can also specify directory as an optional subdirectory to place the copied file into if name is unspecified, as with object_file.

This build step recognizes the environment variables for the relevant copy mode.

copy_files(files, *, [mode], [extra_deps], [description])§

Availability: build.bfg

Create a build step to copy each of the files in files using the specified mode; this is equivalent to calling copy_file for each element in files.

Like object_files, copy_files returns a special list that allows you to index into it using the filename of one of the source files listed in files.

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,'.

generated_source([name], file, *, ..., [extra_deps], [description])§

Availability: build.bfg

Create a build step that generates a source file named name from an input (typically another source file) named file; if name is not specified, this function will use the filename in file as a base (typically the filename with a different extension). Note that unlike with other file steps, name represents the exact file name to be used for the output file (i.e. the file extension isn't added automatically).

The following arguments may also be specified:

Note

When building files via yacc, this step will automatically generate both source and header files named <name>.tab.c and <name>.tab.h. You can force this step to build only the source file by passing a single filename to the name argument; you can also customize the names by passing a pair of filenames: generated_source(['foo.c', 'foo.h'], 'bar.y')

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

generated_sources(files, *, ..., [extra_deps], [description])§

Availability: build.bfg

Create a source-generation build step for each of the files in files; this is equivalent to calling generated_source for each element in files.

Like object_files, generated_sources returns a special list that allows you to index into it using the filename of one of the source files listed in files.

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, this function will use the filename in file as a base (typically the filename 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 (however, entry_point cannot be specified for static libraries), 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.

Test steps§

These steps help you define automated tests that can all be run via the test target. For simple cases, you should only need the test function, 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.

Grouping steps§

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 outputs that should be run by default when building. These are all accumulated into the all target. If an iterable object is passed as an argument to default, each element of the iterable will be added. If default is never called, all executables and libraries not passed to test will be built by default.

To allow this to be chained with other functions, default will return the arguments passed into it: as a single object if one argument is passed, or a tuple if multiple are passed.

install(..., [directory])§

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 an iterable object is passed as an argument to install, each element of the iterable will be added. If there are any runtime dependencies for a file (such as shared libraries you just built), they will be installed as well.

The install location can be customized via the directory argument. If passed as a string, the value will be appended to the default install location, e.g. install(header_file('foo.hpp'), directory='dir') will install to $INCLUDEDIR/dir/foo.hpp. You can also pass a Path object to override the default install location entirely.

To allow referencing the installed copies of the files passed to it, install will return file objects representing the installed files: as a single object if one argument is passed, or a tuple if multiple are passed.

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 step recognizes the following environment variables: $DESTDIR, $INSTALL, $INSTALL_NAME_TOOL, $MKDIR_P, $PATCHELF.

User-defined steps§

While the standard build steps cover the most common tasks in a build, many projects need to run more-specialized commands. A build script can define custom steps via the build_step and command functions: build_step defines a step which outputs one or more files that can be used in other steps, while command defines a more general step that should always be run when it's a target (similar to the test or install targets).

Both build_step and command allow you to specify an arbitrary command cmd or cmds; cmd takes a single command, whereas cmds takes a list of commands. Each command will be passed through env.run_arguments() and 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. Any file objects specified in the command will automatically be added as dependencies to this step. In addition, commands can include placeholders, which will automatically be expanded to the files corresponding to that placeholder.

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.

build_step(name, *, cmd|cmds, [files], [environment], [type], [always_outdated], [extra_deps], [description])§

Availability: build.bfg

Create a custom build step that produces one or more files named name by running an arbitrary command (cmd or cmds). name may either be a single file name or a list of file names. If always_outdated is true, this build step will be considered out-of-date no matter the status of the output.

The command argument can use the placeholders build_step.output to refer to the output files (defined by name) and build_step.input to refer to the input files (defined by files).

By default, the output of this step is one or more auto_files; you can adjust this with the type argument: this should be a function (or a list thereof) taking a path and returning a file object. If type is a single function, it will be applied to every output of build_step; if it's a list of functions, they will be applied element-wise to each output.

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

Availability: build.bfg

Create a build step named name that runs an arbitrary command, specified in either cmd or cmds. This build step is always considered out-of-date (as with a "phony" Makefile target, such as test or install).

The command argument can use the placeholder command.input to refer to the input files (defined by files).

placeholder§

Availability: build.bfg

When used in the cmd or cmds argument of build_step or command, this will create a reference to the inputs or outputs of the step. Placeholders can be indexed or sliced just like ordinary Python lists, and can also be combined with strings to add prefixes and suffixes:

script = source_file('script.py')

# Roughly equivalent to `python script.py -ifoo.txt -sbar.txt -squux.txt`
command('foo', cmd=[
    script, '-i' + command.input[0], '-s' + command.input[1:]
], files=['foo.txt', 'bar.txt', 'quux.txt'])

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. When using MSVC, this also determines whether to link to debug or release variants of the runtime.

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.entry_point(value)§

Set the symbol to use for beginning program execution. This is equivalent to passing entry_point=value to executable or shared_library.

opts.gui([main])§

Generate a graphical program; this is important for Windows builds, since the default is to generate a command-line program that opens a terminal window. On Windows, this option sets the subsystem to WINDOWS; if main is true, it also sets the entry point to mainCRTStartup (which calls the standard main function instead of the Windows-specific WinMain). On other platforms, this option has no effect.

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.static()§

When linking to libraries, only link statically.

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,'.

Package resolvers§

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, [submodules], [version], *, [lang], [kind], [system])§

Availability: build.bfg

Search for a package named name optionally containing one or more submodules. lang is the source language of the package (if not specified, this will use the default language for the project); this will affect how the package is resolved. For native packages (C, C++, Fortran, etc), this will use mopack to resolve the package; otherwise, this will use a language-specific check to find packages on the system. 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 system is True (the default), any directories will be treated as system directories for compilers that support this.

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.

When calling this function, you can exclude the submodules argument and pass a version as the second positional argument if it's parseable as a version specifier. For example, package('pkg', '>=1.0').

This function 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], *, [version], [includes], [libs], [auto_fill], ...)§

Availability: build.bfg

Create pkg-config information for this project and install it along with the rest of the installed files. In addition, create an -uninstalled variant of the pkg-config file to allow it to be used prior to installing the project.

All of the arguments below 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, this function will automatically fill in default values for the following fields:

If auto_fill is false, this function will return a package object that can be used in other build steps as normal.

system_executable(name, [format])§

Availability: build.bfg

Search for an executable named name somewhere in the system's $PATH. If format is unset, the executable's object format will be set to the default for the host platform.

This function 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], [extra_env], [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 is None (the default), the environment variables in env.variables will be used instead. Similarly, you can set extra_env to be a dict of env vars; these will be added to the dict in env (or to env.variables if env is None) to produce the final set of 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], [extra_env], [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.tool(name)§

Return the tool named name.

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/linkers§

Compiler and linker objects represent the specific tool used to compile a source file (generally into an object file) or to link a set of object files (generally into an executable or library).

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, represented as a list, e.g. ['g++'].

compiler.found§

Whether the command for this compiler was found on the system.

Tools§

Tool objects represent a specific command used to perform some task (usually during a build), such as 'copy' or 'rm'. They can be retrieved via env.tool. While tool objects are primarily suited to bfg's internals, there are still a few useful properties for build.bfg files:

tool.command§

The command to run when invoking this tool, represented as a list, e.g. ['cp', '-f'].

tool.found§

Whether this tool was found on the system.

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(..., [show_stack])§

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

Log a debug message with the specified arguments separated by spaces (as with print()). 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.

export(...)§

Availability: build.bfg and options.bfg

Within a submodule, export a list of keyword arguments to be returned to the calling module.

filter_by_platform(path)§

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 can be used as the filter for find_files or find_path.

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([pattern], *, [type], [extra], [exclude], ...)§

Availability: build.bfg

Find files that match the glob (or list of globs) pattern, returning them as file objects. Globs work much the same as in POSIX shells, with support for the following patterns:

By default, globs that end with a / will match only directories, while globs not ending with / will match only files. In addition, globs may be passed as path objects, allowing you to specify a different root to find files in (e.g. the build directory).

"Simple" globs, used for extra and exclude (see below) support all of the above except for **, and are matched against only the basename of each file. By default, several globs (.#*, *~, and #*#) are excluded; this can be customized via the find_exclude argument to project.

The following arguments may also 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.

find_paths([pattern], *, [type], [extra], [exclude], ...)§

Availability: build.bfg

Find files that match the glob (or list of globs) pattern, returning them as path objects. The arguments to this function are the same as for find_files.

info(message, [show_stack])§

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

Log an informational message with the specified arguments separated by spaces (as with print()). If show_stack is true, show the stack trace where the message was logged from.

InstallRoot§

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

An enumeration of root directories for Path objects, to be used during installation. Possible values are:

Path(path, [root], [destdir])§

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

Create a new path object for a given path. root may be a value in the Root or InstallRoot enumerations, or another Path object. When the root is a value in InstallRoot, you can also specify destdir; if true, this path will be prepended with $DESTDIR on platforms that support destdirs. When the root is another path, this constructor will return the same value as root.append(path).

Path.addext(ext)§

Append the extension ext to this path and return the new path. Note that ext should include the leading dot, e.g. '.txt'.

Path.append(path)§

Append a new path component to this path and return the result.

Path.basename()§

Return the basename (the last path component) of this path.

Path.ext()§

Return the extension of this path, if any; otherwise, return ''.

Path.parent()§

Return the parent of this path as a new Path object.

Path.relpath(start, [prefix], [localize])§

Return a string representing this path's location relative to a starting path start. Both paths should have the same Root. If localize is true (the default), this function will translate the path to the native form for the host platform; otherwise, it will return it untranslated (using POSIX-style separators).

Path.reroot(root)§

Return a new Path object with the same path suffix as this path, but with the path root set to root.

Path.root§

Return the Root of this path.

Path.split()§

Split this path's suffix into a list of its components.

Path.splitleaf()§

Split the leaf component of this path and return the parent and leaf. Equivalent to (path.parent(), path.basename()).

Path.suffix§

Return the suffix of this path (the portion that would be appended to the path's root.

Path.stripext([replace])§

Remove the extension from this path and replace it with an optional new extension specified in replace, returning the newly-created Path object.

path_exists(name)§

Return whether the path named name exists on the filesystem. name can be either a string or a path object.

project([name], [version], ...)§

Availability: build.bfg

Set the name and/or 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.

In addition, you can set a number of project-wide options with this function:

Root§

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

An enumeration of root directories for Path objects. Possible values are:

safe_format(fmt, ...)§

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

Safely format a string fmt, as with str.format. Unlike str.format however, this converts placeholders to string via safe_str, ensuring that the result is correctly-escaped when used in a build script.

safe_str(s)§

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

Convert an object s into a "safe" string, if possible. Safe strings are used by the build backends to correctly handle escaping special characters as needed.

submodule(path)§

Availability: build.bfg and options.bfg

Include and execute the build.bfg (or options.bfg, as appropriate) file contained in the submodule path. Within the submodule's bfg file, all paths for inputs (source files) and outputs (built files) are evaluated relative to path. This function returns a dict of all the exported objects from the submodule's bfg file.

warning(...)§

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

Log a warning with the specified arguments separated by spaces (as with print()) 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.

srcdir§

Availability: <toolchain>.bfg

Return the source directory of this project as a Path object.

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.