summaryrefslogtreecommitdiff
path: root/doc/ref/api-init.texi
diff options
context:
space:
mode:
authorMarius Vollmer <mvo@zagadka.de>2004-08-02 12:29:00 +0000
committerMarius Vollmer <mvo@zagadka.de>2004-08-02 12:29:00 +0000
commit07d83abe7b8b617e4bb70a08efc0c0f6999fa0cc (patch)
tree34c8a7b9d98000169379038be8551ed44c0bdb83 /doc/ref/api-init.texi
parent237be238424f1b6d130799ad931ba6fa8504a97c (diff)
downloadguile-07d83abe7b8b617e4bb70a08efc0c0f6999fa0cc.tar.gz
* scheme-binding.texi: Renamed to api-binding.texi.
* scheme-compound.texi: Renamed to api-compound.texi. * scheme-control.texi: Renamed to api-control.texi. * scheme-data.texi: Renamed to api-data.texi. * scheme-debug.texi: Renamed to api-debug.texi. * deprecated.texi: Renamed to api-deprecated.texi. * scheme-evaluation.texi: Renamed to api-evaluation.texi. * ref-init.texi: Renamed to api-init.texi. * scheme-io.texi: Renamed to api-io.texi. * scheme-memory.texi: Renamed to api-memory.texi. * scheme-modules.texi: Renamed to api-modules.texi. * scheme-options.texi: Renamed to api-options.texi. * scm.texi: Renamed to api-overview.texi. * scheme-procedures.texi: Renamed to api-procedures.texi. * scheme-scheduling.texi: Renamed to api-scheduling.texi. * scheme-scm.texi: Renamed to api-scm.texi. * scheme-smobs.texi: Renamed to api-smobs.texi. * scheme-snarf.texi: Renamed to api-snarf.texi. * scheme-translation.texi: Renamed to api-translation.texi. * scheme-utility.texi: Renamed to api-utility.texi. * debugging.texi: Renamed to scheme-debugging.texi. * scripts.texi: Renamed to scheme-scripts.texi. * program.texi: Renamed to libguile-program.texi.
Diffstat (limited to 'doc/ref/api-init.texi')
-rw-r--r--doc/ref/api-init.texi66
1 files changed, 66 insertions, 0 deletions
diff --git a/doc/ref/api-init.texi b/doc/ref/api-init.texi
new file mode 100644
index 000000000..94407114b
--- /dev/null
+++ b/doc/ref/api-init.texi
@@ -0,0 +1,66 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+
+@node Initialization
+@section Initializing Guile
+
+@deftypefn {C Function} void scm_boot_guile (int @var{argc}, char **@var{argv}, void (*@var{main_func}) (void *@var{data}, int @var{argc}, char **@var{argv}), void *@var{data})
+Initialize the Guile Scheme interpreter. Then call @var{main_func},
+passing it @var{data}, @var{argc}, and @var{argv} as indicated. The
+function @var{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 @var{main_func}
+returns, @code{scm_boot_guile} calls @code{exit (0)};
+@code{scm_boot_guile} never returns. If you want some other exit
+value, have @var{main_func} call @code{exit} itself.
+
+@code{scm_boot_guile} arranges for the Scheme @code{command-line}
+function to return the strings given by @var{argc} and @var{argv}. If
+@var{main_func} modifies @var{argc} or @var{argv}, it should call
+@code{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 @var{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, @code{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, @code{scm_boot_guile} function exits, rather
+than returning, to discourage you from making that mistake.
+
+See @code{scm_init_guile}, below, for a function that can find the real
+base of the stack, but not in a portable way.
+@end deftypefn
+
+@deftypefn {C Function} void scm_init_guile ()
+Initialize the Guile Scheme interpreter.
+
+In contrast to @code{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 @code{scm_boot_guile} instead.
+
+Note that @code{scm_init_guile} does not inform Guile about the command
+line arguments that should be returned by the Scheme function
+@code{command-line}. You can use @code{scm_set_program_arguments} to do
+this.
+@end deftypefn
+
+@deftypefn {C Function} void scm_shell (int @var{argc}, char **@var{argv})
+Process command-line arguments in the manner of the @code{guile}
+executable. This includes loading the normal Guile initialization
+files, interacting with the user or running any scripts or expressions
+specified by @code{-s} or @code{-e} options, and then exiting.
+@xref{Invoking Guile}, for more details.
+
+Since this function does not return, you must do all
+application-specific initialization before calling this function.
+@end deftypefn