23	ilibr  librarian
This chapter describes the librarian tool ilibr that integrates a group of compiled code files into a single unit that can be referenced by a program. The chapter begins by describing the command line syntax, goes on to describe some aspects of toolset libraries, and ends with some hints about how to build efficient libraries from separate modules. 
23.1	Introduction
The librarian builds libraries from one or more separately compiled units supplied as input files. The input files may be any of the following types: 
•	Compiled object code files produced by the INMOS compilers:
-	oc (occam 2 compiler),
-	icc (ANSI C compiler),
-	if77 (FORTRAN-77 compiler).
•	Library files already generated by ilibr (see section 23.2.4).
•	Linked object files (see section 23.2.3). 
The input files for one library must all be of the same type.
The librarian takes a list of compiled files in TCOFF format and integrates them into a single object file that can be used by a program or program module. Each module in the input list becomes a selectively loadable module in the library. Input files can either be specified as a list on the command line or in indirect files.
The library, once built, will contain an index followed by the concatenated modules. The index is generated and sorted by the librarian to facilitate rapid access of the library content by the other tools in the toolset, for example, the linker. 
Compiled object files (excluding library files) may be concatenated for convenience before using the librarian. This may prove useful when dealing with a large number of input files.
The operation of the librarian in terms of standard file extensions is shown below.

23.2	Running the librarian
To invoke the librarian use the following command line:
ilibr  filenames  { options }
where:	filenames is a list of input files separated by spaces. 

options is a list of one or more options from Table 8.1.
The number of file names allowed on a command line is system dependent. To avoid overflow, an indirect file may be used or files (other than library files) may be concatenated. It is the user's responsibility to ensure that the concatenation process does not corrupt the modules, for example by omitting to specify that the concatenation is to be done in binary mode. 
If no arguments are given on the command line a help page is displayed giving the command syntax.

Option	Description	
F filename	Specifies a library indirect file.	
I	Displays progress information as the library is built.	
O filename	Specifies an output file. If no output file is specified the name is taken from the first input file and a .lib extension is added.	

Table 8.1ilibr command line options
Example
ilibr myprog.t4x myprog.t8x

ilibr myprog.t4x myprog.t8x myprog.t0x

