diff options
Diffstat (limited to 'docs/setup/macos_build.rst')
| -rw-r--r-- | docs/setup/macos_build.rst | 122 |
1 files changed, 122 insertions, 0 deletions
diff --git a/docs/setup/macos_build.rst b/docs/setup/macos_build.rst new file mode 100644 index 0000000000..3d32b8aed0 --- /dev/null +++ b/docs/setup/macos_build.rst @@ -0,0 +1,122 @@ +Building Firefox On macOS +========================= + +This document will help you get set up to build Firefox on your own +computer. Getting set up 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. + +Requirements +------------ + +- **Memory:** 4GB RAM minimum, 8GB+ recommended. +- **Disk Space:** At least 30GB of free disk space. +- **Operating System:** macOS - most recent or prior release. It is advisable + to upgrade to the latest “point” release. See :ref:`build_hosts` for more + information. + + +1. System preparation +--------------------- + +1.1. Install Brew +~~~~~~~~~~~~~~~~~ + +Mozilla's source tree requires a number of third-party tools. +You will need to install `Homebrew <https://brew.sh/>`__ so that we +can automatically fetch the tools we need. + +1.2. Install Xcode +~~~~~~~~~~~~~~~~~~ + +Install Xcode from the App Store. +Once done, finalize the installation in your terminal: + +.. code-block:: shell + + sudo xcode-select --switch /Applications/Xcode.app + sudo xcodebuild -license + +1.3 Install Mercurial +~~~~~~~~~~~~~~~~~~~~~ + +Mozilla's source code is hosted in Mercurial repositories. You will +need Mercurial to download and update the code. Additionally, we'll +put user-wide python package installations on the ``$PATH``, so that +both ``hg`` and ``moz-phab`` will be easily accessible: + +**NOTE** Pay special attention to the `==6.1.4`, as Mercurial >=6.2 is incompatible with several plugins + +.. code-block:: shell + + echo 'export PATH="'"$(python3 -m site --user-base)"'/bin:$PATH"' >> ~/.zshenv + python3 -m pip install --user mercurial==6.1.4 + +Now, restart your shell so that the ``PATH`` change took effect. +You can test that Mercurial is installed by running: + +.. code-block:: shell + + hg version + +.. note:: + + If you're using a shell other than ``zsh``, you'll need to manually add Python's + ``bin`` directory to your ``PATH``, as your shell probably won't pick up our + changes in ``~/.zshenv``. + +2. Bootstrap a copy of the Firefox source code +---------------------------------------------- + +Now that your system is ready, we can download the source code and have Firefox +automatically download the other dependencies it needs. The below command +will download a lot of data (years of Firefox history!) then guide you through +the interactive setup process. + +.. code-block:: shell + + curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -O + python3 bootstrap.py + +.. note:: + + In general, the Firefox workflow works best with Mercurial. However, + if you'd prefer to use ``git``, you can grab the source code in + "git" form by running the bootstrap script with the ``vcs`` parameter: + + .. code-block:: shell + + python3 bootstrap.py --vcs=git + + This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood. + +Choosing a build type +~~~~~~~~~~~~~~~~~~~~~ + +If you aren't modifying the Firefox backend, then select one of the +:ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are +building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide`. + +3. Build +-------- + +Now that your system is bootstrapped, you should be able to build! + +.. code-block:: shell + + cd mozilla-unified + hg up -C central + ./mach build + ./mach run + +🎉 Congratulations! You've built your own home-grown Firefox! + +Now the fun starts +------------------ + +Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_, +say hello in the `Introduction channel +<https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to +start working on <https://codetribute.mozilla.org/>`_. +See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes, +send patches to Mozilla, update your source code locally, and more. |