DOCUMENT: TI, public
DURATION: Indefinite

TITLE:    How to step through the source code for OWL when
          when debugging an application built with BC++ 5.0

PRODUCT:  Borland C++
VERSION:  5.0
AUTHOR:   George Cross
DATE:     May 6 1996
KEYWORDS: BC50, debugging, debug, OWL, BIDS, CLASSLIB, stepping,
          diagnostic, OWL source, BIDS source, CLASSLIB source,
          source code, building OWL, building BIDS

================================================================

When debugging an application created using OWL, it is often
helpful to step through the OWL source code.  Here are two
ways you can do this.

1. The Quick and Easy Way
-------------------------
The source for OWL is on the CD for Borland C++ 5.0 in the
directory, BC5\SOURCE\OWL.  If you already know particular
source files that you want to step through, you can do the
following,

1. Link in with your project, those OWL source files through
   which you want to step.  In the IDE, select View | Project
   and add the 

2. Link to the static versions of the OWL, BIDS and runtime
   libraries. See the below for the names of these.

3. Compile your project with Out-of-line inline functions (-vi).


2.  Using the Debug Version of OWL
----------------------------------
Using the debug version of OWL will enable you to step through
all source files for OWL when debugging your application.  See
the table below for the names of the files of the debug version
of OWL.

1. Build the debug versions of OWL and BIDS as follows for the
   32-bit DLL versions,
   OWL:  make MODEL=d -DWIN32 -DDEBUG -DDIAGS
   BIDS: make -r -DWIN32 -DDLL -DDEBUG -DDIAGS

   These commands must be executed from the directories,
   bc5\source\owl, and, bc5\source\classlib respectively.

   This will put the following files in your bc5\bin directory,
   OWL50DF.DLL              BIDS50DF.DLL
   OWL50DF.TDS              BIDS50F.TDS
   OWL50DF.MAP              BIDS50DF.MAP

   This will also put the following files in your bc5\lib
   directory,
   OWLDWFI.LIB              BIDSDFI.LIB

   The .TDS files are the most important.  They contain the
   symbol tables used by the debugger.

   **** NOTE **** There are .TDS files on the CD already in
   bc5\lib\cg.  Don't substitute them for rebuilding OWL
   as outlined here.  Rebuild OWL if you would like to debug
   successfully.

   The files OWL50DF.DLL, OWLDWFI.LIB, BIDS50DF.DLL and
   BIDSDFI.LIB are already on the CD for BC++ 5.0.  These
   contain diagnostic information, but need to be rebuilt
   in order to get the debug information contained in .TDS files.
   Diagnostics are portions of code which provide run time state
   information of your application via the macros PRECONDITION,
   TRACE, WARN, CHECK and their extended versions.  Please see
   the Borland C++ Class Libraries Reference, Class Diagnostic
   Macros for further information.

2. Check Diagnostic in the Target Expert for your project.

3. Indicate to the debugger which are the directories for the
   OWL source and the BIDS source.  This will normally be,
   bc5\source\owl;bc5\source\classlib


Library Version Information
---------------------------
The OWL and BIDS libraries are distinguished by the following
characters appearing in their names,

   OWL  Object Windows Language; a class library which
        encapsulates the Windows API.
   BIDS Borland International Data Structures; a template
        based container class library.

   .DLL dynamic link library
   .LIB static library or import library
   .TDS file containing symbolic information used by the debugger
   .MAP text file depicting the memory mapping of the target

   S   small memory model
   M   medium memory model
   C   compact memory model
   L   large memory model
   F   flat memory model
   D   diagnostic/debug information included; a version of OWL
       or BIDS with this in its name is used when building a
       target which will use the diagnostic versions of OWL
       and BIDS.
   I   import library; a version of OWL or BIDS libraries
       with this in its name is used when building a target
       which will link to the dynamic versions of OWL and BIDS.
   U   user DLL; a version of OWL or BIDS libraries with this
       in its name is used to build a project whose target is a
       DLL
   T   multithreaded version; a version of OWL or BIDS libraries
       with this in its name is used to build 32-bit multithreaded
       targets.

The documentation is thorough on OWL library names.  Please see
the ObjectWindows Reference Guide, Overview of ObjectWindows,
ObjectWindows Libraries.

The 32-bit BIDS library files are,

 BIDS50DF.DLL   debug/diagnostic, flat memory model, dynamic version
 BIDS50F.DLL    non-debug/non-diagnostic, flat memory model
                dynamic version
 BIDS50T.DLL    non-debug/non-diagnostic, flat memory model,
                multithreaded, dynamic version
 BIDSDF.LIB     debug/diagnostic, flat memory model, static
                version
 BIDSF.LIB      non-debug/non-diagnostic, flat memory model
                static version
 BIDSFI.LIB     non-debug/non-diagnostic, flat memory model,
                import library
 BIDSDFI.LIB    debug/diagnostic, flat memory model, import
                library
 BIDSDT.LIB     debug/diagnostic, flat memory model, multithreaded
                static version
 BIDST.LIB      non-debug/non-diagnostic, flat memory model,
                multithreaded static version
 BIDSDTI.LIB    debug/diagnostic, flat memory model,
                multithreaded, import library
 BIDSTI.LIB     non-debug/non-diagnostic, flat memory model,
                multithreaded import library



Bibliography
------------
ObjectWindows Reference Guide, Overview of ObjectWindows, Object
Windows Libraries.

Borland C++ Class Libraries Reference, Class Diagnostic Macros

Borland C++ User's Guide, Compiling and Linking from the Command
Line, Linking Libraries.