Rev 3247: Add a plugin-api.txt developer document starting to description services for/from plugins. in http://people.ubuntu.com/~robertc/baz2.0/plugin_api
Robert Collins
robertc at robertcollins.net
Fri Feb 29 11:09:19 GMT 2008
At http://people.ubuntu.com/~robertc/baz2.0/plugin_api
------------------------------------------------------------
revno: 3247
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
=== 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
=== 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-02-29 11:09:08 +0000
@@ -0,0 +1,168 @@
+==========
+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.
+
+
+.. contents::
+
+
+Motivation
+==========
+
+To provide a pithy central document for plugin authors to refer to.
+
+
+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.
+
+Design
+------
+
+Because loading a plugin is all that is required to activate it, and
+because plugins may require external dependencies to load properly (such
+as being specific to the Windows platform), we use a separate interface to
+obtain plugin metadata from the setup.py script which plugins will
+typically have.
+
+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 declaritive 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
+
+
More information about the bazaar-commits
mailing list