API Documentation

This part of the documentation contains the API reference of the functions and classes that can be used in Craftfiles.

Functions

craftr.return_()[source]

Raise a ModuleReturn exception, causing the module execution to be aborted and returning back to the parent module. Note that this function can only be called from a Craftr modules global stack frame, otherwise a RuntimeError will be raised.

craftr.expand_inputs(inputs, frameworks=None)[source]

Expands a list of inputs into a list of filenames. An input is a string (filename) or a Target object from which the Target.outputs are used. Returns a list of strings.

If frameworks is specified, it must be a list to which the frameworks of all input Target objects will be appended. The frameworks need to be expanded with expand_frameworks().

craftr.expand_frameworks(frameworks, result=None)[source]

Given a list of Framework objects, this function creates a new list that contains all objects of frameworks and additionally all objects that are listed in each of the frameworks "frameworks" key recursively. Duplicates are also elimated.

craftr.import_file(filename)[source]

Import a Craftr module by filename.

craftr.import_module(modname, globals=None, fromlist=None)[source]

Similar to importlib.import_module(), but this function can also improt contents of modname into globals. If globals is specified, the module will be directly imported into the dictionary. If fromlist list *, a wildcard import into globals will be perfromed. fromlist can also be a list of names to import.

This function always returns the root module.

craftr.debug(*args, stacklevel=1, verbosity=None, **kwargs)[source]
craftr.info(*args, stacklevel=1, **kwargs)[source]
craftr.warn(*args, stacklevel=1, **kwargs)[source]
craftr.error(*args, stacklevel=1, raise_=True, **kwargs)[source]
craftr.craftr_min_version(version_string)[source]

Ensure the current version of Craftr is at least the version specified with version_string, otherwise call error().

Session Objects

class craftr.Session(cwd=None, path=None, server_bind=None, verbosity=0, strace_depth=3, export=False)[source]

This class manages a build session and encapsulates all Craftr modules and Targets.

cwd

The original working directory from which Craftr was invoked, or the directory specified with the -p command-line option. This is different than the current working directory since Craftr changes to the build directory immediately.

env

A dictionary of environment variables, initialized as a copy of os.environ. In a Craftfile, you can use os.environ or the alias craftr.environ instead, which is more convenient that accessing session.env.

path

A list of search paths for Craftr extension modules. See Extension Modules.

modules

A dictionary of Craftr extension modules. Key is the module name without the craftr.ext. prefix.

targets

A dictionary mapping the full identifier to Target objects that have been declared during the build session. When the Session is created, a clean Target which calls ninja -t clean is always created automatically.

server

An rts.CraftrRuntimeServer object that is started when the session context is entered with magic.enter_context() and stopped when the context is exited. See on_context_enter().

server_bind

A tuple of (host, port) which the server will be bound to when it is started. Defaults to None, in which case the server is bound to the localhost on a random port.

rts_funcs

A dictionary that maps target names to functions. The function will be invoked when you call craftr-rts <func_name> (note: the Craftr Runtime Server must be running and the environment variable CRAFTR_RTS must be set). The functions added to this dictionary must accept a list of command-line arguments.

ext_importer

A ext.CraftrImporter object that handles the importing of Craftr extension modules. See Extension Modules.

var

A dictionary of variables that will be exported to the Ninja manifest.

verbosity

The logging verbosity level. Defaults to 0. Used by the logging functions debug(), info(), warn() and error().

strace_depth:

The logging functions may print a stack trace of the log call when the verbosity is high enough. This defines the depth of the stack trace. Defaults to 3.

export

This is set to True when the -e option was specified on the command-line, meaning that a Ninja manifest will be exported. Some projects eventually need to export additional files before running Ninja, for example with TargetBuilder.write_command_file().

exec_if_exists(filename)[source]

Executes filename if it exists. Used for running the Craftr environment files before the modules are loaded. Returns None if the file does not exist, a types.ModuleType object if it was executed.

on_context_enter(prev)[source]

Called when entering the Session context with magic.enter_context(). Does the following things:

Note

A copy of the original os.environ is saved and later restored in on_context_leave(). The os.environ object can not be replaced by another object, that is why we change its values in-place.

on_context_leave()[source]

Called when the context manager entered with magic.enter_context() is exited. Undos all of the stuff that on_context_enter() did and more.

  • Stop the Craftr Runtime Server
  • Restore the os.environ dictionary
  • Removes all craftr.ext. modules from sys.modules and ensures they are in Session.modules (they are expected to be put there from the ext.CraftrImporter).
start_server()[source]

Start the Craftr RTS server (see Session.server). It will automatically be stopped when the session context is exited.

update()[source]

Alias for Session.ext_importer.update().

Target Objects

class craftr.Target(command, inputs=None, outputs=None, implicit_deps=None, order_only_deps=None, foreach=False, description=None, pool=None, var=None, deps=None, depfile=None, msvc_deps_prefix=None, explicit=False, frameworks=None, meta=None, module=None, name=None)[source]

This class is a direct representation of a Ninja rule and the corresponding in- and output files. Will be rendered into a rule and one or many build statements in the Ninja manifest.

name

The name of the target. This is usually deduced from the variable the target is assigned to if no explicit name was passed to the Target constructor. Note that the actual name of the generated Ninja rule must be read from fullname.

module

The Craftr extension module this target belongs to. Defaults to the currently executed module (retrieved from the thread-local module). Can be None, but only if there is no module currently being executed.

command

A list of strings that represents the command to execute. A string can be passed to the constructor in which case it is parsed with shell.split().

inputs

A list of filenames that are listed as inputs to the target and that are substituted for $in and $in_newline during the Ninja execution. Can be None. The Target constructor expands the passed argument with expand_inputs(), thus also accepts a single filename, Target or a list with Targets and/or filenames.

outputs

A list of filenames that are listed as outputs of the target and that are substituted for $out during the Ninja execution. Can be None. The Target constructor accepts a list of filenames or a single filename for this attribute.

implicit_deps

A list of filenames that are required to build the Target, additionally to the inputs, but are not expanded by the $in variable in Ninja. See “Implicit dependencies” in the Ninja Manual.

order_only_deps

See “Order-only dependencies” in the Ninja Manual.

foreach

If this is set to True, the number of inputs must match the number of outputs. Instead of generating a single build instruction in the Ninja manifest, an instruction for each input/output pair will be created instead. Defaults to False.

description

A description of the Target. Will be added to the generated Ninja rule. Defaults to None.

pool

The name of the build pool. Defaults to None. Can be "console" for Targets that don’t actually build files but run a program. Craftr will treat Targets in that pool as if explicit is True.

deps

The mode for automatic dependency detection for C/C++ targets. See the “C/C++ Header Depenencies” section in the Ninja Manual.

depfile

A filename that contains additional dependencies.

msvc_deps_prefix

The MSVC dependencies prefix to be used for the rule.

frameworks

A list of Frameworks that are used by the Target. Rule functions that take other Targets as inputs can include this list. For example, a C++ compiler might add a Framework with libs = ['c++'] to a Target so that the Linker to which the C++ object files target is passed automatically knows to link with the c++ library.

Usually, a rule function uses the TargetBuilder (which internally uses expand_inputs()) to collect all Frameworks used in the input targets.

explicit

If True, the target will only be built by Ninja if it is explicitly specified on the command-line or if it is required by another target. Defaults to False.

meta

A dictionary of meta variables that can be set from anywhere. Usually, rule functions use this dictionary to promote additional information to the caller, for example what the actual computed output filename of a compilation is.

__lshift__(other)[source]

Shift operator to add to the list of implicit_deps.

Note

If other is or contains a Target, the targets frameworks are not added to this Target’s framework list!

fullname

The full identifier of the Target. If the Target is assigned to a module, this is the module name and the Target.name, otherwise the same as Target.name.

TargetBuilder Objects

class craftr.TargetBuilder(inputs, frameworks, kwargs, meta=None, module=None, name=None, stacklevel=1)[source]

This is a helper class to make it easy to implement rule functions that create a Target. Rule functions usually depend on inputs (being files or other Targets that can also contain additional frameworks), rule-level settings and Frameworks. The TargetBuilder takes all of this into account and prepares the data conveniently.

