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, 0 insertions, 191 deletions
diff --git a/doc/sources/libguile-tools.texi b/doc/sources/libguile-tools.texi
deleted file mode 100644
index d434406e9..000000000
--- a/doc/sources/libguile-tools.texi
+++ /dev/null
@@ -1,191 +0,0 @@
-@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