forked from mirrors/gecko-dev
fbc37fe116
Runtime configs have been implemented for awhile, but disabled. This patch enables configuration. Config files will be loaded in the following order (later files override earlier ones): 1a. $MACHRC 1b. $MOZBUILD_STATE_PATH/machrc (if $MACHRC is unset) 2. topsrcdir/machrc 3. CLI via --settings Note: .machrc may be used instead of machrc if desired. MozReview-Commit-ID: IntONAZLGML --HG-- extra : rebase_source : ff79b129eaea7cca5064d30fa6ddc76fceb9669b
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
|
|
settings
|