Edgewall Software

Changes between Version 6 and Version 7 of TracDev/PluginDevelopment


Ignore:
Timestamp:
Aug 29, 2005, 2:06:28 AM (19 years ago)
Author:
Christopher Lenz
Comment:

Document egg packaging/deployment

Legend:

Unmodified
Added
Removed
Modified

  • TracDev/PluginDevelopment

    v6 v7  
    55== Extension points ==
    66
    7 Trac offers an increasing number of ''extension points'' that allow you to plugin custom extensions for various functions. You can view a list of provided extension points on the page ''About Trac/Plugins'' (not available here yet).
     7Trac offers an increasing number of ''extension points'' that allow you to plugin custom extensions for various functions. You can view a list of provided extension points on the page ''About Trac/Plugins'' of your Trac installation.
    88
    99Currently we have:
    1010
    11  * {{{trac.core.IEnvironmentSetupParticipant}}} [[BR]]
    12    Allows plugins to participate in the creation and upgrade of the environment. Can be used to setup additional database tables or directories needed for the plugin to operate
    13  * {{{trac.web.main.IRequestHandler}}} [[BR]]
    14    Allows plugins to add handlers for HTTP requests.
    15  * {{{trac.web.chrome.INavigationContributor}}} [[BR]]
    16    Allows plugins to extend the navigation menus of the web interface.
    17  * {{{trac.web.chrome.ITemplateProvider}}} [[BR]]
    18    Extension point interface for components that provide their own ClearSilver templates and accompanying static resources.
    19  * {{{trac.perm.IPermissionRequestor}}} [[BR]]
    20    Plugins can use this extension point to define additional "actions" for the permission system.
    21  * {{{trac.Timeline.ITimelineEventProvider}}} [[BR]]
    22    Allows plugins to contribute events to the [wiki:TracTimeline timeline].
    23  * {{{trac.mimeview.api.IHTMLPreviewRenderer}}} [[BR]]
    24    Allows plugins to provide support for rendering specific content of a specific type as HTML (used for TracSyntaxColoring and image preview)
    25  * {{{trac.wiki.api.IWikiChangeListener}}} [[BR]]
    26    Allows plugins to observe creation, modification and deletion of wiki pages.
    27  * {{{trac.wiki.api.IWikiMacroProvider}}} [[BR]]
    28    Allows plugins to contribute WikiMacros to Trac.
    29  * {{{trac.wiki.api.IWikiSyntaxProvider}}} [[BR]]
    30    Plugins can extend this extension point to add custom syntax rules to the wiki formatting system. In particular, this allows registration of additional TracLinks types.
     11 `trac.core.IEnvironmentSetupParticipant`:: Allows plugins to participate in the creation and upgrade of the environment. Can be used to setup additional database tables or directories needed for the plugin to operate
     12 `trac.web.main.IRequestHandler`:: Allows plugins to add handlers for HTTP requests.
     13 `trac.web.chrome.INavigationContributor`:: Allows plugins to extend the navigation menus of the web interface.
     14 `trac.web.chrome.ITemplateProvider`:: Extension point interface for components that provide their own ClearSilver templates and accompanying static resources.
     15 `trac.perm.IPermissionRequestor`:: Plugins can use this extension point to define additional "actions" for the permission system.
     16 `trac.Timeline.ITimelineEventProvider`:: Allows plugins to contribute events to the [wiki:TracTimeline timeline].
     17 `trac.mimeview.api.IHTMLPreviewRenderer`:: Allows plugins to provide support for rendering specific content of a specific type as HTML (used for TracSyntaxColoring and image preview)
     18 `trac.wiki.api.IWikiChangeListener`::  Allows plugins to observe creation, modification and deletion of wiki pages.
     19 `trac.wiki.api.IWikiMacroProvider`:: Allows plugins to contribute WikiMacros to Trac.
     20 `trac.wiki.api.IWikiSyntaxProvider`:: Plugins can extend this extension point to add custom syntax rules to the wiki formatting system. In particular, this allows registration of additional TracLinks types.
    3121
    3222''Note that plugins can themselves add new extension points, so the list above is incomplete by nature.''
    3323
    34 == Adding custom plugins ==
     24== Writing the plugin code ==
    3525
    36 To extend Trac with a custom plugin, you need to provide a ''component''. For example, to add a new web module to Trac (i.e. a component that handles HTTP requests and extends the navigation bar), you'd start with something like the following code:
     26To extend Trac with a custom plugin, you need to implement a ''component''. For example, to add a new web module to Trac (i.e. a component that handles HTTP requests and extends the navigation bar), you'd start with something like the following code:
    3727
    3828{{{
    3929#!python
    4030from trac.core import *
     31from trac.web import IRequestHandler
    4132from trac.web.chrome import INavigationContributor
    42 from trac.web.main import IRequestHandler
    4333
    4434class HelloWorldPlugin(Component):
    … …  
    7262 * {{{log}}}: The configured logger, see the Python [http://docs.python.org/lib/module-logging.html logging API] for more information.
    7363
    74 == Deploying a custom plugin ==
     64These variables can also be accessed from the initializer (`__init__`) of a component.
    7565
    76 To register a custom plugin with a Trac environment, you edit the [wiki:TracIni trac.ini] file to add a new configuration section for your plugin. Let's assume the above plugin is in a Python module with the name ''example.helloworld''
     66Storing any other objects as instance variables of your component is probably a bad idea: remember that a component is only instantiated once for a given environment; unless your plugin is used in a CGI deployment of Trac, that means that the same component instance will get invoked for multiple HTTP requests; if the server is multi-threaded, this will even happen concurrently.
    7767
     68== Packaging and deploying plugins ==
     69
     70Plugins are packaged as [http://peak.telecommunity.com/DevCenter/PythonEggs Python Eggs]. You can use [http://peak.telecommunity.com/DevCenter/setuptools setuptools] to make a `setup.py` script that will produce a Python Egg for your plugin.
     71
     72The egg file needs to have a file named `trac_plugin.txt` in its `EGG-INFO` directory. This file should contain the names of all modules that need to be imported by Trac to register your components.
     73
     74  ''Note that this will change in the very near future: setuptools 0.6 will introduce the concept of “entry points”, which will be used instead of the `trac_plugin.txt` descriptor.''
     75
     76A plugin can either be deployed globally, or only for a specific environment. Global deployment is done by installing the plugin:
    7877{{{
    79 [helloworld]
    80 module = example.helloworld
     78$ cd /path/to/pluginsource
     79$ python setup.py install
    8180}}}
    8281
    83 Your plugin should now get loaded and registered when Trac is run (when running under [wiki:TracModPython mod_python] or [wiki:TracStandalone tracd], you'll need to restart the server). This assumes that your module is on the Python path. If it is not, you can simply tell Trac where to look for it by using the {{{path}}} option:
    84 
     82To deploy a plugin only to a specific Trac environment, copy the egg file into the `plugins` directory of that environment:
    8583{{{
    86 [helloworld]
    87 module = example.helloworld
    88 path = /home/cmlenz/src/trac-plugins
     84$ cd /path/to/pluginsource
     85$ python setup.py bdist_egg
     86$ cp dist/*.egg /path/to/projenv/plugins
    8987}}}
    9088
    91 The name of the configuration section is not significant: Trac simply goes through all the sections and looks for an option called {{{module}}}. But if your plugin also uses its own configuration options, you should of course document the name of the section where these options are expected to be found, and the admin will probably choose to put the {{{module}}} and {{{path}}} options in the same section:
    92 
     89During development of a plugin, it is inconvenient to have to install it in either of the ways described above. Instead, you should use the setuptools `develop` command:
    9390{{{
    94 [helloworld]
    95 module = example.helloworld
    96 path = /home/cmlenz/src/trac-plugins
    97 message = Hello world!
     91$ cd /path/to/pluginsource
     92$ python setup.py develop --install-dir=/path/to/projenv/plugins
    9893}}}
    9994
    100 You can use this configuration option from the plugin as follows:
     95You can omit the `--install-dir` argument to make the development version of your plugin available globally.
    10196
    102 {{{
    103 #!python
    104 ...
    105 class HelloWorldPlugin(Component):
    106     ...
    107     def process_request(self, req):
    108         req.send_response(200)
    109         req.send_header('Content-Type', 'text/plain')
    110         req.end_headers()
    111         req.write(self.config.get('helloworld', 'message')
    112 }}}
     97This will install an `.egg-link` file instead of the actual egg. That file is basically a link to the source directory of your plugin, so that Trac will always see the latest version of your code.
    11398
    11499== Disabling built-in components ==