docs/setup/windows_build.rst

   1 Building Firefox On Windows
   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 If you'd prefer to build Firefox for Windows in a virtual machine,
  10 you may be interested in the `Windows images provided by Microsoft
  11 <https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/>`_.
  12
  13 Requirements
  14 ------------
  15
  16 -  **Memory:** 4GB RAM minimum, 8GB+ recommended.
  17 -  **Disk Space:** At least 40GB of free disk space.
  18 -  **Operating System:** Windows 10. It is advisable to have Windows Update be fully
  19    up-to-date. See :ref:`build_hosts` for more information.
  20
  21 Recommended (For Windows 11 Users)
  22 ----------------------------------
  23 Setup a `Dev Drive
  24 <https://learn.microsoft.com/en-us/windows/dev-drive/#how-to-set-up-a-dev-drive>`_.
  25
  26 .. note::
  27
  28     -  A Dev Drive has been shown to make Firefox builds and VCS operations 5-10% faster.
  29     -  This guide assumes no Dev Drive, so all instructions of ``C:\mozilla-source`` should be to your Dev Drive letter instead (eg: ``D:\mozilla-source``), as your ``C:\`` drive can never be a Dev Drive.
  30
  31 1. Install MozillaBuild
  32 -----------------------
  33
  34 Install `MozillaBuild
  35 <https://ftp.mozilla.org/pub/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`_.
  36
  37 Accept the default installation directory.
  38 Windows may prompt you to "reinstall with the correct settings", which you
  39 should click to accept.
  40
  41 When working with Firefox tooling, you'll need to do so from within the MozillaBuild
  42 shell. You can start it by running ``C:\mozilla-build\start-shell.bat`` (you may want
  43 to make a shortcut to this file so it's easier to start).
  44
  45 .. note::
  46
  47     The MozillaBuild shell is a lot more like a Linux shell than the Windows ``cmd``. You can
  48     learn more about it `here <https://wiki.mozilla.org/MozillaBuild>`_.
  49
  50 2. Bootstrap a copy of the Firefox source code
  51 ----------------------------------------------
  52
  53 Now that your system is ready, we can download the source code and have Firefox
  54 automatically download the other dependencies it needs. The below command
  55 will download a lot of data (years of Firefox history!) then guide you through
  56 the interactive setup process.
  57
  58 .. code-block:: shell
  59
  60     # Using the C:\mozilla-build\start-shell.bat shell from step 1:
  61     cd c:/
  62     mkdir mozilla-source
  63     cd mozilla-source
  64     wget https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py
  65     python3 bootstrap.py
  66 .. note::
  67
  68     When running ``bootstrap.py`` there will be a `UAC (User Account Control) prompt <https://docs.microsoft.com/en-us/windows/security/identity-protection/user-account-control/how-user-account-control-works>`_ for PowerShell after
  69     selecting the destination directory for the source code clone. This is
  70     necessary to add the Microsoft Defender Antivirus exclusions automatically. You
  71     should select ``Yes`` on the UAC prompt, otherwise you will need
  72     to :ref:`follow some manual steps below <Ensure antivirus exclusions>`.
  73
  74 .. note::
  75
  76     To use ``git``, you can grab the source code in "git" form by running the
  77     bootstrap script with the ``vcs`` parameter:
  78
  79     .. code-block:: shell
  80
  81         python3 bootstrap.py --vcs=git
  82
  83     This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood.
  84
  85 Choosing a build type
  86 ~~~~~~~~~~~~~~~~~~~~~
  87
  88 If you aren't modifying the Firefox backend, then select one of the
  89 :ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are
  90 building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide <geckoview-contributor-guide>`.
  91
  92 .. _Ensure antivirus exclusions:
  93
  94 Ensure antivirus exclusions
  95 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  96
  97 Microsoft Defender Antivirus and some third-party antivirus products
  98 are known to significantly degrade build times and sometimes even cause failed
  99 builds (due to a "missing file"). This is usually because we have tests for
 100 well-known security bugs that have code samples that antivirus software identifies
 101 as a threat, automatically quarantining/corrupting the files.
 102
 103 To avoid this, add the following folders to your third-party antivirus exclusion list:
 104
 105 -  The ``C:\mozilla-build`` folder.
 106 -  The directory where the Firefox code is (probably ``C:\mozilla-source``).
 107 -  The ``%USERPROFILE%/.mozbuild`` directory (probably ``C:\Users\<user>\.mozbuild``).
 108
 109 The ``bootstrap.py`` script attempts to add the above folders to the Microsoft
 110 Defender Antivirus exclusion list automatically. You should check that they were
 111 successfully added, but if they're missing you will need to `add the exclusions to
 112 Microsoft Defender Antivirus manually
 113 <https://support.microsoft.com/en-ca/help/4028485/windows-10-add-an-exclusion-to-windows-security>`_.
 114
 115 .. note::
 116
 117     If you are using Mercurial and you're already missing files (you'll see them listed in ``hg status``), you can have them
 118     brought back by reverting your source tree: ``hg update -C``.
 119
 120     If you are using Git and you're already missing files (you'll see them listed in ``git status``), you can have them brought back by discarding changes in your source tree: ``git restore .``.
 121
 122 1. Build
 123 --------
 124
 125 Now that your system is bootstrapped, you should be able to build!
 126
 127 .. code-block:: shell
 128
 129     cd c:/mozilla-source/mozilla-unified
 130     hg up -C central
 131     ./mach build
 132
 133 🎉 Congratulations! You've built your own home-grown Firefox!
 134 You should see the following message in your terminal after a successful build:
 135
 136 .. code-block:: console
 137
 138     Your build was successful!
 139     To take your build for a test drive, run: |mach run|
 140     For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
 141
 142 You can now use the ``./mach run`` command to run your locally built Firefox!
 143
 144 If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
 145
 146 Now the fun starts
 147 ------------------
 148
 149 Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_,
 150 say hello in the `Introduction channel
 151 <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to
 152 start working on <https://codetribute.mozilla.org/>`_.
 153 See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes,
 154 send patches to Mozilla, update your source code locally, and more.
 155
 156 .. note::
 157
 158     If you'd like to interact with Mach from a different command line environment
 159     than MozillaBuild, there's experimental support for it described
 160     :ref:`over here <Using Mach on Windows Outside MozillaBuild>`.
 161
 162 Troubleshooting
 163 ---------------
 164
 165 Build errors
 166 ~~~~~~~~~~~~
 167
 168 If you encounter a build error when trying to setup your development environment, please follow these steps:
 169    1. Copy the entire build error to your clipboard
 170    2. Paste this error on `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.
 171    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!
 172
 173 MozillaBuild out-of-date
 174 ~~~~~~~~~~~~~~~~~~~~~~~~
 175
 176 The build system expects that you're using the most-recent MozillaBuild release.
 177 However, MozillaBuild doesn't auto-update. If you're running into local issues,
 178 they may be resolved by `upgrading your MozillaBuild <https://wiki.mozilla.org/MozillaBuild>`_.
 179
 180 Spaces in folder names
 181 ~~~~~~~~~~~~~~~~~~~~~~
 182
 183 **Firefox will not build** if the path to MozillaBuild or the Firefox source
 184 contain **spaces** or other breaking characters such as pluses, quotation marks,
 185 or metacharacters.  The Visual Studio tools and SDKs are an exception - they may
 186 be installed in a directory which contains spaces. It is strongly recommended
 187 that you accept the default settings for all installation locations.
 188
 189 Quotation marks in ``PATH``
 190 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 191
 192 Quotation marks (") aren't translated properly when passed to MozillaBuild
 193 sub-shells. Since they're not usually necessary, you should ensure they're
 194 not in your ``PATH`` environment variable.
 195
 196 ``PYTHON`` environment variable
 197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 198
 199 If ``PYTHON`` is set, the build may fail with the error: "``The system
 200 cannot find the file specified``." Ensure that you aren't having
 201 a ``PYTHON`` environment variable set.
 202
 203 Cygwin interference
 204 ~~~~~~~~~~~~~~~~~~~
 205
 206 If you happen to have Cygwin installed, its tools may erroneously be
 207 used when building Firefox. Ensure that MozillaBuild directories (in
 208 ``C:\mozilla-build\``) are before Cygwin directories in the ``PATH``
 209 environment variable.