                       Fetching and Building REDUCE
                       ============================

[This document was written some while ago and needs a full review - I
am putting this comment in in September 2014 as a reminder to prompt
that re-work. ACN]

The prerequisites for using this package will depend somewhat on whether
you choose to use the CSL or PSL build.

At present most users of PSL will use the ready-build binaries of the PSL
Lisp system that are fetched when you configure that option, and so almost no
special development tools are required. However the full sources and some
scripts for bootstrap-building of PSL Lisp from scratch are being provided,
and anybody wishing to experiment in that area should check the PSL-specific
parts of the tree and if necessary post enquiries on the mailing list and/or
forum to check which cases are currently supported.

For CSL you need to be able to compile both CSL itself and the FOX toolkit
on which it depends. Please note that even if you have FOX available already
on your computer the code her uses a (slightly) customised version and your
standard system-wide installation of FOX will not be used and should be
irrelevant here.
   For Windows, the "cygwin" environment providing a "bash" shell.
       Note that building under "msys" or the plain Windows command
       prompt is not possible. Obviously it will be sensible to keep your
       cygwin installation up to date, and some updates there have in the
       past not always been upards compatible. The aim is to keep the
       current CSL/Reduce at Sourceforge buildable using the most recent
       cygwin release. But any difficulty due to temporary bugs or glitches
       at the cygwin end can not be resolved here!
   GNU make (other versions of "make" are not liable to work), autoconf
       and automake. Well you can probably survive without having autoconf
       and automake, but if you have them you should use a reasonably up to
       date version.
   For CSL you need a C/C++ development context. On Windows you
       need the "mingw64-i686" and possily the "mingw-x86_64" compiler
       variants (as well as plain gcc) from cygwin while on other systems
       you need X11 and other development capability, including Xft,
       fontconfig, (n)curses, Posix threads.

One of the most common problems people seem to have the first time that they
try to build CSL arises when they do not have quite all the necessary tools,
libraries and header files installed. While most relevant run-time libraries
are liable to have been provided for them by default, the development versions
might not have. On a 64-bit Linux it can also be nice to have the libraries
and compiler options that make it possible to compile and run 32-bit code as
well as 64-bit. The state of your cygwin installation can be checked using
scripts/cygwin-sanity-check.sh but please be aware that the tests that does
are indicative rather than definitive and when (occasionally) either Reduce
is extended and additional dependencies arise or cygwin is reorganised and the
names of some packages alter the tests may become outdated.

If you try to build REDUCE but one of the programming tools or development
libraries that is required is not available then there is no guarantee that
the failure that results will describe itself to you clearly.

To try to make that easier to cope with I provide a script that attempts to
check for prerequisites and that is lighter weight than the full configuration
process and maybe reports trouble in a cleaner way. To use it select the
Reduce "trunk" directory as current and at a bash prompt (you MUST have
"bash" available as a shell, and you will run least rish if you run all scripts
from it. I have tried to make most of them compatible with a legacy /bin/sh
but testing and guaranteeing that is tedious) go
      scripts/csl-sanity-check.sh
This should run auto-configure scripts and eventually compile and run a small
program that pops up a dull window. If you get the window at the end it has
succeeded and you can try building Reduce. If not then it probably reports
a step where some header file or library is missing. You need to search the
installation sources relevant your operating system and install more stuff,
then try again. Eg for cygwin you re-run "setup", while on Linux I like it when
my distribution lets me use "synaptic", but "apt-get" and "yum" and various
other package managers can also be used. You need to check the documentation
of your particular operating system - or perhaps better fina local expert to
get you started.

Note that if you configure using "--with-csl --with-wx" you also need GTK2
(GTK+) development files if you are on an X11-based platform, but at present
csl-sanity-check.sh does not test for that.

Some people may find that they need things that are not installed on
their system but they have not been granted adminitrator authority and so
can not merely install them in the obvious way. The easiest response is to
talk to a local system manager! But for a range of the tools (eg autoconf,
make, ncurses etc) if you can not identify a ready-built binary
package that suits your environment it will be easy to build one from sources
found "at the usual places", and may be easy to arrange that the resulting
binaries are on your PATH and libraries somewhere where they will be found.
But in such a case you may end up needing to hand-patch some of the Makefiles
here.

