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.

• 30 GB of free space. The Thunderbird build can use up to 30-40GB of disk space to complete depending on your operating system.

• 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 first complete the instructions for your OS and then continue following these build instructions.

• Windows Build Prerequisites

• Linux Build Prerequisites

• macOS Build Prerequisites

Build Configuration

To build Thunderbird, you need a file named mozconfig in the root directory of the mozilla-central checkout that contains the option comm/mail enabled. If you do not already have this file, then you can create it with this line by doing this in the source/ directory:

echo 'ac_add_options --enable-project=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 recommended that you only use options that you fully understand. Here are come recommended options to use and why:

• To create a debug build instead of a release build: ac_add_options --enable-debug

• To speed up subsequent builds by caching compilation results for both C++ and Rust: ac_add_options --with-ccache=sccache

• To enable some additional checks we have enabled in the CI: ac_add_options --enable-clang-plugin

• To enable debug symbols: ac_add_options --enable-debug-symbols

• To enable autoclobber: mk_add_options AUTOCLOBBER=1

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

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

Building

After you have met the build prerequisites for your OS, the build is started in the source directory with:

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

Make Your Build Faster

Follow this guide to rely on sccache and other Tips for making builds faster.

Running Thunderbird

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

Update and Build Again

To pull down the latest changes, in the mozilla directory run the following commands:

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

or to do it via one command:

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

Then just run the ./mach build command detailed in the Building instructions above. This will only recompile files that changed, but it may still take a long time.

Rebuilding

To build after changes you can simply run:

./mach build

Rebuilding Specific Parts

If you have made many changes, but only want to rebuild specific parts, you may run the following commands.

C or C++ Files:

./mach build binaries

JavaScript or XUL Files (Windows Only):

./mach build path/to/dir

./mach build comm/calendar/lightning

The Basics

64-bit Windows

You will need to be running a 64-bit version of Windows in order to build Thunderbird. To check this in Windows 10, open the start menu and click on the gear icon on the left-hand side of the menu. This will open up the "settings" window. Click on the "System" option and then scroll down to "About". Click on the "About" option and on the new screen next to "System Type" you should see: "64-bit operating system"

Visual Studio

In order to get the necessary libraries in order to build Thunderbird, you will need to install Visual Studio - an IDE from Microsoft. Download the free community edition here.

During installation make sure the following workloads are checked:

• "Desktop development with C++"

• "Game development with C++"

MozillaBuild Package

Finally, download the MozillaBuild Package from Mozilla. Accept the default settings, in particular the default installation directory: c:\mozilla-build\. On some versions of Windows an error dialog will give you the option to ‘reinstall with the correct settings’ - you should agree and proceed.

Getting the Code

Once you have run start-shell.bat, you will need to grab the source code if you haven't already.

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/

Mach Bootstrap

In the source directory run the following command to get additional dependencies needed to install Thunderbird:

./mach bootstrap

You will be presented with the following options:

Please choose the version of Firefox you want to build:
  1. Firefox for Desktop Artifact Mode
  2. Firefox for Desktop
  3. GeckoView/Firefox for Android Artifact Mode
  4. GeckoView/Firefox for Android

Please choose option 2 to proceed with a successful build.

This action will install all the remaining libraries and dependencies necessary to build Thunderbird locally.

Building Thunderbird

Now that you have the prerequisites for Windows, make sure you have the source code via the commands on the "Setting up a build environment" page:

Then you can follow the instructions on the Building Thunderbird page:

Hardware Requirements

64-bit version

You will need to be running a 64-bit version of Linux in order to build Thunderbird. You can check which version you're running by typing this command in your terminal:

uname -m

if this command returns x86_64 you can proceed.

30 GB of free space

The Thunderbird build can use 30-40GB of disk space to complete depending on your operating system.

Build Environment

Python

You’ll need Python 3.8 or later installed.

You can check with python3 --version to see if you have it already. If not, you can install it with your distribution’s package manager. Make sure your system is up to date!

You will also need python3-distutils and python3-pip installed from your distribution's package manager.

Mercurial

As noted in the Setting up a build environment page, both mozilla-central and comm-central are repositories using the Mercurial version control system. This means you will need to install Mercurial. Here are the quick commands to use for common Linux based operating systems but for a more complete list of instructions (if neither of these works for your use case), please see Mercurial's download page on their wiki.

Ubuntu/Debian

sudo apt install mercurial

Fedora

sudo dnf install mercurial

Getting the Code

Once you have Mercurial installed, you are ready to grab the source code. There are a couple of different methods to do this.

Scripted

The bootstrap.py script will grab the two source repos you need, run ./mach bootstrap for you, and sets up a necessary mozconfig file. Download this file to the directory where you would like your source code folder to live, either by clicking the link and moving the file to the appropriate location or using wget. Then make it executable and run it.

mkdir tb-build && cd tb-build
wget https://hg.mozilla.org/comm-central/raw-file/tip/python/rocboot/bin/bootstrap.py
chmod +x bootstrap.py
./bootstrap.py

This will create a mozilla-unified directory with both a mozconfig and a comm/ folder inside. The mozconfig file is setup to build Thunderbird and you can verify this with cat mozconfig; the --enable-project parameter should be comm/mail:

ac_add_options --enable-project=comm/mail

Manually

If you would rather manually gather the source code, perform the bootstrap, and create your mozconfig file, then follow these steps.

Checkout the Source Code

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 needs to be placed inside the Mozilla source code, in a directory named comm/:

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

Create mozconfig file

This step will need to be performed if you manually checked out the code and performed the bootstrap, and it will covered in the next section you follow, Building Thunderbird.

Mach Bootstrap

In the source directory run the following command to get additional dependencies needed to install Thunderbird:

./mach bootstrap

You will be presented with the following options:

Please choose the version of Firefox you want to build:
  1. Firefox for Desktop Artifact Mode
  2. Firefox for Desktop
  3. GeckoView/Firefox for Android Artifact Mode
  4. GeckoView/Firefox for Android

Please choose option 2 to proceed with a successful build.

This action should install all the remaining libraries and dependencies necessary to build Thunderbird locally.

Missing libraries

It could happen that some libraries will not be installed by the bootstrap command, specifically those related to the Rust programming language. Check whether these packages are available in your system by running these commands in your terminal:

• which rustc

• which cargo

If one or both commands return an empty output, you need to install them manually:

• Install Rust and cargo (the Rust package manager): curl https://sh.rustup.rs -sSf | sh

• Install cbindgen (tool that generates C bindings from Rust code): cargo install cbindgen

export PATH=$HOME/.cargo/bin:$PATH

You're all set

Go back to the Building Thunderbird page and continue following the guide.

Hardware Requirements

30 GB of free space

The Thunderbird build can use 30-40GB of disk space to complete depending on your operating system.

Build Environment

Python

You will need python (version 3.8 or later) and pipx (used to install packages from pypi). Both of these can be installed from homebrew. If you have not yet setup homebrew, please see the homebrew installation instructions.

brew install python pipx

Use pipx to install mozphab

MozPhab is the tool needed to interface with Mozilla's instance of Phabricator. This step is needed before the bootstrap step. Pipx is the tool that we will use to install MozPhab and then we will make sure the relevant ~/.local/bin has been added to the PATH envirnoment variable.

pipx install MozPhab
pipx ensurepath 

Mercurial

As noted in the Setting up a build environment page, both mozilla-central and comm-central are version controlled with Mercurial. This means you will need to install Mercurial. Here is a quick command to install it with mercurial but for a more complete list of instructions, please see Mercurial's download page on their wiki.

brew install mercurial

Get the Source

Once you have Mercurial and MozPhab installed, you are ready to grab the source code. There are a couple of different methods to do this.

Scripted

We have created and host a script that will grab the two source repos you need, run ./mach bootstrap for you, and sets up a necessary mozconfig file. This script is called bootstrap.py. Download this file to the directory where you would like your source code folder to live, either by clicking the link and moving the file to the appropriate location or using wget. Then we will make it executable and run it.

mkdir tb-build && cd tb-build
wget https://hg.mozilla.org/comm-central/raw-file/tip/python/rocboot/bin/bootstrap.py
chmod +x bootstrap.py
./bootstrap.py

This will create a mozilla-unified directory with both a mozconfig and a comm/ folder inside. The mozconfig file is setup to build Thunderbird and you can verify this with cat mozconfig; the --enable-project parameter should be comm/mail:

ac_add_options --enable-project=comm/mail

Manually

If you would rather manually gather the source code, perform the bootstrap, and create your mozconfig file, then follow these steps.

Checkout the Source Code

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 needs to be placed inside the Mozilla source code, in a directory named comm/:

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

Create mozconfig file

This step will need to be performed if you manually checked out the code and performed the bootstrap, and it will covered in the next section you follow, Building Thunderbird.

Mach Bootstrap

In the source directory run the following command to get additional dependencies needed to install Thunderbird:

./mach bootstrap

You will be presented with the following options:

