Rev 3340: (robertc) Add a plugin-api.txt developer document starting to in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Mon Apr 7 02:26:51 BST 2008
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3340
revision-id:pqm at pqm.ubuntu.com-20080407012644-p1nash3ycyh2f5n8
parent: pqm at pqm.ubuntu.com-20080406162820-yto4yesv7cnrybbt
parent: robertc at robertcollins.net-20080406233706-3md3w1c651a0pndm
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Mon 2008-04-07 02:26:44 +0100
message:
(robertc) Add a plugin-api.txt developer document starting to
description services for/from plugins. (Robert Collins)
added:
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
modified:
doc/developers/index.txt index.txt-20070508041241-qznziunkg0nffhiw-1
------------------------------------------------------------
revno: 3246.6.3
revision-id:robertc at robertcollins.net-20080406233706-3md3w1c651a0pndm
parent: robertc at robertcollins.net-20080404043834-wc6bp7fdls2w3rf5
committer: Robert Collins <robertc at robertcollins.net>
branch nick: plugin_api
timestamp: Mon 2008-04-07 09:37:06 +1000
message:
Fix ReST table formatting in doc/developers/plugin-api.txt.
modified:
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
------------------------------------------------------------
revno: 3246.6.2
revision-id:robertc at robertcollins.net-20080404043834-wc6bp7fdls2w3rf5
parent: robertc at robertcollins.net-20080229110908-uiik8oo46rho0tn2
committer: Robert Collins <robertc at robertcollins.net>
branch nick: plugin_api
timestamp: Fri 2008-04-04 15:38:34 +1100
message:
Review feedback.
modified:
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
------------------------------------------------------------
revno: 3246.6.1
revision-id:robertc at robertcollins.net-20080229110908-uiik8oo46rho0tn2
parent: pqm at pqm.ubuntu.com-20080229011300-p50it0si2y8mbv0d
committer: Robert Collins <robertc at robertcollins.net>
branch nick: plugin_api
timestamp: Fri 2008-02-29 22:09:08 +1100
message:
Add a plugin-api.txt developer document starting to description services for/from plugins.
added:
doc/developers/plugin-api.txt pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
modified:
doc/developers/index.txt index.txt-20070508041241-qznziunkg0nffhiw-1
=== added file 'doc/developers/plugin-api.txt'
--- a/doc/developers/plugin-api.txt 1970-01-01 00:00:00 +0000
+++ b/doc/developers/plugin-api.txt 2008-04-06 23:37:06 +0000
@@ -0,0 +1,173 @@
+==========
+Plugin API
+==========
+
+Status
+======
+
+:Date: 2008-02-29
+
+bzrlib has a very flexible internal structure allowing plugins for many
+operations. Plugins can add commands, new storage formats, diff and merge
+features and more. This document provides an overview of the API and
+conventions for plugin authors.
+
+.. contents::
+
+
+Structure of a plugin
+=====================
+
+Plugins are Python modules under ``bzrlib.plugins``. They can be installed
+either into the PYTHONPATH in that location, or in ~/.bazaar/plugins.
+
+Plugins should have a setup.py.
+
+As for other Python modules, the name of the directory must match the
+expected name of the plugin.
+
+
+Plugin metadata before installation
+===================================
+
+Plugins can export a summary of what they provide, and what versions of bzrlib
+they are compatible with. This allows tools to be written to work with plugins,
+such as to generate a directory of plugins, or install them via a
+symlink/checkout to ~/.bazaar/plugins.
+
+This interface allows bzr to interrogate a plugin without actually loading
+it. This is useful because loading a plugin may have side effects such
+as registering or overriding commands, or the plugin may raise an error,
+if for example a prerequisite is not present.
+
+
+Metadata protocol
+-----------------
+
+A plugin that supports the bzr plugin metadata protocol will do two
+things. Firstly, the ``setup.py`` for the plugin will guard the call to
+``setup()``::
+
+ if __name__ == 'main':
+ setup(...)
+
+Secondly, the setup module will have one or more of the following variables
+present at module scope. Any variables that are missing will be given the
+defaults from the table. An example of every variable is provided after
+the full list.
+
++------------------------+---------+----------------------------------------+
+| Variable | Default | Definition |
++========================+=========+========================================+
+| bzr_plugin_name | None | The name the plugin package should be |
+| | | given on disk. The plugin is then |
+| | | available to python at |
+| | | bzrlib.plugins.NAME |
++------------------------+---------+----------------------------------------+
+| bzr_commands | [] | A list of the commands that the plugin |
+| | | provides. Commands that already exist |
+| | | in bzr and are decorated by the plugin |
+| | | do not need to be listed (but it is not|
+| | | harmful if you do list them). |
++------------------------+---------+----------------------------------------+
+| bzr_plugin_version | None | A version_info 5-tuple with the plugins|
+| | | version. |
++------------------------+---------+----------------------------------------+
+| bzr_minimum_version | None | A version_info 3-tuple for comparison |
+| | | with the bzrlib minimum and current |
+| | | version, for determining likely |
+| | | compatibility. |
++------------------------+---------+----------------------------------------+
+| bzr_maximum_version | None | A version_info 3-tuple like |
+| | | bzr_minimum_version but checking the |
+| | | upper limits supported. |
++------------------------+---------+----------------------------------------+
+| bzr_control_formats | {} | A dictionary of descriptions of version|
+| | | control directories. See |
+| | | `Control Formats` below. |
++------------------------+---------+----------------------------------------+
+| bzr_checkout_formats | {} | A dictionary of tree_format_string -> |
+| | | human description strings, for tree |
+| | | formats that drop into the |
+| | | ``.bzr/checkout`` metadir system. |
++------------------------+---------+----------------------------------------+
+| bzr_branch_formats | {} | As bzr_checkout_formats but for |
+| | | branches. |
++------------------------+---------+----------------------------------------+
+| bzr_repository_formats | {} | As bzr_checkout_formats but for |
+| | | repositories. |
++------------------------+---------+----------------------------------------+
+
+Control Formats
+---------------
+
+Because disk format detection for formats that bzr does not understand at
+all can be useful, we allow a declarative description of the shape of a
+control directory. Each description has a name for showing to users, and a
+dictonary of relative paths, and the content needed at each path. Paths
+that end in '/' are required to be directories and the value for that key
+is ignored. Other paths are required to be regular files, and the value
+for that key is either None, in which case the file is statted but the
+content is ignored, or a literal string which is compared against for
+the content of the file. Thus::
+
+ # (look for a .hg directory)
+ bzr_control_formats = {"Mercurial":{'.hg/': None}}
+
+ # (look for a file called .svn/format with contents 4\n).
+ bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
+
+
+Example
+-------
+
+An example setup.py follows::
+
+ #!/usr/bin/env python2.4
+ from distutils.core import setup
+
+ bzr_plugin_name = 'demo'
+ bzr_commands = [
+ 'new-command',
+ ]
+
+ bzr_branch_formats = {
+ "Branch label on disk\n":"demo branch",
+ }
+
+ bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}
+
+ bzr_plugin_version = (1, 3, 0, 'dev', 0)
+ bzr_minimum_version = (1, 0, 0)
+
+ if __name__ == 'main':
+ setup(name="Demo",
+ version="1.3.0dev0",
+ description="Demo plugin for plugin metadata.",
+ author="Canonical Ltd",
+ author_email="bazaar at lists.canonical.com",
+ license = "GNU GPL v2",
+ url="https://launchpad.net/bzr-demo",
+ packages=['bzrlib.plugins.demo',
+ 'bzrlib.plugins.demo.tests',
+ ],
+ package_dir={'bzrlib.plugins.demo': '.'})
+
+
+Plugin metadata after installation
+==================================
+
+After a plugin has been installed, metadata can be more easily obtained.
+Currently the only metadata used is for API versioning.
+
+API version
+-----------
+
+Please see `API versioning <api-versioning.html>`_ for details on the API
+metadata protocol used by bzrlib.
+
+
+..
+ vim: ft=rst tw=74 ai
+
+
=== modified file 'doc/developers/index.txt'
--- a/doc/developers/index.txt 2008-01-11 05:08:20 +0000
+++ b/doc/developers/index.txt 2008-02-29 11:09:08 +0000
@@ -35,6 +35,8 @@
* `Network protocol <network-protocol.html>`_ |--| Custom network protocol.
+* `Plugin APIs <plugin-api.html>`_ |--| APIs plugins should use.
+
* `Repositories <repository.html>`_ |--| What repositories do and are used for.
Data formats
More information about the bazaar-commits
mailing list