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 aRuntimeError
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 theTarget.outputs
are used. Returns a list of strings.If frameworks is specified, it must be a
list
to which the frameworks of all inputTarget
objects will be appended. The frameworks need to be expanded withexpand_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_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.
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 useos.environ
or the aliascraftr.environ
instead, which is more convenient that accessingsession.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, aclean
Target which callsninja -t clean
is always created automatically.
-
server
¶ An
rts.CraftrRuntimeServer
object that is started when the session context is entered withmagic.enter_context()
and stopped when the context is exited. Seeon_context_enter()
.
-
server_bind
¶ A tuple of
(host, port)
which theserver
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 variableCRAFTR_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()
anderror()
.
-
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 withTargetBuilder.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:- Sets up the :data`os.environ` with the values from
Session.env
- Adds the
Session.ext_importer
tosys.meta_path
- Starts the Craftr Runtime Server (
Session.server
) and sets theCRAFTR_RTS
environment variable
Note
A copy of the original
os.environ
is saved and later restored inon_context_leave()
. Theos.environ
object can not be replaced by another object, that is why we change its values in-place.- Sets up the :data`os.environ` with the values from
-
on_context_leave
()[source]¶ Called when the context manager entered with
magic.enter_context()
is exited. Undos all of the stuff thaton_context_enter()
did and more.- Stop the Craftr Runtime Server
- Restore the
os.environ
dictionary - Removes all
craftr.ext.
modules fromsys.modules
and ensures they are inSession.modules
(they are expected to be put there from theext.CraftrImporter
).
-
start_server
()[source]¶ Start the Craftr RTS server (see
Session.server
). It will automatically be stopped when the session context is exited.
-
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 manybuild
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 fromfullname
.
-
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. TheTarget
constructor expands the passed argument withexpand_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. TheTarget
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 ofoutputs
. Instead of generating a singlebuild
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 ifexplicit
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 withlibs = ['c++']
to a Target so that the Linker to which the C++ object files target is passed automatically knows to link with thec++
library.Usually, a rule function uses the
TargetBuilder
(which internally usesexpand_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 theTarget.name
, otherwise the same asTarget.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 andFrameworks
. The TargetBuilder takes all of this into account and prepares the data conveniently.Parameters: - inputs – Inputs for the target. Processed by
expand_inputs()
. UseTargetBuilder.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 theTargetBuilder
constructor and the specifiedkwargs
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 theTarget
.
-
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).
-
add_framework
(_TargetBuilder__fw_or_name, _TargetBuilder__fw_dict=None, **kwargs)[source]¶ Add or create a new Framework and add it to
options
andframeworks
.
-
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.
-
expand_inputs
(inputs)[source]¶ Wrapper for
expand_inputs()
that will add the Frameworks extracted from the inputs tooptions
andframeworks
.
-
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.
-
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 theTarget
.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.
- inputs – Inputs for the target. Processed by
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 useexpand_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']
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.
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.
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.
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.
The utils
module¶
-
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.
-
craftr.utils.
gre_search
(pattern, subject, mode=0)[source]¶ 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.
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 fromtuple
but insead fromobject
. 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'>