TLIB Help


TLIB is a utility that manages libraries of individual .OBJ
(object module) files. A library is a convenient tool for
dealing with a collection of object modules as a single unit.


Using TLIB: the Turbo Librarian
===============================
When it modifies an existing library, TLIB always creates a copy of
the original library with a .BAK extension.

You can use TLIB to build and modify your own libraries, libraries
furnished by other programmers, or commercial libraries you've
purchased. You can also use TLIB to:

  o  Create a new library from a group of object modules.

  o  Add object modules or other libraries to an existing library.

  o  Remove object modules from an existing library.

  o  Replace object modules from an existing library.

  o  Extract object modules from an existing library.

  o  List the contents of a new or existing library.


Why use object module libraries?
--------------------------------
When you program, you often create a collection of useful functions.
With modular programming, you are likely to split those functions into
many separately compiled source files. Any particular program might
use only a subset of functions from the entire collection.

An object module library manages a collection of functions and
classes. When you link your program with a library, the linker scans
the library and automatically selects only those modules needed for
the current program.


The TLIB command line
---------------------
The TLIB command line takes the following general form, where items
listed in square brackets are optional:

     tlib [@respfile] [option] libname [operations] [, listfile]


Option         Description
------         -----------
@respfile The path and name of the response file you want to
          include. You can specify more than one response file.

libname   The DOS path name of the library you want to create or
          manage. Every TLIB command must be given a libname.
          Wildcards are not allowed. TLIB assumes an extension
          of .LIB if none is given. (It's best to use only the
          .LIB extension.) NOTE: If the named library does not
          exist and there are 'add' operations, TLIB creates the
          library.

/C        The case-sensitive flag. This option is not normally
          used.

/E        Creates Extended Dictionary.

/Psize         Sets the library page size to 'size'.

/0        Removes comment records from the library.

operations     The list of operations TLIB performs. Operations can
          appear in any order. If you only want to examine the
          contents of the library, don't give any operations.

listfile  The name of the file that lists library contents. It
          must be preceded by a comma. No listing is produced if
          you don't give a file name. The listing is an
          alphabetical list of each module. The entry for each
          module contains an alphabetical list of each public
          symbol defined in that module. The default extension
          for the 'listfile' is .LST. You can direct the listing
          to the screen by using the 'listfile' name CON, or to
          the printer by using the name PRN.


Using response files
- - - - - - - - - - -
When you use a large number of operations, or if you find yourself
repeating certain sets of operations over and over, you will probably
want to use response files. A response file is an ASCII text file that
contains all or part of a TLIB command. Using response files, you can
build TLIB commands larger than would fit on one command line.
Response files can:

  o  Contain more than one line of text; use the ampersand
     character (&) at the end of a line to indicate that
     another line follows.

  o  Include a partial list of commands. You can combine
     options from the command line with options in a response file.

  o  Be used with other response files in a single TLIB command line.


Using case-sensitive symbols: The /C option
- - - - - - - - - - - - - - - - - - - - - -
TLIB maintains a dictionary of all public symbols defined in the
modules of the library. When you add a module to a library, its symbol
must be unique. If you try to add a module to the library that
duplicates a symbol, TLIB displays an error message and doesn't add
the module.

NOTE: Don't use /C if you plan to use the library with other linkers
or let other people use the library.

Because some linkers aren't case-sensitive, TLIB rejects symbols that
differ only in case (for example, the symbols 'lookup' and 'LOOKUP'
are treated as duplicates). TLINK, however, can distinguish case, so
if you use your library only with TLINK, you can use the TLIB /C
option to add a module to a library that includes symbols differing
only in case.


Creating an extended dictionary: The /E option
- - - - - - - - - - - - - - - -  - - - - - - - -
To increase the linker's capacity for large links, you can use TLIB to
create an extended dictionary and append it to the library file. This
dictionary contains, in a compact form, information that is not
included in the standard library dictionary and that lets the linker
(TLINK) preprocess library files so that any unnecessary modules are
not preprocessed.

To create an extended dictionary for a library that you're modifying,
use the /E option when you start TLIB to add, remove, or replace
modules in the library. You can also use the /E option to create an
extended dictionary for an existing library that you don't want to
modify. For example, if you type "TLIB /E mylib" the linker appends an
extended dictionary to the specified library.

