mozbuild.configure package¶

Submodules¶

mozbuild.configure.check_debug_ranges module¶

mozbuild.configure.check_debug_ranges.get_range_for(compilation_unit, debug_info)¶: Returns the range offset for a given compilation unit in a given debug_info.

mozbuild.configure.check_debug_ranges.get_range_length(range, debug_ranges)¶: Returns the number of items in the range starting at the given offset.

mozbuild.configure.check_debug_ranges.main(bin, compilation_unit)¶

mozbuild.configure.constants module¶

mozbuild.configure.help module¶

class mozbuild.configure.help.HelpFormatter(argv0)¶

Bases: object

RE_FORMAT = re.compile('{([^|}]*)\\|([^|}]*)}')¶

add(option)¶

format_help(option)¶

format_options_by_category(options_by_category)¶

usage(out)¶

mozbuild.configure.lint module¶

class mozbuild.configure.lint.LintSandbox(environ=None, argv=None, stdout=None, stderr=None)¶

Bases: mozbuild.configure.ConfigureSandbox

imports_impl(_import, _from=None, _as=None)¶: Implementation of @imports. This decorator imports the given _import from the given _from module optionally under a different _as name. The options correspond to the various forms for the import builtin.

@imports(‘sys’) @imports(_from=’mozpack’, _import=’path’, _as=’mozpath’)

option_impl(*args, **kwargs)¶: Implementation of option() This function creates and returns an Option() object, passing it the resolved arguments (uses the result of functions when functions are passed). In most cases, the result of this function is not expected to be used. Command line argument/environment variable parsing for this Option is handled here.

run(path=None)¶: Executes the given file within the sandbox, as well as everything pending from any other included file, and ensure the overall consistency of the executed script(s).

unwrap(func)¶

wraps(func)¶

mozbuild.configure.options module¶

class mozbuild.configure.options.CommandLineHelper(environ=environ({'TERM_PROGRAM': 'Apple_Terminal', 'TERM': 'xterm-256color', 'SHELL': '/bin/zsh', 'TMPDIR': '/var/folders/yt/2kyz65ds4qv_65pqwdb40x8h0000gn/T/', 'TERM_PROGRAM_VERSION': '440', 'TERM_SESSION_ID': '44D43395-B15B-4C30-B407-FB0B82511DC0', 'USER': 'davidp', 'SSH_AUTH_SOCK': '/private/tmp/com.apple.launchd.OpTkbPBPcK/Listeners', 'PATH': '/Users/davidp/moz/mozilla-unified/obj-x86_64-apple-darwin20.6.0/docs/html/_venv/common/bin:/Users/davidp/moz/mozilla-unified/obj-x86_64-apple-darwin20.6.0/_virtualenvs/docs/bin:/Users/davidp/moz/mozilla-unified/node_modules/.bin:/Users/davidp/.mozbuild/node/bin:/Users/davidp/.mozbuild/srcdirs/mozilla-unified-5358a99862ea/_virtualenvs/mach/bin:/Users/davidp/bin:/Users/davidp/.cargo/bin:/Users/davidp/bin:/Users/davidp/.cargo/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin', 'LaunchInstanceID': '0489829A-0BCB-4917-9DE6-08D311C69421', '__CFBundleIdentifier': 'com.apple.Terminal', 'PWD': '/Users/davidp/moz/mozilla-unified', 'LANG': 'en_US.UTF-8', 'XPC_FLAGS': '0x0', 'XPC_SERVICE_NAME': '0', 'HOME': '/Users/davidp', 'SHLVL': '1', 'LOGNAME': 'davidp', 'SECURITYSESSIONID': '186a8', '__CF_USER_TEXT_ENCODING': '0x1F5:0x0:0x0', 'PLAT': 'macosx-11-x86_64', 'VIRTUAL_ENV': '/Users/davidp/moz/mozilla-unified/obj-x86_64-apple-darwin20.6.0/docs/html/_venv/common', 'MACH_MAIN_PID': '4015', 'MACH_STDOUT_ISATTY': '1', 'DOCUTILSCONFIG': '/Users/davidp/moz/mozilla-unified/docs/docutils.conf'}), argv=['./mach', 'doc'])¶

