linuxmafia.com 2013/2013.06.linuxmafia.com/linuxmafia.com/pub/palmos/development/glib.txt

Text File | 2000-12-08 | 10.2 KB | 223 lines

GLib shared libraries for the Pilot

This document describes how to use gcc to create and use GLib shared
libraries on the Pilot. It is divided into seven sections:

   * What is a GLib shared library?
   * Upgrading gcc
   * Creating static libraries
   * Creating GLib shared libraries
   * Creating applications that use GLib shared libraries
   * Using applications that use GLib shared libraries
   * Conclusions

Comments are welcome; see the Conclusions section.

What is a GLib shared library?

Shared libraries enable many applications to share common code, without
having to have a copy of the code in each application's code resource. For
example, there can be one copy of encryption routines, or a version of the
standard C library, and many applications can be using it.

Shared libraries can also help you get around the 32K code size limit; you
can break up your code into a main portion (of at most 32K), and a number of
libraries (each of at most 32K).

GLib (pronounced ``gee-lib'') shared libraries are a way to implement shared
libraries on the Pilot that differs from the ``standard'' (SysLib) mechanism
for the Palm Pilot.

Some features of GLib:

   * GLib libraries work on the old Pilots as well as the Palm Pilots.
   * It is extremely easy to convert a static library into a GLib shared
     library, as well as to link an application to the GLib library.
   * GLib libraries can have static and global data (though they cannot, at
     this time, export global data to the calling application).
   * The common case is fast: no systraps are done to call a GLib shared
     library function after the library has been loaded, when globals are
     available.
   * The uncommon case is correct: GLib shared libraries work even when the
     application globals have not been loaded.

GLib libraries are implemented as resource databases, with a database type
of GLib, and a library-specific creator ID. The GLib library will usually
contain three resources: GLib 0 (the code), data 0 (the library globals),
and rloc 0 (the data relocation table). By contrast, an application if a
resource database with (usually) five resources: code 0, code 1, data 0,
rloc 0, and pref 0. The GLib 0 resource in a shared library corresponds
exactly to the code 1 resource in an application.

Upgrading gcc

Before going any further, you need to make sure that you have a recent
version of gcc. m68k-palmos-coff-gcc -v should report its version number to
be (at time of writing) 2.7.2.2-kgpd-071097. This is the version also known
as 0.5.0. If you are using an earlier version, you should certainly upgrade;
this version fixes quite a few problems, including handling of certain kinds
of global variables.

Creating static libraries

