Unix installation instructions for SINGULAR version 3-1-0
*********************************************************

The possibilities for installing SINGULAR on a Unix or Linux system
range from a purely manual installation over a convenient installation
of RPM or DEB packages up to a completely automated installation via a
package tool like apt or yum.

For a Linux system with RPM (like Redhat/Fedora, Mandrake/Mandriva,
SuSE etc.), or with DEB (like Debian, Ubuntu etc.) one should follow
the intructions at `http://www.singular.uni-kl.de/UNIX/'.

The manual installation (for all other Unix systems) is described below:

To install SINGULAR on a ix86-Win platform, you need the following two
archives:
`a:'
     Singular-3-1-0-share.tar.gz contains architecture independent data
     like documentation and libraries.

`b:'
     Singular-3-1-0-ix86-Win.tar.gz contains architecture dependent
     executables, like the SINGULAR program.

You can obtain these (and other) archives from
     `ftp://www.mathematik.uni-kl.de/pub/Math/Singular/UNIX/'.

*Important:* Please see the file COPYING contained in the distribution
for license information on SINGULAR. Please register yourself as a
SINGULAR user by using the registration form on the SINGULAR homepage
`http://www.singular.uni-kl.de'.  If for some reason you cannot access
the registration form, you can also register by sending an email to
<singular@mathematik.uni-kl.de> with subject line `register' and body
containing the following data: your name, email address, organisation,
country and platform(s).

To install SINGULAR
===================

Make sure that you have approximately 20 MByte of free disk space and
follow these steps.
  1. Simply change to the directory in which you wish to install
     SINGULAR (usually wherever you install 3rd-party software), for
     example:
          cd /usr/local
          or
          mkdir install;cd install
          (you do not need root privileges in this case)

     SINGULAR specific subdirectories will be created in such a way
     that multiple versions and multiple architecture dependent files
     of SINGULAR can peaceably coexist under the same `/usr/local' tree.

  2. Unpack the archives:
          gzip -dc <path_to>/Singular-3-1-0-ix86-Win.tar.gz | tar -pxf -
          gzip -dc <path_to>/Singular-3-1-0-share.tar.gz | tar -pxf -

     This creates the directory Singular/3-1-0 with
     (sub)directories         which contain
     `ix86-Win'               `Singular' and `ESingular' executables
     `LIB'                    SINGULAR libraries (`*.lib' files)
     `emacs'                  files for the SINGULAR Emacs user interface
     `info'                   info files of SINGULAR manual
     `html'                   html files of SINGULAR manual
     `doc'                    miscellaneous documentation files
     `examples'               SINGULAR examples (`*.sing' files)

     For the executable to work, the directory layout must look pretty
     much like this; the executable will look for "sibling" directories
     at run-time to figure out where its SINGULAR libraries and on-line
     documentation files are. These constraints on the local directory
     layout are necessary to avoid having to hard-code pathnames into
     the executables, or require that environment variables be set
     before running the executable. In particular, you *must not move
     or copy* the SINGULAR executables to another place, but use
     soft-links instead.

