This page lists the symbols that bt exports. If the build script is run by the executable, they are made accessible to the build script automatically. Mutable variables can be accessed through the module bt.

If a name is not listed here, then it should be assumed to be internal.

bt.bt

bt’s main module.

bt.debug = False

Whether to print debugging information. Currently only names of tasks before they run are printed.

bt.FileSpecifier

A path or collection of paths.

alias of str | Iterable[FileSpecifier] | Callable[[], FileSpecifier]

bt.Runnable

A function that can be called without arguments.

alias of Callable[[], Any]

class bt.Arguments(*arguments)

Arguments is a list derivative that stores a full or partial command line.

Only None, strings and Iterables may be added; None is discarded and every Iterable is flattened.

source = ["main.c"]
exe = "foo"
options = "-Ofast -std=c2x"
command = Arguments("gcc", source, "-o", exe, options, parameter("o"))
print(command) # gcc main.c -o foo -Ofast -std=c2x
print(command.split()) # ['gcc', 'main.c', '-o', 'foo', '-Ofast', '-std=c2x']

__str__()

Return all elements joined by spaces.

split()

Split this argument list’s __str__ into a list.

class bt.Files(*files)

bt.mkdir(path: str, new=False)

Make a directory with the given path, also making its ancestors if necessary. If new and the path already exists, then raise an exception.

bt.outdent(text: str) → str

Outdent text and strip leading and trailing whitespace. If the last line contains only whitespace, then include a trailing newline.

bt.parameter(name: str, default=None, require=False) → str

Return the value of the parameter name if it’s set or else default. If it’s unset and not require, then print an error message and exit.

bt.read(file: str) → str

open, read and close the file and return its contents.

bt.require(version: int)

Exit with an error message if the version of bt is older than version.

bt.rm(path: str)

Remove the specified path recursively if it exists.

bt.sh(*commandLine: str | Arguments | Iterable | None, shell=True, text=True, **kwargs) → CompletedProcess[str]

Wrap subprocess.run with the defaults shell = True and text = True. Convert commandLine into an Arguments and then a string.

bt.shout(*args, capture_output=True, **kwargs) → str

Wrap sh with capture_output = True and return the command’s stdout.

bt.task(*dependencies: str | Task | Callable[[], Any], name: str | None = None, default=False, export=True, pure=False, source: str | Iterable[FileSpecifier] | Callable[[], FileSpecifier] = [], input: Any | None = None, output: str | Iterable[FileSpecifier] | Callable[[], FileSpecifier] = []) → Task

Declare a task named name to be run at most once from the command line or as a dependency. Each dependency will run before the task.

If default, then the task will run when no tasks are specified in the command line.

If export, then it will be available in the command line.

If pure, then dependent tasks may be skipped even if this task runs.

If source or output is not an empty list or input is not None, then caching will be enabled.

source and output will be searched for files recursively. Callables found therein will be converted into their results.

source may contain glob patterns. The nonexistence of an exact file in source is an error.

All routines (as determined by inspect.isroutine) found recursively in input will be evaluated just before the task runs.

The task will be skipped if - caching is enabled - no task dependency runs - input and the source files’ mtimes are the same values from the task’s previous run - and all output files exist.

bt.write(file: str, contents: str)

open, write contents to and close the file.