guile/guile-core/doc intro.texi

[Marius Vollmer]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Marius Vollmer <address@hidden> 01/03/11 16:50:08

Modified files:
        guile-core/doc : intro.texi 

Log message:
        * intro.texi: Changed to reflect current practice better.  Added
        stuff about writing Guile Extensions (aka dynamically loaded
        shared libraries).

CVSWeb URLs:
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/doc/intro.texi.diff?r1=1.1&r2=1.2

Patches:
Index: guile/guile-core/doc/intro.texi
diff -u guile/guile-core/doc/intro.texi:1.1 guile/guile-core/doc/intro.texi:1.2
--- guile/guile-core/doc/intro.texi:1.1 Fri Mar  9 00:21:59 2001
+++ guile/guile-core/doc/intro.texi     Sun Mar 11 16:50:08 2001
@@ -1,4 +1,4 @@
address@hidden $Id: intro.texi,v 1.1 2001/03/09 08:21:59 ossau Exp $
address@hidden $Id: intro.texi,v 1.2 2001/03/12 00:50:08 mvo Exp $
 
 @page
 @node What is Guile?
@@ -62,6 +62,7 @@
 * Running Guile Interactively::  
 * Guile Scripts::               
 * Linking Programs With Guile::  
+* Writing Extensions for Guile::  
 * Writing Guile Modules::       
 @end menu
 
@@ -355,15 +356,18 @@
 The header file @code{<libguile.h>} provides declarations for all of
 Guile's functions and constants.  You should @code{#include} it at the
 head of any C source file that uses identifiers described in this
-manual.
+manual.  Once you've compiled your source files, you need to link them
+against the Guile object code library, @code{libguile}.
 
-Once you've compiled your source files, you can link them against Guile
-by passing the flag @code{-lguile} to your linker.  If you installed
-Guile with multi-thread support (by passing @code{--enable-threads} to
-the @code{configure} script), you may also need to link against the
-QuickThreads library, @code{-lqt}.  Guile refers to various mathematical
-functions, so you will probably need to link against the mathematical
-library, @code{-lm}, as well.
+On most systems, you should not need to do tell the compiler and linker
+explicitely where they can find @file{libguile.h} and @file{libguile}.
+When Guile has been installed in a peculiar way, or when you are on a
+peculiar system, things might not be so easy and you might need to pass
+additional @code{-I} or @code{-L} options to the compiler.  Guile
+provides the utility program @code{guile-config} to help you find the
+right values for these options.  You would typically run
address@hidden during the configuration phase of your program and
+use the obtained information in the Makefile.
 
 @menu
 * Guile Initialization Functions::  What to call first.
@@ -374,7 +378,19 @@
 @node Guile Initialization Functions
 @subsection Guile Initialization Functions
 
-To initialize Guile, use this function:
+To initialize Guile, you can use one of two functions.  The first,
address@hidden, is the most portable way to initialize Guile.  It
+should be used whenever you have control over the main function of your
+program because it never returns.  The second function,
address@hidden, does return and can thus be used in more
+situations.  However, @code{scm_init_guile} is not as widely available
+as @code{scm_boot_guile} because it needs to rely on non-portable code
+to find the stack bounds.  When Guile does not know how to find these
+bounds on your system, it will not provide @code{scm_init_guile}.
+
+When you can tolerate the limits of @code{scm_boot_guile}, you should
+use it in favor of @code{scm_init_guile} since that will make your
+program more portable.
 
 @deftypefun void scm_boot_guile (int @var{argc}, char address@hidden, void 
(address@hidden) (), void address@hidden)
 Initialize the Guile Scheme interpreter.  Then call @var{main_func},
@@ -391,22 +407,36 @@
 @code{scm_set_program_arguments} with the final list, so Scheme code
 will know which arguments have been processed.
 
address@hidden establishes a catch-all error handler which prints
-an error message and exits the process.  This means that Guile exits in
-a coherent way if a system error occurs and the user isn't prepared to
-handle it.  If the user doesn't like this behavior, they can establish
-their own universal catcher in @var{main_func} to shadow this one.
-
 Why must the caller do all the real work from @var{main_func}?  Guile's
-garbage collector assumes that all local variables which reference
-Scheme objects will be above @code{scm_boot_guile}'s stack frame on the
-stack.  If you try to manipulate Scheme objects after this function
-returns, it's the luck of the draw whether Guile's storage manager will
-be able to find the objects you allocate.  So, @code{scm_boot_guile}
-function exits, rather than returning, to discourage you from making
-that mistake.
+garbage collector scans the stack to find all local variables that
+reference Scheme objects.  To do this, it needs to know the bounds of
+the stack that might contain such references.  Because there is no
+protable way in C to find the base of the stack, @code{scm_boot_guile}
+assumes that all references are above its own stack frame.  If you try
+to manipulate Scheme objects after this function returns, it's the luck
+of the draw whether Guile's storage manager will be able to find the
+objects you allocate.  So, @code{scm_boot_guile} function exits, rather
+than returning, to discourage you from making that mistake.
+
+See @code{scm_init_guile}, below, for a function that can find the real
+base of the stack, but not in a portable way.
 @end deftypefun
 
