close Warning: Can't synchronize with repository "(default)" (/common/SVN/wimax does not appear to be a Subversion repository.). Look in the Trac log for more information.

Changes between Version 3 and Version 4 of TracPlugins


Ignore:
Timestamp:
Jan 30, 2019, 11:46:28 PM (18 months ago)
Author:
trac
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • TracPlugins

    v3 v4  
    77== Plugin discovery
    88
    9 From the user's point of view, a plugin is either a standalone .py file or a package (egg or wheel). Trac looks for plugins in Python's `site-packages` directory, the [TracIni#GlobalConfiguration global shared] `plugins` directory and the [TracEnvironment project environment] `plugins` directory. Components defined in globally-installed plugins must be explicitly enabled in the [[TracIni#components-section| [components] ]] section of the `trac.ini` file. Components defined in the `plugins` directory of the project environment are enabled, unless explicitly disabled in the `[components]` section of the `trac.ini` file.
     9From the user's point of view, a plugin is either a standalone .py file or an .egg package. Trac looks for plugins in Python's `site-packages` directory, the [TracIni#GlobalConfiguration global shared] `plugins` directory and the [TracEnvironment project environment] `plugins` directory. Components defined in globally-installed plugins must be explicitly enabled in the [[TracIni#components-section| [components] ]] section of the `trac.ini` file. Components defined in the `plugins` directory of the project environment are enabled, unless explicitly disabled in the `[components]` section of the `trac.ini` file.
     10
     11== Requirements for Trac eggs #Requirements
     12
     13To use egg-based plugins in Trac, you need to have [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (version >= 0.6) installed.
     14
     15To install `setuptools`, download the bootstrap module [http://peak.telecommunity.com/dist/ez_setup.py ez_setup.py] and execute it as follows:
     16
     17{{{#!sh
     18$ python ez_setup.py
     19}}}
     20
     21If the `ez_setup.py` script fails to install the setuptools release, you can download it from [pypi:setuptools PyPI] and install it manually.
     22
     23Plugins can also consist of a single `.py` file dropped directly into either the project's or the shared `plugins` directory.
    1024
    1125== Installing a Trac plugin
     
    2539You should now have an *.egg file. Examine the output of running Python to find where this was created.
    2640
    27 Once you have the plugin archive, copy it into the `plugins` directory of the [TracEnvironment project environment]. Also, make sure that the web server has sufficient permissions to read the plugin egg. Then restart the web server. If you are running as a [TracStandalone "tracd" standalone server], restart tracd, ie kill the process and run again.
     41Once you have the plugin archive, copy it into the `plugins` directory of the [wiki:TracEnvironment project environment]. Also, make sure that the web server has sufficient permissions to read the plugin egg. Then restart the web server. If you are running as a [wiki:TracStandalone "tracd" standalone server], restart tracd, ie kill the process and run again.
    2842
    2943To uninstall a plugin installed this way, remove the egg from the `plugins` directory and restart the web server.
     
    4054{{{#!sh
    4155$ easy_install TracTags
    42 }}}
    43 {{{#!sh
    4456$ pip install TracTags
    4557}}}
    4658
    47 If `easy_install` is not on your system, see the [trac:setuptools#Installsetuptools Trac setuptools documentation].
     59If `easy_install` is not on your system, see the Requirements section above to install it. Windows users will need to add the `Scripts` directory of their Python installation (for example, `C:\Python27\Scripts`) to their `PATH` environment variable, or use the full path to `easy_install` (for example, `C:\Python27\Scripts\easy_install.py`). See [http://peak.telecommunity.com/DevCenter/EasyInstall#windows-notes easy_install Windows notes] for more information.
    4860
    4961`pip` is included in Python 2.7.9. In earlier versions of Python it can be installed through the package manager of your OS (e.g. `apt-get install python-pip`) or using the [https://pip.pypa.io/en/latest/installing.html#install-pip get_pip.py].
     
    5971==== From source
    6072
    61 `easy_install` and `pip` make installing from source a snap. Just give it the URL to either a repository or a tarball/zip of the source:
     73`easy_install` makes installing from source a snap. Just give it the URL to either a Subversion repository or a tarball/zip of the source:
    6274{{{#!sh
    6375$ easy_install https://trac-hacks.org/svn/tagsplugin/trunk
    6476}}}
    65 {{{#!sh
    66 $ pip install svn+https://trac-hacks.org/svn/tagsplugin/trunk
    67 }}}
    68 When installing from a repository using `pip`, be sure to use the repository type in the protocol. For example, `svn+https` for Subversion and `git+https` for Git.
    6977
    7078==== Enabling the plugin
    7179
    72 Unlike plugins installed per environment, you'll have to explicitly enable globally installed plugins via [TracIni trac.ini]. This also applies to plugins installed in the shared plugins directory, ie the path specified in the [TracIni#inherit-plugins_dir-option "[inherit] plugins_dir"] configuration option.
    73 
    74 This is done in the [TracIni#components-section "[components]"] section of the configuration file `trac.ini`. For example:
     80Unlike plugins installed per environment, you'll have to explicitly enable globally installed plugins via [wiki:TracIni trac.ini]. This also applies to plugins installed in the shared plugins directory, ie the path specified in the `[inherit] plugins_dir` configuration option.
     81
     82This is done in the `[components]` section of the configuration file `trac.ini`. For example:
    7583{{{#!ini
    7684[components]
     
    92100A database backup will be made before upgrading the environment, unless the `--no-backup` option is specified. For more information, refer to the documentation output by `trac-admin /path/to/env help upgrade`.
    93101
    94 ==== Redeploying static resources
    95 
    96 If you [TracInstall#MappingStaticResources mapped static resources] so they are served by the web server, and the plugin contains static resources (CSS, !JavaScript and image files), the resources will need to be deployed to the location on the filesystem that is served by the web server.
    97 
    98 Execute the `deploy` command, as was done during install and [TracUpgrade#a5.Refreshstaticresources upgrade]:
    99 
    100 {{{#!sh
    101 $ trac-admin /path/to/env deploy /deploy/path
    102 }}}
    103 
    104 After executing the command, you must restart your web server.
    105 
    106 {{{#!div style="border: 1pt dotted; margin: 1em"
    107 **Note:** Some web browsers (IE, Opera) cache CSS and Javascript files, so you should instruct your users to manually erase the contents of their browser's cache. A forced refreshed (SHIFT + <F5>) should be enough.
    108 {{{#!comment
    109 Remove above note once #9936 is fixed.
    110 }}}
    111 }}}
    112 
    113 ==== Upgrading a Plugin
    114 
    115 Normally, upgrading a plugin is simply a matter of repeating the install process. You may want to [#Uninstalling uninstall] old versions of the plugin.
    116 
    117 The `pip install` command has an `--upgrade (-U)` switch that will uninstall the old version and install the new version. The command can have some unintended side-effects though, because it will also upgrade the plugin dependencies. For example, if `Trac` is listed as a dependency of the plugin in `setup.py`, the latest version of Trac will be downloaded and installed. This may not be what you want if you are running an older version of Trac because not all your plugins are compatible with the latest version of Trac, or you simply haven't done the appropriate planning for upgrading Trac. Uninstalling and then installing the plugin can be a safer option:
    118 {{{#!sh
    119 $ pip uninstall <pluginname>
    120 $ pip install <pluginname>
    121 }}}
    122 
    123 Alternatively you can use a [https://pip.pypa.io/en/stable/user_guide/#requirements-files requirements file] and pin the versions of the packages that you don't want to implicitly upgrade.
    124 
    125102==== Uninstalling
    126103
    127 `pip` makes it easy to uninstall a plugin:
    128 {{{#!sh
    129 $ pip uninstall <pluginname>
    130 }}}
    131 
    132 The `pip uninstall` command can be used even if the plugin was installed using `easy_install` or `python setup.py install`.
    133 
    134104Neither `easy_install` nor `python setup.py` have an uninstall feature. However, it is usually trivial to remove a globally installed egg and reference:
    135105
    136  1. Do `easy_install -m <plugin name>` to remove references from `$PYTHONLIB/site-packages/easy-install.pth` when the plugin is installed by setuptools.
     106 1. Do `easy_install -m [plugin name]` to remove references from `$PYTHONLIB/site-packages/easy-install.pth` when the plugin installed by setuptools.
    137107 1. Delete executables from `/usr/bin`, `/usr/local/bin`, or `C:\\Python*\Scripts`. To find what executables are involved, refer to the `[console-script]` section of `setup.py`.
    138108 1. Delete the .egg file or folder from where it's installed, usually inside `$PYTHONLIB/site-packages/`.
     
    148118== Setting up the plugin cache
    149119
    150 Some plugins will need to be extracted by the Python egg's runtime. See [wiki:TracInstall#egg-cache] for information on setting up the egg cache.
     120Some plugins will need to be extracted by the Python egg's runtime (`pkg_resources`), so that their contents are actual files on the file system. The directory in which they are extracted defaults to `.python-eggs` in the home directory of the current user, which may or may not be a problem. You can, however, override the default location using the `PYTHON_EGG_CACHE` environment variable.
     121
     122To do this from the Apache configuration, use the `SetEnv` directive:
     123{{{#!apache
     124SetEnv PYTHON_EGG_CACHE /path/to/dir
     125}}}
     126
     127This works whether you're using the [wiki:TracCgi CGI] or the [wiki:TracModPython mod_python] front-end. Put this directive next to where you set the path to the [wiki:TracEnvironment Trac environment], ie in the same `<Location>` block.
     128
     129For example for CGI:
     130{{{#!apache
     131 <Location /trac>
     132   SetEnv TRAC_ENV /path/to/projenv
     133   SetEnv PYTHON_EGG_CACHE /path/to/dir
     134 </Location>
     135}}}
     136
     137Or for mod_python:
     138{{{#!apache
     139 <Location /trac>
     140   SetHandler mod_python
     141   ...
     142   SetEnv PYTHON_EGG_CACHE /path/to/dir
     143 </Location>
     144}}}
     145
     146'''Note''': !SetEnv requires the `mod_env` module, which needs to be activated for Apache. In this case the !SetEnv directive can also be used in the `mod_python` Location block.
     147
     148For [wiki:TracFastCgi FastCGI], you'll need to `-initial-env` option, or whatever is provided by your web server for setting environment variables.
     149
     150'''Note''': if you already use -initial-env to set the project directory for either a single project or parent, you will need to add an additional -initial-env directive to the !FastCgiConfig directive:
     151
     152{{{#!apache
     153FastCgiConfig -initial-env TRAC_ENV=/var/lib/trac -initial-env PYTHON_EGG_CACHE=/var/lib/trac/plugin-cache
     154}}}
     155
     156=== About hook scripts
     157
     158If you have set up some Subversion hook scripts that call the Trac engine, such as the post-commit hook script provided in the `/contrib` directory, make sure you define the `PYTHON_EGG_CACHE` environment variable within these scripts as well.
    151159
    152160== Web-based plugin administration
    153161
    154 The !WebAdmin interface offers limited support for plugin configuration to users with `TRAC_ADMIN` permission:
    155 
    156 * enabling and disabling installed plugins
     162The [trac:WebAdmin] interface offers limited support for plugin configuration through the web to users with `TRAC_ADMIN` permission:
     163
     164* en/disabling installed plugins
    157165* installing plugins by uploading them as eggs
    158166
     
    164172This disables the whole panel, so the first function will no longer be available either.
    165173
    166 == Writing Trac Plugins
    167 
    168 You can write your own Trac plugin using the following resources:
    169 * [trac:TracDev Developer documentation]
    170 * [https://trac-hacks.org Examples on trac-hacks.org]
    171 * [trac:browser:branches/1.2-stable/sample-plugins sample-plugins]
    172 
    173174== Troubleshooting
    174175
     
    203204=== Check the log files
    204205
    205 Enable [TracLogging logging] and set the log level to `DEBUG`, then watch the log file for messages about loading plugins.
     206Enable [wiki:TracLogging logging] and set the log level to `DEBUG`, then watch the log file for messages about loading plugins.
    206207
    207208=== Verify you have the proper permissions
    208209
    209 Some plugins require you have special permissions in order to use them. !WebAdmin, for example, requires the user to have `TRAC_ADMIN` permissions for it to show up on the navigation bar.
     210Some plugins require you have special permissions in order to use them. [trac:WebAdmin WebAdmin], for example, requires the user to have `TRAC_ADMIN` permissions for it to show up on the navigation bar.
    210211
    211212=== Is the wrong version of the plugin loading?
    212213
    213 If you put your plugins inside the `plugins` directories, and certainly if you have more than one project, you need to make sure that the correct version of the plugin is loading. Here are some basic rules:
     214If you put your plugins inside plugins directories, and certainly if you have more than one project, you need to make sure that the correct version of the plugin is loading. Here are some basic rules:
    214215
    215216 * Only one version of the plugin can be loaded for each running Trac server, ie each Python process. The Python namespaces and module list will be shared, and it cannot handle duplicates. Whether a plugin is `enabled` or `disabled` makes no difference.
     
    220221=== If all of the above failed
    221222
    222 Okay, so the logs don't mention plugins, the egg is readable, the Python version is correct, ''and'' the egg has been installed globally (and is enabled in trac.ini)... and it ''still'' doesn't work or give any error messages or any other indication as to why. Hop on the [trac:IrcChannel IrcChannel] or [trac:MailingList] and ask away!
     223Okay, so the logs don't mention plugins, the egg is readable, the Python version is correct, ''and'' the egg has been installed globally (and is enabled in trac.ini)... and it ''still'' doesn't work or give any error messages or any other indication as to why. Hop on the [trac:IrcChannel IrcChannel] and ask away!
    223224
    224225----