index.rst (2530B)
1 ==== 2 Mach 3 ==== 4 5 Mach (German for *do*) is a generic command dispatcher for the command 6 line. 7 8 To use mach, you install the mach core (a Python package), create an 9 executable *driver* script (named whatever you want), and write mach 10 commands. When the *driver* is executed, mach dispatches to the 11 requested command handler automatically. 12 13 .. raw:: html 14 15 <h2>Features</h2> 16 17 ---- 18 19 On a high level, mach is similar to using argparse with subparsers (for 20 command handling). When you dig deeper, mach offers a number of 21 additional features: 22 23 Distributed command definitions 24 With optparse/argparse, you have to define your commands on a central 25 parser instance. With mach, you annotate your command methods with 26 decorators and mach finds and dispatches to them automatically. 27 28 Command categories 29 Mach commands can be grouped into categories when displayed in help. 30 This is currently not possible with argparse. 31 32 Logging management 33 Mach provides a facility for logging (both classical text and 34 structured) that is available to any command handler. 35 36 Settings files 37 Mach provides a facility for reading settings from an ini-like file 38 format. 39 40 .. raw:: html 41 42 <h2>Components</h2> 43 44 ---- 45 46 Mach is conceptually composed of the following components: 47 48 core 49 The mach core is the core code powering mach. This is a Python package 50 that contains all the business logic that makes mach work. The mach 51 core is common to all mach deployments. 52 53 commands 54 These are what mach dispatches to. Commands are simply Python methods 55 registered as command names. The set of commands is unique to the 56 environment mach is deployed in. 57 58 driver 59 The *driver* is the entry-point to mach. It is simply an executable 60 script that loads the mach core, tells it where commands can be found, 61 then asks the mach core to handle the current request. The driver is 62 unique to the deployed environment. But, it's usually based on an 63 example from this source tree. 64 65 .. raw:: html 66 67 <h2> Project State</h2> 68 69 ---- 70 71 mach was originally written as a command dispatching framework to aid 72 Firefox development. While the code is mostly generic, there are still 73 some pieces that closely tie it to Mozilla/Firefox. The goal is for 74 these to eventually be removed and replaced with generic features so 75 mach is suitable for anybody to use. Until then, mach may not be the 76 best fit for you. 77 78 .. toctree:: 79 :maxdepth: 1 80 :hidden: 81 82 usage 83 commands 84 driver 85 logging 86 settings 87 telemetry 88 windows-usage-outside-mozillabuild 89 faq