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 thefoo/
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 thebar/
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_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 (seeLOCALIZED_FILES
for a discussion of the specifics). Paths ininputs
starting withen-US/
or containinglocales/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
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.