mozbuild Sandbox Symbols¶
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. *.jsm
- Will match all
.jsm
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. ('Core', 'Build Config')
.
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.
IMPACTED_TESTS¶
File patterns, tags, and flavors for tests relevant to these files.
Storage Type: | _TypedRecord |
---|---|
Input Type: | list |
Maps source files to the tests potentially impacted by those files. Tests can be specified by file pattern, tag, or flavor.
For example:
- with Files(‘runtests.py’):
- IMPACTED_TESTS.files += [
- ‘**’,
]
in testing/mochitest/moz.build will suggest that any of the tests under testing/mochitest may be impacted by a change to runtests.py.
File patterns may be made relative to the topsrcdir with a leading ‘/’, so
- with Files(‘httpd.js’):
- IMPACTED_TESTS.files += [
- ‘/testing/mochitest/tests/Harness_sanity/**’,
]
in netwerk/test/httpserver/moz.build will suggest that any change to httpd.js will be relevant to the mochitest sanity tests.
Tags and flavors are sorted string lists (flavors are limited to valid values).
For example:
- with Files(‘toolkit/devtools/*’):
- IMPACTED_TESTS.tags += [
- ‘devtools’,
]
in the root moz.build would suggest that any test tagged ‘devtools’ would potentially be impacted by a change to a file under toolkit/devtools, and
- with Files(‘dom/base/nsGlobalWindow.cpp’):
- IMPACTED_TESTS.flavors += [
- ‘mochitest’,
]
Would suggest that nsGlobalWindow.cpp is potentially relevant to any plain mochitest.
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_APK_NAME¶
The name of an Android APK file to generate.
Storage Type: | unicode |
---|---|
Input Type: | unicode |
ANDROID_APK_PACKAGE¶
The name of the Android package to generate R.java for, like org.mozilla.gecko.
Storage Type: | unicode |
---|---|
Input Type: | unicode |
ANDROID_ASSETS_DIRS¶
Android assets directories.
Storage Type: | _TypedListWithItems |
---|---|
Input Type: | list |
This variable contains a list of directories containing static files to package into an ‘assets’ directory and merge into an APK file.
ANDROID_EXTRA_PACKAGES¶
The name of extra Android packages to generate R.java for, like [‘org.mozilla.other’].
Storage Type: | StrictOrderingOnAppendList |
---|---|
Input Type: | list |
ANDROID_EXTRA_RES_DIRS¶
Android extra package resource directories.
Storage Type: | _TypedListWithItems |
---|---|
Input Type: | list |
This variable contains a list of directories containing static files to package into a ‘res’ directory and merge into an APK file. These directories are packaged into the APK but are assumed to be static unchecked dependencies that should not be otherwise re-distributed.
ANDROID_GENERATED_RESFILES¶
Android resource files generated as part of the build.
Storage Type: | StrictOrderingOnAppendList |
---|---|
Input Type: | list |
This variable contains a list of files that are expected to be generated (often by preprocessing) into a ‘res’ directory as part of the build process, and subsequently merged into an APK file.
ANDROID_INSTRUMENTATION_MANIFESTS¶
List of manifest files defining Android instrumentation tests.
Storage Type: | _OrderedListWithAction |
---|---|
Input Type: | list |
ANDROID_RES_DIRS¶
Android resource directories.
Storage Type: | _TypedListWithItems |
---|---|
Input Type: | list |
This variable contains a list of directories containing static files to package into a ‘res’ directory and merge into an APK file.
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 manipulated
Storage Type: | AsmFlags |
---|---|
Input Type: | dict |
directly.
BRANDING_FILES¶
List of files to be installed into the branding directory.
Storage Type: | _TypedListWithItems |
---|---|
Input Type: | list |
BRANDING_FILES
will copy (or symlink, if the platform supports it)
the contents of its files to the dist/branding
directory. Files that
are destined for a subdirectory can be specified by accessing a field.
For example, to export foo.png
to the top-level directory and
bar.png
to the directory images/subdir
, append to
BRANDING_FILES
like so:
BRANDING_FILES += ['foo.png']
BRANDING_FILES.images.subdir += ['bar.png']
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: | unicode |
---|---|
Input Type: | unicode |
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. These could also be combined into a single
update:
DEFINES.update({
'NS_NO_XPCOM': True,
'MOZ_EXTENSIONS_DB_SCHEMA': 15,
'DLL_SUFFIX': '".so"',
})
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: | unicode |
---|---|
Input Type: | unicode |
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: | unicode |
---|---|
Input Type: | unicode |
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: | unicode |
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 |
FIREFOX_UI_UPDATE_MANIFESTS¶
List of manifest files defining firefox-ui-update 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 |
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
and flags
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.
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’, (…)} (…)
HAS_MISC_RULE¶
Whether this directory should be traversed in the misc
tier.
Storage Type: | bool |
---|---|
Input Type: | bool |
Many libs
rules still exist in Makefile.in files. We highly prefer
that these rules exist in the misc
tier/target so that they can be
executed concurrently during tier traversal (the misc
tier is
fully concurrent).
Presence of this variable indicates that this directory should be
traversed by the misc
tier.
Please note that converting libs
rules to the misc
tier must
be done with care, as there are many implicit dependencies that can
break the build in subtle ways.
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: | unicode |
---|---|
Input Type: | unicode |
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: | unicode |
---|---|
Input Type: | unicode |
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_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.
JAVA_JAR_TARGETS¶
Defines Java JAR targets to be built.
Storage Type: | dict |
---|---|
Input Type: | dict |
This variable should not be populated directly. Instead, it should populated by calling add_java_jar().
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: | unicode |
---|---|
Input Type: | unicode |
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
Paths specified here must be relative to the source directory and 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.
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_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_LAYOUT_MANIFESTS¶
List of manifest files defining marionette-layout tests.
Storage Type: | _OrderedListWithAction |
---|---|
Input Type: | list |
MARIONETTE_UNIT_MANIFESTS¶
List of manifest files defining marionette-unit tests.
Storage Type: | _OrderedListWithAction |
---|---|
Input Type: | list |
MARIONETTE_WEBAPI_MANIFESTS¶
List of manifest files defining marionette-webapi 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_COMPONENTS_MANIFEST¶
Do not create a binary-component manifest entry for the
Storage Type: | bool |
---|---|
Input Type: | bool |
corresponding XPCOMBinaryComponent.
NO_EXPAND_LIBS¶
Forces to build a real static library, and no corresponding fake
Storage Type: | bool |
---|---|
Input Type: | bool |
library.
NO_JS_MANIFEST¶
Explicitly disclaims responsibility for manifest listing in EXTRA_COMPONENTS.
Storage Type: | bool |
---|---|
Input Type: | bool |
Normally, if you have .js files listed in EXTRA_COMPONENTS
or
EXTRA_PP_COMPONENTS
, you are expected to have a corresponding
.manifest file to go with those .js files. Setting NO_JS_MANIFEST
indicates that the relevant .manifest file and entries for those .js
files are elsehwere (jar.mn, for instance) and this state of affairs
is OK.
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.
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.
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: | unicode |
---|---|
Input Type: | unicode |
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.
PUPPETEER_FIREFOX_MANIFESTS¶
List of manifest files defining puppeteer unit tests for Firefox.
Storage Type: | _OrderedListWithAction |
---|---|
Input Type: | list |
PYTHON_UNITTEST_MANIFESTS¶
List of manifest files defining python unit tests.
Storage Type: | _OrderedListWithAction |
---|---|
Input Type: | list |
RCFILE¶
The program .rc file.
Storage Type: | unicode |
---|---|
Input Type: | unicode |
This variable can only be used on Windows.
RCINCLUDE¶
The resource script file to be included in the default .res file.
Storage Type: | unicode |
---|---|
Input Type: | unicode |
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.
RESFILE¶
The program .res file.
Storage Type: | unicode |
---|---|
Input Type: | unicode |
This variable can only be used on Windows.
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_TARGET_DIR¶
Where CARGO_TARGET_DIR should point when compiling this library. If
Storage Type: | unicode |
---|---|
Input Type: | unicode |
not set, it defaults to the current objdir. It should be a relative path to the current objdir; absolute paths should not be used.
This variable should not be used directly; you should be using the RustLibrary template instead.
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_TEST¶
Name of a Rust test to build and run via cargo test.
Storage Type: | unicode |
---|---|
Input Type: | unicode |
This variable should not be used directly; you should be using the RustTest template instead.
RUST_TEST_FEATURES¶
Cargo features to activate for RUST_TEST.
Storage Type: | List |
---|---|
Input Type: | list |
This variable should not be used directly; you should be using the RustTest template instead.
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: | unicode |
---|---|
Input Type: | unicode |
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: | unicode |
---|---|
Input Type: | unicode |
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: | unicode |
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.
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_LIBS¶
List of libraries to link to programs and libraries.
Storage Type: | StrictOrderingOnAppendList |
---|---|
Input Type: | list |
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.
USE_YASM¶
Use the yasm 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 yasm instead.
If yasm is not available on this system, or does not support the current target architecture, an error will be raised.
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.
WEBRTC_SIGNALLING_TEST_MANIFESTS¶
List of manifest files defining WebRTC signalling tests.
Storage Type: | _OrderedListWithAction |
---|---|
Input Type: | list |
WEB_PLATFORM_TESTS_MANIFESTS¶
List of (manifest_path, test_path) defining web-platform-tests.
Storage Type: | _TypedListWithAction |
---|---|
Input Type: | list |
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.
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: | unicode |
---|---|
Input Type: | unicode |
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_NO_MANIFEST¶
Indicate that the XPIDL module should not be added to a manifest.
Storage Type: | bool |
---|---|
Input Type: | bool |
This flag exists primarily to prevent test-only XPIDL modules from being added to the application’s chrome manifest. Most XPIDL modules should not use this flag.
XPIDL_SOURCES¶
XPCOM Interface Definition Files (xpidl).
Storage Type: | StrictOrderingOnAppendList |
---|---|
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: | unicode |
---|---|
Input Type: | unicode |
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¶
add_java_jar¶
Declare a Java JAR target to be built.
Arguments: | (str) |
---|
This is the supported way to populate the JAVA_JAR_TARGETS variable.
The parameters are: * dest - target name, without the trailing .jar. (required)
This returns a rich Java JAR type, described at
mozbuild.frontend.data.JavaJarData
.
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 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.
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 (JSMs) 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.jsm']
.
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.