Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

4    Using the Palm OS Librarian

Palm OS® Protein C/C++ Compiler Tools Guide

Palm OS® Developer Suite

The Palm OS librarian, palib, is a tool that you use to create and manage a collection of ELF object files. palib creates library files that conform to the Unix 'ar' archive file format.

Using the palib Command Line Tool ^TOP^

With palib, you can do all of the following tasks:

Creating a New Archive Library ^TOP^

To create an archive library, you specify the option -create:

palib -create myLib.l

This command creates an empty library file with the name myLib.l.

As an alternative, you can create a library using the option -add:

palib -add myLib.l TestMain.o 

This command creates myLib.l if it doesn't exist, and then adds TestMain.o to myLib.l.

Adding an ELF Object File to a Library ^TOP^

To add an ELF object file to an archive library, you specify the option -add:

palib -add myLib.l TestsCode.o

This command adds TestsCode.o to myLib.l if it already exists, or creates myLib.l and adds TestsCode.o if the library file doesn't already exist.


NOTE: If the ELF object file is already a member of the library, then palib displays an error message and the file is not added to the library.

You can specify multiple ELF object files in one add request.

Deleting an ELF Object File from a Library ^TOP^

To remove an ELF object file from an archive library, you specify the option -delete:

palib -delete myLib.l TestsCode.o

This command deletes TestsCode.o from myLib.l.

You can specify multiple ELF object files in one delete request.

Replacing an ELF Object File in a Library ^TOP^

To replace an ELF object file in an archive library, you specify the option -replace:

palib -replace myLib.l TestsPlug.o

If the ELF object file TestsPlug.o is in the library myLib.l, this command replaces the TestsPlug.o file. If TestsPlug.o is not already in the library file, the command simply adds TestsPlug.o to myLib.l.

You can specify multiple ELF object files in one replace request.

Extracting an ELF Object Files from a Library ^TOP^

To extract an ELF object file from an archive library, you specify the option -extract:

palib -extract myLib.l TestsCode.o

If the ELF object file TestsCode.o is in the library myLib.l, this command extracts the TestsCode.o file to the local directory.

You can specify multiple ELF object files in one extract request.


WARNING! If the local directory already has a file by the same name as the one you are extracting, palib overwrites the existing file with the one extracted from the library file.

Displaying the Contents of a Library ^TOP^

To display a list of object files in a library, you specify the option
-toc:

palib -toc TestLib.L 

The output shows the list of object files in the order that you added them to the library.

Listing 4.1  Sample output from the option -toc


TestsLib_Startup.o 
TestsPlug.o 
TestsRendering.o 
TestsCode.o 
Tests.o 
TestsLibMain.o 

To display a list of symbols in the library, you specify the option
-symtab:

palib -symtab TestLib.L 

The output shows the list of symbols in the order in which they appear in the ELF object files.

Listing 4.2  Sample output from the option -symtab


__user_libspace                from TestsLib_Startup.o   at offset 1474 
$Sub$$TestSetFormId            from TestsLib_Startup.o   at offset 1474 
$Sub$$TestSetFormPtr           from TestsLib_Startup.o   at offset 1474 
$Sub$$TestSetGadgets           from TestsLib_Startup.o   at offset 1474 
RenderDefineRoundRect          from TestsRendering.o     at offset 27e9e 
RenderRawBitmapLabel           from TestsRendering.o     at offset 27e9e 
RenderGetTextHeight            from TestsRendering.o     at offset 27e9e 
PrvTestGadgetTabsBodyCallBack  from TestsCode.o          at offset 45172 
PrvTestUpdateScrollFlag        from TestsCode.o          at offset 45172 
TestSetFlags                   from Tests.o              at offset 651e6 
TestGetTextColors              from Tests.o              at offset 651e6 
TestSetEnableUpdate            from Tests.o              at offset 651e6 
TestGetTabGraphics             from Tests.o              at offset 651e6 
TestsLibMain                   from TestsLibMain.o       at offset 8c51a 

To display a list of entry points defined in the library, you specify the option -entries:

palib -entries TestLib.L 

The output shows the list of entries in the order in which they appear in the ELF object files.

Listing 4.3  Sample output from the option -entries


ENTRY at offset 0 in section startup_code_header_area of TestsLib_Startup.o  
ENTRY at offset 0 in section startup_code_header_area of SampleLib_Startup.o  

palib Reference ^TOP^

This section provides reference information for the palib tool.

Librarian Command Line Interface ^TOP^

The general format of the palib command line interface is this:

palib [options] libraryName [elfFileList] 
options
palib options, as described in the section "Librarian Options."
libraryName
The name of the library (.L) file. If the library file exists, then palib will use the library specified; if the library file does not exist, then palib will create the file.
elfFileList
A list of ELF object files.

Librarian Options ^TOP^

-add | -a
palib adds the ELF object files specified by elfFileList to the library.
-create | -c
palib creates a new library, overwriting any existing library with the same name.
-delete | -d
palib deletes the files specified by elfFileList from the library.
-entries | -e
palib displays a list of entry points defined in a library.
-extract | -x
palib extracts the files specified by elfFileList from the library.
-help | -h
palib prints a summary of help.
-replace | -r
palib replaces the files specified by elfFileList in a library. If a file does not already exist, it will simply be added.
-symtab | -s
palib displays a table of all symbols and where they reside in the library.
-toc | -t
palib displays the table of contents of the library.
-V
palib writes the its version numbers to stderr, and exits without performing any further actions.
-via filename
palib reads the file filename for more options.