examples/box-dynamic/README

   1                                                                -*- outline -*-
   2
   3 * Overview
   4
   5 This directory includes an example program for extending Guile with a
   6 new (and even useful) data type, putting it into a shared library, so it
   7 can be called from an unmodified guile interpreter.
   8
   9
  10 * Build Instructions
  11
  12 To build the example, simply type
  13
  14   make libbox
  15
  16 in this directory.
  17
  18
  19 * The Box Data Type
  20
  21 A box is simply an object for storing one other object in.  It can be
  22 used for passing parameters by reference, for example.  You simply
  23 store an object into a box, pass it to another procedure which can
  24 store a new object into it and thus return a value via the box.
  25
  26
  27 ** Usage
  28
  29 Box objects are created with `make-box', set with `box-set!' and
  30 examined with `box-ref'.  Note that these procedures are placed in a
  31 module called (box-module) and can thus only be accessed after using
  32 this module.  See the following example session for usage details:
  33
  34 Extend your LD_LIBRARY_PATH variable (or equivalent) to include . and
  35 .libs
  36
  37
  38 ** Example Session
  39
  40 $ guile
  41 guile> (load-extension "libbox" "scm_init_box")
  42 guile> (define b (make-box))
  43 guile> b
  44 #<box #f>
  45 guile> (box-set! b '(list of values))
  46 guile> b
  47 #<box (list of values)>
  48 guile> (box-ref b)
  49 (list of values)
  50 guile> (quit)
  51 $
  52
  53
  54 * Module Installation
  55
  56 If you like this example so much that you want to have it available
  57 for normal usage, install the dynamic libraries in the .libs directory
  58 to the directory $(prefix)/lib