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

A11Y_MANIFESTS

List of manifest files defining a11y tests.

Storage Type:

_OrderedListWithAction

Input Type:

list

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.

CRAMTEST_MANIFESTS

List of manifest files defining cram unit tests.

Storage Type:

_OrderedListWithAction

Input Type:

list

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.

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.

  1. 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.