address@hidden void scm_init_guile ()
+Initialize the Guile Scheme interpreter.
+
+In contrast to @code{scm_boot_guile}, this function knows how to find
+the true base of the stack and thus does not need to usurp the control
+flow of your program.  However, since finding the stack base can not be
+done portably, this function might not be available in all installations
+of Guile.  If you can, you should use @code{scm_boot_guile} instead.
+
+Note that @code{scm_init_guile} does not inform Guile about the command
+line arguments that should be returned by the Scheme function
address@hidden  You can use @code{scm_set_program_arguments} to do
+this.
address@hidden deftypefun
+
 One common way to use Guile is to write a set of C functions which
 perform some useful task, make them callable from Scheme, and then link
 the program with Guile.  This yields a Scheme interpreter just like
@@ -427,10 +457,6 @@
 
 Since this function does not return, you must do all
 application-specific initialization before calling this function.
-
-If you do not use this function to start Guile, you are responsible for
-making sure Guile's usual initialization files, @file{init.scm} and
address@hidden/boot-9.scm}, get loaded.  This will change soon.
 @end deftypefun
 
 
@@ -468,19 +494,22 @@
 ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
 process the command-line arguments in the usual way.
 
-Here is a Makefile which you can use to compile the above program.
+Here is a Makefile which you can use to compile the above program.  It
+uses @code{guile-config} to learn about the necessary compiler and
+linker flags.
 @example
 # Use GCC, if you have it installed.
 CC=gcc
 
-# Tell the C compiler where to find <libguile.h> and -lguile.
-CFLAGS=-I/usr/local/include -L/usr/local/lib
+# Tell the C compiler where to find <libguile.h>
+CFLAGS=`guile-config compile`
 
-# Include -lqt and -lrx if they are present on your system.
-LIBS=-lguile -lqt -lrx -lm
+# Tell the linker what libraries to use and where to find them.
+LIBS=`guile-config link`
 
 simple-guile: simple-guile.o
-        address@hidden@} address@hidden@} simple-guile.o address@hidden@} -o 
simple-guile
+        address@hidden@} simple-guile.o address@hidden@} -o simple-guile
+
 simple-guile.o: simple-guile.c
         address@hidden@} -c address@hidden@} simple-guile.c
 @end example
@@ -488,20 +517,22 @@
 If you are using the GNU Autoconf package to make your application more
 portable, Autoconf will settle many of the details in the Makefile above
 automatically, making it much simpler and more portable; we recommend
-using Autoconf with Guile.  Here is a @file{configure.in} file for
address@hidden, which Autoconf can use as a template to generate a
address@hidden script:
+using Autoconf with Guile.  Guile also provides the @code{GUILE_FLAGS}
+macro for autoconf that performs all necessary checks.  Here is a
address@hidden file for @code{simple-guile} that uses this macro.
+Autoconf can use as this file as template to generate a @code{configure}
+script.  In order for Autoconf to find the @code{GUILE_FLAGS} macro, you
+will need to run @code{aclocal} first.  This is not really Guile
+specific, so you should refer to the Autoconf documentation REFFIXME
+when in doubt.
 @example
 AC_INIT(simple-guile.c)
 
 # Find a C compiler.
 AC_PROG_CC
 
-# Check for libraries.
-AC_CHECK_LIB(m, sin)
-AC_CHECK_LIB(rx, regcomp)
-AC_CHECK_LIB(qt, main)
-AC_CHECK_LIB(guile, scm_boot_guile)
+# Check for Guile
+GUILE_FLAGS
 
 # Generate a Makefile, based on the results.
 AC_OUTPUT(Makefile)
@@ -512,11 +543,11 @@
 @example
 # The configure script fills in these values.
 CC=@@CC@@
-CFLAGS=@@CFLAGS@@
-LIBS=@@LIBS@@
+CFLAGS=@@GUILE_CFLAGS@@
+LIBS=@@GUILE_LDFLAGS@@
 
 simple-guile: simple-guile.o
-        address@hidden@} address@hidden@} simple-guile.o address@hidden@} -o 
simple-guile
+        address@hidden@} simple-guile.o address@hidden@} -o simple-guile
 simple-guile.o: simple-guile.c
         address@hidden@} -c address@hidden@} simple-guile.c
 @end example
@@ -531,21 +562,17 @@
 Makefile.in     configure*      configure.in    simple-guile.c
 $ ./configure
 creating cache ./config.cache
-checking for gcc... gcc
+checking for gcc... (cached) gcc
 checking whether the C compiler (gcc  ) works... yes
 checking whether the C compiler (gcc  ) is a cross-compiler... no
-checking whether we are using GNU C... yes
-checking whether gcc accepts -g... yes
-checking for sin in -lm... yes
-checking for regcomp in -lrx... yes
-checking for main in -lqt... yes
-checking for scm_boot_guile in -lguile... yes
-updating cache ./config.cache
+checking whether we are using GNU C... (cached) yes
+checking whether gcc accepts -g... (cached) yes
+checking for Guile... yes
 creating ./config.status
 creating Makefile
 $ make
