Copyright (c) 1996 by Alexandre Frey. All rights reserved.

0/ Warning
-----------
Dload is not far from being a hack. It is provided AS IS without any
garanty whatsoever. I'm not even sure if it won't destroy your files
or crash your disk ... 

Dload is distributed freely, provided that the copyright notice in
each files remains intact.

Bug reports, comments, suggestions, improvements, flames, or simply
use reports are welcome !! Send them to frey@lix.polytechnique.fr.

1/ Overview
-------------
This directory contains the source files of Dload, a package to
provide dynamic linking to Bigloo, a Scheme system by Manuel Serrano,
based on BFD, the Binary File Descriptor library from GNU.

The package is rather portable since it benefits from all the efforts
made in BFD.

2/ Installation
-----------------
a. Requirements

You need bigloo version 1.7 and BFD version >= 2.6.  

If you don't have BFD on your system (it comes with binutils, gdb,
gas, gld ...), you can download the archive bfd-2.6.tar.gz which
contains all the files needed by Dload. Note that Dload may be
compiled and linked with older versions of BFD, but it may also not
work correctly.

On some systems, a bug in BFD leads to incorrect overflow checking
when performing a relocation. bfd-2.6.patch corrects the problem.

b. Edit the Makefile to suit your system.

If you want to compile Dload with an already installed BFD library,
comment the line BFD = ...

b. type `make all'

This will produce the files libdload.a and dload.bgl

c. type `make install'

You may have to be root to do that.

3/ Quick reference 
------------------- 
. Place an (import dload) directive in your module. Bigloo must know
where to find the interface dload.bgl. At your option you may type
-access dload .../dload.bgl in the bigloo command line or use a afile
or a rc file . See bigloo documentations for details.

. You must link your application with libdload.a, libbfd.a and
libiberty.a . Type -ldload -lbfd -liberty in the command line.

. Once linked, and before stripping the executable, you must execute
the utility dloadmap on it. This will produce a map file of static
symbols with extension .map.

. Before using any function of Dload, you must call the function
(dload-init <static-map-filename>) where <static-map-filename> is
the name of the file produces by dloadmap.

. Dynamic modules are loaded and linked in structures called
`unit'. You create such an object by calling (make-empty-unit). You
test if an object is a unit with the predicate unit?.

. You load object files or libraries with (dload <unit> <filename>).
This function loads the file and automatically link it with the
previoulsy loaded files and with the libraries listed in the variable
*default-lib*. The returned value is a boolean which indicates whether
the unit can be used or if there remain undefined symbols.

An optional boolean argument <use-static?> may be passed to dload. If it
is true, the file is not really loaded but dload use the static values
corresponding to the defined symbols of the file. Typically you can do
that when you have linked the file statically with your application.
By default, this argument is #f (except for the libraries in
*default-lib*, normally the c, math and bigloo libraries).

. You can then initialize a module with (module-initialize <unit>
<module-name>) where <module-name> is the symbol used in the module
declaration of a file linked in <unit>.

. Now, you use (get-symbol-value <unit> <module-name> <var-name>) to
get the value of a variable and (set-symbol-value! <unit>
<module-name> <var-name> <value>) to set it. Note that you can't set!
a immutable function since it is compiled to a c function. 

. *static-unit* is a special unit which gathers all the static
symbols, you can apply get-symbol-value and set-symbol-value! on it
but not dload.

. Note that an arbitrary number of units can be created and an object
file may be loaded several times (in different units) without
interaction (except of course if you use static values).

Have fun !

--
Alexandre Frey
<frey@lix.polytechnique.fr>








