xlib.txt                        Copyright (c) 1995,96 xTech Ltd
----------------------------------------------------------------

                      XDS Library Manager
                      -------------------

Libraries are files of a special format that are used to collect
object modules or information required to tune import from DLL
(so called "import libraries").

The XLIB.EXE utility included to this package is intended for
library management.

The following topics are discussed below:

1. Usage
   1.1 Options
   1.2 File Names
   1.3 Response files
   1.4 Commands

2. Operation modes

3. Proper librarian mode

4. Import Librarian Mode

5. Library Contents List Mode

6. Supported Formats
   6.1. Output library format
   6.2. Input object file format
   6.3. Input executable format
   6.4. Import Definition Files Format

1. Usage
--------

To invoke XDS Library manager enter a command "xlib" with
necessary arguments. Being invoked without additional arguments
xlib outputs a brief help message similar to the following:

  XDS Library manager v1.0 (c) xTech 1995
  usage   = xlib /IMPLIB { option } libname[.lib] { file }
          | xlib { option } libname[.lib] { command }
          | xlib /LIST { option } libname[.lib]
  option  = /OptionName[+|-|=ValueString]
  file    = filename([.dll]|.exe|.idf) | @ResponceFileName
  command = { +|-|* }module[.obj] | @ResponceFileName
    "+" - add module to library
    "-" - remove module from library
    "*" - extract module to separate object file
  Options:
    /IMPLIB - create import library
    /LIST   - show library contens
    /LOGO-  - no logo
    /HELP   - print this text
    /SAFE-  - no "BAK" files
    /NEW    - create new library file (without /LIST and /IMPLIB
              only)
    /PREFIX=str  - set internal name prefix to "str"
                   (with /IMPLIB only)
    /POSTFIX=str - set internal name postfix to "str"
                   (with /IMPLIB only)


An argument may be either an option, a file name, a command, or 
a response file. Arguments controls operation mode, name of output
library and a set of files used to perform requested task.


1.1 Options

Options may be placed in arbitrary order at the command line.
Options are started with the slash ("/") character immediately
followed by an option name and optionally with ON/OFF sign
("+"/"-") or with the "=" sign followed by a string value.
In the first case the option is of BOOLEAN type while in the 
latter case it have a string value. Types of valid options
are hard-coded in the program and improper type of an option 
would cause an error. If neither "+", "-", or "=<string>" is present,
the option is considered to be of BOOLEAN type with value "ON".

Following is a list of all valid options with their meaning and
default values.

===============================================================
Name    Type  Default  Effect
               value
---------------------------------------------------------------
IMPLIB  BOOL   OFF     Set xlib to "import librarian" mode
                       of operation (See 4)

LIST    BOOL   OFF     If ON, xLib only outputs contents of
                       a given library; no other operation is
                       performed. (See 5)

LOGO    BOOL   ON      Specifies whether xLib has to print its
                       logo.

HELP    BOOL   OFF     If ON, causes  xLib to output a brief 
                       help text; no other operation is be
                       performed.

SAFE    BOOL   ON      Sets the xlib to rename files to ".BAK"
                       before overwriting them.

NEW     BOOL   OFF     xlib will always create a new library file
                       instead of using the existing one.

PREFIX  Str    empty   Sets prefix of imported names 
                       (See 4).

POSTFIX Str    empty   Sets postfix of imported names 
                       (See 4).

===============================================================

If xlib encounters an unknown option, or an option that have no
effect in a given operation mode, it produces a warning message.


1.2 File Names

File names appearing in xlib's command line are regular file
names. Each name may be prefixed with directory path.
If extension is omitted defaults are used. Below is the
list of default extensions for various types of files.

Type            Extension

Library file     .lib
Object module    .obj
DLL              .dll

1.3 Response files

Response file for xlib is a text file that contains a number
of xlib arguments, one per line. Any kind of argument is allowed
except response file. Some options have no effect when used 
in response file, These are "IMPLIB", "LIST", "HELP" and "LOGO"
options.

1.4 Commands

Commands are names of files prefixed by a set of command
signs. The signs are "+","-" and "*". Any other character used
in a command prefix is interpreted as first character of a proper
file name. Relational order of characters in the prefix have no
meaning.

Note that commands are valid for "library manager" operation
mode only (See 3).


2. Operation modes
------------------

The xlib utility has three operation modes: library contents
list mode, import librarian mode and proper librarian
mode. Operation modes are switched by "IMPLIB" and "LIST"
options as follows:

  i)   If "IMPLIB" option is set, xlib is switched to import
  librarian mode (See 4).

  ii)  If "LIST" option is set, xlib is switched to library
  contents list mode (See 5).

  iii) If both "IMPLIB" and "LIST" options are set, xlib is
  switched to import librarian mode (See 4).

  iv)  If both "IMPLIB" and "LIST" modes are not set, xlib is
  switched to proper librarian mode (See 3).

Details of operation modes are given in following chapters.


3. Proper librarian mode
------------------------

In this mode xlib acts as a proper library manager. First given
argument that does not represent an option setting is treated as
a name of a library file to deal with. If extension is omitted, the
default ".lib" is added. If the option "NEW" is not set, the
xlib supposes that the given library file should exist and should
be valid, otherwise it produces a warning and createsa a new
library file.

Other arguments given in the command line or in a response file are
treated as commands (see 1.4). Each command represents a set
of actions and a name of object module or library.

