Building Firefox for OSX

Thank you for helping us build the world's best browser on the world's most popular OS. This document will will help you get set up to build and hack on your own version of Firefox on your local machine. Getting set up won't be difficult, but it can take a while - we need to download a lot of bytes! Even on a fast connection, this can take ten to fifteen minutes of work, spread out over an hour or two.

The details are further down this page, but this quick-start guide should get you up and running:

Getting Ready

They aren’t complicated, but there are a few prerequisites to build Firefox on OSX. You need:

  • Some familiarity with the OSX terminal environment.
  • OSX 10.7 or later. If you're not sure, "About this Mac" under the Apple menu will tell you.
  • Next, check to make sure you have Python installed. Python ships by default with OSX, so you can check by opening a terminal window and typing python --version. However, if you run into cryptic errors during your build, be aware that Python 2.7.11 (no higher, no lower) is the only version of Python confirmed to work perfectly with bootstrap.py. Use pyenv if you'd like to keep multiple Python versions available on your machine.
  • Finally, internet connection and about 40GB of free disk space for XCode, the Firefox source and room to build.

 

Getting Started.

Getting set up on OSX is fast and easy. If you don’t have one yet, create a "src" directory for yourself under your home directory:

cd && mkdir src

Next download the bootstrap.py script and save it in your src/ directory.

And finally, in your terminal: cd ~/src and start the bootstrapper like this:

python bootstrap.py

... and follow the prompts. If you don't have Homebrew or Ports installed - software package managers that will let us install some programs we'll need - you'll be asked to pick one. Either will work, but most Mozilla developers use Homebrew.

Getting Access

That last step can take some time to finish While it’s running, take a moment to sign in to Bugzilla. Bugzilla.mozilla.org is Mozilla’s issue tracker. To comment on a bug or submit a patch you’ll need a Bugzilla account. You can either use your GitHub account, or you can sign up for a Bugzilla account here.

As well as Bugzilla, much of Mozilla’s internal communication happens over IRC. You can download Limechat here, and learn how to connect to Mozilla with IRC here. If you’re just getting started or have questions about getting set up you can join us in the #introduction channel, where some of our community members hang out to try and help new contributors get rolling.

Get The Code

This is the last big step. In a terminal, in your src/ directory, enter:

hg clone https://hg.mozilla.org/mozilla-central/

... and enter. This step uses mercurial to pull down the Firefox source code from Mozilla-Central. hg is the chemical symbol for mercury, if you’re wondering.

While you’re waiting for that to finish, take a look at our Mercurial documentation.

It explains how we use version control at Mozilla to manage our code and land changes to our source tree.

Let’s Build Firefox

You’re ready; now we can tie it all together. In your terminal:

cd mozilla-central
./mach build

And you’re on your way, building your own copy of Firefox from source.

Don’t get discouraged if this takes a while; Firefox is pretty big, and this takes some time on even the fastest modern machines.

Join Mozillians.org!

There’s one more thing you can do for yourself while you’re waiting: create an account for yourself on Mozillians. Mozillians is the Mozilla community directory, where you can connect with people who share your interests, projects or countries. This step is optional, but we think it will be worth your while.

Now the fun starts.

You have the code, you’ve compiled Firefox. Fire it up with ./mach run and you’re ready to start hacking. The next steps are up to you: join us on IRC in the#introduction channel, follow StartMozilla on Twitter and find a a bug to start working on.

Thank you

Mozilla's strength is the community behind it; Firefox is the product of a global development team working to keep the Web free, open and participatory, and your contributions will make Firefox and the Web better for hundreds of millions of people around the world.

The Details

Mozilla builds for OS X are Mach-O builds, built from Makefiles. Doing builds on OS X is therefore very similar to doing Unix/Linux builds. You should be comfortable using the Terminal app (in /Applications/Utilities). Additional instructions are available for building Mozilla as a universal binary.

If you run into problems, see the Mozilla Build Frequently Asked Questions or the rest of the Mozilla build documentation.

One-Line Setup (Try This First!)

Run the following in a terminal:

curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py > bootstrap.py && python bootstrap.py

This will help you install all the build prerequisites for OS X. Your account will need permission to administer this computer to succeed; you can verify that you have this permission in System Preferences -> Users & Groups.

In some circumstances - particularly if you've got a MacPorts or Homebrew development environment already set up - this script can error out. Most of those errors can be resolved by bringing your MacPorts or Homebrew installations up to date.

You can do this with:

port selfupdate && port upgrade outdated

for MacPorts and

brew update && brew upgrade

