10
bzrlib has a very flexible internal structure allowing plugins for many
11
operations. Plugins can add commands, new storage formats, diff and merge
21
To provide a pithy central document for plugin authors to refer to.
24
Plugin metadata before installation
25
===================================
27
Plugins can export a summary of what they provide, and what versions of bzrlib
28
they are compatible with. This allows tools to be written to work with plugins,
29
such as to generate a directory of plugins, or install them via a
30
symlink/checkout to ~/.bazaar/plugins.
35
Because loading a plugin is all that is required to activate it, and
36
because plugins may require external dependencies to load properly (such
37
as being specific to the Windows platform), we use a separate interface to
38
obtain plugin metadata from the setup.py script which plugins will
44
A plugin that supports the bzr plugin metadata protocol will do two
45
things. Firstly, the ``setup.py`` for the plugin will guard the call to
48
if __name__ == 'main':
51
Secondly, the setup module will have one or more of the following variables
52
present at module scope. Any variables that are missing will be given the
53
defaults from the table. An example of every variable is provided after
56
+------------------------+---------+----------------------------------------+
57
| Variable | Default | Definition |
58
+========================+=========+========================================+
59
| bzr_plugin_name | None | The name the plugin package should be |
60
| | | given on disk. The plugin is then |
61
| | | available to python at |
62
| | | bzrlib.plugins.NAME |
63
+------------------------+---------+----------------------------------------+
64
| bzr_commands | [] | A list of the commands that the plugin |
65
| | | provides. Commands that already exist |
66
| | | in bzr and are decorated by the plugin |
67
| | | do not need to be listed (but it is not|
68
| | | harmful if you do list them). |
69
+------------------------+---------+----------------------------------------+
70
| bzr_plugin_version | None | A version_info 5-tuple with the plugins|
72
+------------------------+---------+----------------------------------------+
73
| bzr_minimum_version | None | A version_info 3-tuple for comparison |
74
| | | with the bzrlib minimum and current |
75
| | | version, for determining likely |
76
| | | compatibility. |
77
+------------------------+---------+----------------------------------------+
78
| bzr_maximum_version | None | A version_info 3-tuple like |
79
| | | bzr_minimum_version but checking the |
80
| | | upper limits supported. |
81
+------------------------+---------+----------------------------------------+
82
| bzr_control_formats | {} | A dictionary of descriptions of version|
83
| | | control directories. See |
84
| | | `Control Formats` below. |
85
+------------------------+---------+----------------------------------------+
86
| bzr_checkout_formats | {} | A dictionary of tree_format_string -> |
87
| | | human description strings, for tree |
88
| | | formats that drop into the |
89
| | | ``.bzr/checkout`` metadir system. |
90
+------------------------+---------+----------------------------------------+
91
| bzr_branch_formats | {} As bzr_checkout_formats but for branches. |
92
+------------------------+---------+----------------------------------------+
93
| bzr_repository_formats | {} As bzr_checkout_formats but for repositories. |
94
+------------------------+---------+----------------------------------------+
99
Because disk format detection for formats that bzr does not understand at
100
all can be useful, we allow a declaritive description of the shape of a
101
control directory. Each description has a name for showing to users, and a
102
dictonary of relative paths, and the content needed at each path. Paths
103
that end in '/' are required to be directories and the value for that key
104
is ignored. Other paths are required to be regular files, and the value
105
for that key is either None, in which case the file is statted but the
106
content is ignored, or a literal string which is compared against for
107
the content of the file. Thus::
109
# (look for a .hg directory)
110
bzr_control_formats = {"Mercurial":{'.hg/': None}}
112
# (look for a file called .svn/format with contents 4\n).
113
bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
119
An example setup.py follows::
121
#!/usr/bin/env python2.4
122
from distutils.core import setup
124
bzr_plugin_name = 'demo'
129
bzr_branch_formats = {
130
"Branch label on disk\n":"demo branch",
133
bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
135
bzr_plugin_version = (1, 3, 0, 'dev', 0)
136
bzr_minimum_version = (1, 0, 0)
138
if __name__ == 'main':
141
description="Demo plugin for plugin metadata.",
142
author="Canonical Ltd",
143
author_email="bazaar@lists.canonical.com",
144
license = "GNU GPL v2",
145
url="https://launchpad.net/bzr-demo",
146
packages=['bzrlib.plugins.demo',
147
'bzrlib.plugins.demo.tests',
149
package_dir={'bzrlib.plugins.demo': '.'})
152
Plugin metadata after installation
153
==================================
155
After a plugin has been installed, metadata can be more easily obtained.
156
Currently the only metadata used is for API versioning.
161
Please see `API versioning <api-versioning.html>`_ for details on the API
162
metadata protocol used by bzrlib.
added
removed
doc/developers/plugin-api.txt
