29.5 Building a library

Build Bigloo libraries require several steps that are explained in this section. This section shows how to create static and dynamic (or shared) libraries. However not that creating a dynamic library highly dependent on the host operating system. Users willing to create dynamic libraries on other operating systems should use the api directory of the Bigloo source code tree as an example.

• The first step is to build a library heap. This is achieved using a special compilation mode: -mkaddheap -mkaddlib -addheap -heap-library <ident>. That is, for your library you have to create a heap associated source file that imports all the binding you want in your library. The heap source file must be excluded from the source files that will be used to build the host library.

  Suppose we have a unique source file, bformat.scm for our library. The module clause of this source file is:

  (module __bformat
     (export (bformat fmt::bstring . args)
             bformat:version))
  
  (define (bformat fmt . args)
     (apply format (string-replace fmt #\% #\~) args))
  
  (define bformat:version 1.0)
  

  Prior to compiling the library, we have to create the heap associated file (let’s name it make_lib.scm). This file could be:

  (module __make_lib
     (import (__bformat "bformat.scm"))
     (eval (export-all)))
  

  Building it is simple:

  bigloo -unsafe -safee -q -mkaddheap -mkaddlib -heap-library bformat \
       make_lib.scm -addheap bformat.heap
  

  The options -mkaddheap and -mkaddlib tell Bigloo that it is compiling an heap associated file. The option -addheap tells Bigloo the name of the heap file to be produced. The option -heap-library instructs the compiler for the library name to be included inside the heap file. This name is used for checking versions at run-time.

• The second step is to compile all the library source file. These compilation must be done using the -mkaddlib compilation mode. For example:

  bigloo -O3 -unsafe -safee -mkaddlib       \
     -cc gcc -fsharing -q -rm               \
     -unsafev bformat.scm -o bformat_u.o -c
  bigloo -O3 -mkaddlib -g -cg -cc gcc       \
     -fsharing -q -rm                       \
     -unsafev bformat.scm -o bformat.o -c
  

  The first compilation produces the unsafe version the second the produced the debugging version.

• The third step is to build the host operating system libraries. There is no portable way to do this. This operation may looks like:

  ar qcv libbigloobformat_s-1.0.a bformat.o
  ranlib libbigloobformat_s-1.0.a
  ld -G -o libbigloobformat_s-1.0.so bformat.o -lm -lc
  ar qcv libbigloobformat_u-1.0.a bformat_u.o
  ranlib libbigloobformat_u-1.0.a
  ld -G -o libbigloobformat_u-1.0.so bformat_u.o -lm -lc
  

• The fourth step consist in creating the bformat_es and bformat_eu libraries for eval. For the unsafe version we use:

  bigloo -O3 -unsafe -safee -mkaddlib       \
     -cc gcc -fsharing -q -rm               \
     -unsafev make_lib.scm -o make_lib.o -c
  ld -G -o libbigloobformat_eu-1.0.so make_lib.o -lm -lc
  ar qcv libbigloobformat_eu-1.0.a make_lib.o
  ranlib libbigloobformat_eu-1.0.a
  

  For the safe version we do:

  bigloo -O3 -mkaddlib              \
     -cc gcc -fsharing -q -rm               \
     -unsafev make_lib.scm -o make_lib.o -c
  ld -G -o libbigloobformat_es-1.0.so make_lib.o -lm -lc
  ar qcv libbigloobformat_es-1.0.a make_lib.o
  ranlib libbigloobformat_es-1.0.a
  

• The last step is to create an initialization file bformat.init:

  (declare-library! 'bformat 
     :version "1.0"
     :srfi '(bformat)
     :basename "bigloobformat"
     :module-init '__bformat
     :module-eval '__make_lib
     :class-init "bigloo.bformat.__bformat"
     :class-eval "bigloo.bformat.__make_lib")
  

At this time, you are ready to use your library. For that, let’s assume the file foo.scm:

(module foo
   (library bformat))

(bigloo-library-path-set! (cons (pwd) (bigloo-library-path)))
(print (bformat "Library path: %a" (bigloo-library-path)))

(eval '(library-load 'bformat))
(repl)

It can be compiled and executed with:

bigloo foo.scm -L . -copt -L.
LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH ./a.out

The Bigloo distribution contains library exemplars that should probably considered as a departure point for new libraries.

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