How To Make Your Own Shared Library for the Palm
These examples only compile with the old GCC Palm Compiler m68k-palmos-coff-gcc V0.5.0.
A version for Prc-Tools will be available here soon.

Introduction

I wanted to learn how to create a shared library so that my RiseSet and Earth&S applications could share the large routines for computing the right ascension and declination for the sun and moon. This would free space for Riseset to add other features.
In this article I will give you a set of two C programs: a shared library and a calling application, along with the make files and an auxiliary program. This should be enough to created your own shared library.
The assumed complier is GCC.

The starting point for creating your own shared library is an article by Ian Goldberg of Berkeley's ISAAC Group for the excellent treatise on Pilot shared libraries. The article is quite complete, but there are two error that will through you off. I suggest that first you read Goldberg's article and then follow this article, build the calling application "Example Shared Library Test": ExShLibTest.c, and the "Example Shared Library": ExShlib.c.

This Example Shared Library

Supplied in the archive are:
ExShLib.c
The source of example shared library.
ExShLib.h
The header of example shared library.
ExShLibDef.c
The source of example shared library function definition application.
appl2libr.c
The source of appl2libr -- a application to change the resource type.
appl2libr.exe
The compiled version of appl2libr.c.
ExShLib.mak
The make file for example shared library.
ExShLibTest.c
The source of example shared library test application.
ExShLibTest.rcp
The resource file of example shared library test application.
ExShLibTest.rh
The resource file header of example shared library test application.
ExShLibTest.mak
The make file for example shared library test application.
ExSharedLib.html
This file.
exshlib.bmp
A bitmap for ExShLibTest.
Required files not supplied in the archive are: In this example, the two functions in the shared library are: sum of the squares of two quantities, and the square root of the sum of the squares of two quantities. These were selected because they are simple functions yet need floating point, and therefore the use of MathLib.

Following each of the files in the archive are discussed.

ExShLib.c -- The shared library

Looking at ExShLib.c note that there are 8 routines:
start
The jump table that manages this library's traps.
install_dispatcher
The connection to the OS
ExShLib_open
Whatever your library need to do when it is opened in the calling application.
In this example we need to open MathLib, and create two "global variables". Since no globals variables (in the usual sense of a C program) are allowed in a shared library, the OS provides a means of linking dynamic memory to the shared library in the SysLibTblEntry() area. This link can be retrieved by shared library routines as needed. We need to keep the use count for this library and the reference number of MathLib.
ExShLib_close
Whatever your library need to do when it is closed in the calling application.
In this example we need to close MathLib.
ExShLib_sleep
Whatever your library need to do when OS goes to sleep.
In this example nothing is needed.
exshlib_wake
Whatever your library need to do when OS wakes up.
In this example nothing is needed.
exshlib_sumsqr
The routine to compute the sum of the squares of a and b.
ExShLib_sqrtSumSqr
The routine to compute the square root of the sum of the squares of A and B.
Your shared library will have 6 routines plus the routines of the shared library.

ExShLib.h

ExShLib.h defines the routines of the shared library. The important thing to notice is that the names of the routine are not exactly the same as in ExShLib.c. They are associated with each other via the traps, and should not be named the same as it will confuse the linker.
Note that the creators used in these example programs are not registered.

ExShLibDef.c

ExShLibDef.c is a programs that defines the format of the libraries two functions. It must be compiled (or at least linked) when the calling application is created. (See ExShLibTest.mak.)

appl2libr.c and appl2libr.exe

When compiled with the make file: ExShLib.mak, build-prc assumes the database it creates is of type 'appl'. Shared libraries should be of type 'libr'. So Ian Goldberg provides us with a program to change this. Both the source and DOS executable version of appl2libr is provide for your convenience.

ExShLib.mak

ExShLib.mak is the make file for the shared library. Note that it is quite different than a normal application make file. The most important difference is the compile flags: -shared -nostartfiles. In Ian Goldberg's shllib.html the -nosatartfiles is missing.

ExShLibTest.* -- The testing application

The files ExShLibTest.* files create a little Palm application to test the example shared library. Once you test check out Example Shared Library you might want to use it as a test for the function you put in your library.

There is nothing special in this test application other than:

ExShLibTest.mak

ExShLibTest.mak is the make file for the shared library test application. It is a standard make file. Note OBJS include ExShLibDef.o as discussed above.

Contact Information

ExShLib and ExShLibTest was created by David W. Bray, Potsdam, NY;
Copyright 2000 David W. Bray, All Rights Reserved.
The author may be contacted at: bray@davidbray.org

The Bray PalmPilot Page can be found at: http://www.40-below.com/palm/