for Homebrew. If that doesn't work, or you need more details, please contact Mike Hoye. The documentation below may also be of assistance.

You will need:

  • Apple ID (to install Xcode)
  • 1 hour (to download and install Xcode, which is slow)
  • Homebrew or Macports  (bootstrap.py will install these if necessary)

Once your build environment is complete, proceed to Step 3 below.

Build Steps (Details)

Building on OS X is divided into the following steps:

  1. Install Apple-distributed developer tools
  2. Install supplementary build tools
  3. Obtain a copy of the Mozilla source code
  4. Configure the Mozilla source tree to suit your needs
  5. Build Firefox

1. Install Apple-distributed developer tools

For all versions of OS X, you will need to install Xcode to build any Mozilla application.

Note that for Xcode 4.5 and later the expected install location is /Applications (not /Developer/Applications). When you run a 4.5+ .dmg it will simply show you an Xcode.app file. Take care NOT to run this .app from there. Drag it to /Applications and run it from there instead. If you run Xcode.app from the .dmg folder directly it will screw up various paths associated with your Xcode install by making them point into /Volumes/Xcode/Xcode.app. That in turn will break building of Mozilla (probably with build errors making WebRTC makefiles), updating of MacPorts, etc. once the .dmg is unmounted! If you do find yourself in this position, try running

sudo xcode-select -switch /Applications/Xcode.app

Note that if you get a build failure where it can't find "find_sdk.py" when generating webrtc makefiles from .gyp files, this is likely your problem.

You can download and install Xcode from:

  • https://developer.apple.com/downloads/index.action (Apple ID required, but subscription and credit card info not required.)
  • The Apple App Store (in newer versions of OS X)
    • Note that you need to run /Applications/Install Xcode.app after installing Xcode via the App Store. This, however, may fail due to "untrusted package" error. One known workaround to this is to set the computer's clock back temporarily to 1/1/2010 and trying the installation again.
  • The Mac OS X Install DVD that came with your computer. The Xcode or XcodeTools installer should be located in the "Optional Installs" folder. If possible, you should obtain Xcode from the Internet to ensure you have an up-to-date version.

Generally, any released version of Xcode should build the latest version of a Mozilla source tree. However, early adopters of new and beta Xcode releases may see incompatibilities. Therefore, heed caution when upgrading OS X and Xcode.

The compatibility of various OS X and Xcode versions is listed in the Software Requirements section below.

For Xcode 4.5 and up you will also need to manually install the Command Line Tools: Xcode > Preferences > Downloads > Command line tools > Components > Install. (Failing to do this when upgrading from an older version of Xcode will simply leave you with the old /usr/bin/clang etc.)

Note: the Apple version of clang 4.2 is now required.  If you see the error message below you are likely using an older clang version:

In file included from .../js/src/vm/PropertyKey.cpp:9:
./../../dist/include/js/PropertyKey.h:35:7: error: no member named 'operator=' in 'JS::Value'
class PropertyKey
      ^~~~~~~~~~~
./../../dist/include/js/PropertyKey.h:87:14: note: implicit default move assignment operator for 'JS::PropertyKey' first required here
        *key = PropertyKey(uint32_t(v.toInt32()));
             ^
1 error generated.

2. Install supplementary build tools

Mozilla's source tree requires a number of third party tools and applications to build it. You will need to install these before you can build anything.

You have the choice over how to install all these components. You can use a package manager like Homebrew or Ports. Or, you can obtain, compile, and install them individually. For simplicity and to save your time, using a package manager is recommended. The following sections describe how to install the packages using existing package managers. Choose whatever package manager you prefer.

You can also use these package managers to install Clang if your version of Xcode doesn't have it already.

2.1a Install Dependencies via Homebrew

Homebrew is "the missing package manager for OS X." It provides a simple command-line interface to install packages, typically by compiling them from source.

The first step is to install Homebrew. See https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Installation.md#installation

Once you have Homebrew installed, you'll need to run the following:

brew install yasm mercurial gawk ccache python

Depending on the version of Xcode you are using, "brew install mercurial" may fail due to a missing Mac OS 4 universal SDK. You may work around this issue by directly installing mercurial binary from this site, and installing yasm only using brew.

You will also need autoconf 2.13, but the core Homebrew repository will install a newer version by default, so you need to specify the version when installing it:

brew install autoconf@2.13

If you get errors trying to build, it means you have another version of autoconf installed and used as default. To use autoconf 2.13, run:

​brew link --overwrite autoconf@2.13

 

2.1b Install Dependencies via MacPorts

