Using Mach on Windows Outside MozillaBuild¶
These docs still require that you’ve followed the Building Firefox On Windows guide.
MozillaBuild is required to build
Firefox on Windows, because it provides necessary unix-y tools such as
Traditionally, to interact with Mach and the Firefox Build System, Windows developers would have to do so from within the MozillaBuild shell. This could be disadvantageous for two main reasons:
The MozillaBuild environment is unix-y and based on
bash, which may be unfamiliar for developers used to the Windows Command Prompt or Powershell.
There have been long-standing stability issues with MozillaBuild - this is due to the fragile interface point between the underlying “MSYS” tools and “native Windows” binaries.
It is now (experimentally!) possible to invoke Mach directly from other command line environments, such as Powershell, Command Prompt, or even a developer-managed MSYS2 environment. Windows Terminal should work as well, for those on the “cutting edge”.
If you’re using a Cygwin-based environment such as MSYS2, it’ll probably be best to use the Windows-native version of Python (as described below) instead of a Python distribution provided by the environment’s package manager. Otherwise you’ll likely run into compatibility issues:
Cygwin/MSYS Python will run into compatibility issues with Mach due to its unexpected Unix-y conventions despite Mach assuming it’s on a “Windows” platform. Additionally, there may be performance issues.
MinGW Python will encounter issues building native packages because they’ll expect the MSVC toolchain.
This is only recommended for more advanced Windows developers: this work is experimental and may run into unexpected failures!
Following are steps for preparing Windows-native (Command Prompt/Powershell) usage of Mach:
1. Install Python¶
Download Python from the the official website.
To avoid Mach compatibility issues with recent Python releases, it’s recommended to install the 2nd-most recent “major version”. For example, at time of writing, the current modern Python version is 3.10.1, so a safe version to install would be the most recent 3.9 release.
You’ll want to download the “Windows installer (64-bit)” associated with the release you’ve chosen. During installation, ensure that you check the “Add Python 3.x to PATH” option, otherwise you might encounter issues running Mercurial.
Due to issues with Python DLL import failures with pip-installed binaries, it’s not recommended to use the Windows Store release of Python.
2. Modify your PATH¶
The Python “user site-packages directory” needs to be added to your
PATH so that packages
pip install --user (such as
hg) can be invoked from the command-line.
From the Start menu, go to the Control Panel entry for “Edit environment variables for your account”.
Pathrow in the top list of variables. Click “New” to add a new item to the list.
In a Command Prompt window, resolve the Python directory with the command
python -c "import site; import os; print(os.path.abspath(os.path.join(site.getusersitepackages(), '..', 'Scripts')))".
Paste the output into the new item entry in the “Edit environment variable” window.
Click “New” again, and add the
binfolder of MozillaBuild: probably
3. Install Version Control System¶
If you’re using Mercurial, you’ll need to install it to your Windows-native Python:
pip3 install --user mercurial windows-curses
If you’re using Git with Cinnabar, follow its setup instructions.
4. Set Powershell Execution Policy¶
If you’re using Powershell, Windows will raise an error by default when you try to invoke
.\mach : File <topsrcdir>\mach.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1
To work around this:
From the Start menu, type in “Powershell”, then right-click on the best match and click “Run as administrator”
Run the command
Close the Administrator Powershell window, and open a regular Powershell window
Go to your Firefox checkout (likely
Test the new execution policy by running
.\mach bootstrap. If it doesn’t immediately fail with the error about “Execution Policies”, then the problem is resolved.
At this point, you should be able to invoke Mach and manage your version control system outside of MozillaBuild.
See here for a detailed guide on installing and customizing a development environment with MSYS2, zsh, and Windows Terminal.