source: git/INSTALL @ 8ce4652

                         Singular version <x.y.z>
                     University of Kaiserslautern
     Department of Mathematics   Centre for Computer Algebra
          Authors: G.-M. Greuel, G. Pfister, H. Schoenemann
                  (C) 1986-1998 All Rights Reserved

             UNIX INSTALLATION INSTRUCTIONS FOR SINGULAR
             ============================================


To install Singular on a Unix platform, you need at least the
following two files: 

Singular-<x.y.z>-share.tar.gz 
   -- contains architecture-independent data like documentation or libraries

Singular-<x.y.z>-<uname description>.tar.gz
   -- contains architecture dependent executables, like the Singular program

where <uname description> is a description of the processor and
operating system for which Singular is compiled (e.g, ix86-Linux).
You can obtain these files from
ftp://www.mathematik.uni-kl.de/pub/Math/Singular/.

IMPORTANT
=========
Please see the file COPYING contained in the distribution for license
information on Singular. In particular, notice that we only grant you
permission to use Singular, if you have registered yourself as a
Singular user by sending email to <singular@mathematik.uni-kl.de> 
with the subject line (or, mail body) `register'.

TO INSTALL SINGULAR
===================
Simply cd to the directory in which you wish to install SINGULAR,
and then unpack the architecture independent tar file, followed by
the architecture-dependent files for those architectures you use.

  cd /usr/local/        # or wherever you install 3rd-party software
  gzip -dc Singular-<x.y.z>-share.tar.gz | tar -pxf -
  gzip -dc Singular-<x.y.z>-<uname description>.tar.gz | tar -pxf -

Replace `/usr/local/' with what you like, but it probably ought not
have `Singular' or a version number in it - that directory is expected
to be the common prefix for installed software, and Singular-specific
subdirectories of it will be created.  The directories are arranged
in such a way that multiple versions of Singular can peaceably coexist
under the same `/usr/local/' tree.

After unpacking, you will have a directory structure like:

  ./<uname description>/bin/Singular-<x.y.z>    executable(s)
  ./info/singular.hlp                           info file
  ./Singular/LIB/<x.y.z>/                       Singular libraries
  ./Singular/doc/<x.y.z>/                       documentation (ps, dvi, info)
  ./Singular/html/<x.y.z>/                      documentation (html)


For the executable to work, the directory layout must look pretty much
like this; the executable looks for "sibling" directories at run-time
to figure out where its Singular libraries and on-line info
documentation are.  These constraints on the local directory layout
are necessary to avoid having to hardcode pathnames into the
executables, or require that environment variables be set before
running the executable. In particular, you should not move or copy
the Singular executables to another place, but use soft-links
instead. For example, to install Singular on your system, use
something like:
 ln -s `pwd`./<uname description>/bin/Singular-<x.y.z> /usr/local/bin/Singular
See also the `TROUBLES' section below, if you run into any problems.


TO INSTALL THE ON-LINE DOCUMENTATION
=====================================
Singular needs the `info' program for its on-line documentation. If
you do not have the `info' program installed on your system, you may
obtain it from
ftp://www.mathematik.uni-kl.de/pub/Math/Singular/utils/
by downloading the respective info-<uname description>.tar.gz file.

If you have the `info' program installed on your system, no further
actions are required. Otherwise, to install, simply cd to the
directory where you unpacked the other tar files and then unpack the
info tar file.

  cd /usr/local/      # i.e., wherever you have unpacked Singular tar files
  gzip -dc info-<uname description>.tar.gz | tar -pxf -

This adds
  ./<uname description>/bin/info                info program
to the above directory structure and ensures that the `info' program
is found at run-time.


TROUBLES
=========

* For HPUX systems: 
  The /etc/termcap files which are pre-installed on these systems are
  broken which leads to messages like

   Name collision between 9826 9836

  when Singular is started. To fix this, you can get fixed termcap
  files from 
  ftp://www.mathematik.uni-kl.de/pub/Math/Singular/utils
  by downloading the files termcap-<uname-description> and either
  replace your /etc/termcap file by the file found there, or view, and 
  redo the respective changes by diff'ing the downloaded and the
  original file.

* For Linux systems:
  Due to some incompatibilities of shared libraries, the start-up of
  Singular might fail with messages like 
    
   Can not find shared library ....

  To fix this, download and install
   
   Singular-<x.y.z>-<uname description>-static.tar.gz 
 
  which contains statically linked executables.

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

* General: Singular can not find its libraries or info-file:
  (1) 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).
  (2) Check whether the directories containing the libraries and
      info-file can be found by Singular: If $bindir denotes the
      directory where the Singular executable resides, then Singular
      looks for library files as follows:
      1.) In all dirs specified by the environment variable SINGULARPATH
      2.) $bindir/LIB
      3.) $bindir/LIB/<x.y.z>
      4.) $bindir/../../Singular/LIB
      5.) $bindir/../../Singular/LIB/<x.y.z>
      6.) /usr/local/Singular/LIB/
      7.) /usr/local/Singular/LIB/<x.y.z>
      The info-file, i.e., the file singular.hlp is looked for at the
      following places: 
      1.) $bindir/../doc/
      2.) $bindir/../info/
      3.) $bindir/../../Singular/doc/<x.y.z>/
      4.) $bindir/../../Singular/doc/
      5.) $bindir/../../info/
      6.) /usr/local/Singular/doc/<x.y.z>/
      7.) /usr/local/Singular/doc/
      8.) /usr/local/info/
      9.) In all directories contained in the Singular SearchPath.
  (3) As a last resort, you can set the environment variable
      SINGULARPATH, so that the directories containing the Singular
      libraries and info-files are contained in the value of
      SINGULARPATH. 
  You can inspect the used SearchPath and info-file by starting up
  Singular with the `-v' option, or  by issuing the command
  `system("with")'. Use colons (i.e., `:') for directory separators
  within the SINGULARPATH.

      
* General: Singular can not find the `info' program:
  Install the info program on your system -- see the section 
  "TO INSTALL THE ON-LINE DOCUMENTATION" above.

* For any other troubles, please send mail 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.mathematik.uni-kl.de/~zca/Singular
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.