Configuring Build Options

• Edit
• Watch

Table of contents

1. 1. Using a .mozconfig configuration file
2. 2. Building with an Objdir
3. 3. Parallel compilation
4. 4. Choose an application
5. 5. Selecting Build Options
   1. 5.1. Optimization
   2. 5.2. Graphics Toolkit
   3. 5.3. Extensions
   4. 5.4. Tests
   5. 5.5. Other Options
6. 6. Example .mozconfig Files
   1. 6.1. Firefox, Default Release Configuration
   2. 6.2. Firefox, Debugging Build
   3. 6.3. Firefox, disable-libxul debug build
   4. 6.4. Thunderbird, Debugging Build
   5. 6.5. SeaMonkey, Optimized (but not static)
   6. 6.6. XULRunner, Minimal Release Build
7. 7. Building multiple applications from the same source tree
   1. 7.1. Using MOZ_BUILD_PROJECTS in a single mozconfig
   2. 7.2. Using multiple mozconfig files
8. 8. Complete List of configure Options
   1. 8.1. Specific to testing and/or profiling
   2. 8.2. Platform-specific Options
   3. 8.3. System-Replacement Options
   4. 8.4. Other Commonly Used Options
   5. 8.5. Other Not So Commonly Used Options

• Tags
• Files

Page Notifications Off

Table of contents

1. 1. Using a .mozconfig configuration file
2. 2. Building with an Objdir
3. 3. Parallel compilation
4. 4. Choose an application
5. 5. Selecting Build Options
   1. 5.1. Optimization
   2. 5.2. Graphics Toolkit
   3. 5.3. Extensions
   4. 5.4. Tests
   5. 5.5. Other Options
6. 6. Example .mozconfig Files
   1. 6.1. Firefox, Default Release Configuration
   2. 6.2. Firefox, Debugging Build
   3. 6.3. Firefox, disable-libxul debug build
   4. 6.4. Thunderbird, Debugging Build
   5. 6.5. SeaMonkey, Optimized (but not static)
   6. 6.6. XULRunner, Minimal Release Build
7. 7. Building multiple applications from the same source tree
   1. 7.1. Using MOZ_BUILD_PROJECTS in a single mozconfig
   2. 7.2. Using multiple mozconfig files
8. 8. Complete List of configure Options
   1. 8.1. Specific to testing and/or profiling
   2. 8.2. Platform-specific Options
   3. 8.3. System-Replacement Options
   4. 8.4. Other Commonly Used Options
   5. 8.5. Other Not So Commonly Used Options

 

 

Gecko 5.0+ note

(Firefox 5.0+)

 

Starting with Gecko 5.0 (Firefox 5.0) , building Firefox has become extremely simple. The default application is now Firefox, so you can build Firefox by simply doing configure && make (for downloaded code) or make -f client.mk (for code from the Mercurial repository); this will build something roughly the same as the shipped version of Firefox corresponding to the code you have. You only need to follow the steps below if you want to customize the build (e.g. to create a debug build, or a release build with debug symbols), you want to build something other than Firefox, or you want to build pre-gecko 5.0 source.

If you are building Mozilla source code from before Firefox 5, then you must first select the Mozilla application that you want to build (see below), and you will probably also need to set at least some of the other basic configuration options (such as whether to build a debug build or not) to get the type of build that you need.

Please read the following directions carefully before building, and follow them in order. If you skip any steps, you may find that you can't build the software, or that the build result isn't usable. Note that build options, including options not usable from the command-line, may appear in "confvars.sh" files in the source tree.

Note: On Mac OS X, you may want to take into consideration the concept of building universal binaries.

 

Build Instructions:

• Requirements
• Source
• Configuration
• Build
• Frequently Asked Questions
• More...

 

Using a .mozconfig configuration file

The choice of which Mozilla application to build and other configuration options should be set in a .mozconfig file. (It is possible to manually call configure with command-line options, but this is not recommended.) The .mozconfig file in your source directory (when using CVS this means mozilla/.mozconfig) or in your HOME directory (~/.mozconfig).

NOTE: Placing .mozconfig as mentioned above is appropriate for Firefox or XULRunner. For Seamonkey, Thunderbird, and other comm-central apps, you place it in /src and not in /src/mozilla.

