10
bzrlib has a very flexible internal structure allowing plugins for many
11
operations. Plugins can add commands, new storage formats, diff and merge
12
features and more. This document provides an overview of the API and
13
conventions for plugin authors.
21
Plugins are Python modules under ``bzrlib.plugins``. They can be installed
22
either into the PYTHONPATH in that location, or in ~/.bazaar/plugins.
24
Plugins should have a setup.py.
26
As for other Python modules, the name of the directory must match the
27
expected name of the plugin.
30
Plugin metadata before installation
31
===================================
33
Plugins can export a summary of what they provide, and what versions of bzrlib
34
they are compatible with. This allows tools to be written to work with plugins,
35
such as to generate a directory of plugins, or install them via a
36
symlink/checkout to ~/.bazaar/plugins.
38
This interface allows bzr to interrogate a plugin without actually loading
39
it. This is useful because loading a plugin may have side effects such
40
as registering or overriding commands, or the plugin may raise an error,
41
if for example a prerequisite is not present.
47
A plugin that supports the bzr plugin metadata protocol will do two
48
things. Firstly, the ``setup.py`` for the plugin will guard the call to
51
if __name__ == 'main':
54
Secondly, the setup module will have one or more of the following variables
55
present at module scope. Any variables that are missing will be given the
56
defaults from the table. An example of every variable is provided after
59
+------------------------+---------+----------------------------------------+
60
| Variable | Default | Definition |
61
+========================+=========+========================================+
62
| bzr_plugin_name | None | The name the plugin package should be |
63
| | | given on disk. The plugin is then |
64
| | | available to python at |
65
| | | bzrlib.plugins.NAME |
66
+------------------------+---------+----------------------------------------+
67
| bzr_commands | [] | A list of the commands that the plugin |
68
| | | provides. Commands that already exist |
69
| | | in bzr and are decorated by the plugin |
70
| | | do not need to be listed (but it is not|
71
| | | harmful if you do list them). |
72
+------------------------+---------+----------------------------------------+
73
| bzr_plugin_version | None | A version_info 5-tuple with the plugins|
75
+------------------------+---------+----------------------------------------+
76
| bzr_minimum_version | None | A version_info 3-tuple for comparison |
77
| | | with the bzrlib minimum and current |
78
| | | version, for determining likely |
79
| | | compatibility. |
80
+------------------------+---------+----------------------------------------+
81
| bzr_maximum_version | None | A version_info 3-tuple like |
82
| | | bzr_minimum_version but checking the |
83
| | | upper limits supported. |
84
+------------------------+---------+----------------------------------------+
85
| bzr_control_formats | {} | A dictionary of descriptions of version|
86
| | | control directories. See |
87
| | | `Control Formats` below. |
88
+------------------------+---------+----------------------------------------+
89
| bzr_checkout_formats | {} | A dictionary of tree_format_string -> |
90
| | | human description strings, for tree |
91
| | | formats that drop into the |
92
| | | ``.bzr/checkout`` metadir system. |
93
+------------------------+---------+----------------------------------------+
94
| bzr_branch_formats | {} | As bzr_checkout_formats but for |
96
+------------------------+---------+----------------------------------------+
97
| bzr_repository_formats | {} | As bzr_checkout_formats but for |
99
+------------------------+---------+----------------------------------------+
104
Because disk format detection for formats that bzr does not understand at
105
all can be useful, we allow a declarative description of the shape of a
106
control directory. Each description has a name for showing to users, and a
107
dictonary of relative paths, and the content needed at each path. Paths
108
that end in '/' are required to be directories and the value for that key
109
is ignored. Other paths are required to be regular files, and the value
110
for that key is either None, in which case the file is statted but the
111
content is ignored, or a literal string which is compared against for
112
the content of the file. Thus::
114
# (look for a .hg directory)
115
bzr_control_formats = {"Mercurial":{'.hg/': None}}
117
# (look for a file called .svn/format with contents 4\n).
118
bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
124
An example setup.py follows::
126
#!/usr/bin/env python2.4
127
from distutils.core import setup
129
bzr_plugin_name = 'demo'
134
bzr_branch_formats = {
135
"Branch label on disk\n":"demo branch",
138
bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
140
bzr_plugin_version = (1, 3, 0, 'dev', 0)
141
bzr_minimum_version = (1, 0, 0)
143
if __name__ == 'main':
146
description="Demo plugin for plugin metadata.",
147
author="Canonical Ltd",
148
author_email="bazaar@lists.canonical.com",
149
license = "GNU GPL v2",
150
url="https://launchpad.net/bzr-demo",
151
packages=['bzrlib.plugins.demo',
152
'bzrlib.plugins.demo.tests',
154
package_dir={'bzrlib.plugins.demo': '.'})
157
Plugin metadata after installation
158
==================================
160
After a plugin has been installed, metadata can be more easily obtained by
161
looking inside the module object -- in other words, for variables defined
162
in the plugin's ``__init__.py``.
164
Help and documentation
165
----------------------
167
The module docstring is used as the plugin description shown by ``bzr
168
plugins``. As with all Python docstrings, the first line should be a
169
short complete sentence summarizing the plugin. The full docstring is
170
shown by ``bzr help PLUGIN_NAME``.
172
Remember that to be effective, the module docstring must be the first
173
statement in the file. It may come after comments but it must be before
174
any import statements.
179
Plugins can and should declare that they depend on a particular version of
182
from bzrlib.api import require_api
184
require_api(bzrlib, (1, 11, 0))
186
Please see `API versioning <api-versioning.html>`_ for more details on the API
187
metadata protocol used by bzrlib.
192
The plugin should expose a version tuple to describe its own version. We
193
recommend this stay approximately in sync with bzr, but you can use
196
__version__ == (1, 10, 0)
202
Plugins should avoid doing work or loading code from the plugin or
203
external libraries, if they're just installed but not actually active,
204
because this slows down every invocation of bzr. The bzrlib APIs
205
generally allow the plugin to 'lazily' register methods to invoke if a
206
particular disk format or seen or a particular command is run.
218
vim: ft=rst tw=74 ai shiftwidth=4
added
removed
doc/developers/plugin-api.txt
