mirror of
https://github.com/mozilla/gecko-dev.git
synced 2025-11-08 12:19:05 +02:00
1d78259cdb
I was looking for a good place to put documentation for enabling the bash completion script when I realized that the 'mach' documentation is targeted at tool developers rather than users. Seeing as this is the main 'mach' documentation and we want to make 'firefox-source-docs' the place to go for contribution information, we should endeavour to target end users with this documentation. This adds a very basic usage page which should be expanded upon, but is better than nothing. I changed the headers in 'index.rst' to use raw:: html so that they don't show up in the nav bar to the left (and subsequently block the *actually important* things from appearing). Differential Revision: https://phabricator.services.mozilla.com/D16254 --HG-- extra : moz-landing-system : lando
86 lines
2.4 KiB
ReStructuredText
86 lines
2.4 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
|