← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/plugins.txt

Deprecate compare_trees and move its body to InterTree.changes_from.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/plugins.txt
 
1
What is a Plugin
 
2
================
 
3
A plugin is an external component for Bazaar-NG that is typically made by
 
4
third parties. A plugin is capable of augmenting Bazaar-NG by adding or
 
5
replacing new or current functionality in Bazaar-NG. Plugins often work as
 
6
a way for developers to test new features for Bazaar-NG prior to inclusion
 
7
in the official codebase. Plugins can do a variety of things, including
 
8
overriding commands, adding new commands, providing additional network
 
9
transports, customizing log output. The sky is the limit for the
 
10
customization that can be done through plugins.
 
11
 
 
12
Where to find Plugins 
 
13
=====================
 
14
We keep our list of plugins on the http://bazaar-vcs.org/PluginRegistry page.
 
15
 
 
16
Writing a plugin
 
17
================
 
18
Plugins are very similar to bzr core functionality.  They can import
 
19
anything in bzrlib.  A plugin may simply override standard functionality,
 
20
but most plugins supply new commands.
 
21
 
 
22
To create a command, make a new object that derives from
 
23
`bzrlib.commands.Command`, and name it cmd_foo, where foo is the name of
 
24
your command.  If you create a command whose name contains an underscore,
 
25
it will appear in the UI with the underscore turned into a hyphen.  For
 
26
example, "cmd_baz_import" will appear as "baz-import".  For examples of how
 
27
to write commands, please see builtins.py.
 
28
 
 
29
Once you've created a command you must register the command with
 
30
`bzrlib.commands.register_command(cmd_foo)`.  You must register the command
 
31
when your file is imported, otherwise bzr will not see it.
 
32
 
 
33
Bzr will scan **bzrlib/plugins** and **~/.bazaar/plugins** for plugins by
 
34
default.  You can override this with **BZR_PLUGIN_PATH**.  Plugins may be
 
35
either modules or packages.  If your plugin is a single file, you can
 
36
structure it as a module.  If it has multiple files, or if you want to
 
37
distribute it as a bzr branch, you should structure it as a package, i.e. a
 
38
directory with an **__init__.py** file.
 
39
 
 
40
Please feel free to contribute your plugin to BzrTools, if you think it
 
41
would be useful to other people.
 
42
 
 
43
How to Install a plugin 
 
44
=======================
 
45
Installing a plugin is very easy! One can either install a plugin
 
46
systemwide or on a user by user basis. Both methods involve create a
 
47
"plugins" directory. Within this directory one can place plugins in
 
48
subdirectories. For example, "plugins/bzrtools/".
 
49
 
 
50
Two locations are currently checked; the bzrlib/plugins directory
 
51
(typically found in /usr/lib/python2.4/site-packages/bzrlib/plugins/) and
 
52
$HOME/.bazaar/plugins/.
 
53
 
 
54
One can additionally override the home plugins by setting the environment
 
55
variable BZR_PLUGIN_PATH to a directory that contains plugins. The
 
56
installation of a plugin can be checked by running **bzr plugins** at
 
57
any time. New commands can be seen by running **bzr help commands**.
 
58
 
 
59
Plugins work particularly well with Bazaar-NG branches. For example, to
 
60
install the bzrtools plugins for your main user account, one can perform
 
61
the following:: 
 
62
 
 
63
    bzr branch http://panoramicfeedback.com/opensource/bzr/bzrtools
 
64
    ~/.bazaar/plugins/bzrtools
 
65