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