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:
- Opening of ExShLib in StartApplication,
- Closing of ExShLib on StopApplication, and
- Calling the two functions in slHandler when COMPUTEID is executed.
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/