[[PageOutline(2-5)]] = Trac Troubleshooting 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 [http://trac.edgewall.org/wiki Wiki pages]. Some are present in each Trac installation, for example those that are part of the TracGuide, while most are only found on this site, for example the TracFaq (frequently asked questions). Some subsystems have their dedicated page with a troubleshooting section: - PySqlite#Troubleshooting - MySqlDb#Troubleshooting - TracSubversion#Troubleshooting - TracModPython#Troubleshooting - TracPlugins#Troubleshooting - TracNotification#Troubleshooting Then, use the TracSearch to dig through existing tickets describing issues similar to yours. 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. If you're facing a new problem, the next step is to try to find out the root cause. == Debugging Trac === Python errors 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 [http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller 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. The TracDev collection of development guides can be useful here. ==== 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; an ugly but effective way of debugging. It may even be possible to run `tracd` with a debugger, but not explored here. 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