Configuring Build Options

  • Revision slug: Configuring_Build_Options
  • Revision title: Configuring Build Options
  • Revision id: 22340
  • Created:
  • Creator: Gschmidt
  • Is current revision? No
  • Comment /* Choose an Application */ Added pointer to XULRunner default config file

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.

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

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

export MOZCONFIG=~/mozilla/mozconfig-firefox


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

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 following mozconfig option enables an objdir:

mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/some_subdir

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

Browser (Firefox)
Your .mozconfig file should source the Firefox default mozconfig file:
. $topsrcdir/browser/config/mozconfig

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

Mail (Thunderbird)
Your .mozconfig file should source the Thunderbird default mozconfig file:
. $topsrcdir/mail/config/mozconfig

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

Standalone Calendar (Sunbird)
Your .mozconfig file should source the Sunbird default mozconfig file:
. $topsrcdir/calendar/sunbird/config/mozconfig

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

XULRunner
Your .mozconfig file should source the XULRunner default mozconfig file:
. $topsrcdir/xulrunner/config/mozconfig

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

ac_add_options --enable-default-toolkit=gtk2|gtk|xlib|qt|cairo-gtk2|cairo-xlib|windows|mac|cocoa|os2|beos|photon
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 (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.

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

Static Build

ac_add_options --enable-static --disable-shared
These options build a larger single executable, which has components linked statically. This means that there are many fewer component DLLs, which can improve startup time. However, unless your build machine has a lot of RAM, this option is not for you. 512MB RAM minimum, 1G recommended. These options should always be used together. If you use --enable-static, it is recommended that you also --disable-tests.

ac_add_options --disable-static --enable-shared
These options make components into separate shared libraries. This makes debugging and incremental compiling much easier, but the resulting build can be slower and somewhat less efficient.

This option is the default.

Extensions

ac_add_options --enable-extensions=default|all|ext1,ext2,-skipext3
There are many optional pieces of code that live in {{wiki.template('Named-source', [ "extensions/", "the extensions/ directory" ])}} of the source tree. 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.

Example .mozconfig Files

Firefox Optimized Static

. $topsrcdir/browser/config/mozconfig
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/ff-opt-static
ac_add_options --enable-optimize
ac_add_options --disable-debug
ac_add_options --enable-static
ac_add_options --disable-shared
ac_add_options --disable-tests
mk_add_options MOZ_CO_PROJECT=browser

Thunderbird, Debugging Build

. $topsrcdir/mail/config/mozconfig
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/tbird-debug
mk_add_options MOZ_CO_PROJECT=mail,calendar
ac_add_options --disable-optimize
ac_add_options --enable-debug

SeaMonkey, Optimized (but not static)

mk_add_options MOZ_CO_PROJECT=suite
ac_add_options --enable-application=suite
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/suite-opt
ac_add_options --enable-optimize
ac_add_options --disable-debug

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.

As an example, the following steps can be used to build Firefox and Thunderbird. You should first create three mozconfig files.

mozconfig-common

mk_add_options MOZ_CO_PROJECT=browser,mail

# add other common options here, such as making a static release build and
# disabling tests
ac_add_options --enable-optimize --disable-debug
ac_add_options --disable-tests

mozconfig-firefox

# include the common mozconfig
. ./mozconfig-common

# Build Firefox
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/firefox-static
ac_add_options --enable-application=browser

mozconfig-thunderbird

# include the common mozconfig
. ./mozconfig-common

# Build Thunderbird
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/thunderbird-static
ac_add_options --enable-application=mail

To checkout, run the following commands:

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

To build Firefox, run the following commands:

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

To build Thunderbird, run the following commands:

export MOZCONFIG=/path/to/mozilla/mozconfig-thunderbird
make -f client.mk build
{{ wiki.languages( { "fr": "fr/Configuration_des_options_de_compilation", "ja": "ja/Configuring_Build_Options" } ) }}

Revision Source

<p>
<span class="comment">NOTE: Do not make substantive changes to this document   without consulting Benjamin Smedberg &lt;benjamin@smedbergs.us&gt;   or one of the build-config peers.</span>
</p><p>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.
</p><p>{{wiki.template(':en/Build_Documentation/TOC')}}
</p>
<h3 name="Using_a_.mozconfig_Configuration_File"> Using a .mozconfig Configuration File </h3>
<p>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).
</p><p>You may also set the MOZCONFIG environment variable to the full path of your configuration file:
</p>
<pre class="eval">export MOZCONFIG=~/mozilla/mozconfig-firefox
</pre>
<p><br>
.mozconfig contains two types of options:
</p>
<ul><li> Options prefixed with <code>mk_add_options</code> are passed to <tt>client.mk</tt>, and are usually options controlling cvs checkout and update.
</li><li> Options prefixed with <code>ac_add_options</code> are passed to <tt>configure</tt>, and affect the build process.
</li></ul>
<p>These options will be automatically used when <tt>./configure</tt> or <tt>make -f client.mk</tt> are run.
</p>
<h3 name="Building_with_an_Objdir"> Building with an Objdir </h3>
<p>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 following mozconfig option enables an objdir:
</p>
<pre class="eval">mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/some_subdir
</pre>
<h3 name="Choose_an_Application"> Choose an Application </h3>
<p></p><dl>
<dt>Mozilla Suite (SeaMonkey)
</dt><dd>Specify the following options:

