Simple Thunderbird build

This page covers the basic steps needed to build a bleeding-edge, development version of Thunderbird 60 or later. For Thunderbird up to 59, see the old build documentation. For additional, more detailed information, see the build documentation.

Hardware requirements

  • At least 4 GB of RAM. 8 GB or more is recommended. While you can build Thunderbird on older hardware it can take quite a bit of time to compile on slower machines with less RAM.
  • Good internet connection for the initial source download.

Build prerequisites

Depending on your Operating System you will need to carry out a different process to prepare your machine. So firstly complete the instructions for your OS and then continue following these build instructions.

MAPI Headers

On Windows: check that the MAPI header files from https://www.microsoft.com/en-us/download/details.aspx?id=12905 are installed because the MAPI header files (except MAPI.h) are not bundled with Visual Studio 2017 (Windows SDK 10). You should copy 17 of the 18 header files to a Windows SDK include directory so that the build process will find the files, that is C:\Program Files (x86)\Windows Kits\10\Include\10.0.nnnnn.0\shared, where nnnnn is the highest number present on the system. Note that the downloaded Outlook 2010 MAPI Header Files contain 18 fies, of which only 17 are needed. Do not copy MAPI.h, it is already in C:\Program Files (x86)\Windows Kits\10\Include\10.0.17134.0\um\MAPI.h.

As of April 2019, 10.0.17134.0 is needed to compile Thunderbird. Assuming standard installation locations, copy these 17 files to C:\Program Files (x86)\Windows Kits\10\Include\10.0.17134.0\shared.

18/10/2010  16:11             7,334 MAPIAux.h
02/06/2009  17:02             7,938 MAPICode.h
02/06/2009  17:02            22,960 MAPIDbg.h
02/06/2009  17:02            84,644 MAPIDefS.h
02/06/2009  17:02            27,840 MAPIForm.h
02/06/2009  17:02            11,880 MAPIGuid.h
02/06/2009  17:02             2,648 MAPIHook.h
02/06/2009  17:02             5,359 MAPINls.h
02/06/2009  17:02             2,743 MAPIOID.h
02/06/2009  17:02            32,978 MAPISPI.h
02/06/2009  17:02            54,395 MAPITags.h
02/06/2009  17:02            26,467 MAPIUtil.h
02/06/2009  17:02            97,301 MAPIVal.h
02/06/2009  17:02             9,334 MAPIWin.h
02/06/2009  17:02             1,906 MAPIWz.h
02/06/2009  17:02            18,277 MAPIX.h
02/06/2009  17:02             5,012 MSPST.h

Get the source

