`ronin`¶

`ronin.cli`¶

ronin.cli.cli(*projects)¶

Delegates control to the Rōnin CLI on one or more projects.

Note that the process is expected to exit after running the CLI, so this should only normally be used as the last call of your build script.

Parameters:	projects ([`Project`]) – projects

`ronin.contexts`¶

class ronin.contexts.Context(parent=None, immutable=False)¶

Bases: object

Keeps track of environmental and user configuration properties per run.

Designed to be attached to a single thread. Supports nesting contexts within the thread: a child context will return its parent’s properties if it does not define them itself.

If the context is immutable it will raise ImmutableContextException if you try to modify any of the properties.

Parameters:	parent (`Context`) – parent context or None immutable (bool) – set to True to make immutable

append_to_import_path(name, default=None)¶

Convenience method to append a property in the context, if it exists, to sys.path.

Parameters:	name (str) – name in the format “key.property” default – default value

fallback(value, name, default=None)¶

If the value is not None, returns it. Otherwise works identically to get().

Parameters:	value – value name (str) – name in the format “key.property” default – default value
Returns:	value, default, or None

get(name, default=None)¶

Gets a value from the context or default if undefined.

Values of any type can be stored in the context.

Note that if the value is defined and is None, then None is returned and not default.

Parameters:	name (str) – name in the format “ns.k” default – default value
Returns:	value, default, or None

exception ronin.contexts.ContextException(message=None)¶

Bases: exceptions.Exception

Base class for context exceptions.

exception ronin.contexts.ImmutableContextException(message=None)¶

Bases: ronin.contexts.ContextException

Attempted to modify an immutable context.

exception ronin.contexts.IncorrectUseOfContextException(message=None)¶

Bases: ronin.contexts.ContextException

Attempted to access a namespace instead of a property.

exception ronin.contexts.NoContextException(message=None)¶

Bases: ronin.contexts.ContextException

Attempted to access the current context but there is none.

exception ronin.contexts.NotInContextException(message=None)¶

Bases: ronin.contexts.ContextException

Attempted to access a property that is not in the context.

ronin.contexts.configure_context(root_path=None, input_path_relative=None, output_path_relative=None, binary_path_relative=None, object_path_relative=None, source_path_relative=None, name=None, frame=1)¶

Configures the current context for builds.

Parameters:

root_path (str or FunctionType) – the root of the input/output directory structure; defaults to the directory in which the calling script resides
input_path_relative (str or FunctionType) – the default input path relative to the root; defaults to the root itself
output_path_relative (str or FunctionType) – the default base output path relative to the root; defaults to ‘build’
binary_path_relative (str or FunctionType) – the default binary output base path relative to the output path; defaults to ‘bin’
object_path_relative (str or FunctionType) – the default object output base path relative to the output path; defaults to ‘obj’
source_path_relative (str or FunctionType) – the default source output base path relative to the output path; defaults to ‘src’
name (str or FunctionType) – optional name to use for descriptions
frame (int) – how many call frames to wind back to in order to find the calling script

ronin.contexts.current_context(immutable=True)¶

Returns the current context if there is one, otherwise raises NoContextException.

By default, the context will be treated as immutable.

Parameters:	immutable (bool) – set to False in order to allow changes to the context
Returns:	current context
Return type:	`Context`

ronin.contexts.new_child_context()¶

Creates a new context.

If there already is a context in this thread, our new context will be a child of that context.

Returns:	new child context
Return type:	`Context`

ronin.contexts.new_context(**kwargs)¶

Creates a new context and calls configure_context() on it. If there already is a context in this thread, our new context will be a child of that context.

Parameters:

root_path (str or FunctionType) – the root of the input/output directory structure; defaults to the directory in which the calling script resides
input_path_relative (str or FunctionType) – the default input path relative to the root; defaults to the root itself
output_path_relative (str or FunctionType) – the default base output path relative to the root; defaults to ‘build’
binary_path_relative (str or FunctionType) – the default binary output base path relative to the output path; defaults to ‘bin’
object_path_relative (str or FunctionType) – the default object output base path relative to the output path; defaults to ‘obj’
source_path_relative (str or FunctionType) – the default source output base path relative to the output path; defaults to ‘src’
name (str or FunctionType) – optional name to use for descriptions
frame (int) – how many call frames to wind back to in order to find the calling script

