diff options
Diffstat (limited to 'docs/setup/windows_build.rst')
| -rw-r--r-- | docs/setup/windows_build.rst | 476 |
1 files changed, 476 insertions, 0 deletions
diff --git a/docs/setup/windows_build.rst b/docs/setup/windows_build.rst new file mode 100644 index 0000000000..945d38c349 --- /dev/null +++ b/docs/setup/windows_build.rst @@ -0,0 +1,476 @@ +Building Firefox On Windows +=========================== + +Thank you for helping us build the world's best browser on the world's +most popular OS. This document will help you get set up to build and +hack on your own version of Firefox on your local machine. + +Getting set up won't be difficult, but it 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. + +The details are further down this page, but this quick start guide +should get you up and running: + +Getting ready +------------- + +To build Firefox on Windows, you need a 64-bit version of Windows 7 or +later and about 40 GB of free space on your hard drive. You can make +sure your version of Windows is 64-bit on Windows 7 by right-clicking on +“Computer” in your “Start” menu, clicking “Properties” and then +“System”. On Windows 8.1 and Windows 10, right-clicking the “Windows” +menu button and choosing “System” will show you the same information. +You can alternatively press the “Windows” and “Pause Break” buttons +simultaneously on your keyboard on any version of Windows. + +Next, we want to start on a solid foundation: make sure you’re up to +date with Windows Update and then we’ll get moving. + +.. note:: + + Microsoft is providing some Windows images with Visual Studio and code + https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/ + + +Visual Studio 2019 +~~~~~~~~~~~~~~~~~~ + + +.. note:: + + As of `bug + 1483835 <https://bugzilla.mozilla.org/show_bug.cgi?id=1483835>`_, local + Windows builds `use clang-cl by + default <https://groups.google.com/d/topic/mozilla.dev.platform/MdbLAcvHC0Y/discussion>`_ + as compiler. Visual Studio is still necessary for build tools, headers, + and SDK. + +.. note:: + + Automation builds still use Visual Studio 2017, so there may be some + divergence until we upgrade. `Bug + 1581930 <https://bugzilla.mozilla.org/show_bug.cgi?id=1581930>`_ tracks + various issues building with 2019. Please file your issue there and + downgrade in the interim if you encounter build failures. + +`Download and install the Community +edition <https://visualstudio.microsoft.com/downloads/>`_ of Visual +Studio 2019. Professional and Enterprise are also supported if you have +either of those editions. + +.. note:: + + When installing, the following workloads must be checked: + + - "Desktop development with C++" (under the Windows group) + - "Game development with C++" (under the Mobile & Gaming group) + + In addition, go to the Individual Components tab and make sure the + following components are selected under the "SDKs, libraries, and + frameworks" group: + + - "Windows 10 SDK" (at least version **10.0.17134.0**) + - "C++ ATL for v142 build tools (x86 and x64)" (also select ARM64 + if you'll be building for ARM64) + +Make sure you run Visual Studio once after installing, so it finishes +any first-run tasks and associates the installation with your account. + +If you already have Visual Studio 2019 installed, you can get to the +installer via its menu "Tools" → "Get Tools and Features". + +Other Required Tools +~~~~~~~~~~~~~~~~~~~~ + +MozillaBuild +^^^^^^^^^^^^ + +Finally, download the `MozillaBuild +Package <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`__ +from Mozilla. Accept the default settings, in particular the default +installation directory: ``c:\mozilla-build\``. On some versions of +Windows an error dialog will give you the option to ‘reinstall with the +correct settings’ - you should agree and proceed. + +Once this is done, creating a shortcut to +``c:\mozilla-build\start-shell.bat`` on your desktop will make your life +easier. + +Getting the source +~~~~~~~~~~~~~~~~~~ + +This is the last big step. Double-clicking **start-shell.bat** in +``c:\mozilla-build`` (or the shortcut you’ve created above) will open a +terminal window. + +Start by creating a "mozilla-source" directory off of ``C:\`` and cd +into it like so + +.. code-block:: shell + + cd c:/ + + mkdir mozilla-source + + cd mozilla-source + +Next, you can get the Firefox source code with Mercurial. There is a +wiki page on how to :ref:`get the source using +Mercurial <Mercurial Overview>` +but, in summary, if your network connection is good enough to download +1+ GB without interuption and you want the main development repository, +then you can just use: + +.. code-block:: shell + + curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -o bootstrap.py + + python3 bootstrap.py + +... and follow the prompts. This will use mercurial to checkout the +source code. If you prefer to work with git, use this command instead (you'll +have to have `Git for Windows <https://git-scm.com/download/win>`_ installed): + +.. code-block:: shell + + python3 bootstrap.py --vcs=git + +While you’re waiting for that process to finish, take a look at `our +Mercurial +documentation <http://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/index.html>`_. +It explains how we use version control at Mozilla to manage our code and +land changes to our source tree. + +Build Firefox! +~~~~~~~~~~~~~~ + +Now we tie it all together. In your terminal window, ``cd`` to your +source directory as before and type + +.. code-block:: shell + + cd mozilla-unified # ... or the name of the repo you chose earlier + + ./mach bootstrap + + ./mach build + +The ``./mach bootstrap`` step is a catch-all for any dependencies not +covered in this documentation. Note that, bootstrap works **only with +the Mercurial repo of the source**, not with source tar balls, nor the +github mirror. If you are working on Firefox or Firefox for Android +frontends or building Firefox without any changes, select :ref:`Artifact Builds +<Understanding Artifact Builds>` in +the first question in ``./mach bootstrap``. Artifact builds will +complete more quickly! Artifact builds are unsuitable for those working +on C++ or Rust code. + +You’re on your way. Don’t be discouraged if this takes a while; it takes +some time even on the fastest modern machines and as much as two hours +or more on older hardware. Firefox is pretty big, because the Web is +big. + + +You're ready +~~~~~~~~~~~~ + +When mach build completes, you'll have your own version of Firefox built +from the source code on your hard drive, ready to run. You can run it +with + +.. code-block:: shell + + ./mach run + +Now you have your own home-built version of Firefox. + +If you saw an error here, look further down in this document for the +"Troubleshooting" section - some antivirus software quarantine some of +our tests, so you need to create exceptions for the "mozilla-source" and +"mozilla-build" directories. Don't turn your antivirus off! Just add the +exceptions. + + +Details and troubleshooting +--------------------------- + +Hardware and software requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Firefox build process is both I/O and CPU-intensive, and can take a +long time to build even on modern hardware. The minimum and recommended +hardware requirements for Mozilla development are: + +- At least 4 GB of RAM. 8 GB or more is recommended, and more is always + better. +- 35 GB free disk space. This amount of disk space accommodates Visual + Studio 2019 Community Edition, the required SDKs, the MozillaBuild + package, the Mercurial source repository and enough free disk space + to compile. A solid-state hard disk is recommended as the Firefox + build process is I/O-intensive. +- A 64-bit version of Windows 7 (Service Pack 1) or later. You can + still build 32-bit Firefox on a 64-bit Windows installation. + +Overview +~~~~~~~~ + +The Mozilla build process requires many tools that are not pre-installed +on most Windows systems. In addition to Visual Studio, install +MozillaBuild - a software bundle that includes the required versions of +bash, GNU make, Mercurial, and much more. + +Firefox 61+ require Visual Studio 2017 Update 6 or newer to build. + +Firefox 48 to 60 build with Visual Studio 2015. Visual Studio 2017 also +works for building Firefox 58 or newer. + +Firefox 37 through to 47 build with Visual Studio 2013 (VC12) and +possibly Visual Studio 2015 (although Visual Studio 2015 may not build +every revision). + +Earlier versions of Firefox build with older versions of Visual Studio. + +Installing the build prerequisites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Complete each of these steps otherwise, you may not be able to build +successfully. There are notes on these software requirements below. + +#. Make sure your system is up-to-date through Windows Update. +#. Install `Visual Studio Community + 2019 <https://www.visualstudio.com/downloads/>`_ (free). + Alternatively, you can also use a paid version of Visual Studio. Some + additional components may be required to build Firefox, as noted in + the "Visual Studio 2019" section above. Earlier versions of Visual + Studio are not supported; the Firefox codebase relies on C++ features + that are not supported in earlier releases. +#. Optionally, in addition to VS2019, you may want to install `Visual + C++ 2008 Express <http://go.microsoft.com/?linkid=7729279>`_ (free) + to compile some Python extensions used in the build system as Python + 2.7.x for Windows is built with that compiler by default. Note, if + you want to use "mach resource-usage", "mach doctor", "mach + android-emulator", or run talos tests locally, you should install it + for building psutil. +#. Download and install the + `MozillaBuild <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`__ + package, containing additional build tools. If you have Cygwin + installed, read the note in the tips section. If you see a Windows + error dialog giving you the option to re-install with the 'correct + settings', after the MozillaBuild's installer exits, choose the + option and after that all should be well. More information about + MozillaBuild and links to newer versions are available at + https://wiki.mozilla.org/MozillaBuild. + +Troubleshooting +~~~~~~~~~~~~~~~ + +In some circumstances, the following problems can arise: + +Antivirus performance +^^^^^^^^^^^^^^^^^^^^^ + +- Windows Defender and some scanning antivirus products are known to + have a major impact on build times. For example, if you have cloned + ``mozilla-unified`` successfully but ``./mach build`` fails, reporting + a missing file, you are likely experiencing this problem. Our + regression tests, for well-known security bugs, can include code + samples that some antivirus software will identify as a threat, and + will either quarantine or otherwise corrupt the files involved. To + resolve this you will need to add your source and object directories + (the ``mozilla-source`` and ``mozilla-build`` + directories) to the + `exclusion list in Windows Defender <https://support.microsoft.com/en-ca/help/4028485/windows-10-add-an-exclusion-to-windows-security>`_ + or your antivirus software. If you are missing files, revert your source + tree with the ``hg update -C`` command. Once this is done your next + ``./mach build`` should complete successfully. + +Installing Visual Studio in a different language than the system can cause issues +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- For example, having Visual Studio in French when the system is in + English causes the build to spew a lot of include errors and finishes + with a link error. + +.. note:: + + **Note:** **Mozilla will not build** if the path to the installation + tool folders contains **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. + +MozillaBuild package +~~~~~~~~~~~~~~~~~~~~ + +The MozillaBuild package contains other software prerequisites necessary +for building Mozilla, including the MSYS build environment, +`Mercurial <https://www.mercurial-scm.org/>`_, CVS, Python, YASM, NSIS, and UPX, +as well as optional but useful tools such as wget and emacs. + +`Download the current MozillaBuild +package. <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`_ + +By default, the package installs to ``c:\mozilla-build`` and it is +recommended to use the default path. Don't use a path that contains +spaces. The installer does not modify the Windows registry. Note that +some binaries may require `Visual C++ Redistributable +package <https://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2&displaylang=en>`_ to +run. + +.. note:: + + **MozillaBuild command prompt expectation setting:** Note that the + "UNIX-like" environment provided by MozillaBuild is only really useful + for building and committing to the Mozilla source. Most command line + tools you would expect in a modern Linux distribution are not present, + and those tools that are provided can be as much as a decade or so old + (especially those provided by MSYS). It's the old tools in particular + that can cause problems since they often don't behave as expected, are + buggy, or don't support command line arguments that have been taken for + granted for years. For example, copying a source tree using + ``cp -rf src1 src2`` does not work correctly because of an old version + of cp (it gives "cp: will not create hard link" errors for some files). + In short, MozillaBuild supports essential developer interactions with + the Mozilla code, but beyond that don't be surprised if it trips you up + in all sorts of exciting and unexpected ways. + +Opening a MozillaBuild command prompt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After the prerequisites are installed, launch +the ``start-shell.bat`` batch file using the Windows command +prompt in the directory to which you installed MozillaBuild +(``c:\mozilla-build`` by default). This will launch an MSYS/BASH command +prompt properly configured to build Firefox. All further commands should +be executed in this command prompt window. (Note that this is not the +same as what you get with the Windows CMD.EXE shell.) + +.. note:: + + Note: This is not the same as what you get with the Windows CMD.EXE + shell. + +Create a directory for the source +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Note:** You won't be able to build the Firefox source code if it's +under a directory with spaces in the path such as "Documents and +Settings". You can pick any other location, such as a new directory +c:/mozilla-source or c:/thunderbird-src. The build command prompt also +tolerates "c:\\" and "/c/", but the former gives confusion in the +Windows command prompt, and the latter is misinterpreted by some tools +(at least MOZ\_OBJDIR). The "C:/" syntax helps draw attention that the +**MozillaBuild** command prompt is assumed from here on out since it +provides configured environment and tools. + + +It's a sensible idea to create a new shallow directory, like +"c:/mozilla-source" dedicated solely to the +code: + +.. code-block:: shell + + cd c:/; mkdir mozilla-source; cd mozilla-source + +Keeping in mind the diagnostic hints below should you have issues. You +are now ready to get the Firefox source and build. + +Command prompt tips and caveats +------------------------------- + +- To paste into this window, you must right-click on the window's title + bar, move your cursor to the “Edit” menu, and click “Paste”. You can + also set “Quick Edit Mode” in the “Properties” menu and right-click + the window to paste your selection. +- If you have Cygwin installed, make sure that the MozillaBuild + directories come before any Cygwin directories in the search path + enhanced by ``start-shell-msvc2015.bat`` (use ``echo $PATH`` to see + your search path). +- In the MSYS / BASH shell started by ``start-shell-msvc2015.bat``, + UNIX-style forward slashes (/) are used as path separators instead of + the Windows-style backward slashes (\\). So if you want to change to + the directory ``c:\mydir``, in the MSYS shell to improve clarity, you + would use ``cd /c/mydir ``though both ``c:\mydir`` and ``c:/mydir`` + are supported. +- The MSYS root directory is located in ``/c/mozilla-build/msys`` if + you used the default installation directory. It's a good idea not to + build anything under this directory. Instead use something like + ``/c/mydir``. + +Common problems, hints, and restrictions +---------------------------------------- + +- :ref:`Debugging Firefox on Windows FAQ <Debugging On Windows>`: + Tips on how to debug Mozilla on Windows. +- Your installed MozillaBuild may be too old. The build system may + assume you have new features and bugfixes that are only present in + newer versions of MozillaBuild. Instructions for how to update + MozillaBuild `can be found + here <https://wiki.mozilla.org/MozillaBuild>`_. +- If the bootstrapping script ``bootstrap.py`` fails, you can also try running + ``hg clone https://hg.mozilla.org/mozilla-unified`` followed by + ``cd mozilla-unified; ./mach bootstrap`` yourself. +- The build may fail if your machine is configured with the wrong + architecture. If you want to build 64-bit Firefox, add the two lines + below to your mozconfig file: + +.. code-block:: shell + + ac_add_options --target=x86_64-pc-mingw32 + ac_add_options --host=x86_64-pc-mingw32 + +- The build may fail if your ``PATH`` environment variable contains + quotation marks("). Quotes are not properly translated when passed + down to MozillaBuild sub-shells and they are usually not needed so + they can be removed. +- The build may fail if you have a ``PYTHON`` environment variable set. + It displays an error almost immediately that says + "``The system cannot find the file specified``." Typing + "``unset PYTHON``" before running the Mozilla build tools in the same + command shell should fix this. Make sure that ``PYTHON`` is unset, + rather than set to an empty value. +- The build may fail if you have Cygwin installed. Make sure that the + MozillaBuild directories (``/c/mozilla-build`` and subdirectories) + come before any Cygwin directories in your PATH environment variable. + If this does not help, remove the Cygwin directories from PATH, or + try building on a clean PC with no Cygwin. +- Building with versions of NSIS other than the version that comes with + the latest supported version of MozillaBuild is not supported and + will likely fail. +- If you intend to distribute your build to others, set + ``WIN32_REDIST_DIR=$VCINSTALLDIR\redist\x86\Microsoft.VC141.CRT`` in + your mozconfig to get the Microsoft CRT DLLs packaged along with the + application. Note the exact .CRT file may depend on your Visual + Studio version. +- The Microsoft Antimalware service can interfere with compilation, + often manifesting as an error related to ``conftest.exe`` during + build. To remedy this, add at your object directory at least to the + exclusion settings. +- Errors like "second C linkage of overloaded function + '\_interlockedbittestandset' not allowed", are encountered when + intrin.h and windows.h are included together. Use a *#define* to + redefine one instance of the function's name. +- Parallel builds (``-jN``) do not work with GNU makes on Windows. You + should use the ``mozmake`` command included with current versions of + MozillaBuild. Building with the ``mach`` command will always use the + best available make command. +- If you encounter a build failure like "ERROR: Cannot find + makecab.exe", try applying the patch from `bug + 1383578 <https://bugzilla.mozilla.org/show_bug.cgi?id=1383578>`_, + i.e. change: ``SET PATH="%PATH%;!LLVMDIR!\bin"`` to + ``SET "PATH=%PATH%;!LLVMDIR!\bin"``. +- If you encounter a build failure with + ``LINK: fatal error LNK1181: cannot open input file ..\..\..\..\..\security\nss3.lib``, + it may be related to your clone of ``mozilla-unified`` being located + in the Users folder (possibly encrypted). Try moving it outside of + the Users folder. The docs recommend + ``C:\mozilla-source\mozilla-unified`` which should work. +- If you encounter a build failure with + ``ERROR: GetShortPathName returned a long path name.``.You need + create a 8dot3name short name for the path which has space.For + example : fsutil file setshortname "C:\\Program Files (x86)" + PROGRA~2. If you got "access denied", try to restart your computer + to safe mode and try again. + |