<pre class="eval">ac_add_options --enable-application=suite
# Use the following to checkout SeaMonkey from CVS:
mk_add_options MOZ_CO_PROJECT=suite
</pre>
<p></p></dd><dt>Browser (Firefox)
</dt><dd>Your .mozconfig file should source the Firefox <a class="external" href="http://lxr.mozilla.org/mozilla/source/browser/config/mozconfig">default mozconfig file</a>:

<pre class="eval">. $topsrcdir/browser/config/mozconfig
</pre>
<p>Do not copy and paste the file's contents into your mozconfig, as they may change over time!
</p><p></p></dd><dt>Mail (Thunderbird)
</dt><dd>Your .mozconfig file should source the Thunderbird <a class="external" href="http://lxr.mozilla.org/mozilla/source/mail/config/mozconfig">default mozconfig file</a>:

<pre class="eval">. $topsrcdir/mail/config/mozconfig
</pre>
<p>Do not copy and paste the file's contents into your mozconfig, as they may change over time!
</p><p></p></dd><dt>Standalone Calendar (Sunbird)
</dt><dd>Your .mozconfig file should source the Sunbird <a class="external" href="http://lxr.mozilla.org/mozilla/source/calendar/sunbird/config/mozconfig">default mozconfig file</a>:

<pre class="eval">. $topsrcdir/calendar/sunbird/config/mozconfig
</pre>
<p>Do not copy and paste the file's contents into your mozconfig, as they may change over time!
</p><p></p></dd><dt>XULRunner
</dt><dd>Your .mozconfig file should source the XULRunner <a class="external" href="http://lxr.mozilla.org/mozilla/source/xulrunner/config/mozconfig">default mozconfig file</a>:

<pre class="eval">. $topsrcdir/xulrunner/config/mozconfig
</pre>
<p>Do not copy and paste the file's contents into your mozconfig, as they may change over time!
</p><p></p></dd></dl>

