mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-05 00:25:27 +00:00
e6f5b57c9e
The main mach docs page is a bit long. Let's split it into multiple articles to increase readability going forward. --HG-- rename : python/mach/docs/index.rst => python/mach/docs/commands.rst rename : python/mach/docs/index.rst => python/mach/docs/driver.rst rename : python/mach/docs/index.rst => python/mach/docs/logging.rst extra : rebase_source : 484d60327568333fcb0069e1f3444dc6db4322c0 extra : histedit_source : 18d09ac2e2e93565661763b6567f7a46226735f5
75 lines
2.3 KiB
ReStructuredText
75 lines
2.3 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.
|
|
|
|
Features
|
|
========
|
|
|
|
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.
|
|
|
|
Components
|
|
==========
|
|
|
|
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.
|
|
|
|
Project State
|
|
=============
|
|
|
|
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
|
|
|
|
commands
|
|
driver
|
|
logging
|