Changes between Version 27 and Version 28 of TracPlugins

Timestamp:

Jul 10, 2006, 11:47:39 AM (18 years ago)

Author:

Christopher Lenz

Comment:

Add troubleshooting section

TracPlugins

@@ -36 +36 @@
 
 === For All Projects ===
-==== With a .egg file ====
+
+==== With an .egg file ====
+
 Some plugins (such as WebAdmin) are downloadable as a `.egg` file which can be installed with the `easy_install` program:
 {{{
@@ -53 +55 @@
 
 ==== From source ====
+
 If you downloaded the plugin's source from Subversion, or a source zip file you can install it using the included `setup.py`:
 {{{
@@ -105 +108 @@
 For [wiki:TracFastCgi FastCGI], you'll need to `-initial-env` option, or whatever is provided by your web server for setting environment variables.
 
+== Troubleshooting ==
+
+=== Is setuptools properly installed? ===
+
+Try this from the command line:
+{{{
+$ python -c "import pkg_resources"
+}}}
+
+If you get '''no output''', setuptools '''is''' installed. Otherwise, you'll need to install it before plugins will work in Trac.
+
+=== Did you get the correct version of the Python egg? ===
+
+Python eggs have the Python version encoded in their filename. For example, `MyPlugin-1.0-py2.4.egg` is an egg for Python 2.4, and will '''not''' be loaded if you're running a different Python version (such as 2.3 or 2.5).
+
+Also, verify that the egg file you downloaded is indeed a ZIP archive. If you downloaded it from a Trac site, chances are you downloaded the HTML preview page instead.
+
+=== Is the plugin enabled? ===
+
+If you install a plugin globally (i.e. ''not'' inside the `plugins` directory of the Trac project environment) you will have to explicitly enable it in [wiki:TracIni trac.ini]. Make sure that:
+ * you actually added the necessary line(s) to the `[components]` section
+ * the package/module names are correct
+ * if you're reference a module (as opposed to a class), you've appended the necessary “.*”
+ * the value is “enabled", not e.g. “enable”
+
+=== Check the permissions on the egg file ===
+
+Trac must of course be able to read the file. Yeah, you knew that ;-)
+
+=== Check the log files ===
+
+Enable [wiki:TracLogging logging] in Trac, set the log level to `DEBUG` and then watch the log file for messages about loading plugins.
+
 ----
 See also TracGuide, [wiki:PluginList plugin list], [wiki:TracDev/ComponentArchitecture component architecture]