← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/plugin-api.txt

  • Committer: Jelmer Vernooij
  • Date: 2012-02-01 19:55:27 UTC
  • mto: This revision was merged to the branch mainline in revision 6460.
  • Revision ID: jelmer@samba.org-20120201195527-p11zolw13w81035y
Consider invalid mail clients an error rather than just a warning.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/plugin-api.txt
 
1
==========
 
2
Plugin API
 
3
==========
 
4
 
 
5
 
 
6
 
 
7
:Date: 2009-01-23
 
8
 
 
9
.. contents::
 
10
 
 
11
Introduction
 
12
============
 
13
 
 
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.
 
18
 
 
19
If you're writing a plugin and have questions not addressed by this
 
20
document, please ask us.
 
21
 
 
22
See also
 
23
--------
 
24
 
 
25
 * `Bazaar Developer Documentation Catalog <../index.html>`_.
 
26
 * `Bazaar Plugins Guide <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_ for
 
27
   more suggestions about particular APIs.
 
28
 
 
29
 
 
30
Structure of a plugin
 
31
=====================
 
32
 
 
33
Plugins are Python modules under ``bzrlib.plugins``. They can be installed
 
34
either into the PYTHONPATH in that location, or in ~/.bazaar/plugins.
 
35
 
 
36
Plugins should have a setup.py.
 
37
 
 
38
As for other Python modules, the name of the directory must match the
 
39
expected name of the plugin.
 
40
 
 
41
 
 
42
Plugin metadata before installation
 
43
===================================
 
44
 
 
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.
 
49
 
 
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.
 
54
 
 
55
 
 
56
Metadata protocol
 
57
-----------------
 
58
 
 
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
 
61
``setup()``::
 
62
 
 
63
  if __name__ == 'main':
 
64
      setup(...)
 
65
 
 
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
 
69
the full list.
 
70
 
 
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|
 
86
|                        |         | version.                               |
 
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        |
 
107
|                        |         | branches.                              |
 
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
+------------------------+---------+----------------------------------------+
 
115
 
 
116
Control Formats
 
117
---------------
 
118
 
 
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::
 
128
 
 
129
  # (look for a .hg directory)
 
130
  bzr_control_formats = {"Mercurial":{'.hg/': None}}
 
131
 
 
132
  # (look for a file called .svn/format with contents 4\n).
 
133
  bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
 
134
 
 
135
 
 
136
Example
 
137
-------
 
138
 
 
139
An example setup.py follows::
 
140
 
 
141
  #!/usr/bin/env python2.4
 
142
  from distutils.core import setup
 
143
 
 
144
  bzr_plugin_name = 'demo'
 
145
  bzr_commands = [
 
146
      'new-command',
 
147
      ]
 
148
 
 
149
  bzr_branch_formats = {
 
150
      "Branch label on disk\n":"demo branch",
 
151
      }
 
152
 
 
153
  bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
 
154
 
 
155
  bzr_transports = ["hg+ssh://"]
 
156
 
 
157
  bzr_plugin_version = (1, 3, 0, 'dev', 0)
 
158
  bzr_minimum_version = (1, 0, 0)
 
159
 
 
160
  if __name__ == 'main':
 
161
      setup(name="Demo",
 
162
            version="1.3.0dev0",
 
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',
 
170
                      ],
 
171
            package_dir={'bzrlib.plugins.demo': '.'})
 
172
 
 
173
 
 
174
Plugin metadata after installation
 
175
==================================
 
176
 
 
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``.
 
180
 
 
181
Help and documentation
 
182
----------------------
 
183
 
 
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``.
 
188
 
 
189
This is a user-visible docstring so should be prefixed with ``__doc__ =``
 
190
to ensure help works under ``python -OO`` with docstrings stripped.
 
191
 
 
192
API version
 
193
-----------
 
194
 
 
195
Plugins can and should declare that they depend on a particular version of
 
196
bzrlib like so::
 
197
 
 
198
    from bzrlib.api import require_api
 
199
 
 
200
    require_api(bzrlib, (1, 11, 0))
 
201
 
 
202
Please see `API versioning <api-versioning.html>`_ for more details on the API
 
203
metadata protocol used by bzrlib.
 
204
 
 
205
Plugin version
 
206
--------------
 
207
 
 
208
The plugin should expose a version tuple to describe its own version.
 
209
Some plugins use a version number that corresponds to the version of bzr
 
210
they're released against, but you can use whatever you want.  For example::
 
211
 
 
212
    version_info = (1, 10, 0)
 
213
 
 
214
 
 
215
Detecting whether code's being loaded as a plugin
 
216
-------------------------------------------------
 
217
 
 
218
You may have a Python module that can be used as a bzr plugin and also in
 
219
other places.  To detect whether the module is being loaded by bzr, use
 
220
something like this::
 
221
 
 
222
    if __name__ == 'bzrlib.plugins.loggerhead':
 
223
        # register with bzrlib...
 
224
 
 
225
 
 
226
Plugin performance
 
227
==================
 
228
 
 
229
Plugins should avoid doing work or loading code from the plugin or
 
230
external libraries, if they're just installed but not actually active,
 
231
because this slows down every invocation of bzr.  The bzrlib APIs
 
232
generally allow the plugin to 'lazily' register methods to invoke if a
 
233
particular disk format or seen or a particular command is run.
 
234
 
 
235
 
 
236
Plugin registrations
 
237
====================
 
238
 
 
239
The plugin ``__init__.py`` runs when the plugin is loaded during bzr
 
240
startup.  Generally the plugin won't want to actually do anything at this
 
241
time other than register or override functions to be called later.
 
242
 
 
243
The plugin can import bzrlib and call any function.
 
244
Some interesting APIs are described in `Bazaar Plugins Guide <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_.
 
245
 
 
246
 
 
247
Publishing your plugin
 
248
======================
 
249
 
 
250
When your plugin is basically working you might like to share it with
 
251
other people.  Here are some steps to consider:
 
252
 
 
253
 * make a project on Launchpad.net like
 
254
   <https://launchpad.net/bzr-fastimport>
 
255
   and publish the branches or tarballs there
 
256
 
 
257
 * include the plugin in <http://wiki.bazaar.canonical.com/BzrPlugins>
 
258
 
 
259
 * post about it to the ``bazaar-announce`` list at ``lists.canonical.com``
 
260
 
 
261
..
 
262
   vim: ft=rst tw=74 ai shiftwidth=4