linux_build.rst (5412B)
1 Building Firefox On Linux 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:** A 64-bit installation of Linux. It is strongly advised 15 that you use a supported distribution; see :ref:`build_hosts`. We also 16 recommend that your system is fully up-to-date. 17 18 .. note:: 19 20 Some Linux distros are better-supported than others. Mozilla maintains 21 bootstrapping code for Ubuntu, but others are managed by the 22 community (thanks!). The more esoteric the distro you're using, 23 the more likely that you'll need to solve unexpected problems. 24 25 26 1. System preparation 27 --------------------- 28 29 To build Firefox, it's necessary to have a Python of version 3.9 or later 30 installed. Python 2 is no longer required to build Firefox, although it is still 31 required for running some kinds of tests. Additionally, you will probably need 32 Python development files as well to install some pip packages. 33 34 You should be able to install Python and git using your system package manager: 35 36 - For Debian-based Linux (such as Ubuntu): ``sudo apt update && sudo apt install curl python3 python3-pip git`` 37 - For Fedora Linux: ``sudo dnf install python3 python3-pip git`` 38 39 If you need a version of Python that your package manager doesn't have, 40 then you can use `pyenv <https://github.com/pyenv/pyenv>`_, assuming that your 41 system is supported. 42 43 2. Bootstrap a copy of the Firefox source code 44 ---------------------------------------------- 45 46 Now that your system is ready, we can download the source code and have Firefox 47 automatically download the other dependencies it needs. The below command 48 will download a lot of data (years of Firefox history!) then guide you through 49 the interactive setup process. 50 51 .. code-block:: shell 52 53 curl -LO https://raw.githubusercontent.com/mozilla-firefox/firefox/refs/heads/main/python/mozboot/bin/bootstrap.py 54 55 python3 bootstrap.py 56 57 Choosing a build type 58 ~~~~~~~~~~~~~~~~~~~~~ 59 60 If you aren't modifying the Firefox backend, then select one of the 61 :ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are 62 building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide <geckoview-contributor-guide>`. 63 64 3. Build 65 -------- 66 67 Now that your system is bootstrapped, you should be able to build! 68 69 .. code-block:: shell 70 71 cd firefox 72 git pull 73 ./mach build 74 75 🎉 Congratulations! You've built your own home-grown Firefox! 76 You should see the following message in your terminal after a successful build: 77 78 .. code-block:: console 79 80 Your build was successful! 81 To take your build for a test drive, run: |mach run| 82 For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html 83 84 You can now use the ``./mach run`` command to run your locally built Firefox! 85 86 If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_. 87 88 To customize your build with different options (like optimization levels, debug builds, or project selection), see :ref:`Configuring Build Options`. 89 90 Now the fun starts 91 ------------------ 92 93 Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_, 94 say hello in the `Introduction channel 95 <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to 96 start working on <https://codetribute.mozilla.org/>`_. 97 See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes, 98 send patches to Mozilla, update your source code locally, and more. 99 100 Troubleshooting 101 --------------- 102 103 Build errors 104 ~~~~~~~~~~~~ 105 106 If you encounter a build error when trying to setup your development environment, please follow these steps: 107 1. Copy the entire build error to your clipboard 108 2. Paste this error to `gist.github.com <https://gist.github.com/>`_ in the text area 109 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! 110 111 The CLOBBER file has been updated 112 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 113 114 This is a normal error to encounter and tends to appear when working on a bug for a long period of time. 115 If you encounter this error, you need to run ``./mach clobber`` before running ``./mach build``. 116 Running ``./mach clobber`` will remove previous build artifacts to restart a build from scratch. 117 If you are using an artifact build, this will mean that the next build will take slightly longer than usual. 118 However, if you are using a non-artifact/full build, the next build will take significantly longer to complete. 119 120 Using a non-native file system (NTFS, network drive, etc) 121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 122 123 In our experience building Firefox in these hybrid or otherwise complex environments 124 always ends in unexpected, often silent and always hard-to-diagnose failure. 125 Building Firefox in that environment is far more likely to reveal the flaws and 126 shortcomings of those systems than it is to produce a running web browser.