home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / CLISP-1.LHA / CLISP960530-sr.lha / doc / module.txt < prev    next >
Encoding:
Text File  |  1996-04-15  |  3.9 KB  |  102 lines
  1.                    Managing external modules for CLISP
  2.                    ===================================
  3.  
  4. CLISP has a facility for adding external modules (written in C, for example).
  5. It is invoked through clisp-link.
  6.  
  7. A module is a piece of external code which defines extra Lisp objects, symbols
  8. and functions. A module name must consist of the characters A-Z,a-z,_,0-9. The
  9. module name "clisp" is reserved. Normally a module name is derived from the
  10. corresponding file name.
  11.  
  12. clisp-link needs a directory containing:
  13.     modules.d
  14.     modules.c
  15.     module.cc
  16.     clisp.h
  17. clisp-link expects to find these files in a subdirectory linkkit/ of the
  18. current directory. This can be overridden by the environment variable
  19. CLISP_LINKKIT.
  20.  
  21. clisp-link operates on CLISP linking sets and on module sets.
  22.  
  23. A linking set is a directory containing:
  24.     makevars          some /bin/sh commands, setting the variables
  25.                         CC       the C compiler
  26.                         CFLAGS   flags for the C compiler, when compiling
  27.                         CLFLAGS  flags for the C compiler, when linking
  28.                         LIBS     libraries to use when linking
  29.                         X_LIBS   additional X window system libraries to use
  30.                         RANLIB   the ranlib command
  31.                         FILES    the list of files needed when linking
  32.     modules.h         the list of modules contained in this linking set
  33.     all the FILES listed in makevars
  34.     lisp.run          the executable
  35.     lispinit.mem      the memory image
  36. To run a clisp contained in some linking set <dir>, call
  37. "<dir>/lisp.run -M <dir>/lispinit.mem".
  38.  
  39. A module set is a directory containing:
  40.     link.sh          some /bin/sh commands, which prepare the directory
  41.                      before linking, and set the variables NEW_FILES, NEW_LIBS,
  42.                      NEW_MODULES and TO_LOAD
  43. and any other files needed by link.sh .
  44. Note that in link.sh the module set directory is referred to as "$modulename"/.
  45. The NEW_FILES variable shall contain a space-separated list of files that
  46. belong to the module set and will belong to every new linking set. The NEW_LIBS
  47. variable shall contain a space-separated list of files or C compiler switches
  48. that need to be passed to the C compiler when linking the lisp.run belonging
  49. to a new linking set. The NEW_MODULES variable shall contain a space-separated
  50. list of the module names belonging to the module set. Normally, every .c file
  51. in the module set defines a module of its own. The module name is derived from
  52. the file name. The TO_LOAD variable shall contain a space-separated list of
  53. Lisp files to load before building the lispinit.mem belonging to a new linking
  54. set.
  55.  
  56. The command
  57. "clisp-link create-module-set <module-dir> <file1.c> ..."
  58. creates a module set in <module-dir> which refers (via symbolic links) to
  59. file1.c etc. The files are expected to be modules of their own.
  60.  
  61. The command
  62. "clisp-link add-module-set <module-dir> <source-dir> <destination-dir>"
  63. combines a linking set in <source-dir> and a module in <module-dir> to a new
  64. linking set, in a directory <destination-dir> which is newly created.
  65.  
  66.                               Example
  67.                               -------
  68.  
  69. To link in the FFI bindings for the Linux operating system, the following
  70. steps are needed. (Step 1 and step 2 need not be executed in this order.)
  71.  
  72. 1. Create a new module set:
  73.  
  74.    $ clisp-link create-module-set linux /somewhere/bindings/linux.c
  75.  
  76.    Modify the newly created linux/link.sh to add "-lm" to the libraries:
  77.  
  78.    NEW_LIBS="$file_list"
  79.    -->
  80.    NEW_LIBS="$file_list -lm"
  81.  
  82.    Modify the newly created linux/link.sh to load linux.fas before saving
  83.    the memory image:
  84.  
  85.    TO_LOAD=''
  86.    -->
  87.    TO_LOAD='/somewhere/bindings/linux.fas'
  88.  
  89. 2. Compile linux.lsp, creating linux.c:
  90.  
  91.    $ clisp -c /somewhere/bindings/linux.lsp
  92.  
  93. 3. Create a new linking set:
  94.  
  95.    $ clisp-link add-module-set linux base base+linux
  96.  
  97. 4. Run and try it:
  98.  
  99.    $ base+linux/lisp.run -M base+linux/lispinit.mem
  100.    > (linux::stat "/tmp")
  101.  
  102.