Bases: object

Helper class to handle the various ways options can be given either on the command line of through the environment.

For instance, an Option(‘–foo’, env=’FOO’) can be passed as –foo on the command line, or as FOO=1 in the environment or on the command line.

If multiple variants are given, command line is prefered over the environment, and if different values are given on the command line, the last one wins. (This mimicks the behavior of autoconf, avoiding to break existing mozconfigs using valid options in weird ways)

Extra options can be added afterwards through API calls. For those, conflicting values will raise an exception.

add(arg, origin='command-line', args=None)¶

handle(option)¶: Return the OptionValue corresponding to the given Option instance, depending on the command line, environment, and extra arguments, and the actual option or variable that set it. Only works once for a given Option.

exception mozbuild.configure.options.ConflictingOptionError(message, **format_data)¶: Bases: mozbuild.configure.options.InvalidOptionError

exception mozbuild.configure.options.InvalidOptionError¶: Bases: Exception

class mozbuild.configure.options.NegativeOptionValue(origin='unknown')¶

Bases: mozbuild.configure.options.OptionValue

Represents the value for a negative option (–disable/–without)

This is effectively an empty tuple with a origin attribute.

class mozbuild.configure.options.Option(name=None, env=None, nargs=None, default=None, possible_origins=None, choices=None, category=None, help=None, define_depth=0)¶

Bases: object

Represents a configure option

A configure option can be a command line flag or an environment variable or both.

name is the full command line flag (e.g. –enable-foo).
env is the environment variable name (e.g. ENV)
nargs is the number of arguments the option may take. It can be a number or the special values ‘?’ (0 or 1), ‘*’ (0 or more), or ‘+’ (1 or more).
default can be used to give a default value to the option. When the name of the option starts with ‘–enable-‘ or ‘–with-‘, the implied default is an empty PositiveOptionValue. When it starts with ‘–disable-‘ or ‘–without-‘, the implied default is a NegativeOptionValue.
choices restricts the set of values that can be given to the option.
help is the option description for use in the –help output.
possible_origins is a tuple of strings that are origins accepted for this option. Example origins are ‘mozconfig’, ‘implied’, and ‘environment’.
category is a human-readable string used only for categorizing command- line options when displaying the output of configure –help. If not supplied, the script will attempt to infer an appropriate category based on the name of the file where the option was defined. If supplied it must be in the _ALL_CATEGORIES list above.
define_depth should generally only be used by templates that are used to instantiate an option indirectly. Set this to a positive integer to force the script to look into a deeper stack frame when inferring the category.

category¶

choices¶

default¶

define_depth¶

env¶

get_value(option=None, origin='unknown')¶

Given a full command line option (e.g. –enable-foo=bar) or a variable assignment (FOO=bar), returns the corresponding OptionValue.

Note: variable assignments can come from either the environment or from the command line (e.g. ../configure CFLAGS=-O2)

help¶

id¶

property maxargs¶

property minargs¶

name¶

nargs¶

property option¶

possible_origins¶

prefix¶

static split_option(option)¶

Split a flag or variable into a prefix, a name and values

Variables come in the form NAME=values (no prefix). Flags come in the form –name=values or –prefix-name=values where prefix is one of ‘with’, ‘without’, ‘enable’ or ‘disable’. The ‘=values’ part is optional. Values are separated with commas.

class mozbuild.configure.options.OptionValue(values=(), origin='unknown')¶

Bases: tuple

Represents the value of a configure option.

This class is not meant to be used directly. Use its subclasses instead.

The origin attribute holds where the option comes from (e.g. environment, command line, or default)

format(option)¶

static from_(value)¶

