source: trunk/doc/ReportingBugs.txt@ 10130

This file is a subset of the OdinBug online help file.


Reporting Bugs:
===============

To make our job easier when dealing with reports of failures to run certain
applications, there's a standard form to report bugs. 
Use OdinBug to create these bug reports.

Some remarks:

- Always try the debug build with the application unless only the release
  build shows the problem.
- Make sure you have installed Odin properly (using WarpIN). If you installed
  using a ZIP file, do not forget to run OdinInst.EXE after unpacking the ZIP
  file! 
- PE.EXE is the recommended way to run Windows applications; remove Win32K.SYS
  from your CONFIG.SYS
- Use a recent daily build. Bug reports with ancient (> 1 week old) builds are
  not very useful. The problem you report might no longer be present!
- Always send these bug reports to the odinusers mailing list; not directly to
  the developers (so others can respond if the problem is old or already
  fixed).
- Currently the only valid mailing list address is odinusers@yahoogroups.com.
  In order to send a bug report you have to be subscribed to this mailing
  list. 
- Go to http://groups.yahoo.com/groups/odinusers/join in order to subscribe
  (or use the URL object that OdinBug has created in your Odin folder.)

Sometimes the small part of the logfile isn't enough for us to determine where
the problem lies.

In that case, we'll ask you to mail us the entire file (ZIPped).
So please do not send big logfiles to the mailing list!


Generating useful logfiles:
===========================

Only those builds, that have "debug" in their name can generate logfiles in
order to show what a win32 application is doing, while it is running. The
logfile is inevitable to determine why certain applications don't run
correctly.

The logfile is the main source of bug information for OdinBug.

The name of the logfile follows a naming scheme:

         odin32_?.log, where ? is 0, 1, 2 etc.

The major disadvantage of logging is the overhead. Therefore it has been
disabled by default in all the "debug" builds.

You only get logfiles if you use a debug build and have 

         SET WIN32LOG_ENABLED=1

properly set. This turns on logging for all debug dlls.

However, this can result in huge logfiles. To reduce the size, use release
builds of dlls that are not relevant to the problem you're seeing. The general
rule is that usually only the logging information generated by GDI32, KERNEL32
and USER32 is important.

Use the release build of GDI32 if the problem you're seeing isn't related to
painting. (GDI32 generates a lot of logging information)

To disable logging again, you must clear this variable:

         SET WIN32LOG_ENABLED=


Useful tips:
============

Crashes are always easy to locate in logfiles (search for 'Exception
Information'), but improper behaviour isn't.

In the system menu (top left button of a window), there's a menu item called
'Put mark in debug log'. Selecting this item puts the line 'Mark requested by
user' in the log. 

This can be useful e.g. if a window is resized improperly after you click
on a button. To make it easy for us to locate the right log lines, you
should select the 'Put mark in debug log' menu item and then click on the
button that causes the problem.


Standard form of a bug report:
==============================

--------------------- Begin of Odin Bug Report ----------------------
  
Odin build information:
  
  Current Odin build:     (odin32bin-2001????-debug.wpi or .zip)
  Installation method:    (WarpIN or manually)
  Launching method:       (Win32K.SYS or PE.EXE)
  Last WarpIN install:    (date/time)
  Last OdinInst install:  (date/time)
  Odin "Windows" dir:     (search for "Windows  dir" in logfile!)
  Odin "System32" dir:    (search for "System32 dir" in logfile!)
  Evaluated Odin.INI:     (located in System32 directory)
  
General system information:
  
  OS/2 version:           (Warp 4, 4.5, Warp 3 not officially supported)
  OS/2 reports version:   (2.4, 2.45) kernel revision: (14.0xx)
  FixPack Level:          (15)
  Is xf86sup.sys loaded?  Yes/No
  Display driver:         (Scitech/Matrox/gradd)
  Video Chipset:          (Matrox/Nvidia TNT/Geforec/ATI Rage Pro)
  
Win32 program information:
  
  Odin logfile:           (odin32_?.log found in the application's dir)
  Windows executable:     (commandline of the program)
  Application name:       (name)
  Application version:    (version)
  Available from:         (URL if available)
  
Verbal problem description:

(what happened, in your own words, be as accurate as possible)

Exception information and stack dump:

(search for "[Exception" in the logfile!)

ODIN.INI information:

(located in x:\Odin\System32 directory)
---------------------- End of Odin Bug Report -----------------------