macos_build.rst (6731B)
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 2. Bootstrap a copy of the Firefox source code 41 ---------------------------------------------- 42 43 Now that your system is ready, we can download the source code and have Firefox 44 automatically download the other dependencies it needs. The below command 45 will download a lot of data (years of Firefox history!) then guide you through 46 the interactive setup process. 47 48 .. code-block:: shell 49 50 curl -L https://raw.githubusercontent.com/mozilla-firefox/firefox/refs/heads/main/python/mozboot/bin/bootstrap.py -O 51 python3 bootstrap.py 52 53 Choosing a build type 54 ~~~~~~~~~~~~~~~~~~~~~ 55 56 If you aren't modifying the Firefox backend, then select one of the 57 :ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are 58 building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide <geckoview-contributor-guide>`. 59 60 3. Build and Run 61 ---------------- 62 63 Now that your system is bootstrapped, you should be able to build! 64 65 .. code-block:: shell 66 67 cd firefox 68 git pull 69 ./mach build 70 71 🎉 Congratulations! You've built your own home-grown Firefox! 72 You should see the following message in your terminal after a successful build: 73 74 .. code-block:: console 75 76 Your build was successful! 77 To take your build for a test drive, run: |mach run| 78 For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html 79 80 You can now use the ``./mach run`` command to run your locally built Firefox! 81 82 If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_. 83 84 Signing 85 ~~~~~~~ 86 87 Code signing your Mac build is not required for local testing and is rarely 88 needed for development. The way Firefox is signed does impact functionality 89 such as passkey support so it is required in some cases. Generating a build as 90 close to a production build as possible requires code signing. 91 See :ref:`Signing Local macOS Builds` for more information. 92 93 Running outside the development environment 94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 95 96 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: 97 98 .. code-block:: shell 99 100 ./mach package 101 102 Copy the resulting ``.dmg`` file from ``obj-*/dist/`` to the target system, 103 then double-click it as usual to find an ``.app`` bundle containing all 104 dependencies. 105 106 On Apple Silicon Macs, you will need to sign the build for this to work using 107 :ref:`Signing Local macOS Builds`. 108 109 Once the build has been copied to the target system, open it with 110 right-click->Open. The build will not launch by default because it is not 111 notarized. In addition to code signing, notarization is required on macOS 112 10.15+ for a downloaded app to be launchable by double clicking the app in 113 Finder. 114 115 Now the fun starts 116 ------------------ 117 118 Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_, 119 say hello in the `Introduction channel 120 <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to 121 start working on <https://codetribute.mozilla.org/>`_. 122 See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes, 123 send patches to Mozilla, update your source code locally, and more. 124 125 Troubleshooting 126 --------------- 127 128 Build errors 129 ~~~~~~~~~~~~ 130 131 If you encounter a build error when trying to setup your development environment, please follow these steps: 132 1. Copy the entire build error to your clipboard 133 2. Paste this error to `gist.github.com <https://gist.github.com/>`__ in the text area 134 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 gist.github.com snippet you created! 135 136 The CLOBBER file has been updated 137 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 138 139 This is a normal error to encounter and tends to appear when working on a bug for a long period of time. 140 If you encounter this error, you need to run ``./mach clobber`` before running ``./mach build``. 141 Running ``./mach clobber`` will remove previous build artifacts to restart a build from scratch. 142 If you are using an artifact build, this will mean that the next build will take slightly longer than usual. 143 However, if you are using a non-artifact/full build, the next build will take significantly longer to complete. 144 145 Python-related errors 146 ~~~~~~~~~~~~~~~~~~~~~ 147 148 Building, running, testing, etc. not always support the latest Python versions, therefore it is possible to encounter Python-related errors, 149 especially after updating your Python distribution to a new version. 150 151 The recommended way to work around this is to use a virtual environment with a compatible Python version. 152 Please consider `mach's <https://searchfox.org/mozilla-central/source/mach>`_ ``MIN_PYTHON_VERSION`` and ``MAX_PYTHON_VERSION_TO_CONSIDER`` 153 for the range of compatible versions. 154 155 Should you be using Python through Homebrew, you can install older releases like this: 156 157 .. code-block:: shell 158 159 brew install python@3.<your-desired-version> 160 161 You can set up the virtual environment manually or use a supporting tool such as `pyenv <https://github.com/pyenv/pyenv>`_ (recommended). 162 Below is an example for manual setup. 163 164 .. code-block:: shell 165 166 cd firefox 167 # Creates virtual environment for <your-desired-version> in folder .venv 168 python3.<your-desired-version> -m venv .venv 169 # Activates virtual environment 170 source .venv/bin/activate