elk/INSTALL

$Id$

Compilation and Installation Instructions for Elk
-------------------------------------------------


1. Change to the directory "config" and choose the configuration file for
   your type of system.
   
   The names of the config files have three parts separated by dashes:
   machine-os-compiler.  "machine" identifies the type of hardware, "os" is
   the operating system name and version, and "compiler" identifies the C
   compiler to be used to compile Elk.

   When you have selected a config file, make a symbolic link "system" to
   it (or a hard link, or copy it), for example:

      ln -s alpha-osf1-cc system

   If you can't find a suitable config file for your system, create a new
   one by copying one of the existing files (preferably one that resembles
   your platform).  Edit the new file and change the definitions that need
   to be changed for your type of platform.

   Alternatively, you may find a suitable config file in config/untested.
   These config files have been provided by users of earlier Elk releases,
   or they are for platforms to which I don't have access any longer.  In
   any case, they may or may not work, as the current Elk release has not
   been tested with any of these.

   
2. Edit the file config/site and have a look at the definitions.  Change
   "install_dir" to point to the directory under which the Elk runtime
   system will be installed on your system.  Also, remove -L/usr/X11/lib
   from all definitions if the X libraries reside in a standard location.

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


3. Change back to the directory where you unpacked the distribution and
   have a look at the SUBDIRS definition in the Makefile.  Delete any
   components that you don't want to install (for example, delete
   lib/xm and lib/xm/xt if you don't have Motif and/or don't want the
   Motif extension).


4. You may want to look up your type of platform in the file MACHINES for
   further information and potential pitfalls with specific compilers and
   operating system versions.


5. Run "make install" (or just "make" and then "make install").


6. Invoke the Scheme interpreter ($install_dir/scheme) and test it by
   typing a few Scheme expressions or by loading some of the example
   programs from the "examples" directory tree.
   
   If your platform supports dynamic loading of object files, test it by
   loading, for example, one of the programs from examples/unix.  You
   may also want to run some of the X11 demonstration programs to check
   whether the X11 extensions work.

   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
   with a number of extensions statically.  For example, to create an
   interpreter with the UNIX extension, you can change to $install_dir and
   type:

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

   (see below for more information).  Invoke the newly created unixelk
   interpreter and test it with the examples programs in examples/unix.
   


Roadmap for $install_dir (files that are created by running "make install")
---------------------------------------------------------------------------


+-- bin ---- scheme     The Scheme interpreter proper
|
|
+-- include --  The include files to be included by Elk extensions and by
|               applications using Elk (actually, only "scheme.h" is used;
|               scheme.h then includes the right files).  config.h is created
|               automatically; do not edit it.  The include files may or may
|               not use function prototypes, depending on the config file you
|               used for building Elk.
|
|
+-- runtime --+-- scm --     The Scheme files used by Elk during runtime, such
|             |              as the interactive toplevel and the debugger
|             |
|             `-- obj --     The dynamically loadable objects used at runtime.
|                            The directory may be empty if your platform does
|                            not support dynamic loading.  There are sub-
|                            directories for the Athena widgets and Motif
|                            extensions holding one object per widget class
|
|
+-- lib --+-- standalone.o   The Scheme interpreter as an object file.  This
          |                  file can be linked with extensions or with your
          |                  application to produce a runnable executable.
          |                  On startup the executable automatically invokes
          |                  extension initializers (beginning with elk_init_)
          |                  and C++ static constructors by scanning its own
          |                  symbol table (ditto for finalizers/destructors).
          |                  You may want to use the script linkscheme to link
          |                  with standalone.o, as additional libraries may
          |                  be required.
          |
          +-- module.o       Like standalone.o, except that it doesn't have
          |                  a main() function.  main() must be provided by
          |                  your application and must call Elk_Init():
          |
          |                  Elk_Init(int argv, char **argv, int initflag,
          |                           char *file);
          |
          |                  argc/argv are the arguments of your main().  You
          |                  may change them, but argv[0] MUST be the original
          |                  argv[0] (Elk_Init takes its address to determine
          |                  the stackbase.  If initflag is non-zero, Elk_Init
          |                  calls the extension initializers as described
          |                  above.  file is zero or the name of a Scheme file
          |                  to be loaded by Elk_Init.
          |
          +-- linkscheme     Shell script to link standalone.o with a number
          |                  of object files (extensions or your application)
          |                  and libraries.  The first argument is the name of
          |                  the output file; all other arguments are passed
          |                  to the linker.
          |
          +-- makedl         Shell script to create a dynamically loadable
          |                  object from one or more .o files.  The first
          |                  argument is the output file name.
          |
          `-- ldflags        Prints the flags to be used when linking files
                             with Elk (with standalone.o or module.o).  You
                             may use this in your Makefiles.

For more details, read the C/C++ Programmer's Manual (doc/cprog).



How the Makefiles in the Elk distribution are organized
-------------------------------------------------------

Each source directory contains a small Makefile with a few standard rules;
all these 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' 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/siteinfo.scm.

`make clean' causes everything 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.