Writing MzScheme Extensions

To write a C/C++-based extension for MzScheme, follow these steps:

• For each C/C++ file that uses MzScheme library functions, #include the file escheme.h.

  This file is distributed with the PLT software in plt/collects/mzscheme/include, but if mzc is used to compile, this path is found automatically.

• Define the C function scheme_initialize, which takes a Scheme_Env * namespace (see section 2.3) and returns a Scheme_Object * Scheme value.

  This initialization function can install new global primitive procedures or other values into the namespace, or it can simply return a Scheme value. The initialization function is called when the extension is loaded with load-extension (the first time); the return value from scheme_initialize is used as the return value for load-extension. The namespace provided to scheme_initialize is the current namespace when load-extension is called.

• Define the C function scheme_reload, which has the same arguments and return type as scheme_initialize.

  This function is called if load-extension is called a second time (or more times) for an extension. Like scheme_initialize, the return value from this function is the return value for load-extension.

• Compile the extension C/C++ files to create platform-specific object files.

  The mzc compiler, distributed with MzScheme, compiles plain C files when the --cc flag is specified. Actually, mzc does not compile the files itself, but it locates a C compiler on the system and launches it with the appropriate compilation flags. If the platform is a relatively standard Unix system, a Windows system with either Microsoft's C compiler or gcc in the path, or a MacOS system with Metrowerks CodeWarrior installed, then using mzc is typically easier than working with the C compiler directly.

• Link the extension C/C++ files with mzdyn.o (Unix) or mzdyn.obj (Windows) to create a shared object.

  The mzdyn object file is distributed in a platform-specific directory in plt/collects/mzscheme/lib for Unix or Windows, but it is not distributed for MacOS.

  The mzc compiler links object files into an extension when the --ld flag is specified, automatically locating mzdyn. Under MacOS, mzc generates the mzdyn object file as necessary.

• Load the shared object within Scheme using (load-extension path), where path is the name of the extension file generated in the previous step.

IMPORTANT: Scheme values are garbage collected using a conservative garbage collector, so pointers to MzScheme objects can be kept in registers, stack variables, or structures allocated with scheme_malloc. However, static variables that contain pointers to collectable memory must be registered using scheme_register_extension_global (see section 2.2).

As an example, the following C code defines an extension that returns "hello world" when it is loaded:

 #include "escheme.h"
 Scheme_Object *scheme_initialize(Scheme_Env *env) {
   return scheme_make_string("hello world");
 }
 Scheme_Object *scheme_reload(Scheme_Env *env) {
   return scheme_initialize(env); /* Nothing special for reload */
 }

Assuming that this code is in the file hw.c, the extension is compiled under Unix with the following two commands:

  mzc --cc hw.c
  mzc --ld hw.so hw.o 

The plt/collects/mzscheme/examples directory in the PLT distribution contains additional examples.