Super Prev Next

Managing libraries

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

The XDS Library Manager (also referred to as XLIB in the documentation), is intended for library creation and management.


Super Prev Next

Starting XLIB

To invoke XLIB, enter "xlib" with necessary arguments at the command prompt. An argument may be either an option, a file name, a command, or a response file name. The command line syntax varies among operation modes.

Being invoked without additional arguments, XLIB outputs a brief help message.


Super Prev Next

Options

Options may be placed on the command line in arbitrary order. An option consists of the slash ("/") character immediately followed by an option name. Some options also have string values delimited with the "=" character.

The following table lists XLIB options along with their meanings and default values.

Option Meaning
/IMPLIB Create an import library
/EDF Create an export definition file
/LIST List contents of a given library
/HELP Output a brief help text and terminate
/NOLOGO Suppress logo
/NOBAK Do not backup files before overwriting them
/NEW Always create a new library
/PREFIX=String Set prefix of imported names
/POSTFIX=String Set postfix of imported names
/USEORD Use ordinal numbers (see Import library creation and Export info extraction)

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


Super Prev Next

File names

File names appearing on XLIB command line are regular file names. Each name may be prefixed with directory path. If an extension is omitted, defaults are used:

Type Extension
Library .lib
Object module .obj
DLL .dll
Export definition file .edf
Import definition file .idf


Super Prev Next

Response files

A response file argument is the "@" character immediately followed by a response file name. A response file is a text file that contains a number of XLIB arguments, one on each line. Any type of argument is allowed except another response file.

Note: The options /IMPLIB, /LIST, /EDF, /HELP, and /NOLOGO have no effect when used in a response file.


Super Prev Next

Commands

A command is a non-empty set of command symbols ("+","-", and "*") followed by the name of the object module or file which is the subject of the command. Relational order of command symbols has no meaning.

Note that commands are valid for the library management operation mode only.


Super Prev Next

Operation modes

XLIB has four operation modes, switched by /IMPLIB, /LIST, and /EDF options as follows:

Option Mode
default Library management
/IMPLIB Import library creation
/LIST Library contents listing
/EDF Export info extraction

Details of operation modes are given in the following sections.


Super Prev Next

Library management

    xlib { option } libname[.lib] { command }
    command = { +|-|* }module[.obj] | @ResponceFileName

In this mode XLIB acts as a proper library manager. The first argument which does not represent an option setting is treated as the name of the library file. If an extension is omitted, the default ".lib" is added. If the /NEW option is not set, XLIB supposes that the given library file already exists and is valid, otherwise it produces a warning and creates a new library file.

Arguments following a library name are treated as commands. Each command represents a set of actions and a name of an object module or library.

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

  1. extract
  2. remove
  3. add

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

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

Finally, the new library is written to disk. The original library file, if existed before XLIB execution, is saved by changing its extension to .BAK, unless the /NOBAK option is specified.


Super Prev Next

Import library creation

    xlib /IMPLIB { option } libname[.lib] { File }
    File = filename([.dll]|.exe|.idf) | @ResponceFileName

In this mode XLIB produces an import library. Libraries of this kind contain information which is used by linkers to tune up import sections in executable files (see Load-time dynamic linking). Import libraries are commonly used instead of definition files.

To switch XLIB to import librarian mode, specify the /IMPLIB option on the command line.

In this mode, XLIB treats the first given argument that does not represent an option setting as the name of the output library file. If an extension is omitted, the default .lib is added. XLIB always creates a new library file. If the output file does already exist, XLIB saves it by changing its extension to ".bak", unless the /NOBAK option is set.

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 or DLL) or from an import definition file. The type of source is determined by file extension, where ".exe" stands for an executable, ".dll" stands for a dynamically linked library, and ".idf" stands for an import definition file. If an extension is omitted, ".dll" is added by default.

See Supported formats for details of supported formats.

In general, an import library sets correspondence between entry names (e.g. names under which entries may be referenced in other executable modules) and pairs consisting of a DLL name and an internal name or ordinal number of an exported entry. It may be necessary to mangle entry names to fit naming convention of a programming system. XLIB provides a simple mechanism for mangling. It uses value of the /PREFIX option as a prefix and value of the /POSTFIX option as a postfix for all entry names it produces.

For example, being invoked with

    /PREFIX=_IMP_ /POSTFIX=_EXP_

XLIB will mangle the internal name "OneEntry" to the entry name "_IMP_OneEntry_EXP_".

By default, XLIB creates import libraries which use import by name. The /USEORD option forces it to use import by ordinal. See How does the dynamic linking work and Load-time dynamic linking for more information.

After you have created an import library, you may use XLIB on it to add object modules which you want to be available to a linker when you link with that import library.


Super Prev Next

Import definition files

Below is the description of the import definition files format.

    File = Import ";" { Import ";" }
    Import = FROM Module IMPORT Entry { "," Entry }
    Entry = InternalName [ AS EntryName ]

Module is a name of an executable module (DLL or EXE). InternalName is the entry name as it appears within that module. Finally, EntryName is the entry name as it is to be known to other modules. If the AS EntryName clause is omitted, the entry is exported under its internal name.

Lines starting with "%" are treated as comments and ignored.

Example of an import definition file:

%
%  Sample Import Definition File
%  Copyright (c) 1997 XDS Ltd.
%
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


Super Prev Next

Library contents listing

    xlib /LIST { option } libname[".lib"]

In this mode XLIB outputs a library contents listing.

To switch XLIB to the library contents mode, specify the /LIST option on the command line.

In this mode XLIB treats the first given argument as the input library file name. If extension is omitted, the default ".lib" will be added. The library must exist and must be in correct format, otherwise XLIB will produce an error report.

Other arguments that are not option settings are ignored.

Library contents are printed as follows:

    Library "libxds.lib"
      MODULE src\isoimp\chancons.mod
        ChanConsts_BEGIN
      MODULE src\isoimp\charclas.mod
        CharClass_IsControl
        CharClass_IsLetter
        CharClass_IsLower
        CharClass_IsNumeric
        CharClass_IsUpper
        CharClass_IsWhiteSpace
        CharClass_BEGIN
     .  .  .


Super Prev Next

Export info extraction

    xlib /EDF { option } edfname[.edf] dllname[.dll]

If this mode, XLIB reads export information from the given DLL and creates an export definition file (EDF), which may then be edited and used when the DLL is rebuilt (See Controlling export from a DLL).

If the option /USEORD is specified, the output EDF will contain ordinal numbers.

The first non-option argument is treated as the output EDF name. If no extension is specified, ".edf" is assumed. The second argument must be a DLL name. If an extension is omitted, the default ".dll" is assumed.


Super Prev Next

Supported formats

Here the input and output formats currently supported by XLIB are discussed.


Super Prev Next

Output library format

Currently XLIB produces output libraries in OMF format only. This format is compatible with most of available linkers. The important exception are Microsoft linkers which expect libraries to be in COFF format.

COFF format will be supported later.


Super Prev Next

Input object file format

Currently XLIB expects all input object files to be in OMF format. Many modern 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. XDS compilers may produce object files in both formats (see the OBJFMT option).

COFF format will be supported later.


Super Prev Next

Input executable format

XLIB may retrieve information for import libraries from executables (either DLL or EXE) which are in the PE (Portable Executable) format, used for 32-bit executables in Windows. No other formats are planned to be supported.