Next: , Up: Linking Programs With Guile

5.3.1 Guile Initialization Functions

To initialize Guile, you can use one of two functions. The first, scm_boot_guile, 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, scm_init_guile, does return and can thus be used in more situations. However, scm_init_guile is not as widely available as 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 scm_init_guile.

When you can tolerate the limits of scm_boot_guile, you should use it in favor of scm_init_guile since that will make your program more portable.

— Function: void scm_boot_guile (int argc, char **argv, void (*main_func) (), void *closure)

Initialize the Guile Scheme interpreter. Then call main_func, passing it closure, argc, and argv. main_func should do all the work of the program (initializing other packages, defining application-specific functions, reading user input, and so on) before returning. When main_func returns, call exit (0); scm_boot_guile never returns. If you want some other exit value, have main_func call exit itself.

scm_boot_guile arranges for the Scheme command-line function to return the strings given by argc and argv. If main_func modifies argc or argv, it should call scm_set_program_arguments with the final list, so Scheme code will know which arguments have been processed.

Why must the caller do all the real work from main_func? Guile's 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 portable way in C to find the base of the stack, 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, scm_boot_guile function exits, rather than returning, to discourage you from making that mistake.

See scm_init_guile, below, for a function that can find the real base of the stack, but not in a portable way.

— Function: void scm_init_guile ()

Initialize the Guile Scheme interpreter.

In contrast to 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 scm_boot_guile instead.

Note that scm_init_guile does not inform Guile about the command line arguments that should be returned by the Scheme function command-line. You can use scm_set_program_arguments to do this.

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 guile, but augmented with extra functions for some specific application — a special-purpose scripting language.

In this situation, the application should probably process its command-line arguments in the same manner as the stock Guile interpreter. To make that straightforward, Guile provides this function:

— Function: void scm_shell (int argc, char **argv)

Process command-line arguments in the manner of the guile executable. This includes loading the normal Guile initialization files, interacting with the user or running any scripts or expressions specified by -s or -e options, and then exiting. See Invoking Guile, for more details.

Since this function does not return, you must do all application-specific initialization before calling this function.