Parameters:
  • inputs – Inputs for the target. Processed by expand_inputs(). Use TargetBuilder.inputs instead of the argument you passed here to access the inputs. Must be a string, Target, list or None.
  • frameworks – A list of frameworks to take into account.
  • kwargs – Additional keyword-arguments that have been passed to the rule-function. These will be turned into a new Framework object. create_target() will check if all arguments of this dictionary have been taken into account and will yield a warning if not.
  • module
  • name
  • stacklevel
caller
inputs
frameworks
kwargs
options

A FrameworkJoin object that is used to read settings from the list of frameworks collected from the input Targets, the additional frameworks specified to the TargetBuilder constructor and the specified kwargs dictionary.

module
name

The name of the Target that is being built.

target_attrs

A dictonary of arguments that are set to the target after construction in create_target(). Can only set attributes that are already attributes of the Target.

meta

Meta data for the Target that is passed directly to Target.meta.

Note

If the meta parameter to the constructor is None, it will be read from the kwargs dictionary (thus inheriting the option from the called rule function).

__getitem__(key)[source]

Alias for FrameworkJoin.__getitem__().

add_framework(_TargetBuilder__fw_or_name, _TargetBuilder__fw_dict=None, **kwargs)[source]

Add or create a new Framework and add it to options and frameworks.

create_target(command, inputs=None, outputs=None, **kwargs)[source]

Create a Target and return it.

Parameters:
  • command – The command-line for the Target.
  • inputs – The inputs for the Target. If None, the TargetBuilder.inputs will be used instead.
  • outputs – THe outputs for the Target.
  • kwargs – Additional keyword arguments for the Target constructor. Make sure that none conflicts with the target dictionary.

Note

This function will yield a warning when there are any keys in the kwargs dictionary that have not been read from the options.

expand_inputs(inputs)[source]

Wrapper for expand_inputs() that will add the Frameworks extracted from the inputs to options and frameworks.

fullname

The full name of the Target that is being built.

get(key, default=None)[source]

Alias for FrameworkJoin.get().

invalid_option(option_name, option_value=<object object>, cause=None)[source]

Use this method in a rule function if you found the value of an option has an invalid option. You should raise a ValueError on a fatal error instead.

log(level, *args, stacklevel=1, **kwargs)[source]

Log function that includes the fullname.

merge(key)[source]

Alias for FrameworkJoin.merge().

target

A dictonary of arguments that are set to the target after construction in create_target(). Can only set attributes that are already attributes of the Target.

Deprecated since version Use: target_attrs instead.

write_command_file(arguments, suffix=None, always=False)[source]

Writes a file to the .cmd folder in the builder directory (ie. the current directory) that contains the command-line arguments specified in arguments. The name of that file is the name of the Target that is created with this builder. Optionally, a suffix for that file can be specified to be able to write multiple such files. Returns the filename of the generated file. If always is set to True, the file will always be created even if Session.export is set to False.

write_multicommand_file(commands, cwd=None, exit_on_error=True, suffix=None, always=False)[source]

Write a platform dependent script that executes the specified commands in order. If exit_on_error is True, the script will exit if an error is encountered while executing the commands.

Returns a list representing the command-line to run the script.

Parameters:
  • commands – A list of strings or command lists that are written into the script file.
  • cwd – Optionally, the working directory to change to when the script is executed.
  • exit_on_error – If this is True, the script will exit immediately if any command returned a non-zero exit code.
  • suffix – An optional file suffix. Note that on Windows, .cmd is added to the filename after that suffix.
  • always – If this is true, the file is always created, not only if a Ninja manifest is being exported (see Session.export).
Returns:

A tuple of two elements. The first element is a command list that represents the command used to invoke the created script. The second element is the actual command file that was written.

Framework Objects

class craftr.Framework(_Framework__fw_name=None, _Framework__init_dict=None, **kwargs)[source]

A Framework represents a set of options that are to be taken into account by compiler classes. Eg. you might create a framework that contains the additional information and options required to compile code using OpenCL and pass that to the compiler interface.

