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

5    Using the Palm OS Shared Library Tool

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

Palm OS® Developer Suite

This chapter describes how you can use pslib, the Palm OS shared library tool, to define the entry point and exports for Palm OS applications and shared libraries.

Palm OS Shared Library Tool Concepts ^TOP^

The Palm OS shared library tool pslib is essential for building Palm OS applications and shared libraries. Chapter 1, "Understanding Palm OS Application Development," provides an overview of the entire process for building Palm OS applications and shared libraries, and describes how pslib fits in the overall process.

This is the process for using pslib:

  1. First, create a shared library definition (SLD) file. (See Chapter 7, "Shared Library Definition File Format Reference," for information on creating SLD files.)
  2. Then use pslib to convert your SLD file into object files targeted for execution either on Palm OS devices or on Palm OS Simulator.

    For more information about Palm OS device targets, see the section "Building Files for Device Targets."

    For more information about Palm OS Simulator targets, see the section "Building Files for Palm OS Simulator Targets."

  3. Link the startup object file created by pslib with your compiled code object files to produce your application or shared library.
  4. Link the stub object file created by pslib with an application that calls a function exported by your shared library.

Building Files for Device Targets ^TOP^

Figure 5.1 shows the files that pslib produces for ARM-based device targets. When you build code to run on ARM-based devices, you need to link the Palm OS startup object file with the code you compile with the Palm OS compiler.

Figure 5.1  pslib Overview for Device Targets

Building Files for Palm OS Simulator Targets ^TOP^

Figure 5.2 shows the files that pslib produces for Palm OS Simulator targets. When you build code to run on Palm OS Simulator, you need to link the startup object file with the code you compile with the gcc compiler for x86.

Figure 5.2  pslib Overview for Palm OS Simulator Targets

Using pslib with Palm OS Developer Suite ^TOP^

pslib is fully integrated with Palm OS Developer Suite. When you build your application or shared library with Palm OS Developer Suite, pslib is called as part of the build process. You do not need to invoke pslib directly.

Using the pslib Command Line Tool ^TOP^

pslib is used to compile a shared library definition file (SLD) into binary resource files that can be linked into a Palm OS shared library or Palm OS application.

The command line syntax for pslib is:

pslib -inDef filename [options] 
-inDef [none | filename ]
The -inDef parameter is required, with either a filename or the value none.
none
When the value none is specified, no shared library definition file is required. All information is taken from the remaining command line options.
filename
The filename of the input shared library definition file. The input SLD file must conform to the format described in Chapter 7, "Shared Library Definition File Format Reference."
options
Additional command line options as described in the following section "Specifying Command Line Options."

Specifying Command Line Options ^TOP^

-ARMarch [4T | 5T | 5TE | 0]
This parameter specifies the minimum required ARM architecture to load this library. (This parameter does not apply to targets built for Palm OS Simulator.)
If you specify this optional parameter, it overrides the ARMARCH keyword in the SLD file.
pslib issues a warning message when this command line option and the SLD file value are different.
-creator four_character_code
four_character_code specifies a 4-byte resource type.
If you specify this optional parameter, it overrides the creator specification in the SLD file. pslib issues a warning message when this command line option and the SLD file value are different.
-entry entryName
entryName specifies the name of the primary entry point.
If you specify this optional parameter, it overrides the ENTRY keyword in the SLD file. pslib issues a warning message when this command line option and the SLD file value are different.
-execName executableName
executableName overrides the name of the SLD file as the default base of the executable filename (the filename used for locating DLL with Palm OS Simulator.)
This parameter is optional unless the -inDef parameter specified none.
-help | -h
pslib displays help information and ignores any other options.
-OSversion versionnumber
versionnumber specifies the minimum required version of Palm OS to load this library. If you don't specify this option, Palm OS Cobalt 6.0 is assumed.
If you specify this optional parameter, it overrides the OSVERSION keyword in the SLD file.
pslib issues a warning message when this command line option and the SLD file value are different.
-outEntryNums filename
filename specifies the output C/C++ header file with enumerations (enum) and defines (#define) for each module entry point.
-outErrors filename
filename specifies the name of a file to which you want pslib to write error messages.
-outObjStartup filename
filename specifies the output startup object filename for a Palm OS device target build.
-outObjStubs filename
filename specifies the output stubs object filename for a Palm OS device target build.
-outSimDefs filename
filename specifies the output linker definition filename for a Palm OS Cobalt Simulator target build.
-outSimgcc filename
filename specifies the gcc-compatible output object file. When you use this option, the startup, stub and linker definition files generated are also generated as gcc-compatible files.
-outSimRsrc filename
filename specifies the output acod resource file for a Palm OS Cobalt Simulator target build.
-outSimStartup filename
filename specifies the output startup object filename for a Palm OS Cobalt Simulator target build.
-outSimStubs filename
filename specifies the output stubs object filename for a Palm OS Cobalt Simulator target build.
-patchable [0 | 1]
If you specify this optional parameter, it overrides the PATCHABLE keyword in the SLD file.
0
By default, an exported function is unpatchable.
1
By default, an exported function is patchable.
pslib issues a warning message when this command line option and the SLD file value are different.
-revision integer
integer specifies a revision number.
If you specify this optional parameter, it overrides the REVISION keyword in the SLD file. pslib issues a warning message when this command line option and the SLD file value are different.
-rsrcID integer
integer specifies a resource ID.
If you specify this optional parameter, it overrides the RESOURCEID keyword in the SLD file. pslib issues a warning message when this command line option and the SLD file value are different.
-type four_character_code
four_character_code specifies a 4-byte resource type.
If you specify this optional parameter, it overrides the type specification in the input SLD file. pslib issues a warning message when this command line option and the SLD file value are different.
-V
pslib displays the version information and exits.

NOTE: At least one output file (device target or Palm OS Cobalt Simulator target) must be specified or pslib issues an error message.