Debugging TWiki Code
Let's assume you are in one of two situations:
- You have a problem on your install, TWiki is collapsing with an error message, and you know enough Perl to figure out that it's a code bug.
- You are developing an extension to TWiki, for example a plugin.
The following tips are from the TWiki developers, and are designed to help you debug.
Log Files
The Web Server Error Log
The web server error log is a
critical resource - find out where this is located and consult it frequently, since many Perl script warnings and errors appear only in this log file.
- On Unix/Apache, the error log is often in
/var/logs/httpd/error_log
- or just look in the Apache /etc/httpd/conf/httpd.conf
(location may vary, ask your ISP if necessary) and search for 'ErrorLog' (try grep ErrorLog /etc/httpd/conf/httpd.conf
).
- On Windows, there is usually a menu item for displaying the log
TWiki Log Files
TWiki also writes a bunch of log files that may be useful. These are pointed to from
configure
, default location is the
twiki/data
directory. They are less useful than the web server error log, but may help especially when debugging plugins. By default, output from
writeDebug
and
writeLog
calls go to
twiki/data/debug.txt
and
twiki/data/log202402.txt
, respectively.
Debugging Core Code
In core code, you are highly recommended to insert some
print STDERR
calls around where the problem seems to be, to check that variables are getting set where you think you are, and to monitor activity. This output goes into the web server error log.
Here's an example, where
someSubroutine
is a function you are investigating, and
$someVariable
is a variable you are interested in.
print STDERR "someSubroutine - someVariable is $someVariable\n";
You'll need some Perl skills to do this (but not that much) - see
PerlTips for some useful links.
For more in-depth debugging, there is a graphical debugger for Perl - see Ptkdb, mentioned in
PerlTips. Most developers don't use it, though; they rely on
print STDERR
.
In several places the TWiki developers have already left
print STDERR
statements in place, but commented out. Just uncomment these statements to get - for example - a full breakdown of access control requests.
If you can't get access to the web server error log, and you are debugging a plugin, then use
TWiki::Func::writeDebug
. If you are debugging the core, you can't rely on that method so you are best to open a file on disc for append and write there instead. For example,
open(F, ">>/users/fred/wozzat.log"); print F "What's happening?\n"; close(F);
For more information on
open
, read the Perl documentation.
Dumping complex data structures
If you want to get a good look at a more complex data structure (an array, hash, or reference), use the
Data::Dumper
module, like this:
use Data::Dumper;
...
print STDERR Data::Dumper->Dump([ $value ]);
Debugging Plugins
Because of the way plugins are currently autoloaded, most compile errors and warnings in your plugin
will be silently ignored. If you're getting weird errors and don't know why:
- Check in TWikiPlugins, under FAILEDPLUGINS, where the errors will be displayed.
- Try compiling your plugin module from the command line on the server...like this:
$ cd /var/www/twiki
$ perl -Ilib -e 'use TWiki; use TWiki::Plugins::YourNewPlugin;'
That will give you any compile errors or warnings your plugin is generating. You'll need to change
/var/www/twiki
to your base twiki directory, and
YourNewPlugin
to the name of your plugin module (no
.pm
extension). And also,
use strict;
in your plugin; it really
is easier in the long run.
If you can't get access to the web server error log, then use
TWiki::Func::writeDebug
to write to the debug log file pointed at from
configure
, default is
twiki/data/debug.txt
.
Remember, Perl is an interpreted language, so any code you put in to debug will be compiled every time your plugin is run, even if it does nothing. Don't leave active
writeDebug
statements lying around in code. Comment them out when you are finished.
Debugging problems with external programs
TWiki uses some external programs that have to exist on your server. These are mainly to do with the database, which uses
RCS, and searching, which uses GNU
grep
. If you suspect a problem with an external program, then you can enable painfully detailed output to the error log by editing
lib/TWiki/Sandbox.pm
. Find the lines:
# Set to 1 to trace all command executions to STDERR
$this->{TRACE} = 0;
#$this->{TRACE} = 1; # DEBUG
Debugging Javascript
While the TWiki core dosn't use any Javascript, many plugins and extensions do. Debugging Javascript can be a nightmare due partly to the way Javascript can rewrite the page being displayed dynamically, but also because the errors are often very obscure.
If you are using Mozilla, or a Mozilla based browser like Firefox, you should get a copy of the
Venkmann Javascript debugger. It's an
invaluable tool for debugging Javascript. Internet Explorer users can download the Microsoft Script Debugger for IE-specific problems, but for all other problems you are recommended to install a Mozilla-based browser, and only use the IE based tools if you have no other choice. Some IE users will have access to Microsoft Visual Studio, which offers somewhat better debugging support.
Remember that
Mozilla and IE interpret the HTML specs differently. Just because Javascript works on Mozilla, that does not mean it works on IE, or on Safari, or any other browsers. You have to test as many as you can (and as many versions of the same browser as you can).
Executing commands as the webserver user
TWiki's default setup requires various files to have the right permissions so that the TWiki
CGI scripts can write to them. However, once the files are created by the 'nobody' user, you can't normally do anything to them without a complicated set of 'copy, delete original and rename, then fix permissions' operations. One solution is to write a custom
CGI script to do what you want (the most secure option) - another is to install
CGI-Telnet. This lets you run
any server command through a
CGI form that looks a bit like a Telnet session. Since it's a
CGI script, it can be used to run commands as 'nobody' when fixing permissions etc.
- SECURITY WARNING: This program could introduce a major security hole. Like other programs of this type, it allows you to delete, download and upload files - you are strongly recommended to choose a non-obvious password and to enable this tool only when you are actually using it, disabling it immediately afterwards.
- To disable CGI-Telnet, use
chmod 000 cgitelnet
on Unix. On NT (including CygWin), you should move it to a directory that is not CGI-enabled and is also not accessible via the Web (chmod has no effect on a default Cygwin setup).
- If you are sure you are finished using CGI-Telnet, just delete the script; you can quickly re-upload it when needed.
- All these disable/delete actions can be done from within CGI-Telnet, which is quite convenient.
- My main enhancement was a check that the password has been changed from the default password - it will refuse to work if the password has not been changed. I've tested this on CygWin but the script should also work on Unix and Windows NT/2000. I also simplified the output somewhat when logging on, and lengthened the command line.
- The original CGI-Telnet is available from http://www.rohitab.com/cgiscripts/cgitelnet.html but using this enhanced version is recommended.
- CGI-Telnet doesn't require any Perl modules, making it very easy to install (and very fast on Windows...), but it does require cookies to be enabled in your browser (and stores the password in a cookie...) - consider erasing your cookies after using CGI-Telnet, particularly if you are using a shared PC (though perhaps the program does this on disconnecting?).
Related pages:
Getting help
If all else fails (in fact,
before all else fails) you should check out the
TWiki IRC channel. Developers often hang out there. You can also use the TWiki Support web to ask questions that don't need an immediate answer. There is also a sourceforge mailing list, called TWiki-Dev, that will get to all the active developers.
Contributors: WalterMundt,
MartinRaabe,
RichardDonkin,
CrawfordCurrie