If you use /E to add a library module containing a C++ class with a
virtual function, you'll get the error message "Library contains
COMDEF records--extended dictionary not created".


Setting the page size: The /P option
- - - - - - - - - - - - - - - - -  -
Every DOS library file contains a dictionary that appears at the end
of the .LIB file, following all of the object modules. For each module
in the library, the dictionary contains a 16-bit address of that
particular module within the .LIB file; this address is given in terms
of the library page size (it defaults to 16 bytes).

The library page size determines the maximum combined size of all
object modules in the library, which cannot exceed 65,536 pages. The
default (and minimum) page size of 16 bytes allows a library of about
1 MB in size. To create a larger library, use the /P option to
increase the page size. The page size must be a power of 2, and it
cannot be smaller than 16 or larger than 32,768.

All modules in the library must start on a page boundary. For example,
in a library with a page size of 32 (the lowest possible page size
higher than the default 16), an average of 16 bytes is lost per object
module in padding. If you attempt to create a library that is too
large for the given page size, TLIB issues an error message and
suggests that you use /P with the next available higher page size.


Removing comment records: The /0 option
- - - - - - - - - - - - - - - - - - - -
Use the /0 option to remove comment records, which reduces the size of
a library. For example, you might have debugging or browsing
information in a library, but you no longer need to use that
information; the /0 option removes that information.


The operation list
- - - - - - - - - -
The operation list describes what actions you want TLIB to do. It
consists of a sequence of operations given one after the other. Each
operation consists of a one- or two-character action symbol followed
by a file or module name. You can put whitespace around either the
action symbol or the file or module name but not in the middle of a
two-character action or in a name.

You can put as many operations as you like on the command line, up to
126 characters. The order of the operations is not important. TLIB
always applies the operations in a specific order:

 1) All extract operations are done first.

 2) All remove operations are done next.

 3) All add operations are done last.

TLIB finds the name of a module by stripping any drive, path, and
extension information from the given file name. TLIB always assumes
reasonable defaults. For example, to add a module that has an .OBJ
extension from the current directory, you need to supply only the
module name, not the path and .OBJ extension.

TLIB recognizes three action symbols (-, +, *), which you can use
singly or combined in pairs for a total of five distinct operations.
The action symbols and what they do are listed here:

Symbol    Name      Description
------    ----      -----------
+    Add       TLIB adds the named file to the library. If
               the file has no extension, TLIB assumes an
               extension of .OBJ. If the file is itself a
               library (with a .LIB extension), then the
               operation adds all of the modules in the named
               library to the target library. If a module
               being added already exists, TLIB displays a
               message and does not add the new module.

-    Remove         TLIB removes the named module from the
               library. If the module does not exist in the
               library, TLIB displays a message. A remove
               operation needs only a module name. TLIB lets
               you enter a full path name with drive and
               extension included, but ignores everything
               except the module name.

*    Extract        TLIB creates the named file by copying the
               corresponding module from the library to the
               file. If the module does not exist, TLIB
               displays a message and does not create a file.
               If the named file already exists, it is
               overwritten.

-*   Extract & TLIB copies the named module to the
               corresponding file name and then removes it
               from the library.

-+   Replace        TLIB replaces the named module with the
               corresponding file.


Examples
--------
These examples demonstrate some of the things you can do with TLIB:

  o  To create a library named MYLIB.LIB with modules X.OBJ,
     Y.OBJ, and Z.OBJ, type "tlib mylib +x +y +z".

  o  To create a library named MYLIB.LIB and get a listing
     in MYLIB.LST too, type "tlib mylib +x +y +z, mylib.lst".

  o  To replace module X.OBJ with a new copy, add A.OBJ and
     delete Z.OBJ from MYLIB.LIB, type "tlib mylib -+x +a -z".

  o  To create a new library (ALPHA) with modules A.OBJ,
     B.OBJ...G.OBJ using a response file:

     First create a text file, ALPHA.RSP, with

          @^+a.obj +b.obj +c.obj &
             +d.obj +e.obj +f.obj &
             +g.obj

     Then use the TLIB command, which produces a listing file named
     ALPHA.LST: "tlib alpha @alpha.rsp, alpha.lst".

NOTE: You can't directly rename modules in a library. To rename a
module, extract and remove it, rename the file just created, then add
it back into the library.

/**************************** END OF FILE ********************************/

