summaryrefslogtreecommitdiffstats
path: root/docs/setup/macos_build.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/setup/macos_build.rst')
-rw-r--r--docs/setup/macos_build.rst151
1 files changed, 151 insertions, 0 deletions
diff --git a/docs/setup/macos_build.rst b/docs/setup/macos_build.rst
new file mode 100644
index 0000000000..df3719e648
--- /dev/null
+++ b/docs/setup/macos_build.rst
@@ -0,0 +1,151 @@
+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:
+
+.. code-block:: shell
+
+ echo 'export PATH="'"$(python3 -m site --user-base)"'/bin:$PATH"' >> ~/.zshenv
+ python3 -m pip install --user mercurial
+
+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::
+
+ 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 <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
+
+🎉 Congratulations! You've built your own home-grown Firefox!
+You should see the following message in your terminal after a successful build:
+
+.. code-block:: console
+
+ Your build was successful!
+ To take your build for a test drive, run: |mach run|
+ For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
+
+You can now use the ``./mach run`` command to run your locally built Firefox!
+
+If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
+
+Running outside the development environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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:
+
+.. code-block:: shell
+
+ ./mach package
+
+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.
+
+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.
+
+Troubleshooting
+---------------
+
+Build errors
+~~~~~~~~~~~~
+
+If you encounter a build error when trying to setup your development environment, please follow these steps:
+ 1. Copy the entire build error to your clipboard
+ 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.
+ 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!