If you have run the main CSL/Reduce configure step, as in
   ./configure --with-csl
and tried "make" at a stage when you do not have all relevant headers and
libraries installed then the build can fail part way through in a messy way.
In principle you can check ALL the logs and work out what happened, but in
reality that can be daunting. Furthermore it can get in a state where a
subsequent use of "make" fails in an unhelpful manner. Experts can patch things
up and recover, but the simplest approach in case of confusion is
   rm -rf cslbuild
   ./configure --with-csl
   make
where all the partially build stuff that had accumulated in cslbuild is
discarded and the configuration and compilation is started afresh. Obviously
you will not delete that directory if you have put important files of your
own there!

A feature of subversion is that if you change any file locally then your local
edit is interpreted as a possibly valuable update that you may at some stage
contribute back into the project. This is good, but it means that if you
accidentally corrupt a local copy of some file then subversion will NOT
automatically repair it. So if you have just recently started with Reduce and
something odd is happening it may make sense to get yourself back in lock-step
with the central repository. You are provided with two scripts
   scripts/make-pristine.sh
   scripts/stamp.sh
The first of those merely issues the subversion commands that discard all local
changes you have made to bring everything into step. The second updates the
time-stamps on various configuration files so that when you run "configure"
it should not attempt to use autoconf and automake locally, but instead should
be content with the files as fetched. These two scripts can avoid confusion
early on. Once you are fully working and especially if you are doing your own
development within Reduce you will not wish to use them.


You can fetch or update REDUCE in one of (at least) two ways

(1) Fetch a file from the Sourceforge download area, eg from the
reduce-algebra-source section. Unpack it. Note that the full archives
at sourceforge are updated sporadically and not to any coherent schedule,
so what you get could be a little out of date.

OR

(2) Use subversion to fetch or refresh a copy from the master site.

svn checkout
  https://reduce-algebra.svn.sourceforge.net/svnroot/reduce-algebra
  reduce-algebra
(all the above three lines really stand for one long line of input)
[Ha this URL is now painfully WRONG and out of date]

    That should create a directory called "reduce-algebra" for you.
    To refresh your files, enter the reduce-algebra directory and go
        svn update
    Note that the main copy of everything will end up in the "trunk"
    sub-directory of what you fetch.

The version fetched and updated using subversion (hah - note that you
need "subversion" installed on your computer to do this!) will be fully
up to date. That naturally means that at some moments it will include
changes that temporarily break it, but in general any suich should be
corrected fairly rapdily. Furthermore by browsing the documentation of
subversion you can find out how to check out a version from say 2 weeks
ago (or indeed any historical varient) if needbe.



The simplest way version of the build process is to select the directory
where REDUCE was unpacked as current and issue one of the command
         ./configure --with-csl
     OR  ./configure --with-psl

Follow that by the command "make" and if all goes well everything relevant
will be compiled. But at least in the CSL case please try
scripts/csl-sanity-check.sh first - it may save you a lot of agony.

For (some sort of) convenience a script "rebuild.sh" in the top level of
the distribution tries to do this for both PSL and CSL and it then leaves
overall log files also at the top level.

You can then run REDUCE using the command
    bin/redcsl
or
    bin/redpsl

[At present I do not in any way guarantee (and I probably do not even expect)
that the usual "configure" option "--prefix=..." or the idiom "make install"
will behave as you might have hoped. Indeed there are reports that at
present "make install" is deeply broken and SHOULD NOT BE ATTEMPTED.]

Any machine you are on is attributed an identity such as i686-pc-windows
or x86_64-unknown-ubuntu10.10. Note that this is slightly more specific than
the normal GNU host triple in that it attempts to include the name of a Linux
distribution. Binaries are actually built within cslbuild/<triple> or
pslbuild/<triple>. This arrangement is intended to be helpful if you have one
file-space shared between several machine that may have different
architectures. So the scripts like bin/redcsl deduce where to look and
chain to binaries there. In the CSL case you could make a symbolic link
as in "ln -s .../trunk/cslbuild/<triple>/csl/reduce XXXX" where XXXX is some
location on your PATH which then lets you launch Reduce more directly. Reduce
needs some resources in the same directory as the bain executable so merely
copying <triple>/csl/reduce to somewhere else is not liable to be a good idea.

