Object files can be dynamically loaded into Lush using the (mod-load "mylibrary.o") construct.

Let's say you have written a C file called tt titi.c /tt with the following content:

  float sq(float x)
  {
    return x*x;
  }

You have compiled the file and produced the object file titi.o . Calling sq from the Lush interpreter is as simple as the following. First, dynamically load the object file into Lush

  ? (mod-load "titi.o")

then, write a compiled lisp function whose only purpose is to call tt sq /tt . To be able to call C from Lush:

  ? (de square (x) ((-float-) x) 
        (cheader "extern float sq(float);")
        (float #{ sq( $x ) #} )
  ? (dhc-make "junk" square)

The function square can now be called:

  ? (square 5)
  = 25

Dynamically loaded Modules can be .o object files, but also .a files (static libraries), or .so files (shared objects). Functions in dynamically loaded modules can call any external function or variable defined or used by Lush as well as external functions and variable defined in other modules. In particular, the C library functions are accessible. A function defined in a module however is not always executable. Indeed, its module might call an undefined function, or a function defined by another non executable module. In fact, four situations occur:

• Initialized and executable modules are the only accessible modules. All functions referenced by these modules have been found, and the initialization routine (e.g. init_essai ) has been succesfully executed, creating descriptors for the new lisp functions defined in the modules. At this point, all new lisp functions defined by such a module are accessible and work as expected.

  
  

• Uninitialized modules reference some undefined functions, or some functions defined by a non executable module. Therefore, the initialization function has not been executed, and the descriptors for the new lisp functions defined by such a module have not been created.

  
  

• Modules may be initialized but non executable. Such a situation occurs when a module has been initialized and executable, but is no longer executable, because it uses some function or global variable which is no longer defined, because its module has been unloaded.

  
  

• Finally, certain modules do not define an initialization function. Such modules just define C functions used by other modules. We say that such a module is in a unknown state.
  

• Shared libraries. These files usually have extension ".so" , ".sl" , ".dll" or ".dylib" depending on the operating system. Use (getconf "SOEXT") to determine which extension is valid on your system.
  
• Object files. These files usually have extension ".o" or ".obj" . Use (getconf "OBJEXT") to determine which extension is valid on your system.
  
• Library archives containing a collection of object files. Function mod-load only loads the components of a .a file that provide definitions for currently undefined symbols. You may want to use functions mod-create-reference to create fake undefined symbols and selectively load parts of the library before actually using them. WARNING: C++ static constructors are not called when a .a file is loaded. If you experience problems calling functions defined in a dynamically loadad .a files written in C++, you should first convert the .a file to a .so file (static constructors in .so files are called).

  
  

WARNING: Lush on Mac OS X has some peculiarities. First, mod-load loads object files by first creating a equivalent "bundle" file. These bundle files are stored in directory "/tmp" . Second, mod-load has no support for loading library archive. The best course of action is to first transform them into dynamic library (dylibs).

This operations encompasses three steps:

• Destroying all lisp functions previously defined by the module. Calling such functions will cause an error in the future.
  
• Relinquishing the memory utilized by the module.
  
• Checking the executability of all loaded modules, and mark the lisp functions defined by a module as partially linked, if this modules is no longer executable.

  
  

The optional argument extlist is a list of possible filename extensions. The default value is either null (when name already contains an extension) or the system dependent filename extension for shared libraries.

? (find-shared-library "libm")
= "/usr/lib/libm.so"

The optional argument extlist is a list of possible filename extensions. The default value is either null (when name already contains an extension) or the system dependent filename extension for static libraries.

? (find-static-library "libm")
= "/usr/lib/libm.a"

? (find-shared-or-static-library "libm")
= "/usr/lib/libm.so"

Example:

   ? (mod-list)
   = ("/home/leonb/lush/src/lush" "/home/leonb/test/essai.o")

Example:

   ? (mod-undefined)
   = ("compute_squares" "numbers_of_squares")

Function hookfunction is called with two arguments when the state of the module changes. The first argument is a selector symbol representing the nature of the state change. The second arguments is the module object itself.

The selector symbol can take the following values:

• init The hook function is called with selector init just after calling the initialization function of the module. Most useful hook functions will scan the list of definitions returned by module-defs and define global symbols to access the newly defined primitives.
  
• exec The hook function is called with selector exec whenever the executability of the module changes because of loading/unloading another module.
  
• unlink The hook function is called with selector unlink just before unloading the module. This is a good time to revert the changes made during the module initialization.
  

Here is an example of a file, named "essai.c" , which defines a new lisp function written in C for computing the square of the hypotenuse of triangles.

   /* ------ Beginning of File "essai.c" ------ */
   #include "header.h"
   /* This is the function that does the work */
   double hypotenuse(x,y)
   double x,y;
   {
     double z = x*x + y*y; 
     printf("hypot(%f,%f)=%f\n",x,y,z);
     return z;
   }
   
   
   /* This is the interpreter interface function */
   
   DX(xhypotenuse) {
     ARG_NUMBER(2); 
     ALL_ARGS_EVAL;
     return NEW_NUMBER( hypotenuse(AREAL(1),AREAL(2)));
   }
   
   /* This is the initialization routine.
    * Its name is formed by prepending "init_" to the file name
    */
   void init_essai()
   {
     dx_define("hypotenuse",xhypotenuse);
   }
   /* These two (optional) definitions to guarantee that
    * this module will only be loaded by compatible versions of LUSH. 
    */
   int majver_essai = 40; /* LUSH_MAJOR */
   int minver_essai = 10; /* LUSH_MINOR */
   /* ------ End of File "essai.c" ------ */

Integrating this function into the LUSH interpreter can be achieved in two ways:

• Copying this file in the "src" directory of Lush, adding "essai.o" to the list of objects in the "Makefile" , calling "init_essai()" from file "toplevel.c" and recompiling everything. This will build a new version of Lush with the new function.
  
• Compiling this file separately and loading the resulting object file into Lush at run-time. This solution is named dynamic linking of an external module. Modules are loaded with the function mod-load , and unloaded with the function mod-unload . These functions allocate the necessary memory, relocate the machine code, and resolve the external references.
  

The compilation is performed by the command:

  globina% gcc -c -I/home/leonb/lush/include essai.c

The resulting "essai.o" file can be loaded into LUSH with the following command.

  ? (mod-load "essai.o")
  = "/home/user/subdir/essai.o"
  ? (hypotenuse 3 4)
  hypot(3.000000,4.000000)=25.000000
  = 25

Example:

  globina% gdb lush
  ... GDB starts
  (gdb) run
  ... LUSH starts
  ? ;;; The following override forces compilation with -g:
  ? (setq dhc-make-overrides (alist-add "OPTS" "-g" dhc-make-overrides))
  = (("OPTS" . "-g"))
  ? ;;; Define a function
  ? (de mydiv(a b) ((-double-) a b) (/ a b))
  = mydiv
  ? (dhc-make () mydiv)
  ...
  ? (mydiv 2 3)
  = 0.6667
  ? (mydiv 2 0)
  
  Program received signal SIGFPE, Arithmetic exception.
  0x0885dcbf in ?? ()
  (gdb) call dld_print_gdb_commands(1)
       add-symbol-file /home/leonb/lush/C/i686-pc-linux-gnu/mydiv.o 0x885dc84 \
           -s .text 0x885dc84 -s .data 0x885dd44 -s .bss 0x885ddf8 -s .rodata 0x885ddf8
  $1 = 10
  (gdb) add-symbol-file /home/leonb/lush/C/i686-pc-linux-gnu/mydiv.o 0x885dc84 \
           -s .text 0x885dc84 -s .data 0x885dd44 -s .bss 0x885ddf8 -s .rodata 0x885ddf8
  add symbol table from file "/home/leonb/lush/C/i686-pc-linux-gnu/mydiv.o" at
        .text_addr = 0x885dc84
        .text_addr = 0x885dc84
        .data_addr = 0x885dd44
        .bss_addr = 0x885ddf8
        .rodata_addr = 0x885ddf8
  (y or n) y
  Reading symbols from /home/leonb/lush/C/i686-pc-linux-gnu/mydiv.o...done.
  (gdb) where
  #0  0x0885dcbf in C_mydiv (L1_a=2, L1_b=0) at /home/leonb/lush/C/mydiv.c:28
  #1  0x0885dd00 in X_mydiv (a=0xbfffbaa8) at /home/leonb/lush/C/mydiv.c:44
  #2  0x0810e8f0 in dh_listeval ()
  (gdb) up
  #1  0x0885dd00 in X_mydiv (a=0xbfffbaa8) at /home/leonb/lush/C/mydiv.c:44
  44        ret.dh_real = C_mydiv (a[1].dh_real, a[2].dh_real);
  (gdb) down
  #0  0x0885dcbf in C_mydiv (L1_a=2, L1_b=0) at /home/leonb/lush/C/mydiv.c:28
  28          L_Tmp0 = (L1_a / (real) L1_b);
  (gdb) print L1_b
  $2 = 0      ### HAHA. Bug was found.

GDB contains decent support to debug code contained in shared libraries (i.e. files with extension ".so" ). Another possibility for debugging modules consists in building them as shared libraries.

Example:

  globina% gcc -shared -o essai.so -I/home/leonb/lush/include  essai.c
  globina% gdb lush
  ... GDB starts
  (gdb) run
  ... LUSH starts
  ? (mod-load "essai.so")
  = "/home/leonb/essai.so"
  <CTRL-C>
  (gdb) br xhypotenuse
  Break in xhypotenuse
  (gdb) cont
  ? (hypotenuse 3 4)
  Breakpoint 1, 0x4001a8c1 in xhypotenuse () from /home/leonb/essai.so
  (gdb) ....

There are two limitations:

• Shared libraries must be completely linked. They can only reference symbols contained in the main lush executable and its libraries (not in other dynamically loaded modules)
  
• Shared libraries cannot be unloaded and replaced by another version.