1 Configuring Build Options
2 =========================
4 +--------------------------------------------------------------------+
5 | This page is an import from MDN and the contents might be outdated |
6 +--------------------------------------------------------------------+
8 This document details how to configure Firefox builds.
9 Most of the time a ``mozconfig`` file is not required. The default
10 options are the most well-supported, so it is preferable to add as few
11 options as possible. Please read the following directions carefully
12 before building, and follow them in order. Skipping any step may cause
13 the build to fail, or the built software to be unusable. Build options,
14 including options not usable from the command-line, may appear in
15 "``confvars.sh``" files in the source tree.
18 Using a ``mozconfig`` configuration file
19 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
21 The choice of which Mozilla project to build and other configuration
22 options can be configured in a ``mozconfig`` file. (It is possible to
23 manually call ``configure`` with command-line options, but this is not
24 recommended). The ``mozconfig`` file should be in your source directory
25 (that is, ``/mozilla-central/mozconfig``).
27 Create a blank ``mozconfig`` file:
31 echo "# My first mozilla config" > mozconfig
33 If your mozconfig isn't in your source directory, you can also use the
34 ``MOZCONFIG`` environment variable to specify the path to your
35 ``mozconfig``. The path you specify **must** be an **absolute** path or
36 else ``client.mk`` will not find it. This is useful if you choose to
37 have multiple ``mozconfig`` files for different projects or
38 configurations (see below for a full example). Note that in the
39 ``export`` example below the filename was not ``mozconfig``. Regardless
40 of the name of the actual file you use, we refer to this file as the
41 ``mozconfig`` file in the examples below.
43 Setting the ``mozconfig`` path:
47 export MOZCONFIG=$HOME/mozilla/mozconfig-firefox
51 Calling the file ``.mozconfig`` (with a leading dot) is also
52 supported, but this is not recommended because it may make the file
53 harder to find. This will also help when troubleshooting because
54 people will want to know which build options you have selected and
55 will assume that you have put them in your ``mozconfig`` file.
58 ``mozconfig`` contains two types of options:
59 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61 - Options prefixed with ``mk_add_options`` are passed to
62 ``client.mk``. The most important of these is ``MOZ_OBJDIR``, which
63 controls where your project gets built (also known as the object
65 - Options prefixed with ``ac_add_options`` are passed to ``configure``,
66 and affect the build process.
69 Building with an objdir
70 ~~~~~~~~~~~~~~~~~~~~~~~
72 This means that the source code and object files are not intermingled in
73 your directory system and you can build multiple projects (e.g.,
74 Firefox and Thunderbird) from the same source tree. If you do not
75 specify a ``MOZ_OBJDIR``, it will be automatically set to
76 ``@TOPSRCDIR@/obj-@CONFIG_GUESS@``.
78 If you need to re-run ``configure``, the easiest way to do it is using
79 ``./mach configure``; running ``configure`` manually is strongly
82 Adding the following line to your ``mozconfig`` allows you to change the
87 mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-@CONFIG_GUESS@
89 It is a good idea to have your objdir name start with ``obj`` so that
92 Sometimes it can be useful to build multiple versions of the source
93 (such as with and without diagnostic asserts). To avoid the time it
94 takes to do a full rebuild, you can create multiple ``mozconfig`` files
95 which specify different objdirs. For example, a ``mozconfig-dbg``:
99 mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-ff-dbg
100 ac_add_options --enable-debug
102 and a ``mozconfig-rel-opt``:
106 mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-ff-rel-opt
107 ac_add_options --disable-debug
108 ac_add_options --enable-optimize
110 allow for building both versions by specifying the configuration via
111 the ``MOZCONFIG`` environment variable:
115 $ env MOZCONFIG=/path/to/mozconfig-dbg ./mach build
116 $ env MOZCONFIG=/path/to/mozconfig-rel-opt ./mach build
118 Don't forget to set the ``MOZCONFIG`` environment variable for the
119 ``mach run`` command as well.
121 Be aware that changing your ``mozconfig`` will require the configure
122 process to be rerun and therefore the build will take considerably
123 longer, so if you find yourself changing the same options regularly, it
124 may be worth having a separate ``mozconfig`` for each. The main downside
125 of this is that each objdir will take up a significant amount of space
134 The build system automatically makes an intelligent guess
135 for how many CPU cores to use when building. The option below is
136 typically not needed.
138 Most modern systems have multiple cores or CPUs, and they can be
139 optionally used concurrently to make the build faster. The ``-j`` flag
140 controls how many parallel builds will run concurrently. You will see
141 (diminishing) returns up to a value approximately 1.5× to 2.0× the
142 number of cores on your system.
146 mk_add_options MOZ_PARALLEL_BUILD=4
148 If your machine is overheating, you might want to try a lower value.
154 The ``--enable-project=project`` flag is used to select a project to
155 build. Firefox is the default.
157 Choose one of the following options to add to your ``mozconfig`` file:
162 ac_add_options --enable-project=browser
171 ac_add_options --enable-project=comm/mail
173 Mozilla Suite (SeaMonkey)
176 ac_add_options --enable-project=suite
178 Calendar (Lightning Extension, uses Thunderbird)
181 ac_add_options --enable-project=comm/mail
182 ac_add_options --enable-calendar
185 Selecting build options
186 ~~~~~~~~~~~~~~~~~~~~~~~
188 The build options you choose depends on what project you are
189 building and what you will be using the build for. If you want to use
190 the build regularly, you will want a release build without extra
191 debugging information; if you are a developer who wants to hack the
192 source code, you probably want a non-optimized build with extra
195 There are many options recognized by the configure script which are
196 special-purpose options intended for embedders or other special
197 situations, and should not be used to build the full suite/XUL
198 projects. The full list of options can be obtained by running
199 ``./mach configure -- --help``.
203 Do not use a configure option unless you know what it does.
204 The default values are usually the right ones. Each additional option
205 you add to your ``mozconfig`` file reduces the chance that your build
206 will compile and run correctly.
208 The following build options are very common:
213 `SCCache <https://github.com/mozilla/sccache>`__ allows speeding up subsequent
214 C / C++ builds by caching compilation results. Unlike
215 `ccache <https://ccache.dev>`__, it also allows caching Rust artifacts, and
216 supports `distributed compilation
217 <https://github.com/mozilla/sccache/blob/master/docs/DistributedQuickstart.md>`__.
219 In order to enable ``sccache`` for Firefox builds, you can use
220 ``ac_add_options --with-ccache=sccache``.
222 From version 0.7.4, sccache local builds are using the ``preprocessor cache mode``
223 by default. With a hot cache, it decreases the build time by a factor of 2 to 3
224 compared the previous method. This feature works like the `direct mode in ccache
225 <https://ccache.dev/manual/3.7.9.html#_the_direct_mode>`__,
226 using a similar way to handle caching and dependencies.
230 When using sccache, because of the operation on the files and storage,
231 the initial build of Firefox will be slower.
236 ``ac_add_options --enable-optimize``
237 Enables the default compiler optimization options
241 This is enabled by default
243 ``ac_add_options --enable-optimize=-O2``
244 Chooses particular compiler optimization options. In most cases, this
245 will not give the desired results, unless you know the Mozilla
246 codebase very well; note, however, that if you are building with the
247 Microsoft compilers, you probably **do** want this as ``-O1`` will
248 optimize for size, unlike GCC.
249 ``ac_add_options --enable-debug``
250 Enables assertions in C++ and JavaScript, plus other debug-only code.
251 This can significantly slow a build, but it is invaluable when
252 writing patches. **People developing patches (especially in C++)
253 should generally use this option.**
254 ``ac_add_options --disable-optimize``
255 Disables compiler optimization. This makes it much easier to step
256 through code in a debugger.
257 ``ac_add_options --enable-release``
258 Enables more conservative, release engineering-oriented options. This may
259 slow down builds. This also turns on full optimizations for Rust. Note this
260 is the default when building release/beta/esr.
261 ``ac_add_options --enable-debug-js-modules``
262 Enable only JavaScript assertions. This is useful when working
263 locally on JavaScript-powered components like the DevTools. This will
264 help catch any errors introduced into the JS code, with less of a
265 performance impact compared to the ``--enable-debug`` option.
266 ``export RUSTC_OPT_LEVEL=2``
267 Enable full optimizations for Rust code.
269 You can make an optimized build with debugging symbols. See :ref:`Building
270 with Debug Symbols <Building with Debug Symbols>`.
272 Building as Beta or Release
273 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
275 ``ac_add_options --as-milestone=release``
276 This makes it easy to build nightly with a release or beta configuration to
277 test the different ifdef behaviors. To do a full beta simulation see
278 `Sheriffing/How To/Beta simulations <https://wiki.mozilla.org/Sheriffing/How_To/Beta_simulations>`__.
287 ``ac_add_options --enable-extensions=default|all|ext1,ext2,-skipext3``
288 There are many optional pieces of code that live in {{
289 Source("extensions/") }}. Many of these extensions are now considered
290 an integral part of the browsing experience. There is a default list
291 of extensions for the suite, and each app-specific ``mozconfig``
292 specifies a different default set. Some extensions are not compatible
293 with all apps, for example:
295 - ``cookie`` is not compatible with thunderbird
296 - ``typeaheadfind`` is not compatible with any toolkit app (Firefox,
299 Unless you know which extensions are compatible with which apps, do
300 not use the ``--enable-extensions`` option; the build system will
301 automatically select the proper default set of extensions.
306 ``ac_add_options --disable-tests``
307 By default, many auxiliary test programs are built, which can
308 help debug and patch the mozilla source. Disabling these tests can
309 speed build time and reduce disk space considerably. Developers
310 should generally not use this option.
315 ``mk_add_options MOZ_CO_LOCALES=ISOcode``
317 ``ac_add_options --enable-ui-locale=ISOcode``
319 ``ac_add_options --with-l10n-base=/path/to/base/dir``
325 ``mk_add_options AUTOCLOBBER=1``
326 If a clobber would be required before a build, this will cause mach
327 to clobber and continue with the build instead of asking the user to
328 manually clobber and exiting.
330 ``ac_add_options --enable-warnings-as-errors``
331 This makes compiler warnings into errors which fail the build. This
332 can be useful since certain warnings coincide with reviewbot lints
333 which must be fixed before merging.
335 .. _Example_.mozconfig_Files:
337 Example ``mozconfig`` Files
338 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
340 Mozilla's official builds use mozconfig files from the appropriate
341 directory within each repository.
345 These ``mozconfig`` files are taken from production builds
346 and are provided as examples only. It is recommended to use the default
347 build options, and only change the properties from the list above as
348 needed. The production builds aren't really appropriate for local
351 - .. rubric:: Firefox, `Debugging Build (macOS
352 64bits) <http://hg.mozilla.org/mozilla-central/file/tip/browser/config/mozconfigs/macosx64/debug>`__
353 :name: Firefox.2C_Default_Release_Configuration
355 Building multiple projects from the same source tree
356 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
358 It is possible to build multiple projects from the same source tree,
359 as long as you `use a different objdir <#Building_with_an_Objdir>`__ for
362 You need to create multiple ``mozconfig`` files.
364 As an example, the following steps can be used to build Firefox and
365 Thunderbird. You should first create three ``mozconfig`` files.
367 ``mozconfig-common``:
371 # add common options here, such as making an optimized release build
372 mk_add_options MOZ_PARALLEL_BUILD=4
373 ac_add_options --enable-optimize --disable-debug
375 ``mozconfig-firefox``:
379 # include the common mozconfig
383 mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-firefox
384 ac_add_options --enable-project=browser
386 ``mozconfig-thunderbird``:
390 # include the common mozconfig
394 mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-thunderbird
395 ac_add_options --enable-project=comm/mail
397 To build Firefox, run the following commands:
401 export MOZCONFIG=/path/to/mozilla/mozconfig-firefox
404 To build Thunderbird, run the following commands:
408 export MOZCONFIG=/path/to/mozilla/mozconfig-thunderbird
411 Using mozconfigwrapper
412 ^^^^^^^^^^^^^^^^^^^^^^
414 Mozconfigwrapper is similar to using multiple mozconfig files except
415 that it abstracts and hides them so you don't have to worry about where
416 they live or which ones you've created. It also saves you from having to
417 export the MOZCONFIG variable each time. For information on installing
418 and configuring mozconfigwrapper, see
419 https://github.com/ahal/mozconfigwrapper.