This chapter describes the Watcom Library Manager, and includes the following sections:
The Watcom Library Manager can be used to create and update object library files. It takes as input an object file or a library file, and creates or updates a library file. For OS/2, Windows 3.x and Windows NT applications, it can also create import libraries from Dynamic Link Libraries.
An object library is essentially a collection of object files. These object files generally contain utility routines that can be used as input to the Watcom Linker to create an application. The following are some of the advantages of using library files:
The Watcom Library Manager currently runs under the following operating systems:
The Watcom Library Manager command line is as follows:
wlib [options] lib_file [cmd_list]
The square brackets ([ ]) denote items that are optional.
The following is a summary of valid options, using this syntax:
The sections that follow describe the operations that can be performed on a library file.
The backup copy has the same file name as the original library file but has a file extension of .bak. Hence, lib_file shouldn't have a file extension of .bak.
An object file can be added to a library file by specifying a +obj_file command, where obj_file is the file specification for an object file. A file extension of .o is assumed if none is specified. If the library file doesn't exist, a warning message is issued, and the library file is created.
For example,
wlib mylib +myobj
In the above example, the object file myobj is added to the library file mylib.lib.
When a module is added to a library, the Watcom Library Manager issues a warning if a symbol redefinition occurs. This occurs if a symbol in the module being added is already defined in another module that already exists in the library file. Note that the module is added to the library in any case.
It's also possible to combine two library files together. The following example adds all modules in the library newlib.lib to the library mylib.lib.
wlib mylib +newlib.lib
Note that you must specify the .lib file extension. Otherwise, the Watcom Library Manager assumes you are adding an object file.
A module can be deleted from a library file by specifying a -mod_name command, where mod_name is the file name of the object file when it was added to the library, with the directory and file extension removed.
For example,
wlib mylib -myobj
In the above example, the Watcom Library Manager is instructed to delete the module myobj from the library file mylib.lib.
It's also possible to specify a library file instead of a module name. For example,
wlib mylib -oldlib.lib
In the above example, all modules in the library file oldlib.lib are removed from the library file mylib.lib. Note that you must specify the .lib file extension. Otherwise, the Watcom Library Manager assumes you are removing an object module.
A module can be replaced by specifying a -+mod_name or +-mod_name command. The module mod_name is deleted from the library. The object file mod_name is then added to the library. For example,
wlib mylib -+myobj
In the above example, the module myobj is replaced by the object file myobj.
It's also possible to merge two library files, as shown in the following example:
wlib mylib -+updlib.lib
In the above example, all modules in the library file updlib.lib replace the corresponding modules in the library file mylib.lib. Any module in the library updlib.lib that's not in library mylib.lib is added to the library mylib.lib. Note that you must specify the .lib file extension. Otherwise, the Watcom Library Manager assumes you are replacing an object module.
A module can be extracted from a library file by specifying a :mod_name command. The module mod_name isn't deleted, but is copied to a disk file. If mod_name is preceded by a path specification, the output file is placed in the directory identified by the path specification. If mod_name is followed by a file extension, the output file contains the specified file extension. For example,
wlib mylib :myobj
In the above example, the module myobj is copied to a disk file. The disk file is an object file with file name myobj. A file extension of .o is used. For example,
wlib mylib :myobj.out
In the above example, the module myobj is extracted from the library file mylib.lib, and placed in the file myobj.out.
You can extract a module from a file and have that module deleted from the library file by specifying a :-mod_name command. The following example performs the same operations as in the previous example but, in addition, the module is deleted from the library file:
wlib mylib :-myobj.out
Note that the same result is achieved if the delete operator precedes the extract operator.
The Watcom Library Manager can also be used to create import libraries from Dynamic Link Libraries. Import libraries are used when linking OS/2, Windows 3.x or Windows NT applications.
For example,
wlib implib +dynamic.dll
In the above example, the following actions are performed:
Note that you must specify the .dll file extension. Otherwise, the Watcom Library Manager assumes you are adding an object file.
An import library entry can be created and added to a library by specifying a command of the following form:
++sym.dll_name[.export_name][.ordinal]
where
For example,
wlib math ++__sin.trig.sin.1
In the above example, an import library entry is created for symbol sin, and added to the library math.lib. The symbol sin is defined in the Dynamic Link Library called trig.dll as __sin. When an application is linked with the library math.lib, the resulting executable file contains an import by ordinal value 1. If the ordinal value is omitted, the resulting executable file contains an import by name sin.
The Watcom Library Manager can be instructed to process all commands in a disk file by specifying the @cmd_file command, where cmd_file is a file specification for the command file. A file extension of .lbc is assumed if none is specified. The commands must be one of those previously described. For example,
wlib mylib @mycmd
In the above example, all commands in the file mycmd.lbc are processed by the Watcom Library Manager.
The following sections describe the list of options allowed when invoking the Watcom Library Manager:
The b option tells the Watcom Library Manager to not create a backup library file. In the following example, the object file identified by new is added to the library file mylib.lib:
wlib -b mylib +new
If the library file mylib.lib already exists, no backup library file (mylib.bak) is created.
The c option tells the Watcom Library Manager to use a case-sensitive comparison when comparing a symbol to be added to the library to a symbol already in the library file. This causes the names myrtn and MYRTN to be treated as different symbols. By default, comparisons are case-insensitive. That is, the symbol myrtn is the same as the symbol MYRTN.
The d option tells the Watcom Library Manager the directory in which all extracted modules are to be placed. The default is to place all extracted modules in the current directory.
In the following example, the module mymod is extracted from the library mylib.lib. The module is placed in the file /o/mymod.o.
wlib -d=/o mymod
When creating import libraries from Dynamic Link Libraries, import entries for the names in the resident and non-resident names tables are created. The i option can be used to describe the method used to import these names:
For example,
wlib -iro -inn implib +dynamic.dll
Note that you must specify the .dll file extension for the Dynamic Link Library. Otherwise an object file is assumed.
The l (``el'') option instructs the Watcom Library Manager to produce, in a listing file, a list of the names of all symbols that can be found in the library file. The file name of the listing file is the same as the file name of the library file; the file extension of the listing file is .lst.
For example,
wlib -l mylib
In the above example, the Watcom Library Manager is instructed to list the contents of the library file mylib.lib and produce the output in a listing file called mylib.lst.
An alternate form of this option is -l=list_file. With this form, you can specify the name of the listing file. When specifying a listing file name, a file extension of .lst is assumed if none is specified.
For example,
wlib -l=mylib.out mylib
In the above example, the Watcom Library Manager is instructed to list the contents of the library file mylib.lib, and produce the output in a listing file called mylib.out.
You can get a listing of the contents of a library file on the terminal by specifying only the library name on the command line, as demonstrated by the following example:
wlib mylib
The m option instructs the Watcom Library Manager to display C++ mangled names, rather than displaying their demangled form. The default is to interpret mangled C++ names, and display them in a somewhat more intelligible form.
The n option tells the Watcom Library Manager always to create a new library file. If the library file already exists, a backup copy is made (unless the b option is specified). The original contents of the library are discarded, and a new library is created. If the n option wasn't specified, the existing library would be updated.
For example,
wlib -n mylib +myobj
In the above example, a library file called mylib.lib is created. It contains a single object module, namely myobj, regardless of the contents of mylib.lib prior to issuing the above command. If mylib.lib already exists, it's renamed to mylib.bak.
The o option can be used to specify the output library file name if you want the original library to remain unchanged and a new library to be created. For example,
wlib -o=newlib lib1 +lib2.lib
In the above example, the modules from lib1.lib and lib2.lib are added to the library newlib.lib. Note that since the original library remains unchanged, no backup copy is created. Also, if the l option is used to specify a listing file, the listing file assumes the file name of the output library.
The p option specifies the record size in bytes for each record in the library file. The record size must be a power of 2, in the range 16 to 32768. If the record size is less than 16, it's rounded up to 16. If the record size is greater than 16 and not a power of 2, it's rounded up to the nearest power of 2. The default record size is 16 bytes.
Each entry in the dictionary of a library file contains an offset from the start of the file that points to a module. The offset is 16 bits and is a multiple of the record size. Since the default record size if 16, the maximum size of a library file for a record size of 16 is 16*64K. If the size of the library file increases beyond this size, you must increase the record size. For example,
wlib -p=32 lib1 +lib2.lib
In the above example, the Watcom Library Manager is instructed to create/update the library file lib1.lib by adding the modules from the library file lib2.lib. The record size of the resulting library file is 32 bytes.
The q option suppresses the banner and copyright notice that are normally displayed when the Watcom Library Manager is invoked. For example,
wlib -q -l mylib
The s option tells the Watcom Library Manager to remove line number records from object files that are being added to a library. Line number records are generated in the object file if the d1 option is specified when compiling the source code.
For example,
wlib -s mylib +myobj
The t option tells the Watcom Library Manager to remove path information from the module name specified in THEADR records in object files that are being added to a library. The module name is created from the file name by the compiler and placed in the THEADR record of the object file. The module name contains path information if the file name given to the compiler contains path information. For example,
wlib -t mylib +myobj
The x option tells the Watcom Library Manager to extract all modules from the library.
Object modules are placed in the current directory unless the d option is used to specify an alternate directory.
In the following example all modules are extracted from the library mylib.lib and placed in the current directory:
wlib -x mylib
In the following example, all modules are extracted from the library mylib.lib. The module is placed in the /o directory.
wlib -x -d=/o mylib
You can use the WLIB environment variable to specify commonly used Library Manager options. There options are processed before those specified on the command line. For example,
export "WLIB=-n -c"
The above example defines the default options to be -n (always create a new library) and -c (use case-sensitive comparisons for symbols).
The following messages may be issued by the Watcom Library Manager: