summaryrefslogtreecommitdiff
path: root/doc/sources/libguile-tools.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/sources/libguile-tools.texi')
-rw-r--r--doc/sources/libguile-tools.texi191
1 files changed, 191 insertions, 0 deletions
diff --git a/doc/sources/libguile-tools.texi b/doc/sources/libguile-tools.texi
new file mode 100644
index 000000000..d434406e9
--- /dev/null
+++ b/doc/sources/libguile-tools.texi
@@ -0,0 +1,191 @@
+@node Tools to automate adding libraries
+@chapter Tools to automate adding libraries
+
+You want to ...
+
+The chapters @ref{Libguile -- high level interface} and @ref{Libguile --
+SCM interface} showed how to make C libraries available from Scheme.
+Here I will describe some automated tools that the Guile team has made
+available. Some have been written especially for Guile (the Guile Magic
+Snarfer), and some are also in use with other languages (Python, Perl,
+...)
+
+@menu
+* By hand with gh_::
+* By hand with Guile Magic Snarfer::
+* Automatically using libtool::
+* Automatically using SWIG::
+@end menu
+
+@node By hand with gh_
+@section By hand with gh_
+
+@node By hand with Guile Magic Snarfer
+@section By hand with Guile Magic Snarfer
+
+When writing C code for use with Guile, you typically define a set of C
+functions, and then make some of them visible to the Scheme world by
+calling the @code{scm_make_gsubr} function; a C functions published in
+this way is called a @dfn{subr}. If you have many subrs to publish, it
+can sometimes be annoying to keep the list of calls to
+@code{scm_make_gsubr} in sync with the list of function definitions.
+Frequently, a programmer will define a new subr in C, recompile his
+application, and then discover that the Scheme interpreter cannot see
+the subr, because he forgot to call @code{scm_make_gsubr}.
+
+Guile provides the @code{guile-snarf} command to manage this problem.
+Using this tool, you can keep all the information needed to define the
+subr alongside the function definition itself; @code{guile-snarf} will
+extract this information from your source code, and automatically
+generate a file of calls to @code{scm_make_gsubr} which you can
+@code{#include} into an initialization function. (The command name
+comes from the verb ``to snarf'', here meaning ``to unceremoniously
+extract information from a somewhat unwilling source.'')
+
+@menu
+* How guile-snarf works:: Using the @code{guile-snarf} command.
+* Macros guile-snarf recognizes:: How to mark up code for @code{guile-snarf}.
+@end menu
+
+@node How guile-snarf works
+@subsection How @code{guile-snarf} works
+
+For example, here is how you might define a new subr called
+@code{clear-image}, implemented by the C function @code{clear_image}:
+
+@example
+@group
+#include <libguile.h>
+
+@dots{}
+
+SCM_PROC (s_clear_image, "clear-image", 1, 0, 0, clear_image);
+
+SCM
+clear_image (SCM image_smob)
+@{
+ @dots{}
+@}
+
+@dots{}
+
+void
+init_image_type ()
+@{
+#include "image-type.x"
+@}
+@end group
+@end example
+
+The @code{SCM_PROC} declaration says that the C function
+@code{clear_image} implements a Scheme subr called @code{clear-image},
+which takes one required argument, no optional arguments, and no tail
+argument. @code{SCM_PROC} also declares a static array of characters
+named @code{s_clear_image}, initialized to the string
+@code{"clear-image"}. The body of @code{clear_image} may use the array
+in error messages, instead of writing out the literal string; this may
+save string space on some systems.
+
+Assuming the text above lives in a file named @file{image-type.c}, you will
+need to execute the following command to compile this file:
+@example
+guile-snarf image-type.c > image-type.x
+@end example
+@noindent This scans @file{image-type.c} for @code{SCM_PROC}
+declarations, and sends the following output to the file
+@file{image-type.x}:
+@example
+scm_make_gsubr (s_clear_image, 1, 0, 0, clear_image);
+@end example
+When compiled normally, @code{SCM_PROC} is a macro which expands to a
+declaration of the @code{s_clear_image} string.
+
+In other words, @code{guile-snarf} scans source code looking for uses of
+the @code{SCM_PROC} macro, and generates C code to define the
+appropriate subrs. You need to provide all the same information you
+would if you were using @code{scm_make_gsubr} yourself, but you can
+place the information near the function definition itself, so it is less
+likely to become incorrect or out-of-date.
+
+If you have many files that @code{guile-snarf} must process, you should
+consider using a rule like the following in your Makefile:
+@example
+.SUFFIXES: .x
+.c.x:
+ ./guile-snarf $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) $< > $@
+@end example
+This tells make to run @code{guile-snarf} to produce each needed
+@file{.x} file from the corresponding @file{.c} file.
+
+@code{guile-snarf} passes all its command-line arguments directly to the
+C preprocessor, which it uses to extract the information it needs from
+the source code. this means you can pass normal compilation flags to
+@code{guile-snarf} to define preprocessor symbols, add header file
+directories, and so on.
+
+
+
+@node Macros guile-snarf recognizes
+@subsection Macros @code{guile-snarf} recognizes
+
+Here are the macros you can use in your source code from which
+@code{guile-snarf} can construct initialization code:
+
+
+@defmac SCM_PROC (@var{namestr}, @var{name}, @var{req}, @var{opt}, @var{tail}, @var{c_func})
+Declare a new Scheme primitive function, or @dfn{subr}. The new subr
+will be named @var{name} in Scheme code, and be implemented by the C
+function @var{c_func}. The subr will take @var{req} required arguments
+and @var{opt} optional arguments. If @var{tail} is non-zero, the
+function will accept any remaining arguments as a list.
+
+Use this macro outside all function bodies, preferably above the
+definition of @var{c_func} itself. When compiled, the @code{SCM_PROC}
+declaration will expand to a definition for the @var{namestr} array,
+initialized to @var{name}. The @code{guile-snarf} command uses this
+declaration to automatically generate initialization code to create the
+subr and bind it in the top-level environment. @xref{How guile-snarf
+works}, for more info.
+
+@xref{Subrs}, for details on argument passing and how to write
+@var{c_func}.
+@end defmac
+
+
+@defmac SCM_GLOBAL (@var{var}, @var{scheme_name})
+Declare a global Scheme variable named @var{scheme_name}, and a static C
+variable named @var{var} to point to it. The value of the Scheme
+variable lives in the @sc{cdr} of the cell @var{var} points to.
+Initialize the variable to @code{#f}.
+
+Use this macro outside all function bodies. When compiled, the
+@code{SCM_GLOBAL} macro will expand to a definition for the variable
+@var{var}, initialized to an innocuous value. The @code{guile-snarf}
+command will use this declaration to automatically generate code to
+create a global variable named @var{scheme_name}, and store a pointer to
+its cell in @var{var}.
+@end defmac
+
+
+@defmac SCM_CONST_LONG (@var{var}, @var{scheme_name}, @var{value})
+Like @code{SCM_GLOBAL}, but initialize the variable to @var{value},
+which must be an integer.
+@end defmac
+
+
+@defmac SCM_SYMBOL (@var{var}, @var{name})
+Declare a C variable of type @code{SCM} named @var{var}, and initialize
+it to the Scheme symbol object whose name is @var{name}.
+
+Use this macro outside all function bodies. When compiled, the
+@code{SCM_SYMBOL} macro will expand to a definition for the variable
+@var{var}, initialized to an innocuous value. The @code{guile-snarf}
+command will use this declaration to automatically generate code to
+create a symbol named @var{name}, and store it in @var{var}.
+@end defmac
+
+@node Automatically using libtool
+@section Automatically using libtool
+
+@node Automatically using SWIG
+@section Automatically using SWIG