doc/ref/libguile-extensions.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2011
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @node Linking Guile with Libraries
   8 @section Linking Guile with Libraries
   9
  10 The previous section has briefly explained how to write programs that
  11 make use of an embedded Guile interpreter.  But sometimes, all you
  12 want to do is make new primitive procedures and data types available
  13 to the Scheme programmer.  Writing a new version of @code{guile} is
  14 inconvenient in this case and it would in fact make the life of the
  15 users of your new features needlessly hard.
  16
  17 For example, suppose that there is a program @code{guile-db} that is a
  18 version of Guile with additional features for accessing a database.
  19 People who want to write Scheme programs that use these features would
  20 have to use @code{guile-db} instead of the usual @code{guile} program.
  21 Now suppose that there is also a program @code{guile-gtk} that extends
  22 Guile with access to the popular Gtk+ toolkit for graphical user
  23 interfaces.  People who want to write GUIs in Scheme would have to use
  24 @code{guile-gtk}.  Now, what happens when you want to write a Scheme
  25 application that uses a GUI to let the user access a database?  You
  26 would have to write a @emph{third} program that incorporates both the
  27 database stuff and the GUI stuff.  This might not be easy (because
  28 @code{guile-gtk} might be a quite obscure program, say) and taking this
  29 example further makes it easy to see that this approach can not work in
  30 practice.
  31
  32 It would have been much better if both the database features and the GUI
  33 feature had been provided as libraries that can just be linked with
  34 @code{guile}.  Guile makes it easy to do just this, and we encourage you
  35 to make your extensions to Guile available as libraries whenever
  36 possible.
  37
  38 You write the new primitive procedures and data types in the normal
  39 fashion, and link them into a shared library instead of into a
  40 stand-alone program.  The shared library can then be loaded dynamically
  41 by Guile.
  42
  43 @menu
  44 * A Sample Guile Extension::
  45 @end menu
  46
  47
  48 @node A Sample Guile Extension
  49 @subsection A Sample Guile Extension
  50
  51 This section explains how to make the Bessel functions of the C library
  52 available to Scheme.  First we need to write the appropriate glue code
  53 to convert the arguments and return values of the functions from Scheme
  54 to C and back.  Additionally, we need a function that will add them to
  55 the set of Guile primitives.  Because this is just an example, we will
  56 only implement this for the @code{j0} function.
  57
  58 Consider the following file @file{bessel.c}.
  59
  60 @smallexample
  61 #include <math.h>
  62 #include <libguile.h>
  63
  64 SCM
  65 j0_wrapper (SCM x)
  66 @{
  67   return scm_from_double (j0 (scm_to_double (x)));
  68 @}
  69
  70 void
  71 init_bessel ()
  72 @{
  73   scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
  74 @}
  75 @end smallexample
  76
  77 This C source file needs to be compiled into a shared library.  Here is
  78 how to do it on GNU/Linux:
  79
  80 @smallexample
  81 gcc `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` \
  82   -shared -o libguile-bessel.so -fPIC bessel.c
  83 @end smallexample
  84
  85 For creating shared libraries portably, we recommend the use of GNU
  86 Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
  87
  88 A shared library can be loaded into a running Guile process with the
  89 function @code{load-extension}.  In addition to the name of the
  90 library to load, this function also expects the name of a function from
  91 that library that will be called to initialize it.  For our example,
  92 we are going to call the function @code{init_bessel} which will make
  93 @code{j0_wrapper} available to Scheme programs with the name
  94 @code{j0}.  Note that we do not specify a filename extension such as
  95 @file{.so} when invoking @code{load-extension}.  The right extension for
  96 the host platform will be provided automatically.
  97
  98 @lisp
  99 (load-extension "libguile-bessel" "init_bessel")
 100 (j0 2)
 101 @result{} 0.223890779141236
 102 @end lisp
 103
 104 For this to work, @code{load-extension} must be able to find
 105 @file{libguile-bessel}, of course.  It will look in the places that
 106 are usual for your operating system, and it will additionally look
 107 into the directories listed in the @code{LTDL_LIBRARY_PATH}
 108 environment variable.
 109
 110 To see how these Guile extensions via shared libraries relate to the
 111 module system, @xref{Putting Extensions into Modules}.
 112
 113
 114 @c Local Variables:
 115 @c TeX-master: "guile.texi"
 116 @c End: