source: git/doc/INSTALL_unix.texi @ 6ce030f

@comment -*-texinfo-*-
@c FILE: INSTALL_unix.texi
@c PURPOSE: Installation instruction for Singular on Unix
@c

@c @ifclear VERSION
@include version.texi
@c @end ifclear

@ifclear singularmanual
@majorheading Unix installation instructions for @sc{Singular} version @value{VERSION}
@end ifclear

@ifclear UNAME
@set _UNAME uname
@end ifclear

@ifset UNAME
@include uname.texi
@end ifset

The possibilities for installing @sc{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 @url{http://www.singular.uni-kl.de/UNIX/}.

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

To install @sc{Singular} on a
@ifset UNAME
@value{_UNAME}
@end ifset
@ifclear UNAME
Unix
@end ifclear
platform, you need the following two
archives:
@table @code
@item a:
Singular-@value{VERSION}-share.tar.gz
contains architecture independent data like documentation and libraries.
@item b:
Singular-@value{VERSION}-@value{_UNAME}.tar.gz
contains architecture dependent executables, like the @sc{Singular}
program.
@end table
@ifclear UNAME
@*
@code{@value{_UNAME}} is a description of the processor and operating system
for which @sc{Singular} is compiled (e.g, @code{ix86-Linux}). Please contact us if
you cannot find an appropriate architecture dependent archive.
@end ifclear

You can obtain these (and other) archives from
@display
@uref{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/UNIX/}.
@end display

@include register.texi

@heading To install SINGULAR

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

@sc{Singular} specific subdirectories will be created in such a way
that multiple versions and multiple architecture dependent files
of @sc{Singular} can peaceably coexist under the same @code{/usr/local}
tree.

@item
Unpack the archives:
@smallexample
gzip -dc <path_to>/Singular-@value{VERSION}-@value{_UNAME}.tar.gz | tar -pxf -
gzip -dc <path_to>/Singular-@value{VERSION}-share.tar.gz | tar -pxf -
@end smallexample

This creates the directory Singular/@value{VERSION} with
@multitable @columnfractions .36 .64
@item (sub)directories
@tab  which contain
@item @code{@value{_UNAME}}
@tab @code{Singular} and @code{ESingular} executables
@item @code{LIB}
@tab @sc{Singular} libraries (@code{*.lib} files)
@item @code{emacs}
@tab files for the @sc{Singular} Emacs user interface
@item @code{info}
@tab info files of @sc{Singular} manual
@item @code{html}
@tab html files of @sc{Singular} manual
@item @code{doc}
@tab miscellaneous documentation files
@item @code{examples}
@tab @sc{Singular} examples (@code{*.sing} files)
@end multitable

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 @sc{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 @strong{must not move or copy}
the @sc{Singular} executables to another place, but use soft-links
instead.
@end enumerate

The following steps are optional:

@itemize @bullet
@item
Arrange that typing @code{Singular} at the shell prompt starts up the
installed @sc{Singular} executable.

If you have root permission, do:
@smallexample
ln -s `pwd`/Singular/@value{VERSION}/@value{_UNAME}/Singular  /usr/local/bin/Singular-@value{VERSION}
ln -s `pwd`/Singular/@value{VERSION}/@value{_UNAME}/ESingular  /usr/local/bin/ESingular-@value{VERSION}
ln -s /usr/local/bin/Singular-@value{VERSION} /usr/local/bin/Singular
ln -s /usr/local/bin/ESingular-@value{VERSION} /usr/local/bin/ESingular
@end smallexample
        
Otherwise, append the directory
@code{`pwd`/Singular/@value{VERSION}/@value{_UNAME}/} to your @code{$PATH}
environment variable. For the @code{csh} (or, @code{tcsh}) shell do:
@smallexample
set path=(`pwd`/Singular/@value{VERSION}/@value{_UNAME} $path)
@end smallexample
For the @code{bash} (or, @code{ksh}) shell do:
@smallexample
export PATH=`pwd`/Singular/@value{VERSION}/@value{_UNAME}/:$PATH
@end smallexample

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

@strong{IMPORTANT:} Do @emph{never} move or copy the file
@code{Singular/@value{VERSION}/@value{_UNAME}/Singular} to another
place, but use soft-links instead.

@item
If you wish to use any of the following features of
@sc{Singular}, make sure that the respective programs are installed on your system:

@multitable @columnfractions .5 .5
@item @strong{Feature} @tab @strong{Requires}
@item running @code{ESingular}, or @code{Singular} within Emacs
@tab @uref{http://www.gnu.org/software/emacs/emacs.html,,Emacs} version
20 or higher, or, @uref{http://www.xemacs.org,,XEmacs} version 20.3 or
higher (ESingular is only included in the Linux distribution.
On other Unix platforms you can download the
@uref{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/src/,,
@sc{Singular} emacs lisp files} but we give no warranties for specific platforms).
@item on-line @code{html} help
@tab any web browser
@item on-line @code{info} help
@tab @uref{http://www.texinfo.org,,info}, or
@uref{http://math-www.uni-paderborn.de/~axel/tkinfo/,,tkinfo} texinfo browser programs
@item TAB completion and history mechanism of ASCII-terminal interface
@tab shared @uref{ftp://ftp.de.uu.net/pub/gnu/readline/,,readline}
library, i.e. @code{/usr/lib/libreadline.so}
@item visualization of curves and surfaces
@tab
@uref{http://www.imaginary2008.de/surfer.php,,surfer}
Setup executable for the visualization tool surfer.
@end multitable

You may download most of these programs from
@display
@uref{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/utils/}.
@end display

@item Customize the on-line help system:

By default, on-line help is displayed in @code{html} format using
the @code{netscape} program.

However, this behavior can be customized in several ways
using the @sc{Singular} commands @code{system("--browser",<browser>)}
and @code{system("--allow-net", 1)} (or, by starting up @sc{Singular}
with the respective command line options).

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

See also
@ifset singularmanual
@ref{The online help system}, @ref{Command line options}, and
@ref{Startup sequence},
@end ifset
@ifclear singularmanual
the sections @emph{The online help system}, @emph{Command line options}, and
@emph{Startup sequence} in the @sc{Singular} manual
@end ifclear
for more details on customizing the on-line help system.

@item
Add the line
@smallexample
* Singular:(singular.hlp).     A system for polynomial computations
@end smallexample
to your system-wide @code{dir} file (usually @code{/usr/info/dir} or
@code{/usr/local/info/dir} and  copy or soft-link the file
@code{Singular/@value{VERSION}/info/singular.hlp}
to the directory of your @code{dir} file.
@*This assures that the
@sc{Singular} manual can be  accessed from stand-alone texinfo
browser programs such as @code{info} or @code{Emacs}.
(This is not a prerequisite for using the help system from within @code{Singular}.)
@end itemize

@heading Troubleshooting

@itemize @bullet
@item General: @sc{Singular} cannot find its libraries or on-line help
@enumerate
@item
Make sure that you have read and/or execute permission the files and
directories of the @sc{Singular} distribution. If in doubt, @code{cd} to the
directory where you unpacked @sc{Singular}, and do (as root, if
necessary):
@smallexample
chmod -R a+rX Singular
@end smallexample

@item
Start up @sc{Singular}, and issue the command @code{system("Singular");}.
If this does not return the correct and expanded location of the
@sc{Singular} executable, then you found a bug in @sc{Singular}, which we
ask you to report (see below).
@item
Check whether the directories containing the libraries and on-line help
files can be found by @sc{Singular}: If @code{$bindir} denotes the
directory where the @sc{Singular} executable resides, then @sc{Singular}
looks for library files as follows:
@* (0) the current directory
@* (1) all dirs of the environment variable SINGULARPATH
@* (2) @code{$bindir/LIB}
@* (3) @code{$bindir/../LIB}
@* (4) @code{/usr/local/Singular/@value{VERSION}/LIB}
@* (4) @code{/usr/local/Singular/LIB}
@* The on-line @code{info} files need to be at  @code{$bindir/../info} and the
@code{html} pages at @code{$bindir/../html}.
@end enumerate

You can inspect the found library and @code{info}/@code{html}
directories by starting up @sc{Singular} with the
@code{--version} option, or by issuing the @sc{Singular} command
@code{system("--version");}.

@item Under previous SuSE-Linux releases, @sc{ESingular} did not display a prompt:
@cindex SuSE, ESingular bug
@cindex ESingular, no prompt
@cindex bug, ESingular
This is due to the very restrictive access rights of @code{/dev/pty*} of
the standard @uref{http://www.suse.de,SuSE} 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
@example
chmod 666 /dev/pty*
@end example
or,
@example
chmod g+s $(which emacs)
chgrp tty $(which emacs)
chmod g+s $(which xemacs)
chgrp tty $(which xemacs)
@end example

@c @item For @code{HPUX} systems:
@c @*The /etc/termcap files which are pre-installed on these systems are
@c broken which leads to messages like
@c @example
@c Name collision between 9826 9836
@c @end example
@c when @sc{Singular} is started. To fix this, you can get fixed termcap
@c files from @uref{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/utils}
@c by downloading the files termcap-<uname-description> and either
@c replace your /etc/termcap file by the file found there, or view, and
@c redo the respective changes by @code{diff}'ing the downloaded and the
@c original file.

@item For @code{ix86-Linux} systems:
@*Due to some incompatibilities of shared libraries, the start-up of
@sc{Singular} might fail with messages like
@example
  Can not find shared library ...
@end example
For DEBIAN systems, try to do
@code{ln -s /usr/lib/libncurses.so /usr/lib/libncurses.so.4}.
@*If this fails (and on other systems)
download and install
@code{Singular-@value{VERSION}-ix86-Linux-static.tar.gz}.

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

@item For any other troubles:
@*Please send an email to @email{singular@@mathematik.uni-kl.de}
and include the header which is displayed by starting up @sc{Singular}
with the @code{-v} option, and a description of your machine (issue the
command @code{uname -a} on your shell) in your report.
@end itemize

@include info.texi

@ifclear singularmanual
GOOD LUCK and ENJOY!
Your @sc{Singular} team.
@end ifclear