REDUCE - Open Source release


                      July 2013, then February 2014

Tiny updates to this file just to try to keep the credits to other
projects that are used up to date. As of Feb 2014 the revision number
at Sourceforge is 2337, and this seems to correspond to an average
activity rate of a bit over 3 checkins per day.

                             December 2010

This project just reached revision 1000 in the Sourceforge subversion
repository. This feels like something of a landmark.


                              March 2009


This is the REDUCE algebra system, which was originally developed by
Tony Hearn. A bibliography somewhere in this tree reports some of the
large numbers of papers that have been written about or relying on
REDUCE.


                                     Arthur Norman.  March 2009


The BULK of the files in this tree are subject to the (modified) BSD license,
as shown below. There are some components that are subject to more restrictive
terms (notably the FOX GUI Toolkit, used in one version of the code here, is
under LGPL).

===========================================================================

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the relevant copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNERS OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.


===========================================================================

The CSL version of Reduce has started to migrate to use the wxWidgets
library rather than FOX (see below). wxWidgets is under its own license
which is LGPL 2 (or later) plus some permissive exceptions for the
distribution of applications linked against the library. A full
archive is wxWidgets source is included and that contains full details.



Note that the directory csl/fox contains a modified version of the
FOX toolkit (www.fox-toolkit.com) version 1.6 which is subject to
LGPL 2.1. Note explicitly that while an unmodified version of FOX can be
linked into an application and the resulting version may be distributed
without hindrance even the smallest change that has not been accepted by
the FOX central site can only be used under the terms of the LGPL.

Within the FOX directory the "utils" subdirectory contains a program
reswrap.cpp that is used while building FOX. I do not see any cause for
anybody to even want to distribute a binary of that, but to satisfy the
GPL better I have put a copy of the GPL in the directory with it. No part of
reswrap itself ends up in the main programs built here, and its status is
thus rather like that of gcc and other tools.

The FOX test programs were originally held within the FOX directory, but
they are subject to the GPL not the LGPL or any more benign license. I have
moved them to a separate directory to make it unambiguous that there are at
most here as mere aggregation, and the standard build sequences here make
even the presence of that directory optional. I do not intend to provide or
distribute binary copies of any of them ever, and so there should not be any
complications at all on that front.


The "gnuplot" package is used with REDUCE and its license indicates that
it may be redistributed freely, but that modified versions may only be
circulated in the form of patch files against the official release. The
version included here is an original un-modified copy. Well actually right now
there is no version included with Reduce. This is because Sourceforge policy
is that if we include any binary then we must also put the corresponding
source into the Sourceforge Release system. Putting a copy of a snapshot
of the gnuplot source there seems both clumsy and asks for confusion as and
when gnuplot gets updated, so this area is under review!

The CSL source directory contains material derived from Adobe font metrics,
and these metrics it works can be found on many sites - they can be
downloaded directly from Adobe's ftp site but also they are included
with many existing software packages in forms that clearly state that
they are available for redistribution and that the authors of those
packages have checked license conditions carefully. The set of files
I use here came with "teTeX 2" where these terms are carefully set
out and where the package is very well established and widely used so
there would have been plenty of opportunity for concerns about rights
to be aired. I have not altered the metric files at all.

There is a copy of the "distorm" x86 disassembler, which originated from
Gil Dabah and licensed under the modified BSD license. See
http://ragestorm.net/distorm.

I use adjusted versions of Computer Modern Fonts derived from the Blue Sky
Research and Y&Y inc versions but which are now freely available for general
use. Their copyright is held by the American Mathematical Society, and the
versions here should yield exactly the same font metrics as the original
versions.

The Truetype-format fonts are from the BaKoMa Computer Modern Font collection
as distributed via "ctan", and the associated permissive license is included
in the directory where they are held. This set of files and its associated
.tfm metrics are gradually replacing my use of other font data.

An implementation of the MD5 message digest is due to Eric Young and
comes from an implementation of SSL, and is subject to what is in essence the
modified BSD license. The original and full version of the license terms
is included where that code is incorporated.

Various other parts within CSL were contributed by NAG Ltd and by various
students and others, including J O'Connell, M O Seymour, but were made
available to me and to Codemist for inclusion within CSL.

The files in the "psl" directory come from ZIB and are some of the ones
that they used with the Reduce Development System. As shown there these are
also under a BSD license - see the HP_disclaimer.txt that confirms a release
from one of the earlier major copyright holders.

crlibm is a "correctly rounded maths library" subject to LGPL 2.1. It was
fetched from http://lipforge.ens-lyon.fr/www/crlibm/ but needed (minor)
aljustment to let it build here.

