Changes between Version 4 and Version 5 of TracTroubleshooting

Timestamp:

Nov 3, 2006, 3:13:12 PM (18 years ago)

Author:

Christian Boos

Comment:

Some initial notes about how to debug the Python side of things

TracTroubleshooting

@@ +1 @@
+[[PageOutline(2-5)]]
 = Trac Troubleshooting or ''"When Things Go Wrong"'' =
 
@@ -23 +24 @@
 
 == Debugging Trac ==
+
+=== Python errors ===
+
+First, it should be noted that debugging Python errors in Trac is much more convenient since [milestone:0.11]:
+when you get an internal error and provided you have the TRAC_ADMIN privilege, the error page will show you an interactive stack trace, which enables you to see the faulty line of code in its context and to view the values of the local variables.
+
+Now, before describing the specific debugging techniques you can use, some basic understanding of the way Trac is working is needed.
+
+Trac uses a model-view-controller approach. The ''controller'' is a Python class called a "module" which inherits from the Component class implementing the `IRequestHandler` interface (a ''Component'' is the basic building block in the TracDev/ComponentArchitecture, it ''implements'' some ''Interface''s). The controller reacts on user requests and prepares the data that will be used by a template engine to fill the adequate template, in order to render the ''view'' which will be sent back to the user.
+
+Other resources from TracDev can be useful reading here, in particular TracDev/HowTracWorks. 
+
+==== Inspecting the Template data ====
+===== Clearsilver's HDF =====
+
+Before [milestone:0.11], Trac was using ClearSilver as its template engine.
+Clearsilver uses a so-called ''Hierarchical Data Format'' which is prepared by the controller.
+In order to inspect this ''HDF'', a simple trick is to append to the URL the `?hdfdump=1` string (or `&hdfdump=1`, in case other parameters are already present in the URL). 
+
+===== Genshi data dictionary =====
+Starting with [milestone:0.11], Trac uses the [http://genshi.edgewall.org Genshi] template engine.
+As this template engine is also written in Python, no specific data format is needed and a simple Python dictionary is used to feed the engine. It's very easy to inspect any part of this data by modifying the template and inserting `${pprint(...)}` statements, possibly in between `<pre>...</pre>` tags.
+Each modification to a template will be detected on the fly and you'll be able to see the result of the change immediately, provided you have the following setup in your TracIni:
+{{{
+[trac]
+auto_reload = yes
+}}}
+
+==== Modifying the Code ====
+
+TracStandalone is the indispensable companion whether you intend to develop or debug Trac. In particular, check out the `-r` (auto-reload) feature, which will make Trac notice any change to one of its source file and restart automatically. You can therefore see Trac react immediately to your code changes (provided you don't have syntax errors outside of a method...).
+
+In this setup, you're free to try out modification, dump additional information to the log or insert direct `print` statements... (ugly but effective way of debugging).
+
+It's probably possible to run `tracd` with a debugger, but I'll skip that paragraph for now ;)
 
 === System Errors ===