`ronin.executors`¶

class ronin.executors.Executor¶

Bases: object

Base class for executors.

Variables:

command (str or FunctionType) – command
command_types ([str]) – command types supported (used by extensions)
output_extension (str or FunctionType) – when calculating outputs, change extension to this
output_prefix (str or FunctionType) – when calculating outputs, prefix this to filename
hooks ([FunctionType]) – called when generating the Ninja file

add_input(value)¶

command_as_str(argument_filter=None)¶

write_command(f, argument_filter=None)¶

class ronin.executors.ExecutorWithArguments¶

Bases: ronin.executors.Executor

Base class for executors with arguments.

add_argument(*value)¶

add_argument_unfiltered(*value)¶

remove_argument(*value)¶

remove_argument_unfiltered(*value)¶

write_command(f, argument_filter=None)¶

`ronin.extensions`¶

class ronin.extensions.ExplicitExtension(inputs=None, include_paths=None, defines=None, library_paths=None, libraries=None)¶

Bases: ronin.extensions.Extension

An extension with explicitly stated data to support gcc-like executors.

Parameters:

inputs ([str or FunctionType]) – input paths; note that these should be absolute paths
include_paths ([str or FunctionType]) – include paths; note that these should be absolute paths
defines ([(str or FunctionType, str or FunctionType)]) – defines in a (name, value) tuple format; use None for value if the define does not have a value
library_paths ([str or FunctionType]) – include paths; note that these should be absolute paths
libraries ([str or FunctionType]) – library names

apply_to_executor_gcc_compile(executor)¶

apply_to_executor_gcc_link(executor)¶

apply_to_phase(phase)¶

class ronin.extensions.Extension¶

Bases: object

Base class for extensions.

Extensions can nest child extensions (and so can they).

Variables:	extensions – child extensions

apply_to_executor(executor)¶

apply_to_phase(phase)¶

class ronin.extensions.OutputsExtension(project, phase_name)¶

Bases: ronin.extensions.Extension

An extension that pulls in outputs from another build phase.

Parameters:	project (Project) – project phase_name (str or FunctionType) – phase name in project

apply_to_executor_gcc_link(executor)¶

`ronin.ninja`¶

class ronin.ninja.NinjaFile(project, command=None, encoding=None, file_name=None, columns=None, strict=None)¶

Bases: object

Manages a Ninja build system file.

Parameters:

project (Project) – project
command (str or FunctionType) – Ninja command; defaults to the context’s ninja.command
encoding (str or FunctionType) – Ninja file encoding; defaults to the context’s ninja.encoding
file_name (str or FunctionType) – Ninja filename (without “.ninja” extension); defaults to the context’s ninja.file_name
columns (int) – number of columns in Ninja file; defaults to the context’s ninja.columns
strict (bool) – strict column mode; defaults to the context’s ninja.strict

build()¶

Calls generate() and runs Ninja as a subprocess in build mode.

Returns:	subprocess exit code
Return type:	int

clean()¶

Runs Ninja as a subprocess in clean mode, and then deletes the Ninja file if successful. Also makes sure to clean any temporary state for the project in the context.

Returns:	subprocess exit code
Return type:	int

command¶

delegate()¶: Calls build() and then exits the process with the correct exit code.

encoding¶

file_name¶

The Ninja file name, not including the path. The file_name if set, or else the project’s file_name, or else ninja.file_name in the context.

Type:	`str`

generate()¶: Writes the Ninja file to path, overwriting existing contents and making sure to make parent directories.

path¶

Full path to the Ninja file. A join of the project’s output_path and file_name.

Type:	`str`

remove()¶: Deletes the Ninja file at path if it exists.

write(f)¶

Writes the Nina file content.

Parameters:	f (file-like) – where to write

ronin.ninja.configure_ninja(ninja_command=None, encoding=None, file_name=None, columns=None, strict=None)¶

