==== 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

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. .. raw:: html

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. .. raw:: html

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 :hidden: usage commands driver logging settings telemetry windows-usage-outside-mozillabuild faq