Compiler interfaces may also add items to Target.frameworks that can be taken into account by other target rules. expand_inputs() returns a list of frameworks that are being used in the inputs.

Use the FrameworkJoin class to create an object to process the data from multiple frameworks.

Parameters:
  • __fw_name – The name of the Framework. If omitted, the assigned name of the calling module will be used.
  • __init_dict – A dictionary to initialize the Framework with.
  • kwargs – Additional key/value pairs for the Framework.

FrameworkJoin Objects

class craftr.FrameworkJoin(*frameworks)[source]

This class is used to process a set of Frameworks and retreive relevant information from it. For some options, you might want to read the first value that is specified in any of the frameworks, for another you may want to create a list of all values in the frameworks. This is what the FrameworkJoin allows you to do.

Note

The FrameworkJoin does not use expand_frameworks() but uses the list of frameworks passed to the constructor as-is.

>>> fw1 = Framework('fw2', defines=['DEBUG'])
>>> fw2 = Framework(defines=['DO_STUFF'])
>>> print(fw2.name)
'fw2'
>>> FrameworkJoin(fw1, fw2).merge('defines')
['DEBUG', 'DO_STUFF']
used_keys

A set of keys that have been accessed via __getitem__(), get() and merge().

frameworks

The list of Framework objects.

__iadd__(frameworks)[source]
get(key, default=None)[source]

Get the first available value of key from the frameworks.

keys()[source]

Returns a set of all keys in all frameworks.

merge(key)[source]

Merge all values of key in the frameworks into one list, assuming that every key is a non-string sequence and can be appended to a list.

The path module

craftr.path.addprefix(subject, prefix)[source]

Given a filename, this function will prepend the specified prefix to the base of the filename and return it. filename may be an iterable other than a string in which case the function is applied recursively and a list is being returned instead of a string.

__Important__: This is not the directy equivalent of addsuffix() as it considered subject to be a filename and appends the prefix only to the files base name.

craftr.path.addsuffix(subject, suffix, replace=False)[source]

Given a string, this function appends suffix to the end of the string and returns the new string.

subject may be an iterable other than a string in which case the function will be applied recursively on all its items and a list is being returned instead of a string.

If the replace argument is True, the suffix will be replaced instead of being just appended. Make sure to include a period in the suffix parameter value.

craftr.path.autoglob(path, parent=None)[source]

Returns glob(path) if path is actually a glob-style pattern. If it is not, it will return [path] as is, not checking wether it exists or not.

craftr.path.commonpath(paths)[source]

Returns the longest sub-path of each pathname in the sequence paths. Raises ValueError if paths is empty or contains both relative and absolute pathnames. If there is only one item in paths, the parent directory is returned.

craftr.path.get_long_path_name(path)[source]

On Windows, this function returns the correct capitalization for path. On all other systems, this returns path unchanged.

craftr.path.glob(*patterns, exclude=None, parent=None)[source]

Wrapper for glob2.glob() that accepts an arbitrary number of patterns and matches them. The paths are normalized with normpath(). If called from within a module, relative patterns are assumed relative to the modules parent directory.

If exclude is specified, it must be a string or a list of strings that is/contains glob patterns or filenames to be removed from the result before returning.

craftr.path.isglob(path)[source]

Returns True if path is a glob-able pattern, False if not.

craftr.path.iter_tree(dirname, depth=1)[source]

Iterates over all files in dirname and its sub-directories up to the specified depth. If dirname is a list, this scheme will be applied for all items in the list.

craftr.path.listdir(path, abs=True)[source]

This version of os.listdir yields absolute paths.

craftr.path.local(path)[source]

Can only be called from a module context. Returns path normalized, assumed relative to the current modules project directory.

craftr.path.makedirs(path)[source]

Simple os.makedirs() clone that does not error if path is already an existing directory.

craftr.path.move(filename, basedir, newbase)[source]

Given a filename and two directory names, this function generates a new filename which is constructed from the relative path of the filename and the first directory and the joint of this relative path with the second directory.

This is useful to generate a new filename in a different directory based on another. Craftr uses this function to generate object filenames.

