Topspeed_JPI/TS-V3/DOC/TECHKIT.DOC

TopSpeed Professional TechKit          Release notes version 3.02
=============================          ==========================

Known problems in this release:
-------------------------------

1: The post-mortem debugger does not correctly show the value
   of local variables.

2: The profiler will only operate in line number mode for one
   module at a time.


Resource files for Microsoft Windows version 3.00
-------------------------------------------------

The TopSpeed TechKit now includes a resource compiler, TSRC.EXE,
which, in conjunction with the TopSpeed Linker, allows resources
to be added to executable programs for use under Microsoft
Windows version 3 without requiring the use of the Microsoft
Windows SDK. The TopSpeed resource compiler does not work in
the same way as the Microsoft resource compiler RC.EXE, although
it uses the same file formats.

The TopSpeed resource compiler processes a resource script file
(with .RC extension) and produces a compiled resource file (with
.RES extension) of the same name. This file can then be added to
the link list (for example, using #pragma link(myfile.res)),
and the TopSpeed Linker will automatically add the resources
to the end of the executable file.

The configuration file TSPRJ.TXT contains a #declare_compiler
command for the file extension .RC, so that a resource file
can be added to an project simply by including the statement

  #compile resfile.rc

in the project file. The project system will then build the
.RES file if neccessary, then add it to the link list
automatically.


Microsoft Windows Example Programs
----------------------------------

You will find the following Windows examples programs in the
examples directory:

  ?WDEMO     A simple windows program that displays text
             in a window. ? is P, M, C, or D depending on
             the source language.

  ?WDEMO_D   The same program, but using a Windows DLL
             (WDLL*.DLL, depending on the language).
             Before making these programs, you must
             make the project for the corresponding
             DLL.

While not useful or interesting in themselves, these programs
can be used as "skeletons" for more complex windows progams,
and to gain an insight into how Windows programs and DLLs
are put together.


TopSpeed Executable File Compression Utility TSCRUNCH.EXE
---------------------------------------------------------

The TSCRUNCH program is is a utility to compress .EXE files to
the minimum possible size under DOS. The exe file is compressed
using LWZ compression techniques and then has a small loader/
expander added to the startup code. This form of compression
can reduce the exe file by up to 50% or more of its original
size.

To use TSCRUNCH just type

   TSCRUNCH exename

e.g.

   tscrunch myprog

This will create a new exe file (providing the compression is
worthwhile) and create a backup of the uncompressed file with
the extension '.EXB'.

It should be noted that compression of an exe file will cause
the loading time to greatly increase, so it is best used on EXE
files that are either infrequently used or where the loading
time is not significant.

N.B. TSCRUNCH cannot be used for Overlay or Dynalink model,
     programs, nor for Windows or OS/2 programs.
     TSCRUNCH cannot be used for files containing VID or
     CodeView debug information.


TSMKHELP - TopSpeed Help File Compiler
--------------------------------------

You can use TSMKHELP to make your own help files for use within
the TopSpeed environment. Help files are compressed files with
the extension .HLP and are generated from specially formatted
text files (with the extension .HTX). To run tsmkhelp just type

  tsmkhelp <helpname>

and <helpname>.HTX will be read and <helpname>.HLP generated.

The file TSMAIN.HTX is supplied as an example HTX file which
allows you to re-make the 'root' TopSpeed help file. The format
the HTX file is described in the supplied file TSMKHELP.DOC.


TopSpeed Object file Disassembler TSDA
--------------------------------------

A new feature has been added to the TopSpeed Disassembler, so
that if an object file contains line-number information, the
disassembler will insert the lines from the source file into
the output, making it much easier to determine what code has
been produced for which source line.

In order to produce an object file that contains source-line
information, the pragma debug(line_num=>on) or the command-line
option /b must be specified when the object file is compiled.
In addition, the object file must be compiled with either
minimum or full debug information, using the pragma
debug(vid=>min) or debug(vid=>full), or using the command-line
option /v1 or /v2.

The disassembler attempts to produce a result that can
be re-assembled. However, there is a small problem with forward
references to non-public labels, which can be resolved by
declaring the symbol as extrn/public, or by re-arranging the
assembler text. Disabling smart linking when compiling may give
a clearer result and fewer forward reference problems.

If you are disassembling object files for the purposes of
comparing the quality of generated code, it is worth noting
that the code generated when full debug is specified is
considerably less eficient, as values must be kept in memory
rather than in registers to ensure that vid can read and/or
modify them. When minimum debug is specified, this does not
apply and the code generated is close to the quality of
code generated without debug information. Certain optimizations
concerning re-ordering of jumps are not performed when
even minimum vid is specified, as these would obscure the
correlation between machine code and source-code lines to the
point where vid could not operate. In order to generate optimal
code, debug(vid=>off) must be specified.


Using Microsoft's windows.h
---------------------------

If you use Microsoft's version of the windows header file,
windows.h, the declaration of pLocalHeap should be made an
extern declaration, otherwise duplicate public warnings may
be produced. (Such warnings can be safely ignored in this
instance.)