Note: On Windows, you won't be able to build the Thunderbird source code if it's under a directory with spaces in the path (e.g., don't use "Documents and Settings"). You can pick any other location, such as a new directory C:/thunderbird-src (where "C:/", with a forward slash, is intentional to clarify you are in the MozillaBuild command prompt per Windows build prerequisite).
Note: Parts of the build process also have problems when the source code is in a directory where the path is long (nested many levels deep). On Linux, this can manifest as problems setting up the virtualenv for running tests (failure to install pip or virtualenv because of OS access denied errors, where access is denied not because of permission problems, but because the paths being accessed have been truncated, and so do not exist). Having the source deep in a filesystem hierarchy can also cause problems with pymake builds on Windows. If you run into seemingly arbitrary problems in building and the source is deeply nested, try moving it closer to the root of your machine and re-building.

Get the latest Mozilla source code from Mozilla's mozilla-central Mercurial code repository, and check it out into a local directory source/ (or however you want to call it). Then, get the latest Thunderbird source code from Mozilla's comm-central Mercurial code repository. It now needs to be placed inside the Mozilla source code, in a directory named comm/ (this is inverse from Thunderbird 59 and earlier):

hg clone https://hg.mozilla.org/mozilla-central source/
cd source/
hg clone https://hg.mozilla.org/comm-central comm/

The source code requires 3.6GB of free space or more and additionally 5GB or more for default build. Instead of using hg clone, you can follow these instructions on downloading and "unpacking" a Mercurial bundle.

Warning: The page Getting comm-central Source Code Using Mercurial [en-US] is 99% out of date! Only useful content is working with Github.

Build configuration

To build Thunderbird, you need to add a file named mozconfig to the root directory of the mozilla-central checkout that contains the following line:

ac_add_options --enable-application=comm/mail

You can create a file with this line by doing this in the source/ directory:

echo 'ac_add_options --enable-application=comm/mail' > mozconfig

If you omit this line, the build system will build Firefox instead. Other build configuration options can be added to this file, although it's strongly recommended that you only use options that you fully understand. For example, to create a debug build instead of a release build, that file would also contain the line:

ac_add_options --enable-debug

Each of these ac_add_options entries needs to be on its own line.

For more on configuration options, see the page Configuring build options. Note that if you use an MOZ_OBJDIR it cannot be a sibling folder to your source directory. Use an absolute path to be sure!

To also build Lightning when building Thunderbird

Add the following line to your mozconfig file:

ac_add_options --enable-calendar

To add that line you can do this in the source/ directory:

echo 'ac_add_options --enable-calendar' >> mozconfig

Building

Before you start, make sure that the version you checked out is not busted. For hg tip, you should see green Bs on https://treeherder.mozilla.org/#/jobs?repo=comm-central

To start the build, cd into the source directory, and run:

./mach build

mach is our command-line tool to streamline common developer tasks. See the mach article for more.

Building can take a significant amount of time, depending on your system, OS, and chosen build options. Linux builds on a fast box may take under 15 minutes, but Windows builds on a slow box may take several hours. Tips for making builds faster.

The executable will be at the location listed under Running below.

Running

To run your build, you can use

./mach run

There are various command line parameters you can add, e.g. to specify a profile.

Various temporary files, libraries, and the Thunderbird executable will be found in your object directory (under comm-central/), which is prefixed with obj-. The exact name depends on your system and OS. For example, a Mac user may get an object directory name of obj-x86_64-apple-darwin10.7.3/.

The Thunderbird executable in particular, and its dependencies are located under the dist/bin folder under the object directory. To run the executable from your comm-central working directory:

  • Windows: obj-.../dist/bin/thunderbird.exe
  • Linux: obj-.../dist/bin/thunderbird
  • macOS: obj-.../dist/Daily.app/Contents/MacOS/thunderbird

How to update and build again

In your source directory:

hg pull -u
cd comm
hg pull -u
cd ..

or same commands shorter:

hg pull -u; (cd comm; hg pull -u)

Then just re-run the mach command above. This will only recompile files that changed, but it's still a long haul.

Rebuilding

To build after making changes, run

./mach build

again. This will only rebuild what is necessary for these changes. It is also possible to rebuild specifically.

If you changed C or C++ files, run:

./mach build binaries

If you changed JavaScript or XUL files, on macOS or Linux you don't have to rebuild since the files in the object directory are linked to the ones in the source directory. On Windows run:

./mach build path/to/dir

This is the tricky bit since you need to specify the directory that installs the files, which may be a parent directory of the changed file's directory. For example, to just rebuild the Lightning calendar extension:

./mach build comm/calendar/lightning

For all other changes run the full rebuild:

./mach build

Problems Building?

Have you:

  • Check comm-central on Treeherder for known failures at the time you pulled the code. The current status of the trunk can also be checked at https://treestatus.mozilla.org/
    • If the trunk is broken (i.e. closed), you may wish to consider building one of the branches (to pull the source code from a branch, just replace the url to the repository in the hg clone instruction).
  • Check to make sure that the path in which you placed the source code has no spaces, and is not too long.
  • Searched the bug database for issues relating to your problem (e.g., platform-specific issues).
  • Try asking in mozilla.dev.builds - include details of what is in your mozconfig, and what the actual error is.
  • Check if your mozilla/ is a symlink. A symlink there is not supported.
  • Check for @TOPSRCDIR@ or relative paths in your mozconfig. Those have caused several problems historically and tend to be poorly tested when the build system changes.
  • If on Windows you get link errors like "LNK1102: out of memory" or "LNK1318: Unexpected PDB error; OK (0)", try deleting the largest .PDB files before rushing out the door to buy more RAM. Clobbering (see below) will also remove those files.
  • Try with a clean obj-dir. You can clean out previous build artefacts using
    ./mach clobber

References