diff options
Diffstat (limited to 'python/mach/docs/windows-usage-outside-mozillabuild.rst')
| -rw-r--r-- | python/mach/docs/windows-usage-outside-mozillabuild.rst | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/python/mach/docs/windows-usage-outside-mozillabuild.rst b/python/mach/docs/windows-usage-outside-mozillabuild.rst new file mode 100644 index 0000000000..6a034fd384 --- /dev/null +++ b/python/mach/docs/windows-usage-outside-mozillabuild.rst @@ -0,0 +1,124 @@ +========================================== +Using Mach on Windows Outside MozillaBuild +========================================== + +.. note:: + + These docs still require that you've followed the :ref:`Building Firefox On Windows` guide. + +`MozillaBuild <https://wiki.mozilla.org/MozillaBuild>`__ is required to build +Firefox on Windows, because it provides necessary unix-y tools such as ``sh`` and ``awk``. + +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: + +1. The MozillaBuild environment is unix-y and based on ``bash``, which may be unfamiliar + for developers used to the Windows Command Prompt or Powershell. +2. 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". + +.. note:: + + 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. + +.. warning:: + + 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 <https://www.python.org/downloads/windows/>`__. + +.. note:: + + 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 <https://bz.mercurial-scm.org/show_bug.cgi?id=6635>`__. + +.. note:: + + 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 +installed via ``pip install --user`` (such as ``hg``) can be invoked from the command-line. + +1. From the Start menu, go to the Control Panel entry for "Edit environment variables + for your account". +2. Double-click the ``Path`` row in the top list of variables. Click "New" to add a new item to + the list. +3. 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')))"``. +4. Paste the output into the new item entry in the "Edit environment variable" window. +5. Click "New" again, and add the ``bin`` folder of MozillaBuild: probably ``C:\mozilla-build\bin``. +6. Click "OK". + +3. Install Version Control System +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you're using Mercurial, you'll need to install it to your Windows-native Python: + +.. code-block:: shell + + pip3 install --user mercurial windows-curses + +If you're using Git with Cinnabar, follow its `setup instructions <https://github.com/glandium/git-cinnabar#setup>`__. + +4. Set Powershell Execution Policy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you're using Powershell, Windows will raise an error by default when you try to invoke +``.\mach.ps1``: + +.. code:: + + .\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: + +1. From the Start menu, type in "Powershell", then right-click on the best match and click + "Run as administrator" +2. Run the command ``Set-ExecutionPolicy RemoteSigned`` +3. Close the Administrator Powershell window, and open a regular Powershell window +4. Go to your Firefox checkout (likely ``C:\mozilla-source\mozilla-unified``) +5. 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. + +Success! +~~~~~~~~ + +At this point, you should be able to invoke Mach and manage your version control system outside +of MozillaBuild. + +.. tip:: + + `See here <https://crisal.io/words/2022/11/22/msys2-firefox-development.html>`__ for a detailed guide on + installing and customizing a development environment with MSYS2, zsh, and Windows Terminal. |