bugs1Add my vote for this tag development1Add my vote for this tag create new tag
, view all tags

Debugging TWiki Code

Let's assume you are in one of two situations:

  1. 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.
  2. 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/log201705.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:

  1. Check in TWikiPlugins, under FAILEDPLUGINS, where the errors will be displayed.
  2. 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

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatEXT cgitelnet r2 r1 manage 21.7 K 2002-04-05 - 23:43 RichardDonkin Version with corrected password
Edit | Attach | Watch | Print version | History: r27 < r26 < r25 < r24 < r23 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r27 - 2014-10-21 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.