class mozbuild.configure.options.PositiveOptionValue(values=(), origin='unknown')¶

Bases: mozbuild.configure.options.OptionValue

Represents the value for a positive option (–enable/–with/–foo) in the form of a tuple for when values are given to the option (in the form –option=value[,value2…].

mozbuild.configure.options.istupleofstrings(obj)¶

mozbuild.configure.util module¶

class mozbuild.configure.util.ConfigureOutputHandler(stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, stderr=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, maxlen=20)¶

Bases: logging.Handler

A logging handler class that sends info messages to stdout and other messages to stderr.

Messages sent to stdout are not formatted with the attached Formatter. Additionally, if they end with ‘… ‘, no newline character is printed, making the next message printed follow the ‘… ‘.

Only messages above log level INFO (included) are logged.

Messages below that level can be kept until an ERROR message is received, at which point the last maxlen accumulated messages below INFO are printed out. This feature is only enabled under the queue_debug context manager.

INTERRUPTED = 2¶

KEEP = 1¶

PRINT = 2¶

THROW = 0¶

WAITING = 1¶

emit(record)¶

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

queue_debug()¶

class mozbuild.configure.util.LineIO(callback, errors='strict')¶

Bases: object

File-like class that sends each line of the written data to a callback (without carriage returns).

close()¶

write(buf)¶

class mozbuild.configure.util.Version(version)¶

Bases: distutils.version.LooseVersion

A simple subclass of distutils.version.LooseVersion. Adds attributes for major, minor, patch for the first three version components so users can easily pull out major/minor versions, like:

v = Version(‘1.2b’) v.major == 1 v.minor == 2 v.patch == 0

mozbuild.configure.util.getpreferredencoding()¶

Module contents¶

class mozbuild.configure.CombinedDependsFunction(sandbox, func, dependencies)¶

Bases: mozbuild.configure.DependsFunction

dependencies¶

result()¶

sandbox¶

sandboxed¶

when¶

exception mozbuild.configure.ConfigureError¶: Bases: Exception

class mozbuild.configure.ConfigureSandbox(config, environ=environ({'TERM_PROGRAM': 'Apple_Terminal', 'TERM': 'xterm-256color', 'SHELL': '/bin/zsh', 'TMPDIR': '/var/folders/yt/2kyz65ds4qv_65pqwdb40x8h0000gn/T/', 'TERM_PROGRAM_VERSION': '440', 'TERM_SESSION_ID': '44D43395-B15B-4C30-B407-FB0B82511DC0', 'USER': 'davidp', 'SSH_AUTH_SOCK': '/private/tmp/com.apple.launchd.OpTkbPBPcK/Listeners', 'PATH': '/Users/davidp/moz/mozilla-unified/obj-x86_64-apple-darwin20.6.0/docs/html/_venv/common/bin:/Users/davidp/moz/mozilla-unified/obj-x86_64-apple-darwin20.6.0/_virtualenvs/docs/bin:/Users/davidp/moz/mozilla-unified/node_modules/.bin:/Users/davidp/.mozbuild/node/bin:/Users/davidp/.mozbuild/srcdirs/mozilla-unified-5358a99862ea/_virtualenvs/mach/bin:/Users/davidp/bin:/Users/davidp/.cargo/bin:/Users/davidp/bin:/Users/davidp/.cargo/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin', 'LaunchInstanceID': '0489829A-0BCB-4917-9DE6-08D311C69421', '__CFBundleIdentifier': 'com.apple.Terminal', 'PWD': '/Users/davidp/moz/mozilla-unified', 'LANG': 'en_US.UTF-8', 'XPC_FLAGS': '0x0', 'XPC_SERVICE_NAME': '0', 'HOME': '/Users/davidp', 'SHLVL': '1', 'LOGNAME': 'davidp', 'SECURITYSESSIONID': '186a8', '__CF_USER_TEXT_ENCODING': '0x1F5:0x0:0x0', 'PLAT': 'macosx-11-x86_64', 'VIRTUAL_ENV': '/Users/davidp/moz/mozilla-unified/obj-x86_64-apple-darwin20.6.0/docs/html/_venv/common', 'MACH_MAIN_PID': '4015', 'MACH_STDOUT_ISATTY': '1', 'DOCUTILSCONFIG': '/Users/davidp/moz/mozilla-unified/docs/docutils.conf'}), argv=['./mach', 'doc'], stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, stderr=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, logger=None)¶

Bases: dict

Represents a sandbox for executing Python code for build configuration. This is a different kind of sandboxing than the one used for moz.build processing.

The sandbox has 9 primitives: - option - depends - template - imports - include - set_config - set_define - imply_option - only_when

option, include, set_config, set_define and imply_option are functions. depends, template, and imports are decorators. only_when is a context_manager.

These primitives are declared as name_impl methods to this class and the mapping name -> name_impl is done automatically in __getitem__.

Additional primitives should be frowned upon to keep the sandbox itself as simple as possible. Instead, helpers should be created within the sandbox with the existing primitives.

The sandbox is given, at creation, a dict where the yielded configuration will be stored.

config = {} sandbox = ConfigureSandbox(config) sandbox.run(path) do_stuff(config)

BUILTINS = {'AssertionError': <class 'AssertionError'>, 'False': False, 'None': None, 'True': True, '__build_class__': <built-in function __build_class__>, '__import__': <function forbidden_import>, 'all': <built-in function all>, 'any': <built-in function any>, 'bool': <class 'bool'>, 'dict': <class 'dict'>, 'enumerate': <class 'enumerate'>, 'getattr': <built-in function getattr>, 'hasattr': <built-in function hasattr>, 'int': <class 'int'>, 'isinstance': <built-in function isinstance>, 'len': <built-in function len>, 'list': <class 'list'>, 'max': <built-in function max>, 'min': <built-in function min>, 'range': <class 'range'>, 'set': <class 'set'>, 'sorted': <built-in function sorted>, 'str': <class 'str'>, 'tuple': <class 'tuple'>, 'zip': <class 'zip'>}¶

OS = <ReadOnlyNamespace {'path': <ReadOnlyNamespace {'abspath': <function abspath>, 'basename': <function basename>, 'dirname': <function dirname>, 'isabs': <function isabs>, 'join': <function join>, 'normcase': <function normcase>, 'normpath': <function normpath>, 'realpath': <function realpath>, 'relpath': <function relpath>}>}>¶

RE_MODULE = re.compile('^[a-zA-Z0-9_\\.]+$')¶

depends_impl(*args, **kwargs)¶

Implementation of @depends() This function is a decorator. It returns a function that subsequently takes a function and returns a dummy function. The dummy function identifies the actual function for the sandbox, while preventing further function calls from within the sandbox.

@depends() takes a variable number of option strings or dummy function references. The decorated function is called as soon as the decorator is called, and the arguments it receives are the OptionValue or function results corresponding to each of the arguments to @depends. As an exception, when a HelpFormatter is attached, only functions that have ‘–help’ in their @depends argument list are called.

The decorated function is altered to use a different global namespace for its execution. This different global namespace exposes a limited set of functions from os.path.

imply_option_impl(option, value, reason=None, when=None)¶

Implementation of imply_option(). Injects additional options as if they had been passed on the command line. The option argument is a string as in option()’s name or env. The option must be declared after imply_option references it. The value argument indicates the value to pass to the option. It can be: - True. In this case imply_option injects the positive option

(–enable-foo/–with-foo).
imply_option(‘–enable-foo’, True) imply_option(‘–disable-foo’, True)

are both equivalent to –enable-foo on the command line.

False. In this case imply_option injects the negative option

(–disable-foo/–without-foo).
imply_option(‘–enable-foo’, False) imply_option(‘–disable-foo’, False)

are both equivalent to –disable-foo on the command line.
None. In this case imply_option does nothing.
imply_option(‘–enable-foo’, None) imply_option(‘–disable-foo’, None)

are both equivalent to not passing any flag on the command line.

a string or a tuple. In this case imply_option injects the positive option with the given value(s).

imply_option(‘–enable-foo’, ‘a’) imply_option(‘–disable-foo’, ‘a’)

are both equivalent to –enable-foo=a on the command line.
imply_option(‘–enable-foo’, (‘a’, ‘b’)) imply_option(‘–disable-foo’, (‘a’, ‘b’))

are both equivalent to –enable-foo=a,b on the command line.

Because imply_option(‘–disable-foo’, …) can be misleading, it is recommended to use the positive form (‘–enable’ or ‘–with’) for option.

The value argument can also be (and usually is) a reference to a @depends function, in which case the result of that function will be used as per the descripted mapping above.

The reason argument indicates what caused the option to be implied. It is necessary when it cannot be inferred from the value.

imports_impl(_import, _from=None, _as=None)¶: Implementation of @imports. This decorator imports the given _import from the given _from module optionally under a different _as name. The options correspond to the various forms for the import builtin.

@imports(‘sys’) @imports(_from=’mozpack’, _import=’path’, _as=’mozpath’)

include_file(path)¶

Include one file in the sandbox. Users of this class probably want to use run instead.

Note: this will execute all template invocations, as well as @depends functions that depend on ‘–help’, but nothing else.

include_impl(what, when=None)¶: Implementation of include(). Allows to include external files for execution in the sandbox. It is possible to use a @depends function as argument, in which case the result of the function is the file name to include. This latter feature is only really meant for –enable-application/–enable-project.

only_when_impl(when)¶

Implementation of only_when()

only_when is a context manager that essentially makes calls to other sandbox functions within the context block ignored.

option_impl(*args, **kwargs)¶: Implementation of option() This function creates and returns an Option() object, passing it the resolved arguments (uses the result of functions when functions are passed). In most cases, the result of this function is not expected to be used. Command line argument/environment variable parsing for this Option is handled here.

run(path=None)¶: Executes the given file within the sandbox, as well as everything pending from any other included file, and ensure the overall consistency of the executed script(s).

set_config_impl(name, value, when=None)¶: Implementation of set_config(). Set the configuration items with the given name to the given value. Both name and value can be references to @depends functions, in which case the result from these functions is used. If the result of either function is None, the configuration item is not set.

set_define_impl(name, value, when=None)¶: Implementation of set_define(). Set the define with the given name to the given value. Both name and value can be references to @depends functions, in which case the result from these functions is used. If the result of either function is None, the define is not set. If the result is False, the define is explicitly undefined (-U).

template_impl(func)¶: Implementation of @template. This function is a decorator. Template functions are called immediately. They are altered so that their global namespace exposes a limited set of functions from os.path, as well as depends and option. Templates allow to simplify repetitive constructs, or to implement helper decorators and somesuch.

wraps(func)¶

class mozbuild.configure.DependsFunction(sandbox, func, dependencies, when=None)¶

Bases: object

static and_impl(iterable)¶

dependencies¶

property name¶

static or_impl(iterable)¶

result()¶

sandbox¶

sandboxed¶

property sandboxed_dependencies¶

when¶

class mozbuild.configure.SandboxDependsFunction(unsandboxed)¶

Bases: object

Sandbox-visible representation of @depends functions.

class mozbuild.configure.SandboxedGlobal¶

Bases: dict

Identifiable dict type for use as function global

class mozbuild.configure.TrivialDependsFunction(sandbox, func, dependencies, when=None)¶

Bases: mozbuild.configure.DependsFunction

Like a DependsFunction, but the linter won’t expect it to have a dependency on –help ever.

dependencies¶

sandbox¶

sandboxed¶

when¶

mozbuild.configure.forbidden_import(*args, **kwargs)¶