~bzr-pqm/bzr/bzr.dev

Configuring Bazaar

==================

.. contents::

   :depth: 2

As a Bazaar developer there are a few things you need to know about

configuration:

* how to add a new option,

* how add a new stack,

* how add a new store.

The first sections in this document summarize the steps needed when adding a

new configuration item, the rest of the document gives more internal details

on how this is implemented.

Get an option value

-------------------

Options values are obtained with ``stack.get(option_name)`` where ``stack``

is one of the daughter classes of ``config.Stack``, see their docstrings for

a description of which sections are used from which stores.

The value returned is of the type declared for that ``Option`` and if

nothing is specifically declared you will get the default for that option.

Add a new option

----------------

You add a new ``Option`` to the ``option_registry``, either inside

``bzrlib/config.py`` or during initialization of your plugin (use

``register_lazy`` in this case). New plugins should have systematic

hierarchical names so that related values are grouped together::

  option_registry.register(

      Option('dirstate.fdatasync', default=True,

            from_unicode=bool_from_store,

            help="Flush dirstate changes onto physical disk? ...."))

You then need to decide which stack is appropriate to implement the Option

policy:

* which config files (aka ``Store``) needs to be queried, which sections are

  relevant and in what order,

* which section will receive the modifications (if relevant).

The docstrings for the existing stacks cover most of the known use cases.

Modify an option value or delete an option

------------------------------------------

Just reading an option is what is needed most of the time, modifying option

values or removing options is usually something that is not automated but

left to the user (with ``bzr config``).

Nevertheless, if you need to save a modified option value, use

``.set(option_name, value)`` and ``.remove(option_name)`` to delete the

option. Both methods are provided by the ``Stack`` object.

But before doing that, you must be sure that the stack you're using have a

writable section (this is true for ``GlobalStack`` which uses the

``DEFAULT`` section in ``bazaar.conf`` and for ``BranchStack``which uses the

no-name section in ``branch.conf``).

Old and new configuration code

------------------------------

There is (as of late 2011) some older and some newer configuration code. The

old code has specific methods for various checks or uses classes like

``GlobalConfig``.  Don't add to to it; try to remove it.

If you encounter an option using the old code you may want to migrate

it. This generally involves:

* registering the option,