The following steps are optional:

   * Arrange that typing `Singular' at the shell prompt starts up the
     installed SINGULAR executable.

     If you have root permission, do:
          ln -s `pwd`/Singular/3-1-0/ix86-Win/Singular  /usr/local/bin/Singular-3-1-0
          ln -s `pwd`/Singular/3-1-0/ix86-Win/ESingular  /usr/local/bin/ESingular-3-1-0
          ln -s /usr/local/bin/Singular-3-1-0 /usr/local/bin/Singular
          ln -s /usr/local/bin/ESingular-3-1-0 /usr/local/bin/ESingular

     Otherwise, append the directory ``pwd`/Singular/3-1-0/ix86-Win/'
     to your `$PATH' environment variable. For the `csh' (or, `tcsh')
     shell do:
          set path=(`pwd`/Singular/3-1-0/ix86-Win $path)
     For the `bash' (or, `ksh') shell do:
          export PATH=`pwd`/Singular/3-1-0/ix86-Win/:$PATH

     You also might want to adjust your personal start-up files
     (`~/.cshrc' for `csh', `~/.tcshrc' for `tcsh', or `~/.profile' for
     `bash') accordingly, so that the `$PATH' variable is set
     automatically each time you login.

     *IMPORTANT:* Do _never_ move or copy the file
     `Singular/3-1-0/ix86-Win/Singular' to another place, but use
     soft-links instead.

   * If you wish to use any of the following features of SINGULAR, make
     sure that the respective programs are installed on your system:

     *Feature*                          *Requires*
     running `ESingular', or            Emacs version 20 or higher, or,
     `Singular' within Emacs            XEmacs version 20.3 or higher
                                        (ESingular is only included in
                                        the Linux distribution.  On other
                                        Unix platforms you can download
                                        the SINGULAR emacs lisp files but
                                        we give no warranties for
                                        specific platforms).
     on-line `html' help                any web browser
     on-line `info' help                info, or tkinfo texinfo browser
                                        programs
     TAB completion and history         shared readline library, i.e.
     mechanism of ASCII-terminal        `/usr/lib/libreadline.so'
     interface                          
     visualization of curves and        surfer Setup executable for the
     surfaces                           visualization tool surfer.

     You may download most of these programs from
          `ftp://www.mathematik.uni-kl.de/pub/Math/Singular/utils/'.

   * Customize the on-line help system:

     By default, on-line help is displayed in `html' format using the
     `netscape' program.

     However, this behavior can be customized in several ways using the
     SINGULAR commands `system("--browser",<browser>)' and
     `system("--allow-net", 1)' (or, by starting up SINGULAR with the
     respective command line options).

     In particular, creating the file `Singular/3-1-0/LIB/.singularrc'
     and putting the SINGULAR command
          system("--allow-net", 1);
     in it, allows the on-line help system to fetch its `html' pages
     from Singular's WWW home site (http://www.singular.uni-kl.de) in
     case its local html pages are not found. That is, you may delete
     your local html pages, after setting this option.

     See also the sections _The online help system_, _Command line
     options_, and _Startup sequence_ in the SINGULAR manual for more
     details on customizing the on-line help system.

   * Add the line
          * Singular:(singular.hlp).     A system for polynomial computations
     to your system-wide `dir' file (usually `/usr/info/dir' or
     `/usr/local/info/dir' and  copy or soft-link the file
     `Singular/3-1-0/info/singular.hlp' to the directory of your `dir'
     file.
     This assures that the SINGULAR manual can be  accessed from
     stand-alone texinfo browser programs such as `info' or `Emacs'.
     (This is not a prerequisite for using the help system from within
     `Singular'.)

Troubleshooting
===============

   * General: SINGULAR cannot find its libraries or on-line help
       1. Make sure that you have read and/or execute permission the
          files and directories of the SINGULAR distribution. If in
          doubt, `cd' to the directory where you unpacked SINGULAR, and
          do (as root, if necessary):
               chmod -R a+rX Singular

       2. Start up SINGULAR, and issue the command
          `system("Singular");'.  If this does not return the correct
          and expanded location of the SINGULAR executable, then you
          found a bug in SINGULAR, which we ask you to report (see
          below).

       3. Check whether the directories containing the libraries and
          on-line help files can be found by SINGULAR: If `$bindir'
          denotes the directory where the SINGULAR executable resides,
          then SINGULAR looks for library files as follows:
          (0) the current directory
          (1) all dirs of the environment variable SINGULARPATH
          (2) `$bindir/LIB'
          (3) `$bindir/../LIB'
          (4) `/usr/local/Singular/3-1-0/LIB'
          (4) `/usr/local/Singular/LIB'
          The on-line `info' files need to be at  `$bindir/../info' and
          the `html' pages at `$bindir/../html'.

     You can inspect the found library and `info'/`html' directories by
     starting up SINGULAR with the `--version' option, or by issuing
     the SINGULAR command `system("--version");'.

   * Under previous SuSE-Linux releases, ESINGULAR did not display a
     prompt: This is due to the very restrictive access rights of
     `/dev/pty*' of the standard SuSE (http://www.suse.de) distribution
     (starting from version 6.3 on). The problem may still be present
     when working with the latest SuSE-Linux release.  As root, do one
     of the following: Either
          chmod 666 /dev/pty*
     or,
          chmod g+s $(which emacs)
          chgrp tty $(which emacs)
          chmod g+s $(which xemacs)
          chgrp tty $(which xemacs)

   * For `ix86-Linux' systems:
     Due to some incompatibilities of shared libraries, the start-up of
     SINGULAR might fail with messages like
            Can not find shared library ...
     For DEBIAN systems, try to do `ln -s /usr/lib/libncurses.so
     /usr/lib/libncurses.so.4'.
     If this fails (and on other systems) download and install
     `Singular-3-1-0-ix86-Linux-static.tar.gz'.

   * For `AIX' systems:
     The default `info' program of the system is not GNU's texinfo
     browser which is used to display the on-line documentation in the
     `info' format. Therefore, the distribution of the AIX executable
     already contains the `info' browser program.  If you remove this
     program, make sure that the GNU `info' program is executed if you
     call '`info'' from your shell.

   * For any other troubles:
     Please send an email to <singular@mathematik.uni-kl.de> and
     include the header which is displayed by starting up SINGULAR with
     the `-v' option, and a description of your machine (issue the
     command `uname -a' on your shell) in your report.

More information about SINGULAR: Comments, Questions, Bug Reports
=================================================================

More and up-to-date information about SINGULAR is always available from
     `http://www.singular.uni-kl.de'.
We very much welcome any comments, questions, and bug reports. Please
contact us at
     <singular@mathematik.uni-kl.de>.

GOOD LUCK and ENJOY!  Your SINGULAR team.