Parameters:

ninja_command (str or FunctionType) – ninja command; defaults to “ninja”
encoding (str or FunctionType) – Ninja file encoding; defaults to “utf-8”
file_name (str or FunctionType) – Ninja filename (without “.ninja” extension); defaults to “build”
columns (int) – number of columns in Ninja file; defaults to 100
strict (bool) – strict column mode; defaults to False

ronin.ninja.escape(value)¶

Escapes special characters for literal inclusion in a Ninja file.

Parameters:	value (str or FunctionType) – literal value to escape
Returns:	escaped value
Return type:	str

ronin.ninja.pathify(value)¶

Escapes special characters for inclusion in a Ninja file where paths are expected.

Parameters:	value (str or FunctionType) – path value to escape
Returns:	escaped value
Return type:	str

`ronin.phases`¶

class ronin.phases.Output(path, the_file)¶

Bases: object

Phase output.

Parameters:	path (str) – absolute path the_file (str) – file name

class ronin.phases.Phase(project=None, name=None, executor=None, description=None, inputs=None, inputs_from=None, input_path=None, input_path_relative=None, extensions=None, output=None, output_path=None, output_path_relative=None, output_strip_prefix=None, output_strip_prefix_from=None, output_transform=None, run_output=False, run_command=None, rebuild_on=None, rebuild_on_from=None, build_if=None, build_if_from=None)¶

Bases: object

A build phase within a project (see Project).

Each phase is equivalent to a single rule statement within a Ninja file together with the build statements that make use of it. Phases can be interrelated in complex ways: indeed, this feature is exactly what makes Rōnin useful (and writing Ninja files by hand difficult).

Phases can work in either “multi-output” or “single-output” mode, the latter triggered by setting the output parameter. The former is often used for incremental compilation, the latter often used for linking various outputs to a single binary.

A phase must be set with a ronin.executors.Executor to be useful. It was an architectural to separate the two classes in order to make it easier to extend code in each direction, however in the data model they are always joined.

Another important part of the architecture is ronin.extensions.Extension. This allows a kind of “live mix-in” for both phases and executors without having to extend those classes, for example to inject inputs and/or executor arguments.

As a convenience, if you set the project and name init arguments, then the phase will automatically be added to that project. You can do this manually instead.

Variables:

vars ({str: FunctionType or str}) – custom Ninja variables
hooks ([FunctionType]) – called when generating the Ninja file

Parameters:

project (Project) – project to which this phase will be added (if set must also set name)
name (str or FunctionType) – name in project to which this phase will be added (if set must also set project)
executor (Executor) – executor
description (str or FunctionType) – Ninja description; may include Ninja variables, such as $out; defaults to “[phase name] $out”
inputs ([str or FunctionType]) – input paths; note that these should be absolute paths
inputs_from ([str or FunctionType or Phase]) – names or instances of other phases in the project, the outputs of which we add to this phase’s inputs
extensions (Extension) – extensions
output (str or FunctionType) – specifies that the phase has a single output; note that actual path of the output will be based on this parameter but not identical to it, for example “lib” might be added as a prefix, “.dll” as an extension, etc., according to the executor and/or project variant
output_path (str or FunctionType) – override project’s output_path; otherwise will be based on the executor’s output_type
output_path_relative (str or FunctionType) – joined to the context’s paths.output
output_strip_prefix (str or FunctionType) – stripped from outputs if they begin with this
output_strip_prefix_from (str or FunctionType or Phase) – name or instance of other phase in project, from which the output path is used as this phase’s output_strip_prefix
output_transform (FunctionType) – called on all outputs
run_output (int) – set to non-zero to run the output after a successful build in sequence
run_command ([str or FunctionType]) – arguments for the run command; use “{output}” to insert output
rebuild_on ([str or FunctionType]) – similar to inputs but used as “implicit dependencies” in Ninja (single pipe), meaning that the build will be re-triggered when these files change
rebuild_on_from ([str or FunctionType or Phase]) – names or instances of other phases in the project, the outputs of which we add to this phase’s rebuild_on
build_if ([str or FunctionType]) – similar to inputs but used as “order dependencies” in Ninja (double pipe), meaning that the build will be triggered only after these files are built
build_if_from ([str or FunctionType or Phase]) – names or instances of other phases in the project, the outputs of which we add to this phase’s build_if

