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).
101
If you start migrating a given option to the config stacks, don't stop
102
mid-way, all its uses should be covered (tests included). There are some
103
edge cases where updates via one API will be not be seen by the other API
104
(see http://pad.lv/948339 and http://pad.lv/948344 for details). Roughly,
105
the old API always trigger an IO while the new one cache values to avoid
106
them. This works fine as long as a given option is handled via a single API.
111
Stacks capture the various places an option can be declared by the user with
112
associated levels of generality and query them in the appropriate order
113
returning the first definition found. For example, the
114
``append_revisions_only`` option may be declared for all branches of a user
115
in ``bazaar.conf``, or for a hierarchy of branches in ``locations.conf`` or
116
in a single branch in ``branch.conf``.
118
Defining a new stack means you need a new way to expose these levels to the
119
user that is not covered by the existing stacks.
121
This is achieved by declaring:
123
* which stores can provide a value for the option,
125
* which sections apply to the stack instance, some filtering for a given
126
context can be defined,
128
* which (store, section) should receive the modifications.
130
Mapping different sections to different stacks is a powerful way to organize
131
the options and provide various levels of configuration to the user. This is
132
achieved with ``Store`` and ``SectionMatcher`` objects.
138
The following stores are used by ``bzr`` in ways that illustrate various
144
``bzr`` itself defines two sections here:
146
* ``DEFAULT`` where global options are defined,
148
* ``ALIASES`` where command aliases are defined. This section is *not*
149
available via ``GlobalStack``, instead, the ``bzr alias`` command uses it
150
for its own purposes.
152
Plugins can define either additional options in the ``DEFAULT`` section or
153
new sections for their own needs (this is not especially encouraged
154
though). The ``bzr-bookmarks`` plugin defines a ``BOOKMARKS`` section there
160
The Ubuntu package importer defines a store and two stacks involving
161
``pkgimport.conf``. A no-name section contains the options common to all
162
packages and sections named after their corresponding package can also be
165
The ``ImporterStack`` uses ``locations.conf`` and the no-name section in
166
``pkgimport.conf`` for the importer options.
168
The ``PackageStack`` uses only ``pkgimport.conf`` and uses the section name
169
after the package followed by the no-name section.
174
``bzr`` defines sections corresponding to URLs there and includes the
175
relevant sections in ``LocationStack`` and ``BranchStack``. No no-name
176
section is recognized in this file.
181
This file defines the option for a given branch and uses only the no-name
187
The Option object is used to define its properties:
189
* name: a name: a valid python identifier (even if it's not used as an
190
identifier in python itself). This is also used to register the option.
192
* from_unicode: a callable accepting a unicode string and returning a
193
suitable value for the option. If the string cannot be coerced it should
196
* override_from_env: a list of environment variables. The first variable set
197
will be used as the option value overriding any other definition of the
200
* default: the default value that Stack.get() should return if no value can
201
be found for the option. This can also be a callable as long as it returns
204
* default_from_env: a list of environment variables. The first variable set
205
will provide a default value overriding 'default' which remains the
206
default value if *no* environment variable is set.
208
* help: a doc string describing the option, the first line should be a
209
summary and can be followed by a blank line and a more detailed
210
explanation. This will be displayed to the user with::
212
bzr help <option name>
214
* invalid: the action to be taken when an invalid value is encountered in a
215
store (during a Stack.get()).
217
The value of an option is a unicode string or ``None`` if it's not
218
defined. By using ``from_unicode`` you can turn this string into a more
219
appropriate representation.
221
If you need a list value, you should use ``ListOption`` instead.
223
For options that take their values from a ``Registry`` object,
224
``RegistryOption`` can be used. This will automatically take care of
225
looking up the specified values in the dictionary and documenting the
226
possible values in help.
231
Options are grouped into sections which share some properties with the well
234
* the key is the name,
235
* you can get, set and remove an option,
236
* the value is a unicode string.
238
MutableSection is needed to set or remove an option, ReadOnlySection should
245
Options can be persistent in which case they are saved into Stores.
247
``config.Store`` defines the abstract interface that all stores should
250
This object doesn't provide direct access to the options, it only provides
251
access to Sections. This is deliberate to ensure that sections can be
252
properly shared by reusing the same underlying objects. Accessing options
253
should be done via the ``Section`` objects.
255
A ``Store`` can contain one or more sections, each section is uniquely
256
identified by a unicode string.
258
``config.IniFileStore`` is an implementation that use ``ConfigObj``.
260
Depending on the object it is associated with (or not) a ``Store`` also needs
261
to implement a locking mechanism. ``LockableIniFileStore`` implements such a
262
mechanism for ``IniFileStore`` based stores.
264
Classes are provided for the usual Bazaar configuration files and could be
265
used as examples to define new ones if needed. The associated tests provides a
266
basis for new classes which only need to register themselves in the right
267
places to inherit from the existing basic tests and add their own specific
270
A ``Store`` defines how option values are stored, this includes:
272
* defining the sections where the options are grouped,
274
* defining how the values are quoted/unquoted for storage purposes. Stacks
275
use the unquoted values internally (default value handling and option
276
expansion are simpler this way) and ``bzr config`` quote them when they
277
need to be displayed.
283
For some contexts, only some sections from a given store will apply. The
284
``SectionMatcher`` objects are used to define which sections in a store
285
apply to a given context.
287
The main constraint here is that a ``SectionMatcher`` should delay the loading
288
of the associated store as long as possible. The constructor should collect
289
all data needed for the selection and uses it while processing the sections in
292
Only ``ReadOnlySection`` objects are manipulated here but a
293
``SectionMatcher`` can return dedicated ``Section`` objects to provide
294
additional context (the ``LocationSection`` add an ``extra_path`` attribute
295
to implement the section local options for example). If no sections match,
296
an empty list is returned.
298
Options local to a section can be defined for special purposes and be
299
handled by ``Section.get()``. One such option is ``relpath`` which is
300
defined in ``LocationSection`` as an alternative to the ``appendpath``
303
For ``appendpath``, the ``LocationSection`` will carry ``extra_path`` as the
304
relative path between the section name and the location used. ``relpath``
305
will be available as a ``Section`` local option with the same
306
value. ``basename`` will carry the location base name and be available as a
307
local option with the same name. Note that such options can only be expanded
308
inside the section that defines them.
310
Specific section matchers can be implemented by overriding ``get_sections``
315
* ``NameMatcher(store, unique_id)``: To select a single section matching
318
* ``LocationMatcher(store, location)``: To select all sections that match
319
``location`` sorted by decreasing number of path components.
321
* ``StartingPathMatcher(store, location)``: To select all sections that
322
match ``location`` in the order they appear in the ``store``.
327
An option can take different values depending on the context it is
328
used. This can involve configuration files, options from the command line,
329
default values in bzrlib and then some.
331
Such a context is implemented by creating a list of ``Section`` stacked upon
332
each other. A ``Stack`` can then be asked for an option value and returns the
333
first definition found.
335
This provides a great flexibility to decide priorities between sections when
336
the stack is defined without to worry about them in the code itself.
338
A stack also defines a mutable section (which can be None) to handle
341
Many sections (or even stores) are aimed at providing default values for an
342
option but these sections shouldn't be modified lightly as modifying an option
343
used for different contexts will indeed be seen by all these contexts.
345
Default values in configuration files are defined by users. Developers
346
shouldn't have to modify them, as such, no mechanism nor heuristics are used
347
to find which section (or sections) should be modified.
349
A ``Stack`` defines a mutable section when there is no ambiguity. If there
350
is one, then the *user* should be able to decide and in this case a new
351
``Stack`` can be created cheaply.
353
Different stacks can be created for different purposes, the existing
354
``GlobalStack``, ``LocationStack`` and ``BranchStack`` can be used as basis
355
or examples. These classes are the only ones that should be used in code,
356
``Stores`` can be used to build them but shouldn't be used otherwise, ditto
357
for sections. Again, the associated tests could and should be used against the
360
Also note that ``MemoryStack`` can be used without any disk resources which
361
allows for simpler and faster tests. A common pattern is to accept a
362
``config`` parameter related to a given feature and test it with predefined
363
configurations without involving the whole
364
stack. ``bzrlib.tests.test_commit``, ``bzrlib.tests.test_gpg`` and
365
``bzrlib.tests.test_smtp_connection`` are good examples.
added
removed
doc/developers/configuration.txt
