← Back to branch summary

~bzr/ubuntu/lucid/bzr/beta-ppa

« back to all changes in this revision

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

  • Committer: Martin Pool
  • Date: 2010-07-02 07:29:40 UTC
  • mfrom: (129.1.7 packaging-karmic)
  • Revision ID: mbp@sourcefrog.net-20100702072940-hpzq5elg8wjve8rh
http://bugs.debian.org/452024
http://bugs.debian.org/464688
http://bugs.debian.org/523595
http://bugs.debian.org/526233
http://bugs.debian.org/537708
http://bugs.debian.org/555336
http://bugs.debian.org/555343
https://launchpad.net/bugs/249452
https://launchpad.net/bugs/385074
* PPA rebuild.
* PPA rebuild for Karmic.
* PPA rebuild for Jaunty.
* PPA rebuild for Hardy.
* From postinst, actually remove the example bash completion scripts.
  (LP: #249452)
* New upstream release.
* New upstream release.
* New upstream release.
* Revert change to Build-depends: Dapper does not have python-central.
  Should be python-support..
* Target ppa..
* Target ppa..
* Target ppa..
* Target ppa..
* New upstream release.
* Switch to dpkg-source 3.0 (quilt) format.
* Bump standards version to 3.8.4.
* Remove embedded copy of python-configobj. Closes: #555336
* Remove embedded copy of python-elementtree. Closes: #555343
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* debian/control: Fix obsolete-relation-form-in-source
  lintian warning. 
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Split out docs into bzr-doc package.
* New upstream release.
* Added John Francesco Ferlito to Uploaders.
* Fix install path to quick-reference guide
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again, again.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to path changes.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Bump standards version to 3.8.3.
* Remove unused patch system.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix copy and paste tab error in .install file
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
 + Fixes compatibility with Python 2.4. Closes: #537708
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream version.
* Bump standards version to 3.8.2.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add python-pyrex to build-deps to ensure C extensions are always build.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix API compatibility version. (Closes: #526233)
* New upstream release.
  + Fixes default format for upgrade command. (Closes: #464688)
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add missing dependency on zlib development library. (Closes:
  #523595)
* Add zlib build-depends.
* Add zlib build-depends.
* Add zlib build-depends.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Move to section vcs.
* Bump standards version to 3.8.1.
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Recommend ca-certificates. (Closes: #452024)
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Update watch file. bazaar now uses launchpad to host its sources.
* Remove patch for inventory root revision copy, applied upstream.
* New upstream release.
* New upstream release.
* New upstream release
* Force removal of files installed in error to /etc/bash_completion.d/
  (LP: #249452)
* New upstream release.
* New upstream release
* New upstream release.
* Bump standards version.
* Include patch for inventory root revision copy, required for bzr-svn.
* New upstream release.
* Remove unused lintian overrides.
* Correct the package version not to be native.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Final 1.5 release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add myself as a co-maintainer.
* Add a Dm-Upload-Allowed: yes header.
* New upstream bugfix release.
* New upstream release.
* Final 1.3 release.
* New upstream release.
* First release candidate of the upcoming 1.3 release.
* Rebuild to fix the problem caused by a build with a broken python-central.
* New upstream release.
* Rebuild for dapper PPA.
* Apply Lamont's patches to fix build-dependencies on dapper.
  (See: https://bugs.launchpad.net/bzr/+bug/189915)

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
 * <http://bazaar-vcs.org/WritingPlugins> wiki page with many more
 
27
   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
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.
 
192
 
 
193
API version
 
194
-----------
 
195
 
 
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
 
204
metadata protocol used by bzrlib.
 
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``
 
261
 
 
262
..
 
263
   vim: ft=rst tw=74 ai shiftwidth=4