apply()¶: Applies all extensions and hooks to this phase.

command_as_str(argument_filter=None)¶

Applies all extensions to the executor and calls its command_as_str.

Returns:	command as string
Return type:	str

get_outputs(inputs)¶

Calculates the outputs for this phase depending on the inputs, applying output prefix and extension from the executor and finally the calling the output_transform function.

Parameters:	inputs ([`str`]) – inputs
Returns:	(True if “single-output”, outputs); length of `outputs` will always be 1 in “single-output” mode, otherwise it will be the same length as `inputs`
Return type:	(`bool`, [`Output`])

input_path¶

The set input_path, or the context’s paths.input joined to input_path_relative, or the project’s input_path.

Type:	`str`

output_path¶

The set output_path, or the context’s paths.output joined to output_path_relative, or the project’s output_path for the executor’s output_type.

Type:	`str`

`ronin.projects`¶

class ronin.projects.Project(name, version=None, variant=None, input_path=None, input_path_relative=None, output_path=None, output_path_relative=None, file_name=None, phases=None)¶

Bases: object

A container for an interrelated set of build phase (see Phase).

Every project is equivalent to a single Ninja file. Projects by default inherit properties from the current context, but can override any of them.

A Rōnin build script can in turn consist of any number of projects, though likely would require at least one to do something useful. Actually, due the dynamic nature of Rōnin build scripts, an entirely different number and nature of projects may be created by each run of a script.

After setting up projects, they are usually handed over to cli(). Though, you can also use the NinjaFile class directly instead.

Variables:

phases ({str: Phase}) – phases
hooks ([FunctionType]) – called when generating the Ninja file
run ({int: [str or FunctionType]}) – executed in order after a successful build

Parameters:

name (str or FunctionType) – project name
version (str or FunctionType) – project version
variant (str or FunctionType) – override project variant; defaults to the context’s projects.default_variant or host_platform()
input_path (str or FunctionType) – override input path; defaults to the context’s paths.input_path
input_path_relative (str or FunctionType) – override input path (relative)
output_path (str or FunctionType) – override output path generation
output_path_relative (str or FunctionType) – override output path generation (relative)
file_name (str or FunctionType) – override Ninja file name; defaults to the context’s ninja.file_name
phases ({str: Phase}) – project phases

executable_extension¶

The executable extension for the variant.

See: platform_executable_extension().

Type:	`str`

get_output_path(output_type)¶

The context’s paths.[output_type] or project’s output_path joined to the context’s paths.[output_type]_relative.

Parameters:	output_type (str or FunctionType) – output type
Returns:	output path for output the type
Return type:	str

get_phase_for(value, attr)¶

Gets a phase and its name in the project. The argument is a phase name or a phase in the project.

Parameters:	value (str or FunctionType or Phase) – phase name or phase attr (str) – name of attribute from which the value was taken (for error messages)
Returns:	phase name, phase
Return type:	(`str`, `Phase`)
Raises:	ValueError – if phase not found in project

get_phase_name(phase)¶

The name of the phase if it’s in the project.

Parameters:	phase (Phase) – phase
Returns:	phase name or `None`
Return type:	str

input_path¶

The set input_path, or the context’s paths.input.

Type:	`str`

is_linux¶

True if variant is a Linux platform.

Type:	`bool`

is_windows¶

True if variant is a Windows platform.

Type:	`bool`

output_path¶

The set output_path, or the context’s paths.output joined to the project’s output_path_relative and variant.

Type:	`str`

shared_library_extension¶

The shared library extension for the variant.

See: platform_shared_library_extension().

Type:	`str`

shared_library_prefix¶

The shared library prefix for the variant.

See: platform_shared_library_prefix().

Type:	`str`

variant¶

Project variant.

Type:	`str`