Logs from building and testing Reduce end up in the directory where the
main binary gets created, so if things go wromg that is where you may wish
to look.



There are a number of optional ways in which configuration may be customised:
         ./configure --with-csl --enable-debug
   Enable "gcc -g" compilation of the C parts of CSL so that gdb can be
   used to debug things.

         ./configure --with-csl --with-m32
   On an architecture that is basically 64-bit (mostly 64-bit Linux) this
   arranges to compile 32-bit binaries. As in "gcc -m32". Similarly
   "--with-m64" exists. To use this your computer must be set up to be
   able to build both widths of binary. This is sometimes referred to as
   "multilib".
 
         ./configure --with-csl --with-mingw64
   Provided a cross compiler x86_64-win64-mingw32-gcc is available (plus all
   associated tools - and they can be installed via cygwin setup) build
   a 64-bit Windows system.

         ./configure --with-csl --with-cygwin
   Normally the CSL build on a Windows platform builds a normal native Windows
   binary using "mingw32". "--with-cygwin" causes it to build a "cygwin"
   system that expects to use X-windows rather than a native Windows GUI,
   and that links in the cygwin1.dll library which imposes some additional
   license constraints. This is not expected to be very useful and will often
   be broken.

         ./configure --with-psl --with-m32
   As "--with-m32" for CSL, this used 32-bit PSL even if you are in a
   64-bit-capable environment. I think!

   For example, to build both 32-bit and 64-bit PSL on a 64-bit Windows system
   you would run the following commands
         ./configure --with-psl --with-m32
         ./configure --with-psl
         make

   There are other options, many of which are experimental or historical.
   See "./configure --help" for a definitive list. In the CSL world I will
   perhaps note "--with-wx" which relates to a currently incomplete move from
   using FOX to using wxWidgets as the GUI toolkit.



Having built the system [in the CSL world] you can go
         make testall
and that will run the full set of REDUCE test scripts, leaving some output
in the log directory. [With CSL] This also compares the test output with
reference logs held in the main source tree and provides a summary of
differences, and prepares a table comparing the performance of the current
computer the the one used to create the reference logs.




Developers and some more ambitious users may need to understand the
directory layout in more detail.  The main directories supplied are
as follows, where MACHINE stands for a machine identification, eg
i686-pc-windows-debug.

 trunk                    The main version of everything
   bin                    Scripts to launch REDUCE etc
   csl/cslbase            Main CSL Lisp sources
       fox                the FOX GUI toolkit, an LGPL package
   cslbuild/generated-c   Part of REDUCE compiled into C
            MACHINE/csl   where REDUCE binaries are built
                    fox   where the FOX GUI toolkit is built
   csllogs/MACHINE/build  logs from building REDUCE
                   test   logs from testing REDUCE
   packages/alg           REDUCE sources, on package per directory
            ...
            ztrans
   psl/psl-amd64          Ready-build binaries of the PSL Lisp system ...
       ...                ...
       psl/win32          ... for a variety of architectures
   pslbuild/MACHINE/.     where REDUCE gets built
                    psl   copy of relevant architecture-specific PSL
                    red   REDUCE built binary "fasl" and image files
                    deps  used to record dependencies in the build
   psllogs/build          logs from building REDUCE
           test           logs from testing REDUCE
   scripts                scripts used to maintain the system.



If you are working on just one platform and have completed the configuration
and done an initial build you may like to select either cslbuild/MACHINE/csl
or pslbuild/MACHINE as your current directory: the Makefile that ends up there
is the main one used for rebuilding the system.


For special purposes you may wish to investigate the csl/jlisp directory (all
Reduce runnable via Java - distinctly slower and at present the user interface
is not well sorted, but it might be fun) and csl/embedded (a kit for making
a simple small C-coded version for potential use as a component in some other
software rather than a free-standing complete program).


The more alive the Reduce project is the more you can expect there to be
additions, changes and enhancements but please understand that these all
carry risk of transient introduction of bugs. Report trouble to us via
Sourceforge and when and if we can we will fix them. But all the source code
is there so you can also join in the debugging and propse fixes (please!)



A C Norman. July 2008. Updated Jan 2009, September 2010, March 2011

[more updates needed - September 2014]


