windows-usage-outside-mozillabuild.rst (5477B)
1 ========================================== 2 Using Mach on Windows Outside MozillaBuild 3 ========================================== 4 5 .. note:: 6 7 These docs still require that you've followed the :ref:`Building Firefox On Windows` guide. 8 9 `MozillaBuild <https://wiki.mozilla.org/MozillaBuild>`__ is required to build 10 Firefox on Windows, because it provides necessary unix-y tools such as ``sh`` and ``awk``. 11 12 Traditionally, to interact with Mach and the Firefox Build System, Windows 13 developers would have to do so from within the MozillaBuild shell. This could be 14 disadvantageous for two main reasons: 15 16 1. The MozillaBuild environment is unix-y and based on ``bash``, which may be unfamiliar 17 for developers used to the Windows Command Prompt or Powershell. 18 2. There have been long-standing stability issues with MozillaBuild - this is due to 19 the fragile interface point between the underlying "MSYS" tools and "native Windows" 20 binaries. 21 22 It is now (experimentally!) possible to invoke Mach directly from other command line 23 environments, such as Powershell, Command Prompt, or even a developer-managed MSYS2 24 environment. Windows Terminal should work as well, for those on the "cutting edge". 25 26 .. note:: 27 28 If you're using a Cygwin-based environment such as MSYS2, it'll probably be 29 best to use the Windows-native version of Python (as described below) instead of a Python 30 distribution provided by the environment's package manager. Otherwise you'll likely run into 31 compatibility issues: 32 33 * Cygwin/MSYS Python will run into compatibility issues with Mach due to its unexpected Unix-y 34 conventions despite Mach assuming it's on a "Windows" platform. Additionally, there may 35 be performance issues. 36 * MinGW Python will encounter issues building native packages because they'll expect the 37 MSVC toolchain. 38 39 .. warning:: 40 41 This is only recommended for more advanced Windows developers: this work is experimental 42 and may run into unexpected failures! 43 44 Following are steps for preparing Windows-native (Command Prompt/Powershell) usage of Mach: 45 46 1. Install Python 47 ~~~~~~~~~~~~~~~~~ 48 49 Download Python from the `the official website <https://www.python.org/downloads/windows/>`__. 50 51 .. note:: 52 53 To avoid Mach compatibility issues with recent Python releases, it's recommended to install 54 the 2nd-most recent "major version". For example, at time of writing, the current modern Python 55 version is 3.10.1, so a safe version to install would be the most recent 3.9 release. 56 57 You'll want to download the "Windows installer (64-bit)" associated with the release you've chosen. 58 During installation, ensure that you check the "Add Python 3.x to PATH" option, otherwise you might 59 `encounter issues running Mercurial <https://bz.mercurial-scm.org/show_bug.cgi?id=6635>`__. 60 61 .. note:: 62 63 Due to issues with Python DLL import failures with pip-installed binaries, it's not 64 recommended to use the Windows Store release of Python. 65 66 2. Modify your PATH 67 ~~~~~~~~~~~~~~~~~~~ 68 69 The Python "user site-packages directory" needs to be added to your ``PATH`` so that packages 70 installed via ``pip install --user`` (such as ``hg``) can be invoked from the command-line. 71 72 1. From the Start menu, go to the Control Panel entry for "Edit environment variables 73 for your account". 74 2. Double-click the ``Path`` row in the top list of variables. Click "New" to add a new item to 75 the list. 76 3. In a Command Prompt window, resolve the Python directory with the command 77 ``python -c "import site; import os; print(os.path.abspath(os.path.join(site.getusersitepackages(), '..', 'Scripts')))"``. 78 4. Paste the output into the new item entry in the "Edit environment variable" window. 79 5. Click "New" again, and add the ``bin`` folder of MozillaBuild: probably ``C:\mozilla-build\bin``. 80 6. Click "OK". 81 82 3. Install Version Control System 83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 84 85 If you're using Mercurial, you'll need to install it to your Windows-native Python: 86 87 .. code-block:: shell 88 89 pip3 install --user mercurial windows-curses 90 91 If you're using Git with Cinnabar, follow its `setup instructions <https://github.com/glandium/git-cinnabar#setup>`__. 92 93 4. Set Powershell Execution Policy 94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 95 96 If you're using Powershell, Windows will raise an error by default when you try to invoke 97 ``.\mach.ps1``: 98 99 .. code:: text 100 101 .\mach : File <topsrcdir>\mach.ps1 cannot be loaded because running scripts is disabled on this system. For 102 more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170. 103 At line:1 char:1 104 105 To work around this: 106 107 1. From the Start menu, type in "Powershell", then right-click on the best match and click 108 "Run as administrator" 109 2. Run the command ``Set-ExecutionPolicy RemoteSigned`` 110 3. Close the Administrator Powershell window, and open a regular Powershell window 111 4. Go to your Firefox checkout (likely ``C:\mozilla-source\mozilla-unified``) 112 5. Test the new execution policy by running ``.\mach bootstrap``. If it doesn't immediately fail 113 with the error about "Execution Policies", then the problem is resolved. 114 115 Success! 116 ~~~~~~~~ 117 118 At this point, you should be able to invoke Mach and manage your version control system outside 119 of MozillaBuild. 120 121 .. tip:: 122 123 `See here <https://crisal.io/words/2022/11/22/msys2-firefox-development.html>`__ for a detailed guide on 124 installing and customizing a development environment with MSYS2, zsh, and Windows Terminal.