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     To use ``git``, you can grab the source code in "git" form by running the
  82     bootstrap script with the ``vcs`` parameter:
  83
  84     .. code-block:: shell
  85
  86          python3 bootstrap.py --vcs=git
  87
  88     This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood.
  89
  90 Choosing a build type
  91 ~~~~~~~~~~~~~~~~~~~~~
  92
  93 If you aren't modifying the Firefox backend, then select one of the
  94 :ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are
  95 building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide <geckoview-contributor-guide>`.
  96
  97 3. Build
  98 --------
  99
 100 Now that your system is bootstrapped, you should be able to build!
 101
 102 .. code-block:: shell
 103
 104     cd mozilla-unified
 105     hg up -C central
 106     ./mach build
 107
 108 🎉 Congratulations! You've built your own home-grown Firefox!
 109 You should see the following message in your terminal after a successful build:
 110
 111 .. code-block:: console
 112
 113     Your build was successful!
 114     To take your build for a test drive, run: |mach run|
 115     For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
 116
 117 You can now use the ``./mach run`` command to run your locally built Firefox!
 118
 119 If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
 120
 121 Running outside the development environment
 122 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 123
 124 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:
 125
 126 .. code-block:: shell
 127
 128    ./mach package
 129
 130 Copy the resulting ``.dmg`` file from ``obj-*/dist/`` to the target system, then double-click it as usual to find an ``.app`` bundle containing all dependencies.
 131
 132 Now the fun starts
 133 ------------------
 134
 135 Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_,
 136 say hello in the `Introduction channel
 137 <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to
 138 start working on <https://codetribute.mozilla.org/>`_.
 139 See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes,
 140 send patches to Mozilla, update your source code locally, and more.
 141
 142 Troubleshooting
 143 ---------------
 144
 145 Build errors
 146 ~~~~~~~~~~~~
 147
 148 If you encounter a build error when trying to setup your development environment, please follow these steps:
 149    1. Copy the entire build error to your clipboard
 150    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.
 151    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!