Overview

  The basic functionality of MzScheme can very quickly be added to any C or C++ program. To embed MzScheme in a program:

• Compile and link the MzScheme library -- libmzscheme.a -- into your program.
• Initialize a global MzScheme environment by calling  scheme_basic_env.
• Access MzScheme though  scheme_load,  scheme_rep,  scheme_eval, and/or other top-level MzScheme functions.

  MzScheme can be extended by dynamically-loaded code similarly:

• Define a C function  scheme_intialize that takes an environment pointer and installs new global primitives or syntax.
• Link the extension C/C++ files with ``mzdyn.o'' to a shared object.
• Load the shared object from Scheme with (load-extension name).

  C/C++ files using an embedded MzScheme interpreter should  #include the file ``scheme.h''; C/C++ files which are extending MzScheme dynamically should  #include the file ``escheme.h''.

  Scheme values are garbage collected using a conservative garbage collector, so pointers to MzScheme objects can be kept in any global or local variable, or in any structure allocated with  scheme_malloc. (References from  malloc'ed memory are invisible.)  scheme_malloc can also be used to allocate non-Scheme data; memory allocated this way will be automatically garbage-collected.

  A new Scheme primitive procedure is created with  scheme_make_prim_w_arity, which takes a C function pointer and returns a Scheme procedure value. This Scheme value can be installed as a global function using  scheme_add_global.

  New syntax is created with  scheme_make_compiled_syntax and  scheme_add_global. To fully support syntax (allowing printable compile code), install special callbacks with  scheme_register_syntax_executer and possibly  scheme_install_type_writer and  scheme_install_type_reader.

  Scheme exceptions are trapped by using  scheme_setjmp (which acts just like  setjmp) with  scheme_error_buf. New primitive procedures and syntax can raise a generic exception by calling  scheme_signal_error. A primitive exception can be raised with  scheme_raise_exn.