mozbuild Sandbox Symbols¶

Note

moz.build files’ implementation includes a Path class. This class is used as a backing type for some of the sandbox variables. It expresses paths relative to a context. Supported paths are:

‘/topsrcdir/relative/paths’

‘srcdir/relative/paths’

‘!/topobjdir/relative/paths’

‘!objdir/relative/paths’

‘%/filesystem/absolute/paths’

Sub-Context: Files¶

Metadata attached to files.

It is common to want to annotate files with metadata, such as which Bugzilla component tracks issues with certain files. This sub-context is where we stick that metadata.

The argument to this sub-context is a file matching pattern that is applied against the host file’s directory. If the pattern matches a file whose info is currently being sought, the metadata attached to this instance will be applied to that file.

Patterns are collections of filename characters with / used as the directory separate (UNIX-style paths) and * and ** used to denote wildcard matching.

Patterns without the * character are literal matches and will match at most one entity.

Patterns with * or ** are wildcard matches. * matches files at least within a single directory. ** matches files across several directories.

foo.html: Will match only the foo.html file in the current directory.
*.mjs: Will match all .mjs files in the current directory.
**/*.cpp: Will match all .cpp files in this and all child directories.
foo/*.css: Will match all .css files in the foo/ directory.
bar/*: Will match all files in the bar/ directory and all of its children directories.
bar/**: This is equivalent to bar/* above.
bar/**/foo: Will match all foo files in the bar/ directory and all of its children directories.

The difference in behavior between * and ** is only evident if a pattern follows the * or **. A pattern ending with * is greedy. ** is needed when you need an additional pattern after the wildcard. e.g. **/foo.

BUG_COMPONENT¶

The bug component that tracks changes to these files.

Storage Type:: TypedTuple
Input Type:: tuple

Values are a 2-tuple of unicode describing the Bugzilla product and component. e.g. ('Firefox Build System', 'General').

FINAL¶

Mark variable assignments as finalized.

Storage Type:: bool
Input Type:: bool

During normal processing, values from newer Files contexts overwrite previously set values. Last write wins. This behavior is not always desired. FINAL provides a mechanism to prevent further updates to a variable.

When FINAL is set, the value of all variables defined in this context are marked as frozen and all subsequent writes to them are ignored during metadata reading.

See Finalizing Values for more info.

SCHEDULES¶

Maps source files to the CI tasks that should be scheduled when

Storage Type:: Schedules
Input Type:: list

