windows_build.rst (10222B)
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 .. note:: 14 15 Microsoft "temporarily" stopped providing these VM images in 2024. Although 16 more time-consuming initially, you can create a VM and install Windows with 17 an official Windows 11 ISO file from `Microsoft's Download Windows 11 page 18 <https://www.microsoft.com/en-us/software-download/windows11#SoftwareDownload_Edition>`_. 19 20 Unlike the evaluation versions in Microsoft's pre-built VM images, an 21 unactivated Windows VM does not shut down every hour. 22 23 System Requirements 24 ------------------- 25 26 - **Memory:** 4GB RAM minimum, 8GB+ recommended. 27 - **Disk Space:** At least 40GB of free disk space. 28 - **Operating System:** Windows 10 or later. It is advisable to have Windows Update be fully 29 up-to-date. See :ref:`build_hosts` for more information. 30 31 Recommended (For Windows 11 Users) 32 ---------------------------------- 33 Setup a `Dev Drive 34 <https://learn.microsoft.com/en-us/windows/dev-drive/#how-to-set-up-a-dev-drive>`_. 35 36 .. note:: 37 38 - A Dev Drive has been shown to make Firefox builds and VCS operations 5-10% faster. 39 - 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. 40 - If you are using a Virtual Machine, assign a second disk in the VM 41 hypervisor and use that disk as the disk partition for the Dev Drive. 42 43 1. Install MozillaBuild 44 ----------------------- 45 46 Install `MozillaBuild 47 <https://ftp.mozilla.org/pub/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`_. 48 49 Accept the default installation directory. 50 Windows may prompt you to "reinstall with the correct settings", which you 51 should click to accept. 52 53 When working with Firefox tooling, you'll need to do so from within the MozillaBuild 54 shell. You can start it by running ``C:\mozilla-build\start-shell.bat`` (you may want 55 to make a shortcut to this file so it's easier to start). 56 57 .. note:: 58 59 The MozillaBuild shell is a lot more like a Linux shell than the Windows ``cmd``. 60 The installer bundles required tools such as Git, Python, wget, etc. You can 61 learn more about it `here <https://wiki.mozilla.org/MozillaBuild>`_. 62 63 2. Bootstrap a copy of the Firefox source code 64 ---------------------------------------------- 65 66 Now that your system is ready, we can download the source code and have Firefox 67 automatically download the other dependencies it needs. The below command 68 will download a lot of data (years of Firefox history!) then guide you through 69 the interactive setup process. 70 71 .. code-block:: shell 72 73 # Using the C:\mozilla-build\start-shell.bat shell from step 1: 74 cd c:/ 75 mkdir mozilla-source 76 cd mozilla-source 77 wget https://raw.githubusercontent.com/mozilla-firefox/firefox/refs/heads/main/python/mozboot/bin/bootstrap.py 78 79 python3 bootstrap.py 80 .. note:: 81 82 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 83 selecting the destination directory for the source code clone. This is 84 necessary to add the Microsoft Defender Antivirus exclusions automatically. You 85 should select ``Yes`` on the UAC prompt, otherwise you will need 86 to :ref:`follow some manual steps below <Ensure antivirus exclusions>`. 87 88 Choosing a build type 89 ~~~~~~~~~~~~~~~~~~~~~ 90 91 If you aren't modifying the Firefox backend, then select one of the 92 :ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are 93 building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide <geckoview-contributor-guide>`. 94 95 Ensure antivirus exclusions 96 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 97 .. _ensure-antivirus-exclusions: 98 99 Microsoft Defender Antivirus and some third-party antivirus products 100 are known to significantly degrade build times and sometimes even cause failed 101 builds (due to a "missing file"). This is usually because we have tests for 102 well-known security bugs that have code samples that antivirus software identifies 103 as a threat, automatically quarantining/corrupting the files. 104 105 To avoid this, add the following folders to your third-party antivirus exclusion list: 106 107 - The ``C:\mozilla-build`` folder. 108 - The directory where the Firefox code is (probably ``C:\mozilla-source``). 109 - The ``%USERPROFILE%/.mozbuild`` directory (probably ``C:\Users\<user>\.mozbuild``). 110 111 The ``bootstrap.py`` script attempts to add the above folders to the Microsoft 112 Defender Antivirus exclusion list automatically. You should check that they were 113 successfully added, but if they're missing you will need to `add the exclusions to 114 Microsoft Defender Antivirus manually 115 <https://support.microsoft.com/en-ca/help/4028485/windows-10-add-an-exclusion-to-windows-security>`_. 116 117 .. note:: 118 119 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 .``. 120 121 1. Build 122 -------- 123 124 Now that your system is bootstrapped, you should be able to build! 125 126 .. code-block:: shell 127 128 cd c:/mozilla-source/firefox 129 git pull origin main 130 ./mach build 131 132 🎉 Congratulations! You've built your own home-grown Firefox! 133 You should see the following message in your terminal after a successful build: 134 135 .. code-block:: console 136 137 Your build was successful! 138 To take your build for a test drive, run: |mach run| 139 For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html 140 141 You can now use the ``./mach run`` command to run your locally built Firefox! 142 143 If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_. 144 145 Now the fun starts 146 ------------------ 147 148 Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_, 149 say hello in the `Introduction channel 150 <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to 151 start working on <https://codetribute.mozilla.org/>`_. 152 See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes, 153 send patches to Mozilla, update your source code locally, and more. 154 155 .. note:: 156 157 If you'd like to interact with Mach from a different command line environment 158 than MozillaBuild, there's experimental support for it described 159 :ref:`over here <Using Mach on Windows Outside MozillaBuild>`. 160 161 Troubleshooting 162 --------------- 163 164 Build errors 165 ~~~~~~~~~~~~ 166 167 If you encounter a build error when trying to setup your development environment, please follow these steps: 168 1. Copy the entire build error to your clipboard 169 2. Paste this error on `gist.github.com <https://gist.github.com/>`_ in the text area 170 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! 171 172 The CLOBBER file has been updated 173 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 174 175 This is a normal error to encounter and tends to appear when working on a bug for a long period of time. 176 If you encounter this error, you need to run ``./mach clobber`` before running ``./mach build``. 177 Running ``./mach clobber`` will remove previous build artifacts to restart a build from scratch. 178 If you are using an artifact build, this will mean that the next build will take slightly longer than usual. 179 However, if you are using a non-artifact/full build, the next build will take significantly longer to complete. 180 181 MozillaBuild out-of-date 182 ~~~~~~~~~~~~~~~~~~~~~~~~ 183 184 The build system expects that you're using the most-recent MozillaBuild release. 185 However, MozillaBuild doesn't auto-update. If you're running into local issues, 186 they may be resolved by `upgrading your MozillaBuild <https://wiki.mozilla.org/MozillaBuild>`_. 187 188 Spaces in folder names 189 ~~~~~~~~~~~~~~~~~~~~~~ 190 191 **Firefox will not build** if the path to MozillaBuild or the Firefox source 192 contain **spaces** or other breaking characters such as pluses, quotation marks, 193 or metacharacters. Windows usernames are a common cause for spaces in the path, 194 so please ensure that your Windows username does not contain spaces, or miniconda 195 will have errors during fenix builds. The Visual Studio tools and SDKs are an exception - they may 196 be installed in a directory which contains spaces. It is strongly recommended 197 that you accept the default settings for all installation locations. 198 199 Quotation marks in ``PATH`` 200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 201 202 Quotation marks (") aren't translated properly when passed to MozillaBuild 203 sub-shells. Since they're not usually necessary, you should ensure they're 204 not in your ``PATH`` environment variable. 205 206 Python failed to find files in directories 207 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 208 209 Python can sometimes fail to find files in directories when path length limits are reached, 210 even when the root directory is kept relatively short: ``C:\mozilla-source\firefox``. This can be resolved by 211 `turning Windows long paths on <https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry>`_. 212 213 ``PYTHON`` environment variable 214 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 215 216 If ``PYTHON`` is set, the build may fail with the error: "``The system 217 cannot find the file specified``." Ensure that you aren't having 218 a ``PYTHON`` environment variable set. 219 220 Cygwin interference 221 ~~~~~~~~~~~~~~~~~~~ 222 223 If you happen to have Cygwin installed, its tools may erroneously be 224 used when building Firefox. Ensure that MozillaBuild directories (in 225 ``C:\mozilla-build\``) are before Cygwin directories in the ``PATH`` 226 environment variable.