path: root/docs/setup/macos_build.rst

Building Firefox On macOS
=========================

This document will help you get set up to build Firefox on your own
computer. 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:

.. rubric:: Quick start (Try this first!)
   :name: Quick_start_Try_this_first!

.. rubric:: Prerequisites
   :name: Prerequisites

You will need:

-  an Apple ID to download and install Apple-distributed developer tools
   mentioned below
-  from 5 minutes to 1 hour to download and install Xcode, which is
   large
-  download and install a local copy of specific macOS SDK version

You will need administrator permissions on your machine to install these
prerequisites. (You can verify that you have these permissions in System
Preferences -> Users & Groups.)

See :ref:`1.1 Install Xcode and Xcode command line tools <xcode>` and :ref:`1.2
Get the local macOS SDK <macossdk>` for more information on how to
install these prerequisites.

.. rubric:: Getting the source
   :name: Getting_the_source
   :class: heading-tertiary

Firstly you need to prepare a directory and get the bootstrap script
that will do the rest:

.. code-block:: shell

    # the bootstrap script needs this directory, but you can choose a different target directory for the Mozilla code later
    cd ~ && mkdir -p src && cd src

    # download the bootstrap script
    curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -o bootstrap.py

If you don't have Python 3.6 or later or Mercurial installed, see :ref:`2.1a Install
dependencies via Homebrew <#install-via-homebrew>` for more information on how
to do so. Then in your terminal from above start the bootstrapper like this:

.. code-block:: shell

    python3 bootstrap.py

... and follow the prompts. This will use mercurial to checkout the
source code. If you prefer to work with git, use this command instead:

.. code-block:: shell

    python3 bootstrap.py --vcs=git

If you don't have `Homebrew <https://brew.sh/>`_ or
`Ports <https://www.macports.org/>`__ 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.

If you don't let the ``bootstrap.py`` script clone the source for you
make sure you do it manually afterward before moving onto the next step.

.. rubric:: Build Firefox!
   :name: Build_Firefox!
   :class: heading-tertiary highlight-spanned

Now we tie it all together.

In your terminal window, ``cd`` to your Mozilla source directory chosen
before and type:

.. code-block:: shell

    # create a minimal build options file
    echo "ac_add_options --with-macos-sdk=$HOME/SDK-archive/MacOSX10.12.sdk" >> mozconfig

    ./mach bootstrap

    ./mach build

The ``./mach bootstrap`` step is a catch-all for any dependencies not
covered in this documentation. If you are working on Firefox frontends
or building Firefox without any changes, select :ref:`Artifact Builds
<Understanding Artifact Builds>` in
the first question in ``./mach bootstrap``.  Artifact builds will
complete more quickly!  Artifact builds are unsuitable for those working
on C++ code.

You’re on your way. Don’t be discouraged if this takes a while; it takes
some time even on the fastest modern machines and as much as two hours
or more on older hardware. Firefox is pretty big, because the Web is
big.

.. rubric:: Now the Fun Starts
   :name: Now_the_Fun_Starts
   :class: heading-tertiary

You have the code, you’ve compiled Firefox. Fire it up with
``./mach run`` and you’re ready to start hacking.

Build steps (details)
---------------------

Building on macOS is divided into the following steps:

#. Install Apple-distributed developer tools - Xcode, Xcode cli tools
   and macOS SDK locally
#. Install supplementary build tools
#. Obtain a copy of the Mozilla source code
#. Configure the Mozilla source tree to suit your needs
#. Build Firefox


.. _xcode:

1.1 Install Xcode and Xcode command line tools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You first need to install Xcode, for which you have two options but both
require you to sign in with an Apple ID:

-  From Apple Developer Download page - `direct
   link <https://developer.apple.com/download/release/>`__. Install the
   latest **release** (non-beta) version of Xcode, open ``Xcode.xip``,
   and then **before** **running the extracted Xcode.app, move it from
   the download folder to /Applications**. (Running it from another
   location may screw up various build paths, homebrew builds, etc. Fix
   by running ``sudo xcode-select -switch /Applications/Xcode.app`` )
-  From the Mac App Store - `direct
   link <https://apps.apple.com/us/app/xcode>`__.

Open /Applications/Xcode.app and let it do its initial first run and
setup stuff.

Install the Xcode command line tools by
running ``xcode-select --install`` in your terminal.

.. _macossdk:

1.2 Get the local macOS SDK
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Firefox currently requires a local copy of macOS 10.12 SDK to build (all
your other apps will still use your more recent version of this SDK,
most probably matching your macOS version).

There are various issues when building the Mozilla source code with
other SDKs and that's why we recommend this specific version.

