To compile and install Elk on your system do the following:
===========================================================

1) Change into the directory "config" and choose the configuration file
   for your type of system.
   
   The names of the configuration files follow the convention
   "machine-os-compiler", where "machine" identifies the type of
   hardware (CPU, manufacturer, ...), "os" is the operating system
   version, and "compiler" identifies the C compiler to be used to
   compile the sources.

   When you have selected a configuration file, make a symbolic link
   "system" to it (or a hard link, or copy it).

   If you can't find a suitable configuration file for your system,
   create a new one by copying one of the existing files.  Edit the
   new file and change the definitions that need to be changed for
   your type of system.  When you are done and everything works, mail
   the new file to <net@cs.tu-berlin.de>, so that it can be made part
   of the next release of Elk.

   Also, you may find a config file suitable for your platform in
   config/untested.  I haven't tested the current release of Elk with
   any of these config files (either because they are based on
   information provided by users of Elk, or because I do not have
   access to these machines any longer).

2) Edit the file config/site and change the definitions that need to
   be changed for your site.  In particular, let $install_dir point to
   the directory under which all the files are to be installed.

   The directory config/sites holds a few locally used site files for
   different operating systems; you may find these useful (in
   particular the libx* variables).

3) If necessary, edit the top-level Makefile and remove those components
   from SUBDIRS that you don't want to compile and install.

4) Look up your type of platform in the file MACHINES for further
   information and potential problems with specific compilers and
   operating system versions.

5) Run "make" and, if this has finished successfully, "make install".

6) Invoke the interpreter ($install_dir/scheme) and test it by typing a
   few Scheme expressions and by loading some of the example programs
   from the "examples" directory tree.
   
   If your platform supports dynamic loading of object files, test
   it by typing, for example,  "(require 'record)" and then
   "(make-record-type 'time '(hours minutes seconds))".

   If freezing of a running program into a new executable ("dump") is
   supported, test it by typing "(dump 'newelk)", then quit the interpreter,
   and finally invoke newelk and see if it works.

7) If your system does *not* support dynamic loading of object files,
   you may want to create an instance of the interpreter that is linked
   together with extensions statically.  For example, to create an
   interpreter with the UNIX extension, you can go to $install_dir and
   type:

      lib/linkscheme bigelk runtime/obj/unix.o runtime/obj/record.o

   (see below for more information).  Then run the newly created "bigelk"
   and test it with the example programs in examples/unix.


Files that get installed by "make install" (all relative to $install_dir):
==========================================================================

   bin/scheme

      The Scheme interpreter proper.

   include/*.h

      The include files to be used when compiling Elk extensions.  Some
      of these files are created from the include files in the source
      directory tree by performing platform-specific substitutions on them.

   lib/standalone.o

      The Scheme interpreter as a pre-linked object file.  This file
      can be linked with extensions and/or an application to produce
      a new executable.  This executable, when started, automatically
      invokes extension initialization functions and C++ static
      constructors (and finalization functions and destructors on
      termination).

      When this file is linked, the flags displayed by the lib/ldflags
      shell script have to be specified, as the interpreter may require
      additional libraries and linker options.  To simplify linking with
      standalone.o, you may want to use the shell script lib/linkscheme.

   lib/module.o

      Another pre-linked object file containing the Scheme interpreter.
      In contrast to standalone.o, module.o doesn't have a main() function.
      It can be linked by applications that have to support their own
      main().

      In place of a main() function, lib/module.o exports a function

          Elk_Init(int argc, char **argv, int call_initializers, char *fn);

      that you have to invoke once in your application to initialize Elk.
      argc and argv are the arguments of your application's main(); at
      least argv[0] must be present and point to the program's file name.

      If call_initializers is non-zero, Elk_Init() invokes the extension
      initialization functions (but, in contrast to lib/standalone.o,
      *not* the C++ static constructors and destructors, as this is already
      performed by the application's main() function).  In this case,
      the finalization functions are called on termination, accordingly.

      If "fn" is non-zero, it specifies the name of a Scheme file to
      be loaded initially (typically the application's `toplevel').

      As with standalone.o (see above), the linker flags displayed by
      lib/ldflags must be specified when linking with module.o.

   lib/linkscheme

      Links lib/standalone.o with extensions, application-specific object
      files, and additional libraries.  The first argument is the name
      of the output file, the remaining arguments are passed to the
      linker.  You do not need to use lib/ldflags when running this script.

   lib/makedl

      This shell script creates a dynamically loadable object file from
      one or more (plain) object files.  It invokes the linker with
      suitable options.  Arguments are the output file name and one
      or more object files.

   lib/ldflags

      This one-liner displays the flags to be specified when linking
      lib/standalone.o or lib/module.o.  You are supposed to invoke
      this script in your Makefiles when developing extensions for or
      an application with Elk.

   runtime/scm/*.scm

      The Scheme files used by the Scheme interpreter at runtime
      (such as the debugger and the toplevel).

   runtime/obj/*.o   runtime/obj/*/*.o

      The dynamically lodable object files used at runtime.  Various
      subdirectories are created under runtime/obj.
   

How the Makefiles in the Elk distribution are organized:
========================================================

   Each source directory contains a small Makefile with a few standard
   rules; all the Makefiles are basically identical.  The actual rules
   are in Makefile.local in each directory; Makefile.local is automatically
   created on the fly by a shell script `build' in each directory whenever
   Makefile.local is out-of-date with respect to config/system or
   config/site.
   
   The `build' shell scripts "localize" the information in each
   Makefile.local by performing variable substitutions based on the
   definitions in config/system and config/site.  `build' also
   localizes a few other files that contain site-specific information,
   such as include/config.h and scm/xwidgets.scm.

   `make clean' causes the software to be rebuilt the next time `make'
   is invoked.  `make distclean' also deletes the Makefile.local
   instances, causing each Makefile.local and all other files with
   site-specific contents to be rebuilt as well.
