/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/configuration.txt

  • Committer: Andrew Bennetts
  • Date: 2011-06-09 07:38:32 UTC
  • mto: This revision was merged to the branch mainline in revision 5964.
  • Revision ID: andrew.bennetts@canonical.com-20110609073832-dt6oww033iexli4l
Fix thinko in wording regarding stacking invariants and revisions with multiple parents.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/configuration.txt
1
 
Configuring Breezy
 
1
Configuring Bazaar
2
2
==================
3
3
 
4
 
.. contents::
5
 
   :depth: 2
6
 
 
7
 
As a Breezy developer there are a few things you need to know about
8
 
configuration:
9
 
 
10
 
* how to add a new option,
11
 
 
12
 
* how add a new stack,
13
 
 
14
 
* how add a new store.
15
 
 
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.
19
 
 
20
 
Get an option value
21
 
-------------------
22
 
 
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.
26
 
 
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.
29
 
 
30
 
Add a new option
31
 
----------------
32
 
 
33
 
You add a new ``Option`` to the ``option_registry``, either inside
34
 
``breezy/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::
37
 
 
38
 
  option_registry.register(
39
 
      Option('dirstate.fdatasync', default=True,
40
 
            from_unicode=bool_from_store,
41
 
            help="Flush dirstate changes onto physical disk? ...."))
42
 
 
43
 
You then need to decide which stack is appropriate to implement the Option
44
 
policy:
45
 
 
46
 
* which config files (aka ``Store``) needs to be queried, which sections are
47
 
  relevant and in what order,
48
 
 
49
 
* which section will receive the modifications (if relevant).
50
 
 
51
 
The docstrings for the existing stacks cover most of the known use cases.
52
 
 
53
 
Modify an option value or delete an option
54
 
------------------------------------------
55
 
 
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 ``brz config``).
59
 
 
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.
63
 
 
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 ``breezy.conf`` and for ``BranchStack``which uses the
67
 
no-name section in ``branch.conf``).
68
 
 
69
 
Old and new configuration code
70
 
------------------------------
71
 
 
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.
75
 
 
76
 
If you encounter an option using the old code you may want to migrate
77
 
it. This generally involves:
78
 
 
79
 
* registering the option,
80
 
 
81
 
* replace the old config by a stack:
82
 
 
83
 
  * ``GlobalConfig`` became ``GlobalStack``,
84
 
 
85
 
  * ``LocationConfig`` became ``LocationStack``,
