27.1 Compiling and linking with a library

From the user stand point, using a library can be made two ways:

• Using the Bigloo -library lib-name option where lib-name is the name of the Bigloo library (not the name of one of the Unix files implementing the library). The name of the library must be lower case. For instance:

  $ bigloo foo.scm -library bformat

• Using the module clause library. This second solution prevent from using a special compilation option. For instance, this module will automatically compile and link with the bformat library:

  (module foo (library bformat)) ... (format ...)

When a Bigloo library lib is used, Bigloo automatically searches if a file called lib.init exists. If such a file exits, it is loaded at compile-time. For instance, that file may be used to specify compilation flags. The initialization file may affect any of the global parameters of the Bigloo compiler. A Bigloo user library might be needing additional system library. For instance, a Bigloo library supporting SSL connections is likely to be needing the a native library. Setting the compiler variable *ld-port-options* has this effect. For instance, one may define an initialization file such as:

(cond-expand
   (bigloo-compile
    (set! *ld-post-options* (string-append "-lssl " *ld-post-options*)))
   (bigloo-eval
    #unspecified))

When a Bigloo library lib is used, the Bigloo linker automatically looks at a library to be linked against the application. The name of the file containing the library depends on the operating system and the back-end used. For instance, under Unix, for a library called NAME, the Bigloo linker searches for a file called libNAME_[s|u]-VERSION.a or libNAME_[s|u]-VERSION.DYNLIB-SUFFIX in the compilation linker path when using the native back-end. It searches for a file NAME_[s|u]-VERSION.zip when the JVM back-end is used.

This default NAME can be overridden in the initialization file. The function declare-library! associates a Bigloo library name and a system name.

library procedure: declare-library! ident [attributes]

All the attributes are optional.

• version: the version number of the library. This defaults to the Bigloo version number.
• basename: the base of the filename containing the library. This default to the library name.
• srfi: a list of symbols denoting the SRFI 0 features implemented by this library. Registered SRFIs may be tested by the cond-expand form (see section SRFIs). This defaults to an empty list.
• dlopen-init: a function to be invoked when the library is dynamically loaded using the function dynamic-load. This defaults to #f.
• module-init: a module to be initialized when the library is loaded. This defaults to #f.
• eval-init: a module to be initialized for binding the library exports in the interpreter. This defaults to #f.
• class-init: the JVM or .NET class name containing the module to be initialized. This defaults to #f.
• eval-init: the JVM or .NET class name containing the module to be initialized for eval. This defaults to #f.
• init: a function to be invoked when a library is loaded. This defaults to #f.
• eval: a function to be invoked when a library is loaded for the interpreter. This defaults to #f.

Examples:

• The following declares a library named foo. When loaded the Bigloo runtime system will seek file named libfoo_s-3.1a.so, libfoo_u-3.1a.so, and libfoo_e-3.1a.so.

  (declare-library! 'foo)

• The following declares a library named pthread. When loaded the Bigloo runtime system will seek file named libbigloopth_s-1.1a.so, libbigloopth_u-1.1a.so, and libbigloopth_e-1.1a.so. Once the library loaded, the SRFI-0 features pthread and srfi-18 will be bound. When loading the library, the two modules __pth_thread and __pth_makelib will be initialized. In the JVM version these modules are compiled in the classes "bigloo.pthread.pthread" and "bigloo.pthread.make-lib".

  (declare-library! 'pthread :basename "bigloopth" :version "1.1a" :srfi '(pthread srfi-18) :module-init '__pth_thread :module-eval '__pth_makelib :class-init "bigloo.pthread.pthread" :class-eval "bigloo.pthread.make-lib")

library procedure: library-translation-table-add! ident name

library procedure: library-translation-table-add! ident name version

library procedure: library-translation-table-add! ident name version :dlopen-init initsym

The function library-translation-table-add! is obsolete. It should no longer be used in new code. It is totally subsumed by declare-library!. The function library-translation-table-add! is still documented for enabling readers to understand old Bigloo source code.

This function register a name for the library id. An optional version can be specified. The optional named argument dlopen-init gives the base name of the initialization entry point of a library.

Imagine that we would like to name our bformat library bigloobformat. This can be achieved by adding the following expression in the initialization file.

(library-translation-table-add! 'bformat "bigloobformat")

Using this translation, on a Unix platform, the library used during the linking will be named: libbigloobformat_s-<BIGLOO-VERSION>.a. In order to change the <BIGLOO-VERSION> to another suffix, such as 1.0, one may use:

(library-translation-table-add! 'bformat "bigloobformat" "1.0")

In such a case, the library searched will be named libbigloobformat_s-1.0.a.

Specifying a #f prevents the insertion of any suffix. Hence,

(library-translation-table-add! 'bformat "bigloobformat" #f)

Instruments the compiler to look at a library named libbigloobformat_s.a.