29.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: bigloo-library-path

library procedure: bigloo-library-path-set!

These functions get and set the default path (a list of strings) for loading libraries.

library procedure: library-load ident . path

Loads a library in the interpreter. In addition to dynamically loading the library, this function tries to load the _es version of the library if it is linked against the safe Bigloo library version or the _eu version if it is linked against the unsafe version of the Bigloo library.

Searches for libraries occur in the regular Bigloo library paths unless optional paths are sent to the function.

This version may be used for automatically exporting bindings to the interpreter. In general, the _es and _eu libraries are simple libraries that contain 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 the _es and _eu libraries.

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 library’s name. More precisely, for the LIB_s library, the loader seeks the entry point named "LIB_s" and for the LIB_es, it seeks "LIB_es". 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 relieves users from any requirement to annotate 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_es and libfoo_eu libraries.

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

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

This document was generated on March 31, 2014 using texi2html 5.0.