(guile.info.gz) Guile Initialization Functions
Info Catalog
(guile.info.gz) Linking Programs With Guile
(guile.info.gz) A Sample Guile Main Program
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.
Invoking Guile, for more details.
Since this function does not return, you must do all
application-specific initialization before calling this function.
Info Catalog
(guile.info.gz) Linking Programs With Guile
(guile.info.gz) A Sample Guile Main Program
automatically generated byinfo2html