Revision Content

NOTE: Do not make substantive changes to this document without consulting Benjamin Smedberg <benjamin@smedbergs.us> or one of the build-config peers.

Running configure and make with the default options will not give you a good working build. You should use a .mozconfig file to obtain a reasonable release build. Please read these 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.

{{wiki.template(':en/Build_Documentation/TOC')}}

Using a .mozconfig Configuration File

Though it is possible to manually call <tt>configure</tt> with command-line options, this is not recommended. Instead, place a .mozconfig file in your source directory (mozilla/.mozconfig) or in your HOME directory (~/.mozconfig).

echo "# My first mozilla config" > .mozconfig

.mozconfig contains two types of options:

Options prefixed with mk_add_options are passed to <tt>client.mk</tt>, and are usually options controlling cvs checkout and update.

Options prefixed with ac_add_options are passed to <tt>configure</tt>, and affect the build process.

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

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

You may also set the MOZCONFIG environment variable to the full path of your configuration file:

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 <tt>mozilla/modules/plugin/base/src/Makefile.in</tt>, with an objdir value of @TOPSRCDIR@/obj-debug, the file and directory path <tt>mozilla/obj-debug/modules/plugin/base/src/Makefile</tt> will be created. This Makefile will magically refer to source files in the <tt>mozilla/modules/plugin/base/src</tt> directory.

If you need manually re-run configure, please do so from within your object, 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 <tt>/cygdrive/c/Projects/FIREFOX/mozilla</tt>, then, from within your objdir you would need to run <tt>/cygdrive/c/Projects/FIREFOX/mozilla/configure</tt> 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@

Choose an Application

Mozilla Suite (SeaMonkey)

Specify the following options:

ac_add_options --enable-application=suite
# Use the following to checkout SeaMonkey from CVS:
mk_add_options MOZ_CO_PROJECT=suite

Do not copy and paste the file's contents into your mozconfig, as they may change over time!

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 is a webtool that can help you create a good configuration: the Mozilla Build Configurator. At this time, the tool is mainly useful for the Mozilla suite; building Firefox or other toolkit applications requires manually editing the generated file.

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 or by looking through the Mozilla Build Configurator.

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 --disable-debug

Disables verbose debugging macros

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

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

Graphics Toolkit

Selects the graphics toolkit. 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 are both well-tested. xlib is considered a tier-3 platform. Qt and cairo are experimental, you will find bugs. On trunk, use cairo-gtk2 (gtk1 and xlib have been removed from the source tree).

ac_add_options --enable-xft

Enables XFT advanced font rendering. This is only available with --enable-default-toolkit=gtk2, and it is recommended with gtk2

ac_add_options --enable-freetype2

Enables freetype font rendering. This is the default for the GTK toolkit. Not compatible with --enable-xft

Statically Linking Components

<tt>ac_add_options --enable-libxul</tt> (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.

<tt>ac_add_options --enable-static --disable-libxul</tt>

These options build a larger single executable, which has components linked statically. <tt>--enable-static</tt> requires <tt>--disable-libxul</tt>. If you use <tt>--enable-static</tt>, it is recommended that you also <tt>--disable-tests</tt>. This option is not recommended for Firefox. It still exists only for Thunderbird and SeaMonkey which cannot yet build in the libxul configuration.

<tt>ac_add_options --disable-static --disable-libxul</tt>

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

Extensions

ac_add_options --enable-extensions=default|all|ext1,ext2,-skipext3

There are many optional pieces of code that live in {{template.Source("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.

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.