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:
[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 SettingsProvider()
decorator in an existing mach command module. E.g:
from mach.decorators import SettingsProvider
@SettingsProvider
class ArbitraryClassName(object):
config_settings = [
('foo.bar', 'string'),
('foo.baz', 'int', 0, 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:
('<section>.<option>', '<type>', default, extra)
type
is a string and can be one of:
string, boolean, int, pos_int, path
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:
('foo.*', 'string')
This allows configuration files like this:
[foo]
arbitrary1 = some string
arbitrary2 = some other string
Documenting Settings¶
All settings must at least be documented in the en_US locale. Otherwise,
running mach settings
will raise. Mach uses gettext to perform localization.
A handy command exists to generate the localization files:
mach settings locale-gen <section>
You’ll be prompted to add documentation for all options in section with the
en_US locale. To add documentation in another locale, pass in --locale
.
Accessing Settings¶
Now that the settings are defined and documented, they’re accessible from individual mach commands if the command receives a context in its constructor. For example:
from mach.decorators import (
Command,
CommandProvider,
SettingsProvider,
)
@SettingsProvider
class ExampleSettings(object):
config_settings = [
('a.b', 'string', 'default'),
('foo.bar', 'string'),
('foo.baz', 'int', 0, {'choices': set([0,1,2])}),
]
@CommandProvider
class Commands(object):
def __init__(self, context):
self.settings = context.settings
@Command('command', category='misc',
description='Prints a setting')
def command(self):
print(self.settings.a.b)
for option in self.settings.foo:
print(self.settings.foo[option])