they change. The tasks are grouped by named components, and those names appear again in the taskgraph configuration `($topsrcdir/taskgraph/).

Some components are “inclusive”, meaning that changes to most files do not schedule them, aside from those described in a Files subcontext. For example, py-lint tasks need not be scheduled for most changes, but should be scheduled when any Python file changes. Such components are named by appending to SCHEDULES.inclusive:

with Files(’**.py’):: SCHEDULES.inclusive += [‘py-lint’]

Other components are ‘exclusive’, meaning that changes to most files schedule them, but some files affect only one or two components. For example, most files schedule builds and tests of Firefox for Android, OS X, Windows, and Linux, but files under mobile/android/ affect Android builds and tests exclusively, so builds for other operating systems are not needed. Test suites provide another example: most files schedule reftests, but changes to reftest scripts need only schedule reftests and no other suites.

Exclusive components are named by setting SCHEDULES.exclusive:

with Files(‘mobile/android/**’):: SCHEDULES.exclusive = [‘android’]

Variables¶

ANDROID_INSTRUMENTATION_MANIFESTS¶

List of manifest files defining Android instrumentation tests.

Storage Type:: _OrderedListWithAction
Input Type:: list

ASFLAGS¶

Flags passed to the assembler for all of the assembly source files

Storage Type:: List
Input Type:: list

declared in this directory.

Note that the ordering of flags matters here; these flags will be added to the assembler’s command line in the same order as they appear in the moz.build file.

ASM_FLAGS¶

Recipe for linker flags for this context. Not to be

Storage Type:: AsmFlags
Input Type:: dict

manipulated directly.

BROWSER_CHROME_MANIFESTS¶

List of manifest files defining browser chrome tests.

Storage Type:: _OrderedListWithAction
Input Type:: list

CFLAGS¶

Flags passed to the C compiler for all of the C source files

Storage Type:: List
Input Type:: list

declared in this directory.

Note that the ordering of flags matters here, these flags will be added to the compiler’s command line in the same order as they appear in the moz.build file.

CMFLAGS¶

Flags passed to the Objective-C compiler for all of the Objective-C

Storage Type:: List
Input Type:: list

source files declared in this directory.

Note that the ordering of flags matters here; these flags will be added to the compiler’s command line in the same order as they appear in the moz.build file.

CMMFLAGS¶

Flags passed to the Objective-C++ compiler for all of the

Storage Type:: List
Input Type:: list

Objective-C++ source files declared in this directory.

Note that the ordering of flags matters here; these flags will be added to the compiler’s command line in the same order as they appear in the moz.build file.

COMPILE_FLAGS¶

Recipe for compile flags for this context. Not to be manipulated

Storage Type:: CompileFlags
Input Type:: dict

directly.

CONFIGURE_DEFINE_FILES¶

Output files generated from configure/config.status.

Storage Type:: _TypedList
Input Type:: list

This is a substitute for AC_CONFIG_HEADER in autoconf. This is very similar to CONFIGURE_SUBST_FILES except the generation logic takes into account the values of AC_DEFINE instead of AC_SUBST.

CONFIGURE_SUBST_FILES¶

Output files that will be generated using configure-like substitution.

Storage Type:: _TypedList
Input Type:: list

This is a substitute for AC_OUTPUT in autoconf. For each path in this list, we will search for a file in the srcdir having the name {path}.in. The contents of this file will be read and variable patterns like @foo@ will be substituted with the values of the AC_SUBST variables declared during configure.

CPP_UNIT_TESTS¶

Compile a list of C++ unit test names.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

Each name in this variable corresponds to an executable built from the corresponding source file with the same base name.

If the configuration token BIN_SUFFIX is set, its value will be automatically appended to each name. If a name already ends with BIN_SUFFIX, the name will remain unchanged. This variable is only available in templates.

CRASHTEST_MANIFESTS¶

List of manifest files defining crashtests.

Storage Type:: _OrderedListWithAction
Input Type:: list

These are commonly named crashtests.list.

CXXFLAGS¶

Flags passed to the C++ compiler for all of the C++ source files

Storage Type:: List
Input Type:: list

declared in this directory.

Note that the ordering of flags matters here; these flags will be added to the compiler’s command line in the same order as they appear in the moz.build file.

DEFFILE¶

The program .def (module definition) file.

Storage Type:: Path
Input Type:: str

This variable can only be used on Windows.

DEFINES¶

Dictionary of compiler defines to declare.

Storage Type:: InitializedDefines
Input Type:: dict

These are passed in to the compiler as -Dkey='value' for string values, -Dkey=value for numeric values, or -Dkey if the value is True. Note that for string values, the outer-level of single-quotes will be consumed by the shell. If you want to have a string-literal in the program, the value needs to have double-quotes.

Example:

DEFINES['NS_NO_XPCOM'] = True
DEFINES['MOZ_EXTENSIONS_DB_SCHEMA'] = 15
DEFINES['DLL_SUFFIX'] = '".so"'

This will result in the compiler flags -DNS_NO_XPCOM, -DMOZ_EXTENSIONS_DB_SCHEMA=15, and -DDLL_SUFFIX='".so"', respectively.

Note that these entries are not necessarily passed to the assembler. Whether they are depends on the type of assembly file. As an alternative, you may add a -DKEY=value entry to ASFLAGS.

DELAYLOAD_DLLS¶

Delay-loaded DLLs.

Storage Type:: List
Input Type:: list

This variable contains a list of DLL files which the module being linked should load lazily. This only has an effect when building with MSVC.

DIRS¶

Child directories to descend into looking for build frontend files.

Storage Type:: _TypedList
Input Type:: list

This works similarly to the DIRS variable in make files. Each str value in the list is the name of a child directory. When this file is done parsing, the build reader will descend into each listed directory and read the frontend file there. If there is no frontend file, an error is raised.

Values are relative paths. They can be multiple directory levels above or below. Use .. for parent directories and / for path delimiters.

DIST_INSTALL¶

Whether to install certain files into the dist directory.

Storage Type:: EnumClass
Input Type:: bool

By default, some files types are installed in the dist directory, and some aren’t. Set this variable to True to force the installation of some files that wouldn’t be installed by default. Set this variable to False to force to not install some files that would be installed by default.

This is confusing for historical reasons, but eventually, the behavior will be made explicit.

DIST_SUBDIR¶

The name of an alternate directory to install files to.

Storage Type:: str
Input Type:: str

When this variable is present, the results of this directory will end up being placed in the $(DIST_SUBDIR) subdirectory of where it would otherwise be placed.

EXPORTS¶

List of files to be exported, and in which subdirectories.

Storage Type:: _TypedListWithItems
Input Type:: list

EXPORTS is generally used to list the include files to be exported to dist/include, but it can be used for other files as well. This variable behaves as a list when appending filenames for export in the top-level directory. Files can also be appended to a field to indicate which subdirectory they should be exported to. For example, to export foo.h to the top-level directory, and bar.h to mozilla/dom/, append to EXPORTS like so:

EXPORTS += ['foo.h']
EXPORTS.mozilla.dom += ['bar.h']

Entries in EXPORTS are paths, so objdir paths may be used, but any files listed from the objdir must also be listed in GENERATED_FILES.

EXTRA_DSO_LDOPTS¶

Flags passed to the linker when linking a shared library.

Storage Type:: List
Input Type:: list

Note that the ordering of flags matter here, these flags will be added to the linker’s command line in the same order as they appear in the moz.build file.

FILES_PER_UNIFIED_FILE¶

The number of source files to compile into each unified source file.

Storage Type:: int
Input Type:: int

FINAL_LIBRARY¶

Library in which the objects of the current directory will be linked.

Storage Type:: str
Input Type:: str

This variable contains the name of a library, defined elsewhere with LIBRARY_NAME, in which the objects of the current directory will be linked.

FINAL_TARGET¶

The name of the directory to install targets to.

Storage Type:: FinalTargetValue
Input Type:: str

The directory is relative to the top of the object directory. The default value is dependent on the values of XPI_NAME and DIST_SUBDIR. If neither are present, the result is dist/bin. If XPI_NAME is present, the result is dist/xpi-stage/$(XPI_NAME). If DIST_SUBDIR is present, then the $(DIST_SUBDIR) directory of the otherwise default value is used.

FINAL_TARGET_FILES¶

List of files to be installed into the application directory.

Storage Type:: _TypedListWithItems
Input Type:: list

FINAL_TARGET_FILES will copy (or symlink, if the platform supports it) the contents of its files to the directory specified by FINAL_TARGET (typically dist/bin). Files that are destined for a subdirectory can be specified by accessing a field, or as a dict access. For example, to export foo.png to the top-level directory and bar.svg to the directory images/do-not-use, append to FINAL_TARGET_FILES like so:

FINAL_TARGET_FILES += ['foo.png']
FINAL_TARGET_FILES.images['do-not-use'] += ['bar.svg']

FINAL_TARGET_PP_FILES¶

Like FINAL_TARGET_FILES, with preprocessing.

Storage Type:: _TypedListWithItems
Input Type:: list

FIREFOX_UI_FUNCTIONAL_MANIFESTS¶

List of manifest files defining firefox-ui-functional tests.

Storage Type:: _OrderedListWithAction
Input Type:: list

FORCE_SHARED_LIB¶

Whether the library in this directory is a shared library.

Storage Type:: bool
Input Type:: bool

This variable is only available in templates.

FORCE_STATIC_LIB¶

Whether the library in this directory is a static library.

Storage Type:: bool
Input Type:: bool

GENERATED_EVENTS_WEBIDL_FILES¶

WebIDL source files for generated events.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

These will be parsed and converted to .cpp and .h files.

GENERATED_FILES¶

Generic generated files.

Storage Type:: StrictOrderingOnAppendListWithFlagsSpecialization
Input Type:: list

Unless you have a reason not to, use the GeneratedFile template rather than referencing GENERATED_FILES directly. The GeneratedFile template has all the same arguments as the attributes listed below (script, inputs, flags, force), plus an additional entry_point argument to specify a particular function to run in the given script.

This variable contains a list of files for the build system to generate at export time. The generation method may be declared with optional script, inputs, flags, and force attributes on individual entries. If the optional script attribute is not present on an entry, it is assumed that rules for generating the file are present in the associated Makefile.in.

Example:

GENERATED_FILES += ['bar.c', 'baz.c', 'foo.c']
bar = GENERATED_FILES['bar.c']
bar.script = 'generate.py'
bar.inputs = ['datafile-for-bar']
foo = GENERATED_FILES['foo.c']
foo.script = 'generate.py'
foo.inputs = ['datafile-for-foo']

This definition will generate bar.c by calling the main method of generate.py with a open (for writing) file object for bar.c, and the string datafile-for-bar. In a similar fashion, the main method of generate.py will also be called with an open (for writing) file object for foo.c and the string datafile-for-foo. Please note that only string arguments are supported for passing to scripts, and that all arguments provided to the script should be filenames relative to the directory in which the moz.build file is located.

To enable using the same script for generating multiple files with slightly different non-filename parameters, alternative entry points into script can be specified:

GENERATED_FILES += ['bar.c']
bar = GENERATED_FILES['bar.c']
bar.script = 'generate.py:make_bar'

The chosen script entry point may optionally return a set of strings, indicating extra files the output depends on.

When the flags attribute is present, the given list of flags is passed as extra arguments following the inputs.

When the force attribute is present, the file is generated every build, regardless of whether it is stale. This is special to the RecursiveMake backend and intended for special situations only (e.g., localization). Please consult a build peer (on the #build channel at https://chat.mozilla.org) before using force.

GENERATED_WEBIDL_FILES¶

Generated WebIDL source files.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

These will be generated from some other files.

GYP_DIRS¶

Defines a list of object directories handled by gyp configurations.

Storage Type:: StrictOrderingOnAppendListWithFlagsSpecialization
Input Type:: list

Elements of this list give the relative object directory. For each element of the list, GYP_DIRS may be accessed as a dictionary (GYP_DIRS[foo]). The object this returns has attributes that need to be set to further specify gyp processing:

input, gives the path to the root gyp configuration file for that object directory.

variables, a dictionary containing variables and values to pass to the gyp processor.

sandbox_vars, a dictionary containing variables and values to pass to the mozbuild processor on top of those derived from gyp configuration.

no_chromium, a boolean which if set to True disables some special handling that emulates gyp_chromium.

no_unified, a boolean which if set to True disables source file unification entirely.

non_unified_sources, a list containing sources files, relative to the current moz.build, that should be excluded from source file unification.

action_overrides, a dict of action_name to values of the script attribute to use for GENERATED_FILES for the specified action.

Typical use looks like:

GYP_DIRS += [‘foo’, ‘bar’] GYP_DIRS[‘foo’].input = ‘foo/foo.gyp’ GYP_DIRS[‘foo’].variables = {

‘foo’: ‘bar’, (…)

} (…)

HOST_CFLAGS¶

Flags passed to the host C compiler for all of the C source files

Storage Type:: List
Input Type:: list

declared in this directory.

Note that the ordering of flags matters here, these flags will be added to the compiler’s command line in the same order as they appear in the moz.build file.

HOST_COMPILE_FLAGS¶

Recipe for host compile flags for this context. Not to be manipulated

Storage Type:: HostCompileFlags
Input Type:: dict

directly.

HOST_CXXFLAGS¶

Flags passed to the host C++ compiler for all of the C++ source files

Storage Type:: List
Input Type:: list

declared in this directory.

Note that the ordering of flags matters here; these flags will be added to the compiler’s command line in the same order as they appear in the moz.build file.

HOST_DEFINES¶

Dictionary of compiler defines to declare for host compilation.

Storage Type:: InitializedDefines
Input Type:: dict

See DEFINES for specifics.

HOST_LIBRARY_NAME¶

Name of target library generated when cross compiling.

Storage Type:: str
Input Type:: str

This variable is only available in templates.

HOST_OS_LIBS¶

List of system libraries for host programs and libraries.

Storage Type:: List
Input Type:: list

HOST_PROGRAM¶

Compiled host executable name.

Storage Type:: str
Input Type:: str

If the configuration token HOST_BIN_SUFFIX is set, its value will be automatically appended to HOST_PROGRAM. If HOST_PROGRAM already ends with HOST_BIN_SUFFIX, HOST_PROGRAM will remain unchanged. This variable is only available in templates.

HOST_RUST_LIBRARY_FEATURES¶

Cargo features to activate for this host library.

Storage Type:: List
Input Type:: list

This variable should not be used directly; you should be using the HostRustLibrary template instead.

HOST_RUST_PROGRAMS¶

Compile a list of Rust executable names.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

Each name in this variable corresponds to an executable built from the Cargo.toml in the same directory.

HOST_SIMPLE_PROGRAMS¶

Compile a list of host executable names.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

Each name in this variable corresponds to a hosst executable built from the corresponding source file with the same base name.

If the configuration token HOST_BIN_SUFFIX is set, its value will be automatically appended to each name. If a name already ends with HOST_BIN_SUFFIX, the name will remain unchanged. This variable is only available in templates.

HOST_SOURCES¶

Source code files to compile with the host compiler.

Storage Type:: _TypedList
Input Type:: list

This variable contains a list of source code files to compile. with the host compiler.

HOST_USE_LIBS¶

List of libraries to link to host programs and libraries.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

IPDL_SOURCES¶

IPDL source files.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

These are .ipdl files that will be parsed and converted to .cpp files.

IS_FRAMEWORK¶

Whether the library to build should be built as a framework on OSX.

Storage Type:: bool
Input Type:: bool

This implies the name of the library won’t be prefixed nor suffixed. Implies FORCE_SHARED_LIB. This variable is only available in templates.

IS_GKRUST¶

Whether the current library defined by this moz.build is gkrust.

Storage Type:: bool
Input Type:: bool

Indicates whether the current library contains rust for libxul. This variable is only available in templates.

IS_RUST_LIBRARY¶

Whether the current library defined by this moz.build is built by Rust.

Storage Type:: bool
Input Type:: bool

The library defined by this moz.build should have a build definition in a Cargo.toml file that exists in this moz.build’s directory.

JAR_MANIFESTS¶

JAR manifest files that should be processed as part of the build.

Storage Type:: _TypedList
Input Type:: list

JAR manifests are files in the tree that define how to package files into JARs and how chrome registration is performed. For more info, see JAR Manifests.

LDFLAGS¶

Flags passed to the linker when linking all of the libraries and

Storage Type:: List
Input Type:: list

executables declared in this directory.

Note that the ordering of flags matters here; these flags will be added to the linker’s command line in the same order as they appear in the moz.build file.

LIBRARY_DEFINES¶

Dictionary of compiler defines to declare for the entire library.

Storage Type:: OrderedDict
Input Type:: dict

This variable works like DEFINES, except that declarations apply to all libraries that link into this library via FINAL_LIBRARY.

LIBRARY_NAME¶

The code name of the library generated for a directory.

Storage Type:: str
Input Type:: str

By default STATIC_LIBRARY_NAME and SHARED_LIBRARY_NAME take this name. In example/components/moz.build,:

LIBRARY_NAME = 'xpcomsample'

would generate example/components/libxpcomsample.so on Linux, or example/components/xpcomsample.lib on Windows. This variable is only available in templates.

LINK_FLAGS¶

Recipe for linker flags for this context. Not to be manipulated

Storage Type:: LinkFlags
Input Type:: dict

directly.

LOCALIZED_FILES¶

List of locale-dependent files to be installed into the application

Storage Type:: _TypedListWithItems
Input Type:: list

directory.

This functions similarly to FINAL_TARGET_FILES, but the files are sourced from the locale directory and will vary per localization. For an en-US build, this is functionally equivalent to FINAL_TARGET_FILES. For a build with --enable-ui-locale, the file will be taken from $LOCALE_SRCDIR, with the leading en-US removed. For a l10n repack of an en-US build, the file will be taken from the first location where it exists from: * the merged locale directory if it exists * $LOCALE_SRCDIR with the leading en-US removed * the in-tree en-US location

Source directory paths specified here must must include a leading en-US. Wildcards are allowed, and will be expanded at the time of locale packaging to match files in the locale directory.

Object directory paths are allowed here only if the path matches an entry in LOCALIZED_GENERATED_FILES.

Files that are missing from a locale will typically have the en-US version used, but for wildcard expansions only files from the locale directory will be used, even if that means no files will be copied.

Example:

LOCALIZED_FILES.foo += [
  'en-US/foo.js',
  'en-US/things/*.ini',
]

If this was placed in toolkit/locales/moz.build, it would copy toolkit/locales/en-US/foo.js and toolkit/locales/en-US/things/*.ini to $(DIST)/bin/foo in an en-US build, and in a build of a different locale (or a repack), it would copy $(LOCALE_SRCDIR)/toolkit/foo.js and $(LOCALE_SRCDIR)/toolkit/things/*.ini.

LOCALIZED_GENERATED_FILES¶

Like GENERATED_FILES, but for files whose content varies based on the locale in use.

Storage Type:: StrictOrderingOnAppendListWithFlagsSpecialization
Input Type:: list

For simple cases of text substitution, prefer LOCALIZED_PP_FILES.

Refer to the documentation of GENERATED_FILES; for the most part things work the same. The two major differences are: 1. The function in the Python script will be passed an additional keyword argument locale

which provides the locale in use, i.e. en-US.

The inputs list may contain paths to files that will be taken from the locale source directory (see LOCALIZED_FILES for a discussion of the specifics). Paths in inputs starting with en-US/ or containing locales/en-US/ are considered localized files.

To place the generated output file in a specific location, list its objdir path in LOCALIZED_FILES.

In addition, LOCALIZED_GENERATED_FILES can use the special substitutions {AB_CD} and {AB_rCD} in their output paths. {AB_CD} expands to the current locale during multi-locale builds and single-locale repacks and {AB_rCD} expands to an Android-specific encoding of the current locale. Both expand to the empty string when the current locale is en-US.

LOCALIZED_PP_FILES¶

Like LOCALIZED_FILES, with preprocessing.

Storage Type:: _TypedListWithItems
Input Type:: list

Note that the AB_CD define is available and expands to the current locale being packaged, as with preprocessed entries in jar manifests.

LOCAL_INCLUDES¶

Additional directories to be searched for include files by the compiler.

Storage Type:: _TypedList
Input Type:: list

MARIONETTE_MANIFESTS¶

List of manifest files defining marionette tests.

Storage Type:: _OrderedListWithAction
Input Type:: list

METRO_CHROME_MANIFESTS¶

List of manifest files defining metro browser chrome tests.

Storage Type:: _OrderedListWithAction
Input Type:: list

MOCHITEST_CHROME_MANIFESTS¶

List of manifest files defining mochitest chrome tests.

Storage Type:: _OrderedListWithAction
Input Type:: list

MOCHITEST_MANIFESTS¶

List of manifest files defining mochitest tests.

Storage Type:: _OrderedListWithAction
Input Type:: list

NO_EXPAND_LIBS¶

Forces to build a real static library, and no corresponding fake

Storage Type:: bool
Input Type:: bool

library.

NO_PGO¶

Whether profile-guided optimization is disable in this directory.

Storage Type:: bool
Input Type:: bool

OBJDIR_FILES¶

List of files to be installed anywhere in the objdir. Use sparingly.

Storage Type:: _TypedListWithItems
Input Type:: list

OBJDIR_FILES is similar to FINAL_TARGET_FILES, but it allows copying anywhere in the object directory. This is intended for various one-off cases, not for general use. If you wish to add entries to OBJDIR_FILES, please consult a build peer (on the #build channel at https://chat.mozilla.org).

OBJDIR_PP_FILES¶

Like OBJDIR_FILES, with preprocessing. Use sparingly.

Storage Type:: _TypedListWithItems
Input Type:: list

OS_LIBS¶

System link libraries.

Storage Type:: List
Input Type:: list

This variable contains a list of system libaries to link against.

PERFTESTS_MANIFESTS¶

List of manifest files defining MozPerftest performance tests.

Storage Type:: _OrderedListWithAction
Input Type:: list

PREPROCESSED_IPDL_SOURCES¶

Preprocessed IPDL source files.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

These files will be preprocessed, then parsed and converted to .cpp files.

PREPROCESSED_TEST_WEBIDL_FILES¶

Preprocessed test WebIDL source files.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

These will be preprocessed, then parsed and converted to .cpp and .h files if tests are enabled.

PREPROCESSED_WEBIDL_FILES¶

Preprocessed WebIDL source files.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

These will be preprocessed before being parsed and converted.

PROGRAM¶

Compiled executable name.

Storage Type:: str
Input Type:: str

If the configuration token BIN_SUFFIX is set, its value will be automatically appended to PROGRAM. If PROGRAM already ends with BIN_SUFFIX, PROGRAM will remain unchanged. This variable is only available in templates.

PYTHON_UNITTEST_MANIFESTS¶

List of manifest files defining python unit tests.

Storage Type:: _OrderedListWithAction
Input Type:: list

RCFILE¶

The program .rc file.

Storage Type:: Path
Input Type:: str

This variable can only be used on Windows.

RCINCLUDE¶

The resource script file to be included in the default .res file.

Storage Type:: Path
Input Type:: str

This variable can only be used on Windows.

REFTEST_MANIFESTS¶

List of manifest files defining reftests.

Storage Type:: _OrderedListWithAction
Input Type:: list

These are commonly named reftest.list.

RUST_LIBRARY_FEATURES¶

Cargo features to activate for this library.

Storage Type:: List
Input Type:: list

This variable should not be used directly; you should be using the RustLibrary template instead.

RUST_LIBRARY_OUTPUT_CATEGORY¶

The output category for this context’s rust library. If set this will

Storage Type:: str
Input Type:: str

correspond to the build command that will build this rust library, and the library will not be built as part of the default build.

RUST_PROGRAMS¶

Compile a list of Rust host executable names.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

Each name in this variable corresponds to an executable built from the Cargo.toml in the same directory.

RUST_TESTS¶

Names of Rust tests to build and run via cargo test.

Storage Type:: _TypedList
Input Type:: list

RUST_TEST_FEATURES¶

Cargo features to activate for RUST_TESTS.

Storage Type:: _TypedList
Input Type:: list

SANDBOXED_WASM_LIBRARY_NAME¶

The name of the static sandboxed wasm library generated for a directory.

Storage Type:: str
Input Type:: str

SHARED_LIBRARY_NAME¶

The name of the static library generated for a directory, if it needs to

Storage Type:: str
Input Type:: str

differ from the library code name.

Implies FORCE_SHARED_LIB.

SHARED_LIBRARY_OUTPUT_CATEGORY¶

The output category for this context’s shared library. If set this will

Storage Type:: str
Input Type:: str

correspond to the build command that will build this shared library, and the library will not be built as part of the default build.

SIMPLE_PROGRAMS¶

Compile a list of executable names.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

Each name in this variable corresponds to an executable built from the corresponding source file with the same base name.

If the configuration token BIN_SUFFIX is set, its value will be automatically appended to each name. If a name already ends with BIN_SUFFIX, the name will remain unchanged. This variable is only available in templates.

SONAME¶

The soname of the shared object currently being linked

Storage Type:: str
Input Type:: str

soname is the “logical name” of a shared object, often used to provide version backwards compatibility. This variable makes sense only for shared objects, and is supported only on some unix platforms.

SOURCES¶

Source code files.

Storage Type:: _TypedListWithItems
Input Type:: list

This variable contains a list of source code files to compile. Accepts assembler, C, C++, Objective C/C++.

SPHINX_PYTHON_PACKAGE_DIRS¶

Directories containing Python packages that Sphinx documents.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

SPHINX_TREES¶

Describes what the Sphinx documentation tree will look like.

Storage Type:: dict
Input Type:: dict

Keys are relative directories inside the final Sphinx documentation tree to install files into. Values are directories (relative to this file) whose content to copy into the Sphinx documentation tree.

STATIC_LIBRARY_NAME¶

The name of the static library generated for a directory, if it needs to

Storage Type:: str
Input Type:: str

differ from the library code name.

Implies FORCE_STATIC_LIB.

SYMBOLS_FILE¶

A file containing a list of symbols to export from a shared library.

Storage Type:: Path
Input Type:: str

The given file contains a list of symbols to be exported, and is preprocessed. A special marker “@DATA@” must be added after a symbol name if it points to data instead of code, so that the Windows linker can treat them correctly.

TELEMETRY_TESTS_CLIENT_MANIFESTS¶

List of manifest files defining telemetry client tests.

Storage Type:: _OrderedListWithAction
Input Type:: list

TEST_HARNESS_FILES¶

List of files to be installed for test harnesses.

Storage Type:: _TypedListWithItems
Input Type:: list

TEST_HARNESS_FILES can be used to install files to any directory under $objdir/_tests. Files can be appended to a field to indicate which subdirectory they should be exported to. For example, to export foo.py to _tests/foo, append to TEST_HARNESS_FILES like so:

TEST_HARNESS_FILES.foo += ['foo.py']

Files from topsrcdir and the objdir can also be installed by prefixing the path(s) with a ‘/’ character and a ‘!’ character, respectively:

TEST_HARNESS_FILES.path += ['/build/bar.py', '!quux.py']

TEST_WEBIDL_FILES¶

Test WebIDL source files.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

These will be parsed and converted to .cpp and .h files if tests are enabled.

UNIFIED_SOURCES¶

Source code files that can be compiled together.

Storage Type:: _TypedList
Input Type:: list

This variable contains a list of source code files to compile, that can be concatenated all together and built as a single source file. This can help make the build faster and reduce the debug info size.

USE_EXTENSION_MANIFEST¶

Controls the name of the manifest for JAR files.

Storage Type:: bool
Input Type:: bool

By default, the name of the manifest is ${JAR_MANIFEST}.manifest. Setting this variable to True changes the name of the manifest to chrome.manifest.

USE_INTEGRATED_CLANGCL_AS¶

Use the integrated clang-cl assembler to assemble assembly files from SOURCES.

Storage Type:: bool
Input Type:: bool

This allows using clang-cl to assemble assembly files which is useful on platforms like aarch64 where the alternative is to have to run a pre-processor to generate files with suitable syntax.

USE_LIBS¶

List of libraries to link to programs and libraries.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

USE_NASM¶

Use the nasm assembler to assemble assembly files from SOURCES.

Storage Type:: bool
Input Type:: bool

By default, the build will use the toolchain assembler, $(AS), to assemble source files in assembly language (.s or .asm files). Setting this value to True will cause it to use nasm instead.

If nasm is not available on this system, or does not support the current target architecture, an error will be raised.

USE_STATIC_LIBS¶

Whether the code in this directory is a built against the static

Storage Type:: bool
Input Type:: bool

runtime library.

This variable only has an effect when building with MSVC.

WASM_CFLAGS¶

Flags passed to the C-to-wasm compiler for all of the C

Storage Type:: List
Input Type:: list

source files declared in this directory.

Note that the ordering of flags matters here, these flags will be added to the compiler’s command line in the same order as they appear in the moz.build file.

WASM_CXXFLAGS¶

Flags passed to the C++-to-wasm compiler for all of the

Storage Type:: List
Input Type:: list

C++ source files declared in this directory.

Note that the ordering of flags matters here; these flags will be added to the compiler’s command line in the same order as they appear in the moz.build file.

WASM_DEFINES¶

Dictionary of compiler defines to declare for wasm compilation.

Storage Type:: InitializedDefines
Input Type:: dict

See DEFINES for specifics.

WASM_FLAGS¶

Recipe for wasm flags for this context. Not to be

Storage Type:: WasmFlags
Input Type:: dict

manipulated directly.

WASM_LIBS¶

Wasm system link libraries.

Storage Type:: List
Input Type:: list

This variable contains a list of wasm system libaries to link against.

WASM_SOURCES¶

Source code files to compile with the wasm compiler.

Storage Type:: _TypedList
Input Type:: list

WEBIDL_EXAMPLE_INTERFACES¶

Names of example WebIDL interfaces to build as part of the build.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

Names in this list correspond to WebIDL interface names defined in WebIDL files included in the build from one of the *WEBIDL_FILES variables.

WEBIDL_FILES¶

WebIDL source files.

Storage Type:: StrictOrderingOnAppendList
Input Type:: list

These will be parsed and converted to .cpp and .h files.

WIN32_EXE_LDFLAGS¶

Flags passed to the linker when linking a Windows .exe executable

Storage Type:: List
Input Type:: list

declared in this directory.

Note that the ordering of flags matter here, these flags will be added to the linker’s command line in the same order as they appear in the moz.build file.

This variable only has an effect on Windows.

XPCOM_MANIFESTS¶

XPCOM Component Manifest Files.

Storage Type:: _TypedList
Input Type:: list

This is a list of files that define XPCOM components to be added to the component registry.

XPCSHELL_TESTS_MANIFESTS¶

List of manifest files defining xpcshell tests.

Storage Type:: _OrderedListWithAction
Input Type:: list

XPIDL_MODULE¶

XPCOM Interface Definition Module Name.

Storage Type:: str
Input Type:: str

This is the name of the .xpt file that is created by linking XPIDL_SOURCES together. If unspecified, it defaults to be the same as MODULE.

XPIDL_SOURCES¶

XPCOM Interface Definition Files (xpidl).

Storage Type:: _TypedList
Input Type:: list

This is a list of files that define XPCOM interface definitions. Entries must be files that exist. Entries are almost certainly .idl files.

XPI_NAME¶

The name of an extension XPI to generate.

Storage Type:: str
Input Type:: str

When this variable is present, the results of this directory will end up being packaged into an extension instead of the main dist/bin results.

Functions¶

error¶

Issue a fatal error.

Arguments:: (str)

If this function is called, processing is aborted immediately.

export¶

Make the specified variable available to all child directories.

Arguments:: (str)

The variable specified by the argument string is added to the environment of all directories specified in the DIRS and TEST_DIRS variables. If those directories themselves have child directories, the variable will be exported to all of them.

The value used for the variable is the final value at the end of the moz.build file, so it is possible (but not recommended style) to place the export before the definition of the variable.

This function is limited to the upper-case variables that have special meaning in moz.build files.

NOTE: Please consult with a build peer (on the #build channel at https://chat.mozilla.org) before adding a new use of this function.

Example usage¶

To make all children directories install as the given extension:

XPI_NAME = 'cool-extension'
export('XPI_NAME')

include¶

Include another mozbuild file in the context of this one.

Arguments:: (SourcePath)

This is similar to a #include in C languages. The filename passed to the function will be read and its contents will be evaluated within the context of the calling file.

If a relative path is given, it is evaluated as relative to the file currently being processed. If there is a chain of multiple include(), the relative path computation is from the most recent/active file.

If an absolute path is given, it is evaluated from TOPSRCDIR. In other words, include('/foo') references the path TOPSRCDIR + '/foo'.

Example usage¶

Include sibling.build from the current directory.:

include('sibling.build')

Include foo.build from a path within the top source directory:

include('/elsewhere/foo.build')

template¶

Decorator for template declarations.

Arguments:: (function)

Templates are a special kind of functions that can be declared in mozbuild files. Uppercase variables assigned in the function scope are considered to be the result of the template.

Contrary to traditional python functions:

return values from template functions are ignored,
template functions don’t have access to the global scope.

Example template¶

The following Program template sets two variables PROGRAM and USE_LIBS. PROGRAM is set to the argument given on the template invocation, and USE_LIBS to contain “mozglue”:

@template
def Program(name):
    PROGRAM = name
    USE_LIBS += ['mozglue']

Template invocation¶

A template is invoked in the form of a function call:

Program('myprog')

The result of the template, being all the uppercase variable it sets is mixed to the existing set of variables defined in the mozbuild file invoking the template:

FINAL_TARGET = 'dist/other'
USE_LIBS += ['mylib']
Program('myprog')
USE_LIBS += ['otherlib']

The above mozbuild results in the following variables set:

FINAL_TARGET is ‘dist/other’

USE_LIBS is [‘mylib’, ‘mozglue’, ‘otherlib’]

PROGRAM is ‘myprog’

warning¶

Issue a warning.

Arguments:: (str)

Warnings are string messages that are printed during execution.

Warnings are ignored during execution.

Special Variables¶

CONFIG¶

Dictionary containing the current configuration variables.

Type:: dict

All the variables defined by the configuration system are available through this object. e.g. ENABLE_TESTS, CFLAGS, etc.

Values in this container are read-only. Attempts at changing values will result in a run-time error.

Access to an unknown variable will return None.

CONTENT_ACCESSIBLE_FILES¶

List of files which can be accessed by web content through resource:// URIs.

Type:: list

CONTENT_ACCESSIBLE_FILES is used to list the files to be exported to dist/bin/contentaccessible. Files can also be appended to a field to indicate which subdirectory they should be exported to.

EXTRA_COMPONENTS¶

Additional component files to distribute.

Type:: list

This variable contains a list of files to copy into $(FINAL_TARGET)/components/.

EXTRA_JS_MODULES¶

Additional JavaScript files to distribute.

Type:: list

This variable contains a list of files to copy into ``$(FINAL_TARGET)/modules.

EXTRA_PP_COMPONENTS¶

Javascript XPCOM files.

Type:: list

This variable contains a list of files to preprocess. Generated files will be installed in the /components directory of the distribution.

EXTRA_PP_JS_MODULES¶

Additional JavaScript files to distribute.

Type:: list

This variable contains a list of files to copy into $(FINAL_TARGET)/modules, after preprocessing.

JS_PREFERENCE_FILES¶

Exported JavaScript files.

Type:: list

A list of files copied into the dist directory for packaging and installation. Path will be defined for gre or application prefs dir based on what is building.

JS_PREFERENCE_PP_FILES¶

Like JS_PREFERENCE_FILES, preprocessed..

Type:: list

OBJDIR¶

The path to the object directory for this file.

Type:: str

Is is the same as TOPOBJDIR + RELATIVEDIR.

RELATIVEDIR¶

Constant defining the relative path of this file.

Type:: str

The relative path is from TOPSRCDIR. This is defined as relative to the main file being executed, regardless of whether additional files have been included using include().

RESOURCE_FILES¶

List of resources to be exported, and in which subdirectories.

Type:: list

RESOURCE_FILES is used to list the resource files to be exported to dist/bin/res, but it can be used for other files as well. This variable behaves as a list when appending filenames for resources in the top-level directory. Files can also be appended to a field to indicate which subdirectory they should be exported to. For example, to export foo.res to the top-level directory, and bar.res to fonts/, append to RESOURCE_FILES like so:

RESOURCE_FILES += ['foo.res']
RESOURCE_FILES.fonts += ['bar.res']

SRCDIR¶

Constant defining the source directory of this file.

Type:: str

This is the path inside TOPSRCDIR where this file is located. It is the same as TOPSRCDIR + RELATIVEDIR.

TESTING_JS_MODULES¶

JavaScript modules to install in the test-only destination.

Type:: list

Some JavaScript modules are test-only and not distributed with Firefox. This variable defines them.

To install modules in a subdirectory, use properties of this variable to control the final destination. e.g.

TESTING_JS_MODULES.foo += ['module.sys.mjs'].

TEST_DIRS¶

Like DIRS but only for directories that contain test-only code.

Type:: list

If tests are not enabled, this variable will be ignored.

This variable may go away once the transition away from Makefiles is complete.

TOPOBJDIR¶

Constant defining the top object directory.

Type:: str

The top object directory is the parent directory which will contain the output of the build. This is commonly referred to as “the object directory.”

TOPSRCDIR¶

Constant defining the top source directory.

Type:: str

The top source directory is the parent directory containing the source code and all build files. It is typically the root directory of a cloned repository.

mozbuild Sandbox Symbols¶

Sub-Context: Files¶

BUG_COMPONENT¶

FINAL¶

SCHEDULES¶

Variables¶

A11Y_MANIFESTS¶

ANDROID_INSTRUMENTATION_MANIFESTS¶

ASFLAGS¶

ASM_FLAGS¶

BROWSER_CHROME_MANIFESTS¶

CFLAGS¶

CMFLAGS¶

CMMFLAGS¶

COMPILE_FLAGS¶

CONFIGURE_DEFINE_FILES¶

CONFIGURE_SUBST_FILES¶

CPP_UNIT_TESTS¶

CRASHTEST_MANIFESTS¶

CXXFLAGS¶

DEFFILE¶

DEFINES¶

DELAYLOAD_DLLS¶

DIRS¶

DIST_INSTALL¶

DIST_SUBDIR¶

EXPORTS¶

EXTRA_DSO_LDOPTS¶

FILES_PER_UNIFIED_FILE¶

FINAL_LIBRARY¶

FINAL_TARGET¶

FINAL_TARGET_FILES¶

FINAL_TARGET_PP_FILES¶

FIREFOX_UI_FUNCTIONAL_MANIFESTS¶

FORCE_SHARED_LIB¶

FORCE_STATIC_LIB¶

GENERATED_EVENTS_WEBIDL_FILES¶

GENERATED_FILES¶

GENERATED_WEBIDL_FILES¶

GYP_DIRS¶

HOST_CFLAGS¶

HOST_COMPILE_FLAGS¶

HOST_CXXFLAGS¶

HOST_DEFINES¶

HOST_LIBRARY_NAME¶

HOST_OS_LIBS¶

HOST_PROGRAM¶

HOST_RUST_LIBRARY_FEATURES¶

HOST_RUST_PROGRAMS¶

HOST_SIMPLE_PROGRAMS¶

HOST_SOURCES¶

HOST_USE_LIBS¶

IPDL_SOURCES¶

IS_FRAMEWORK¶

IS_GKRUST¶

IS_RUST_LIBRARY¶

JAR_MANIFESTS¶

LDFLAGS¶

LIBRARY_DEFINES¶

LIBRARY_NAME¶

LINK_FLAGS¶

LOCALIZED_FILES¶

LOCALIZED_GENERATED_FILES¶

LOCALIZED_PP_FILES¶

LOCAL_INCLUDES¶

MARIONETTE_MANIFESTS¶

METRO_CHROME_MANIFESTS¶

MOCHITEST_CHROME_MANIFESTS¶

MOCHITEST_MANIFESTS¶

NO_EXPAND_LIBS¶

NO_PGO¶

OBJDIR_FILES¶

OBJDIR_PP_FILES¶

OS_LIBS¶

PERFTESTS_MANIFESTS¶

PREPROCESSED_IPDL_SOURCES¶

PREPROCESSED_TEST_WEBIDL_FILES¶

PREPROCESSED_WEBIDL_FILES¶

PROGRAM¶

PYTHON_UNITTEST_MANIFESTS¶