Please choose the version of Firefox you want to build:
  1. Firefox for Desktop Artifact Mode
  2. Firefox for Desktop
  3. GeckoView/Firefox for Android Artifact Mode
  4. GeckoView/Firefox for Android

Please choose option 2 to proceed with a successful build.

This action should install all the remaining libraries and dependencies necessary to build Thunderbird locally.

Missing libraries

It could happen that some libraries will not be installed by the bootstrap command, specifically Rust and Go. Check if these packages are available in your system by running these commands in your terminal:

• which rustc

• which cargo

If one or both commands return an empty output, you need to install them manually. We recommend using HomeBrew to download and install these packages in your system. After that, follow these steps:

• Install Rust: brew install rust

• Install C bindings: cargo install cbindgen

export PATH=$HOME/.cargo/bin:$PATH

You're all set

Go back to the Building Thunderbird page and continue following the guide:

Building everything can take a long time, and in many cases is completely unnecessary. If the changes you are making are limited to the UI, or tests, or even some back-end things, then compiling and linking the unchanged C++ and Rust code produces the same results every time. So let's get someone else to do it for us.

This the idea behind artifact builds. Instead of spending our time doing the building, we instead download pre-built copies of those parts (the "binary components") from the build infrastructure. Then we build everything else (what we're interested in) around them. This can reduce time spent from hours to a few minutes.

There is a number of important caveats, so make sure you understand them before going on.

When can I use an artifact build?

In the simplest terms, if the code you are changing appears as plain-text in the final built output, you can use an artifact build. This includes:

• Javascript

• CSS

• XUL

• HTML

• Pre-processed versions of any of the above

• Any support files such as images

When can't I use an artifact build?

You can't use an artifact build if the code you are changing includes:

• C or C++

• Rust

• IDL interfaces if the binary components use the interface

• Statically-linked component .conf files (even if the component is written in JS)

• Some types of build configuration changes

• … and probably others

Modifying your build setup

How you set up to build depends on your scenario. Many people will still need to do a complete build sometimes. In this case, make a copy of your existing mozconfig file and add these lines:

mk_add_options MOZ_OBJDIR=obj-artifact
ac_add_options --enable-artifact-builds

Line 1 ensures your artifact build goes in a separate object directory. Don't use the same object directory for both types of builds. Line 2 enables artifact building.

From here, remember to make sure you're using the right mozconfig (export MOZCONFIG=/path/to/artifact.mozconfig).

If you don't need to do a complete build, you can just add line 2 to your existing mozconfig.

Building the right thing

As stated earlier, the build process downloads the binary components from the build infrastructure. Here's where things can get a little bit messy.

First, things can only be downloaded if they exist. So you need to make sure what you want is available. Mach will download from the latest successful non-nightly build that matches your current comm-central tree. This might not be the one you expect.

Example: if your platform is 64-bit Linux and your tree was up-to-date at this point, which build will you get?

In this example you have a choice:

• wait for the running build to complete (that is, the B to turn green, you don't need to wait for the tests) before building locally

• build now, from the last successful build and hope the changes that have landed since don't affect you

• "update" your trees back to their state when the last successful build happened

Updating to the right revision

To find the revisions used for a successful build, click on the B, and go down to the bottom of the Job Details tab:

Update both comm-central and mozilla-central trees using hg update -r abcdef1234 before building. In general, when a new build begins on the build infrastructure, it uses the latest mozilla-central as well as the latest comm-central, but that may no longer be the case by the time you build.

Other tips

• The build process logs a lot about what it's doing. This can help you understand exactly what's going on so read it the first few times you build.

• You can in many cases do an even quicker rebuild (for example to remake pre-processed files) by running ./mach build faster (or ../mach build -C . faster if your current directory is comm-central). This skips a bunch of steps at the beginning and end of the build process that you might not need. When in doubt, don't build faster.

• Calendar is built differently in an artifact build but this shouldn't affect most people.

Artifact builds on the Try server

Using an artifact build on the Try server can save you a lot of time, and it also reduces our infrastructure costs. The same conditions about when you can and can't do an artifact build apply, plus only 64-bit builds are working.

To do an artifact Try run, add --artifact to your try syntax. For example:

try: -b o -p linux64,macosx64-shippable,win64 -u all --artifact

(Debug builds also work but you'd specify just macosx64 in that case.)

You can (and should in a lot of cases) specify a mozilla-central revision to build from, by editing the file .gecko_rev.yml, replacing default with the revision you need. If you don't, the Try server will use the latest mozilla-central revision, which may or may not be the same one used for the latest comm-central build.