← Back to branch summary

~jelmer/brz/hpss-working-tree-update

« back to all changes in this revision

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

  • Committer: Jelmer Vernooij
  • Date: 2018-05-18 20:21:49 UTC
  • mfrom: (6313.1.655 work)
  • Revision ID: jelmer@jelmer.uk-20180518202149-xcn8r775zgwi8x5n
merge trunk.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/plugin-api.txt
11
11
Introduction
12
12
============
13
13
 
14
 
bzrlib has a very flexible internal structure allowing plugins for many
 
14
breezy has a very flexible internal structure allowing plugins for many
15
15
operations. Plugins can add commands, new storage formats, diff and merge
16
16
features and more. This document provides an overview of the API and
17
17
conventions for plugin authors.
22
22
See also
23
23
--------
24
24
 
25
 
 * `Bazaar Developer Documentation Catalog <../index.html>`_.
26
 
 * `Bazaar Plugins Guide <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_ for
 
25
 * `Breezy Developer Documentation Catalog <../index.html>`_.
 
26
 * `Breezy Plugins Guide <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_ for
27
27
   more suggestions about particular APIs.
28
28
 
29
29
 
30
30
Structure of a plugin
31
31
=====================
32
32
 
33
 
Plugins are Python modules under ``bzrlib.plugins``. They can be installed
 
33
Plugins are Python modules under ``breezy.plugins``. They can be installed
34
34
either into the PYTHONPATH in that location, or in ~/.bazaar/plugins.
35
35
 
36
36
Plugins should have a setup.py.
42
42
Plugin metadata before installation
43
43
===================================
44
44
 
45
 
Plugins can export a summary of what they provide, and what versions of bzrlib
 
45
Plugins can export a summary of what they provide, and what versions of breezy
46
46
they are compatible with. This allows tools to be written to work with plugins,
47
47
such as to generate a directory of plugins, or install them via a
48
48
symlink/checkout to ~/.bazaar/plugins.
49
49
 
50
 
This interface allows bzr to interrogate a plugin without actually loading
 
50
This interface allows Breezy to interrogate a plugin without actually loading
51
51
it. This is useful because loading a plugin may have side effects such
52
52
as registering or overriding commands, or the plugin may raise an error,
53
53
if for example a prerequisite is not present.
56
56
Metadata protocol
57
57
-----------------
58
58
 
59
 
A plugin that supports the bzr plugin metadata protocol will do two
 
59
A plugin that supports the Breezy plugin metadata protocol will do two
60
60
things. Firstly, the ``setup.py`` for the plugin will guard the call to
61
61
``setup()``::
62
62
 
71
71
+------------------------+---------+----------------------------------------+
72
72
| Variable               | Default | Definition                             |
73
73
+========================+=========+========================================+
74
 
| bzr_plugin_name        | None    | The name the plugin package should be  |
 
74
| brz_plugin_name        | None    | The name the plugin package should be  |
75
75
|                        |         | given on disk. The plugin is then      |
76
76
|                        |         | available to python at                 |
77
 
|                        |         | bzrlib.plugins.NAME                    |
 
77
|                        |         | breezy.plugins.NAME                    |
78
78
+------------------------+---------+----------------------------------------+
79
 
| bzr_commands           | []      | A list of the commands that the plugin |
 
79
| brz_commands           | []      | A list of the commands that the plugin |
80
80
|                        |         | provides. Commands that already exist  |
81
 
|                        |         | in bzr and are decorated by the plugin |
 
81
|                        |         | in brz and are decorated by the plugin |
82
82
|                        |         | do not need to be listed (but it is not|
83
83
|                        |         | harmful if you do list them).          |
84
84
+------------------------+---------+----------------------------------------+
85
 
| bzr_plugin_version     | None    | A version_info 5-tuple with the plugins|
 
85
| brz_plugin_version     | None    | A version_info 5-tuple with the plugins|
86
86
|                        |         | version.                               |
87
87
+------------------------+---------+----------------------------------------+
88
 
| bzr_minimum_version    | None    | A version_info 3-tuple for comparison  |
89
 
|                        |         | with the bzrlib minimum and current    |
 
88
| brz_minimum_version    | None    | A version_info 3-tuple for comparison  |
 
89
|                        |         | with the breezy minimum and current    |
90
90
|                        |         | version, for determining likely        |
91
91
|                        |         | compatibility.                         |
92
92
+------------------------+---------+----------------------------------------+
93
 
| bzr_maximum_version    | None    | A version_info 3-tuple like            |
94
 
|                        |         | bzr_minimum_version but checking the   |
 
93
| brz_maximum_version    | None    | A version_info 3-tuple like            |
 
94
|                        |         | brz_minimum_version but checking the   |
95
95
|                        |         | upper limits supported.                |
96
96
+------------------------+---------+----------------------------------------+
97
 
| bzr_control_formats    | {}      | A dictionary of descriptions of version|
 