This will also help when troubleshooting as people will want to know which build options you have selected and will assume that you have put them in your .mozconfig file.

 echo "# My first mozilla config" > .mozconfig

You can also use the name mozconfig (without the leading dot) for this file, which has the advantage that the file will be visible in directory listings.

.mozconfig contains two types of options:

• Options prefixed with mk_add_options are passed to client.mk.  The most important of these is MOZ_OBJDIR, which controls where your application gets built (also known as the object directory). 
  
  • If you are building from an older project branch that still uses CVS, you will need to set MOZ_CO_PROJECT to the appropriate value or values, using a comma-separated list, such as "mk_add_options MOZ_CO_PROJECT=browser,mail,calendar,suite,xulrunner".  This setting is ignored by most Mozilla project branches, which now use mercurial instead of CVS for source control.
• Options prefixed with ac_add_options are passed to configure, and effect the build process.

These options will be automatically used when ./configure or make -f client.mk are run.

At the bottom of this page are several example .mozconfig files.

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:

export MOZCONFIG=~/mozilla/mozconfig-firefox

This is useful if you choose to have multiple .mozconfig files for different applications or configurations. Note that in this 'export' example 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.

Building with an Objdir

It is highly recommended that you use an objdir when building mozilla. This means that the source code and object files are not intermingled in your directory system. If you use an objdir, you can build multiple applications (e.g. Firefox and Thunderbird) from the same source tree.

The act of using an objdir means that every Makefile.in file in your source tree will be turned into a Makefile in the objdir. The parent directories of the Makefile.in will be the same parent directories in objdir. For example, for the file mozilla/modules/plugin/base/src/Makefile.in, with an objdir value of @TOPSRCDIR@/obj-debug, the file and directory path mozilla/obj-debug/modules/plugin/base/src/Makefile will be created. This Makefile will magically refer to source files in the mozilla/modules/plugin/base/src directory.

If you need to re-run configure, the easiest way to do it is using make -f client.mk configure but if you want to run configure manually please do so from within your object directory, and do it by giving the absolute path to the configure script. For example, if you are running on Win32, and your source tree is in /c/Projects/FIREFOX/mozilla, then, from within your objdir you would need to run /c/Projects/FIREFOX/mozilla/configure whenever you need to manually run configure.

Adding the following line to your .mozconfig enables an objdir:

mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-@CONFIG_GUESS@

 

Gecko 2.0 note

(Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

 

Starting in Gecko 2.0, objdir builds are enabled by default.  If you do not specify a MOZ_OBJDIR it will be automatically set to @TOPSRCDIR@/obj-@CONFIG_GUESS@

Alternatively, you can run client.mk directly from your objdir, using make -f <path_to_srcdir>/client.mk

Parallel compilation

Most modern systems have multiple cores and/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.5x to 2.0x the number of cores on your system.

mk_add_options MOZ_MAKE_FLAGS="-j4"

NOTE: this is currently unreliable on Windows, and your build may fail. Windows users should instead use PyMake, which safely supports parallel compiles.

Choose an application

The --enable-application=application flag is used to select an application to build.

 

Gecko 5.0 note

(Firefox 5.0)

 

Starting in Gecko 5.0 (Firefox 5.0) , if you don't specify an application, --enable-application=browser is assumed, thereby building Firefox.

Choose one of the following options to add to your mozconfig file:

Browser (Firefox)

ac_add_options --enable-application=browser

Mail (Thunderbird)

ac_add_options --enable-application=mail

Mozilla Suite (SeaMonkey)

ac_add_options --enable-application=suite

Standalone Calendar (Sunbird)

ac_add_options --enable-application=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.

If you do not know what a configure option does, don't use it! The following build options are very common:

Optimization

ac_add_options --enable-optimize 

Enables the default compiler optimization options

ac_add_options --enable-optimize=-O2 

Choose particular compiler optimization options. In most cases, this will not give the desired results, unless you know the mozilla codebase very well.

ac_add_options --enable-debug 

Enables verbose debugging macros and other debug-only code. This can significantly slow a build, but it is invaluable when writing patches.

ac_add_options --disable-optimize 

Disables compiler optimization. This makes it much easier to step through code in a debugger.

You can make an optimized build with debugging symbols. See Building Firefox with Debug Symbols.

Graphics Toolkit

ac_add_options --enable-default-toolkit=gtk2|gtk|xlib|qt|cairo-gtk2|cairo-qt|cairo-windows|windows|mac|cocoa|cairo-cocoa|os2|beos|photon

Selects the graphics toolkit.

On trunk / 1.9 (Firefox 3), this should not be needed in any platform; manually selecting a graphics toolkit is likely to result in a non-working or otherwise highly buggy build. The available toolkits differ from those listed above.

For 1.8 branch, this is not needed for Windows/OS2/BeOS/Photon, since these platforms automatically select the correct toolkit. It is also not needed on Mac, unless you are building Camino on an older branch (Camino uses --enable-default-toolkit=cocoa).

On *nix platforms, selects the graphics toolkit to use. GTK2 and GTK were both well-tested. xlib was considered a tier-3 platform. Qt and cairo were experimental, you will find bugs.

ac_add_options --enable-libxul (default)

Builds the core gecko components as a single library called libxul. This improves startup and runtime performance by reducing the number of relocations performed.

ac_add_options --enable-static --disable-libxul

These options build a larger single executable, which has components linked statically. --enable-static requires --disable-libxul. If you use --enable-static, it is recommended that you also --disable-tests. This option is not recommended for Firefox, Thunderbird, or SeaMonkey, and also no longer supported.

ac_add_options --disable-static --disable-libxul

These options make components into separate shared libraries. This makes debugging and incremental compiling much easier, but the resulting build is slower.

 

--disable-libxul is not directly supported by xulrunner without manually managing the dynamic library load path.

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-specific mozconfig specifies a different default set. Some extensions are not compatible with all apps, for example:

• cookie is not compatible with thunderbird
• typeaheadfind is not compatible with any toolkit app (Firefox, Thunderbird, Sunbird)

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

Other Options

 

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, SMIME, or other software features that require cryptography.

 

ac_add_options --disable-javaxpcom (No Java)

By default, XULRunner builds the Java-XPCOM bridge, which requires an installed JDK. If you get the following error during configure: The header jni.h was not found. Set $JAVA_HOME or use --with-java-include-path, then you can disable java dependencies using ac_add_options --disable-javaxpcom.

Example .mozconfig Files

Mozilla's official builds use mozconfig files from the appropriate directory within http://hg.mozilla.org/build/buildbot-configs/file/ such as win32/mozilla-2.0/nightly for the Firefox 4 (mozilla-2.0) nightly build.

Firefox, Default Release Configuration

. $topsrcdir/browser/config/mozconfigmk_add_options MOZ_OBJDIR=@TOPSRCDIR@/ff-optac_add_options --disable-tests

Firefox, Debugging Build

. $topsrcdir/browser/config/mozconfigmk_add_options MOZ_OBJDIR=@TOPSRCDIR@/ff-dbgac_add_options --disable-optimizeac_add_options --enable-debug ac_add_options --enable-tests

Firefox, disable-libxul debug build

libxul is a large (200mb) shared library, and linking it can be a major bottleneck in the build process. Disabling libxul may speed up incremental builds substantially, but doing so also disables support for out-of-process plugins (OOPP) and other features which rely on inter-process communication (IPC). Note that disabling libxul is no longer officially supported.

. $topsrcdir/browser/config/mozconfigmk_add_options MOZ_OBJDIR=@TOPSRCDIR@/ff-dbgac_add_options --disable-optimizeac_add_options --enable-debug ac_add_options --enable-testsac_add_options --disable-libxulac_add_options --disable-staticac_add_options --disable-ipcac_add_options --enable-chrome-format=jar

Thunderbird, Debugging Build

. $topsrcdir/mail/config/mozconfigmk_add_options MOZ_OBJDIR=@TOPSRCDIR@/tbird-debugac_add_options --disable-optimizeac_add_options --enable-debug

SeaMonkey, Optimized (but not static)

ac_add_options --enable-application=suitemk_add_options MOZ_OBJDIR=@TOPSRCDIR@/suite-optac_add_options --enable-optimizeac_add_options --disable-debug

XULRunner, Minimal Release Build

mk_add_options MOZ_OBJDIR=@topsrcdir@/obj-xulrunnerac_add_options --enable-application=xulrunner#ac_add_options --disable-javaxpcom

Building multiple applications from the same source tree

It is possible to build multiple applications from the same source tree, as long as you have checked out all the necessary sources and 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  ac_add_options --enable-default-toolkit=gtk2 --disable-freetype2 --enable-xft mk_add_options MOZ_OBJDIR=/home/amil082/mozilla_trunk/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 commandline:

 make -f client.mk build MOZ_CURRENT_PROJECT=browser

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 a static release build and# disabling testsac_add_options --enable-optimize --disable-debugac_add_options --disable-tests

mozconfig-firefox:

# include the common mozconfig. ./mozconfig-common# Build Firefoxmk_add_options MOZ_OBJDIR=@TOPSRCDIR@/firefox-staticac_add_options --enable-application=browser

mozconfig-thunderbird:

# include the common mozconfig. ./mozconfig-common# Build Thunderbirdmk_add_options MOZ_OBJDIR=@TOPSRCDIR@/thunderbird-staticac_add_options --enable-application=mail

To checkout, run the following commands:

export MOZCONFIG=/path/to/mozilla/mozconfig-commonmake -f client.mk checkout

To build Firefox, run the following commands:

export MOZCONFIG=/path/to/mozilla/mozconfig-firefoxmake -f client.mk build

To build Thunderbird, run the following commands:

export MOZCONFIG=/path/to/mozilla/mozconfig-thunderbirdmake -f client.mk build

Complete List of configure Options

 

Specific to testing and/or profiling

• --[enable/disable]-profiling
• --[enable/disable]-codesighs
• --[enable/disable]-dtrace
• --[enable/disable]-glibtest
• --[enable/disable]-jprof
• --[enable/disable]-libIDLtest
• --[enable/disable]-logging
• --[enable/disable]-logrefcnt
• --[enable/disable]-perf-metrics
• --[enable/disable]-shark
• --[enable/disable]-tests

Platform-specific Options

• --[enable/disable]-activex
• --[enable/disable]-activex-scripting
• --[enable/disable]-macos-target=VER
• --[enable/disable]-shark
• --with-macos-sdk=dir
• --[enable/disable]-os2-high-mem
• --with-windows-version=MOZ_WINSDK_TARGETVER

System-Replacement Options

These options are used to replace either some technology that is provided by most platforms to Mozilla apps or some technology usually supplied as part of the Mozilla platform, with another copy of that technology. If you do not see the point of this, or do not understand how to replace one of these technologies, just stay away from these options and things will be fine.

• --[enable/disable]-system-cairo
• --[enable/disable]-system-hunspell
• --[enable/disable]-system-lcms
• --[enable/disable]-system-sqlite
• --with-ft-exec-prefix=PFX
• --with-ft-prefix=PFX
• --with-glib-exec-prefix=PFX
• --with-glib-exec-prefix=PFX
• --with-glib-prefix=PFX
• --with-glib-prefix=PFX
• --with-java-bin-path=dir
• --with-java-include-path=dir
• --with-libIDL-exec-prefix=PFX
• --with-libIDL-prefix=PFX
• --with-libxul-sdk=PFX
• --with-nspr-exec-prefix=PFX
• --with-nspr-prefix=PFX
• --with-nss-exec-prefix=PFX
• --with-nss-prefix=PFX
• --with-system-bz2[=PFX]
• --with-system-jpeg[=PFX]
• --with-system-nspr
• --with-system-nss
• --with-system-png[=PFX]
• --with-system-zlib[=PFX]

Other Commonly Used Options

• --[enable/disable]-application=APP - see above.
• --[enable/disable]-crashreporter - on by default, may cause problems on Linux builds. See info in Linux Build Prerequisites.
• --[enable/disable]-debug[=DBG] - a master switch for debug output and other compilation and linking directives.
• --[enable/disable]-javaxpcom
• --[enable/disable]-optimize
• --[enable/disable]-optimize=[OPT]
• --[enable/disable]-plugins
• --[enable/disable]-static
• --help - prints out a list of available options for the configure executable.
• --with-pthreads

Other Not So Commonly Used Options

• --[enable/disable]-accessibility - tested and works well in shipping software. This may not be turned on in early versions, and so will be less stable. See the mozilla.dev.accessibility newsgroup on news.mozilla.org for more info.

• --[enable/disable]-auto-deps
• --[enable/disable]-chrome-format=jar|flat|both|symlink|omni
• --[enable/disable]-compile-environment
• --[enable/disable]-composer
• --[enable/disable]-cpp-exceptions
• --[enable/disable]-cpp-rtti
• --[enable/disable]-crypto
• --[enable/disable]-dbus
• --[enable/disable]-default-toolkit=TK
• --[enable/disable]-elf-dynstr-gc
• --[enable/disable]-extensions
• --[enable/disable]-gnomeui
• --[enable/disable]-gnomevfs
• --[enable/disable]-help-viewer
• --[enable/disable]-image-encoders[={mod1,mod2,default,all,none}]
• --[enable/disable]-install-strip
• --[enable/disable]-installer
• --[enable/disable]-jemalloc
• --[enable/disable]-jit
• --[enable/disable]-js-static-build
• --[enable/disable]-js-ultrasparc
• --[enable/disable]-jsd
• --[enable/disable]-ldap
• --[enable/disable]-ldap-experimental
• --[enable/disable]-leaky
• --[enable/disable]-mailnews
• --[enable/disable]-md
• --[enable/disable]-native-uconv
• --[enable/disable]-necko-disk-cache
• --[enable/disable]-necko-protocols[={http,ftp,default,all,none}]
• --[enable/disable]-necko-small-buffers
• --[enable/disable]-negotiateauth
• --[enable/disable]-official-branding
• --[enable/disable]-parental-controls
• --[enable/disable]-permissions
• --[enable/disable]-places
• --[enable/disable]-plaintext-editor-only
• --[enable/disable]-pref-extensions
• --[enable/disable]-printing
• --[enable/disable]-profile-guided-optimization
• --[enable/disable]-profilelocking
• --[enable/disable]-profilesharing
• --[enable/disable]-quantify
• --[enable/disable]-rdf
• --[enable/disable]-reflow-perf
• --[enable/disable]-safe-browsing
• --[enable/disable]-startup-notification
• --[enable/disable]-static-mail
• --[enable/disable]-storage
• --[enable/disable]-strip
• --[enable/disable]-timeline
• --[enable/disable]-trace-malloc
• --[enable/disable]-ui-locale=ab-CD
• --[enable/disable]-universalchardet
• --[enable/disable]-update-channel=CHANNEL
• --[enable/disable]-update-packaging
• --[enable/disable]-updater
• --[enable/disable]-url-classifier
• --[enable/disable]-v1-string-abi
• --[enable/disable]-webservices
• --[enable/disable]-wrap-malloc
• --[enable/disable]-xmlextras
• --[enable/disable]-xpcom-fastload
• --[enable/disable]-xpconnect-idispatch
• --[enable/disable]-xpctools
• --[enable/disable]-xpfe-components
• --[enable/disable]-xpinstall
• --[enable/disable]-xprint
• --[enable/disable]-xterm-updates
• --[enable/disable]-xtf
• --[enable/disable]-zipwriter
• --bindir=DIR
• --build=BUILD
• --cache-file=FILE
• --datadir=DIR
• --exec-prefix=EPREFIX
• --host=HOST - the --host, --target, and --prefix options are used when cross-compiling.
• --includedir=DIR
• --infodir=DIR
• --libdir=DIR
• --libexecdir=DIR
• --localstatedir=DIR
• --mandir=DIR
• --no-create
• --oldincludedir=DIR
• --prefix=PREFIX - the --host, --target, and --prefix options are used when cross-compiling.
• --program-prefix=PREFIX
• --program-suffix=SUFFIX
• --program-transform-name=PROGRAM
• --quiet
• --sbindir=DIR
• --sharedstatedir=DIR
• --srcdir=DIR
• --sysconfdir=DIR
• --target=TARGET - the --host, --target, and --prefix options are used when cross-compiling.
• --version
• --with-PACKAGE[=ARG]
• --with-branding=dir
• --with-default-mozilla-five-home
• --with-distribution-id=ID
• --with-doc-include-dirs=DIRS
• --with-doc-input-dirs=DIRS
• --with-doc-output-dir=DIR
• --with-user-appdir=DIR
• --with-wrap-malloc=DIR
• --with-x
• --with-xulrunner-stub-name=appname
• --without-PACKAGE
• --without-libIDL
• --x-includes=DIR
• --x-libraries=DIR

Warning: Do not use a configure option unless you know what it does. The default options are there for a reason! The most successful mozconfig files are usually those with the fewest settings.