In this example, the compiled object code files myprog.t4x and myprog.t8x (compiled for T4 and T8 transputers respectively) are used to create a library. Because no output file name is specified on the command line, the library will be given the name myprog.lib.
In this example, the compiled object code files myprog.t4x, myprog.t8x  and myprog.t0x (compiled for T4, T8 and T9000 transputers respectively) are used to create a library. Because no output file name is specified on the command line, the library will be given the name myprog.lib.
23.2.1	Default command line
A set of default command line options can be defined for the tool using the ILIBRARG environment variable. Options must be specified in the variable using the syntax required by the command line. Options from an environment variable are processed before other options.
23.2.2	Library indirect files
Library indirect files are text files that contain lists of input files, directives to the librarian, and comments. Filenames and directives must appear on different lines. Comments must be preceded by the double dash character sequence `--', which causes the rest of the line to be ignored. By convention indirect files are given the .lbb extension. 
Indirect files may be nested within each other, to any level. This is achieved by using the #INCLUDE directive. By convention nested indirect files are also given the extension .lbb. 
The following is an example of an indirect file: 
   -- user's .lbb file

   userproc1.tco           -- single modules
   userproc2.tco
   userproc3.tco
   myconcat.tco            -- concatenation of modules
   #INCLUDE indirect.lbb   -- another indirect file
   userproc4.tco           -- another single module

The contents of a nested indirect file will effectively be expanded at the position it occurred. 
To specify indirect files on the command line each indirect filename must be preceded by the `F' option. 
23.2.3	Linked object input files
The librarian will also accept linked object files as input, with certain conditions. The facility to create libraries of linked modules provides an easy method of specifying input to the configurer. Such library files should only be referenced from a configuration description. 
The librarian will generate an error if an attempt is made to include both linked units and compiled modules in a single library. In addition, libraries of linked object modules must not be used as input to the linker ilink. This is because the linker does not accept linked units as input files.
23.2.4	Library files as input
Library files can themselves be used as input files to ilibr. When a library file is used as a component of a new library, its index is discarded by ilibr.
Library files may not be concatenated for input to the librarian.
23.3	Library modules
Libraries are made up of one or more selectively loadable modules. A module is the smallest unit of a library that can be loaded separately. Modules are selected via the library index. 
23.3.1	Selective loading 
Libraries can contain the same routines compiled for different transputer types and (for occam modules) in different error modes. 
Selection of library modules for linking in with the program is made on the basis of target processor type and error mode. For example, if the program is compiled for an IMS T414 only modules compiled for this processor type or for processors in a compatible transputer class are loaded. For languages such as FORTRAN and C the error mode is always UNIVERSAL.
For C and FORTRAN modules the linker selects the library modules best suited to the compilation units. For occam the compiler identifies the modules to be selected according to the requirements of the main program. The linker then makes the selection.
The linker also selects library modules for linking on the basis of usage. Only those modules that are actually used by the program are linked into the program. 
23.3.2	How the librarian sorts the library index
The librarian creates a library index which is used by the linker to select the required modules. The librarian sorts the index so that for a given processor type, the optimum module is always selected by the linker. 
The librarian compares and sorts modules according to a number of factors including attributes set by the compiler options used. These determine for example, the instruction set of the module and influence runtime execution times. 
For example, where two library modules were derived from the same source but compiled for classes TA and T8, the librarian would place the T8 module first because it uses a larger instruction set. Modules compiled with interactive debugging disabled are placed earlier in the index than those for which debugging is enabled. This is because disabling debugging causes code to execute faster and the librarian orders the index entries such that the first valid entry is always the `best choice'. If two entries are found to be identical the librarian will issue a warning. 
23.4	Library usage files
Library usage files describe the dependencies of a library on other libraries or separately compiled code. They consist of a list of separately compiled units or libraries referenced within a particular library. The .liu files required by the toolset's libraries are supplied by INMOS. 
If the imakef tool is used then library usage files should be created for all libraries that are supplied without source. This is to enable the imakef tool to generate the necessary commands for linking. Library usage files are text files. They may be created for a specific library by invoking the imakef tool and specifying a .liu target. See section 26.5.
Such files are given the same name as the library file to which they relate but with an .liu extension. 
23.5	Building libraries
This section describes the rules that govern the construction of libraries and contains some hints for building and optimizing libraries.
23.5.1	Rules for constructing libraries 
1. Routines of the same name in a library must be compiled for different transputer types, error modes or debug attributes. 
2. Libraries that contain modules compiled for a transputer class (i.e. TA or TB) are treated as though they contain a copy for each member of the class (using the subset of instructions which are common). 
3. Libraries that contain modules compiled in UNIVERSAL mode are treated as though they contain a copy for each of the two error modes HALT and STOP.
4. Libraries that contain modules with interactive debugging enabled are treated as though they also contain a copy with interactive debugging disabled. (When interactive debugging is enabled on occam code files, channel input/output is performed via library calls otherwise transputer instructions are used). 
23.5.2	General hints for building libraries
Routines that are likely to be used together in a program or procedure (such as routines for accessing the file system) can be incorporated into the same library. At a lower level, routines that will always be used together (such as those for opening and closing files) can be incorporated into the same module. 
Libraries can contain the same routines compiled for different transputer types, in different error modes and with different input/output access to channels. Only those modules actually used by the program are incorporated by the compiler and linked in by the linker. 
Where possible compile library input files with debugging enabled. This enables the debugger to locate the library source if an error occurs inside the library. 
When building C libraries care should be taken if the `FS' or `FC' INMOS C compiler command line options are used, that code compatibility is maintained.
23.5.3	Optimizing libraries 
It is possible for the user to optimize the size and content of any libraries which he builds himself, to target appropriate processors, improve the speed of code execution and to provide the best code for a given processor. At the same time is can be desirable to build libraries which are flexible i.e. support different transputer targets.
All libraries
Points to consider when constructing libraries in any language or mixture of languages:
•	Whether the library is to be targeted at one or two specific processors or a wide range of processors. The transputer type specified for the compilation of a library module determines the instruction set used. Transputer classes TA and TB provide the basic instruction sets common to several transputer types. Transputer classes such as the T5 provide extended instruction sets but are targetted at fewer transputers than classes TA and TB. 
•	For floating point operations, classes T5 and TB provide better code and therefore better execution times than class TA. 
•	Whether the versatility of the library should be reduced in order to create a smaller library. 
Libraries containing occam modules
When building libraries which include modules written in occam the same considerations apply, but also note the following:
•	 The error mode used will affect the size of the library. A library created from modules compiled in UNIVERSAL mode will behave as if it contains a copy of the code for both HALT and STOP mode. Also, on the current range of transputers, code compiled in HALT mode will tend to execute faster than if it is compiled in STOP or UNIVERSAL error modes.
•	For libraries containing modules where the method of channel input/output may be altered, (such as in occam), both the availability of the interactive debugging facility and the speed at which the code will be executed may be affected. 
 When interactive debugging is enabled, channel input/output will be implemented via library calls. When interactive debugging is disabled using the occam compiler `Y' option, transputer instructions are used for channel input/output. This leads to faster execution times. However, disabling interactive debugging for one module of a program, will disable this facility for the whole program.           
Code which is compiled to use library calls for channel i/o can be called by code compiled to use either library calls or transputer instructions for channel i/o. The opposite case is not true, therefore, in order to build a library which is flexible in this respect, code should be compiled to use library calls.           
For a detailed description of transputer types and error modes, see appendix B. 
Outlined below are three different approaches to optimization. The first approach provides the greatest level of flexibility in its application. The experienced user may refine these guidelines to specific requirements. 
Semi-optimized library build targeted at all transputer types
This is the simplest way to build a flexible library that covers the full range of transputers.
The user should compile each module separately for the following four cases and incorporate all four versions into the library.

Processor type/class 	Error mode	Method of channel I/O	
T2	UNIVERSAL	Via library calls	
TA	UNIVERSAL	Via library calls.	
T8	UNIVERSAL	Via library calls.	
T9000	UNIVERSAL	Via library calls.	
Note: Error mode and channel i/o only apply only to modules which employ them e.g. occam modules compiled by oc.			

The resulting library will be small in terms of the number of modules it will contain. Due to their generic nature the modules themselves may be bulky and because they contain only the base set of instructions, the execution time for the program will tend to be slower than a more optimized approach. 
Optimized library targeted at all transputer types
In order to build a library which is both generalized enough to work for all 32bit transputers and is then optimized for modules which require extended instructions sets the following approach is recommended:
1. Compile all modules for classes TA, T8 and T9000. This will provide modules which can be run on all 32bit transputers. 
2. If any of the modules perform floating point operations, compile these modules for class TB as well. 
For 16bit transputers it should be sufficient to compile all modules for class T2.
Library build targeted at specific transputer types
This method of building a library will limit the use of the library modules to specific transputer types and error modes. It is recommended as the simplest strategy to use when the following options are known for each module:
•	Target transputer type. 
•	Error mode of modules, if any, (i.e. HALT, STOP or UNIVERSAL).
•	Method of channel input/output, if any. 
All modules to be included in the library must be compiled for each target transputer type required and, if appropriate, for the same error mode and method of channel input/output. The resulting library may be large and contain a certain amount of duplication.
For example, for the following options:
•	T414 and T425 processor types
•	HALT error mode
•	channel input/output via library calls
each module should be compiled for the following:

Processor type/class 	Error mode	Method of channel I/O	
T414	HALT	Via library calls	
T425	HALT	Via library calls.	
Note: Error mode and channel i/o only apply only to modules which employ them e.g. occam modules compiled by oc.			

23.6	Error Messages
This section lists each error and warning message which may be generated by the librarian. Messages are in the standard toolset format which is explained in appendix A. 
23.6.1	Warning messages
filename  bad format: symbol symbol multiply exported
An identical symbol has occurred in the same file. There are three possibilities: 
The same file has been specified twice. 
The file was a library where previous warnings have been ignored.
A module in the file has been incorrectly generated. 
filename1  symbol symbol also exported by filename2
An identical symbol has occurred in more than one module. If the linker requires this symbol, it will never load the second module. 
23.6.2	Serious errors
bad format: reason
A module has been supplied to the librarian which does not conform to a recognized INMOS file format or has been corrupted. 
filename  line number  bad format: excessively long line in indirect file
A line is too long. The length is implementation dependent, and is set to 256 characters in this version.
filename  line number  bad format: file name missing after directive
A directive (such as INCLUDE) has no file name as an argument.
filename  line number  bad format: non ASCII character in indirect file
The indirect file contains some non printable text. A common mistake is to specify a library or module with the F command line argument or the INCLUDE directive. 
bad format: not a TCOFF file
The supplied file is not a library or module of any known type. 
filename  line number  bad format: only single parameter for directive
The directive has been given too many parameters. 
command line error token
An unrecognized token was found on the command line. 
filename  could not open for reading
The named file could not be found/opened for reading. 
filename1  line number  could not open filename2 for reading
The file specified in an INCLUDE directive could not be opened.
filename  could not open for writing 
The named file could not be opened for writing. 
filename  must not mix linked and linkable files
The librarian is capable of creating libraries from compiled modules or linked units, but it is illegal to attempt to create a library from both.
no files supplied
Options have been given to the librarian but no modules or libraries.
filename  nothing of importance in file
The file name specified in a library indirect file or in an INCLUDE directive was empty or contained nothing but white space or comments. 
filename  line number  only one file name per line
More than one file name has been placed on a single line within an indirect file. 
filename  line number  unrecognised directive directive
An unrecognized directive has been found in an indirect file.