[[PageOutline(2-5)]] = Trac Troubleshooting or ''"When Things Go Wrong"'' = This is a collection of recipes you can use to troubleshoot Trac and help us to fix bugs. == RTFW (''Read the Fine Wiki'') == Trac comes with extensive documentation in form of a collection of Wiki pages. Some are present in each Trac installation (those that are part of the TracGuide), while most are only found on this site. Among the latter is the TracFaq (frequently asked questions). A few subsystems have their dedicated page with a troubleshooting section: - PySqlite#Troubleshooting - TracSubversion#Troubleshooting - TracModPython#Troubleshooting - TracPlugins#Troubleshooting - TracNotification#Troubleshooting Then, use the TracSearch to dig through existing tickets, looking for past issues similar to yours thanks to carefully selected keywords. The Trac ["MailingList"]s are also usually of some help. And don't forget it's a Wiki, so feel free to enhance its content while you're at it. Now, assuming you're facing a new problem, the next step is to try to find out what's really wrong. == 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 `
...` 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 ;) Best is to start from a [TracSubversion checkout] of the pristine source code you're interested to debug (or develop for). Then, you can run the standalone server by doing: {{{ $ python scripts/tracd