docs/setup/linux_build.rst

   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 1.1 Install Python
  30 ~~~~~~~~~~~~~~~~~~
  31
  32 To build Firefox, it's necessary to have a Python of version 3.6 or later
  33 installed. Python 2 is no longer required to build Firefox, although it is still
  34 required for running some kinds of tests. Additionally, you will probably need
  35 Python development files as well to install some pip packages.
  36
  37 You should be able to install Python using your system package manager:
  38
  39 -  For Debian-based Linux (such as Ubuntu): ``sudo apt-get install curl python3 python3-pip``
  40 -  For Fedora Linux: ``sudo dnf install python3 python3-pip``
  41
  42 If you need a version of Python that your package manager doesn't have (e.g.:
  43 the provided Python 3 is too old, or you want Python 2 but it's not available),
  44 then you can use `pyenv <https://github.com/pyenv/pyenv>`_, assuming that your
  45 system is supported.
  46
  47 1.2 Install Mercurial
  48 ~~~~~~~~~~~~~~~~~~~~~
  49
  50 Mozilla's source code is hosted in Mercurial repositories. You will
  51 need Mercurial to download and update the code.
  52
  53 Note that if you'd prefer to use the version of Mercurial that is
  54 packaged by your distro, you can skip this section. However, keep in
  55 mind that distro-packaged Mercurial may be outdated, and therefore
  56 slower and less supported.
  57
  58 .. code-block:: shell
  59
  60     python3 -m pip install --user mercurial
  61
  62 You can test that Mercurial is installed by running:
  63
  64 .. code-block:: shell
  65
  66     hg version
  67
  68 .. note::
  69
  70     If your shell is showing ``command not found: hg``, then Python's packages aren't
  71     being found in the ``$PATH``. You can resolve this by doing the following and
  72     restarting your shell:
  73
  74     .. code-block:: shell
  75
  76         # If you're using zsh
  77         echo 'export PATH="'"$(python3 -m site --user-base)"'/bin:$PATH"' >> ~/.zshenv
  78
  79         # If you're using bash
  80         echo 'export PATH="'"$(python3 -m site --user-base)"'/bin:$PATH"' >> ~/.bashrc
  81
  82         # If you're using a different shell, follow its documentation to see
  83         # how to configure your PATH. Ensure that `$(python3 -m site --user-base)/bin`
  84         # is prepended.
  85
  86 2. Bootstrap a copy of the Firefox source code
  87 ----------------------------------------------
  88
  89 Now that your system is ready, we can download the source code and have Firefox
  90 automatically download the other dependencies it needs. The below command
  91 will download a lot of data (years of Firefox history!) then guide you through
  92 the interactive setup process.
  93
  94 .. code-block:: shell
  95
  96     curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -O
  97     python3 bootstrap.py
  98
  99 .. note::
 100
 101     To use ``git``, you can grab the source code in "git" form by running the
 102     bootstrap script with the ``vcs`` parameter:
 103
 104     .. code-block:: shell
 105
 106         python3 bootstrap.py --vcs=git
 107
 108     This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood.
 109
 110 Choosing a build type
 111 ~~~~~~~~~~~~~~~~~~~~~
 112
 113 If you aren't modifying the Firefox backend, then select one of the
 114 :ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are
 115 building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide <geckoview-contributor-guide>`.
 116
 117 3. Build
 118 --------
 119
 120 Now that your system is bootstrapped, you should be able to build!
 121
 122 .. code-block:: shell
 123
 124     cd mozilla-unified
 125     hg up -C central
 126     ./mach build
 127
 128 🎉 Congratulations! You've built your own home-grown Firefox!
 129 You should see the following message in your terminal after a successful build:
 130
 131 .. code-block:: console
 132
 133     Your build was successful!
 134     To take your build for a test drive, run: |mach run|
 135     For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
 136
 137 You can now use the ``./mach run`` command to run your locally built Firefox!
 138
 139 If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
 140
 141 Now the fun starts
 142 ------------------
 143
 144 Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_,
 145 say hello in the `Introduction channel
 146 <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to
 147 start working on <https://codetribute.mozilla.org/>`_.
 148 See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes,
 149 send patches to Mozilla, update your source code locally, and more.
 150
 151 Troubleshooting
 152 ---------------
 153
 154 Build errors
 155 ~~~~~~~~~~~~
 156
 157 If you encounter a build error when trying to setup your development environment, please follow these steps:
 158    1. Copy the entire build error to your clipboard
 159    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.
 160    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!
 161
 162 Using a non-native file system (NTFS, network drive, etc)
 163 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 164
 165 In our experience building Firefox in these hybrid or otherwise complex environments
 166 always ends in unexpected, often silent and always hard-to-diagnose failure.
 167 Building Firefox in that environment is far more likely to reveal the flaws and
 168 shortcomings of those systems than it is to produce a running web browser.