tlib.txt

tasm source document descript

/*************************************************************************/
                                 TLIB.TXT
                              TURBO ASSEMBLER

This file contains details on using TLIB with TASM.

--------------------------------------------------------------------
                        TABLE OF CONTENTS
                        - - - - - - - - -
   Using IMPLIB: The import librarian
   Using IMPDEF: The module-definition file manager
      Classes in a DLL
      Functions in a DLL
   Using TLIB: the Turbo Librarian
      Why use object module libraries?
      The TLIB command line
         Using response files
         Using case-sensitive symbols: The /C option
         Creating an extended dictionary: The /E option
         Setting the page size: The /P option
         Removing comment records: The /0 option
         The operation list
      Examples

--------------------------------------------------------------------

This chapter describes several tools that let you work with library
files.

  o  IMPLIB creates import libraries, and IMPDEF creates module
     definition files (.DEF files). Import libraries and module
     definition files provide information to the linker about
     functions imported from dynamic-link libraries (DLLs).

  o  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 IMPLIB: The import librarian
==================================
The IMPLIB utility creates import libraries. IMPLIB takes as input
DLLs, module definition files, or both, and produces an import library
as output. When you add a DLL as a target, the project manager
compiles and links the DLL's dependent files to create the .DLL file,
then runs IMPLIB to create a .LIB file.

Import libraries contain records. Each record contains the name of a
DLL, and specifies where in the DLL the imported functions reside.
These records are bound to the application by TLINK or the IDE linker,
and provide Windows with the information necessary to resolve DLL
function calls. An import library can be substituted for part or all
of the IMPORTS section of a module definition file.

If you've created a Windows application, you've already used at least
one import library, IMPORT.LIB, the import library for the standard
Windows DLLs.

An import library lists some or all of the exported functions for one
or more DLLs. IMPLIB creates an import library directly from DLLs or
from module definition files for DLLs (or a combination of the two).

To create an import library for a DLL, type

	IMPLIB Options LibName [DefFiles...|DLLs...]

where 'Options' is an optional list of one or more IMPLIB options,
'LibName' is the name for the new import library, 'DefFiles' is a list
of one or more existing module definition files for one or more DLLs,
and 'DLLs' is a list of one or more existing DLLs. You must specify at
least one DLL or module definition file.

A DLL can also have an extension of .EXE or .DRV, not just .DLL.

Options must be lowercase and preceded by either a hyphen or a slash.

Option		Description
------		-----------
-c		Accepts case-sensitive symbols. If you have two symbols
		that differ only in case (like MYSYM and mysym) and you
		don't use -c, IMPLIB uses the first symbol and treats
		the second one as a duplicate.

-i		Tells IMPLIB to ignore WEP, the Windows exit procedure
		required to end a DLL. Use this option if you are
		specifying more than one DLL on the IMPLIB command line.

-w		No warnings.


Using IMPDEF: The module-definition file manager
================================================
IMPDEF takes as input a DLL name, and produces as output a module
definition file with an export section containing the names of
functions exported by the DLL. The syntax is

	IMPDEF DestName.DEF SourceName.DLL

This creates a module definition file named 'DestName'.DEF from the
file 'SourceName'.DLL. The resulting module definition file would look
something like this:

	LIBRARY     FileName

	DESCRIPTION 'Description'

	EXPORTS
		ExportFuncName      @Ordinal
		ExportFuncName      @Ordinal

where 'FileName' is the DLL's root file name, 'Description' is the
value of the DESCRIPTION statement if the DLL was previously linked
with a module definition file that included a DESCRIPTION statement,
'ExportFuncName' names an exported function, and 'Ordinal' is that
function's ordinal value (an integer).


Classes in a DLL
----------------
IMPDEF is useful for a DLL that uses C++ classes. If you use the
_export keyword when defining a class, all of the non-inline member
functions and static data members for that class are exported. It's
easier to let IMPDEF make a module definition file for you because it
lists all the exported functions, and automatically includes the
member functions and static data members.

Since the names of these functions are mangled, it would be tedious to
list them all in the EXPORTS section of a module definition file
simply to create an import library from the module definition file. If
you use IMPDEF to create the module definition file, it includes the
ordinal value for each exported function. If the exported name is
mangled, IMPDEF also includes that function's unmangled, original name
as a comment following the function entry. So, for instance, the
module definition file created by IMPDEF for a DLL that used C++
classes would look something like this:

	LIBRARY     FileName

	DESCRIPTION 'Description'

	EXPORTS
		MangledExportFuncName  @Ordinal ; ExportFuncName
		MangledExportFuncName  @Ordinal ; ExportFuncName

where 'FileName' is the DLL's root file name, 'Description' is the
value of the DESCRIPTION statement if the DLL was previously linked
with a module definition file that included a DESCRIPTION statement,
'MangledExportFuncName' provides the mangled name, 'Ordinal' is that
function's ordinal value (an integer), and 'ExportFuncName' gives the
function's original name.


Functions in a DLL
------------------
IMPDEF creates an editable source file that lists all the exported
functions in the DLL. You can edit this .DEF file to contain only
those functions that you want to make available to a particular
application, then run IMPLIB on the edited .DEF file. This results in
an import library that contains import information for a specific
subset of a DLL's export functions.

Suppose you're distributing a DLL that provides functions to be used
by several applications. Every export function in the DLL is defined
with _export. Now, if all the applications used all the DLL's exports,
then you could use IMPLIB to make one import library for the DLL. You
could deliver that import library with the DLL, and it would provide
import information for all of the DLL's exports. The import library
could be linked to any application, thus eliminating the need for the
particular application to list every DLL function it uses in the
IMPORTS section of its module definition file.

But let's say you want to give only a few of the DLL's exports to a
particular application. Ideally, you want a customized import library
to be linked to that application--an import library that provides
import information only for the subset of functions that the
application uses. All of the other export functions in the DLL are
hidden to that client application.

To create an import library that satisfies these conditions, run
IMPDEF on the compiled and linked DLL. IMPDEF produces a module
definition file that contains an EXPORT section listing all of the
DLL's export functions. You can edit that module definition file,
remove the EXPORTS section entries for those functions you don't want
in the customized import library, and then run IMPLIB on the module
definition file. The result is an import library that contains import
information for only those export functions listed in the EXPORTS
section of the module definition file.


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