www.riscos.com Technical Support: DDE (Desktop Development Environment)

LibFile

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.

The SetUp dialogue box

Click Select on the application icon. This displays the SetUp dialogue box:

The SetUp options

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.

The SetUp menu

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.

Output

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.

Notes:

1. Any directories in the File List to be archived will be recursively archived (i.e. all files in the specified directory will be archived and any directories in the specified directory will themselves be recursively archived). This can be useful if, for example, you are backing up an entire source tree on which you are currently working.
2. When extracting files, LibFile places absolute filenames from the libraries index in their corresponding absolute filenames on disc. Relative filenames (i.e. those not containing a colon (:) a dollar ($) or an at sign (@)) are placed in a temporary directory and, when the extraction is finished, a Save as dialogue box is presented. This allows you to drag the extracted files to a suitable place on your disc. The temporary directory is then renamed to the correct place on your disc, or copied and subsequently deleted if you drag to a different device or filing system.
3. When creating libraries for distribution purposes, you should not use absolute filenames in the File List. If, for example, you created a library with a File List of adfs::Edward.$.PDUtils, it would not be very useful to someone called Ian or to someone using an Econet network. Instead, set your current directory (from the command line with the *Dir command) to adfs::Edward.$ and use the File List PDUtils.
4. When creating libraries for backup purposes, you can use absolute filenames, since you will always be restoring to your own disc. You should not, however, mix absolute and relative filenames in the same library. LibFile will handle this as described in the note on extracting files above, but the behaviour may be confusing to anyone trying to extract files.
5. When creating a library, LibFile builds the library in memory. This means that you cannot create a library bigger than the available memory on your machine. When altering an existing library (using Insert or Delete) Libfile requires memory space for the new and old libraries. If there is not enough memory for this you can get around the problem by extracting all the files and recreating the library including the files to be inserted, or omitting the files to be deleted.
6. When the Symbol table option is selected, LibFile always updates the external symbol table regardless of the operation being performed. This is correct for Create, Insert and Delete. For Extract this is usually not very useful, so you should generally ensure the Symbol table option is deselected when using Extract.
7. If the Symbol table option is not selected, LibFile deletes the external symbol table when used with Insert or Delete. This prevents a potential problem whereby the external symbol table could become out of date with respect to the object modules in the library.
8. Convergence testing is a testing method whereby a binary file (such as an object library) is rebuilt using itself, and the new and old binaries are compared to ensure that they are the same. This can be difficult with tools (such as LibFile) which timestamp files placed in the library, because the new and old libraries will be built at different times, and will always differ.

   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.

9. Wildcard matching, when applied to library members (when using Extract or Delete) applies the wildcard across the complete filename. When applied to files (Create or Insert) wildcards apply to single components of the filename. Thus, the wildcard specification a#c would match a.b and abc when using Extract or Delete, but would only match abc when using Create or Insert.

Command line interface

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.

Options

-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

Notes:

1. Multiple options may be specified in a single options argument. For example, -clso is equivalent to -c -l -s -o.
2. Most of the above options should be familiar from the description of the desktop interface. One possible exception to this is the -q option. This option means 'behave as though the directory specified after the -q option were the current working directory (as set by the dir command)'.

   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.

3. The -q option is used by the desktop interface (since the desktop has no notion of a current working directory) to tell LibFile where to put files with relative pathname (generally <Wimp$ScrapDir>Tmp_name where Tmp_name is a name invented by the desktop interface). This directory is then renamed, or copied to a user-specified directory.
4. For compatibility with previous versions of LibFile, specifying -c with -o with a null file list does not create an empty library. Instead, it ignores the -c option and adds a symbol table to an existing library.

Examples

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.

Assembler example

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:

1. Double click on the !Link application to load it.
2. Assemble s.ATestPrLib to o.ATestPrLib with ObjAsm.
3. Link o.ATestPrLib with the finished PrintLib library to produce an executable AIF image file.

Running the test program by double clicking on it should result in text output into a RISC OS output window: