home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tlx501.zip / DOC / CHANGES.TXT < prev    next >
Text File  |  1995-03-07  |  9KB  |  219 lines
  1. ******************************************************************************
  2. *
  3. * CHANGES.TXT - Changes in TLX from 4.2 to 5.0 to 5.01
  4. *
  5. * Last updated: 07-Mar-1995
  6. *
  7. * Copyright (c) 1991-95 Tarma Software Research. All rights reserved.
  8. *
  9. ******************************************************************************
  10.  
  11.  
  12. Directory structure
  13. -------------------
  14.  
  15.     The directory structure has been changed slightly since version 4.2,
  16.     which itself marked a departure from the previous organization. The
  17.     directories that make up TLX 5.0 are organized as follows:
  18.  
  19.         TLX50            - base, contains info
  20.         TLX50\TLX        - base, contains .h files
  21.         TLX50\TLX\SOLVE     - .h files for searching & CSP
  22.         TLX50\TLX\TEMPLATE    - template source files
  23.         TLX50\SRC        - source files
  24.         TLX50\LIB        - compiled library files
  25.         TLX50\LIB\BC        - Borland libraries
  26.         TLX50\LIB\IBM        - IBM libraries
  27.         TLX50\LIB\SC        - Symantec libraries
  28.         TLX50\LIB\WC        - Watcom libraries
  29.         TLX50\DOC        - contains documentation files
  30.         TLX50\SAMPLES        - sample programs
  31.         TLX50\SAMPLES\AC3    - sample AC-3 CSP program
  32.         TLX50\SAMPLES\AC6    - sample AC-6 CSP program
  33.         TLX50\SAMPLES\BB    - sample branch & bound program
  34.         TLX50\TOOLS        - various tools to support TLX
  35.         TLX50\TOOLS\OS2     - ditto, OS/2 versions
  36.         TLX50\TOOLS\NT         - ditto, Windows NT versions
  37.  
  38.     Not all compiler-specific directories may appear in your distribution.
  39.  
  40.     As before, these changes are primarily intended to avoid name clashes
  41.     with similar files from other providers. To use this new directory
  42.     structure, set up your compiler's INCLUDE path to contain the
  43.     TLX50 base directory (including drive letter, if appropriate).
  44.     For example:
  45.  
  46.         SET INCLUDE=C:\TLX50;C:\WATCOMC\INCLUDE
  47.  
  48.     Alternatively, you may use the corresponding setting from within the
  49.     compiler's IDE, or give it as a parameter on the command line:
  50.  
  51.         BCC /IC:\TLX50;C:\BC4\INCLUDE myfile.cpp
  52.  
  53.     The changes in the directory structure influence the way you should
  54.     refer to TLX header and template source files. Write #include
  55.     directives that refer to TLX header files in your own source code
  56.     as follows:
  57.  
  58.         #include <tlx\arrays.h>         (header file)
  59.         #include <tlx\template\array.cpp>    (template source file)
  60.  
  61.     In combination with the earlier guidelines about your compiler's
  62.     INCLUDE setting, this should produce the desired effect.
  63.  
  64.     NOTE:    the above conventions differ slightly on UNIX platforms
  65.         (where a forward slash '/' is used to separate path
  66.         components), and on Macintosh platforms, where there is
  67.         no direct support for subdirectory specifications. For
  68.         these platforms, conversion tools will be provided
  69.         that adapt the #include directives to the respective
  70.         platform conventions.
  71.  
  72.  
  73. Naming changes from 4.x to 5.0
  74. ------------------------------
  75.  
  76.     All member function names have been changed, mostly to have them
  77.     start with a capital letter. Some others have been changed for
  78.     consistency among classes, and/or for more clarity as to the
  79.     operation they perform.
  80.  
  81.     To automatically change TLX 4.2 names to their 5.0 counterparts,
  82.     we have provided a tool called TLX5UP. This tool is located in
  83.     TLX50/TOOLS (sorry - only an MS-DOS version currently). Use it
  84.     as follows:
  85.  
  86.         TLX5UP filename(s)...
  87.  
  88.     For filename(s)..., enter the names of one or more of your .h or
  89.     .cpp files that you wish to convert. Wildcards are allowed, so
  90.     the following is an easy way to convert all your 4.2 files to
  91.     5.0 conventions:
  92.  
  93.         TLX5UP *.H *.CPP
  94.  
  95.     To see a list of all changes, type TLX5UP without arguments. You
  96.     may need to pipe its output through MORE or a similar utility, or
  97.     redirect it to another file, because of the length of the list.
  98.     Excerpts of TLX5UP output without arguments:
  99.  
  100. (1)        ASSERT              -> TLX_ASSERT
  101.         ASSERT_NULL           -> TLX_ASSERT_NULL
  102.         ASSERT_PTR              -> TLX_ASSERT_PTR
  103.         BENDIAN              -> _BENDIAN
  104.         BREAKPOINT              -> TLX_DEBUGBREAK
  105.         ...
  106. (2)        TLHandle              -> Obsolete_TLHandle
  107.         ...
  108.         ulong              -> tULong
  109.         ushort              -> tUShort
  110. (3)        ASSERT(              -> TLX_ASSERT(
  111.         ASSERT_NULL(          -> TLX_ASSERT_NULL(
  112.         ...
  113.         vector(              -> StorageVector(
  114.         version(              -> Version(
  115.         watch(              -> WatchVars(
  116.  
  117.     Notes:
  118.  
  119.     (1) On each line, the left column indicates the old 4.2 name, while
  120.         on the right the new 5.0 name is shown.
  121.  
  122.     (2) If names have been dropped altogether, they will be replaced by
  123.         their original name with an 'Obsolete_' prefix. If you try to
  124.         compile this name, you will get a compilation error and should
  125.         consult the TLX 5.0 documentation to see by which new facility
  126.         the old one has been replaced.
  127.  
  128.     (3) Partly through the list, a new sublist is started. Names in this
  129.         sublist end in '('; this is a parsing convenience to distinguish
  130.         function names from others.
  131.  
  132.  
  133. Naming changes from 5.0 to 5.01
  134. -------------------------------
  135.  
  136.     Minor changes with respect to names of simple types (tInt32 etc.)
  137.     As with the 4.x -> 5.0 naming changes, an update tool is provided,
  138.     called TLX501UP. It will perform updates from 5.00 to 5.01 *only*,
  139.     so you'll need to use TLX5UP first if you're coming from TLX 4.x.
  140.  
  141.     Use of the tool is identical to TLX5UP. In particular, a complete 
  142.     list of changes may be obtained by running TLX501UP without arguments.
  143.  
  144.  
  145. Use of exceptions and runtime type information
  146. ----------------------------------------------
  147.  
  148.     Starting with this version of TLX, the library source code uses C++
  149.     exceptions to report problems. All error return values from functions
  150.     have been removed; if a function returns, it can be assumed to be
  151.     successful (or at least, it operated without error).
  152.  
  153.     Because not all C++ compilers currently support exceptions, we have
  154.     introduced a migration path. This is actually very simple, because TLX
  155.     will only throw exceptions; it will never catch them. Thus, the only
  156.     exception construct that needs to be emulated for backward
  157.     compatibility is the 'throw' expression. This is accomplished by means
  158.     of a new THROW macro. If the C++ compiler supports exceptions, this
  159.     macro reverts to an ordinary 'throw'; if not, a special function
  160.     '_TlxThrow()' is called to notify the user and perhaps terminate the
  161.     program.
  162.  
  163.     In addition, an exception hierarchy is introduced that starts with the
  164.     base class TLException. All exceptions thrown in TLX code, with the
  165.     exception (no pun intended) of the ANSI/ISO C++ standard exceptions
  166.     xmsg, xalloc, etc. are derived from TLException. (In fact, the
  167.     _TlxThrow() emulation function only accepts TLException-derived
  168.     classes.)
  169.  
  170.     Refer to the header file EXCEPT.H for more information regarding
  171.     exceptions.
  172.  
  173.     A similar story holds for runtime type information (RTTI). The file
  174.     RTTI.H contains a few macros that expand to the new-style typecasts
  175.     (including dynamic_cast<>) on C++ compilers that support them, or use
  176.     old-style casts on compilers that do not. You should be aware,
  177.     however, that the semantics of an old-style typecast are different
  178.     from the new-style ones (in particular in the case of dynamic_cast<>,
  179.     which performs both runtime type checking and allows casts from
  180.     virtual bases to derived classes), and that therefore programs may
  181.     behave differently. You are advised to switch to an RTTI-supporting
  182.     C++ compiler as soon as possible.
  183.  
  184.     There is also marginal emulation support for the new typeid()
  185.     operator.
  186.  
  187.     Refer to the header file RTTI.H for more information regarding
  188.     these items.
  189.  
  190.  
  191. Constraint satisfaction and backtrack search
  192. --------------------------------------------
  193.  
  194.     This area has been largely redesigned. While it implements the same
  195.     algorithms as before, the details are quite different. Consult Tarma
  196.     Software Research if you need help with these changes and/or a white
  197.     paper describing the new implementation.
  198.  
  199.  
  200. Link version checks
  201. -------------------
  202.  
  203.     In order to reduce the chance that you compile your source code
  204.     against one version of the TLX header files (say, debug) while
  205.     linking to another (retail), we have introduced link-time checks
  206.     in the library. Refer to COMPILE.TXT for more information concerning
  207.     these checks.
  208.  
  209.  
  210. Other changes
  211. -------------
  212.  
  213.     The other changes include numerous smaller modifications and/or
  214.     corrections to existing classes, a new (and hopefully improved)
  215.     formatting style for both source code and comments, and the
  216.     introduction of several new classes. However, this process is not
  217.     finished as of this release, so expect more changes (which will
  218.     generally be downward compatible).
  219.