97
| brz_control_formats    | {}      | A dictionary of descriptions of version|
98
98
|                        |         | control directories. See               |
99
99
|                        |         | `Control Formats` below.               |
100
100
+------------------------+---------+----------------------------------------+
101
 
| bzr_checkout_formats   | {}      | A dictionary of tree_format_string ->  |
 
101
| brz_checkout_formats   | {}      | A dictionary of tree_format_string ->  |
102
102
|                        |         | human description strings, for tree    |
103
103
|                        |         | formats that drop into the             |
104
104
|                        |         | ``.bzr/checkout`` metadir system.      |
105
105
+------------------------+---------+----------------------------------------+
106
 
| bzr_branch_formats     | {}      | As bzr_checkout_formats but for        |
 
106
| brz_branch_formats     | {}      | As brz_checkout_formats but for        |
107
107
|                        |         | branches.                              |
108
108
+------------------------+---------+----------------------------------------+
109
 
| bzr_repository_formats | {}      | As bzr_checkout_formats but for        |
 
109
| brz_repository_formats | {}      | As brz_checkout_formats but for        |
110
110
|                        |         | repositories.                          |
111
111
+------------------------+---------+----------------------------------------+
112
 
| bzr_transports         | []      | URL prefixes for which this plugin     |
 
112
| brz_transports         | []      | URL prefixes for which this plugin     |
113
113
|                        |         | will register transports.              |
114
114
+------------------------+---------+----------------------------------------+
115
115
 
127
127
the content of the file. Thus::
128
128
 
129
129
  # (look for a .hg directory)
130
 
  bzr_control_formats = {"Mercurial":{'.hg/': None}}
 
130
  brz_control_formats = {"Mercurial":{'.hg/': None}}
131
131
 
132
132
  # (look for a file called .svn/format with contents 4\n).
133
 
  bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
 
133
  brz_control_formats = {"Subversion":{'.svn/format': '4\n'}}
134
134
 
135
135
 
136
136
Example
141
141
  #!/usr/bin/env python2.4
142
142
  from distutils.core import setup
143
143
 
144
 
  bzr_plugin_name = 'demo'
145
 
  bzr_commands = [
 
144
  brz_plugin_name = 'demo'
 
145
  brz_commands = [
146
146
      'new-command',
147
147
      ]
148
148
 
149
 
  bzr_branch_formats = {
 
149
  brz_branch_formats = {
150
150
      "Branch label on disk\n":"demo branch",
151
151
      }
152
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)
 
153
  brz_control_formats = {"Subversion":{'.svn/format': '4\n'}}
 
154
 
 
155
  brz_transports = ["hg+ssh://"]
 
156
 
 
157
  brz_plugin_version = (1, 3, 0, 'dev', 0)
 
158
  brz_minimum_version = (1, 0, 0)
159
159
 
160
160
  if __name__ == 'main':
161
161
      setup(name="Demo",
165
165
            author_email="bazaar@lists.canonical.com",
166
166
            license = "GNU GPL v2",
167
167
            url="https://launchpad.net/bzr-demo",
168
 
            packages=['bzrlib.plugins.demo',
169
 
                      'bzrlib.plugins.demo.tests',
 
168
            packages=['breezy.plugins.demo',
 
169
                      'breezy.plugins.demo.tests',
170
170
                      ],
171
 
            package_dir={'bzrlib.plugins.demo': '.'})
 
171
            package_dir={'breezy.plugins.demo': '.'})
172
172
 
173
173
 
174
174
Plugin metadata after installation
193
193
-----------
194
194
 
195
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))
 
196
breezy like so::
 
197
 
 
198
    from breezy.api import require_api
 
199
 
 
200
    require_api(breezy, (1, 11, 0))
201
201
 
202
202
Please see `API versioning <api-versioning.html>`_ for more details on the API
203
 
metadata protocol used by bzrlib.
 
203
metadata protocol used by breezy.
204
204
 
205
205
Plugin version
206
206
--------------
219
219
other places.  To detect whether the module is being loaded by bzr, use
220
220
something like this::
221
221
 
222
 
    if __name__ == 'bzrlib.plugins.loggerhead':
223
 
        # register with bzrlib...
 
222
    if __name__ == 'breezy.plugins.loggerhead':
 
223
        # register with breezy...
224
224
 
225
225
 
226
226
Plugin performance
228
228
 
229
229
Plugins should avoid doing work or loading code from the plugin or
230
230
external libraries, if they're just installed but not actually active,
231
 
because this slows down every invocation of bzr.  The bzrlib APIs
 
231
because this slows down every invocation of bzr.  The breezy APIs
232
232
generally allow the plugin to 'lazily' register methods to invoke if a
233
233
particular disk format or seen or a particular command is run.
234
234
 
240
240
startup.  Generally the plugin won't want to actually do anything at this
241
241
time other than register or override functions to be called later.
242
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>`_.
 
243
The plugin can import breezy and call any function.
 
244
Some interesting APIs are described in `Breezy Plugins Guide <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_.
245
245
 
246
246
 
247
247
Publishing your plugin