python/mach/docs/index.rst
author Mark Goodwin <mgoodwin@mozilla.com>
Mon, 01 Feb 2016 16:11:48 +0000
changeset 283075 75fe50edcf9aca16125fa9abf8011e6b36ba7634
parent 220317 d6a8be98af5c49c13cc291d9846f0ac4485d58b8
child 292818 84ba3a5bc33cc4af94f5a46465a6f921d794041b
permissions -rw-r--r--
Bug 1244776 - Update moz-kinto-client.js to include recent Kinto.js changes r=rnewman Please see the Kinto.js PR for the storage adapter changes: https://github.com/Kinto/kinto.js/pull/303 Additions and changes to the Firefox storage adapter tests have been made accordingly.

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