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