The first step in creating a GLib shared library is to create a ``static''
library (also called an ar archive). This is quite simple. First, compile
(but don't link) each of your .c files, with command lines like the
following:

m68k-palmos-coff-gcc -g -O2 -c file.c -o file.o

Actually, the ``-o file.o'' is optional. Also, the ``-O2'' can be left out
if you want to compile without optimization (the program is usually smaller
and faster with -O2, but sometimes it's harder to debug).

Once you have all of the .o files that will be part of your library, group
them together into a static library. For example, if your .o files are
file1.o, file2.o, and file3.o, and you want to call your library ``foo'',
you would use the command:

m68k-palmos-coff-ar rcs libfoo.a file1.o file2.o file3.o

The prefix ``lib'' and the suffix ``.a'' are mandatory in the name of the
library.

If you want to create a program that uses this static library, just write
your program normally, including calls to functions that you defined in your
library. When you link this program, just put -lfoo at the end of the
command. For example:

m68k-palmos-coff-gcc mainprog.o -o mainprog -lfoo

If you use a static library in this way, each program that uses the library
will have its own copy of the library embedded into it. If you want to share
the code for the library between all the programs that use it, you need to
turn your static library into a shared library.

Creating GLib shared libraries

Turning a static library into a GLib shared library is quite simple. First,
make sure your static library was compiled with the upgraded version of gcc
(above). Let's call this static library libfoo.a. We are going to create
FooLib.prc (the GLib shared library), as well as libfoo.sa, a ``stub''
library (much smaller than the static library) that will be linked to each
application that uses the GLib shared library.

You need to generate a list of the functions exported by your library; save
this list in a file called foo.exp. One way to do this is the following:

m68k-palmos-coff-exportlist libfoo.a > foo.exp

This is equivalent (on most systems) to the following command:

m68k-palmos-coff-nm libfoo.a | grep ' T ' | cut -c12- | sort -u > foo.exp

This will make foo.exp contain the list of functions exported by your
library, one per line. Note: the order of the functions listed in foo.exp is
important if you create a new version of the GLib library. Existing
functions should not change their positions in the list, and new functions
should be added to the end.

Next, you need to create two ``stub'' files. The command to do this for you
is:

m68k-palmos-coff-stubgen "Foo Library" FooL foostub.c FooLib.S < foo.exp

Here, "Foo Library" is the (human-readable) name for your library. FooL is
the four-character creator ID (you pick this yourself, but it's supposed to
be globally unique). foostub.c and FooLib.S are files that will be generated
by stubgen.

Now create FooLib.prc as follows:

m68k-palmos-coff-gcc -shared -o FooLib FooLib.S libfoo.a
     This creates FooLib by linking the stub FooLib.S to the static libfoo.a
     library. The -shared flag tells gcc to produce a shared library instead
     of a regular program. You may need to specify the full path to libfoo.a
     if it is not in the current directory.
m68k-palmos-coff-obj-res -l FooLib
     This extracts the GLib 0, data 0, and rloc 0 resources from FooLib.
     These resources contain the shared code, the global data, and the
     relocation information for the library, respectively.
build-prc -l FooLib.prc "Foo Library" FooL GLib0000.FooLib.grc
data0000.FooLib.grc rloc0000.FooLib.grc
     This command creates the FooLib.prc file by combining the GLib 0, data
     0, and rloc 0 resources. The library name ("Foo Library") and the
     creator ID (FooL) need to be the same as were specified to the
     m68k-palmos-coff-stubgen command. The -l option tells build-prc to
     build a GLib library instead of a normal program.

Finally, create the stub library libfoo.sa from foostub.c:

m68k-palmos-coff-gcc -c foostub.c
m68k-palmos-coff-ar rcs libfoo.sa foostub.o

That's it. FooLib.prc is the library users must install in order to use
programs that are linked to libfoo.sa. Distribute FooLib.prc to end users
and distribute libfoo.sa and the header files for libfoo.a to developers of
applications that could use the library.

Creating applications that use GLib shared libraries

Now that you have a GLib shared library and a stub library, how do you
change your application (that was previously linked to libfoo.a) to use the
shared library instead of the static one?

It's surprisingly simple; the application need not change at all. Just make
sure that libfoo.sa is visible to gcc when you link your program with -lfoo.
If gcc finds libfoo.sa instead of (or in addition to) libfoo.a, it will
cause the program to use the GLib shared library instead of the static one.
(Note: if you have both libfoo.sa and libfoo.a, gcc will prefer the shared
version. If you want to force it to use the static library, you can use the
-static flag to gcc.)

Note the current restriction on GLib libraries: library global variables are
not exported to the application. If your application needs to read or write
variables in the library's global space, you should consider modifying the
library to have access functions for them.

Another restriction: be careful if you pass function pointers around (say,
for callbacks). If a function is called via a function pointer, it will have
the globals of the caller, which would not be its own in the case that the
called function was in a shared lib, for example. In general, the rule is:
don't pass a function pointer to a GLib shared library function from a GLib
shared library to the main program, and have the main program call it.

Using applications that use GLib shared libraries

To use an application that requires a GLib shared library, just make sure
both the application and the library are installed on your Pilot before
running the application. GLib shared libraries are just prc files; they are
installed in exactly the same way as applications (HotSync or pilot-xfer,
for example).

If a GLib shared library is not installed, an application that uses it will
still run properly, until it tries to call a function provided by the
library (at which point you will get a Fatal Error informing you which
library you're missing).

Conclusions

Success and failure reports, comments, and questions are welcome. Depending
on the content, appropriate fora are the pilot.programmer and
pilot.programmer.gcc newsgroups hosted on news.massena.com, and the
pilot-unix mailing list at <[e-mail]>. If necessary, I can
be reached directly at the address below (be warned that my email queue
sometimes gets quite backlogged).

Back to the ISAAC Group's Pilot page
  ------------------------------------------------------------------------

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR
DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF,
EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS
PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO
OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
MODIFICATIONS.

Ian Goldberg, [e-mail]