Valid actions are add, remove and extract. The are denoted by
"+", "-" and "*" characters respectively. When more than one 
action is specified, xlib performs them in following order:

   1) extract
   2) remove
   3) add

For instance, to replace module "a.obj" you may use either "-+a" or
"+-a".

If all commands are successfully executed, xlib checks the resulting
library for duplicate names, producing warnings if necessary.

Then xlib creates an output library file and writes the
resulting library. If any file with name equal to output file
name does already exist then xlib may save it by changing its
extension to ".BAK" before overwrite. It is controlled by the SAFE
option that is set ON by default.


4. Import Librarian Mode
------------------------

In this mode xlib produces special kind of library - so called
"import library". This kind of libraries contain the information
for a linker on how to tune up import information in the target
executable. Import libraries are commonly used instead of
definition files.

To switch xlib to import librarian mode set the "IMPLIB"
option ON (i.e. use "/IMPLIB" or "/IMPLIB+" string in the
command line).

In this mode xlib treats first given argument that does not
represent an option setting as a name of an output library file.
If extension is omitted, default ".lib" is added. xlib
always creates new file for the resulting library. If a file
with a given name does already exist, xlib may save it by
changing its extension to ".BAK" depending on "SAFE" option
setting.

Other arguments that do not represent option settings are treated
as names of source files. xlib may retrieve information required
to create an import library from two kinds of sources, namely from
an executable (EXE of DLL) or from a special script file (Import
Definition File). The type of source is determined by its extension,
where ".exe" stands for executable, ".dll" stands for dynamically
linked library and ".idf" stands for import definition file. 
If extension is omitted, ".dll" is added by default.

See 6 for details of supported formats.

In general, an import library sets correspondence between an
internal name (e.g. name that may be referenced from a
program) to a DLL name and an exported entry within it. 
Internal names should be properly mangled to fit naming
convention of a programing system. xlib provides a simple
mechanism for names mangling when it is necessary. It uses value of
the "PREFIX" option as a prefix and value of the "POSTFIX" option as
a postfix for all internal names it produces.

For example, being invoked with

  /PREFIX=_IMP_ /POSTFIX=_EXP_

xlib will mangle entry "OneEntry" to name "_IMP_OneEntry_EXP_".


5. Library Contents List Mode
-----------------------------

In this mode xlib outputs listing of a library contents.

To switch xlib to library contents mode set "LIST" option ON 
(i.e. add "/LIST" or "/LIST+" to the command line).

In this mode xlib treats first given argument as a library
file name. If extension is omitted, the default ".lib" is
added. A file should exist and should be a correct library file,
otherwise xlib produces an error report.

Other arguments that are not option settings are ignored.

Library contents is printed as follows:

XDS Library manager v1.0 (c) xTech 1995
Library "libxds.lib"
  MODULE src\xr\xrMM.mod
    xrMM_Align
    xrMM_COLLECTOR
    xrMM_DoDefrag
    xrMM_DynarrDescSize
    xrMM_free_block
    xrMM_ini_type_desc
    xrMM_parts
    xrMM_BEGIN
  MODULE src\xr\xrO2MM.mod
    X2C_DESTRUCTOR
    X2C_DISPOSE
    X2C_GET_TD
    X2C_MODULE
    X2C_NEW
    X2C_NEW_OPEN
    xrO2MM_BEGIN


6. Supported Formats
--------------------

Here input and output formats currently supported by xlib are
discussed.

6.1. Output library format

Currently xlib produces output libraries in OMF format only.
This format is compatible with most of current linkers. The
important exception is link386 by Microsoft that expects
libraries in COFF format.

COFF format will be supported later.

6.2. Input object file format

Currently xlib expects all input object files to be in OMF
format. Most modern compilers, including XDS compilers, produce
object files in this format. The important exception are MSVC
(v2.0 and higher) compilers by Microsoft which produce output
in COFF format.

COFF format will be supported later.

6.3. Input executable format

The xlib may retrieve export information for import libraries
from executables (either DLL or EXE) which are in "PE" (Portable
Executable) format only. This format is used for all 32-bit
executables in Windows95 and WindowsNT. Other executable formats
will be supported later.

6.4. Import Definition Files Format

Below is the description of the import definition files format. The
description is given in the Extended Backus-Naur Formalism.
Brackets "[" and "]" denotes optionality of the enclosed
expression, braces "{" and "}" denotes repetition possibly 0
times. Terminal symbols are given in capitals (e.g. FROM) or are
enclosed within quotation marks (e.g. ";").

  File = OneImport ";" { OneImport ";" } .
  OneImport = FROM DllName IMPORT Entry { "," Entry } .
  Entry = ExportedEntryName [ AS InternalName ] .
  DllName = name of the DLL or EXE
  ExportedEntryName = name of exported entry .
  InternalName = internal name for the entry .

Lines starting with "%" are considered to be comments and
ignored.

Note that if InternalName is omitted, the ExportedEntryName is
used as internal name.

Example of import definition file:

%  Copyright (c) 1996 xTech Ltd., Russia
%
%  Sample Import Definition File
%
FROM KERNEL32.DLL IMPORT
  CreateFileA
  ,WriteFile
  ,ReadFile
  ,DeleteFileA
  ,MoveFileA
  ,SetFilePointer
  ,SetSystemTime
  ,RtlFillMemory AS FillMemory
  ;

FROM USER32.DLL IMPORT
  ShowWindow
  ,ShowWindowAsync
  ,TileWindows
  ;
% end of the sample import definition file

                        [end of document]
