зеркало из https://github.com/mozilla/gecko-dev.git
141 строка
3.8 KiB
ReStructuredText
141 строка
3.8 KiB
ReStructuredText
.. _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
|
|
|
|
@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:
|
|
|
|
.. code-block:: python
|
|
|
|
('<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:
|
|
|
|
.. parsed-literal::
|
|
|
|
('foo.*', 'string')
|
|
|
|
This allows configuration files like this:
|
|
|
|
.. parsed-literal::
|
|
|
|
[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:
|
|
|
|
.. parsed-literal::
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
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])
|