MacPorts is a package manager for OS X. If you are running Homebrew, you can ignore this section.

To install MacPorts, go to their install page, download the .dmg for your platform, and install it. If you already have MacPorts installed, ensure it is up to date by running:

sudo port selfupdate
sudo port sync

The first of these commands will ask for your root password.

Common errors include:

  • sudo doesn't accept a blank password: create a password for your account in System Preferences.
  • port command not found: add it to your path (see troubleshooting section below).

Use MacPorts to install the packages needed for building Firefox:

sudo port install libidl autoconf213 yasm

You'll then see lots of output as MacPorts builds and installs these packages and their dependencies -- it takes a while, so go grab a cup of coffee.

Note: By default, this will install Python 2.7, which in turn will pull in all of the X11 libraries, which may take a while to build.  You don't need any of those to build Firefox; you may want to consider adding +no_tkinter to the install line to build a python without support for the X11 UI packages.  This should result in a much faster install.
Note: With older versions of Xcode (eg 6.4) you may need to use MacPorts to get the proper version of clang, such as clang-3.6 or later. See bugs in Core, Build Config referring to clang.

2.2 Install Mercurial

Mozilla's source code is hosted in Mercurial repositories. You use Mercurial to interact with these repositories. There are many ways to install Mercurial on OS X:

  1. Install official builds from Selenic
  2. Install via MacPorts:
    sudo port install mercurial
  3. Install via Homebrew:
    brew install mercurial
  4. Install via Pip
    easy_install pip && pip install mercurial

Once you have installed Mercurial, test it by running:

hg version

If this works, congratulations! You'll want to configure your Mercurial settings to match other developers. See Getting Mozilla Source Code Using Mercurial.

If this fails with the error "ValueError: unknown locale: UTF-8", then see the workarounds on the Mercurial wiki's Unix Install page.

When trying to clone a repository you may get an HTTP 500 error (internal server error). This seems to be due to something that Mac Mercurial sends to the server (it's been observed both with MacPort and selenic.com Mercurial binaries). Try restarting your shell, your computer, or reinstall Mercurial (in that order), then report back here what worked, please.

3. Obtain a copy of the Mozilla source code

You may want to read Getting Mozilla Source Code Using Mercurial for the complete instructions. If you are interested in Firefox development:

# The following will create a new directory, mozilla-central, in the
# current one with the contents of the remote repository. This command
# will take many minutes to run, as it will be copying a couple hundred
# megabytes of data over the internet.
$ hg clone https://hg.mozilla.org/mozilla-central/ mozilla-central
$ cd mozilla-central

(If you are building Firefox for Android, you should now return to the Android build instructions.)

4. Configure the Mozilla source tree for build options

In your checked out source tree, you'll create a new file, .mozconfig, which contains your build options. For more on this file, see Configuring Build Options.

To quickly get started, create the file .mozconfig file in your source tree clone with the following contents:

# Define where build files should go. This places them in the directory
# "obj-ff-dbg" under the current source directory
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-ff-dbg
# -s makes builds quieter by default
# -j4 allows 4 tasks to run in parallel. Set the number to be the amount of
# cores in your machine. 4 is a good number.
mk_add_options MOZ_MAKE_FLAGS="-s -j4"
# Enable debug builds
ac_add_options --enable-debug

Builds require the 10.7 SDK or higher. If you'd like to ensure compatibility with an operating system version previous to the one you are building on, you can explicitly specify an SDK by adding a line like this:

ac_add_options --with-macos-sdk=/Developer/SDKs/MacOSX10.8.sdk

For MacOSX 10.10, or maybe for versions of Xcode after version 6, this may need to be a different path, for example:

ac_add_options --with-macos-sdk=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk

Or, check the /Applications/Xcode.app/Contents/Developer/Platforms directory to see which SDKs are installed, and pick one to add into your .mozconfig.

Firefox no longer builds with gcc 4.8 or earlier, but the build system should automatically select clang if it is available in the PATH. If that is not the case, you need to set CC and CXX.  For instance, if you installed Clang 3.7 via Homebrew, then you need to have

CC=clang-mp-3.7
CXX=clang++-mp-3.7

If you installed autoconf 2.13 with the Homebrew recipe linked above, you may need to add the following to your .mozconfig:

mk_add_options AUTOCONF=/usr/local/Cellar/autoconf@2.13/2.13/bin/autoconf213

5. Build

Once you have your .mozconfig file in place, you should be able to build!

./mach build

If the build step works, you should be able to find the built application inside obj-ff-dbg/dist/. If building the browser with --enable-debug, the name of the application is NightlyDebug.app. Try running the following:

./mach run
Note: The compiled application may also be named after the branch you're building; for example, if you changed these instructions to fetch the mozilla-1.9.2 branch, the application will be named Namoroka.app or NamorokaDebug.app.

Hardware requirements

There are no specific hardware requirements, provided that the hardware accommodates all of the software required to build Firefox. Firefox can take a long time to build, so more CPU, more RAM and lots of fast disk is always recommended.

  • Processor:  Intel CPUs are required. Building for PowerPC chips is not supported.
  • Memory: 2GB RAM minimum, 8GB recommended.
  • Disk Space: At least 30GB of free disk space.

Software requirements

  • Operating System: Mac OS X 10.7 or later. It is advisable to upgrade to the latest “point” release by running Software Update, found in the Apple menu. You will need administrative privileges to set up your development environment
  • Development Environment: Xcode. You can obtain from the App Store.
  • Package Management: Either MacPorts or Homebrew.
  • autoconf version 2.13 is needed if you plan on making changes to the Mozilla configure.in files on versions up to 1.9 and when building from mozilla-central. Newer versions of autoconf, including those that come with Xcode and installed in /usr/bin, are incompatible with Mozilla (bug 104642). You can install autoconf 2.13 from either MacPorts or Homebrew.
  • Mercurial source control system (if you're planning to work on post-1.9.0 code). See Mercurial#Installing..mozconfig options and other tunables

These options are specific to Mozilla builds for OS X. For a more general overview of build options and the .mozconfig file, see Configuring Build Options. For specific information on configuring to build a universal binary, see Mac OS X Universal Binaries.

  • Compiler: Firefox releases are no longer built with gcc-4.8 or earlier. A recent copy of clang is needed.
  • There are some options on where to get clang:
    • Newer versions of xcode. The one in xcode 7.0 or newer and the open source 3.6 release should work.
      (Xcode 6.4 is based on pre-release of clang 3.6, that doesn't match to requirement)
    • Following the instructions in the clang web site for information on how to get it.
    • Using some of the package managers (see above).
    Once clang is installed, make sure it is on the PATH and configure should use it.

The following options, specified with ac_add_options, are lines that are intended to be added to your .mozconfig file.

  • Mac OS X SDK: This selects the version of the system headers and libraries to build against, ensuring that the product you build will be able to run on older systems with less complete APIs available. Selecting an SDK with this option overrides the default headers and libraries in /usr/include, /usr/lib, and /System/Library. Mac OS X SDKs are installed in /Developer/SDKs during the Xcode installation by selecting the Cross Development category in the installer’s Customize screen.
    ac_add_options --with-macos-sdk=/path/to/SDK
    

    Official trunk builds use /Developer/SDKs/MacOSX10.7.sdk. Check build/macosx/universal/mozconfig.common for the SDK version used for official builds of any particular source release.

    Applications built against a particular SDK will usually run on earlier versions of Mac OS X as long as they are careful not to use features or frameworks only available on later versions. Note that some frameworks (notably AppKit) behave differently at runtime depending on which SDK was used at build time. This may be the source of bugs that only appear on certain platforms or in certain builds.

For OS X builds, defines are set up as follows:

  • XP_MACOSX is defined
  • XP_UNIX is defined
  • XP_MAC is not defined. XP_MAC is obsolete and has been removed from the source tree (see bug 281889). It was used for CFM (non-Mach-O) builds for the classic (pre-X) Mac OS.

This requires care when writing code for Unix platforms that exclude Mac:

#if defined(XP_UNIX) && !defined(XP_MACOSX)

Troubleshooting

  • Unable to build with GCC. Apple used to ship a GCC based on vanilla GCC 4.2. They still ship LLVM-GCC (which is also base on GCC 4.2). Mozilla does not support building with any GCC 4.2 variant anymore. On OS X, non-Apple (i.e. stock) GCCs are also not supported (they don't support blocks), so you must use clang on OS X.
  • Using Fink with Virex 7.2: There is a conflict between Fink and Virex 7.2. Both place files within /sw. If you have Virex installed, you will need to upgrade to at least version 7.2.1, as described in the Fink News (2003-04-16).
  • If configure (or generally building with clang) generates this error: fatal error: 'stdio.h' file not found
    Try making sure xcode command line tools are installed by running: xcode-select --install [jgilbert] found this necessary during an install for 10.9.

Building with --enable-dtrace fails with configure: error: dtrace enabled but sys/sdt.h not found

Make sure you use the 10.5 SDK, not 10.4 as in the default configuration.