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 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. ('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.

Variables

A11Y_MANIFESTS

List of manifest files defining a11y tests.

Storage Type:_OrderedListWithAction Input Type:list

ALLOW_COMPILER_WARNINGS

Whether to allow compiler warnings (i.e. not treat them as

Storage Type:bool Input Type:bool

errors).

This is commonplace (almost mandatory, in fact) in directories containing third-party code that we regularly update from upstream and thus do not control, but is otherwise discouraged.

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_ECLIPSE_PROJECT_TARGETS

Defines Android Eclipse project targets.

Storage Type:dict Input Type:dict

This variable should not be populated directly. Instead, it should populated by calling add_android_eclipse{_library}_project().

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.

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.

CONFIGURE_DEFINE_FILES

Output files generated from configure/config.status.

Storage Type:_TypedList Input Type:list

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

CONFIGURE_SUBST_FILES

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

Storage Type:_TypedList Input Type:list

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

CPP_UNIT_TESTS

Compile a list of C++ unit test names.

Storage Type:StrictOrderingOnAppendList Input Type:list

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

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

CRASHTEST_MANIFESTS

List of manifest files defining crashtests.

Storage Type:_OrderedListWithAction Input Type:list

These are commonly named crashtests.list.

CXXFLAGS

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

Storage Type:List Input Type:list

declared in this directory.

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

DEFFILE

The program .def (module definition) file.

Storage Type: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.

DISABLE_STL_WRAPPING

Disable the wrappers for STL which allow it to work with C++ exceptions

Storage Type:bool Input Type:bool

disabled.

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

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

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 and inputs flags on individual entries. If the optional script flag 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.

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.
• non_unified_sources, a list containing sources files, relative to the current moz.build, that should be excluded from source file unification.

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_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_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_COMPONENT

Whether the library contains a binary XPCOM component manifest.

Storage Type:bool Input Type:bool

Implies FORCE_SHARED_LIB. This variable is only available in templates.

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.

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().

JETPACK_ADDON_MANIFESTS

List of manifest files defining jetpack addon tests.

Storage Type:_OrderedListWithAction Input Type:list

JETPACK_PACKAGE_MANIFESTS

List of manifest files defining jetpack package tests.

Storage Type:_OrderedListWithAction Input Type:list

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.

LD_VERSION_SCRIPT

The linker version script for shared libraries.

Storage Type:unicode Input Type:unicode

This variable can only be used on Linux.

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.

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_LOOP_MANIFESTS

List of manifest files defining marionette-loop 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_UPDATE_MANIFESTS

List of manifest files defining marionette-update 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

NO_VISIBILITY_FLAGS

Build sources listed in this file without VISIBILITY_FLAGS.

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.

PYTHON_UNIT_TESTS

A list of python unit tests.

Storage Type:StrictOrderingOnAppendList 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.

SDK_FILES

List of files to be installed into the sdk directory.

Storage Type:_TypedListWithItems Input Type:list

SDK_FILES will copy (or symlink, if the platform supports it) the contents of its files to the dist/sdk directory. Files that are destined for a subdirectory can be specified by accessing a field. For example, to export foo.py to the top-level directory and bar.py to the directory subdir, append to SDK_FILES like so:

SDK_FILES += ['foo.py']
SDK_FILES.subdir += ['bar.py']

SDK_LIBRARY

Whether the library built in the directory is part of the SDK.

Storage Type:bool Input Type:bool

The library will be copied into SDK_LIB_DIR ($DIST/sdk/lib).

SHARED_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_SHARED_LIB.

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:SourcePath 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_android_eclipse_library_project

Declare an Android Eclipse library project.

Arguments:(str)

This is one of the supported ways to populate the ANDROID_ECLIPSE_PROJECT_TARGETS variable.

The parameters are: * name - project name.

This returns a rich Android Eclipse project type, described at mozbuild.frontend.data.AndroidEclipseProjectData.

add_android_eclipse_project

Declare an Android Eclipse project.

Arguments:(str, str)

This is one of the supported ways to populate the ANDROID_ECLIPSE_PROJECT_TARGETS variable.

The parameters are: * name - project name. * manifest - path to AndroidManifest.xml.

This returns a rich Android Eclipse project type, described at mozbuild.frontend.data.AndroidEclipseProjectData.

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.

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