home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tvos200.zip / TOOLS / README < prev    next >
Text File  |  1995-04-25  |  13KB  |  350 lines
  1. MKLIB and TCM
  2. -------------
  3.  
  4. These tools are used to build libraries (MKLIB) and .EXE files (TCM) from
  5. simple project files. Both use a config file SAWTOOLS.INI, which must contain
  6. entries describing each set of compiler and options.
  7.  
  8.  
  9. Before using:
  10. -------------
  11. To use these tools, you must have the following environment variables set:
  12.  
  13. SET TMP= (somewhere)
  14. SET USER= (a max. 8-letter code; fi. your initials).
  15. SET PRJ= (your project directory, see below).
  16.  
  17.  
  18. Directory structure:
  19. --------------------
  20. TCM and MKLIB make some assumptions about directory structures used when
  21. developing multiple projects. I use a single directory, called PRJ, which
  22. contains subdirectories for every project I'm currently handling. Shared
  23. libraries, such as TVISION, have a subdirectory there too; this subdirectory
  24. contains all that's needed to build the library or the project.
  25.  
  26. The PRJ directory MUST be referred to by the SET PRJ= statement. On my PC
  27. it is
  28.     SET PRJ=D:\PRJ
  29.  
  30.  
  31. When a project needs stuff from a shared library, I use the include syntax
  32.  
  33.     #include    <tvision/tv.h>
  34.  
  35. The include files for shared libraries are in the project directory for that
  36. library, i.e. d:\prj\tvision.
  37.  
  38.  
  39. TCM
  40. ---
  41. Stands for Tcc Make. This file reads .ppp files; each line therein contains one
  42. module that's used to make the program. The suffix of the file mentioned on
  43. the line will determine what compiler will be called for the file. Each
  44. suffix has a corresponding entry describing the compiler in the sawtools.ini
  45. file.
  46.  
  47. TCM recognises auto-dependency information as generated by the Borland and
  48. WatCOM compilers when it's present in the OBJ file. Dependencies are checked
  49. if this info is present in the object file. A new version of TCM will
  50. check the dependencies for the IBM C Set/2 compiler also.
  51.  
  52.  
  53. How to use
  54. ----------
  55. When your SAWTOOLS.INI file is correct (which must be made OK only once) then
  56. using TCM is very easy. To compile a project you must first generate a .PPP
  57. file for the project. This can be done very easily by using DIR like this:
  58.  
  59.     dir *.cpp /b >tv.ppp
  60.  
  61. which will generate a file containing all .CPP files on a single line.
  62.  
  63. Then, if you need any libraries, you'll add them to the .PPP file by hand.
  64.  
  65. When this is done use the command
  66.  
  67.     TCM tv
  68.  
  69. to compile your program. For every source file, it will check if the object
  70. file exists. If not, the source will be recompiled. If the object does exist
  71. but the source file is newer then it will be recompiled also. If the source
  72. file's date hasn't changed then the object is opened to see if dependency
  73. information is present. If so the info is read and every header file's date
  74. is checked against the dependency information. If any header has changed date
  75. then the source will be recompiled.
  76.  
  77. When all compiles have succeeded then the linker will be started to link
  78. all modules together. The result should be a working .EXE file.
  79.  
  80.  
  81. Defaults:
  82. ---------
  83. You can start TCM without arguments to compile the last program you've compiled
  84. in the current subdirectory. TCM leaves a TCM.DEF file in the directory which
  85. contains the last .PPP file it has built.
  86.  
  87. By default, TCM compiles for the compiler specified in the SAWTOOLS.INI file.
  88. You can override the compiler settings by using the -c:<id> option, which
  89. compiles for the compiler specified. Make sure your environment is OK for
  90. that compiler too!
  91.  
  92. Other options for TCM can be found by using TCM -?.
  93.  
  94.  
  95. How it finds files
  96. ------------------
  97. TCM finds the files in the .PPP file as follows:
  98.  
  99. 1.  In the current directory. If necessary it tries to add a .CPP or a .C
  100.     extension to the name.
  101.  
  102. 2.  When not found, it takes the PRJ environment variable and adds the path
  103.     found therein to the path specified. So, if an entry in the PPP file
  104.     was 'tvision\tview.cpp' and a SET PRJ=D:\PRJ was done then it will try
  105.     to find 'd:\prj\tvision\tview.cpp'. To allow this step, the PPP line
  106.     cannot start with a drive specifier OR a backslash (\); both denote an
  107.     absolute path.
  108.  
  109. 3.  If a suffix was specified on the line we search all paths specified
  110.     for the suffix in the 'def-search' options in the SAWTOOLS.INI.
  111.  
  112. 4.  If the entry was a .LIB file we do some extra processing:
  113.  
  114. 4a. We create a path for the library that's the same as the path that MKLIB
  115.     would use to store the library. That is, depending on the 'def-libpath'
  116.     in the SAWTOOLS.INI file a pathname for the library is made. This may
  117.     include a changed file NAME for the library! When found this library
  118.     is used, as it was made by MKLIB.
  119.     This mechanism ensures that the correct library will be found for the
  120.     current set of compiler & options used.
  121.  
  122. 4b. Then we create a path for the library using the PRJ envvar. First we
  123.     add the contents PRJ before the library name. If it exists the library
  124.     will be used with a warning message, because it is independent of the
  125.     compiler and model used.
  126.  
  127. 4c. Next we create a path by using PRJ, then adding the platform name (OS2 or
  128.     DOS), and at last the library name. This allows proper inclusion of the
  129.     appropriate OS2 or DOS library.
  130.  
  131. 4d. We give up.
  132.  
  133. The SAWTOOLS.INI must reside in the current directory (bah) or somewhere in
  134. the path (Yes!).
  135.  
  136.  
  137. Suffixes
  138. --------
  139. The following suffixes are recognised and treated by TCM:
  140.  
  141. .C    Calls the ".C" entry from the SAWTOOLS.INI file to compile.
  142. .CPP    Calls the ".CPP" entry,
  143. .ASM    Calls the .ASM entry,
  144. .LIB    Uses special stuff to find the file; causes a relink when the
  145.     lib is newer than the .EXE file; is added as a lib to the linker.
  146. .OBJ    Is not compiled, is added to the linker as a .OBJ.
  147. .DEF    Added as a response file to the linker.
  148.  
  149.  
  150. Examples
  151. --------
  152.  
  153. An example VQ.PPP is below:
  154.  
  155.     vqwin
  156.     infsrch
  157.     vinf
  158.  
  159.     infdict
  160.     inffile
  161.     infbase
  162.     inftoc
  163.     infart
  164.  
  165.     tocview
  166.     artview
  167.     tlscrol
  168.     arttxt
  169.  
  170.     dynarr
  171.     cms
  172.  
  173.     // Turbo Vision applets
  174.     tvutil\ascii
  175.     tvutil\calc
  176.     tvutil\calendar
  177.     tvutil\gadgets
  178.     tvutil\mousedlg
  179.     tvutil\fileview
  180.  
  181.     tvision\tv.lib
  182.     cpl\cpl.lib
  183.  
  184. As you can see the // is used as a comment. The upper sources are found in
  185. the current directory and end in .CPP; the tvutil\... files are found
  186. in d:\prj\tvutil\, and my library (for WatCOM) is at d:\lib\os2\w32ol\cpl.lib.
  187.  
  188. For an example SAWTOOLS.INI see below.
  189.  
  190.  
  191. MKLIB
  192. -----
  193. MKLIB is a companion to TCM. Instead of making .exe files it makes .lib files.
  194. It uses a .BLD file which must contain directives on how the lib is made for
  195. the several platforms. It uses the SAWTOOLS.INI file to find out about
  196. compilers and lib managers.
  197. MKLIB will try to retrieve sources for the library from the RCS path by calling
  198. a program CO.EXE. You can prevent this by not using the RCSpath, or by using
  199. the -NCHK option to MKLIB.
  200.  
  201. To build a library, for instance the Turbo Vision library, you need tv.bld in
  202. the TV directory and the PRJ environment variable set. Then issue the command
  203.  
  204.     MKLIB TV -NCHK
  205.  
  206. to create the library for the current compiler & platform.
  207.  
  208. MKLIB does NO dependency checking, EXCEPT the check to compare object dates
  209. with source dates. No header inclusion is checked.
  210.  
  211.  
  212. The SAWTOOLS.INI file.
  213. ----------------------
  214. Both MKLIB and TCM use the SAWTOOLS.INI file to retrieve info about their
  215. current environment and compilers. The first sawtools section you'll need is:
  216.  
  217.     [mklib]
  218.     def-model = l                $ Default memory model,
  219.     def-libpath    = `d:\lib\%j\%c%m\%l`    $ Path = d:\LIB\DOS\OL\VISTA.LIB
  220.     def-listpath    = `%s\%c%m%l`
  221.     def-objpath = `d:\_obj\%j\%c%m\%l`    $ Paths for objects: %c-> compilerletter, %l=libname, %m=modelletter.
  222.     def-EXEobjpath = `c:\%jX\%c%m`        $ .EXE objects: %c-> compilerletter, %l=libname, %m=modelletter.
  223.     def-exepath = `c:\%jx`            $ C:\OS2X or C:\DOSX
  224.     def-search  = .lib : "d:\prj", `d:\lib\%j\%c%m\%l`
  225.  
  226.     [mklib-os2]
  227.     def-compiler = w32o             $ Default compiler is BC++/2
  228.  
  229.     [mklib-dos]
  230.     def-compiler = w32d             $ Default compiler is WatCOM 32 DOS
  231.  
  232. The [mklib] section describes stuff that's shared between platforms; the
  233. sections [mklib-os2] and [mklib-dos] are read only when MKLIB runs on one of
  234. these platforms.
  235.  
  236. The first statement is def-model = l. It specifies that by default MKLIB and
  237. TCM will use the LARGE memory model. Other values can be F (flat), H (huge),
  238. S (small).
  239.  
  240. def-libpath:
  241.     Specifies the path & name of the library output file. It contains % entries
  242.     which are replaced by MKLIB and TCM. The replacement for each % entry is
  243.     specified below. You use these to make sure that a borland C 3.1 large
  244.     model DOS library gets another pathname as a watcom 10.0a OS/2 flat model
  245.     library.
  246.  
  247. def-listpath:
  248.     Specifies the path of the .LST file generated by MKLIB. This version places
  249.     the list in the current directory.
  250.  
  251. def-objpath:
  252.     Specifies the path where .OBJ files are to be placed. Again, use % stuff
  253.     to make sure that objects for different compilers go to different
  254.     directories.
  255.  
  256. def-exeobjpath:
  257.     Used by TCM only to place objects generated by TCM; i.e. objects that
  258.     are generated to make an .EXE file. Usually different from the def-objpath
  259.     so that you can periodically clean it out.
  260.  
  261. def-exepath:
  262.     The path where TCM will place the .EXE file it generates. This version
  263.     places DOS exe files in C:\DOSX and OS/2 exe files in C:\OS2X.
  264.  
  265. def-search:
  266.     Specifies search paths depending on the suffix. When TCM or MKLIB needs a
  267.     file it will search the paths defined for the suffix of the file.
  268.  
  269. def-compiler:
  270.     defines the name of the compiler to use if no compiler is explicitly
  271.     specified on the TCM or MKLIB command line..
  272.  
  273.  
  274. Path expansion characters:
  275.     %m - replaced by MODEL letter, i.e. H, L, M, F ed. as defined on the
  276.      command line or the def-model option.
  277.  
  278.     %s - Replaced with output file name if applicable
  279.     %j - replaced with DOS or OS2 depending on MKLIB platform.
  280.     %c - replaced with compiler ident string, as defined by the libsuffix=
  281.      SAWTOOLS command.
  282.     %l - Replaced with LIB name (from .BLD file) or EXE name (from .ppp).
  283.  
  284.  
  285. The rest of the SAWTOOLS.INI file contains compiler set entries. Each set entry
  286. describes a set of compilers and options for a given platform. So you can have
  287. a set for the Borland C++ 3.1 compiler under DOS, another set for the WatCOM
  288. C++ compiler under OS2 etc.
  289.  
  290. An example compiler set entry is:
  291.  
  292.     [mklib-b2]
  293.     libsuffix = r                $ 1st letter of lib name specifies compiler
  294.     compiler = .c, bcc, "-sm -D__JAL__ -D__32BITS__ -w-sig %d -v -o%o -Od -N -r -k %s"
  295.     compiler = .cpp, bcc, "-sm -D__32BITS__ -D__JAL__ -D__BCP__ -d -N -w-sig %d -v -o%o -N -k -Od -r -Vo- %s"
  296.     compiler = .asm, tasm, "%s,%o/s/z/t/ml/p -D__FLAT__ /d__%m__ %d /iP:\ "
  297.     librarian = tlib, "/c /P128 @%r", "%l &\n", "+%o &\n", ",\n\n\n"
  298.     linker = tlink, "/v /B:0x10000 /c /Toe /ap @%s", "%o %a+\n", "%x\n", "NUL\n", "%l %a+\n", "%d\n", "\n\n\n"
  299.  
  300.     def-search  = .lib : "d:\l\b2\lib" "d:\prj\nw\2"
  301.     def-search  = .obj : "d:\l\b2\lib"
  302.     def-module  = c02.obj, c2mt.lib, os2.lib
  303.  
  304.  
  305.  
  306. The name of this compiler set is 'b2'. This name can be found in the section
  307. name, [mklib-b2]. The def-compiler option, the -FOR command line option of
  308. MKLIB and the -C: option of TCM all specify this name. When MKLIB is invoked
  309. it will first read the [mklib] and [mklib-os2] sections. Then it will parse
  310. command line parameters. After this it will know the compiler set to use, so
  311. it reads [mklib-<setname>].
  312.  
  313. The parameters etc in a set definition are:
  314.  
  315. libsuffix:
  316.     Provides an "indentification" for stuff generated with this template. It
  317.     is used in the output path descriptors so that stuff generated by this
  318.     template will get it's own directory somewhere.
  319.     The value must be a string of 1..8 characters. Because it's used to
  320.     generate a filename use only stuff that is valid in a file name.
  321.  
  322. compiler:
  323.     Defines a compiler for a given suffix. The suffix is specified 1st as .cpp,
  324.     then the name of the compiler executable is specified (bcc) and last a
  325.     command line template is specified.
  326.     The command line template is expanded by TCM and MKLIB and should
  327.     result in a valid command line for the compiler. It can contain % stuff
  328.     also; the meaning for these is specified below.
  329.  
  330. librarian:
  331.     Contains a librarian template. Used to start the librarian and to generate
  332.     the LIB response file.
  333.  
  334. linker:
  335.     Contains a linker template. Used to start the linker and to generate
  336.     the LINKER's response file.
  337.  
  338. def-search:
  339.     See the entry for [mklib] above.
  340.  
  341. def-module:
  342.     Used by TCM only, this specifies what .OBJ and .LIB files must always be
  343.     included in the EXE. All .OBJ files mentioned herein will be linked FIRST,
  344.     all .LIB files mentioned herein will be linked LAST. In this example,
  345.     this ensures that the Borland C++ startup code will be included, and it
  346.     ensures that the Borland C++ runtime library is properly linked.
  347.  
  348.  
  349.  
  350.