Difference between revisions of "Librarian"

Latest revision as of 11:22, 31 July 2017

The librarian program, LIBR, has the function of combining several object files into a single file known as a library. The purposes of combining several such object modules are several.

• a. fewer files to link
• b. faster access
• c. uses less disk space

In order to make the library concept useful, it is necessary for the linker to treat modules in a library differently from object files. If an object file is specified to the linker, it will be linked into the final linked module. A module in a library, however, will only be linked in if it defines one or more symbols previously known, but not defined, to the linker. Thus modules in a library will be linked only if required. Since the choice of modules to link is made on the first pass of the linker, and the library is searched in a linear fashion, it is possible to order the modules in a library to produce special effects when linking. More will be said about this later.

The Library Format

The modules in a library are basically just concatenated, but at the beginning of a library is maintained a directory of the modules and symbols in the library. Since this directory is smaller than the sum of the modules, the linker is speeded up when searching a library since it need read only the directory and not all the modules on the first pass. On the second pass it need read only those modules which are required, seeking over the others. This all minimizes disk i/o when linking.

It should be noted that the library format is geared exclusively toward object modules, and is not a general purpose archiving mechanism as is used by some other compiler systems. This has the advantage that the format may be optimized toward speeding up the linkage process.

Using

The librarian program is called LIBR, and the format of commands to it is as follows:

LIBR k file.lib file.obj ...

Interpreting this, LIBR is the name of the program, k is a key letter denoting the function requested of the librarian (replacing, extracting or deleting modules, listing modules or symbols), file.lib is the name of the library file to be operated on, and file.obj is zero or more object file names.

The key letters are:

r

replace modules

d

delete modules

x

extract modules

m

list module names

s

list modules with symbols

When replacing or extracting modules, the file.obj arguments are the names of the modules to be replaced or extracted. If no such arguments are supplied, all the modules in the library will be replaced or extracted respectively. Adding a file to a library is performed by requesting the librarian to replace it in the library. Since it is not present, the module will be appended to the library. If the r key is used and the library does not exist, it will be created.

Under the d keyletter, the named object files will be deleted from the library. In this instance, it is an error not to give any object file names.

The m and s keyletters will list the named modules and, in the case of the s keyletter, the symbols defined or referenced within (global symbols only are handled by the librarian). As with the r and x keyletters, an empty list of modules means all the modules in the library.

Examples

Here are some examples of usage of the librarian.

LIBR m file.lib

List all modules in the library file.lib.

LIBR s file.lib a.obj b.obj c.obj

List the global symbols in the modules a.obj, b.obj and c.obj

LIBR r file.lib 1.obj 2.obj

Replace the module 1.obj in the file file.lib with the contents of the object file 1.obj, and repeat for 2.obj. If the object module is not already present in the library, append it to the end.

LIBR x file.lib

Extract, without deletion, all the modules in file.lib and write them as object files on disk.

LIBR d file.lib a.obj b.obj 2.obj

Delete the object modules a.obj, b.obj and 2.obj from the library file.lib.

Supplying Arguments

Since it is often necessary to supply many object file arguments to LIBR, and command lines are restricted to 127 characters by CP/M and MS-DOS, LIBR will accept commands from standard input if no command line arguments are given. If the standard input is attached to the console, LIBR will prompt. Multiple line input may be given by using a backslash as a continuation character on the end of a line. If standard input is redirected from a file, LIBR will take input from the file, without prompting. For example:

LIBR
libr> r file.lib 1.obj 2.obj 3.obj \
libr> 4.obj 5.obj 6.obj

will perform much the same as if the .obj files had been typed on the command line. The libr> prompts were printed by LIBR itself, the remainder of the text was typed as input.

LIBR <lib.cmd

Libr will read input from lib.cmd, and execute the command found therein. This allows a virtually unlimited length command to be given to LIBR.

Listing Format

A request to LIBR to list module names will simply produce a list of names, one per line, on standard output. The s keyletter will produce the same, with a list of symbols after each module name. Each symbol will be preceded by the letter D or U, representing a definition or reference to the symbol respectively. The -W option may be used to determine the width of the paper for this operation. For example LIBR -w80 s file.lib will list all modules in file.lib with their global symbols, with the output formatted for an 80 column printer or display.

Ordering of Libraries

The librarian creates libraries with the modules in the order in which they were given on the command line. When updating a library the order of the modules is preserved. Any new modules added to a library after it has been created will be appended to the end.

The ordering of the modules in a library is significant to the linker. If a library contains a module which references a symbol defined in another module in the same library, the module defining the symbol should come after the module referencing the symbol.

Error Messages

Libr issues various error messages, most of which represent a fatal error, while some represent a harmless occurence which will nonetheless be reported unless the -w option was used. In this case all warning messages will be suppressed.