This chapter shows how to use the GH interface to call Guile from your application's C code, and to add new Scheme level procedures to Guile whose behaviour is specified by application specific code written in C.
Note, however, that the GH interface is now deprecated, and developers are encouraged to switch to using the scm interface instead. Therefore, for each GH feature, this chapter should also document how to achieve the same result using the scm interface.
Historically, the GH interface was the product of a practical problem
and a neat idea. The practical problem was that the interface of the
scm_ functions with which Guile itself was written (inherited
from Aubrey Jaffer's SCM) was so closely tied to the (rather arcane)
details of the internal data representation that it was extremely
difficult to write a Guile extension using these functions. The neat
idea was to define a high level language extension interface in such a
way that other extension language projects, not just Guile, would be
able to provide an implementation of that interface; then applications
using this interface could be compiled with whichever of the various
available implementations they chose. So the GH interface was created,
and advertised both as the recommended interface for application
developers wishing to use Guile, and as a portable high level interface
that could theoretically be implemented by other extension language
projects.
Time passed, and various things changed. Crucially, an enormous number
of improvements were made to the scm_ interface that Guile itself
uses in its implementation, with the result that it is now both easy and
comfortable to write a Guile extension with this interface. At the same
time, the contents of the GH interface were somewhat neglected by the
core Guile developers, such that some key operations -- such as smob
creation and management -- are simply not possible using GH alone.
Finally, the idea of multiple implementations of the GH interface did
not really crystallize (apart, I believe, from a short lived
implementation by the MzScheme project).
For all these reasons, the Guile developers have decided to deprecate
the GH interface -- which means that support for GH will be completely
removed after the next few releases -- and to focus only on the
scm_ interface, with additions to ensure that it is as easy to
use in all respects as GH was.
It remains an open question whether a deep kind of interface portability would be useful for extension language-based applications, and it may still be an interesting project to attempt to define a corresponding GH-like interface, but the Guile developers no longer plan to try to do this as part of the core Guile project.
To use gh, you must have the following toward the beginning of your C source:
#include <guile/gh.h>
When you link, you will have to add at least -lguile to the list
of libraries. If you are using more of Guile than the basic Scheme
interpreter, you will have to add more libraries.
The following C constants and data types are defined in gh:
This can cause confusion because they are different from 0 and 1. In
testing a boolean function in libguile programming, you must always make
sure that you check the spec: gh_ and scm_ functions will
usually return SCM_BOOL_T and SCM_BOOL_F, but other C
functions usually can be tested against 0 and 1, so programmers' fingers
tend to just type if (boolean_function()) { ... }
gh_list().
In almost every case, your first gh_ call will be:
gh_enter() never exits, and the user's code should all be in the
main_prog() function. argc and argv will be
passed to main_prog.
gh_enter() after Guile has been started up.
Note that you can use gh_repl inside gh_enter (in other
words, inside the code for main-prog) if you want the program to
be controlled by a Scheme read-eval-print loop.
A convenience routine which enters the Guile interpreter with the standard Guile read-eval-print loop (REPL) is:
Note that gh_repl should be used inside gh_enter,
since any Guile interpreter calls are meaningless unless they happen in
the context of the interpreter.
Also note that when you use gh_repl, your program will be
controlled by Guile's REPL (which is written in Scheme and has many
useful features). Use straight C code inside gh_enter if you
want to maintain execution control in your C program.
You will typically use gh_enter and gh_repl when you
want a Guile interpreter enhanced by your own libraries, but otherwise
quite normal. For example, to build a Guile--derived program that
includes some random number routines GSL (GNU Scientific Library),
you would write a C program that looks like this:
#include <guile/gh.h>
#include <gsl_ran.h>
/* random number suite */
SCM gw_ran_seed(SCM s)
{
gsl_ran_seed(gh_scm2int(s));
return SCM_UNSPECIFIED;
}
SCM gw_ran_random()
{
SCM x;
x = gh_ulong2scm(gsl_ran_random());
return x;
}
SCM gw_ran_uniform()
{
SCM x;
x = gh_double2scm(gsl_ran_uniform());
return x;
}
SCM gw_ran_max()
{
return gh_double2scm(gsl_ran_max());
}
void
init_gsl()
{
/* random number suite */
gh_new_procedure("gsl-ran-seed", gw_ran_seed, 1, 0, 0);
gh_new_procedure("gsl-ran-random", gw_ran_random, 0, 0, 0);
gh_new_procedure("gsl-ran-uniform", gw_ran_uniform, 0, 0, 0);
gh_new_procedure("gsl-ran-max", gw_ran_max, 0, 0, 0);
}
void
main_prog (int argc, char *argv[])
{
init_gsl();
gh_repl(argc, argv);
}
int
main (int argc, char *argv[])
{
gh_enter (argc, argv, main_prog);
}
Then, supposing the C program is in `guile-gsl.c', you could compile it with gcc -o guile-gsl guile-gsl.c -lguile -lgsl.
The resulting program `guile-gsl' would have new primitive
procedures gsl-ran-random, gsl-ran-gaussian and so forth.
[FIXME: need to fill this based on Jim's new mechanism]
Once you have an interpreter running, you can ask it to evaluate Scheme code. There are two calls that implement this:
Note that the line of code in scheme_code must be a well formed
Scheme expression. If you have many lines of code before you balance
parentheses, you must either concatenate them into one string, or use
gh_eval_file().
gh_eval_file is completely analogous to gh_eval_str(),
except that a whole file is evaluated instead of a string.
gh_eval_file returns SCM_UNSPECIFIED.
gh_load is identical to gh_eval_file (it's a macro that
calls gh_eval_file on its argument). It is provided to start
making the gh_ interface match the R5RS Scheme procedures
closely.
The real interface between C and Scheme comes when you can write new Scheme procedures in C. This is done through the routine
gh_new_procedure defines a new Scheme procedure. Its Scheme name
will be proc_name, it will be implemented by the C function
(*fn)(), it will take at least n_required_args arguments,
and at most n_optional_args extra arguments.
When the restp parameter is 1, the procedure takes a final argument: a list of remaining parameters.
gh_new_procedure returns an SCM value representing the procedure.
The C function fn should have the form
Examples of C functions used as new Scheme primitives can be found in
the sample programs learn0 and learn1.
Rationale: this is the correct way to define new Scheme procedures in C. The ugly mess of arguments is required because of how C handles procedures with variable numbers of arguments.
Note: what about documentation strings?
There are several important considerations to be made when writing the C
routine (*fn)().
First of all the C routine has to return type SCM.
Second, all arguments passed to the C function will be of type
SCM.
Third: the C routine is now subject to Scheme flow control, which means that it could be interrupted at any point, and then reentered. This means that you have to be very careful with operations such as allocating memory, modifying static data ...
Fourth: to get around the latter issue, you can use
GH_DEFER_INTS and GH_ALLOW_INTS.
Guile provides mechanisms to convert data between C and Scheme. This
allows new builtin procedures to understand their arguments (which are
of type SCM) and return values of type SCM.
#f if x is zero, #t otherwise.
If start + len is off the end of dst, signal an out-of-range error.
*lenp to the string's length.
This function uses malloc to obtain storage for the copy; the caller is responsible for freeing it.
Note that Scheme strings may contain arbitrary data, including null characters. This means that null termination is not a reliable way to determine the length of the returned value. However, the function always copies the complete contents of str, and sets *lenp to the true length of the string (when lenp is non-null).
If start + len is off the end of src, signal an out-of-range error.
"'symbol-name". If lenp is non-null, the string's length
is returned in *lenp.
This function uses malloc to obtain storage for the returned string; the caller is responsible for freeing it.
vector can be an ordinary vector, a weak vector, or a signed or unsigned uniform vector of the same type as the result array. For chars, vector can be a string or substring. For floats and doubles, vector can contain a mix of inexact and integer values.
If vector is of unsigned type and contains values too large to fit in the signed destination array, those values will be wrapped around, that is, data will be copied as if the destination array was unsigned.
These C functions mirror Scheme's type predicate procedures with one
important difference. The C routines return C boolean values (0 and 1)
instead of SCM_BOOL_T and SCM_BOOL_F.
The Scheme notational convention of putting a ? at the end of
predicate procedure names is mirrored in C by placing _p at the
end of the procedure. For example, (pair? ...) maps to
gh_pair_p(...).
These C functions mirror Scheme's equality predicate procedures with one
important difference. The C routines return C boolean values (0 and 1)
instead of SCM_BOOL_T and SCM_BOOL_F.
The Scheme notational convention of putting a ? at the end of
predicate procedure names is mirrored in C by placing _p at the
end of the procedure. For example, (equal? ...) maps to
gh_equal_p(...).
eq? predicate, 0 otherwise.
eqv? predicate, 0 otherwise.
equal? predicate, 0 otherwise.
Many of the Scheme primitives are available in the gh_
interface; they take and return objects of type SCM, and one could
basically use them to write C code that mimics Scheme code.
I will list these routines here without much explanation, since what
they do is the same as documented in section `Standard procedures' in R5RS. But I will point out that when a procedure takes a
variable number of arguments (such as gh_list), you should pass
the constant SCM_UNDEFINED from C to signify the end of the list.
(define name val): it binds a value to
the given name (which is a C string). Returns the new object.
(cons a b) and (list l0 l1
...) procedures. Note that gh_list() is a C macro that invokes
scm_listify().
(caadar ls) procedures etc ...
(set-car! ...).
(set-cdr! ...).
gh_append() takes args, which is a list of lists
(list1 list2 ...), and returns a list containing all the elements
of the individual lists.
A typical invocation of gh_append() to append 5 lists together
would be
gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED));
The functions gh_append2(), gh_append2(),
gh_append3() and gh_append4() are convenience routines to
make it easier for C programs to form the list of lists that goes as an
argument to gh_append().
scm_reverse().
(memq x ls), (memv x ls) and
(member x ls), and hence use (respectively) eq?,
eqv? and equal? to do comparisons.
If x does not appear in ls, the value SCM_BOOL_F (not
the empty list) is returned.
Note that these functions are implemented as macros which call
scm_memq(), scm_memv() and scm_member()
respectively.
If no pair in alist has x as its CAR, the value
SCM_BOOL_F (not the empty list) is returned.
Note that these functions are implemented as macros which call
scm_assq(), scm_assv() and scm_assoc()
respectively.
(make-vector n fill),
(vector a b c ...) (vector-ref v i) (vector-set v i
value) (vector-length v) (list->vector ls) procedures.
The correspondence is not perfect for gh_vector: this routine
takes a list ls instead of the individual list elements, thus
making it identical to gh_list_to_vector.
There is also a difference in gh_vector_length: the value returned is a
C unsigned long instead of an SCM object.
gh_call0), one argument (gh_call1), and so on. You can
get the same effect by wrapping the arguments up into a list, and
calling gh_apply; Guile provides these functions for convenience.
catch and throw procedures,
which in Guile are provided as primitives.
eq?, eqv? and equal?
predicates.
For now I just include Tim Pierce's comments from the `gh_data.c' file; it should be organized into a documentation of the two functions here.
/* Data lookups between C and Scheme Look up a symbol with a given name, and return the object to which it is bound. gh_lookup examines the Guile top level, and gh_module_lookup checks the module name space specified by the `vec' argument. The return value is the Scheme object to which SNAME is bound, or SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME: should this be SCM_UNSPECIFIED? Can a symbol ever legitimately be bound to SCM_UNDEFINED or SCM_UNSPECIFIED? What is the difference? -twp] */
The following table summarizes the available information on how to transition from the GH to the scm interface. Where transitioning is not completely straightforward, the table includes a reference to more detailed documentation in the preceding sections.
#include <libguile.h> instead of #include
<guile/gh.h>.
guile-config to pick up the flags required to compile C or
C++ code that uses libguile, like so
$(CC) -o prog.o -c prog.c `guile-config compile`If you are using libtool to link your executables, just use
-lguile in your link command. Libtool will expand this into
the needed linker options automatically. If you are not using
libtool, use the guile-config program to query the needed
options explicitly. A linker command like
$(CC) -o prog prog.o `guile-config link`should be all that is needed. To link shared libraries that will be used as Guile Extensions, use libtool to control both the compilation and the link stage.
SCM type
SCM_BOOL_F and SCM_BOOL_T
SCM_UNSPECIFIED and SCM_UNDEFINED
gh_enter
scm_boot_guile instead, but note that scm_boot_guile
has a slightly different calling convention from gh_enter:
scm_boot_guile, and the main program function that you specify
for scm_boot_guile to call, both take an additional closure
parameter. section Guile Initialization Functions for more details.
gh_repl
scm_shell instead.
gh_init
scm_init_guile instead.
gh_eval_str
scm_c_eval_string instead.
gh_eval_file or gh_load
scm_c_primitive_load instead.
gh_new_procedure
scm_c_define_gsubr instead, but note that the arguments are
in a different order: for scm_c_define_gsubr the C function
pointer is the last argument. section A Sample Guile Extension for an
example.
gh_defer_ints and gh_allow_ints
SCM_DEFER_INTS and SCM_ALLOW_INTS instead. Note that
these macros are used without parentheses, as in SCM_DEFER_INTS;.
gh_bool2scm
SCM_BOOL instead.
gh_ulong2scm
scm_ulong2num instead.
gh_long2scm
scm_long2num instead.
gh_double2scm
scm_make_real instead.
gh_char2scm
SCM_MAKE_CHAR instead.
gh_str2scm
scm_mem2string instead.
gh_str02scm
scm_makfrom0str instead.
gh_set_substr
gh_symbol2scm
scm_str2symbol instead. [FIXME: inconsistent naming,
should be scm_str02symbol.]
gh_ints2scm and gh_doubles2scm
scm_c_ints2scm and scm_c_doubles2scm instead.
gh_chars2byvect and gh_shorts2svect
scm_c_chars2byvect and scm_c_shorts2svect instead.
gh_longs2ivect and gh_ulongs2uvect
scm_c_longs2ivect and scm_c_ulongs2uvect instead.
gh_floats2fvect and gh_doubles2dvect
scm_c_floats2fvect and scm_c_doubles2dvect instead.
gh_scm2bool
SCM_NFALSEP instead.
gh_scm2int
gh_scm2int (obj) by
scm_num2int (obj, SCM_ARG1, str)where str is a C string that describes the context of the call.
gh_scm2ulong
gh_scm2ulong (obj) by
scm_num2ulong (obj, SCM_ARG1, str)where str is a C string that describes the context of the call.
gh_scm2long
gh_scm2long (obj) by
scm_num2long (obj, SCM_ARG1, str)where str is a C string that describes the context of the call.
gh_scm2double
gh_scm2double (obj) by
scm_num2dbl (obj, str)where str is a C string that describes the context of the call.
gh_scm2char
SCM_CHAR macro instead, but note that SCM_CHAR
does not check that its argument is actually a character. To check that
a SCM value is a character before using SCM_CHAR to
extract the character value, use the SCM_VALIDATE_CHAR macro.
gh_scm2newstr
gh_scm2newstr (obj, lenp) use
scm_c_string2str (obj, str, lenp). With the
additional str argument the user can pass a pre-allocated memory
chunk or leave it passing NULL.
gh_get_substr
scm_c_substring2str (obj, str, start,
len) function instead.
gh_symbol2newstr
scm_c_symbol2str (obj, str, lenp) function
instead. With the additional str argument the user can pass a
pre-allocated memory chunk or leave it passing NULL.
gh_scm2chars
scm_c_scm2chars instead.
gh_scm2shorts and gh_scm2longs
scm_c_shorts2scm and scm_c_longs2scm instead.
gh_scm2floats and gh_scm2doubles
scm_c_floats2scm and scm_c_doubles2scm instead.
gh_boolean_p
SCM_BOOLP macro instead, or replace gh_boolean_p
(obj) by
SCM_NFALSEP (scm_boolean_p (obj))
gh_symbol_p
SCM_SYMBOLP macro instead, or replace gh_symbol_p
(obj) by
SCM_NFALSEP (scm_symbol_p (obj))
gh_char_p
SCM_CHARP macro instead, or replace gh_char_p
(obj) by
SCM_NFALSEP (scm_char_p (obj))
gh_vector_p
SCM_VECTORP macro instead, or replace gh_vector_p
(obj) by
SCM_NFALSEP (scm_vector_p (obj))
gh_pair_p
SCM_CONSP macro instead, or replace gh_pair_p
(obj) by
SCM_NFALSEP (scm_pair_p (obj))
gh_number_p
SCM_NUMBERP macro instead, or replace gh_number_p
(obj) by
SCM_NFALSEP (scm_number_p (obj))
gh_string_p
SCM_STRINGP macro instead, or replace gh_string_p
(obj) by
SCM_NFALSEP (scm_string_p (obj))
gh_procedure_p
gh_procedure_p (obj) by
SCM_NFALSEP (scm_procedure_p (obj))
gh_list_p
gh_list_p (obj) by
SCM_NFALSEP (scm_list_p (obj))
gh_inexact_p
SCM_INEXACTP macro instead, or replace gh_inexact_p
(obj) by
SCM_NFALSEP (scm_inexact_p (obj))
gh_exact_p
gh_exact_p (obj) by
SCM_NFALSEP (scm_exact_p (obj))
gh_eq_p
SCM_EQ_P macro instead, or replace gh_eq_p
(x, y) by
SCM_NFALSEP (scm_eq_p (x, y))
gh_eqv_p
gh_eqv_p (x, y) by
SCM_NFALSEP (scm_eqv_p (x, y))
gh_equal_p
gh_equal_p (x, y) by
SCM_NFALSEP (scm_equal_p (x, y))
gh_string_equal_p
gh_string_equal_p (x, y) by
SCM_NFALSEP (scm_string_equal_p (x, y))
gh_null_p
SCM_NULLP macro instead, or replace gh_null_p
(obj) by
SCM_NFALSEP (scm_null_p (obj))
gh_cons
scm_cons instead.
gh_car and gh_cdr
SCM_CAR and SCM_CDR macros instead.
gh_cxxr and gh_cxxxr
SCM_CXXR or SCM_CXXXR macro instead.
gh_set_car_x and gh_set_cdr_x
scm_set_car_x and scm_set_cdr_x instead.
gh_list
scm_listify instead.
gh_length
gh_length (lst) by
scm_num2ulong (scm_length (lst), SCM_ARG1, str)where str is a C string that describes the context of the call.
gh_append
scm_append instead.
gh_append2, gh_append3, gh_append4
gh_appendN (l1, ..., lN) by
scm_append (scm_listify (l1, ..., lN, SCM_UNDEFINED))
gh_reverse
scm_reverse instead.
gh_list_tail and gh_list_ref
scm_list_tail and scm_list_ref instead.
gh_memq, gh_memv and gh_member
scm_memq, scm_memv and scm_member instead.
gh_assq, gh_assv and gh_assoc
scm_assq, scm_assv and scm_assoc instead.
gh_make_vector
scm_make_vector instead.
gh_vector or gh_list_to_vector
scm_vector instead.
gh_vector_ref and gh_vector_set_x
scm_vector_ref and scm_vector_set_x instead.
gh_vector_length
SCM_VECTOR_LENGTH macro instead.
gh_apply
scm_apply instead, but note that scm_apply takes an
additional third argument that you should set to SCM_EOL.
Go to the first, previous, next, last section, table of contents.