home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tlx501.zip / DOC / COMPILE.TXT < prev    next >
Text File  |  1995-03-07  |  8KB  |  203 lines
  1. ******************************************************************************
  2. *
  3. * COMPILE.TXT - Compilation of TLX 5.0
  4. *
  5. * Last updated: 17-01-95
  6. *
  7. * Copyright (c) 1991-95 Tarma Software Research. All rights reserved.
  8. *
  9. ******************************************************************************
  10.  
  11.  
  12. In general, you should turn to the appropriate directory for your compiler
  13. and inspect the MAKEFILE in that directory. It will contain information
  14. that will help you to compile TLX for your compiler. In addition, the TLX base
  15. directory contains the following files with compiler-specific information:
  16.  
  17.     BORLAND.TXT    - Information for Borland C++ users
  18.  
  19.  
  20. Environment variables
  21. ---------------------
  22.  
  23.     Before attempting to recompile TLX, you should set the following
  24.     environment variables to point to your compiler's directories:
  25.  
  26.         set INCLUDE=<path of your compiler's .h files>
  27.         set LIB=<path of your compiler's .lib files>
  28.  
  29.     It is probably easiest to do this as part of the AUTOEXEC.BAT,
  30.     CONFIG.SYS, or    .login.rc files, as appropriate for your platform.
  31.     For UNIX platforms with the Bourne or Korn shell, be sure to EXPORT
  32.     the environment variables.
  33.  
  34.  
  35. Debug and retail versions
  36. -------------------------
  37.  
  38.     TLX can be compiled for debugging purposes (contains diagnostic code
  39.     and symbolic debugging information) and as retail version. Check the
  40.     MAKEFILE for instructions on how to build one or both versions.
  41.  
  42.     In order to use either the debug or the retail version of TLX in
  43.     your own code, you should #define _TLXDBG if you want the TLX debug
  44.     version, or leave it undefined if you want the retail version. This
  45.     option is independent of the debugging options for your own code. In
  46.     all, there are 4 combinations of debug/retail versions between TLX and
  47.     your own code. The following table shows which preprocessor symbols to
  48.     define in order to obtain a specific combination. If a symbol is not
  49.     mentioned, you should leave it undefined.
  50.  
  51.                    Your code
  52.              |     Debug        Retail
  53.           -------+----------------------------------
  54.     TLX   Debug  | _TLXDBG        _TLXDBG, NDEBUG
  55.     code  Retail |    (none)        NDEBUG
  56.  
  57.     The way to define preprocessor symbols from outside the source code
  58.     depends on your compiler; usually, it will have a /D command line
  59.     option and/or a 'Defines' setting in its IDE.
  60.  
  61.     Once you have chosen a particular compilation version, be sure to link
  62.     your program to the correct TLX library. See below for details on the
  63.     library naming scheme.
  64.  
  65.  
  66. Memory models
  67. -------------
  68.  
  69.     On platforms which support several memory models (DOS, Windows
  70.     16-bit), TLX can be compiled for one or more models. Again, check the
  71.     relevant MAKEFILE for information.
  72.  
  73.  
  74. Library names
  75. -------------
  76.  
  77.     Because of the various compilation options, the TLX library names
  78.     encode their compilation mode, as follows:
  79.  
  80.  
  81.     DOS
  82.     ---
  83.     TLXDm.LIB    - retail library; 'm' = memory model
  84.     TLXDmD.LIB    - debug library; 'm' = memory model
  85.  
  86.     Windows 16-bit
  87.     --------------
  88.     TLXWm.LIB    - retail library; 'm' = memory model
  89.     TLXWmD.LIB    - debug library; 'm' = memory model
  90.     TLXWm.DLL    - dynalink library; 'm' = memory model
  91.     TLXWmD.DLL    - debug dynalink library; 'm' = memory model
  92.     TLXWmI.LIB    - import library for retail DLL; 'm' = memory model
  93.     TLXWmDI.LIB    - import library for debug DLL; 'm' = memory model
  94.  
  95.     OS/2 2.x
  96.     --------
  97.     TLX2.LIB    - retail library
  98.     TLX2D.LIB    - debug library
  99.     TLX2.DLL    - dynalink library
  100.     TLX2D.DLL    - debug dynalink library
  101.     TLX2I.LIB    - import library for retail DLL
  102.     TLX2DI.LIB    - import library for debug DLL
  103.  
  104.     Macintosh
  105.     ---------
  106.     Libraries for this platform are called 'TLX' and 'TLX Debug'. However,
  107.     due to the way projects work on THINK and Symantec C++ compilers for
  108.     the Macintosh, you'll have to include TLX components on a per-module
  109.     basis in your own projects.
  110.  
  111.  
  112. Link version check
  113. ------------------
  114.  
  115.     In order to reduce the chance that you compile your source code
  116.     against one version of the TLX header files (say, debug) while
  117.     linking to another (retail), we have introduced link-time checks
  118.     in the library. These checks are fully automatic; you will only
  119.     notice their presence if there is a compilation/linking mismatch.
  120.     These mismatches show up as linker errors of the following form
  121.     (the exact wording depends on your linker):
  122.  
  123.         'Undefined symbol: TLX::something()'
  124.  
  125.     where 'something' indicates the type of the mismatch. The following
  126.     mismatches may occur:
  127.  
  128.     'Undefined symbol: TLX::V500rNNN()' (NNN = release number)
  129.  
  130.         You are using release NNN of the header files, while the
  131.         compiled library is of a different release. Check your
  132.         compiler's INCLUDE and LIB paths for consistency; if
  133.         necessary, recompile the library.
  134.  
  135.     'Undefined symbol: TLX::Debug()'
  136.  
  137.         You have compiled your source code against the debug version
  138.         of TLX (i.e. with _TLXDBG defined), while you are
  139.         attempting to link with the retail version. To solve this
  140.         problem, you must either stop defining _TLXDBG (and use the
  141.         retail version), or link to the debug version of the compiled
  142.         library.
  143.  
  144.     'Undefined symbol: TLX::Retail()'
  145.  
  146.         You have compiled your source code against the retail version
  147.         of TLX (i.e. with _TLXDBG undefined), while you are
  148.         attempting to link with the debug version. To solve this
  149.         problem, you must either define _TLXDBG (and use the debug
  150.         version), or link to the retail version of the compiled
  151.         library.
  152.  
  153.     'Undefined symbol: TLX::DLL()'
  154.  
  155.         You have compiled your source code against the DLL version
  156.         of TLX (i.e. with _TLXDLL defined), while you are
  157.         attempting to link with the static version. To solve this
  158.         problem, you must either stop defining _TLXDLL (and use the
  159.         static version), or link to the import library of the
  160.         DLL version of the compiled library.
  161.  
  162.     'Undefined symbol: TLX::Static()'
  163.  
  164.         You have compiled your source code against the static version
  165.         of TLX (i.e. with _TLXDLL undefined), while you are
  166.         attempting to link with the import library of the DLL version.
  167.         To solve this problem, you must either define _TLXDLL (and use
  168.         the DLL version), or link to the static version of the
  169.         compiled library.
  170.  
  171.     The link checks are implemented by inserting a small static object in
  172.     each module that #includes TLX.H. The overhead of this is very small
  173.     (about 2-4 bytes data space per module, and a trivial amount of code
  174.     during startup), but if you cannot tolerate this and are absolutely
  175.     certain that you link to the correct version of the TLX libraries
  176.     (e.g. in the release build for an application), you may forego the
  177.     check and its hidden objects by defining the preprocessor symbol
  178.     _NO_LINK_CHECK prior to #including TLX.H in any of your modules.
  179.  
  180.     NOTE:    If you use the precompiled headers option of your compiler,
  181.         the compiler may warn you that it can't create a precompiled
  182.         header if the precompiled portion includes TLX.H (which
  183.         contains initialized static data). If you really want to use
  184.         precompiled headers and they should encompass TLX.H, you
  185.         may define the _NO_LINK_CHECK symbol as explained above.
  186.         This disables the initialized data object that is used for
  187.         link checks (and therefore the link check itself), after
  188.         which precompilation should pose no further problems.
  189.  
  190.  
  191. Library build check
  192. -------------------
  193.  
  194.     As part of the library build process, a small executable file is
  195.     compiled and linked, then run immediately after the build of a
  196.     library version is completed. This executable does nothing more than
  197.     to print a description of the library on the standard output; its
  198.     purpose is to allow you to verify that the build did indeed succeed,
  199.     and to inform you of the exact version and release of the library.
  200.  
  201.     The executable files have the same filename as the corresponding
  202.     library (i.e. TLXxxx), but with a .EXE extension instead of .LIB.
  203.