← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/configuration.txt

  • Committer: Jelmer Vernooij
  • Date: 2011-11-30 20:02:16 UTC
  • mto: This revision was merged to the branch mainline in revision 6333.
  • Revision ID: jelmer@samba.org-20111130200216-aoju21pdl20d1gkd
Consistently pass tree path when exporting.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/configuration.txt
 
1
Configuring Bazaar
 
2
==================
 
3
 
 
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 or a list of unicode strings.
 
10
 
 
11
Option
 
12
------
 
13
 
 
14
The Option object is used to define its properties:
 
15
 
 
16
* name: a name: a valid python identifier (even if it's not used as an
 
17
  identifier in python itself). This is also used to register the option.
 
18
 
 
19
* default: the default value that Stack.get() should return if no
 
20
  value can be found for the option.
 
21
 
 
22
* default_from_env: a list of environment variables. The first variable set
 
23
  will provide a default value overriding 'default' which remains the
 
24
  default value if *no* environment variable is set.
 
25
 
 
26
* help: a doc string describing the option, the first line should be a
 
27
  summary and can be followed by a blank line and a more detailed
 
28
  explanation.
 
29
 
 
30
* from_unicode: a callable accepting a unicode string and returning a
 
31
  suitable value for the option. If the string cannot be coerced it should
 
32
  return None.
 
33
 
 
34
* invalid: the action to be taken when an invalid value is encountered in a
 
35
  store (during a Stack.get()).
 
36
 
 
37
Sections
 
38
--------
 
39
 
 
40
Options are grouped into sections which share some properties with the well
 
41
known dict objects:
 
42
 
 
43
* the key is the name,
 
44
* you can get, set and remove an option,
 
45
* the value is a unicode string.
 
46
 
 
47
MutableSection is needed to set or remove an option, ReadOnlySection should
 
48
be used otherwise.
 
49
 
 
50
 
 
51
Stores
 
52
------
 
53
 
 
54
Options can be persistent in which case they are saved into Stores.
 
55
 
 
56
``config.Store`` defines the abstract interface that all stores should
 
57
implement.
 
58
 
 
59
This object doesn't provide direct access to the options, it only provides
 
60
access to Sections. This is deliberate to ensure that sections can be
 
61
properly shared by reusing the same underlying objects. Accessing options
 
62
should be done via the ``Section`` objects.
 
63
 
 
64
A ``Store`` can contain one or more sections, each section is uniquely
 
65
identified by a unicode string.
 
66
 
 
67
``config.ConfigObjStore`` is an implementation that use ``ConfigObj``.
 
68
 
 
69
Depending on the object it is associated with (or not) a ``Store`` also needs
 
70
to implement a locking mechanism. ``LockableConfigObjStore`` implements such a
 
71
mechanism for ``ConfigObj`` based stores.
 
72
 
 
73
Classes are provided for the usual Bazaar configuration files and could be
 
74
used as examples to define new ones if needed. The associated tests provides a
 
75
basis for new classes which only need to register themselves in the right
 
76
places to inherit from the existing basic tests and add their own specific
 
77
ones.
 
78
 
 
79
Filtering sections
 
80
------------------
 
81
 
 
82
For some contexts, only some sections from a given store will apply. Defining
 
83
which is what the ``SectionMatcher`` objects are about.
 
84
 
 
85
The main constraint here is that a ``SectionMatcher`` should delay the loading
 
86
of the associated store as long as possible. The constructor should collect
 
87
all data needed for the selection and uses it while processing the sections in
 
88
``get_sections``.
 
89
 
 
90
Only ``ReadOnlySection`` objects are manipulated here but a
 
91
``SectionMatcher`` can return dedicated ``Section`` objects to provide
 
92
additional context (the ``LocationSection`` add an ``extra_path`` attribute
 
93
to implement the ``appendpath`` policy for example). If no sections match,
 
94
an empty list is returned.
 
95
 
 
96
Options local to a section can also be defined for special purposes and be
 
97
handled by ``Section.get()``. One such option is ``relpath`` which is
 
98
defined in ``LocationSection`` as an alternative to the ``appendpath``
 
99
policy.
 
100
 
 
101
For ``appendpath``, the ``LocationSection`` will carry ``extra_path`` as the
 
102
relative path between the section name and the location used. ``relpath``
 
103
will be available as a ``Section`` local option with the same
 
104
value. ``basename`` will carry the location base name and be available as a
 
105
local option with the same name. Note that such options can only be expanded
 
106
inside the section that defines them.
 
107
 
 
108
Specific section matchers can be implemented by overriding ``get_sections``
 
109
or just ``match``.
 
110
 
 
111
``bzrlib`` provides:
 
112
 
 
113
* ``LocationMatcher(store, location)``: To select all sections that match
 
114
  ``location``.
 
115
 
 
116
* ``NameMatcher(store, unique_id)``: To select a single section matching
 
117
  ``unique_id``.
 
118
 
 
119
Stacks
 
120
------
 
121
 
 
122
An option can take different values depending on the context it is used. Such
 
123
a context can involve configuration files, options from the command line,
 
124
default values in bzrlib and then some.
 
125
 
 
126
Such a context is implemented by creating a list of ``Section`` stacked upon
 
127
each other. A ``Stack`` can then be asked for an option value and returns the
 
128
first definition found.
 
129
 
 
130
This provides a great flexibility to decide priorities between sections when
 
131
the stack is defined without to worry about them in the code itself.
 
132
 
 
133
A stack also defines a mutable section (which can be None) to handle
 
134
modifications.
 
135
 
 
136
Many sections (or even stores) are aimed at providing default values for an
 
137
option but these sections shouldn't be modified lightly as modifying an option
 
138
used for different contexts will indeed be seen by all these contexts.
 
139
 
 
140
Default values in configuration files are defined by users. Developers
 
141
shouldn't have to modify them, as such, no mechanism nor heuristics are used
 
142
to find which section (or sections) should be modified.
 
143
 
 
144
A ``Stack`` defines a mutable section when there is no ambiguity.  If there
 
145
is one, then the *user* should be able to decide and in this case a new
 
146
``Stack`` can be created cheaply.
 
147
 
 
148
Different stacks can be created for different purposes, the existing
 
149
``GlobalStack``, ``LocationStack`` and ``BranchStack`` can be used as basis
 
150
or examples. These classes are the only ones that should be used in code,
 
151
``Stores`` can be used to build them but shouldn't be used otherwise, ditto
 
152
for sections. Again, the associated tests could and should be used against the
 
153
created stacks.