INTRODUCTION
------------
This repository manages wdtp (Wine debugger testing package), a set of
tools to test WineDbg.

It consists of:
- a program to drive WineDbg by passing commands to it, and checking
  the output of those commands (wdbgtest),
- a set of unit tests. Each test is made of a:
  + a simple C program
  + a script to drive the commands to be sent to WineDbg by wdbgtest,
    and their expected output.
  Those simple C programs are run under WineDbg.
  In current configuration, all tests are compiled into a single
  executable, each test being chosen from a command line
  parameter. This executable is called wdtp.
  By convention, a simple test (<test>)'s C file is named
  wdtp_<test>.c and the script file <test>.wdtp.
- actually, the wtdp executable is compiled several times, using
  different ways. The final executable is called a flavor of
  wdtp. Each flavor corresponds to a unique set of options to cover
  different elements, among which:
  + compiler: gcc, msvc, MingW...
  + compiler version (if several chains are installed)
  + debug format: stabs, Dwarf2, Codeview, PDB...
  + compiler options: mostly optimisations
  + linker option: debug info stripping, prelinking

   +-------------+        +---------+       +--------------------------+
   |   wdbgtest  | <====> | WineDbg | ----> | wdtp_<flavor>.exe <test> |
   +-------------+        +---------+       +--------------------------+
   | <test>.wdtp |                          |     <test>.c program     |
   +-------------+                          +--------------------------+

Currently, the flavor name is made of:
- name of compiler (gcc, mingw32...), followed by underscore
- if version management is enabled for this compiler, a version
  identifier, followed by an underscore
- a condensed string made out of the options (generally made out of
  debug format and compiler options), followed by an underscore
- the default executable extension (.exe for PEs, .exe.so for Wine modules)

For now, the test suite must be compiled and run against a regular
Wine compilation tree (not against an installed Wine setup).

The WDTP file describes the syntax of .wdtp files.

LICENSING
---------
This package is provided under the LGPL license (see LICENSE file).

CONFIGURATION & BUILDING
------------------------
First, from the directory where you installed the package, run:
	autoconf

Then, if you compile Wine in the Wine source tree, then configuration
is done with:
	./configure --with-wine=<wine_src_dir>
where <wine_src_dir> is the path to the top of your Wine source tree.

Or, if you compile Wine outside the Wine source tree, then
configuration is done with:
	./configure --with-wine=<wine_src_dir> \
		--with-wine-output=<wine_dst_dir>
where <wine_src_dir> is the path to the top of your Wine source tree,
and <wine_dst_dir> is the path to the top of your Wine object tree.

If you have several gcc versions installed on your computer, and you
want to test them all, use
	./configure --enable-gcc-auto
Otherwise, the default gcc version will be used.

If you want to enable mingw32 cross-compilation, use the
--with-mingw32 option to give the name of the version of the
cross-compiler you want to use. For example:
	./configure --with-wine=<wine_src_dir> \
		--with-mingw32=i586-pc-mingw32-gcc

If you want to enable MS Visual C++ compilation (the compiler will be
run with Wine), use the --with-msvc option to give the top directory
where MS Visual C++ is. For example:
	./configure --with-msvc=/home/winapps/Microsoft\ Visual\ C++\ Toolkit\ 2003

In all cases, finalize the installation by building the lot:
	make depend && make

RUNNING & TESTING
-----------------
As already mentionned, wdtp is compiled with different "flavors". We
currently support:
+----------------+----------+------+-------------+
|    flavor      | compiler |debug |optimization |
+----------------+----------+------+-------------+
|gcc_stabspO0    |   gcc    |stabs+|none         |
|gcc_dwarfO0     |   gcc    |dwarf2|none         |
|gcc_dwarfO2     |   gcc    |dwarf2|regular level|
|mingw32_stabspO0|cc mingw32|stabs+|none         |
|mingw32_dwarfO0 |cc mingw32|dwarf2|none         |
|mingw32_dwarfO2 |cc mingw32|dwarf2|regular level|
|msvc_pdbOd      |   msvc   | PDB  |none         |
+----------------+----------+------+-------------+
(cc means cross-compilation)

To test one flavor, use (for example):
	make test_gcc_stabspO0
It will run all available tests with the defined flavor.
Note: if you have enabled versionning for the compiler, you must use
	make test_gcc_45_stabspO0
to test a given version of the compiler (otherwise, it will test the
flavor against all known compiler version).

To run all the tests for all flavors, do:
	make test_all

To run all the tests for a given compiler, do:
	make test_gcc
Note: if you have enabled versionning for a compiler, it will run all
tests against all versions. Use
	make test_gcc_45
to focus the test on a given compiler version.

All flavors are not equally supported:
- the gcc_dwarfO0 is ok
- the {gcc,mingw32}_stabsp0 can provide errors in minidump.wdtp and
  stack.wdtp (likely in main() and below but depends of your gcc version)
- {gcc,mingw32}_dwarfO2 produces a couple of errors (execute:
  mishandling of instruction reordering, which mixes insn from different lines)
- msvc_pdbOd also provides some errors in type.wdtp (mainly due to
  INT4 definition)

DEPENDENCIES
------------
A full blown Wine tree, with all the tools needed to compile it (gcc,
make, flex, bison).

On top of that:
- autoconf (mandatory)
- mingw32 for cross-compilation (optional)
- Microsoft Visual C++ for cross-compilation (optional)

KNOWN ISSUES
------------
Enhancements:
- Enhance the flavor scheme (and autoconf macros) to support several
  versions of the same compiler.
- The conditions in wdtp are hard to maintain (ie no default is
  expressed), and don't scale well when adding new debug formats. So
  we'd better get rid of them (in that form) and replace them by
  values with conditions (ie extend, when expecting value 'val' to
  rather replace val by [3;pdb=1;stabs=2] which will enforce a default
  value.

Known bugs:
- Setting a breakpoint on a line number which doesn't exist in debug
  info is not supported
- Getting a backtrace on an address without any known function to the
  debugger (or line number info) isn't supported
- A backtrace where '(nil)' is used isn't properly supported
- Dereference out of array's bound isn't properly managed (message is:
    "Dereference failed (not a pointer, or out of array bounds)"

Things to do:
- why using the EVAL command for 'set' (could also get rid of mv_null
  in EVAL)

TEST ENHANCEMENTS
-----------------
Display:
- check for other functions (only display information from a given
  function or a given function & stack frame ??)
- enable / disable of display items
Expr:
- better test the x and print commands (especially modifiers /x...)
- casts (integers, pointers)
- fix the sll and ull tests
Minidump:
- recheck when global variables are properly managed/saved in minidump
  files (could be a winedbg option anyway)
Stack:
- extend frame tests with register variables (but how to create them
  in a portable manner ?)
- test passing structures on the stack (it's ABI dependent)
- test returning structures from a function (it's ABI dependent)
Start
- should also test that winedbg starts upon exception
- first chance & second chance exceptions should be tested
- winedbg invocation with a set of commands passed on the command line
- winedbg invocation with a file as commands
- winedbg invocation in automatic mode
- winedbg invocation in gdb mode
XPoint:
- enabling / disabling bp
- use of cont N
- frame scoping for conditional bp
- bp printing
- get rid of wdt_evaluate call (or tweak it so that we get the
  returned value from the evaluation)
- late bp (rechecked when a DLL is loaded)
New test files:
- add a huge file to test a bit about performance (perhaps requires
  also new commands in winedbg to test time/memory usage)

--------------
Local variables:
mode: auto-fill
mode: font-lock
End: