14
bzrlib has a very flexible internal structure allowing plugins for many
15
operations. Plugins can add commands, new storage formats, diff and merge
16
features and more. This document provides an overview of the API and
17
conventions for plugin authors.
19
If you're writing a plugin and have questions not addressed by this
20
document, please ask us.
25
* `Bazaar Developer Documentation Catalog <index.html>`_.
26
* <http://bazaar-vcs.org/WritingPlugins> wiki page with many more
27
suggestions about particular APIs
33
Plugins are Python modules under ``bzrlib.plugins``. They can be installed
34
either into the PYTHONPATH in that location, or in ~/.bazaar/plugins.
36
Plugins should have a setup.py.
38
As for other Python modules, the name of the directory must match the
39
expected name of the plugin.
42
Plugin metadata before installation
43
===================================
45
Plugins can export a summary of what they provide, and what versions of bzrlib
46
they are compatible with. This allows tools to be written to work with plugins,
47
such as to generate a directory of plugins, or install them via a
48
symlink/checkout to ~/.bazaar/plugins.
50
This interface allows bzr to interrogate a plugin without actually loading
51
it. This is useful because loading a plugin may have side effects such
52
as registering or overriding commands, or the plugin may raise an error,
53
if for example a prerequisite is not present.
59
A plugin that supports the bzr plugin metadata protocol will do two
60
things. Firstly, the ``setup.py`` for the plugin will guard the call to
63
if __name__ == 'main':
66
Secondly, the setup module will have one or more of the following variables
67
present at module scope. Any variables that are missing will be given the
68
defaults from the table. An example of every variable is provided after
71
+------------------------+---------+----------------------------------------+
72
| Variable | Default | Definition |
73
+========================+=========+========================================+
74
| bzr_plugin_name | None | The name the plugin package should be |
75
| | | given on disk. The plugin is then |
76
| | | available to python at |
77
| | | bzrlib.plugins.NAME |
78
+------------------------+---------+----------------------------------------+
79
| bzr_commands | [] | A list of the commands that the plugin |
80
| | | provides. Commands that already exist |
81
| | | in bzr and are decorated by the plugin |
82
| | | do not need to be listed (but it is not|
83
| | | harmful if you do list them). |
84
+------------------------+---------+----------------------------------------+
85
| bzr_plugin_version | None | A version_info 5-tuple with the plugins|
87
+------------------------+---------+----------------------------------------+
88
| bzr_minimum_version | None | A version_info 3-tuple for comparison |
89
| | | with the bzrlib minimum and current |
90
| | | version, for determining likely |
91
| | | compatibility. |
92
+------------------------+---------+----------------------------------------+
93
| bzr_maximum_version | None | A version_info 3-tuple like |
94
| | | bzr_minimum_version but checking the |
95
| | | upper limits supported. |
96
+------------------------+---------+----------------------------------------+
97
| bzr_control_formats | {} | A dictionary of descriptions of version|
98
| | | control directories. See |
99
| | | `Control Formats` below. |
100
+------------------------+---------+----------------------------------------+
101
| bzr_checkout_formats | {} | A dictionary of tree_format_string -> |
102
| | | human description strings, for tree |
103
| | | formats that drop into the |
104
| | | ``.bzr/checkout`` metadir system. |
105
+------------------------+---------+----------------------------------------+
106
| bzr_branch_formats | {} | As bzr_checkout_formats but for |
108
+------------------------+---------+----------------------------------------+
109
| bzr_repository_formats | {} | As bzr_checkout_formats but for |
110
| | | repositories. |
111
+------------------------+---------+----------------------------------------+
112
| bzr_transports | [] | URL prefixes for which this plugin |
113
| | | will register transports. |
114
+------------------------+---------+----------------------------------------+
119
Because disk format detection for formats that bzr does not understand at
120
all can be useful, we allow a declarative description of the shape of a
121
control directory. Each description has a name for showing to users, and a
122
dictonary of relative paths, and the content needed at each path. Paths
123
that end in '/' are required to be directories and the value for that key
124
is ignored. Other paths are required to be regular files, and the value
125
for that key is either None, in which case the file is statted but the
126
content is ignored, or a literal string which is compared against for
127
the content of the file. Thus::
129
# (look for a .hg directory)
130
bzr_control_formats = {"Mercurial":{'.hg/': None}}
132
# (look for a file called .svn/format with contents 4\n).
133
bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
139
An example setup.py follows::
141
#!/usr/bin/env python2.4
142
from distutils.core import setup
144
bzr_plugin_name = 'demo'
149
bzr_branch_formats = {
150
"Branch label on disk\n":"demo branch",
153
bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
155
bzr_transports = ["hg+ssh://"]
157
bzr_plugin_version = (1, 3, 0, 'dev', 0)
158
bzr_minimum_version = (1, 0, 0)
160
if __name__ == 'main':
163
description="Demo plugin for plugin metadata.",
164
author="Canonical Ltd",
165
author_email="bazaar@lists.canonical.com",
166
license = "GNU GPL v2",
167
url="https://launchpad.net/bzr-demo",
168
packages=['bzrlib.plugins.demo',
169
'bzrlib.plugins.demo.tests',
171
package_dir={'bzrlib.plugins.demo': '.'})
174
Plugin metadata after installation
175
==================================
177
After a plugin has been installed, metadata can be more easily obtained by
178
looking inside the module object -- in other words, for variables defined
179
in the plugin's ``__init__.py``.
181
Help and documentation
182
----------------------
184
The module docstring is used as the plugin description shown by ``bzr
185
plugins``. As with all Python docstrings, the first line should be a
186
short complete sentence summarizing the plugin. The full docstring is
187
shown by ``bzr help PLUGIN_NAME``.
189
Remember that to be effective, the module docstring must be the first
190
statement in the file. It may come after comments but it must be before
191
any import statements.
196
Plugins can and should declare that they depend on a particular version of
199
from bzrlib.api import require_api
201
require_api(bzrlib, (1, 11, 0))
203
Please see `API versioning <api-versioning.html>`_ for more details on the API
204
metadata protocol used by bzrlib.
209
The plugin should expose a version tuple to describe its own version.
210
Some plugins use a version number that corresponds to the version of bzr
211
they're released against, but you can use whatever you want. For example::
213
version_info = (1, 10, 0)
216
Detecting whether code's being loaded as a plugin
217
-------------------------------------------------
219
You may have a Python module that can be used as a bzr plugin and also in
220
other places. To detect whether the module is being loaded by bzr, use
221
something like this::
223
if __name__ == 'bzrlib.plugins.loggerhead':
224
# register with bzrlib...
230
Plugins should avoid doing work or loading code from the plugin or
231
external libraries, if they're just installed but not actually active,
232
because this slows down every invocation of bzr. The bzrlib APIs
233
generally allow the plugin to 'lazily' register methods to invoke if a
234
particular disk format or seen or a particular command is run.
240
The plugin ``__init__.py`` runs when the plugin is loaded during bzr
241
startup. Generally the plugin won't want to actually do anything at this
242
time other than register or override functions to be called later.
244
The plugin can import bzrlib and call any function.
245
Some interesting APIs are described in <http://bazaar-vcs.org/WritingPlugins>
248
Publishing your plugin
249
======================
251
When your plugin is basically working you might like to share it with
252
other people. Here are some steps to consider:
254
* make a project on Launchpad.net like
255
<https://launchpad.net/bzr-fastimport>
256
and publish the branches or tarballs there
258
* include the plugin in <http://bazaar-vcs.org/BzrPlugins>
260
* post about it to the ``bazaar-announce`` list at ``lists.canonical.com``
263
vim: ft=rst tw=74 ai shiftwidth=4
added
removed
doc/developers/plugin-api.txt