Example:

>>> move('src/main.c', 'src', 'build/obj')
build/obj/main.c

path may be an iterable other than a string in which case the function is applied recursively to all its items and a list is returned instead of a string.

craftr.path.normpath(path, parent_dir=None, abs=True)[source]

Normalizes a filesystem path. Also expands user variables. If a parent_dir is specified, a relative path is considered relative to that directory and converted to an absolute path. The default parent directory is the current working directory.

path may be an iterable other than a string in which case the function is applied recursively to all its items and a list is returned instead of a string.

If abs is True, the path is returned as an absolute path always, otherwise the path is returned in its original structure.

craftr.path.relpath(path, start='.', only_sub=False)[source]

Like the original os.path.relpath() function, but with the only_sub parameter. If only_sub is True and path is not a subpath of start, the path is returned unchanged.

craftr.path.rmvsuffix(subject)[source]

Given a filename, this function removes the the suffix of the filename and returns it. If the filename had no suffix to begin with, it is returned unchanged.

subject may be an iterable other than a string in which case the function is applied recursively to its items and a list is returned instead of a string.

craftr.path.setsuffix(subject, suffix)[source]

Remove the existing suffix from subject and add suffix instead. The suffix must contain the dot at the beginning.

craftr.path.silent_remove(filename)[source]

Remove the file filename if it exists and be silent if it does not. Returns True if the file was removed, False if it did not exist. Raises an error in all other cases.

craftr.path.split_path(path)[source]

Splits path into a list of its parts.

The shell module

This module is similar to the subprocess.run() interface that is available since Python 3.5 but is a bit customized so that it works better with Craftr.

craftr.shell.quote(s)[source]

Enhanced implementation for Windows systems as the original shlex.quote() function uses single-quotes on Windows which can lead to problems.

craftr.shell.run(cmd, *, stdin=None, input=None, stdout=None, stderr=None, shell=False, timeout=None, check=False, cwd=None, encoding='utf-8')[source]

Run the process with the specified cmd. If cmd is a list of commands and shell is True, the list will be automatically converted to a properly escaped string for the shell to execute.

Raises:
CalledProcessError: If check is True and the process exited with
a non-zero exit-code.
TimeoutExpired: If timeout was specified and the process did not
finish before the timeout expires.
OSError: For some OS-level error, eg. if the program could not be
found.
craftr.shell.pipe(*args, merge=True, **kwargs)[source]

Like run(), but pipes stdout and stderr to a buffer instead of directing them to the current standard out and error files. If merge is True, stderr will be merged into stdout.

The utils module

craftr.utils.append_path(pth)[source]

Append pth to the PATH environment variable.

craftr.utils.find_program(name)[source]

Finds the program name in the PATH and returns the full absolute path to it. On Windows, this also takes the PATHEXT variable into account.

Arguments:
name: The name of the program to find.
Returns:
str: The absolute path to the program.
Raises:
FileNotFoundError: If the program could not be found in the PATH.
craftr.utils.flatten(iterable)[source]

Given an iterable that in turn yields an iterable, this function flattens the nested iterables into a single iteration.

Performs re.search() and returns a list of the captured groups, including the complete matched string as the first group. If the regex search was unsuccessful, a list with that many items containing None is returned.

craftr.utils.prepend_path(pth)[source]

Prepend pth to the PATH environment variable.

craftr.utils.slotobject(cls_name, slots)[source]

Similar to collections.namedtuple(), this function creates a type object with the attributes specified via the slots (a string or list of strings) only the type does not inherit from tuple but insead from object. Its attributes can actually be changed. Instances of the type can not act as tuples.

>>> from craftr.utils import slotobject
>>> File = slotobject('File', 'name arc_name')
>>> File('foo', 'subdir/foo')
<File name='foo' arc_name='subdir/foo'>
class craftr.utils.tempfile(suffix='', prefix='tmp', dir=None, text=False)[source]

A better temporary file class where the close() function does not delete the file but only __exit__() does.

craftr.utils.unique(iterable)[source]

Create a list of items in iterable without duplicate, preserving the order of the elements where it first appeared.