Rev 4631: Update doc and add NEWS entry. in file:///home/vila/src/bzr/bugs/412930-plugin-path/
Vincent Ladeuil
v.ladeuil+lp at free.fr
Thu Aug 20 14:26:37 BST 2009
At file:///home/vila/src/bzr/bugs/412930-plugin-path/
------------------------------------------------------------
revno: 4631
revision-id: v.ladeuil+lp at free.fr-20090820132636-i3rs1vf3d3fn46hq
parent: v.ladeuil+lp at free.fr-20090820094722-ng0j9r3re8tk52y7
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: 412930-plugin-path
timestamp: Thu 2009-08-20 15:26:36 +0200
message:
Update doc and add NEWS entry.
* bzrlib/tests/test_plugins.py:
(TestEnvPluginPath.test_disable_core,
TestEnvPluginPath.test_disable_site,
TestEnvPluginPath.test_override_site,
TestEnvPluginPath.test_override_core):
* bzrlib/plugin.py:
(get_standard_plugins_path): Give a better explanantion and don't
break compatibility.
* bzrlib/help_topics/en/configuration.txt:
(BZR_PLUGIN_PATH): Update doc.
* doc/en/user-guide/plugins.txt:
Fix doc.
* doc/en/user-guide/writing_a_plugin.txt:
Fix doc.
-------------- next part --------------
=== modified file 'NEWS'
--- a/NEWS 2009-08-18 20:05:30 +0000
+++ b/NEWS 2009-08-20 13:26:36 +0000
@@ -74,6 +74,11 @@
New Features
************
+* Give more control on BZR_PLUGIN_PATH by providing a way to refer to or
+ disable the user, site and core plugin directories.
+ (Vincent Ladeuil, #412930, #316192, #145612)
+
+
Bug Fixes
*********
=== modified file 'bzrlib/help_topics/en/configuration.txt'
--- a/bzrlib/help_topics/en/configuration.txt 2009-06-26 18:13:41 +0000
+++ b/bzrlib/help_topics/en/configuration.txt 2009-08-20 13:26:36 +0000
@@ -63,6 +63,59 @@
~~~~~~~~~~~~~~~
The path to the plugins directory that Bazaar should use.
+If not set, Bazaar will search for plugins in:
+
+* the user specific plugin directory (containing the user plugins),
+
+* the bzrlib directory (containing the core plugins),
+
+* the size specific plugin directory if applicable (containing
+ the site plugins).
+
+If ``BZR_PLUGIN_PATH`` is set in any fashion, it will change the
+the way the plugin are searched.
+
+As for the ``PATH`` variables, if multiple directories are
+specified in ``BZR_PLUGIN_PATH`` they should be separated by the
+platform specific appropriate character (':' on Unix/Linux/etc,
+';' on windows)
+
+By default all directories specified in ``BZR_PLUGIN_PATH``
+replace 'user' in the but keep searching in 'core' then 'site'.
+
+If you need to change the order or remove one of these
+directories, you should use special values:
+
+* ``-user``, ``-core``, ``-site`` will remove the corresponding
+ path from the default values,
+
+* ``+user``, ``+core``, ``+site`` will add the corresponding path
+ before the remaining default values (and also remove it from
+ the default values).
+
+Note that the special values 'user', 'core' and 'site' should be
+used literally, they will be substituted by the corresponding,
+platform specific, values.
+
+Examples:
+^^^^^^^^^
+
+The examples below uses ':' as the separator, windows users
+should use ';'.
+
+Overriding the default user plugin directory:
+``BZR_PLUGIN_PATH='/path/to/my/other/plugins'``
+
+Disabling the site directory while retaining the user directory:
+``BZR_PLUGIN_PATH='-site:+user'``
+
+Disabling all plugins (better achieved with --no-plugins):
+``BZR_PLUGIN_PATH='-user:-core:-site'``
+
+Overriding the default site plugin directory:
+``BZR_PLUGIN_PATH='/path/to/my/site/plugins:-site':+user``
+
+
BZRPATH
~~~~~~~
=== modified file 'bzrlib/plugin.py'
--- a/bzrlib/plugin.py 2009-08-20 09:47:22 +0000
+++ b/bzrlib/plugin.py 2009-08-20 13:26:36 +0000
@@ -140,11 +140,19 @@
def get_standard_plugins_path():
"""Determine a plugin path suitable for general use."""
# Ad-Hoc default: core is not overriden by site but user can overrides both
- defaults = ['+user', '+core', '+site']
- env_paths = []
- env_path = os.environ.get('BZR_PLUGIN_PATH', None)
- if env_path:
- env_paths = env_path.split(os.pathsep)
+ # The rationale is that:
+ # - 'site' comes last, because these plugins should always be available and
+ # are supposed to be in sync with the bzr installed on site.
+ # - 'core' comes before 'site' so that running bzr from sources or a user
+ # installed version overrides the site version.
+ # - 'user' comes first, because... user is always right.
+ # - the above rules clearly defines which plugin version will be loaded if
+ # several exist. Yet, it is sometimes desirable to disable some directory
+ # so that a set of plugin is disabled as once. This can be done via
+ # -site, -core, -user.
+
+ env_paths = os.environ.get('BZR_PLUGIN_PATH', '+user').split(os.pathsep)
+ defaults = ['+core', '+site']
# The predefined references
refs = dict(core=get_core_plugin_path(),
@@ -173,11 +181,11 @@
defaults.remove(added)
else:
# Explicit beats implicit
- if added in env_paths:
+ if added in env_paths and added in defaults:
defaults.remove(added)
- # Prepend the remaining defaults
- paths = defaults + env_paths
+ # Append the remaining defaults
+ paths = env_paths + defaults
# Resolve references
def resolve_ref(p):
=== modified file 'bzrlib/tests/test_plugins.py'
--- a/bzrlib/tests/test_plugins.py 2009-08-20 09:47:22 +0000
+++ b/bzrlib/tests/test_plugins.py 2009-08-20 13:26:36 +0000
@@ -696,21 +696,23 @@
self.check_path([self.core, self.site], ['-user', '+user'])
def test_disable_core(self):
- self.check_path([self.user, self.site], ['-core'])
+ self.check_path([self.site], ['-core'])
+ self.check_path([self.user, self.site], ['+user', '-core'])
def test_disable_site(self):
- self.check_path([self.user, self.core], ['-site'])
+ self.check_path([self.core], ['-site'])
+ self.check_path([self.user, self.core], ['-site', '+user'])
def test_override_site(self):
- self.check_path([self.core, 'mysite', self.user],
- ['+core', 'mysite', '-site', '+user'])
- self.check_path([self.user, self.core, 'mysite'],
+ self.check_path(['mysite', self.user, self.core],
+ ['mysite', '-site', '+user'])
+ self.check_path(['mysite', self.core],
['mysite', '-site'])
def test_override_core(self):
- self.check_path(['mycore', self.site, self.user],
- ['mycore', '-core', '+site', '+user'])
- self.check_path([self.user, self.site, 'mycore'],
+ self.check_path(['mycore', self.user, self.site],
+ ['mycore', '-core', '+user', '+site'])
+ self.check_path(['mycore', self.site],
['mycore', '-core'])
def test_my_plugin_only(self):
=== modified file 'doc/en/user-guide/plugins.txt'
--- a/doc/en/user-guide/plugins.txt 2007-12-14 07:35:49 +0000
+++ b/doc/en/user-guide/plugins.txt 2009-08-20 13:26:36 +0000
@@ -56,23 +56,11 @@
Alternative plugin locations
----------------------------
-If you have the necessary permissions, plugins can also be installed on
-a system-wide basis. Two locations are currently checked for plugins:
-
- 1. the system location - bzrlib/plugins
- 2. the personal location - $BZR_HOME/plugins.
-
-On a Linux installation, these locations are typically
-``/usr/lib/python2.4/site-packages/bzrlib/plugins/`` and
-``$HOME/.bazaar/plugins/``.
-On a Windows installation, the system location might be
-``C:\\Program Files\\Bazaar\\plugins``
-while the personal location might be
-``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0\plugins``.
-
-One can additionally override the personal plugins location
-by setting the environment variable ``BZR_PLUGIN_PATH``
-to a directory that contains plugins.
+If you have the necessary permissions, plugins can also be installed on a
+system-wide basis. One can additionally override the personal plugins
+location by setting the environment variable ``BZR_PLUGIN_PATH`` (see `User
+Reference <../user-reference/bzr_man.html#bzr-plugin-path>`_ for a detailed
+explanation).
Listing the installed plugins
-----------------------------
=== modified file 'doc/en/user-guide/writing_a_plugin.txt'
--- a/doc/en/user-guide/writing_a_plugin.txt 2008-10-15 19:34:48 +0000
+++ b/doc/en/user-guide/writing_a_plugin.txt 2009-08-20 13:26:36 +0000
@@ -32,11 +32,14 @@
Plugin searching rules
----------------------
-Bzr will scan ``bzrlib/plugins`` and ``~/.bazaar/plugins`` for plugins
-by default. You can override this with ``BZR_PLUGIN_PATH``. Plugins
-may be either modules or packages. If your plugin is a single file,
-you can structure it as a module. If it has multiple files, or if you
-want to distribute it as a bzr branch, you should structure it as a
+Bzr will scan ``~/.bazaar/plugins`` and ``bzrlib/plugins`` for plugins
+by default. You can override this with ``BZR_PLUGIN_PATH``
+(see `User Reference <../user-reference/bzr_man.html#bzr-plugin-path>`_
+for details).
+
+Plugins may be either modules or packages. If your plugin is a single
+file, you can structure it as a module. If it has multiple files, or if
+you want to distribute it as a bzr branch, you should structure it as a
package, i.e. a directory with an ``__init__.py`` file.
More information
More information about the bazaar-commits
mailing list