settings.rst (3930B)
1 .. _mach_settings: 2 3 ======== 4 Settings 5 ======== 6 7 Mach can read settings in from a set of configuration files. These 8 configuration files are either named ``machrc`` or ``.machrc`` and 9 are specified by the bootstrap script. In mozilla-central, these files 10 can live in ``~/.mozbuild`` and/or ``topsrcdir``. 11 12 Settings can be specified anywhere, and used both by mach core or 13 individual commands. 14 15 16 Core Settings 17 ============= 18 19 These settings are implemented by mach core. 20 21 * alias - Create a command alias. This is useful if you want to alias a command to something else, optionally including some defaults. It can either be used to create an entire new command, or provide defaults for an existing one. For example: 22 23 .. parsed-literal:: 24 25 [alias] 26 mochitest = mochitest -f browser 27 browser-test = mochitest -f browser 28 29 30 Defining Settings 31 ================= 32 33 Settings need to be explicitly defined, along with their type, 34 otherwise mach will throw when trying to access them. 35 36 To define settings, use the :func:`~decorators.SettingsProvider` 37 decorator in an existing mach command module. E.g: 38 39 .. code-block:: python 40 41 from mach.decorators import SettingsProvider 42 from mozbuild.base import MachCommandBase 43 44 @SettingsProvider 45 class ArbitraryClassName(MachCommandBase): 46 config_settings = [ 47 ('foo.bar', 'string', "A helpful description"), 48 ('foo.baz', 'int', "Another description", 0, {'choices': set([0,1,2])}), 49 ] 50 51 ``@SettingsProvider``'s must specify a variable called ``config_settings`` 52 that returns a list of tuples. Alternatively, it can specify a function 53 called ``config_settings`` that returns a list of tuples. 54 55 Each tuple is of the form: 56 57 .. code-block:: python 58 59 ('<section>.<option>', '<type>', '<description>', default, extra) 60 61 ``type`` is a string and can be one of: 62 string, boolean, int, pos_int, path 63 64 ``description`` is a string explaining how to define the settings and 65 where they get used. Descriptions should ideally be multi-line paragraphs 66 where the first line acts as a short description. 67 68 ``default`` is optional, and provides a default value in case none was 69 specified by any of the configuration files. 70 71 ``extra`` is also optional and is a dict containing additional key/value 72 pairs to add to the setting's metadata. The following keys may be specified 73 in the ``extra`` dict: 74 75 * ``choices`` - A set of allowed values for the setting. 76 77 Wildcards 78 --------- 79 80 Sometimes a section should allow arbitrarily defined options from the user, such 81 as the ``alias`` section mentioned above. To define a section like this, use ``*`` 82 as the option name. For example: 83 84 .. parsed-literal:: 85 86 ('foo.*', 'string', 'desc') 87 88 This allows configuration files like this: 89 90 .. parsed-literal:: 91 92 [foo] 93 arbitrary1 = some string 94 arbitrary2 = some other string 95 96 97 Finding Settings 98 ================ 99 100 You can see which settings are available as well as their description and 101 expected values by running: 102 103 .. parsed-literal:: 104 105 ./mach settings # or 106 ./mach settings --list 107 108 109 Accessing Settings 110 ================== 111 112 Now that the settings are defined and documented, they're accessible from 113 individual mach commands from the mach command context. 114 For example: 115 116 .. code-block:: python 117 118 from mach.decorators import ( 119 Command, 120 SettingsProvider, 121 ) 122 from mozbuild.base import MachCommandBase 123 124 @SettingsProvider 125 class ExampleSettings(object): 126 config_settings = [ 127 ('a.b', 'string', 'desc', 'default'), 128 ('foo.bar', 'string', 'desc',), 129 ('foo.baz', 'int', 'desc', 0, {'choices': set([0,1,2])}), 130 ] 131 132 @Command('command', category='misc', 133 description='Prints a setting') 134 def command(command_context): 135 settings = command_context._mach_context.settings 136 print(settings.a.b) 137 for option in settings.foo: 138 print(settings.foo[option])