* INSTALL: Update instructions.

1 files changed, 107 insertions, 26 deletions

diff --git a/INSTALL b/INSTALL
index 6cfc1cf0..d5ea8dd8 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,47 +1,128 @@
 Requirements
 ============
 
-  * GCL-2.6.8pre
-  * Noweb
-  * Working C compiler
-  * X11 headers and libraries (optional for MinGW/MSYS)
+OpenAxiom uses the GCL (GNU Common Lisp) for its runtime support.  So,
+if you already have a running GCL (2.6.7 or 2.6.8), that is good.
+Otherwise, you would need to download a dependency tarball from
+OpenAxiom's download web site.  See instructions below.
 
----------------------------
--- Configuring OpenAxiom --
----------------------------
+OpenAxiom needs noweb for extracting its source codes.  If you don't
+have running noweb utilities, you would need to either download the
+dependency tarball from OpenAxiom's download web site, or separately
+install them, and then proceed with configuration as detailed below.
 
-Type:
-	./configure
+Note that GCL and noweb are needed only to build OpenAxiom.  They are
+not needed to run it.
 
-----------------------
--- Making OpenAxiom --
-----------------------
+Finally, you would need a working GNU C compiler.  It is also recommended
+that you install X11 development headers and libraries, especially
+Xpm.  Windows (MingW/MSYS) users do not need X11 components.  They
+still need a working GNU C compiler though.
 
-Type:
-	make
+Ah, one more note:  OpenAxiom requires GNU Make.
 
---------------------------
--- Installing OpenAxiom --
---------------------------
+1. GCL and noweb prerequisites
+   ---------------------------
 
-Type:
-	make install
+If any of GCL or noweb is missing from the environment environment
+where you're building, then you need to either separately install
+them, or download the dependency tarball
 
-==
+    open-axiom-1.0.x-dep.tar.bz2
 
-The above chain of commands should build OpenAxiom and install an
-executable script called 'axiom' in  /usr/local/bin.  You can
-configure OpenAxiom as
+Please, notice that GCL and noweb are needed only to *build*
+OpenAxiom.  If you plan to build OpenAxiom often, then it probably is
+a good idea to separately build and install those tools once for all.
 
-   ./configure --prefix=/banana/space
+If you already have GCL and noweb installed, please go to step 2.
 
-to have the script 'axiom' installed in /banana/space/bin.
+1.a. Download the dependency tarball open-axiom-1.0.x-dep.tar.bz2
 
+1.b. Decompress the dependency tarball
+
+      tar jxfv open-axiom-1.0.x-dep.tar.bz2
+
+
+    That should decompress the dependency tarball in a directory
+named   open-axiom-1.0.x.  Rename it to open-axiom-1.0.0, e.g.:
+
+       mv open-axiom-1.0.x open-axiom-1.0.0
+
+2. Building OpenAxiom
+   ------------------
+
+It is assumed you have already downloaded open-axiom source tarball,
+e.g. open-axiom-1.0.0.tar.bz2.  
+
+Note: If you don't have GCL or noweb in the build environment, please
+make sure that you have either followed the instructions in step 1.,
+or have separately installed them before proceeding.
+
+2.a. Decompress the OpenAxiom source tarball
+
+      tar jfxv open-axiom-1.0.0.tar.bz2
+
+2.b. Configure OpenAxiom
+
+      cd open-axiom-1.0.0 
+      ./configure
+
+
+It is possible to tell configure where to put the final OpenAxiom
+executables.  By default, when you just type in configure like above,
+it will configure the system with prefix /usr/local.  You can instead
+say where you want it to be installed, let's say /banana/space.  You
+would then have typed
+
+     ./configure --prefix=/banana/space
+
+2.c. Make the system
+
+Just type
+
+       make
+
+or
+
+       make 2>&1 | tee build.log
+
+if you would like to inspect the build messages later on -- but most
+users probably don't.
+
+2.d.  Have some coffee
+
+2.e.  Have more coffee
+
+It can take from 30min to 2 hours to build, depending on the
+computational power of the build machine.
+
+3. Installing OpenAxiom   
+   --------------------
+
+Once the build (step 2.) has gone successfully, you may optionally try
+to regress-test the system -- it can take hours.
+
+3.a. [optional]
+
+       make check 2>&1 | tee tests.log
+
+3.b. The system is ready to install
+
+If you configured the system to install in a place that needs special
+privilege, e.g. /usr/local that requires administrator write, please
+make sure that you've gained the adequate privileges.  Then, type:
+
+      make install
+
+3.c. The system is ready for use
+  
+
+4.  Enjoy.
 
 About Make
 ==========
 
-OpenAxiom build system requires GNU Make.  It migth theoretically be
+OpenAxiom build system requires GNU Make.  It might theoretically be
 possible to cram the Makefiles so that they can work with a large set 
 of Make programs.  However, doing so will not be cost effective.  GNU 
 Make has been ported to virtually any system current OpenAxiom can build