← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/plugins.txt

add a clean target

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