home *** CD-ROM | disk | FTP | other *** search
/ linuxmafia.com 2016 / linuxmafia.com.tar / linuxmafia.com / pub / palmos / development / glib.txt < prev    next >
Text File  |  2000-12-07  |  10KB  |  223 lines
  1. GLib shared libraries for the Pilot
  2.  
  3. This document describes how to use gcc to create and use GLib shared
  4. libraries on the Pilot. It is divided into seven sections:
  5.  
  6.    * What is a GLib shared library?
  7.    * Upgrading gcc
  8.    * Creating static libraries
  9.    * Creating GLib shared libraries
  10.    * Creating applications that use GLib shared libraries
  11.    * Using applications that use GLib shared libraries
  12.    * Conclusions
  13.  
  14. Comments are welcome; see the Conclusions section.
  15.  
  16. What is a GLib shared library?
  17.  
  18. Shared libraries enable many applications to share common code, without
  19. having to have a copy of the code in each application's code resource. For
  20. example, there can be one copy of encryption routines, or a version of the
  21. standard C library, and many applications can be using it.
  22.  
  23. Shared libraries can also help you get around the 32K code size limit; you
  24. can break up your code into a main portion (of at most 32K), and a number of
  25. libraries (each of at most 32K).
  26.  
  27. GLib (pronounced ``gee-lib'') shared libraries are a way to implement shared
  28. libraries on the Pilot that differs from the ``standard'' (SysLib) mechanism
  29. for the Palm Pilot.
  30.  
  31. Some features of GLib:
  32.  
  33.    * GLib libraries work on the old Pilots as well as the Palm Pilots.
  34.    * It is extremely easy to convert a static library into a GLib shared
  35.      library, as well as to link an application to the GLib library.
  36.    * GLib libraries can have static and global data (though they cannot, at
  37.      this time, export global data to the calling application).
  38.    * The common case is fast: no systraps are done to call a GLib shared
  39.      library function after the library has been loaded, when globals are
  40.      available.
  41.    * The uncommon case is correct: GLib shared libraries work even when the
  42.      application globals have not been loaded.
  43.  
  44. GLib libraries are implemented as resource databases, with a database type
  45. of GLib, and a library-specific creator ID. The GLib library will usually
  46. contain three resources: GLib 0 (the code), data 0 (the library globals),
  47. and rloc 0 (the data relocation table). By contrast, an application if a
  48. resource database with (usually) five resources: code 0, code 1, data 0,
  49. rloc 0, and pref 0. The GLib 0 resource in a shared library corresponds
  50. exactly to the code 1 resource in an application.
  51.  
  52. Upgrading gcc
  53.  
  54. Before going any further, you need to make sure that you have a recent
  55. version of gcc. m68k-palmos-coff-gcc -v should report its version number to
  56. be (at time of writing) 2.7.2.2-kgpd-071097. This is the version also known
  57. as 0.5.0. If you are using an earlier version, you should certainly upgrade;
  58. this version fixes quite a few problems, including handling of certain kinds
  59. of global variables.
  60.  
  61. Creating static libraries
  62.  
  63. The first step in creating a GLib shared library is to create a ``static''
  64. library (also called an ar archive). This is quite simple. First, compile
  65. (but don't link) each of your .c files, with command lines like the
  66. following:
  67.  
  68. m68k-palmos-coff-gcc -g -O2 -c file.c -o file.o
  69.  
  70. Actually, the ``-o file.o'' is optional. Also, the ``-O2'' can be left out
  71. if you want to compile without optimization (the program is usually smaller
  72. and faster with -O2, but sometimes it's harder to debug).
  73.  
  74. Once you have all of the .o files that will be part of your library, group
  75. them together into a static library. For example, if your .o files are
  76. file1.o, file2.o, and file3.o, and you want to call your library ``foo'',
  77. you would use the command:
  78.  
  79. m68k-palmos-coff-ar rcs libfoo.a file1.o file2.o file3.o
  80.  
  81. The prefix ``lib'' and the suffix ``.a'' are mandatory in the name of the
  82. library.
  83.  
  84. If you want to create a program that uses this static library, just write
  85. your program normally, including calls to functions that you defined in your
  86. library. When you link this program, just put -lfoo at the end of the
  87. command. For example:
  88.  
  89. m68k-palmos-coff-gcc mainprog.o -o mainprog -lfoo
  90.  
  91. If you use a static library in this way, each program that uses the library
  92. will have its own copy of the library embedded into it. If you want to share
  93. the code for the library between all the programs that use it, you need to
  94. turn your static library into a shared library.
  95.  
  96. Creating GLib shared libraries
  97.  
  98. Turning a static library into a GLib shared library is quite simple. First,
  99. make sure your static library was compiled with the upgraded version of gcc
  100. (above). Let's call this static library libfoo.a. We are going to create
  101. FooLib.prc (the GLib shared library), as well as libfoo.sa, a ``stub''
  102. library (much smaller than the static library) that will be linked to each
  103. application that uses the GLib shared library.
  104.  
  105. You need to generate a list of the functions exported by your library; save
  106. this list in a file called foo.exp. One way to do this is the following:
  107.  
  108. m68k-palmos-coff-exportlist libfoo.a > foo.exp
  109.  
  110. This is equivalent (on most systems) to the following command:
  111.  
  112. m68k-palmos-coff-nm libfoo.a | grep ' T ' | cut -c12- | sort -u > foo.exp
  113.  
  114. This will make foo.exp contain the list of functions exported by your
  115. library, one per line. Note: the order of the functions listed in foo.exp is
  116. important if you create a new version of the GLib library. Existing
  117. functions should not change their positions in the list, and new functions
  118. should be added to the end.
  119.  
  120. Next, you need to create two ``stub'' files. The command to do this for you
  121. is:
  122.  
  123. m68k-palmos-coff-stubgen "Foo Library" FooL foostub.c FooLib.S < foo.exp
  124.  
  125. Here, "Foo Library" is the (human-readable) name for your library. FooL is
  126. the four-character creator ID (you pick this yourself, but it's supposed to
  127. be globally unique). foostub.c and FooLib.S are files that will be generated
  128. by stubgen.
  129.  
  130. Now create FooLib.prc as follows:
  131.  
  132. m68k-palmos-coff-gcc -shared -o FooLib FooLib.S libfoo.a
  133.      This creates FooLib by linking the stub FooLib.S to the static libfoo.a
  134.      library. The -shared flag tells gcc to produce a shared library instead
  135.      of a regular program. You may need to specify the full path to libfoo.a
  136.      if it is not in the current directory.
  137. m68k-palmos-coff-obj-res -l FooLib
  138.      This extracts the GLib 0, data 0, and rloc 0 resources from FooLib.
  139.      These resources contain the shared code, the global data, and the
  140.      relocation information for the library, respectively.
  141. build-prc -l FooLib.prc "Foo Library" FooL GLib0000.FooLib.grc
  142. data0000.FooLib.grc rloc0000.FooLib.grc
  143.      This command creates the FooLib.prc file by combining the GLib 0, data
  144.      0, and rloc 0 resources. The library name ("Foo Library") and the
  145.      creator ID (FooL) need to be the same as were specified to the
  146.      m68k-palmos-coff-stubgen command. The -l option tells build-prc to
  147.      build a GLib library instead of a normal program.
  148.  
  149. Finally, create the stub library libfoo.sa from foostub.c:
  150.  
  151. m68k-palmos-coff-gcc -c foostub.c
  152. m68k-palmos-coff-ar rcs libfoo.sa foostub.o
  153.  
  154. That's it. FooLib.prc is the library users must install in order to use
  155. programs that are linked to libfoo.sa. Distribute FooLib.prc to end users
  156. and distribute libfoo.sa and the header files for libfoo.a to developers of
  157. applications that could use the library.
  158.  
  159. Creating applications that use GLib shared libraries
  160.  
  161. Now that you have a GLib shared library and a stub library, how do you
  162. change your application (that was previously linked to libfoo.a) to use the
  163. shared library instead of the static one?
  164.  
  165. It's surprisingly simple; the application need not change at all. Just make
  166. sure that libfoo.sa is visible to gcc when you link your program with -lfoo.
  167. If gcc finds libfoo.sa instead of (or in addition to) libfoo.a, it will
  168. cause the program to use the GLib shared library instead of the static one.
  169. (Note: if you have both libfoo.sa and libfoo.a, gcc will prefer the shared
  170. version. If you want to force it to use the static library, you can use the
  171. -static flag to gcc.)
  172.  
  173. Note the current restriction on GLib libraries: library global variables are
  174. not exported to the application. If your application needs to read or write
  175. variables in the library's global space, you should consider modifying the
  176. library to have access functions for them.
  177.  
  178. Another restriction: be careful if you pass function pointers around (say,
  179. for callbacks). If a function is called via a function pointer, it will have
  180. the globals of the caller, which would not be its own in the case that the
  181. called function was in a shared lib, for example. In general, the rule is:
  182. don't pass a function pointer to a GLib shared library function from a GLib
  183. shared library to the main program, and have the main program call it.
  184.  
  185. Using applications that use GLib shared libraries
  186.  
  187. To use an application that requires a GLib shared library, just make sure
  188. both the application and the library are installed on your Pilot before
  189. running the application. GLib shared libraries are just prc files; they are
  190. installed in exactly the same way as applications (HotSync or pilot-xfer,
  191. for example).
  192.  
  193. If a GLib shared library is not installed, an application that uses it will
  194. still run properly, until it tries to call a function provided by the
  195. library (at which point you will get a Fatal Error informing you which
  196. library you're missing).
  197.  
  198. Conclusions
  199.  
  200. Success and failure reports, comments, and questions are welcome. Depending
  201. on the content, appropriate fora are the pilot.programmer and
  202. pilot.programmer.gcc newsgroups hosted on news.massena.com, and the
  203. pilot-unix mailing list at <pilot-unix@lists.best.com>. If necessary, I can
  204. be reached directly at the address below (be warned that my email queue
  205. sometimes gets quite backlogged).
  206.  
  207. Back to the ISAAC Group's Pilot page
  208.   ------------------------------------------------------------------------
  209.  
  210. IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR
  211. DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
  212. OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF,
  213. EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  214.  
  215. THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
  216. INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
  217. FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS
  218. PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO
  219. OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
  220. MODIFICATIONS.
  221.  
  222. Ian Goldberg, iang@cs.berkeley.edu
  223.