86
 
 
87
 
  * ``BranchConfig`` became ``BranchStack`` (or in this case,
88
 
    ``get_config()`` became ``get_config_stack()``.
89
 
 
90
 
* replace the custom accessor calls with ``conf.get(option_name)``.
91
 
 
92
 
The new config code provides some help for commonly encountered use cases
93
 
that can allow further simplifications like:
94
 
 
95
 
* providing a default value when the option is not defined in any way by the
96
 
  user,
97
 
 
98
 
* convert the unicode string provided by the user into a suitable
99
 
  representation (integer, list, etc).
100
 
 
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.
107
 
 
108
 
Adding a new stack
109
 
------------------
110
 
 
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 ``breezy.conf``, or for a hierarchy of branches in ``locations.conf`` or
116
 
in a single branch in ``branch.conf``.
117
 
 
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.
120
 
 
121
 
This is achieved by declaring:
122
 
 
123
 
* which stores can provide a value for the option,
124
 
 
125
 
* which sections apply to the stack instance, some filtering for a given
126
 
  context can be defined,
127
 
 
128
 
* which (store, section) should receive the modifications.
129
 
 
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.
133
 
 
134
 
 
135
 
Adding a new store
136
 
------------------
137
 
 
138
 
The following stores are used by ``brz`` in ways that illustrate various
139
 
uses of sections.
140
 
 
141
 
breezy.conf
142
 
===========
143
 
 
144
 
``brz`` itself defines two sections here:
145
 
 
146
 
* ``DEFAULT`` where global options are defined,
147
 
 
148
 
* ``ALIASES`` where command aliases are defined. This section is *not*
149
 
  available via ``GlobalStack``, instead, the ``brz alias`` command uses it
150
 
  for its own purposes.
151
 
 
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
155
 
for example.
156
 
 
157
 
location.conf
158
 
=============
159
 
 
160
 
``brz`` defines sections corresponding to URLs there and includes the
161
 
relevant sections in ``LocationStack`` and ``BranchStack``. No no-name
162
 
section is recognized in this file.
163
 
 
164
 
branch.conf
165
 
===========
166
 
 
167
 
This file defines the option for a given branch and uses only the no-name
168
 
section.
 
4
A configuration option has:
 
5
 
 
6
* a name: a valid python identifier (even if it's not used as an
 
7
  identifier in python itself)
 
8
 
 
9
* a value: a unicode string
169
10
 
170
11
Option
171
12
------
175
16
* name: a name: a valid python identifier (even if it's not used as an
176
17
  identifier in python itself). This is also used to register the option.
177
18
 
178
 
* from_unicode: a callable accepting a unicode string and returning a
179
 
  suitable value for the option. If the string cannot be coerced it should
180
 
  return None.
181
 
 
182
 
* override_from_env: a list of environment variables. The first variable set
183
 
  will be used as the option value overriding any other definition of the
184
 
  option.
185
 
 
186
 
* default: the default value that Stack.get() should return if no value can
187
 
  be found for the option. This can also be a callable as long as it returns
188
 
  a unicode string.
189
 
 
190
 
* default_from_env: a list of environment variables. The first variable set
191
 
  will provide a default value overriding 'default' which remains the
192
 
  default value if *no* environment variable is set.
193
 
 
194
 
* help: a doc string describing the option, the first line should be a
195
 
  summary and can be followed by a blank line and a more detailed
196
 
  explanation. This will be displayed to the user with::
197
 
 
198
 
    brz help <option name>
199
 
 
200
 
* invalid: the action to be taken when an invalid value is encountered in a
201
 
  store (during a Stack.get()).
202
 
 
203
 
The value of an option is a unicode string or ``None`` if it's not
204
 
defined. By using ``from_unicode`` you can turn this string into a more
205
 
appropriate representation.
206
 
 
207
 
If you need a list value, you should use ``ListOption`` instead.
208
 
 
209
 
For options that take their values from a ``Registry`` object,
210
 
``RegistryOption`` can be used. This will automatically take care of
211
 
looking up the specified values in the dictionary and documenting the
212
 
possible values in help.
 
19
* default: the default value that Stack.get() should return if no
 
20
  value can be found for the option.
 
21
 
 
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.
213
24
 
214
25
Sections
215
26
--------
224
35
MutableSection is needed to set or remove an option, ReadOnlySection should
225
36
be used otherwise.
226
37
 
227
 
 
228
38
Stores
229
39
------
230
40
 
241
51
A ``Store`` can contain one or more sections, each section is uniquely
242
52
identified by a unicode string.
243
53
 
244
 
``config.IniFileStore`` is an implementation that use ``ConfigObj``.
 
54
``config.ConfigObjStore`` is an implementation that use ``ConfigObj``.
245
55
 
246
56
Depending on the object it is associated with (or not) a ``Store`` also needs
247
 
to implement a locking mechanism. ``LockableIniFileStore`` implements such a
248
 
mechanism for ``IniFileStore`` based stores.
 
57
to implement a locking mechanism. ``LockableConfigObjStore`` implements such a
 
58
mechanism for ``ConfigObj`` based stores.
249
59
 
250
 
Classes are provided for the usual Breezy configuration files and could be
 
60
Classes are provided for the usual Bazaar configuration files and could be
251
61
used as examples to define new ones if needed. The associated tests provides a
252
62
basis for new classes which only need to register themselves in the right
253
63
places to inherit from the existing basic tests and add their own specific
254
64
ones.
255
65
 
256
 
A ``Store`` defines how option values are stored, this includes:
257
 
 
258
 
* defining the sections where the options are grouped,
259
 
 
260
 
* defining how the values are quoted/unquoted for storage purposes. Stacks
261
 
  use the unquoted values internally (default value handling and option
262
 
  expansion are simpler this way) and ``brz config`` quote them when they
263
 
  need to be displayed.
264
 
 
265
 
 
266
66
Filtering sections
267
67
------------------
268
68
 
269
 
For some contexts, only some sections from a given store will apply. The
270
 
``SectionMatcher`` objects are used to define which sections in a store
271
 
apply to a given context.
 
69
For some contexts, only some sections from a given store will apply. Defining
 
70
which is what the ``SectionMatcher`` are about.
272
71
 
273
72
The main constraint here is that a ``SectionMatcher`` should delay the loading
274
73
of the associated store as long as possible. The constructor should collect
275
74
all data needed for the selection and uses it while processing the sections in
276
75
``get_sections``.
277
76
 
278
 
Only ``ReadOnlySection`` objects are manipulated here but a
279
 
``SectionMatcher`` can return dedicated ``Section`` objects to provide
280
 
additional context (the ``LocationSection`` add an ``extra_path`` attribute
281
 
to implement the section local options for example). If no sections match,
282
 
an empty list is returned.
283
 
 
284
 
Options local to a section can be defined for special purposes and be
285
 
handled by ``Section.get()``. One such option is ``relpath`` which is
286
 
defined in ``LocationSection`` as an alternative to the ``appendpath``
287
 
policy.
288
 
 
289
 
For ``appendpath``, the ``LocationSection`` will carry ``extra_path`` as the
290
 
relative path between the section name and the location used. ``relpath``
291
 
will be available as a ``Section`` local option with the same
292
 
value. ``basename`` will carry the location base name and be available as a
293
 
local option with the same name. Note that such options can only be expanded
294
 
inside the section that defines them.
295
 
 
296
 
Specific section matchers can be implemented by overriding ``get_sections``
297
 
or just ``match``.
298
 
 
299
 
``breezy`` provides:
300
 
 
301
 
* ``NameMatcher(store, unique_id)``: To select a single section matching
302
 
  ``unique_id``.
303
 
 
304
 
* ``LocationMatcher(store, location)``: To select all sections that match
305
 
  ``location`` sorted by decreasing number of path components.
306
 
 
307
 
* ``StartingPathMatcher(store, location)``: To select all sections that
308
 
  match ``location`` in the order they appear in the ``store``.
 
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).
 
81
 
 
82
.. FIXME: Replace the appendpath example if/when it's deprecated ;)
309
83
 
310
84
Stacks
311
85
------
312
86
 
313
 
An option can take different values depending on the context it is
314
 
used. This can involve configuration files, options from the command line,
315
 
default values in breezy and then some.
 
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,
 
89
default values in bzrlib and then some.
316
90
 
317
91
Such a context is implemented by creating a list of ``Section`` stacked upon
318
92
each other. A ``Stack`` can then be asked for an option value and returns the
342
116
``Stores`` can be used to build them but shouldn't be used otherwise, ditto
343
117
for sections. Again, the associated tests could and should be used against the
344
118
created stacks.
345
 
 
346
 
Also note that ``MemoryStack`` can be used without any disk resources which
347
 
allows for simpler and faster tests. A common pattern is to accept a
348
 
``config`` parameter related to a given feature and test it with predefined
349
 
configurations without involving the whole
350
 
stack. ``breezy.tests.test_commit``, ``breezy.tests.test_gpg`` and
351
 
``breezy.tests.test_smtp_connection`` are good examples.
352