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
  78     # To use Git as your VCS
  79     python3 bootstrap.py --vcs=git
  80
  81     # To use Mercurial as your VCS
  82     python3 bootstrap.py
  83
  84 .. note::
  85
  86     To use ``git``, you can grab the source code in "git" form by running the
  87     bootstrap script with the ``vcs`` parameter:
  88
  89     .. code-block:: shell
  90
  91          python3 bootstrap.py --vcs=git
  92
  93     This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood.
  94
  95 Choosing a build type
  96 ~~~~~~~~~~~~~~~~~~~~~
  97
  98 If you aren't modifying the Firefox backend, then select one of the
  99 :ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are
 100 building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide <geckoview-contributor-guide>`.
 101
 102 3. Build and Run
 103 ----------------
 104
 105 Now that your system is bootstrapped, you should be able to build!
 106
 107 .. code-block:: shell
 108
 109     cd mozilla-unified
 110     hg up -C central
 111     ./mach build
 112
 113 🎉 Congratulations! You've built your own home-grown Firefox!
 114 You should see the following message in your terminal after a successful build:
 115
 116 .. code-block:: console
 117
 118     Your build was successful!
 119     To take your build for a test drive, run: |mach run|
 120     For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
 121
 122 You can now use the ``./mach run`` command to run your locally built Firefox!
 123
 124 If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
 125
 126 Signing
 127 ~~~~~~~
 128
 129 Code signing your Mac build is not required for local testing and is rarely
 130 needed for development. The way Firefox is signed does impact functionality
 131 such as passkey support so it is required in some cases. Generating a build as
 132 close to a production build as possible requires code signing.
 133 See :ref:`Signing Local macOS Builds` for more information.
 134
 135 Running outside the development environment
 136 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 137
 138 To test your changes on another macOS system (or to keep that particular Firefox around after new builds), you can't just use the generated application bundle (``obj-*/dist/Nightly[Debug].app``), since it contains symbolic links to other built libraries. Instead, build a distributable disk image with:
 139
 140 .. code-block:: shell
 141
 142    ./mach package
 143
 144 Copy the resulting ``.dmg`` file from ``obj-*/dist/`` to the target system,
 145 then double-click it as usual to find an ``.app`` bundle containing all
 146 dependencies.
 147
 148 On Apple Silicon Macs, you will need to sign the build for this to work using
 149 :ref:`Signing Local macOS Builds`.
 150
 151 Once the build has been copied to the target system, open it with
 152 right-click->Open. The build will not launch by default because it is not
 153 notarized. In addition to code signing, notarization is required on macOS
 154 10.15+ for a downloaded app to be launchable by double clicking the app in
 155 Finder.
 156
 157 Now the fun starts
 158 ------------------
 159
 160 Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_,
 161 say hello in the `Introduction channel
 162 <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to
 163 start working on <https://codetribute.mozilla.org/>`_.
 164 See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes,
 165 send patches to Mozilla, update your source code locally, and more.
 166
 167 Troubleshooting
 168 ---------------
 169
 170 Build errors
 171 ~~~~~~~~~~~~
 172
 173 If you encounter a build error when trying to setup your development environment, please follow these steps:
 174    1. Copy the entire build error to your clipboard
 175    2. Paste this error to `paste.mozilla.org <https://paste.mozilla.org>`_ in the text area and change the "Expire in one hour" option to "Expire in one week". Note: it won't take a week to get help but it's better to have the snippet be around for a bit longer than expected.
 176    3. Go to the `introduction channel <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`__ and ask for help with your build error. Make sure to post the link to the paste.mozilla.org snippet you created!
 177
 178 The CLOBBER file has been updated
 179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 180
 181 This is a normal error to encounter and tends to appear when working on a bug for a long period of time.
 182 If you encounter this error, you need to run ``./mach clobber`` before running ``./mach build``.
 183 Running ``./mach clobber`` will remove previous build artifacts to restart a build from scratch.
 184 If you are using an artifact build, this will mean that the next build will take slightly longer than usual.
 185 However, if you are using a non-artifact/full build, the next build will take significantly longer to complete.