forked from mirrors/gecko-dev
92a19e0eb9
Assuming that the `MOZILLABUILD` environment variable is set, allow invoking Mach from non-MozillaBuild terminals. Note that MozillaBuild still needs to be installed, and the `MOZILLABUILD` environment variable will have to be set. For future reference: when I tried setting this up with Windows Store's Python 3.9, I encountered issues when running binaries installed via `pip`: it would fail with `abort: failed to load Python DLL python3x.dll`. Differential Revision: https://phabricator.services.mozilla.com/D133936
89 lines
2.5 KiB
ReStructuredText
89 lines
2.5 KiB
ReStructuredText
====
|
|
Mach
|
|
====
|
|
|
|
Mach (German for *do*) is a generic command dispatcher for the command
|
|
line.
|
|
|
|
To use mach, you install the mach core (a Python package), create an
|
|
executable *driver* script (named whatever you want), and write mach
|
|
commands. When the *driver* is executed, mach dispatches to the
|
|
requested command handler automatically.
|
|
|
|
.. raw:: html
|
|
|
|
<h2>Features</h2>
|
|
|
|
----
|
|
|
|
On a high level, mach is similar to using argparse with subparsers (for
|
|
command handling). When you dig deeper, mach offers a number of
|
|
additional features:
|
|
|
|
Distributed command definitions
|
|
With optparse/argparse, you have to define your commands on a central
|
|
parser instance. With mach, you annotate your command methods with
|
|
decorators and mach finds and dispatches to them automatically.
|
|
|
|
Command categories
|
|
Mach commands can be grouped into categories when displayed in help.
|
|
This is currently not possible with argparse.
|
|
|
|
Logging management
|
|
Mach provides a facility for logging (both classical text and
|
|
structured) that is available to any command handler.
|
|
|
|
Settings files
|
|
Mach provides a facility for reading settings from an ini-like file
|
|
format.
|
|
|
|
.. raw:: html
|
|
|
|
<h2>Components</h2>
|
|
|
|
----
|
|
|
|
Mach is conceptually composed of the following components:
|
|
|
|
core
|
|
The mach core is the core code powering mach. This is a Python package
|
|
that contains all the business logic that makes mach work. The mach
|
|
core is common to all mach deployments.
|
|
|
|
commands
|
|
These are what mach dispatches to. Commands are simply Python methods
|
|
registered as command names. The set of commands is unique to the
|
|
environment mach is deployed in.
|
|
|
|
driver
|
|
The *driver* is the entry-point to mach. It is simply an executable
|
|
script that loads the mach core, tells it where commands can be found,
|
|
then asks the mach core to handle the current request. The driver is
|
|
unique to the deployed environment. But, it's usually based on an
|
|
example from this source tree.
|
|
|
|
.. raw:: html
|
|
|
|
<h2> Project State</h2>
|
|
|
|
----
|
|
|
|
mach was originally written as a command dispatching framework to aid
|
|
Firefox development. While the code is mostly generic, there are still
|
|
some pieces that closely tie it to Mozilla/Firefox. The goal is for
|
|
these to eventually be removed and replaced with generic features so
|
|
mach is suitable for anybody to use. Until then, mach may not be the
|
|
best fit for you.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:hidden:
|
|
|
|
usage
|
|
commands
|
|
driver
|
|
logging
|
|
settings
|
|
telemetry
|
|
windows-usage-outside-mozillabuild
|
|
faq
|