libguile/DYNAMIC-LINKING

   1 Random notes about dynamic linking for Guile. I will update this file
   2 as I go along. Comments are very welcome. I can be reached at
   3 mvo@zagadka.ping.de (Marius Vollmer).
   4
   5 The dynamic linking support is mostly untested. I can't test it
   6 because I don't have all the different platforms, of course. Please
   7 try it out.
   8
   9 To enable support for dynamic linking in libguile, give the
  10
  11     --enable-dynamic-linking
  12
  13 option to configure. It is disabled by default because it will
  14 probably cause lots of problems in its present state. Currently there
  15 is support for -ldld, -ldl, HP-UX (and VMS, but not really).
  16
  17 Files affected:
  18
  19  dynl*           new
  20  configure.in    add --enable-dynamic-linking option and checking for
  21                  system dependencies
  22  Makefile.am     include dynl* in build and dist.
  23  init.c          initialize dynamic linking support
  24
  25 Here is my plan with indications of progress.
  26
  27 - port "dynl.c" and maybe some parts of "Link.scm" from SCM to
  28   Guile. This should not be difficult, maybe I can even squeeze the
  29   VMS code into the "dynl:link", "dyn:call" interface.
  30
  31 * Mostly done, except VMS, and almost completely untested. The -dl
  32   support should work, but the rest has not even been compiled.
  33
  34   The code is in the "dynl*" files. "dynl.c" is the system independent
  35   portion and includes the appropriate system dependent file, either
  36   "dynl-dld.c", "dynl-dl.c" or "dynl-shl.c".
  37
  38   I have renamed the SCM names of the functions, because they didnn't
  39   fit very well into Guile, the semantics are mostly the same:
  40
  41     SCM name       Guile name
  42
  43     dynl:link      dynamic-link FILENAME
  44     dynl:call      dynamic-call SYMBOL DYNOBJ
  45     dynl:main-call dynamic-args-call SYMBOL DYNOBJ STRING-LIST
  46     dynl:unlink    dynamic-unlink DYNOBJ
  47
  48   I plan to generalise dynamic-call and dynamic-args-call to work with
  49   arbitrary arguments, so these names are likely to change.
  50
  51 * There's now one new function
  52
  53     dynamic-func SYMB DYNOBJ
  54
  55   It determines the address of a function in a dynamic object.  The
  56   result of this function can be used with `dynamic-call' and
  57   `dynamic-args-call' as the SYMBOL.
  58
  59   PROBLEMS:
  60
  61   Can tsort cope with blank lines? This situation arises when
  62   configure substitutes nothing for @xtra_PLUGIN_guile_libs@.
  63
  64   You may need to link your application in a special way to make
  65   dynamic linking work. For example, on Linux and a statically linked
  66   libguile.a, you need -rdynamic to make the libguile symbols
  67   available for dynamic linking. The solution is probably to build
  68   libguile as a shared library on the systems that support it. Libtool
  69   seems to be the right solution.
  70
  71 * Libguile is now build using libtool and it works fine for me.
  72
  73
  74 - see how to couple dynamic linking with the module system. Dynamic
  75   objects should have a way to specify the module they want to add
  76   their bindings to. Extend this to statically linked parts of
  77   guile. (i.e. posix could be put into a module and initialized on
  78   demand)
  79
  80 * Maybe it will suffice to have scm_make_gsubr, etc to honor the
  81   current scm_top_level_lookup_closure and do all the module switching
  82   from Scheme.
  83
  84 * I now have modified scm_sysintern to use the lookup procedure when
  85   there is one.  This is a temporal hack while waiting for the module
  86   system to be accessible from C.
  87
  88
  89 - use gtcltk as a test case for the above, so that TCL/Tk capabilities
  90   can be added to guile at runtime.
  91
  92 * Works.
  93
  94   When you link libgtcltk into your application and initialize it with
  95
  96     scm_init_gtcl ();
  97     scm_init_gtk ();
  98
  99   you get the old behaviour.  If you initialize it with
 100
 101     scm_init_ice_9_gtcltk_module ();
 102
 103   the TCL/Tk functions are made available in a module called
 104   #/ice-9/gtcltk.
 105
 106   When you don't link libgtcltk into your application but put it
 107   somewhere in your %load-path, it will be linked dynamically upon the
 108   first `:use-module #/ice-9/gtcltk'.  Using the %load-path for this
 109   is probably not very smart.
 110
 111   From boot-9:
 112
 113 ;;; Dynamic linking of modules
 114
 115 ;; Initializing a module that is written in C is a two step process.
 116 ;; First the module's `module init' function is called.  This function
 117 ;; is expected to call `scm_register_module_xxx' to register the `real
 118 ;; init' function.  Later, when the module is referenced for the first
 119 ;; time, this real init function is called in the right context.  See
 120 ;; gtcltk-lib/gtcltk-module.c for an example.
 121 ;;
 122 ;; The code for the module can be in a regular shared library (so that
 123 ;; the `module init' function will be called when libguile is
 124 ;; initialized).  Or it can be dynamically linked.
 125 ;;
 126 ;; You can safely call `scm_register_module_xxx' before libguile
 127 ;; itself is initialized.  You could call it from an C++ constructor
 128 ;; of a static object, for example.
 129 ;;
 130 ;; To make your Guile extension into a dynamic linkable module, follow
 131 ;; these easy steps:
 132 ;;
 133 ;; - Find a name for your module, like #/ice-9/gtcltk
 134 ;; - Write a function with a name like
 135 ;;
 136 ;;     scm_init_ice_9_gtcltk_module
 137 ;;
 138 ;;   This is your `module init' function.  It should call
 139 ;;
 140 ;;     scm_register_module_xxx ("ice-9 gtcltk", scm_init_gtcltk);
 141 ;;
 142 ;;   "ice-9 gtcltk" is the C version of the module name. Slashes are
 143 ;;   replaced by spaces, the rest is untouched. `scm_init_gtcltk' is
 144 ;;   the real init function that executes the usual initilizations
 145 ;;   like making new smobs, etc.
 146 ;;
 147 ;; - Make a shared library with your code and a name like
 148 ;;
 149 ;;     ice-9/libgtcltk.so
 150 ;;
 151 ;;   and put it somewhere in %load-path.
 152 ;;
 153 ;; - Then you can simply write `:use-module #/ice-9/gtcltk' and it
 154 ;;   will be linked automatically.
 155 ;;
 156 ;; This is all very experimental.
 157
 158
 159 - see how G-Wrap and libffi can work together and extend dyn:call to
 160   functions taking arbitrary arguments. Something along the lines
 161
 162     (define XOpenDisplay (make-foreign-function X11-lib 'XOpenDisplay
 163                                                 .. whatever args ..))
 164
 165 * I have received Guile libffi glue code from Anthony Green but I have
 166   yet to try it out.
 167
 168 * There is now some code at
 169
 170     http//www-nt.e-technik.uni-dortmund.de/m_mvo/guile-ffi-970501.tar.gz
 171
 172   but it doesn't address G-Wrap.