doc/ref/libguile-linking.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, 2010, 2011
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @node Linking Programs With Guile
   8 @section Linking Programs With Guile
   9
  10 This section covers the mechanics of linking your program with Guile
  11 on a typical POSIX system.
  12
  13 The header file @code{<libguile.h>} provides declarations for all of
  14 Guile's functions and constants.  You should @code{#include} it at the
  15 head of any C source file that uses identifiers described in this
  16 manual.  Once you've compiled your source files, you need to link them
  17 against the Guile object code library, @code{libguile}.
  18
  19 @code{<libguile.h>} is not in the default search path for headers,
  20 because Guile supports parallel installation of multiple versions of
  21 Guile, with each version's headers under their own directories.  This is
  22 to allow development against, say, both Guile 2.0 and 2.2.
  23
  24 To compile code that includes @code{<libguile.h>}, or links to
  25 @code{libguile}, you need to select the effective version you are
  26 interested in, and then ask @code{pkg-config} for the compilation flags
  27 or linking instructions.  For effective version
  28 @value{EFFECTIVE-VERSION}, for example, you would invoke
  29 @code{pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}} to get
  30 the compilation and linking flags necessary to link to version
  31 @value{EFFECTIVE-VERSION} of Guile.  You would typically run
  32 @code{pkg-config} during the configuration phase of your program and
  33 use the obtained information in the Makefile.
  34
  35 See the @code{pkg-config} man page, for more information.
  36
  37 @menu
  38 * Guile Initialization Functions::  What to call first.
  39 * A Sample Guile Main Program::  Sources and makefiles.
  40 @end menu
  41
  42
  43 @node Guile Initialization Functions
  44 @subsection Guile Initialization Functions
  45
  46 To initialize Guile, you can use one of several functions.  The first,
  47 @code{scm_with_guile}, is the most portable way to initialize Guile.  It
  48 will initialize Guile when necessary and then call a function that you
  49 can specify.  Multiple threads can call @code{scm_with_guile}
  50 concurrently and it can also be called more than once in a given thread.
  51 The global state of Guile will survive from one call of
  52 @code{scm_with_guile} to the next.  Your function is called from within
  53 @code{scm_with_guile} since the garbage collector of Guile needs to know
  54 where the stack of each thread is.
  55
  56 A second function, @code{scm_init_guile}, initializes Guile for the
  57 current thread.  When it returns, you can use the Guile API in the
  58 current thread.  This function employs some non-portable magic to learn
  59 about stack bounds and might thus not be available on all platforms.
  60
  61 One common way to use Guile is to write a set of C functions which
  62 perform some useful task, make them callable from Scheme, and then link
  63 the program with Guile.  This yields a Scheme interpreter just like
  64 @code{guile}, but augmented with extra functions for some specific
  65 application --- a special-purpose scripting language.
  66
  67 In this situation, the application should probably process its
  68 command-line arguments in the same manner as the stock Guile
  69 interpreter.  To make that straightforward, Guile provides the
  70 @code{scm_boot_guile} and @code{scm_shell} function.
  71
  72 For more about these functions, see @ref{Initialization}.
  73
  74 @node A Sample Guile Main Program
  75 @subsection A Sample Guile Main Program
  76
  77 Here is @file{simple-guile.c}, source code for a @code{main} and an
  78 @code{inner_main} function that will produce a complete Guile
  79 interpreter.
  80
  81 @example
  82 /* simple-guile.c --- how to start up the Guile
  83    interpreter from C code.  */
  84
  85 /* Get declarations for all the scm_ functions.  */
  86 #include <libguile.h>
  87
  88 static void
  89 inner_main (void *closure, int argc, char **argv)
  90 @{
  91   /* module initializations would go here */
  92   scm_shell (argc, argv);
  93 @}
  94
  95 int
  96 main (int argc, char **argv)
  97 @{
  98   scm_boot_guile (argc, argv, inner_main, 0);
  99   return 0; /* never reached */
 100 @}
 101 @end example
 102
 103 The @code{main} function calls @code{scm_boot_guile} to initialize
 104 Guile, passing it @code{inner_main}.  Once @code{scm_boot_guile} is
 105 ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
 106 process the command-line arguments in the usual way.
 107
 108 Here is a Makefile which you can use to compile the above program.  It
 109 uses @code{pkg-config} to learn about the necessary compiler and
 110 linker flags.
 111 @example
 112 # Use GCC, if you have it installed.
 113 CC=gcc
 114
 115 # Tell the C compiler where to find <libguile.h>
 116 CFLAGS=`pkg-config --cflags guile-@value{EFFECTIVE-VERSION}`
 117
 118 # Tell the linker what libraries to use and where to find them.
 119 LIBS=`pkg-config --libs guile-@value{EFFECTIVE-VERSION}`
 120
 121 simple-guile: simple-guile.o
 122         $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
 123
 124 simple-guile.o: simple-guile.c
 125         $@{CC@} -c $@{CFLAGS@} simple-guile.c
 126 @end example
 127
 128 If you are using the GNU Autoconf package to make your application more
 129 portable, Autoconf will settle many of the details in the Makefile above
 130 automatically, making it much simpler and more portable; we recommend
 131 using Autoconf with Guile.  Here is a @file{configure.ac} file for
 132 @code{simple-guile} that uses the standard @code{PKG_CHECK_MODULES}
 133 macro to check for Guile.  Autoconf will process this file into a
 134 @code{configure} script.  We recommend invoking Autoconf via the
 135 @code{autoreconf} utility.
 136
 137 @example
 138 AC_INIT(simple-guile.c)
 139
 140 # Find a C compiler.
 141 AC_PROG_CC
 142
 143 # Check for Guile
 144 PKG_CHECK_MODULES([GUILE], [guile-@value{EFFECTIVE-VERSION}])
 145
 146 # Generate a Makefile, based on the results.
 147 AC_OUTPUT(Makefile)
 148 @end example
 149
 150 Run @code{autoreconf -vif} to generate @code{configure}.
 151
 152 Here is a @code{Makefile.in} template, from which the @code{configure}
 153 script produces a Makefile customized for the host system:
 154 @example
 155 # The configure script fills in these values.
 156 CC=@@CC@@
 157 CFLAGS=@@GUILE_CFLAGS@@
 158 LIBS=@@GUILE_LIBS@@
 159
 160 simple-guile: simple-guile.o
 161         $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
 162 simple-guile.o: simple-guile.c
 163         $@{CC@} -c $@{CFLAGS@} simple-guile.c
 164 @end example
 165
 166 The developer should use Autoconf to generate the @file{configure}
 167 script from the @file{configure.ac} template, and distribute
 168 @file{configure} with the application.  Here's how a user might go about
 169 building the application:
 170
 171 @example
 172 $ ls
 173 Makefile.in     configure*      configure.ac    simple-guile.c
 174 $ ./configure
 175 checking for gcc... ccache gcc
 176 checking whether the C compiler works... yes
 177 checking for C compiler default output file name... a.out
 178 checking for suffix of executables...
 179 checking whether we are cross compiling... no
 180 checking for suffix of object files... o
 181 checking whether we are using the GNU C compiler... yes
 182 checking whether ccache gcc accepts -g... yes
 183 checking for ccache gcc option to accept ISO C89... none needed
 184 checking for pkg-config... /usr/bin/pkg-config
 185 checking pkg-config is at least version 0.9.0... yes
 186 checking for GUILE... yes
 187 configure: creating ./config.status
 188 config.status: creating Makefile
 189 $ make
 190 [...]
 191 $ ./simple-guile
 192 guile> (+ 1 2 3)
 193 6
 194 guile> (getpwnam "jimb")
 195 #("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb"
 196   "/usr/local/bin/bash")
 197 guile> (exit)
 198 $
 199 @end example
 200
 201
 202 @c Local Variables:
 203 @c TeX-master: "guile.texi"
 204 @c End: