     [file version.texi not included]

MacOS X installation instructions for SINGULAR version VERSION
**************************************************************

To install SINGULAR on MacOS X , you need the following two archives:

Singular-VERSION-share.tar.gz
     contains architecture independent data like documentation and libraries (alternatively, you may also download Singular-VERSION-share.zip).

Singular-VERSION-<uname>.tar.gz
     contains architecture dependent executables, like the SINGULAR program.

<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 (and other) archives from

     ftp://www.mathematik.uni-kl.de/pub/Math/Singular.

     [file register.texi not included]

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

Make sure that you have approximately 12MByte 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-VERSION-<uname>.tar.gz | tar -pxf -
          gzip -dc <path_to>/Singular-VERSION-share.tar.gz | tar -pxf -

     This creates the the directory Singular/VERSION with

     (sub)directories
     which contain
     <uname>
     Singular executetable
     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 looks 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/VERSION/<uname>/Singular  /usr/local/bin/Singular-VERSION
          ln -s /usr/local/bin/Singular-VERSION /usr/local/bin/Singular

     Otherwise, append the directory `pwd`/Singular/VERSION/<uname>/ to your $PATH environment variable. For the csh (or, tcsh) shell do:

          set path=(`pwd`/Singular/VERSION/<uname> $path)

     For the bash (or, ksh) shell do:

          export PATH=`pwd`/Singular/VERSION/<uname>/:$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/VERSION/<uname>/Singular to another place, but use soft-links instead.

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

     Feature   Requires

     on-line html help
     netscape browser
     on-line info help
     info, or
     tkinfo texinfo browser programs
     TAB completion and history mechanism of ASCII-terminal interface
     shared readline
     library, i.e. /usr/lib/libreadline.so

     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 the 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/VERSION/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/VERSION/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. (It is not necessary for the use of the help system from within Singular.)

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

  * General: SINGULAR can not 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/VERSION/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");.

  * 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.

     [file info.texi not included]

GOOD LUCK and ENJOY! Your SINGULAR team.