4
A configuration option has:
6
* a name: a valid python identifier (even if it's not used as an
7
identifier in python itself)
9
* a value: a unicode string
7
As a Bazaar developer there are a few things you need to know about
10
* how to add a new option,
12
* how add a new stack,
14
* how add a new store.
16
The first sections in this document summarize the steps needed when adding a
17
new configuration item, the rest of the document gives more internal details
18
on how this is implemented.
23
Options values are obtained with ``stack.get(option_name)`` where ``stack``
24
is one of the daughter classes of ``config.Stack``, see their docstrings for
25
a description of which sections are used from which stores.
27
The value returned is of the type declared for that ``Option`` and if
28
nothing is specifically declared you will get the default for that option.
33
You add a new ``Option`` to the ``option_registry``, either inside
34
``bzrlib/config.py`` or during initialization of your plugin (use
35
``register_lazy`` in this case). New plugins should have systematic
36
hierarchical names so that related values are grouped together::
38
option_registry.register(
39
Option('dirstate.fdatasync', default=True,
40
from_unicode=bool_from_store,
41
help="Flush dirstate changes onto physical disk? ...."))
43
You then need to decide which stack is appropriate to implement the Option
46
* which config files (aka ``Store``) needs to be queried, which sections are
47
relevant and in what order,
49
* which section will receive the modifications (if relevant).
51
The docstrings for the existing stacks cover most of the known use cases.
53
Modify an option value or delete an option
54
------------------------------------------
56
Just reading an option is what is needed most of the time, modifying option
57
values or removing options is usually something that is not automated but
58
left to the user (with ``bzr config``).
60
Nevertheless, if you need to save a modified option value, use
61
``.set(option_name, value)`` and ``.remove(option_name)`` to delete the
62
option. Both methods are provided by the ``Stack`` object.
64
But before doing that, you must be sure that the stack you're using have a
65
writable section (this is true for ``GlobalStack`` which uses the
66
``DEFAULT`` section in ``bazaar.conf`` and for ``BranchStack``which uses the
67
no-name section in ``branch.conf``).
69
Old and new configuration code
70
------------------------------
72
There is (as of late 2011) some older and some newer configuration code. The
73
old code has specific methods for various checks or uses classes like
74
``GlobalConfig``. Don't add to to it; try to remove it.
76
If you encounter an option using the old code you may want to migrate
77
it. This generally involves:
79
* registering the option,
81
* replace the old config by a stack:
83
* ``GlobalConfig`` became ``GlobalStack``,
85
* ``LocationConfig`` became ``LocationStack``,
87
* ``BranchConfig`` became ``BranchStack`` (or in this case,
88
``get_config()`` became ``get_config_stack()``.
90
* replace the custom accessor calls with ``conf.get(option_name)``.
92
The new config code provides some help for commonly encountered use cases
93
that can allow further simplifications like:
95
* providing a default value when the option is not defined in any way by the
98
* convert the unicode string provided by the user into a suitable
99
representation (integer, list, etc).
104
Stacks capture the various places an option can be declared by the user with
105
associated levels of generality and query them in the appropriate order
106
returning the first definition found. For example, the
107
``append_revisions_only`` option may be declared for all branches of a user
108
in ``bazaar.conf``, or for a hierarchy of branches in ``locations.conf`` or
109
in a single branch in ``branch.conf``.
111
Defining a new stack means you need a new way to expose these levels to the
112
user that is not covered by the existing stacks.
114
This is achieved by declaring:
116
* which stores can provide a value for the option,
118
* which sections apply to the stack instance, some filtering for a given
119
context can be defined,
121
* which (store, section) should receive the modifications.
123
Mapping different sections to different stacks is a powerful way to organize
124
the options and provide various levels of configuration to the user. This is
125
achieved with ``Store`` and ``SectionMatcher`` objects.
133
The following stores are used by ``bzr`` in ways that illustrate various
139
``bzr`` itself defines two sections here:
141
* ``DEFAULT`` where global options are defined,
143
* ``ALIASES`` where command aliases are defined. This section is *not*
144
available via ``GlobalStack``, instead, the ``bzr alias`` command uses it
145
for its own purposes.
147
Plugins can define either additional options in the ``DEFAULT`` section or
148
new sections for their own needs (this is not especially encouraged
149
though). The ``bzr-bookmarks`` plugin defines a ``BOOKMARKS`` section there
155
The Ubuntu package importer defines a store and two stacks involving
156
``pkgimport.conf``. A no-name section contains the options common to all
157
packages and sections named after their corresponding package can also be
160
The ``ImporterStack`` uses ``locations.conf`` and the no-name section in
161
``pkgimport.conf`` for the importer options.
163
The ``PackageStack`` uses only ``pkgimport.conf`` and uses the section name
164
after the package followed by the no-name section.
169
``bzr`` defines sections corresponding to URLs there and includes the
170
relevant sections in ``LocationStack`` and ``BranchStack``. No no-name
171
section is recognized in this file.
176
This file defines the option for a given branch and uses only the no-name
16
184
* name: a name: a valid python identifier (even if it's not used as an
17
185
identifier in python itself). This is also used to register the option.
19
* default: the default value that Stack.get() should return if no
20
value can be found for the option.
22
Since plugins should be able to lazily register options, the associated help
23
is not part of the object but provided at registration time.
187
* from_unicode: a callable accepting a unicode string and returning a
188
suitable value for the option. If the string cannot be coerced it should
191
* default: the default value that Stack.get() should return if no value can
192
be found for the option. This can also be a callable as long as it returns
195
* default_from_env: a list of environment variables. The first variable set
196
will provide a default value overriding 'default' which remains the
197
default value if *no* environment variable is set.
199
* help: a doc string describing the option, the first line should be a
200
summary and can be followed by a blank line and a more detailed
201
explanation. This will be displayed to the user with::
203
bzr help <option name>
205
* invalid: the action to be taken when an invalid value is encountered in a
206
store (during a Stack.get()).
208
The value of an option is a unicode string or ``None`` if it's not
209
defined. By using ``from_unicode`` you can turn this string into a more
210
appropriate representation (a list of unicode strings for example).
66
254
Filtering sections
67
255
------------------
69
For some contexts, only some sections from a given store will apply. Defining
70
which is what the ``SectionMatcher`` are about.
257
For some contexts, only some sections from a given store will apply. The
258
``SectionMatcher`` objects are used to define which sections in a store
259
apply to a given context.
72
261
The main constraint here is that a ``SectionMatcher`` should delay the loading
73
262
of the associated store as long as possible. The constructor should collect
74
263
all data needed for the selection and uses it while processing the sections in
77
Only ``ReadOnlySection`` objects are manipulated here but a ``SectionMatcher``
78
can return dedicated ``Section`` to provide additional context (the
79
``LocationSection`` add an ``extra_path`` attribute to implement the
80
``appendpath`` policy for example).
82
.. FIXME: Replace the appendpath example if/when it's deprecated ;)
266
Only ``ReadOnlySection`` objects are manipulated here but a
267
``SectionMatcher`` can return dedicated ``Section`` objects to provide
268
additional context (the ``LocationSection`` add an ``extra_path`` attribute
269
to implement the section local options for example). If no sections match,
270
an empty list is returned.
272
Options local to a section can be defined for special purposes and be
273
handled by ``Section.get()``. One such option is ``relpath`` which is
274
defined in ``LocationSection`` as an alternative to the ``appendpath``
277
For ``appendpath``, the ``LocationSection`` will carry ``extra_path`` as the
278
relative path between the section name and the location used. ``relpath``
279
will be available as a ``Section`` local option with the same
280
value. ``basename`` will carry the location base name and be available as a
281
local option with the same name. Note that such options can only be expanded
282
inside the section that defines them.
284
Specific section matchers can be implemented by overriding ``get_sections``
289
* ``LocationMatcher(store, location)``: To select all sections that match
292
* ``NameMatcher(store, unique_id)``: To select a single section matching
87
An option can take different values depending on the context it is used. Such
88
a context can involve configuration files, options from the command line,
298
An option can take different values depending on the context it is
299
used. This can involve configuration files, options from the command line,
89
300
default values in bzrlib and then some.
91
302
Such a context is implemented by creating a list of ``Section`` stacked upon
added
removed
doc/developers/configuration.txt
