docs/setup/macos_build.rst

   1 Building Firefox On macOS
   2 =========================
   3
   4 This document will help you get set up to build Firefox on your own
   5 computer. Getting set up can take a while - we need to download a
   6 lot of bytes! Even on a fast connection, this can take ten to fifteen
   7 minutes of work, spread out over an hour or two.
   8
   9 Requirements
  10 ------------
  11
  12 -  **Memory:** 4GB RAM minimum, 8GB+ recommended.
  13 -  **Disk Space:** At least 30GB of free disk space.
  14 -  **Operating System:** macOS - most recent or prior release. It is advisable
  15    to upgrade to the latest “point” release.  See :ref:`build_hosts` for more
  16    information.
  17
  18
  19 1. System preparation
  20 ---------------------
  21
  22 1.1. Install Brew
  23 ~~~~~~~~~~~~~~~~~
  24
  25 Mozilla's source tree requires a number of third-party tools.
  26 You will need to install `Homebrew <https://brew.sh/>`__ so that we
  27 can automatically fetch the tools we need.
  28
  29 1.2. Install Xcode
  30 ~~~~~~~~~~~~~~~~~~
  31
  32 Install Xcode from the App Store.
  33 Once done, finalize the installation in your terminal:
  34
  35 .. code-block:: shell
  36
  37     sudo xcode-select --switch /Applications/Xcode.app
  38     sudo xcodebuild -license
  39
  40 1.3 Install Mercurial
  41 ~~~~~~~~~~~~~~~~~~~~~
  42
  43 Mozilla's source code is hosted in Mercurial repositories. You will
  44 need Mercurial to download and update the code. Additionally, we'll
  45 put user-wide python package installations on the ``$PATH``, so that
  46 both ``hg`` and ``moz-phab`` will be easily accessible:
  47
  48 .. code-block:: shell
  49
  50     echo "export PATH=\"$(python3 -m site --user-base)/bin:$PATH\"" >> ~/.zshenv
  51     python3 -m pip install --user mercurial
  52
  53 Now, restart your shell so that the ``PATH`` change took effect.
  54 You can test that Mercurial is installed by running:
  55
  56 .. code-block:: shell
  57
  58     hg version
  59
  60 .. note::
  61
  62     If you're using a shell other than ``zsh``, you'll need to manually add Python's
  63     ``bin`` directory to your ``PATH``, as your shell probably won't pick up our
  64     changes in ``~/.zshenv``.
  65
  66 2. Bootstrap a copy of the Firefox source code
  67 ----------------------------------------------
  68
  69 Now that your system is ready, we can download the source code and have Firefox
  70 automatically download the other dependencies it needs. The below command
  71 will download a lot of data (years of Firefox history!) then guide you through
  72 the interactive setup process.
  73
  74 .. code-block:: shell
  75
  76     curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -O
  77     python3 bootstrap.py
  78
  79 .. note::
  80
  81     In general, the Firefox workflow works best with Mercurial. However,
  82     if you'd prefer to use ``git``, you can grab the source code in
  83     "git" form by running the bootstrap script with the ``vcs`` parameter:
  84
  85     .. code-block:: shell
  86
  87          python3 bootstrap.py --vcs=git
  88
  89     This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood.
  90
  91 Choosing a build type
  92 ~~~~~~~~~~~~~~~~~~~~~
  93
  94 If you aren't modifying the Firefox backend, then select one of the
  95 :ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are
  96 building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide`.
  97
  98 Cleanup
  99 ~~~~~~~
 100
 101 After finishing the bootstrap process, ``bootstrap.py`` can be removed.
 102
 103 .. code-block:: shell
 104
 105     rm bootstrap.py
 106
 107 3. Build
 108 --------
 109
 110 Now that your system is bootstrapped, you should be able to build!
 111
 112 .. code-block:: shell
 113
 114     cd mozilla-unified
 115     ./mach build
 116     ./mach run
 117
 118 🎉 Congratulations! You've built your own home-grown Firefox!
 119
 120 Now the fun starts
 121 ------------------
 122
 123 Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_,
 124 say hello in the `Introduction channel
 125 <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to
 126 start working on <https://codetribute.mozilla.org/>`_.
 127 See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes,
 128 send patches to Mozilla, update your source code locally, and more.
 129
 130 Troubleshooting
 131 ---------------
 132
 133 macOS SDK is unsupported
 134 ~~~~~~~~~~~~~~~~~~~~~~~~
 135
 136 .. only:: comment
 137
 138     If you are editing this section to bump the SDK and Xcode version, I'd recommend
 139     following the steps to ensure that they're not obsolete. Apple doesn't guarantee
 140     the structure of Xcode, so the SDK could be moved to a different location or
 141     stored differently.
 142
 143 If the SDK included with your Xcode installation is not supported by Firefox,
 144 you'll need to manually install one that is compatible.
 145 We're currently using the 11 SDK on our build servers, so that's the one that you
 146 should install:
 147
 148 1. Go to the `More Downloads for Apple Developers <https://developer.apple.com/download/more/>`_ page
 149    and download Xcode 12.5.1.
 150 2. Once downloaded, extract ``Xcode_12.5.1.xip``.
 151 3. In your terminal, copy the SDK from the installer:
 152
 153 .. code-block:: shell
 154
 155     mkdir -p ~/.mozbuild/macos-sdk
 156     # This assumes that Xcode is in your "Downloads" folder
 157     cp -aH ~/Downloads/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX11.3.sdk ~/.mozbuild/macos-sdk/
 158
 159 4. Finally, inform the Firefox build about this SDK by creating (or editing) a file called ``mozconfig`` file
 160    in the Firefox source code directory. Add the following line:
 161
 162 .. code-block::
 163
 164     ac_add_options --with-macos-sdk=$HOME/.mozbuild/macos-sdk/MacOSX11.3.sdk
 165
 166 5. Now, you should be able to successfully run ``./mach build``.