10
14
bzrlib has a very flexible internal structure allowing plugins for many
11
15
operations. Plugins can add commands, new storage formats, diff and merge
12
16
features and more. This document provides an overview of the API and
13
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
18
30
Structure of a plugin
157
169
Plugin metadata after installation
158
170
==================================
160
After a plugin has been installed, metadata can be more easily obtained.
161
Currently the only metadata used is for API versioning.
172
After a plugin has been installed, metadata can be more easily obtained by
173
looking inside the module object -- in other words, for variables defined
174
in the plugin's ``__init__.py``.
176
Help and documentation
177
----------------------
179
The module docstring is used as the plugin description shown by ``bzr
180
plugins``. As with all Python docstrings, the first line should be a
181
short complete sentence summarizing the plugin. The full docstring is
182
shown by ``bzr help PLUGIN_NAME``.
184
Remember that to be effective, the module docstring must be the first
185
statement in the file. It may come after comments but it must be before
186
any import statements.
166
Please see `API versioning <api-versioning.html>`_ for details on the API
191
Plugins can and should declare that they depend on a particular version of
194
from bzrlib.api import require_api
196
require_api(bzrlib, (1, 11, 0))
198
Please see `API versioning <api-versioning.html>`_ for more details on the API
167
199
metadata protocol used by bzrlib.
204
The plugin should expose a version tuple to describe its own version.
205
Some plugins use a version number that corresponds to the version of bzr
206
they're released against, but you can use whatever you want. For example::
208
version_info = (1, 10, 0)
211
Detecting whether code's being loaded as a plugin
212
-------------------------------------------------
214
You may have a Python module that can be used as a bzr plugin and also in
215
other places. To detect whether the module is being loaded by bzr, use
216
something like this::
218
if __name__ == 'bzrlib.plugins.loggerhead':
219
# register with bzrlib...
225
Plugins should avoid doing work or loading code from the plugin or
226
external libraries, if they're just installed but not actually active,
227
because this slows down every invocation of bzr. The bzrlib APIs
228
generally allow the plugin to 'lazily' register methods to invoke if a
229
particular disk format or seen or a particular command is run.
235
The plugin ``__init__.py`` runs when the plugin is loaded during bzr
236
startup. Generally the plugin won't want to actually do anything at this
237
time other than register or override functions to be called later.
239
The plugin can import bzrlib and call any function.
240
Some interesting APIs are described in <http://bazaar-vcs.org/WritingPlugins>
243
Publishing your plugin
244
======================
246
When your plugin is basically working you might like to share it with
247
other people. Here are some steps to consider:
249
* make a project on Launchpad.net like
250
<https://launchpad.net/bzr-fastimport>
251
and publish the branches or tarballs there
253
* include the plugin in <http://bazaar-vcs.org/BzrPlugins>
255
* post about it to the ``bazaar-announce`` list at ``lists.canonical.com``
258
vim: ft=rst tw=74 ai shiftwidth=4
added
removed
doc/developers/plugin-api.txt
