source: trunk/doc/ReportingBugs.txt@ 5087

/* $Id: ReportingBugs.txt,v 1.6 2001-01-09 20:54:31 sandervl Exp $ */

Reporting Odin bugs
-------------------

To make our job easier when dealing with reports of failures to run 
certain apps, there's a standard form to report bug. (see below)

Some remarks:
        - unless the debug version of Odin works ok, always try the debug build 
          with the application
        - make sure you have installed Odin properly (WarpIN)
        - pe.exe is the recommended way to run windows applications; remove
          win32k from your config.sys (note that WarpIN does *not* install win32k)
        - 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 mailinglist; not directly 
          to the developers.
          (so others can respond if the problem is old or already fixed)
          (odinusers@egroups.com; go to www.egroups.com to subscribe)

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 mailinglist!

Generating useful logfiles
--------------------------
To enable logging in the debug build, add the following environment variable:
        SET WIN32LOG_ENABLED=1

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)

Logging.txt contains information on how to selectively enable/disable logging.
Doing this requires some knowledge about the layout of the Odin source tree 
and what each source file does.


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 i.e. 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.


------------ODIN BUGREPORT------------------
Odin build:             date & debug/release
Installed Odin:         manually/WarpIN
Method of launching
win32 apps:             win32k/pe.exe
                        (if pe.exe is used, win32k must not be loaded at all!)
OS/2 version:           OS/2 Warp 4 or OS/2 Warp Server for e-Business 
                        (Warp 3 not officially supported)
Fixpack level:          

Windows  dir:           (search for 'Windows  dir' in odin32_0.log)
System32 dir:           (search for 'System32 dir' in odin32_0.log)

Windows application:    name, version + url (if it can be downloaded somewhere)
Problem description:    Try to give an accurate desription so we can reproduce it on our systems

Log file:               Search for 'stack dump' or 'Exception Information' in odin32_0.log and include 
                        the exception information + last few lines preceding it.
                        i.e:
                        t1: GDI32: SaveDC
                        t1: GDI32: StretchDIBits 1000245 to (0,0) (740,61) from (0,0) (740,61), 1d3001c 18817f0 0 cc0020
                        t1: ---[Exception Information]------------
                        t1:    Access Violation (hardware generated,portable,fatal)
                        t1:    Read Access at address 01d2fe4dh
                        t1:    Exception Address = 1d195cdc 
                        t1: <PMWINX> (#6197), obj #0:00065cdc
                        t1:    Thread:  Ordinal TID: 191, TID: 1, Priority: 0200h
                        t1:    Process: PID: 135, Parent: 38, Status: 16
                        t1:    SS:ESP=0053:00130cb0 EFLAGS=00012216
                               CS:EIP=005b:1d195cdc EBP   =000002e4
                        t1:    EAX=fffffb4d EBX=0000b900 ESI=01d2fe4d
                               ECX=000000b9 EDX=000002e4 EDI=01d4b61c
                        t1:    DS=0053     ES=00000053       FS=150b     GS=0000
                        t1: ---[End Of Exception Information]-----

------------ODIN BUGREPORT------------------