www.riscos.com Technical Support:
LibFile creates and maintains library archives. It can be used to create archives of files for backup and distribution purposes, for example. A special form of library archive containing AOF files can be created for use with Link. The format of library archive files is described in Code file formats.
Click Select on the application icon. This displays the SetUp dialogue box:
Library is the name of the library to be processed. If a library is being created this will be shaded. A Save as dialogue box will be presented when the library is created.
File List, when used with Create or Insert, contains the list of files to be placed in the library. When used with Delete or Extract it contains a list of files in the library which are to be extracted or deleted. You can use wildcard characters in the File List (* to match zero or more characters, and # to match a single character).
Create creates a new library containing the files in File List. This is the default option.
Delete removes the files in File List from the specified library.
Insert adds the files in File List to the specified library. Files of the same name in the library will be replaced.
Extract copies the files in File List from the specified library to disc. The files are not deleted from the library.
List library lists the files contained in the specified library. By default, this option is off.
Click Menu on the SetUp dialogue box. This displays the LibFile SetUp menu.
Command line allows you to specify the command line to be presented to the underlying LibFile command line tool. You should take care when modifying the command line. The effect of certain arguments depends on the order in which they appear in the command line. Changing this order may have unanticipated effects. Refer to the Command line interface.
Symbol table adds an external symbol table, as used by Link, to the library. External symbols in any object files in the library are placed in the symbol table. Non object files are ignored. By default, this option is on.
List symbol table lists the symbols in the external symbol table along with the name of the AOF file which generated each symbol. This option is off by default.
Via file allows you to set up a list of files to be used in one file called a Via file. When creating or maintaining libraries with a large number of files it may become tedious having to drag all the files to the File List every time, especially if they are in different directories. Enter the name of the Via file in the submenu and press Return.
The Output window displays the list of files in the library and/or the list of external symbols when the List library or List symbol table options are selected. The following windows show examples of each.
LibFile provides the Null timestamps option to circumvent this problem. The Null timestamps option uses timestamps of all bits 0, which corresponds to a date of 00:00:00 01-Jan-1900. Thus, libraries built at different times can be compared using a binary comparison utility, without the timestamps causing extraneous differences to appear.
For normal use you do not need to understand the syntax of the LibFile command line, as it is automatically generated for you from the SetUp dialogue box settings.
The format of the LibFile command is:
Libfile options library [file_list]
Wildcards * and # may be used in file_list.
|-h||Display a screen of help text|
|-c||Create a new library containing files in file_list|
|-i||Insert files in file_list, replace existing members|
|-d||Delete the members in file_list|
|-e||Extract members in file_list placing in files of the same name|
|-o||Add an external symbol table to an object library|
|-l||List library, may be specified with any other option|
|-s||List symbol table, may be specified with any other option|
|-t||Use Null timestamps when creating or updating library|
|-v file||Take additional arguments from file|
|-q dir||Place relative filenames in dir when extracting file|
When extracting files with relative pathnames, LibFile creates this directory if it does not already exist and prefixes the relative pathnames with the specified directory. Note, that you should not add a full stop (.) to the end of the directory specification, LibFile adds this itself.
LibFile -c srclib *
Create a library called srclib in the current directory from all the files in the current directory (including the files contained in any directories in the current directory).
LibFile -co adfs::Edward.$.clib.o.AnsiLib o
Create the object library AnsiLib from the object files contained in directory o in the current directory.
Libfile -e -q :Ian.$.PDUtils :0.PDLib *
Extract all the files from :0.PDLib and put them in the directory :Ian.$.PDUtils.
The programming example PrintLib, which you can find in Examples.PrintLib, consists of three potentially useful procedures written in assembler which are intended to be assembled to object files using ObjAsm and then formed into a library with LibFile. They illustrate various programming points as well as how to construct a library.
If you examine the assembler source files in Examples.PrintLib.s you will see that the procedure exported by each file obeys the ARM Procedure Call Standard. This ensures that they, and hence the PrintLib library, can be linked with other languages such as C. It is essential that procedures placed in a library have consistent register conventions, so that they can be re-used later without consulting their source text.
The PrintLib example is provided with both its assembly language source and the finished library. The facilities provided by this library are used in other programming examples. The procedures it exports are:
|print_string||Print a null terminated string pointed to by r0.|
|print_hex||Print in hexadecimal an integer contained in r0.|
|print_double||Print in scientific format a double precision floating point number contained in r0,r1.|
To reconstruct PrintLib from its sources, first double click on !ObjAsm and !LibFile in a directory display to load them as applications with icons on the icon bar. Then assemble s.PrintStr, s.PrintHex and s.PrintDble to corresponding object files by dragging each source file to the ObjAsm icon and saving the output object files in the default places, i.e. o.PrintStr, o.PrintHex and o.PrintDble.
Next drag o.PrintStr to the LibFile icon to make the LibFile SetUp dialogue box appear:
Ensure that the Create option is chosen as above. Drag the other two object files to File List, then click on Run. Finally save the library file produced: it is now ready to use.
The assembly language source file Examples.PrintLib.s.ATestPrLib is an example program making use of the procedures exported by PrintLib. To use it:
Running the test program by double clicking on it should result in text output into a RISC OS output window: