Changes between Initial Version and Version 1 of TracPlugins

May 4, 2007, 4:23:05 PM (15 years ago)



  • TracPlugins

    v1 v1  
     1= Trac Plugins =
     4Since version 0.9, Trac supports plugins that extend the built-in functionality. The plugin functionality is based on the [ component architecture].
     6== Requirements ==
     8To use plugins in Trac, you need to have [ setuptools] (version 0.6) installed.
     10To install `setuptools`, download the bootstrap module [] and execute it as follows:
     12$ python
     15If the `` script fails to install the setuptools release, you can download it from [ PyPI] and install it manually.
     17== Installing a Trac Plugin ==
     19=== For a Single Project ===
     21Plugins are packaged as [ Python eggs]. That means they are ZIP archives with the file extension `.egg`. If you have downloaded a source distribution of a plugin, you can run:
     23$ python bdist_egg
     25to build the `.egg` file.
     27Once you have the plugin archive, you need to 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.
     29=== For All Projects ===
     31Plugins that you want to use in all your projects (such as [ WebAdmin]) can be installed globally by running:
     33$ python install
     36Alternatively, you can just drop the `.egg` file in the Python `site-packages` directory.
     38Unlike plugins installed per-environment, you'll have to explicitly enable globally installed plugins via [wiki:TracIni trac.ini]. This is done in the `[components]` section of the configuration file, for example:
     41webadmin.* = enabled
     44The name of the option is the Python package of the plugin. This should be specified in the documentation of the Plugin, but can also be easily find out by looking at the source (look for a top-level directory that contains a file named ``.)
     46== Setting up the Plugin Cache ==
     48Some plugins will need to be extracted by the Python eggs runtime (`pkg_resources`), so that their contents are actual files on the file system. The directory in which they are extracted defaults to 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.
     50To do this from the Apache configuration, use the `SetEnv` directive as follows:
     52SetEnv PYTHON_EGG_CACHE /path/to/dir
     55This works whether your 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], i.e. in the same `<Location>` block.
     57For example (for CGI):
     59 <Location /trac>
     60   SetEnv TRAC_ENV /path/to/projenv
     61   SetEnv PYTHON_EGG_CACHE /path/to/dir
     62 </Location>
     65or (for mod_python):
     67 <Location /trac>
     68   SetHandler mod_python
     69   ...
     70   SetEnv PYTHON_EGG_CACHE /path/to/dir
     71 </Location>
     74For [wiki:TracFastCgi FastCGI], you'll need to `-initial-env` option, or whatever is provided by your web server for setting environment variables.
     77See also TracGuide, [ plugin list], [ component architecture]