Note: Do not make substantive changes to this document without consulting Benjamin Smedberg <[email protected]> or one of the build-config peers.
This document details how to configure Firefox builds. Most of the time a mozconfig
file is not required. The default options are the most well-supported, so it is preferable to add as few options as possible. Please read the following directions carefully before building, and follow them in order. Skipping any step may cause the build to fail, or the built software to be unusable. Build options, including options not usable from the command-line, may appear in "confvars.sh" files in the source tree.
Using a mozconfig
configuration file
The choice of which Mozilla application to build and other configuration options can be configured in a mozconfig
file. (It is possible to manually call configure
with command-line options, but this is not recommended). The mozconfig
file should be in your source directory (that is, /mozilla-central/mozconfig
or /comm-central/mozconfig
).
Create a blank mozconfig
file:
echo "# My first mozilla config" > mozconfig
You can also use the MOZCONFIG
environment variable to specify the path to your mozconfig
, but the path you specify must be an absolute path or else client.mk
will not find it. This is useful if you choose to have multiple mozconfig
files for different applications or configurations (see below for a full example). Note that in the export
example below the filename was not mozconfig
. Regardless of the name of the actual file you use, we refer to this file as the mozconfig
file in the examples below.
Setting the mozconfig
path:
export MOZCONFIG=~/mozilla/mozconfig-firefox
Calling the file .mozconfig
(with a leading dot) is also supported, but this is not recommended because it may make the file harder to find. This will also help when troubleshooting because people will want to know which build options you have selected and will assume that you have put them in your mozconfig
file.
mozconfig
contains two types of options:
- Options prefixed with
mk_add_options
are passed toclient.mk
. The most important of these isMOZ_OBJDIR
, which controls where your application gets built (also known as the object directory). - Options prefixed with
ac_add_options
are passed toconfigure
, and affect the build process.
Building with an objdir
This means that the source code and object files are not intermingled in your directory system and you can build multiple applications (e.g., Firefox and Thunderbird) from the same source tree. If you do not specify a MOZ_OBJDIR
, it will be automatically set to @TOPSRCDIR@/obj-@CONFIG_GUESS@
.
If you need to re-run configure
, the easiest way to do it is using ./mach configure
; running configure
manually is strongly discouraged.
Adding the following line to your mozconfig
allows you to change the objdir:
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-@CONFIG_GUESS@
It is a good idea to have your objdir name start with obj
so that Mercurial ignores it.
Parallel compilation
Most modern systems have multiple cores or CPUs, and they can be optionally used concurrently to make the build faster. The -j
flag controls how many parallel builds will run concurrently. You will see (diminishing) returns up to a value approximately 1.5× to 2.0× the number of cores on your system.
mk_add_options MOZ_MAKE_FLAGS="-j4"
If your machine is overheating, you might want to try a lower value, e.g. -j1
.
Choose an application
The --enable-application=application
flag is used to select an application to build. Firefox is the default.
Choose one of the following options to add to your mozconfig
file:
- Browser (Firefox)
-
ac_add_options --enable-application=browser
Note: This is the default
- Mail (Thunderbird)
-
ac_add_options --enable-application=mail
- Mozilla Suite (SeaMonkey)
-
ac_add_options --enable-application=suite
- Calendar (Lightning Extension, uses Thunderbird)
-
ac_add_options --enable-application=mail ac_add_options --enable-calendar
- XULRunner
-
ac_add_options --enable-application=xulrunner
Selecting build options
The build options you choose depends on what application you are building and what you will be using the build for. If you want to use the build regularly, you will want a release build without extra debugging information; if you are a developer who wants to hack the source code, you probably want a non-optimized build with extra debugging macros.
There are many options recognized by the configure script which are special-purpose options intended for embedders or other special situations, and should not be used to build the full suite/XUL applications. The full list of options can be obtained by running ./configure --help
.
Warning: Do not use a configure option unless you know what it does. The default values are usually the right ones. Each additional option you add to your mozconfig
file reduces the chance that your build will compile and run correctly.
The following build options are very common:
Optimization
- ac_add_options --enable-optimize
-
Enables the default compiler optimization options
Note: This is enabled by default
- ac_add_options --enable-optimize=-O2
- Chooses particular compiler optimization options. In most cases, this will not give the desired results, unless you know the Mozilla codebase very well; note, however, that if you are building with the Microsoft compilers, you probably do want this as
-O1
will optimize for size, unlike GCC. - ac_add_options --enable-debug
- Enables assertions in C++ and JavaScript, plus other debug-only code. This can significantly slow a build, but it is invaluable when writing patches. People developing patches (especially in C++) should generally use this option.
- ac_add_options --disable-optimize
- Disables compiler optimization. This makes it much easier to step through code in a debugger.
- ac_add_options --enable-debug-js-modules
- Enable only JavaScript assertions. This is useful when working locally on JavaScript-powered components like the DevTools. This will help catch any errors introduced into the JS code, with less of a performance impact compared to the
--enable-debug
option.
You can make an optimized build with debugging symbols. See Building Firefox with Debug Symbols.
Extensions
- ac_add_options --enable-extensions=default|all|ext1,ext2,-skipext3
- There are many optional pieces of code that live in
extensions/
. Many of these extensions are now considered an integral part of the browsing experience. There is a default list of extensions for the suite, and each app-specificmozconfig
specifies a different default set. Some extensions are not compatible with all apps, for example:cookie
is not compatible with thunderbirdtypeaheadfind
is not compatible with any toolkit app (Firefox, Thunderbird)
Unless you know which extensions are compatible with which apps, do not use the --enable-extensions option; the build system will automatically select the proper default set of extensions.
Tests
- ac_add_options --disable-tests
- By default, many auxiliary test applications are built, which can help debug and patch the mozilla source. Disabling these tests can speed build time and reduce disk space considerably. Developers should generally not use this option.
Localization
- mk_add_options MOZ_CO_LOCALES=ISOcode
- TBD.
- ac_add_options --enable-ui-locale=ISOcode
- TBD.
- ac_add_options --with-l10n-base=/path/to/base/dir
- TBD.
Other Options
- mk_add_options AUTOCLOBBER=1
- If a clobber would be required before a build, this will cause mach to clobber and continue with the build instead of asking the user to manually clobber and exiting.
- ac_add_options --disable-crypto
- Cryptography is enabled by default. In some countries, it may be illegal to use or export cryptographic software. You should become familiar with the cryptography laws in your country.
On the 1.7 and aviary branches, cryptography was off by default. You need to specify
--enable-crypto
if you want SSL, S/MIME, or other software features that require cryptography.
Example mozconfig
Files
Mozilla's official builds use mozconfig files from the appropriate directory within each repository.
Warning: These mozconfig
files are taken from production builds and are provided as examples only. It is recommended to use the default build options, and only change the properties from the list above as needed. The production builds aren't really appropriate for local builds.
-
Firefox, Default Release Configuration (Mac OS X, universal build)
-
Firefox, Debugging Build (Mac OS X 64bits)
-
Thunderbird, Debugging Build (Linux 64 bits)
Building multiple applications from the same source tree
It is possible to build multiple applications from the same source tree, as long as you use a different objdir for each application.
You can either create multiple mozconfig
files, or alternatively, use the MOZ_BUILD_PROJECTS
make option.
Using MOZ_BUILD_PROJECTS
in a single mozconfig
To use MOZ_BUILD_PROJECTS
, you must specify a MOZ_OBJDIR
and a MOZ_BUILD_PROJECTS
make option, containing space separated names. Each name can be an arbitrary directory name. For each name, a subdirectory is created under the toplevel objdir. You then need to use the ac_add_app_options
with the specified names to enable different applications in each object directory.
For example:
ac_add_options --disable-optimize --enable-debug mk_add_options MOZ_OBJDIR=/mozilla/src/obj-@CONFIG_GUESS@ mk_add_options MOZ_BUILD_PROJECTS="xulrunner browser mail" ac_add_app_options browser --enable-application=browser ac_add_app_options xulrunner --enable-application=xulrunner ac_add_app_options mail --enable-application=mail
If you want to build only one project using this mozconfig
, use the following command line:
MOZ_CURRENT_PROJECT=browser ./mach build
This will build only browser.
Using multiple mozconfig files
Alternatively, you may want to create separate mozconfig
files.
As an example, the following steps can be used to build Firefox and Thunderbird. You should first create three mozconfig
files.
mozconfig-common
:
# add common options here, such as making an optimized release build mk_add_options MOZ_MAKE_FLAGS="-j4" ac_add_options --enable-optimize --disable-debug
mozconfig-firefox
:
# include the common mozconfig . ./mozconfig-common # Build Firefox mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-firefox ac_add_options --enable-application=browser
mozconfig-thunderbird
:
# include the common mozconfig . ./mozconfig-common # Build Thunderbird mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-thunderbird ac_add_options --enable-application=mail
To build Firefox, run the following commands:
export MOZCONFIG=/path/to/mozilla/mozconfig-firefox ./mach build
To build Thunderbird, run the following commands:
export MOZCONFIG=/path/to/mozilla/mozconfig-thunderbird ./mach build
Using mozconfigwrapper
Mozconfigwrapper is similar to using multiple mozconfig files except that it abstracts and hides them so you don't have to worry about where they live or which ones you've created. It also saves you from having to export the MOZCONFIG variable each time. For information on installing and configuring mozconfigwrapper, see https://github.com/ahal/mozconfigwrapper.