home *** CD-ROM | disk | FTP | other *** search
/ PC Plus SuperCD (UK) 2000 May / PCP163A.iso / Runimage / Cbuilder4 / Examples / WinTools / TLIB.TXT < prev    next >
Encoding:
Text File  |  1999-01-26  |  11.1 KB  |  273 lines
  1. TLIB Help
  2.  
  3.  
  4. TLIB is a utility that manages libraries of individual .OBJ
  5. (object module) files. A library is a convenient tool for
  6. dealing with a collection of object modules as a single unit.
  7.  
  8.  
  9. Using TLIB: the Turbo Librarian
  10. ===============================
  11. When it modifies an existing library, TLIB always creates a copy of
  12. the original library with a .BAK extension.
  13.  
  14. You can use TLIB to build and modify your own libraries, libraries
  15. furnished by other programmers, or commercial libraries you've
  16. purchased. You can also use TLIB to:
  17.  
  18.   o  Create a new library from a group of object modules.
  19.  
  20.   o  Add object modules or other libraries to an existing library.
  21.  
  22.   o  Remove object modules from an existing library.
  23.  
  24.   o  Replace object modules from an existing library.
  25.  
  26.   o  Extract object modules from an existing library.
  27.  
  28.   o  List the contents of a new or existing library.
  29.  
  30.  
  31. Why use object module libraries?
  32. --------------------------------
  33. When you program, you often create a collection of useful functions.
  34. With modular programming, you are likely to split those functions into
  35. many separately compiled source files. Any particular program might
  36. use only a subset of functions from the entire collection.
  37.  
  38. An object module library manages a collection of functions and
  39. classes. When you link your program with a library, the linker scans
  40. the library and automatically selects only those modules needed for
  41. the current program.
  42.  
  43.  
  44. The TLIB command line
  45. ---------------------
  46. The TLIB command line takes the following general form, where items
  47. listed in square brackets are optional:
  48.  
  49.      tlib [@respfile] [option] libname [operations] [, listfile]
  50.  
  51.  
  52. Option         Description
  53. ------         -----------
  54. @respfile The path and name of the response file you want to
  55.           include. You can specify more than one response file.
  56.  
  57. libname   The DOS path name of the library you want to create or
  58.           manage. Every TLIB command must be given a libname.
  59.           Wildcards are not allowed. TLIB assumes an extension
  60.           of .LIB if none is given. (It's best to use only the
  61.           .LIB extension.) NOTE: If the named library does not
  62.           exist and there are 'add' operations, TLIB creates the
  63.           library.
  64.  
  65. /C        The case-sensitive flag. This option is not normally
  66.           used.
  67.  
  68. /E        Creates Extended Dictionary.
  69.  
  70. /Psize         Sets the library page size to 'size'.
  71.  
  72. /0        Removes comment records from the library.
  73.  
  74. operations     The list of operations TLIB performs. Operations can
  75.           appear in any order. If you only want to examine the
  76.           contents of the library, don't give any operations.
  77.  
  78. listfile  The name of the file that lists library contents. It
  79.           must be preceded by a comma. No listing is produced if
  80.           you don't give a file name. The listing is an
  81.           alphabetical list of each module. The entry for each
  82.           module contains an alphabetical list of each public
  83.           symbol defined in that module. The default extension
  84.           for the 'listfile' is .LST. You can direct the listing
  85.           to the screen by using the 'listfile' name CON, or to
  86.           the printer by using the name PRN.
  87.  
  88.  
  89. Using response files
  90. - - - - - - - - - - -
  91. When you use a large number of operations, or if you find yourself
  92. repeating certain sets of operations over and over, you will probably
  93. want to use response files. A response file is an ASCII text file that
  94. contains all or part of a TLIB command. Using response files, you can
  95. build TLIB commands larger than would fit on one command line.
  96. Response files can:
  97.  
  98.   o  Contain more than one line of text; use the ampersand
  99.      character (&) at the end of a line to indicate that
  100.      another line follows.
  101.  
  102.   o  Include a partial list of commands. You can combine
  103.      options from the command line with options in a response file.
  104.  
  105.   o  Be used with other response files in a single TLIB command line.
  106.  
  107.  
  108. Using case-sensitive symbols: The /C option
  109. - - - - - - - - - - - - - - - - - - - - - -
  110. TLIB maintains a dictionary of all public symbols defined in the
  111. modules of the library. When you add a module to a library, its symbol
  112. must be unique. If you try to add a module to the library that
  113. duplicates a symbol, TLIB displays an error message and doesn't add
  114. the module.
  115.  
  116. NOTE: Don't use /C if you plan to use the library with other linkers
  117. or let other people use the library.
  118.  
  119. Because some linkers aren't case-sensitive, TLIB rejects symbols that
  120. differ only in case (for example, the symbols 'lookup' and 'LOOKUP'
  121. are treated as duplicates). TLINK, however, can distinguish case, so
  122. if you use your library only with TLINK, you can use the TLIB /C
  123. option to add a module to a library that includes symbols differing
  124. only in case.
  125.  
  126.  
  127. Creating an extended dictionary: The /E option
  128. - - - - - - - - - - - - - - - -  - - - - - - - -
  129. To increase the linker's capacity for large links, you can use TLIB to
  130. create an extended dictionary and append it to the library file. This
  131. dictionary contains, in a compact form, information that is not
  132. included in the standard library dictionary and that lets the linker
  133. (TLINK) preprocess library files so that any unnecessary modules are
  134. not preprocessed.
  135.  
  136. To create an extended dictionary for a library that you're modifying,
  137. use the /E option when you start TLIB to add, remove, or replace
  138. modules in the library. You can also use the /E option to create an
  139. extended dictionary for an existing library that you don't want to
  140. modify. For example, if you type "TLIB /E mylib" the linker appends an
  141. extended dictionary to the specified library.
  142.  
  143. If you use /E to add a library module containing a C++ class with a
  144. virtual function, you'll get the error message "Library contains
  145. COMDEF records--extended dictionary not created".
  146.  
  147.  
  148. Setting the page size: The /P option
  149. - - - - - - - - - - - - - - - - -  -
  150. Every DOS library file contains a dictionary that appears at the end
  151. of the .LIB file, following all of the object modules. For each module
  152. in the library, the dictionary contains a 16-bit address of that
  153. particular module within the .LIB file; this address is given in terms
  154. of the library page size (it defaults to 16 bytes).
  155.  
  156. The library page size determines the maximum combined size of all
  157. object modules in the library, which cannot exceed 65,536 pages. The
  158. default (and minimum) page size of 16 bytes allows a library of about
  159. 1 MB in size. To create a larger library, use the /P option to
  160. increase the page size. The page size must be a power of 2, and it
  161. cannot be smaller than 16 or larger than 32,768.
  162.  
  163. All modules in the library must start on a page boundary. For example,
  164. in a library with a page size of 32 (the lowest possible page size
  165. higher than the default 16), an average of 16 bytes is lost per object
  166. module in padding. If you attempt to create a library that is too
  167. large for the given page size, TLIB issues an error message and
  168. suggests that you use /P with the next available higher page size.
  169.  
  170.  
  171. Removing comment records: The /0 option
  172. - - - - - - - - - - - - - - - - - - - -
  173. Use the /0 option to remove comment records, which reduces the size of
  174. a library. For example, you might have debugging or browsing
  175. information in a library, but you no longer need to use that
  176. information; the /0 option removes that information.
  177.  
  178.  
  179. The operation list
  180. - - - - - - - - - -
  181. The operation list describes what actions you want TLIB to do. It
  182. consists of a sequence of operations given one after the other. Each
  183. operation consists of a one- or two-character action symbol followed
  184. by a file or module name. You can put whitespace around either the
  185. action symbol or the file or module name but not in the middle of a
  186. two-character action or in a name.
  187.  
  188. You can put as many operations as you like on the command line, up to
  189. 126 characters. The order of the operations is not important. TLIB
  190. always applies the operations in a specific order:
  191.  
  192.  1) All extract operations are done first.
  193.  
  194.  2) All remove operations are done next.
  195.  
  196.  3) All add operations are done last.
  197.  
  198. TLIB finds the name of a module by stripping any drive, path, and
  199. extension information from the given file name. TLIB always assumes
  200. reasonable defaults. For example, to add a module that has an .OBJ
  201. extension from the current directory, you need to supply only the
  202. module name, not the path and .OBJ extension.
  203.  
  204. TLIB recognizes three action symbols (-, +, *), which you can use
  205. singly or combined in pairs for a total of five distinct operations.
  206. The action symbols and what they do are listed here:
  207.  
  208. Symbol    Name      Description
  209. ------    ----      -----------
  210. +    Add       TLIB adds the named file to the library. If
  211.                the file has no extension, TLIB assumes an
  212.                extension of .OBJ. If the file is itself a
  213.                library (with a .LIB extension), then the
  214.                operation adds all of the modules in the named
  215.                library to the target library. If a module
  216.                being added already exists, TLIB displays a
  217.                message and does not add the new module.
  218.  
  219. -    Remove         TLIB removes the named module from the
  220.                library. If the module does not exist in the
  221.                library, TLIB displays a message. A remove
  222.                operation needs only a module name. TLIB lets
  223.                you enter a full path name with drive and
  224.                extension included, but ignores everything
  225.                except the module name.
  226.  
  227. *    Extract        TLIB creates the named file by copying the
  228.                corresponding module from the library to the
  229.                file. If the module does not exist, TLIB
  230.                displays a message and does not create a file.
  231.                If the named file already exists, it is
  232.                overwritten.
  233.  
  234. -*   Extract & TLIB copies the named module to the
  235.                corresponding file name and then removes it
  236.                from the library.
  237.  
  238. -+   Replace        TLIB replaces the named module with the
  239.                corresponding file.
  240.  
  241.  
  242. Examples
  243. --------
  244. These examples demonstrate some of the things you can do with TLIB:
  245.  
  246.   o  To create a library named MYLIB.LIB with modules X.OBJ,
  247.      Y.OBJ, and Z.OBJ, type "tlib mylib +x +y +z".
  248.  
  249.   o  To create a library named MYLIB.LIB and get a listing
  250.      in MYLIB.LST too, type "tlib mylib +x +y +z, mylib.lst".
  251.  
  252.   o  To replace module X.OBJ with a new copy, add A.OBJ and
  253.      delete Z.OBJ from MYLIB.LIB, type "tlib mylib -+x +a -z".
  254.  
  255.   o  To create a new library (ALPHA) with modules A.OBJ,
  256.      B.OBJ...G.OBJ using a response file:
  257.  
  258.      First create a text file, ALPHA.RSP, with
  259.  
  260.           @^+a.obj +b.obj +c.obj &
  261.              +d.obj +e.obj +f.obj &
  262.              +g.obj
  263.  
  264.      Then use the TLIB command, which produces a listing file named
  265.      ALPHA.LST: "tlib alpha @alpha.rsp, alpha.lst".
  266.  
  267. NOTE: You can't directly rename modules in a library. To rename a
  268. module, extract and remove it, rename the file just created, then add
  269. it back into the library.
  270.  
  271. /**************************** END OF FILE ********************************/
  272.  
  273.