Changes between Initial Version and Version 1 of FAQ/Debugging

May 11, 2012, 4:22:29 PM (8 years ago)
Jens Maus

initial version


  • FAQ/Debugging

    v1 v1  
     1[[TOC(titleindex, heading=FAQ Contents, notitle, depth=0, General Questions, Installing YAM, Using YAM, ARexx Scripting, Debugging)]]
     3= [wiki:"Debugging" Debugging] =
     6== Basics about YAM's debugging facilities ==
     7This article discusses how you can get more detailed information from YAM in case you run into a problem which might point out being an actual bug in YAM or any other respective component used by YAM. For the development of YAM, but also for identifying the root of a problem, certain so-called debugging statements are included in the source code of YAM. Part of these statements are normally only available in so-called debug versions of YAM. But some statements are even present in the normal final release versions.
     9So in case you have been instructed by a YAM developer to run a debug version or you want to see if there might be an issue you would like to investigate a bit deeper, the following instructions might help you. Please note, however, that most of the things discussed here are hardly of any help for novice users. So please proceed with debugging only in case you have been instructed by a YAM developer to do so.
     11__IMPORTANT NOTE:__
     13Debug output is meant to help us to find bugs in YAM and may contain private data, like passwords, user names, etc. Please make sure to strip such data from the catched output **before** making it public in any form (e.g. in the bug tracker). We take absolutely **no responsibility** for possibly hacked mail accounts due to accidently published private information. So please be aware of that when dealing with debug output.
     15Different debugging facilities in YAM:
     17YAM provides two different debugging facilities:
     191. debugging and output of all text based communication between YAM and the server you are communicating to (POP3, SMTP, etc.).
     202. a full blown debugging log containing lots of internal stuff
     22The first one is available in every YAM executable (even the release version) and is enabled by either adding the `DEBUG` ToolType to YAM's icon or by running YAM from a Shell via {{{"YAM DEBUG"}}}. The latter method should be the preferred one, because the output can be redirected to a file ({{{"YAM DEBUG >debug.log"}}}) then, which you can edit afterwards.
     24The second facility is not contained in the normal release version of YAM, but in a special debug executable. This executable is also available on YAM's download page. Please make sure to catch the right debug archive for you platform and install the "YAM.debug" executable beside your normal "YAM" executable.
     26To make use of this special debug version, you also need a way to catch the serial output that this debug version sends its debugging information to. This can either be achieved by using a null-modem connection to a second computer (connected to your Amiga via a serial nullmodem cable) or via the Sashimi application available on AmiNet (for OS3/68k, for Morphos/PPC or for AmigaOS4/PPC). Sashimi is an application to cath all output sent to the serial line of your computer and as such allows you to catch the debugging information sent by YAM. In case you are not using Sashimi to capture the debug output, it will be send over the serial line to the remote computer and must be logged there with an appropriate terminal program (e.g. HyperTerminal or TeraTerm Pro under Windows or miniterm under Unix).
     28__Using Sashimi:__
     30If you are using Sashimi to log the debugging information locally, please run Sashimi before running YAM like this:
     33run <>nil: sashimi on noprompt >debug.log
     36Sashimi offers some more options to influence its behaviour. Please refer to Sashimi's documentation for further information.
     38Other required third-party debug tools:
     40Depending on the platform you are running YAM you should have the following tools installed and running before you start running a debug session of YAM:
     42AmigaOS3 or MorphOS:
     44* Enforcer or CyberGuard - to catch illegal memory accesses.
     45* SegTracker - to enable Enforcer/CyberGuard to show the hunk and source code information of the memory fault.
     49* MemGuard - to enable OS4 to track for memory leaks and such
     51All these tools are available mostly on AmiNet or from other public places . Please read their documentation carefully. Usually no special options need to be specified to get a usable output in case of a crash. The only important point is to start those tools before running YAM.
     53__How to define which debugging information to get:__
     55Once you are able to catch the serial output that is sent by the debug version of YAM, you need to tell YAM what kind of debug information you want to have. This is done by using an environment variable (ENV variable) called "yamdebug". You just need to set this variable to a string which contains certain command which YAM will interpret as soon as it will be started (see below).
     57YAM's internal debugging facility is split into two parts: debug classes and debug flags. Debug flags are normally used to define a certain debug output to a function or area of the application (e.g. information about arexx, the startup, tcp/ip related, etc.). Debug classes, however, are used to define that the debug output/information is of a certain nature (e.g. a warning, an error or such). So most of the time you will probably want to set debug flags and only define a whole debug class to be shown or hided in case you receive too much or too less information.
     59All currently available debug flags are:
     61* always - print out always, not specifically related
     62* startup - startup/shutdown stuff
     63* timerio - timer.device stuff
     64* config - all about configuration handling
     65* filter - mail filtering (including spam filtering)
     66* folder - folder management
     67* mail - stuff related to single mails
     68* mime - MIME stuff
     69* gui - GUI handling
     70* rexx - ARexx stuff
     71* net - network and TCP/IP stuff
     72* util - miscellaneous utility stuff
     73* import - mail import and export
     74* xpk - the XPK compression system
     75* image - image handling and caching
     76* update - YAM's automatic update feature
     77* html - HTML document handling
     78* spam - information about the spam filter engine
     79* uidl - UIDL handling ("avoid duplicate mails")
     80* hash - hash table stuff
     81* print - printing of mails
     82* theme - theme stuff
     83* thread - thread handling
     84* all - all of the above
     86By default only the always and startup flags are active. That means, in case you start the debug version of YAM without having the "yamdebug" ENV: variable setup it will only print minor information about the startup and shutdown of YAM. Several flags can be combined and must be separated by either a space, a comma or a semicolon. Flags can also be excluded (negated) by prepending a '!'.
     88The following debug classes are available:
     90* @ctrace - generate a trace of all functions being entered and left
     91* @report -print out report information
     92* @assert - print out assertions
     93* @timeval - print out timing measurements
     94* @debug - print out normal debugging messages
     95* @error - print out error messages
     96* @warning - print out warning messages
     97* @mtrack - print out memory tracking warnings
     98* @tags - print out tag lists
     99* @all - all of the above
     101By default the classes @report, @assert, @debug, @error, @warning and @mtrack are active.
     103Debug classes must be prepended by a '@' character as can be seen by the above list. Several classes can be combined and must be separated by either a space, a comma or a semicolon. Classes can also be excluded (negated) by prepending a '!'.
     105There are two special classes which influence the way the output is generated.
     107Adding "stdout" will output all messages to the Shell window YAM was started from (or to the automatically opened window when YAM was started from the Workbench). These messages can be redirected to a file.
     109Adding "file:path_to_file" will generate a file named "path_to_file" and write all debugging messages directly to this file.
     115setenv yamdebug "net image !startup"
     117This will enable debugging of the network stuff and image handling, but anything related to the startup/shutdown process will be excluded.All debug messages will be transmitted via the serial line to a connected terminal. Optionally these can be captured with a tool like Sashimi.
     120setenv yamdebug all,@!all,@error,stdout
     122This will enable all debug flags, but only for error messages. All debug messages will be printed to the Shell window YAM was started from.
     125setenv yamdebug @ctrace,@error,@!assert,stdout
     127This will enable trace information and error messages, but no assertions
     130setenv yamdebug @all,file:ram:t/debuglog.txt
     132This will enable all debug classes. Beware: the debug log file will become HUGE!!! All debug messages will be directly written to the file "ram:t/debuglog.txt" instead of the serial line.
     134Debug classes and flags can even be combined on one line. That means, e.g. {{{setenv yamdebug @all,all}}} will enable all debug classes and flags and produce the most verbose debug log possible (really, really HUGE!!!)