windows-xp/Source/XPSP1/NT/sdktools/debuggers/redist/docs/32/relnotes.txt

                  Microsoft(R) Debugging Tools for Windows(R)
                         Version 3.0 BETA Release Notes
                                  April 2001

-----------------------------------------------------------------------------

Contents

    Overview
    What's New
    Known Issues
    Programs
    Debugger Extensions
    Software Development Samples
    Documentation
    Redistributables
    More Information
    Feedback

-----------------------------------------------------------------------------

Overview

Debugging Tools for Windows(R) contains tools to analyze and debug OS and
application failures. 

The kernel debugger is KD.exe.  It can be installed and run on Windows NT 4.0,
Windows 2000 and Windows Whistler.  KD.exe can debug Windows NT 4.0,
Windows 2000 and Windows Whistler.

The user-mode debugger is CDB.exe.  It can be installed and used on
Windows NT 4.0, Windows 2000 and Windows Whistler.

WinDbg.exe is the GUI mode version of the debugger.  It supports both user-mode
and kernel-mode debugging.  It can be installed and run on Windows NT 4.0,
Windows 2000 and Windows Whistler.  WinDbg can debug Windows NT 4.0,
Windows 2000 and Windows Whistler.


-----------------------------------------------------------------------------

What's New

This Beta of Debugging Tools for Windows contains many bug fixes and new
enhancements. The debuggers are stable and more reliable than Version 2.0.23.0
and we recommend that you upgrade your debuggers to this new version.

It is also a requirement to use this latest drop if you wish to debug
POST BETA 2 versions of Windows XP; older versions (including 2.0.23) will
not work on the latest Windows XP build.

Here's a list of the enhancements to WinDBG 3.0:

    * Add ambiguous symbol detection (print a warning if a symbol name
      being evaluated is defined multiple times)
    * Better wildcard support in the 'x' command
    * Allow regsiters in the watch window (prefix with '@')
    * Many fixes for windows XP debugger extensions.
    * Modify WinDbg to save workspaces under HKEY_CURRENT_USER
    * Add context menus to the calls, CPU and watch/locals windows in WinDbg
    * Add a scratch pad window to WinDbg
    * Enhace !pool to print more infomration about a block (if it exists)
    * move extensions to winxp directory (instead of w2001)
    * Automatically expand .dmp files out of .cab
    * And lots of bug fixes!

    Windows XP specific enhacements (requires the new debugger AND windows XP)
    * Faster stepping
    * .kdfiles to transfer files over the debugger port


-----------------------------------------------------------------------------

Known Issues


VC4 \ NT 4 DDK support:
-----------------------
The NT 4 DKK shipped with VC4 compatible tools.

This version of the debuggers does not support local variables generated by 
this default build-environment.  The debuggers only supports local variables 
if a .pdb file is generated by the compiler and linker.

To enable .pdb files in the NT 4 DDK, set the following environment variable.

    set USE_PDB=1

The next version of Debugging Tools for Windows will fix this limitation.


Other issues:
-------------

If you need to find source that was compiled at a different location than
the current location to the source, use the ".srcpath" command. 

If you are using Windows NT 4.0, you need to have Microsoft Internet Explorer
5.0 or later installed for all of the features to work correctly.


-----------------------------------------------------------------------------

Programs

This distribution includes the following debuggers:

    KD        - Command-line kernel debugger
    NTSD      - Command-line user-mode debugger
    CDB       - Command-line user-mode debugger (variant of NTSD)
    WinDbg    - GUI kernel debugger

I386KD is also provided in the package to support backwards compatibility. 
It has the same code-base as KD.

There are several debugger-related tools included with the package.  They
are divided into subcategories under Tools in the custom menu during install.
These subcategories include 1) Helpful Tools and 2) AutodumpPlus.  Both of
them are installed by default.

The Helpful Tools option includes these debugger-related tools:

    gflags    - Global Flags Editor
    breakin   - Utility to force a breakin in another process being debugged
    remote    - Remote Command Line
    kill      - Task Killing Utility
    list      - File List Utility
    logviewer - Display API logs created with the .logext extension from the debugger 
    symstore  - Creates a symbol server for automatic symbol lookup
    tlist     - Task List Viewer

The following tools have been incorporated into KD.exe and WinDbg.exe.  They
are also provided with Helpful Tools as small stubs that point you to use the 
debugger.

    dumpchk   - Dump Checking Utility
    dumpexam  - Dump Examining Utility

AutodumpPlus, is a console based VBScript usefull for troubleshooting hangs 
and crashes.  AutodumpPlus scripts the CDB debugger to produce memory dumps 
and/or scripted log files containing debug output from one or more processes.  
This information is placed in uniquely named directories 
(i.e. C:\temp\Crash_Mode__Date_01-22-2001__Time_09-41-08AM) on the local file 
system or a remote network share, and each file is named uniquely 
(i.e. PID-1708__Inetinfo.exe__Date_01-22-2001__Time_09-41-08AM.log) to avoid 
overwriting older files with newer ones. 


-----------------------------------------------------------------------------

Debugger Extensions

Debugger Extensions are DLLs which WinDbg, CDB, NTSD, and KD can use to provide
additional debugger commands.  The Whistler debugger extensions are in the
winxp subdirectory and include:

    exts.dll
    KDexts.dll

The extensions that work for Windows NT 4.0, Windows 2000, and Whistler are in
a winext subdirectory and include:

    uext.dll
    kext.dll
    ext.dll
    logexts.dll

The debugger extension DLLs for Windows NT 4.0 and Windows 2000 are operating 
system version, debug/retail specific.  However, these extensions should
properly support all service packs based on that build.  Multiple versions of
each DLL are included, to provide the necessary files for each variant. All DLLs
are provided in both debug and retail versions.  The debug and retail versions 
of these DLLs for Windows NT 4.0 and Windows 2000 are installed 
into four subdirectories, under the target subdirectory:

    nt4chk
    nt4fre
    w2kchk
    w2kfre
    
The debugger has awareness of these subdirectories, and will not be able
to find them if these subdirectories are renamed or moved.

If a custom extension DLL is to be used, it should be placed in its own
directory.  The user can then set the debugger extension path variable so the
debugger can find the extension.  Debugger extension can also be loaded in
the debugger using fully qualified path names.

For Windows 2000 and Whistler, Ntsdexts.dll ships with the operating system, in
%systemroot%\system32, and is not included in this distribution.

All of the debuggers search for debugger extension DLLs in the 
following places:

    %NT_DEBUGGER_EXTENSION_PATH%;
    %DIRECTORY_FROM_WHICH_KDNTSD_IS_LAUNCHED%\WINEXT;
    %DIRECTORY_FROM_WHICH_KDNTSD_IS_LAUNCHED%\%TARGET_PLATFORM%;
    %DIRECTORY_FROM_WHICH_KDNTSD_IS_LAUNCHED%;
    %Path% 
       
where TARGET_PLATFORM is [nt4fre| nt4chk| w2kfre| w2kchk| winxp].

Use the "version" command in KD/NTSD to see what the extension search 
path, to note where extension DLLs are loaded from.  


-----------------------------------------------------------------------------

Software Development Samples


Header files, libs and samples for debugger extensions samples are provided
in this package.  They are not installed by default.  The "SDK" component of
the package must be selected during the install to get the samples installed.

The samples will compile by using the latest Windows Whistler DDK or SDK.
The header files and libs in this package should replace any existing version
of the header files or libs that are shipped with the DDK or SDK.

Using the samples and headers with the Windows 2000 SDK or DDK will cause
compilation errors.


-----------------------------------------------------------------------------

Documentation

For documentation on how to use these debuggers and related tools, see the
help file debugger.chm that is included with the tools. This documentation
has been improved and expanded since the last release.

You need to have Internet Explorer 5.0 or greater installed in order to use
the documentation properly.

-----------------------------------------------------------------------------

Redistributables

Please read the license agreement during setup for legal information regarding
redistributable files.  If this is a retail release, the license agreement 
mentions that redist.txt gives a list of the files that are redistributable.  
This is a Beta release and none of the files in this package are redistributable.

-----------------------------------------------------------------------------

More Information

For more information on debugging, see the Debugging Tools for Windows
web page, <http://www.microsoft.com/ddk/debugging/>.

We encourage people to get the new debugger off the web "often", as
we will do lots of fixes, while keeping compatibility with NT 4.0 and
Windows 2000.

-----------------------------------------------------------------------------

Feedback

We are interested in your feedback on the tools.  Please mail suggestions or 
bug reports to [email protected].  This is not a support alias, but your 
feedback will help us to plan future changes for these tools and will make 
them more useful to you in the future.

-----------------------------------------------------------------------------