The Latin Modern Fonts and Latin Moder Math Fonts are from
http://www.gust.org.pl/projects/e-foundry and copies of the original
archives containing them are in csl/support-packages along with unpacked
a copy of the GUST-FONT-LICENSE.txt file and relevant README files.
There are two uses of derived works, and the GUST License (which is
an instance of the Latex Project Public License) requires that an
explanation of what is covered and what changes are made is placed in
a prominent place (eg here!).
In csl/cslbase/wxfonts there are re-packed font files. Merely placing the
files in a tree that is distinct from the .zip file that formed the
original distribution makes this a derived (and changed) work. But I
have also needed to (use fontforge to) convert each .oft file so I also
have a .ttf version since my Windows code appeared not to render glyphs
from the .otf versions. This should not alter character shapes or metrics
but may degrade rendering. I have also extracted from these fonts a
series of bitmaps that record which characters are present in the fonts.
This is done because I was not instantly able to do this at the point of
rendering, and because it then helps me use font substitution for any
missing characters. In use these fonts will be set up as application-
specific private fonts rather than as globally and permenantly installed
ones, so the chances of causing confusion for other software ought to
be low. The font directories that are to be distributed as part of
a binary release of the software contain READE files etc alongside the
actual fonts, and executable software will respond to a "--help" option
by displaying a message that contains a brief citation of the fonts and
how to recover original official versions.
I believe that since I have not changed font shapes, metrics or coverage
and since the distribution is not set up to make the fonts available
generally - just to have them used as application-private resources - that
renamking the fonts (to avoid confusion) is not necessary here.
But it is important to record that the fonts and derived information are
NOT subject to the full permissions of the BSD License and that any
use that envisages moving them away from the code here or altering the
messages about them that "--help" displays needs to be done only after
careful review of the actual licenses.




                                           A C Norman (acn1@cam.ac.uk)

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

                               January 2015
                                 June 2020



The notes here are about having a full set of Reduce sources fetched from
Sourceforge and compiling them on your own computer. Following that path
lets you track the most recent changes, updates and corrections. Because
both Reduce and the platforms that people may wish to build on change over
time what is explained here will almost always have a few details where it
is out of date: so check the date to see how recently this has been refreshed.
But almost always the changes needed to what is explained here will be small,
and if you find some please report back to the Reduce mailing list for the
benefit of others.

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

Users of PSL will use the ready-build binaries of the PSL Lisp system that
are present in the material hosted at Sourceforge. Rebuilding PSL from source
is possible but the procedures are not covered at all here and anybody needing
to do that probably needs to consult the PSL experts. Because PSL uses
pre-made binaries these have to be present for the architecture you are using.
They are available for all the most important or common cases. Because the
binaries are pre-made there are few demands for compilers or special
libraries installed on the computer you will use PSL on.

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. To join in development work on what is hoped to be a future
version of CSL-Reduce you would also need to be able to work with wxWidgets.

You will need:
   For Windows, the "cygwin" environment providing a "bash" shell.
       Note that building under "msys" or the plain Windows command
       prompt is not possible (without you doing significant work of your
       own to arrange for it). 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! These days you MUST use
       the 64-bit version of cygwin - note that the obsolete 32-bit one is
       deprecated by its suppliers.
       The command scripts/cygwin-sanity-check.sh attempts to check if
       sufficient cygwin components have been installed, and it may save
       you pain if you try it and respond to its suggestions before trying
       a full build of Reduce.
   For Macintosh you need the XCode command line tools, and you are liable
       to need to use Macports to fetch and install a significant number
       of commands and libraries that Apple do not provide as standard.
       There is a file in the scripts directory that I use to fetch the
       set of "ports" that I use. You will also need Xquartz to support the
       GUI.
   For Linux you can inspect scripts/ubuntu-sanity-check.sh or the fedora
       equivalent to find a script that installs what is probably a superset
       of the packages you will need.
   For other platforms there is a hope that everything will work if you
       can provide a bash shell and enough development libraries, but you
       mat need to sort out details for yourself. Here are a few more comments:
   GNU make (other versions of "make" are not liable to work), autoconf,
       automake and libtool. All should be at least tolerably up to date
       versions.
   You need a C++ development context. On Windows you need the
       and "mingw-x86_64" compiler variants (as well as plain g++) from
       cygwin while on other systems you need X11 and other
       development capability, including Xft, fontconfig, (n)curses, Posix
       threads. The building has been tested using versions of both gcc
       and clang. The compiler should be new enough that it supports C++11
       and for choice C++17.