-gcc -c -g -O2 simple-guile.c
-gcc -g -O2 simple-guile.o -lguile -lqt -lrx -lm  -o simple-guile
+gcc -c -I/usr/local/include simple-guile.c
+gcc simple-guile.o -L/usr/local/lib -lguile -lqthreads -lpthread -lm -o 
simple-guile
 $ ./simple-guile
 guile> (+ 1 2 3)
 6
@@ -556,12 +583,125 @@
 $ 
 @end example
 
address@hidden Writing Extensions for Guile
address@hidden Writing Extensions for Guile
+
+The previous sections have briefly explained how to write programs that
+make use of an embedded Guile interpreter.  But sometimes, all you want
+to do is make new primitive procedures and data types available to the
+Scheme programmer.  Writing a new version of @code{guile} is
+inconvenient in this case and it would in fact make the life of the
+users of your new fetaures needlessly hard.
+
address@hidden [[ the following is probably a bit longwinded ]]
+
+For example, suppose that there is a program @code{guile-db} that is a
+version of Guile with additional features for accessing a database.
+People who want to write Scheme programs that use these features would
+have to use @code{guile-db} instead of the usual @code{guile} program.
+Now suppose that there is also a program @code{guile-gtk} that extends
+Guile with access to the popular Gtk+ toolkit for graphical user
+interfaces.  People who want to write GUIs in Scheme would have to use
address@hidden  Now, what happens when you want to write a Scheme
+application that uses a GUI to let the user accessa a database?  You
+would have to write a @emph{third} program that incorporates both the
+database stuff and the GUI stuff.  This might not be easy (because
address@hidden might be a quite obscure program, say) and taking this
+example further makes it easy to see that this approach can not work in
+practice.
+
+It would have been much better if both the database features and the GUI
+feature had been provided as libraries that can just be linked with
address@hidden  Guile makes it easy to do just this, and we encourage you
+to make your extensions to Guile available as libraries whenever
+possible.
+
+You write the new primitive procedures and data types in the normal
+fashion, and link them into a shared library instead of into a
+standalone program.  The shared library can then be loaded dynamically
+by Guile.
+
address@hidden
+* A Sample Guile Extension::    
address@hidden menu
+
address@hidden A Sample Guile Extension
address@hidden A Sample Guile Extension
+
+This section explains how to make the Bessel functions of the C library
+available to Scheme.  First we need to write the appropriate glue code
+to convert the arguments and return values of the functions from Scheme
+to C and back.  Additionally, we need a function that will add them to
+the set of Guile primitives.  Because this is just an example, we will
+only implement this for the @code{j0} function, tho.
 
+Consider the following file @file{bessel.c}.
+
address@hidden
+#include <math.h>
+#include <libguile.h>
+
+SCM
+j0_wrapper (SCM x)
address@hidden
+  return scm_make_real (j0 (scm_num2dbl (x, "j0")));
address@hidden
+
+void
+init_bessel ()
address@hidden
+  scm_make_gsubr ("j0", 1, 0, 0, j0_wrapper);
address@hidden
address@hidden smallexample
+
+This C source file needs to be compiled into a shared library.  Here is
+how to do it on GNU/Linux:
+
address@hidden
+gcc -shared -o libguile-bessel.so -fPIC bessel.c
address@hidden smallexample
+
+For creating shared libraries portably, we recommend the use of
address@hidden Libtool}.
+
+A shared library can be loaded into a running Guile process with
address@hidden  After it has been linked you can call its exported
+functions via @code{dynamic-call}.  For our example, we are going to
+call the function @code{init_bessel} which will make @code{j0_wrapper}
+available to Scheme programs with the name @code{j0}.  Note that we do
+not specify a filename extension such as @file{.so} when invoking
address@hidden  The right extension for the host platform will be
+provided automatically.
+
address@hidden
+(define bessel-lib (dynamic-link "libguile-bessel"))
+(dynamic-call "init_bessel" bessel-lib)
+(j0 2)
address@hidden 0.223890779141236
address@hidden smalllisp
+
+For this to work, @code{dynamic-link} must be able to find
address@hidden, of course.  It will look in the places that are
+usual for your operating system, and it will additionally look into the
+directories listed in the @code{LTDL_LIBRRAY_PATH} environment variable.
+
+To see how these Guile extensions via shared libraries relate to the
+module system, see below REFFIXME.
+
 @node Writing Guile Modules
 @section Writing Guile Modules
-
-[to be written]
 
+Guile has support for dividing a program into @dfn{modules}.  By using
+modules, you can group related code together and manage the composition
+of complete programs from their largely independent parts.
+
+(The module system is in flux, and will likely look very different in
+the future.  Feel free to use the existing system anyway.  Guile will
+provide reasonable backwards compatability.)
+
+[[ more stuff to follow: how to load third-party modules, how to write
+new modules, how to arrange for autoloading, how to load shared
+libraries as modules. ]]
 
 @page
 @node Reporting Bugs