To get the 10.12 SDK, first download Xcode 8.2 from the `More
Downloads for Apple
Developers <https://developer.apple.com/download/more/>`__ page. Once
downloaded, mount the .dmg file. Then in the Terminal run the following:

.. code-block:: shell

    mkdir -p $HOME/SDK-archive
    cp -a /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk $HOME/SDK-archive/MacOSX10.12.sdk

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

.. _install-via-homebrew:

2.1a Install dependencies via Homebrew
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

`Homebrew <http://brew.sh/>`__ is "the missing package manager for
macOS." 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://brew.sh/

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

.. code-block:: shell

    brew install yasm mercurial gawk ccache python

Python 2 is never necessary solely to build Firefox, but it is still required
for some development tasks (including testing and pushing to ``try``). If your
system does not already have a Python 2 installed, you can use ``brew`` to
install one:

.. code-block:: shell

    brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/86a44a0a552c673a05f11018459c9f5faae3becc/Formula/python@2.rb

2.1b Install Dependencies via MacPorts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

To install MacPorts, go to their `install
page <http://www.macports.org/install.php>`_, download the .dmg for
your platform, and install it. If you already have MacPorts installed,
ensure it is up to date by running:

.. code::

    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 the
   troubleshooting section below).

Use MacPorts to install the packages needed for building Firefox:

.. code::

    sudo port install libidl yasm python27 py27-gnureadline

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 macOS:

1. Install `official builds from
   Selenic <http://mercurial.selenic.com/>`_

2. Install via Homebrew:

.. code-block:: shell

       brew install mercurial

3. Install via MacPorts:

.. code-block:: shell

       sudo port install mercurial

4. Install via Pip:

.. code-block:: shell

       easy_install pip && pip install mercurial

Once you have installed Mercurial, test it by running:

.. code-block:: shell

    hg version

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

If this fails with the error "``ValueError: unknown locale: UTF-8``",
then see the
`workarounds <http://www.selenic.com/mercurial/wiki/index.cgi/UnixInstall#head-1c10f216d5b9ccdcb2613ea37d407eb45f22a394>`_
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 :ref:`Getting Mozilla Source Code
Using Mercurial <Mercurial Overview>` for the
complete instructions.

If you are interested in Firefox development only then run the following
command, which will create a new directory, ``mozilla-central``, in the
current one with the contents of the remote repository.

Below command will take many minutes to run, as it will be copying a
couple hundred megabytes of data over the internet.

.. code::

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

(If you are building Firefox for Android, you should now return to the
`Android build instructions <https://wiki.mozilla.org/Mobile/Fennec/Android#Mac_OS_X>`_.)

4. Configure the build options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In your checked out source tree create a new file, ``mozconfig``, which
will contain your build options. For more on this file, see :ref:`Configuring Build Options`.

To get started quickly, create the file with the following contents:

.. code::

    # 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

    # Enable debug builds
    ac_add_options --enable-debug

    # Use the local copy of specific version of macOS SDK compatible with Mozilla source code
    ac_add_options --with-macos-sdk=$HOME/SDK-archive/MacOSX10.12.sdk

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 9 via Homebrew, then you need to have this in your
``mozconfig``:

.. code::

    CC=clang-9
    CXX=clang++-9

5. Build
~~~~~~~~

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

.. code-block:: shell

    ./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``.
To launch the application, try running the following:

.. code-block:: shell

    ./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 <#Software_Requirements>`_ required
to build Firefox. Firefox can take a long time to build, so more CPU,
more RAM and lots of fast disk space are 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:** macOS 10.12 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 this from the App
   Store.
-  **Package Management:** Either Homebrew or
   `MacPorts <http://www.macports.org/>`_.

These options are specific to Mozilla builds for macOS. For a more
general overview of build options and the ``mozconfig`` file, see
:ref:`Configuring Build Options`.

-  **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.
      -  Following the instructions in the `clang
         website <http://clang.llvm.org/get_started.html>`__ 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.

-  **macOS 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``.

   .. code-block:: shell

         ac_add_options --with-macos-sdk=/path/to/SDK

   Official trunk builds use `MacOSX10.12.sdk`. Check
   `build/macosx/universal/mozconfig.common <https://searchfox.org/mozilla-central/source/build/macosx/cross-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 macOS 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 macOS 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:

.. code-block:: shell

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

Troubleshooting
---------------

-  **If configure (or generally building with clang) fails with
   ``fatal error: 'stdio.h' file not found``:** Make sure the Xcode
   command line tools are installed by running.
   ``xcode-select --install``.
-  **For inexplicable errors in the configure phase:** Review all
   modifications of your PATH in .bash\_profile, .bash\_rc or whatever
   configuration file you're using for your chosen shell. Removing all
   modifications and then re-adding them one-by-one can narrow down
   problems.