* replace the old config by a stack:

  * ``GlobalConfig`` became ``GlobalStack``,

  * ``LocationConfig`` became ``LocationStack``,

  * ``BranchConfig`` became ``BranchStack`` (or in this case,

    ``get_config()`` became ``get_config_stack()``.

* replace the custom accessor calls with ``conf.get(option_name)``.

The new config code provides some help for commonly encountered use cases

that can allow further simplifications like:

* providing a default value when the option is not defined in any way by the

  user,

* convert the unicode string provided by the user into a suitable

  representation (integer, list, etc).

If you start migrating a given option to the config stacks, don't stop

mid-way, all its uses should be covered (tests included). There are some

edge cases where updates via one API will be not be seen by the other API

(see http://pad.lv/948339 and http://pad.lv/948344 for details). Roughly,

the old API always trigger an IO while the new one cache values to avoid

them. This works fine as long as a given option is handled via a single API.

Adding a new stack

------------------

Stacks capture the various places an option can be declared by the user with

associated levels of generality and query them in the appropriate order

returning the first definition found. For example, the

``append_revisions_only`` option may be declared for all branches of a user

in ``bazaar.conf``, or for a hierarchy of branches in ``locations.conf`` or

in a single branch in ``branch.conf``.

Defining a new stack means you need a new way to expose these levels to the

user that is not covered by the existing stacks.

This is achieved by declaring:

* which stores can provide a value for the option,

* which sections apply to the stack instance, some filtering for a given

  context can be defined,

* which (store, section) should receive the modifications.

Mapping different sections to different stacks is a powerful way to organize

the options and provide various levels of configuration to the user. This is

achieved with ``Store`` and ``SectionMatcher`` objects.

Adding a new store

------------------

The following stores are used by ``bzr`` in ways that illustrate various

uses of sections.

bazaar.conf

===========

``bzr`` itself defines two sections here:

* ``DEFAULT`` where global options are defined,

* ``ALIASES`` where command aliases are defined. This section is *not*

  available via ``GlobalStack``, instead, the ``bzr alias`` command uses it

  for its own purposes.

Plugins can define either additional options in the ``DEFAULT`` section or

new sections for their own needs (this is not especially encouraged

though). The ``bzr-bookmarks`` plugin defines a ``BOOKMARKS`` section there

for example.

pkgimport.conf

==============

The Ubuntu package importer defines a store and two stacks involving

``pkgimport.conf``. A no-name section contains the options common to all

packages and sections named after their corresponding package can also be

defined.

The ``ImporterStack`` uses ``locations.conf`` and the no-name section in

``pkgimport.conf`` for the importer options.

The ``PackageStack`` uses only ``pkgimport.conf`` and uses the section name

after the package followed by the no-name section.

location.conf

=============

``bzr`` defines sections corresponding to URLs there and includes the

relevant sections in ``LocationStack`` and ``BranchStack``. No no-name

section is recognized in this file.

branch.conf

===========

This file defines the option for a given branch and uses only the no-name

section.

Option

------

The Option object is used to define its properties:

* name: a name: a valid python identifier (even if it's not used as an

  identifier in python itself). This is also used to register the option.

* from_unicode: a callable accepting a unicode string and returning a

  suitable value for the option. If the string cannot be coerced it should

  return None.

* override_from_env: a list of environment variables. The first variable set

  will be used as the option value overriding any other definition of the

  option.

* default: the default value that Stack.get() should return if no value can

  be found for the option. This can also be a callable as long as it returns

  a unicode string.

* default_from_env: a list of environment variables. The first variable set

  will provide a default value overriding 'default' which remains the

  default value if *no* environment variable is set.

* help: a doc string describing the option, the first line should be a

  summary and can be followed by a blank line and a more detailed

  explanation. This will be displayed to the user with::

    bzr help <option name>

* invalid: the action to be taken when an invalid value is encountered in a

  store (during a Stack.get()).

The value of an option is a unicode string or ``None`` if it's not

defined. By using ``from_unicode`` you can turn this string into a more

appropriate representation.

If you need a list value, you should use ``ListOption`` instead.

For options that take their values from a ``Registry`` object,

``RegistryOption`` can be used. This will automatically take care of

looking up the specified values in the dictionary and documenting the

possible values in help.

Sections

--------

Options are grouped into sections which share some properties with the well

known dict objects:

* the key is the name,

* you can get, set and remove an option,

* the value is a unicode string.

MutableSection is needed to set or remove an option, ReadOnlySection should

be used otherwise.

Stores

------

Options can be persistent in which case they are saved into Stores.

``config.Store`` defines the abstract interface that all stores should

implement.

This object doesn't provide direct access to the options, it only provides

access to Sections. This is deliberate to ensure that sections can be

properly shared by reusing the same underlying objects. Accessing options

should be done via the ``Section`` objects.

A ``Store`` can contain one or more sections, each section is uniquely

identified by a unicode string.

``config.IniFileStore`` is an implementation that use ``ConfigObj``.

Depending on the object it is associated with (or not) a ``Store`` also needs

to implement a locking mechanism. ``LockableIniFileStore`` implements such a

mechanism for ``IniFileStore`` based stores.

Classes are provided for the usual Bazaar configuration files and could be

used as examples to define new ones if needed. The associated tests provides a

basis for new classes which only need to register themselves in the right

places to inherit from the existing basic tests and add their own specific

ones.

A ``Store`` defines how option values are stored, this includes:

* defining the sections where the options are grouped,

* defining how the values are quoted/unquoted for storage purposes. Stacks

  use the unquoted values internally (default value handling and option

  expansion are simpler this way) and ``bzr config`` quote them when they

  need to be displayed.

Filtering sections

------------------

For some contexts, only some sections from a given store will apply. The

``SectionMatcher`` objects are used to define which sections in a store

apply to a given context.

The main constraint here is that a ``SectionMatcher`` should delay the loading

of the associated store as long as possible. The constructor should collect

all data needed for the selection and uses it while processing the sections in

``get_sections``.

Only ``ReadOnlySection`` objects are manipulated here but a

``SectionMatcher`` can return dedicated ``Section`` objects to provide

additional context (the ``LocationSection`` add an ``extra_path`` attribute

to implement the section local options for example). If no sections match,

an empty list is returned.

Options local to a section can be defined for special purposes and be

handled by ``Section.get()``. One such option is ``relpath`` which is

defined in ``LocationSection`` as an alternative to the ``appendpath``

policy.

For ``appendpath``, the ``LocationSection`` will carry ``extra_path`` as the

relative path between the section name and the location used. ``relpath``

will be available as a ``Section`` local option with the same

value. ``basename`` will carry the location base name and be available as a

local option with the same name. Note that such options can only be expanded

inside the section that defines them.

Specific section matchers can be implemented by overriding ``get_sections``

or just ``match``.

``bzrlib`` provides:

* ``NameMatcher(store, unique_id)``: To select a single section matching

  ``unique_id``.

* ``LocationMatcher(store, location)``: To select all sections that match

  ``location`` sorted by decreasing number of path components.

* ``StartingPathMatcher(store, location)``: To select all sections that

  match ``location`` in the order they appear in the ``store``.

Stacks

------

An option can take different values depending on the context it is

used. This can involve configuration files, options from the command line,

default values in bzrlib and then some.

Such a context is implemented by creating a list of ``Section`` stacked upon

each other. A ``Stack`` can then be asked for an option value and returns the

first definition found.

This provides a great flexibility to decide priorities between sections when

the stack is defined without to worry about them in the code itself.

A stack also defines a mutable section (which can be None) to handle

modifications.

Many sections (or even stores) are aimed at providing default values for an

option but these sections shouldn't be modified lightly as modifying an option

used for different contexts will indeed be seen by all these contexts.

Default values in configuration files are defined by users. Developers

shouldn't have to modify them, as such, no mechanism nor heuristics are used

to find which section (or sections) should be modified.

A ``Stack`` defines a mutable section when there is no ambiguity.  If there

is one, then the *user* should be able to decide and in this case a new

``Stack`` can be created cheaply.

Different stacks can be created for different purposes, the existing

``GlobalStack``, ``LocationStack`` and ``BranchStack`` can be used as basis

or examples. These classes are the only ones that should be used in code,

``Stores`` can be used to build them but shouldn't be used otherwise, ditto

for sections. Again, the associated tests could and should be used against the

created stacks.

Also note that ``MemoryStack`` can be used without any disk resources which

allows for simpler and faster tests. A common pattern is to accept a

``config`` parameter related to a given feature and test it with predefined

configurations without involving the whole

stack. ``bzrlib.tests.test_commit``, ``bzrlib.tests.test_gpg`` and

``bzrlib.tests.test_smtp_connection`` are good examples.