<h3 name="Selecting_Build_Options"> Selecting Build Options </h3>
<p>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.
</p><p>There is a webtool that can help you create a good configuration: the <a class="external" href="http://webtools.mozilla.org/build/config.cgi">Mozilla Build Configurator</a>. At this time, the tool is mainly useful for the Mozilla suite; building Firefox or other toolkit applications requires manually editing the generated file.
</p><p>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 <a class="external" href="http://webtools.mozilla.org/build/config.cgi">Mozilla Build Configurator</a>.
</p><p><b>If you do not know what a configure option does, don't use it!</b> The following build options are very common:
</p>
<h4 name="Optimization"> Optimization </h4>
<dl><dt> ac_add_options --enable-optimize </dt><dd> Enables the default compiler optimization options 
</dd><dt> ac_add_options --enable-optimize=-O2 </dt><dd> Choose particular compiler optimization options. In most cases, this will not give the desired results, unless you know the mozilla codebase very well. 
</dd><dt> ac_add_options --disable-debug </dt><dd> Disables verbose debugging macros 
</dd><dt> ac_add_options --disable-optimize </dt><dd> Disables compiler optimization. This makes it much easier to step through code in a debugger. 
</dd><dt> ac_add_options --enable-debug </dt><dd>  Enables debugging macros and other debug-only code. This can significantly slow a build, but it is invaluable when writing patches.
</dd></dl>
<h4 name="Graphics_Toolkit"> Graphics Toolkit </h4>
<p></p><dl>
<dt>ac_add_options --enable-default-toolkit=gtk2|gtk|xlib|qt|cairo-gtk2|cairo-xlib|windows|mac|cocoa|os2|beos|photon 
</dt><dd>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 (Camino uses --enable-default-toolkit=cocoa.
<p>On *nix platforms, selects the graphics toolkit to use. GTK2 and GTK are both well-tested. xlib is considered a <a class="external" href="http://www.mozilla.org/build/faq.html#supported">tier-3 platform</a>. Qt and cairo are experimental, you will find bugs. 
</p><p></p></dd><dt>ac_add_options --enable-xft
</dt><dd>Enables XFT advanced font rendering. This is only available with --enable-default-toolkit=gtk2, and it is recommended with gtk2 
<p></p></dd><dt>ac_add_options --enable-freetype2
</dt><dd>Enables freetype font rendering. This is the default for the GTK toolkit. Not compatible with --enable-xft 
<p></p></dd></dl>

<h4 name="Static_Build"> Static Build </h4>
<p></p><dl>
<dt>ac_add_options --enable-static --disable-shared
</dt><dd>These options build a larger single executable, which has components linked statically. This means that there are many fewer component DLLs, which can improve startup time. However, unless your build machine has a lot of RAM, this option is not for you. 512MB RAM minimum, 1G recommended. These options should always be used together. If you use --enable-static, it is recommended that you also --disable-tests. 
<p></p></dd><dt>ac_add_options --disable-static --enable-shared
</dt><dd>These options make components into separate shared libraries. This makes debugging and incremental compiling much easier, but the resulting build can be slower and somewhat less efficient.
<p>This option is the default.
</p></dd></dl>

<h4 name="Extensions"> Extensions </h4>
<p></p><dl>
<dt>ac_add_options --enable-extensions=default|all|ext1,ext2,-skipext3
</dt><dd>There are many optional pieces of code that live in {{wiki.template('Named-source', [ "extensions/", "the extensions/ directory" ])}} of the source tree. 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:

<ul><li> cookie is not compatible with thunderbird
</li><li> typeaheadfind is not compatible with any toolkit app (firefox, thunderbird, sunbird) 
</li></ul>
<p>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. 
</p></dd></dl>

<h4 name="Tests"> Tests </h4>
<p></p><dl>
<dt>ac_add_options --disable-tests
</dt><dd>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. 
</dd></dl>

<h4 name="Other_Options"> Other Options </h4>
<p></p><dl>
<dt>ac_add_options --disable-crypto
</dt><dd>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.
<p>On the 1.7 and aviary branches, cryptography was off by default. You need to specify <code>--enable-crypto</code> if you want SSL, SMIME, or other software features that require cryptography. 
</p><p></p></dd></dl>

<h3 name="Example_.mozconfig_Files"> Example .mozconfig Files </h3>
<h4 name="Firefox_Optimized_Static"> Firefox Optimized Static </h4>
<pre class="eval">. $topsrcdir/browser/config/mozconfig
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/ff-opt-static
ac_add_options --enable-optimize
ac_add_options --disable-debug
ac_add_options --enable-static
ac_add_options --disable-shared
ac_add_options --disable-tests
mk_add_options MOZ_CO_PROJECT=browser
</pre>
<h4 name="Thunderbird.2C_Debugging_Build"> Thunderbird, Debugging Build </h4>
<pre class="eval">. $topsrcdir/mail/config/mozconfig
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/tbird-debug
mk_add_options MOZ_CO_PROJECT=mail,calendar
ac_add_options --disable-optimize
ac_add_options --enable-debug
</pre>
<h4 name="SeaMonkey.2C_Optimized_.28but_not_static.29"> SeaMonkey, Optimized (but not static) </h4>
<pre class="eval">mk_add_options MOZ_CO_PROJECT=suite
ac_add_options --enable-application=suite
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/suite-opt
ac_add_options --enable-optimize
ac_add_options --disable-debug
</pre>
<h3 name="Building_multiple_applications_from_the_same_source_tree"> Building multiple applications from the same source tree </h3>
<p>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 <a href="#Building_with_an_Objdir">use a different objdir</a> for each application.
</p><p>As an example, the following steps can be used to build Firefox and Thunderbird. You should first create three mozconfig files.
</p><p>mozconfig-common
</p>
<pre class="eval">mk_add_options MOZ_CO_PROJECT=browser,mail

# add other common options here, such as making a static release build and
# disabling tests
ac_add_options --enable-optimize --disable-debug
ac_add_options --disable-tests
</pre>
<p>mozconfig-firefox
</p>
<pre class="eval"># include the common mozconfig
. ./mozconfig-common

# Build Firefox
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/firefox-static
ac_add_options --enable-application=browser
</pre>
<p>mozconfig-thunderbird
</p>
<pre class="eval"># include the common mozconfig
. ./mozconfig-common

# Build Thunderbird
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/thunderbird-static
ac_add_options --enable-application=mail
</pre>
<p>To checkout, run the following commands:
</p>
<pre class="eval">export MOZCONFIG=/path/to/mozilla/mozconfig-common
make -f client.mk checkout
</pre>
<p>To build Firefox, run the following commands:
</p>
<pre class="eval">export MOZCONFIG=/path/to/mozilla/mozconfig-firefox
make -f client.mk build
</pre>
<p>To build Thunderbird, run the following commands:
</p>
<pre class="eval">export MOZCONFIG=/path/to/mozilla/mozconfig-thunderbird
make -f client.mk build
</pre>{{ wiki.languages( { "fr": "fr/Configuration_des_options_de_compilation", "ja": "ja/Configuring_Build_Options" } ) }}
Revert to this revision