27.3 library and eval

The function library-load loads a library in the interpreter.

library procedure: library-exists? ident . path

Checks if the library ident exists for the current back-end.

The regular Bigloo library paths are scanned unless optional paths are sent to the function.

library procedure: library-load ident . path

Loads a library in the interpreter. In addition to dynamically loading the library, this function tries to the _e version of the library.

Libraries are searched in regular Bigloo library paths unless optional paths are sent to the function.

This version may be used for automatically exporting binding to the interpreter. In general, the _e library is a simple library that contains only one module, the module that is used to build the heap-file. For instance, let's consider an implementation of a library for SSL programming. This library is composed of a single implementation module __ssl_ssl. The library is build using a heap file:

(module __ssl_makelib (import __ssl_ssl))

Changing this file for:

(module __ssl_makelib (import __ssl_ssl) (eval (export-all)))

Enables the construction of a _e library.

When the system loads a dynamic library, it initializes it. For that it expects to find initialization entry points in the dynamic libraries that are named after the libraries name. More precisely, for the LIB_s library, the loader seeks the entry point named "LIB_s" and for the LIB_e, it seeks "LIB_e". The name of the initialization entry of a library can be changed using the declare-library! function. If that named is changed, one module of the library must contain an option module clause that sets the variable *dlopen-init* with the name of the initialization entry point.

Since Bigloo 3.1a, the runtime system supports a better way for initializing libraries. Initialization modules can be associated with a library. When loaded, these modules are automatically initialized. This new method fits harmoniously with the Bigloo initialization process and it prevents users from annotating the source code of the library.

For instance, if a library initialization file contains the following declaration:

(declare-library! 'foo :module-init 'foo)

Then, the library must implement the foo module.

(module foo (import ...) ...)

In addition if the library binds variables, functions, or classes in the interpreter then, an eval-init clause must be added to the class declaration:

(declare-library! 'foo :module-init 'foo :eval-init 'foo-eval)

Then, the module foo-eval must be implemented in the libfoo_e library.

(module foo-eval (import ...) (eval (export-all)))

The standard distribution contains examples of such construction. In particular, the multi-threading libraries pthread and fthread use this facility.