← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

https://launchpad.net/bugs/524184
NEWS section template into a separate file

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/plugin-api.txt
2
2
Plugin API
3
3
==========
4
4
 
5
 
Status
6
 
======
7
 
 
8
 
:Date: 2008-02-29
 
5
 
 
6
 
 
7
:Date: 2009-01-23
 
8
 
 
9
.. contents::
 
10
 
 
11
Introduction
 
12
============
9
13
 
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.
14
18
 
15
 
.. contents::
 
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
 * <http://bazaar-vcs.org/WritingPlugins> wiki page with many more
 
27
   suggestions about particular APIs
16
28
 
17
29
 
18
30
Structure of a plugin
97
109
| bzr_repository_formats | {}      | As bzr_checkout_formats but for        |
98
110
|                        |         | repositories.                          |
99
111
+------------------------+---------+----------------------------------------+
 
112
| bzr_transports         | []      | URL prefixes for which this plugin     |
 
113
|                        |         | will register transports.              |
 
114
+------------------------+---------+----------------------------------------+
100
115
 
101
116
Control Formats
102
117
---------------
136
151
      }
137
152
 
138
153
  bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
 
154
 
 
155
  bzr_transports = ["hg+ssh://"]
139
156
  
140
157
  bzr_plugin_version = (1, 3, 0, 'dev', 0)
141
158
  bzr_minimum_version = (1, 0, 0)
157
174
Plugin metadata after installation
158
175
==================================
159
176
 
160
 
After a plugin has been installed, metadata can be more easily obtained.
161
 
Currently the only metadata used is for API versioning.
 
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
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.
162
192
 
163
193
API version
164
194
-----------
165
195
 
166
 
Please see `API versioning <api-versioning.html>`_ for details on the API
 
196
Plugins can and should declare that they depend on a particular version of
 
197
bzrlib like so::
 
198
 
 
199
    from bzrlib.api import require_api
 
200
 
 
201
    require_api(bzrlib, (1, 11, 0))
 
202
 
 
203
Please see `API versioning <api-versioning.html>`_ for more details on the API
167
204
metadata protocol used by bzrlib.
168
205
 
 
206
Plugin version
 
207
--------------
 
208
 
 
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::
 
212
 
 
213
    version_info = (1, 10, 0)
 
214
 
 
215
 
 
216
Detecting whether code's being loaded as a plugin
 
217
-------------------------------------------------
 
218
 
 
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::
 
222
 
 
223
    if __name__ == 'bzrlib.plugins.loggerhead':
 
224
        # register with bzrlib...
 
225
 
 
226
 
 
227
Plugin performance
 
228
==================
 
229
 
 
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.
 
235
 
 
236
 
 
237
Plugin registrations
 
238
====================
 
239
 
 
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.
 
243
 
 
244
The plugin can import bzrlib and call any function.
 
245
Some interesting APIs are described in <http://bazaar-vcs.org/WritingPlugins>
 
246
 
 
247
 
 
248
Publishing your plugin
 
249
======================
 
250
 
 
251
When your plugin is basically working you might like to share it with
 
252
other people.  Here are some steps to consider:
 
253
 
 
254
 * make a project on Launchpad.net like
 
255
   <https://launchpad.net/bzr-fastimport>
 
256
   and publish the branches or tarballs there
 
257
 
 
258
 * include the plugin in <http://bazaar-vcs.org/BzrPlugins>
 
259
 
 
260
 * post about it to the ``bazaar-announce`` list at ``lists.canonical.com``
169
261
 
170
262
..
171
 
   vim: ft=rst tw=74 ai
172
 
 
173
 
 
 
263
   vim: ft=rst tw=74 ai shiftwidth=4