@comment -*-texinfo-*- @comment $Id$ @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 /Singular-@value{VERSION}-@value{_UNAME}.tar.gz | tar -pxf - gzip -dc /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",)} 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- 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