2.  Introduction  

      This manual can be roughly divided into two parts. The first part (chapters @(ch-arch) to @(ch-static)) describes the architectural aspects of Elk-based applications and Elk extensions. Facilities and tools for building extensible applications with Elk are introduced here. Readers who are already familiar with the concepts explained in this part of the document may want to skip it and begin reading at chapter @(ch-notes) or later. The second part (covering chapters @(ch-notes) to @(ch-advanced)) specifies the C functions and types available to application programmers and describes techniques for building data structures that can be interfaced to Scheme in an efficient way. Appendix C briefly summarizes all the functions, macros, types, and variables exported by the Elk kernel to the C/C++ programmer.

      Here is a short overview of the remaining chapters of this manual. Chapter @(ch-arch) discusses the architecture of extensible applications based on Elk and their relation to Elk extensions. Chapter @(ch-linking) provides an overview of the two basic methods for integrating an application (or extensions) with Elk: dynamic loading and static linking. Chapter @(ch-dynl) describes use of dynamic loading in more detail; topics include automatic extension initialization and C++ static constructors embedded in dynamically loaded modules. Chapter @(ch-static) describes several forms of linking user-supplied code with Elk statically and how these affect the structure of an application's main() function.

      The remaining chapters are a complete specification of the functions and types of the C/C++ programmer's interface to Elk. Chapter @(ch-notes) provides introductory notes and advice for programmers of C/C++ code interfacing to Elk (use of include files, predefined preprocessor symbols, etc.). Chapter @(ch-anatomy) describes the anatomy of Scheme objects from the C/C++ programmer's point of view. Chapter @(ch-defprim) explains how applications and extensions can define new Scheme primitives. Chapter @(ch-types) presents the standard, built-in Scheme types implemented by Elk (numbers, pairs, vectors, etc.) and functions for creating and accessing Scheme objects of these types from within C/C++ code. The facilities for defining new, first-class Scheme data types are described in chapter @(ch-deftype). Finally, chapter @(ch-advanced) deals with a number of more advanced topics, such as functions for interacting with the garbage collector, automatic finalization of inaccessible objects, definition of user-supplied reader functions, error handling, etc.

      A note on the naming conventions followed by the C identifiers used throughout this document: the names of all functions, macros, types, and variables exported by Elk have their components separated by underscores and capitalized (as in Register_Object(), for example). In contrast, the names defined by examples shown in this manual only use lower case letters, so that they can be distinguished easily from predefined functions exported by Elk.

Markup created by unroff 1.0,    September 24, 1996,    net@informatik.uni-bremen.de