******************************************************************************
*
* COMPILE.TXT - Compilation of TLX 5.0
*
* Last updated: 17-01-95
*
* Copyright (c) 1991-95 Tarma Software Research. All rights reserved.
*
******************************************************************************


In general, you should turn to the appropriate directory for your compiler
and inspect the MAKEFILE in that directory. It will contain information
that will help you to compile TLX for your compiler. In addition, the TLX base
directory contains the following files with compiler-specific information:

	BORLAND.TXT	- Information for Borland C++ users


Environment variables
---------------------

	Before attempting to recompile TLX, you should set the following
	environment variables to point to your compiler's directories:

	    set INCLUDE=<path of your compiler's .h files>
	    set LIB=<path of your compiler's .lib files>

	It is probably easiest to do this as part of the AUTOEXEC.BAT,
	CONFIG.SYS, or	.login.rc files, as appropriate for your platform.
	For UNIX platforms with the Bourne or Korn shell, be sure to EXPORT
	the environment variables.


Debug and retail versions
-------------------------

	TLX can be compiled for debugging purposes (contains diagnostic code
	and symbolic debugging information) and as retail version. Check the
	MAKEFILE for instructions on how to build one or both versions.

	In order to use either the debug or the retail version of TLX in
	your own code, you should #define _TLXDBG if you want the TLX debug
	version, or leave it undefined if you want the retail version. This
	option is independent of the debugging options for your own code. In
	all, there are 4 combinations of debug/retail versions between TLX and
	your own code. The following table shows which preprocessor symbols to
	define in order to obtain a specific combination. If a symbol is not
	mentioned, you should leave it undefined.

			       Your code
		     |	 Debug		Retail
	      -------+----------------------------------
	TLX   Debug  | _TLXDBG		_TLXDBG, NDEBUG
	code  Retail |	(none)		NDEBUG

	The way to define preprocessor symbols from outside the source code
	depends on your compiler; usually, it will have a /D command line
	option and/or a 'Defines' setting in its IDE.

	Once you have chosen a particular compilation version, be sure to link
	your program to the correct TLX library. See below for details on the
	library naming scheme.


Memory models
-------------

	On platforms which support several memory models (DOS, Windows
	16-bit), TLX can be compiled for one or more models. Again, check the
	relevant MAKEFILE for information.


Library names
-------------

	Because of the various compilation options, the TLX library names
	encode their compilation mode, as follows:


    DOS
    ---
	TLXDm.LIB	- retail library; 'm' = memory model
	TLXDmD.LIB	- debug library; 'm' = memory model

    Windows 16-bit
    --------------
	TLXWm.LIB	- retail library; 'm' = memory model
	TLXWmD.LIB	- debug library; 'm' = memory model
	TLXWm.DLL	- dynalink library; 'm' = memory model
	TLXWmD.DLL	- debug dynalink library; 'm' = memory model
	TLXWmI.LIB	- import library for retail DLL; 'm' = memory model
	TLXWmDI.LIB	- import library for debug DLL; 'm' = memory model

    OS/2 2.x
    --------
	TLX2.LIB	- retail library
	TLX2D.LIB	- debug library
	TLX2.DLL	- dynalink library
	TLX2D.DLL	- debug dynalink library
	TLX2I.LIB	- import library for retail DLL
	TLX2DI.LIB	- import library for debug DLL

    Macintosh
    ---------
	Libraries for this platform are called 'TLX' and 'TLX Debug'. However,
	due to the way projects work on THINK and Symantec C++ compilers for
	the Macintosh, you'll have to include TLX components on a per-module
	basis in your own projects.


Link version check
------------------

	In order to reduce the chance that you compile your source code
	against one version of the TLX header files (say, debug) while
	linking to another (retail), we have introduced link-time checks
	in the library. These checks are fully automatic; you will only
	notice their presence if there is a compilation/linking mismatch.
	These mismatches show up as linker errors of the following form
	(the exact wording depends on your linker):

		'Undefined symbol: TLX::something()'

	where 'something' indicates the type of the mismatch. The following
	mismatches may occur:

	'Undefined symbol: TLX::V500rNNN()' (NNN = release number)

		You are using release NNN of the header files, while the
		compiled library is of a different release. Check your
		compiler's INCLUDE and LIB paths for consistency; if
		necessary, recompile the library.

	'Undefined symbol: TLX::Debug()'

		You have compiled your source code against the debug version
		of TLX (i.e. with _TLXDBG defined), while you are
		attempting to link with the retail version. To solve this
		problem, you must either stop defining _TLXDBG (and use the
		retail version), or link to the debug version of the compiled
		library.

	'Undefined symbol: TLX::Retail()'

		You have compiled your source code against the retail version
		of TLX (i.e. with _TLXDBG undefined), while you are
		attempting to link with the debug version. To solve this
		problem, you must either define _TLXDBG (and use the debug
		version), or link to the retail version of the compiled
		library.

	'Undefined symbol: TLX::DLL()'

		You have compiled your source code against the DLL version
		of TLX (i.e. with _TLXDLL defined), while you are
		attempting to link with the static version. To solve this
		problem, you must either stop defining _TLXDLL (and use the
		static version), or link to the import library of the
		DLL version of the compiled library.

	'Undefined symbol: TLX::Static()'

		You have compiled your source code against the static version
		of TLX (i.e. with _TLXDLL undefined), while you are
		attempting to link with the import library of the DLL version.
		To solve this problem, you must either define _TLXDLL (and use
		the DLL version), or link to the static version of the
		compiled library.

	The link checks are implemented by inserting a small static object in
	each module that #includes TLX.H. The overhead of this is very small
	(about 2-4 bytes data space per module, and a trivial amount of code
	during startup), but if you cannot tolerate this and are absolutely
	certain that you link to the correct version of the TLX libraries
	(e.g. in the release build for an application), you may forego the
	check and its hidden objects by defining the preprocessor symbol
	_NO_LINK_CHECK prior to #including TLX.H in any of your modules.

	NOTE:	If you use the precompiled headers option of your compiler,
		the compiler may warn you that it can't create a precompiled
		header if the precompiled portion includes TLX.H (which
		contains initialized static data). If you really want to use
		precompiled headers and they should encompass TLX.H, you
		may define the _NO_LINK_CHECK symbol as explained above.
		This disables the initialized data object that is used for
		link checks (and therefore the link check itself), after
		which precompilation should pose no further problems.


Library build check
-------------------

	As part of the library build process, a small executable file is
	compiled and linked, then run immediately after the build of a
	library version is completed. This executable does nothing more than
	to print a description of the library on the standard output; its
	purpose is to allow you to verify that the build did indeed succeed,
	and to inform you of the exact version and release of the library.

	The executable files have the same filename as the corresponding
	library (i.e. TLXxxx), but with a .EXE extension instead of .LIB.
