/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

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

  • Committer: Gustav Hartvigsson
  • Date: 2021-01-09 21:36:27 UTC
  • Revision ID: gustav.hartvigsson@gmail.com-20210109213627-h1xwcutzy9m7a99b
Added 'Case Preserving Working Tree Use Cases' from Canonical Wiki

* Addod a page from the Canonical Bazaar wiki
  with information on the scmeatics of case
  perserving filesystems an a case insensitive
  filesystem works.
  
  * Needs re-work, but this will do as it is the
    same inforamoton as what was on the linked
    page in the currint documentation.

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
breezy 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
 * `Breezy Developer Documentation Catalog <../index.html>`_.
 
26
 * `Breezy Plugins Guide <plugin-development.txt>`_ for
 
27
   more suggestions about particular APIs.
 
28
 
 
29
 
 
30
Structure of a plugin
 
31
=====================
 
32
 
 
33
Plugins are Python modules under ``breezy.plugins``. They can be installed
 
34
either into the PYTHONPATH in that location, or in ~/.config/breezy/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 breezy
 
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 ~/.config/breezy/plugins.
 
49
 
 
50
This interface allows Breezy 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 Breezy 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
| brz_plugin_name        | None    | The name the plugin package should be  |
 
75
|                        |         | given on disk. The plugin is then      |
 
76
|                        |         | available to python at                 |
 
77
|                        |         | breezy.plugins.NAME                    |
 
78
+------------------------+---------+----------------------------------------+
 
79
| brz_commands           | []      | A list of the commands that the plugin |
 
80
|                        |         | provides. Commands that already exist  |
 
81
|                        |         | in brz 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
| brz_plugin_version     | None    | A version_info 5-tuple with the plugins|
 
86
|                        |         | version.                               |
 
87
+------------------------+---------+----------------------------------------+
 
88
| brz_minimum_version    | None    | A version_info 3-tuple for comparison  |
 
89
|                        |         | with the breezy minimum and current    |
 
90
|                        |         | version, for determining likely        |
 
91
|                        |         | compatibility.                         |
 
92
+------------------------+---------+----------------------------------------+
 
93
| brz_maximum_version    | None    | A version_info 3-tuple like            |
 
94
|                        |         | brz_minimum_version but checking the   |
 
95
|                        |         | upper limits supported.                |
 
96
+------------------------+---------+----------------------------------------+
 
97
| brz_control_formats    | {}      | A dictionary of descriptions of version|
 
98
|                        |         | control directories. See               |
 
99
|                        |         | `Control Formats` below.               |
 
100
+------------------------+---------+----------------------------------------+
 
101
| brz_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
| brz_branch_formats     | {}      | As brz_checkout_formats but for        |
 
107
|                        |         | branches.                              |
 
108
+------------------------+---------+----------------------------------------+
 
109
| brz_repository_formats | {}      | As brz_checkout_formats but for        |
 
110
|                        |         | repositories.                          |
 
111
+------------------------+---------+----------------------------------------+
 
112
| brz_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
  brz_control_formats = {"Mercurial":{'.hg/': None}}
 
131
 
 
132
  # (look for a file called .svn/format with contents 4\n).
 
133
  brz_control_formats = {"Subversion":{'.svn/format': '4\n'}}
 
134
 
 
135
 
 
136
Example
 
137
-------
 
138
 
 
139
An example setup.py follows::
 
140
 
 
141
  #!/usr/bin/env python3
 
142
  from distutils.core import setup
 
143
 
 
144
  brz_plugin_name = 'demo'
 
145
  brz_commands = [
 
146
      'new-command',
 
147
      ]
 
148
 
 
149
  brz_branch_formats = {
 
150
      "Branch label on disk\n":"demo branch",
 
151
      }
 
152
 
 
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
 
 
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=['breezy.plugins.demo',
 
169
                      'breezy.plugins.demo.tests',
 
170
                      ],
 
171
            package_dir={'breezy.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
Plugin version
 
193
--------------
 
194
 
 
195
The plugin should expose a version tuple to describe its own version.
 
196
Some plugins use a version number that corresponds to the version of bzr
 
197
they're released against, but you can use whatever you want.  For example::
 
198
 
 
199
    version_info = (1, 10, 0)
 
200
 
 
201
 
 
202
Detecting whether code's being loaded as a plugin
 
203
-------------------------------------------------
 
204
 
 
205
You may have a Python module that can be used as a bzr plugin and also in
 
206
other places.  To detect whether the module is being loaded by bzr, use
 
207
something like this::
 
208
 
 
209
    if __name__ == 'breezy.plugins.loggerhead':
 
210
        # register with breezy...
 
211
 
 
212
 
 
213
Plugin performance
 
214
==================
 
215
 
 
216
Plugins should avoid doing work or loading code from the plugin or
 
217
external libraries, if they're just installed but not actually active,
 
218
because this slows down every invocation of bzr.  The breezy APIs
 
219
generally allow the plugin to 'lazily' register methods to invoke if a
 
220
particular disk format or seen or a particular command is run.
 
221
 
 
222
 
 
223
Plugin registrations
 
224
====================
 
225
 
 
226
The plugin ``__init__.py`` runs when the plugin is loaded during bzr
 
227
startup.  Generally the plugin won't want to actually do anything at this
 
228
time other than register or override functions to be called later.
 
229
 
 
230
The plugin can import breezy and call any function.
 
231
Some interesting APIs are described in `Breezy Plugins Guide <plugin-development.txt>`_.
 
232
 
 
233
 
 
234
Publishing your plugin
 
235
======================
 
236
 
 
237
When your plugin is basically working you might like to share it with
 
238
other people.  Here are some steps to consider:
 
239
 
 
240
 * make a project on Launchpad.net like
 
241
   <https://launchpad.net/bzr-fastimport>
 
242
   and publish the branches or tarballs there
 
243
 
 
244
 * include the plugin in <http://wiki.bazaar.canonical.com/BzrPlugins>
 
245
 
 
246
 * post about it to the ``bazaar-announce`` list at ``lists.canonical.com``
 
247
 
 
248
..
 
249
   vim: ft=rst tw=74 ai shiftwidth=4