I have (recently) built using cygwin64, Ubuntu and Fedora Linuxes
on pcs, Raspbian (raspberry Pi OS, both 32 and 64-bit variants) on a
Raspberry Pi and OSX Catalina. In the past I have built using PCBSD/FreeBSD
and Solaris on both pc and sparc (requiring significant
extra software installation), SGI, HP-pa, the IBM z-architecture and at one
stage (not now I think) I coudd run Reduce on an HP IPAQ 4700 PDA or an
openWRT router. The hope is that almost any machine with a C++ compiler
should suffice for the basic system. In case of a challenging environment
it may be prudent to do initial testing by running
"./configure --with-csl --without-gui" to avoid all attempts to build
windowing libraries. Also in recent years I have started to suppose that all
computers have substantial amounts of memory, so ones with only a few megabytes
(or even only tend or hundreds) may cause problems.

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. 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! If the failure
is detected at configuer time the evidence will be in a file "config.log"
(possibly somewhere within the cslbuild directory). In case of trouble I often
go
    script buildlog.log
    rm -rf cslbuild
    ./configure --with-csl
    make
    exit
and then buildlog.log contains a full transcript of all the output from the
attempt. Its size can be daunting and distinguishing between messages,
warnings, observations and errors can take experience!

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 risk 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 you are
looking at "apt-get" and "yum" and various other package managers. You need
to check the documentation of your particular operating system - or perhaps
better find 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. Thus this scheme is not
recommended!

OR

(2) Use subversion to fetch or refresh a copy from the master site.
        svn checkout \
           svn://svn.code.sf.net/p/reduce-algebra/code/trunk \
           reduce-algebra
    That should create a directory called "reduce-algebra" for you.
    To refresh your files, enter the reduce-algebra directory and go
        svn update
    You can check the documentation of subversion (svn) to discover
    what further options and possibilities tare provided. Two notable
    advanntages of this are (a) "svn update" lets you refresh your copy
    to match the very latest one available without needing to fetch
    everything again afresh and (n) "svn -r NNNN update" lets you update
    you local copy to match "revision NNNN", a possibly older copy of
    everything, so if the main development version is even temporarily
    broken (that should only happen accidentally!) you can fetch older
    versions for comparison.

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 such 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
(or first one of those then the other)

It ought not to be necessary to provide any other options to the configure
script or to pre-set environment variables, but for experts there are (of
course) many opportunities for customisation. If you find you are on a platform
where simple use of the configure script is insufficient please report that
so that things can be updated and users in the future will come closer to
find that everything works first time without fuss.

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.

If you build both the CSL and PSL versions then it can be a comfort to
run
    scripts/testall.sh
which runs all the various test scripts and displays a report showing any
places where the output on your machine does not match reference versions
of the logs. Directories called csl-times and psl-times end up with the
log output. In some cases log discrepancies are expected! For instance some
of the test files generate timing reports so their output varies depending on
the speed or size of your computer. In other cases improvements to the
system may change test output but the reference logs may not have been
updated to reflect it. Some logs are there to highlight difference between
detailed behaviour of CSL and PSL that are not hugely important but that
may be addressed at some stage in the future.

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.
But there is scripts/mk-snapshots.sh which is used to build the distribution
snapshots and those can then be installed.]

Any machine you are on is attributed an identity such as x86_64-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 main 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 wrong 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 --without-gui
         ./configure --with-csl --with-wx
   By default the CSL version build in support for a GUI using the FOX
   toolkit. If for some reason that is not required or can not be supported
   then "--without-gui" removes it. There are some plans to change to use
   wxWidgets rather than FOX, and "--with-wx" enables the experimental build
   for that. At the time of writing the code compiles but is significantly
   unfinished. Volunteers to help complete it would be useful! But neither of
   these options are a very good idea for ordinary users!

   There are other options, many of which are experimental or historical.
   See "./configure --help" for a definitive list.


Developers and some more ambitious users may need to understand the
directory layout in more detail. The document "Inside Reduce" the
the "primers" part of the Reduce documentation directory may provide
useful guidance.
The main directories supplied are as follows, where MACHINE stands for
a machine identification, eg x86_64-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
   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
   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/new-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). Both of
these are for experienced programmers who want to use them in some broader
project rather than being fully supported variants on Reduce itself.

There are also "spins" of Reduce by way of extra files and scripts that have
made it possible to build the system on other Lisps, from Common Lisp as
far as emacs lisp. There are a range of alternative interfaces for both
console and GUI purposes in varying states of support and maturity.


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 propose fixes (please!)



A C Norman. July 2008. Updated Jan 2009, September 2010, March 2011,
            September 2014, January 2015, June 2020.