source: git/INSTALL.unix @ 64d729

                         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-1999 All Rights Reserved

             UNIX INSTALLATION INSTRUCTIONS FOR SINGULAR
             ============================================
To install Singular on a Unix platform, you need the following two
archives: 

Singular-<x-y-z>-share.tar.gz (or, Singular-<x-y-z>-share.zip)
   -- contains architecture independent data like documentation and libraries
Singular-<x-y-z>-<uname>.tar.gz
   -- contains architecture dependent executables, like the Singular program

where <uname> is a description of the processor and operating system
for which Singular is compiled (e.g, ix86-Linux). Please contact us if
you can not find an appropriate architecture-dependent archive.

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
===================
(0) You need appr. 10MByte of free disk space to unpack the archives.

(1) Simply change to the directory in which you wish to install
    Singular (usually wherever you install 3rd-party software):

      cd /usr/local/    

    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 architecture dependent files: 

      gzip -dc Singular-<x-y-z>-<uname>.tar.gz | tar -pxf -

(3) Unpack the architecture independent files: 
    If you downloaded  Singular-<x-y-z>-share.tar.gz do:
  
      gzip -dc Singular-<x-y-z>-share.tar.gz | tar -pxf -

    Alternatively, if you  downloaded Singular-<x-y-z>-share.zip do:
  
      unzip -u Singular-<x-y-z>-share.zip 

(4) [Optionally:] Arrange that typing 'Singular' at the shell prompt
    starts up the installed Singular executable.

    If you have root permission, do:
      
      ln -s `pwd`/Singular/<uname>/<x-y-z>/Singular /usr/local/bin/Singular 
        
    Otherwise, append the dir `pwd`/Singular/<uname>/<x-y-z> to your $PATH
    environment variable. For the csh (or, tcsh) shell do:

      set path=(`pwd`/Singular/<uname>/<x-y-z> $path)
 
    For the bash (or, ksh) shell do:
  
      export PATH=`pwd`/Singular/<uname>/<x-y-z>:$PATH

    You also might want to adjust your personal start-up files accordingly, 
    so that the PATH variable is set automatically each time you login.

    IMPORTANT: Do NEVER move or copy the file
    `./Singular/<uname>/<x-y-z>/Singular'  to another place, but use
    soft-links instead. 


After unpacking, you will have a directory structure like:
  ./Singular/<uname>/<x-y-z>/        executable(s)
  ./Singular/LIB/<x-y-z>/            Singular libraries
  ./Singular/LIB/gftables/           Singular lookup tables
  ./Singular/doc/<x-y-z>/            documentation (ps, dvi, info)
  ./Singular/html/<x-y-z>/           documentation (html)
  ./Singular/README                  general information on Singular
  ./Singular/COPYING                 licence information
  ./Singular/INSTALL                 this file

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. 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>.tar.gz file.

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>.tar.gz | tar -pxf -

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

You also might want to add a Singular menu entry to the global info
file of your system, such that the Singular on-line help can be
accessed from the stand-alone `info' program or from the Emacs editor: 
(1) Add the line 

* Singular:(singular.hlp).     A system for polynomial computations

to your system `dir' file (usually `/usr/info/dir' or `/usr/local/info/dir') 

(2) Copy or soft-link the file ./Singular/doc/<x-y-z>/singular.hlp
    to the directory of your `dir' file.


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, first delete the file
        ./Singular/<uname>/<x-y-z>/Singular

  and then download and install

   Singular-<x-y-z>-<uname>-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.) 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.) All dirs where it looks for libraries.
  (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.