summaryrefslogtreecommitdiffstats
path: root/docs/setup/windows_build.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/setup/windows_build.rst')
-rw-r--r--docs/setup/windows_build.rst209
1 files changed, 209 insertions, 0 deletions
diff --git a/docs/setup/windows_build.rst b/docs/setup/windows_build.rst
new file mode 100644
index 0000000000..99f5fdf5d9
--- /dev/null
+++ b/docs/setup/windows_build.rst
@@ -0,0 +1,209 @@
+Building Firefox On Windows
+======================================
+
+This document will help you get set up to build Firefox on your own
+computer. Getting set up can take a while - we need to download a
+lot of bytes! Even on a fast connection, this can take ten to fifteen
+minutes of work, spread out over an hour or two.
+
+If you'd prefer to build Firefox for Windows in a virtual machine,
+you may be interested in the `Windows images provided by Microsoft
+<https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/>`_.
+
+Requirements
+------------
+
+- **Memory:** 4GB RAM minimum, 8GB+ recommended.
+- **Disk Space:** At least 40GB of free disk space.
+- **Operating System:** Windows 10. It is advisable to have Windows Update be fully
+ up-to-date. See :ref:`build_hosts` for more information.
+
+Recommended (For Windows 11 Users)
+----------------------------------
+Setup a `Dev Drive
+<https://learn.microsoft.com/en-us/windows/dev-drive/#how-to-set-up-a-dev-drive>`_.
+
+.. note::
+
+ - A Dev Drive has been shown to make Firefox builds and VCS operations 5-10% faster.
+ - 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.
+
+1. Install MozillaBuild
+-----------------------
+
+Install `MozillaBuild
+<https://ftp.mozilla.org/pub/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`_.
+
+Accept the default installation directory.
+Windows may prompt you to "reinstall with the correct settings", which you
+should click to accept.
+
+When working with Firefox tooling, you'll need to do so from within the MozillaBuild
+shell. You can start it by running ``C:\mozilla-build\start-shell.bat`` (you may want
+to make a shortcut to this file so it's easier to start).
+
+.. note::
+
+ The MozillaBuild shell is a lot more like a Linux shell than the Windows ``cmd``. You can
+ learn more about it `here <https://wiki.mozilla.org/MozillaBuild>`_.
+
+2. Bootstrap a copy of the Firefox source code
+----------------------------------------------
+
+Now that your system is ready, we can download the source code and have Firefox
+automatically download the other dependencies it needs. The below command
+will download a lot of data (years of Firefox history!) then guide you through
+the interactive setup process.
+
+.. code-block:: shell
+
+ # Using the C:\mozilla-build\start-shell.bat shell from step 1:
+ cd c:/
+ mkdir mozilla-source
+ cd mozilla-source
+ wget https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py
+ python3 bootstrap.py
+.. note::
+
+ 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
+ selecting the destination directory for the source code clone. This is
+ necessary to add the Microsoft Defender Antivirus exclusions automatically. You
+ should select ``Yes`` on the UAC prompt, otherwise you will need
+ to :ref:`follow some manual steps below <Ensure antivirus exclusions>`.
+
+.. note::
+
+ To use ``git``, you can grab the source code in "git" form by running the
+ bootstrap script with the ``vcs`` parameter:
+
+ .. code-block:: shell
+
+ python3 bootstrap.py --vcs=git
+
+ This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood.
+
+Choosing a build type
+~~~~~~~~~~~~~~~~~~~~~
+
+If you aren't modifying the Firefox backend, then select one of the
+:ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are
+building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide <geckoview-contributor-guide>`.
+
+.. _Ensure antivirus exclusions:
+
+Ensure antivirus exclusions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Microsoft Defender Antivirus and some third-party antivirus products
+are known to significantly degrade build times and sometimes even cause failed
+builds (due to a "missing file"). This is usually because we have tests for
+well-known security bugs that have code samples that antivirus software identifies
+as a threat, automatically quarantining/corrupting the files.
+
+To avoid this, add the following folders to your third-party antivirus exclusion list:
+
+- The ``C:\mozilla-build`` folder.
+- The directory where the Firefox code is (probably ``C:\mozilla-source``).
+- The ``%USERPROFILE%/.mozbuild`` directory (probably ``C:\Users\<user>\.mozbuild``).
+
+The ``bootstrap.py`` script attempts to add the above folders to the Microsoft
+Defender Antivirus exclusion list automatically. You should check that they were
+successfully added, but if they're missing you will need to `add the exclusions to
+Microsoft Defender Antivirus manually
+<https://support.microsoft.com/en-ca/help/4028485/windows-10-add-an-exclusion-to-windows-security>`_.
+
+.. note::
+
+ If you are using Mercurial and you're already missing files (you'll see them listed in ``hg status``), you can have them
+ brought back by reverting your source tree: ``hg update -C``.
+
+ 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 .``.
+
+1. Build
+--------
+
+Now that your system is bootstrapped, you should be able to build!
+
+.. code-block:: shell
+
+ cd c:/mozilla-source/mozilla-unified
+ hg up -C central
+ ./mach build
+
+🎉 Congratulations! You've built your own home-grown Firefox!
+You should see the following message in your terminal after a successful build:
+
+.. code-block:: console
+
+ Your build was successful!
+ To take your build for a test drive, run: |mach run|
+ For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
+
+You can now use the ``./mach run`` command to run your locally built Firefox!
+
+If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
+
+Now the fun starts
+------------------
+
+Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_,
+say hello in the `Introduction channel
+<https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to
+start working on <https://codetribute.mozilla.org/>`_.
+See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes,
+send patches to Mozilla, update your source code locally, and more.
+
+.. note::
+
+ If you'd like to interact with Mach from a different command line environment
+ than MozillaBuild, there's experimental support for it described
+ :ref:`over here <Using Mach on Windows Outside MozillaBuild>`.
+
+Troubleshooting
+---------------
+
+Build errors
+~~~~~~~~~~~~
+
+If you encounter a build error when trying to setup your development environment, please follow these steps:
+ 1. Copy the entire build error to your clipboard
+ 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.
+ 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!
+
+MozillaBuild out-of-date
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The build system expects that you're using the most-recent MozillaBuild release.
+However, MozillaBuild doesn't auto-update. If you're running into local issues,
+they may be resolved by `upgrading your MozillaBuild <https://wiki.mozilla.org/MozillaBuild>`_.
+
+Spaces in folder names
+~~~~~~~~~~~~~~~~~~~~~~
+
+**Firefox will not build** if the path to MozillaBuild or the Firefox source
+contain **spaces** or other breaking characters such as pluses, quotation marks,
+or metacharacters. The Visual Studio tools and SDKs are an exception - they may
+be installed in a directory which contains spaces. It is strongly recommended
+that you accept the default settings for all installation locations.
+
+Quotation marks in ``PATH``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Quotation marks (") aren't translated properly when passed to MozillaBuild
+sub-shells. Since they're not usually necessary, you should ensure they're
+not in your ``PATH`` environment variable.
+
+``PYTHON`` environment variable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If ``PYTHON`` is set, the build may fail with the error: "``The system
+cannot find the file specified``." Ensure that you aren't having
+a ``PYTHON`` environment variable set.
+
+Cygwin interference
+~~~~~~~~~~~~~~~~~~~
+
+If you happen to have Cygwin installed, its tools may erroneously be
+used when building Firefox. Ensure that MozillaBuild directories (in
+``C:\mozilla-build\``) are before Cygwin directories in the ``PATH``
+environment variable.