source: git/doc/INSTALL_unix.texi @ 26644b1

Last change on this file since 26644b1 was 26644b1, checked in by Hans Schoenemann <hannes@…>, 11 years ago
chg: help system, lib2doc updated add: primepower as a comment from master
  • Property mode set to 100644
File size: 11.9 KB
[a89a22c]1@comment -*-texinfo-*-
[a94090]2@c FILE: INSTALL_unix.texi
[6d0847]3@c PURPOSE: Installation instruction for Singular on Unix
[e84c97]6@c @ifclear VERSION
[a89a22c]7@include version.texi
[e84c97]8@c @end ifclear
10@ifclear singularmanual
[119757]11@majorheading Unix installation instructions for @sc{Singular} version @value{VERSION}
[a89a22c]12@end ifclear
14@ifclear UNAME
[148c86e]15@set _UNAME uname
[a89a22c]16@end ifclear
18@ifset UNAME
[354f3b]19@include uname.texi
[a89a22c]20@end ifset
[437efdf]22The possibilities for installing @sc{Singular} on a Unix or Linux system range from
[ab5406e]23a purely manual installation over a convenient installation of RPM or DEB
24packages up to a completely automated installation via a package tool like
25apt or yum.
27For a Linux system with RPM (like Redhat/Fedora, Mandrake/Mandriva, SuSE etc.),
28or with DEB (like Debian, Ubuntu etc.) one should follow
29the intructions at @url{}.
[148c86e]31The manual installation (for all other Unix systems) is described below:
[3de58c]33To install @sc{Singular} on a
[a89a22c]34@ifset UNAME
36@end ifset
37@ifclear UNAME
39@end ifclear
40platform, you need the following two
[a89a22c]42@table @code
[fcba80d]43@item a:
[e84c97]45contains architecture independent data like documentation and libraries.
[fcba80d]46@item b:
[a89a22c]48contains architecture dependent executables, like the @sc{Singular}
[3de58c]50@end table
[a89a22c]51@ifclear UNAME
[354f3b]53@code{@value{_UNAME}} is a description of the processor and operating system
[a89a22c]54for which @sc{Singular} is compiled (e.g, @code{ix86-Linux}). Please contact us if
[437efdf]55you cannot find an appropriate architecture dependent archive.
[a89a22c]56@end ifclear
[354f3b]58You can obtain these (and other) archives from
[354f3b]61@end display
[7aebcd]63@include register.texi
65@heading To install SINGULAR
[695850]67Make sure that you have approximately 20 MByte of free disk space and follow
[a89a22c]68these steps.
71Simply change to the directory in which you wish to install
[6d0847]72@sc{Singular} (usually wherever you install 3rd-party software), for example:
[3de58c]74cd /usr/local
[26644b1]76mkdir install;cd install
[6d0847]77(you do not need root privileges in this case)
[a89a22c]78@end smallexample
80@sc{Singular} specific subdirectories will be created in such a way
81that multiple versions and multiple architecture dependent files
[3de58c]82of @sc{Singular} can peaceably coexist under the same @code{/usr/local}
86Unpack the archives:
[6d0847]88gzip -dc <path_to>/Singular-@value{VERSION}-@value{_UNAME}.tar.gz | tar -pxf -
89gzip -dc <path_to>/Singular-@value{VERSION}-share.tar.gz | tar -pxf -
[a89a22c]90@end smallexample
[7e96fe]92This creates the directory Singular/@value{VERSION} with
[a89a22c]93@multitable @columnfractions .36 .64
94@item (sub)directories
95@tab  which contain
[6d0847]96@item @code{@value{_UNAME}}
97@tab @code{Singular} and @code{ESingular} executables
98@item @code{LIB}
[a89a22c]99@tab @sc{Singular} libraries (@code{*.lib} files)
[6d0847]100@item @code{emacs}
[a89a22c]101@tab files for the @sc{Singular} Emacs user interface
[6d0847]102@item @code{info}
[a89a22c]103@tab info files of @sc{Singular} manual
[6d0847]104@item @code{html}
[a89a22c]105@tab html files of @sc{Singular} manual
[6d0847]106@item @code{doc}
[a89a22c]107@tab miscellaneous documentation files
[6d0847]108@item @code{examples}
[e61231]109@tab @sc{Singular} examples (@code{*.sing} files)
[a89a22c]110@end multitable
112For the executable to work, the directory layout must look pretty much
[7e96fe]113like this; the executable will look for "sibling" directories at run-time
[3de58c]114to figure out where its @sc{Singular} libraries and on-line
[6d0847]115documentation files are. These constraints on the local directory layout
[354f3b]116are necessary to avoid having to hard-code pathnames into the
[a89a22c]117executables, or require that environment variables be set before
[3cc667]118running the executable. In particular, you @strong{must not move or copy}
[a89a22c]119the @sc{Singular} executables to another place, but use soft-links
121@end enumerate
123The following steps are optional:
[c04b94]125@itemize @bullet
127Arrange that typing @code{Singular} at the shell prompt starts up the
[3de58c]128installed @sc{Singular} executable.
130If you have root permission, do:
[a89a22c]132ln -s `pwd`/Singular/@value{VERSION}/@value{_UNAME}/Singular  /usr/local/bin/Singular-@value{VERSION}
133ln -s `pwd`/Singular/@value{VERSION}/@value{_UNAME}/ESingular  /usr/local/bin/ESingular-@value{VERSION}
134ln -s /usr/local/bin/Singular-@value{VERSION} /usr/local/bin/Singular
135ln -s /usr/local/bin/ESingular-@value{VERSION} /usr/local/bin/ESingular
136@end smallexample
[a89a22c]138Otherwise, append the directory
139@code{`pwd`/Singular/@value{VERSION}/@value{_UNAME}/} to your @code{$PATH}
140environment variable. For the @code{csh} (or, @code{tcsh}) shell do:
142set path=(`pwd`/Singular/@value{VERSION}/@value{_UNAME} $path)
[3de58c]143@end smallexample
[a89a22c]144For the @code{bash} (or, @code{ksh}) shell do:
[a89a22c]146export PATH=`pwd`/Singular/@value{VERSION}/@value{_UNAME}/:$PATH
147@end smallexample
149You also might want to adjust your personal start-up files
[354f3b]150(@code{~/.cshrc} for @code{csh}, @code{~/.tcshrc} for @code{tcsh}, or
[3de58c]151@code{~/.profile} for @code{bash}) accordingly,
[a89a22c]152so that the @code{$PATH} variable is set automatically each time you login.
[3de58c]154@strong{IMPORTANT:} Do @emph{never} move or copy the file
[354f3b]155@code{Singular/@value{VERSION}/@value{_UNAME}/Singular} to another
[3de58c]156place, but use soft-links instead.
[7e96fe]159If you wish to use any of the following features of
[1cbba61]160@sc{Singular}, make sure that the respective programs are installed on your system:
162@multitable @columnfractions .5 .5
163@item @strong{Feature} @tab @strong{Requires}
164@item running @code{ESingular}, or @code{Singular} within Emacs
[437efdf]165@tab @uref{,,Emacs} version
[6d0847]16620 or higher, or, @uref{,,XEmacs} version 20.3 or
[7e96fe]167higher (ESingular is only included in the Linux distribution.
168On other Unix platforms you can download the
[437efdf]170@sc{Singular} emacs lisp files} but we give no warranties for specific platforms).
[a89a22c]171@item on-line @code{html} help
[1ccc0a]172@tab any web browser
[a89a22c]173@item on-line @code{info} help
[354f3b]174@tab @uref{,,info}, or
175@uref{,,tkinfo} texinfo browser programs
[a89a22c]176@item TAB completion and history mechanism of ASCII-terminal interface
[354f3b]177@tab shared @uref{,,readline}
[a89a22c]178library, i.e. @code{/usr/lib/}
[3de58c]179@item visualization of curves and surfaces
182Setup executable for the visualization tool surfer.
[a89a22c]183@end multitable
[354f3b]185You may download most of these programs from
[354f3b]188@end display
190@item Customize the on-line help system:
[7e96fe]192By default, on-line help is displayed in @code{html} format using
[26644b1]193a web browser.
[354f3b]195However, this behavior can be customized in several ways
[acc8b4]196using the @sc{Singular} commands @code{system("--browser",<browser>)}
[354f3b]197and @code{system("--allow-net", 1)} (or, by starting up @sc{Singular}
[a89a22c]198with the respective command line options).
200In particular, creating the file
[354f3b]201@code{Singular/@value{VERSION}/LIB/.singularrc} and putting the
[a89a22c]202@sc{Singular} command
204system("--allow-net", 1);
205@end smallexample
206in it, allows the on-line help system to fetch its @code{html} pages
[8cb38d]207from @uref{, Singular's WWW
[3de58c]208home site}
[a89a22c]209in case its local html pages are not found. That is, you may delete your
[3de58c]210local html pages, after setting this option.
[3de58c]212See also
[a89a22c]213@ifset singularmanual
214@ref{The online help system}, @ref{Command line options}, and
[acc8b4]215@ref{Startup sequence},
[a89a22c]216@end ifset
217@ifclear singularmanual
218the sections @emph{The online help system}, @emph{Command line options}, and
[3de58c]219@emph{Startup sequence} in the @sc{Singular} manual
[a89a22c]220@end ifclear
221for more details on customizing the on-line help system.
224Add the line
226* Singular:(singular.hlp).     A system for polynomial computations
227@end smallexample
228to your system-wide @code{dir} file (usually @code{/usr/info/dir} or
229@code{/usr/local/info/dir} and  copy or soft-link the file
231to the directory of your @code{dir} file.
[a89a22c]232@*This assures that the
233@sc{Singular} manual can be  accessed from stand-alone texinfo
[acc8b4]234browser programs such as @code{info} or @code{Emacs}.
[7e96fe]235(This is not a prerequisite for using the help system from within @code{Singular}.)
[a89a22c]236@end itemize
238@heading Troubleshooting
[c04b94]240@itemize @bullet
[437efdf]241@item General: @sc{Singular} cannot find its libraries or on-line help
[6d0847]244Make sure that you have read and/or execute permission the files and
[437efdf]245directories of the @sc{Singular} distribution. If in doubt, @code{cd} to the
[69b674c]246directory where you unpacked @sc{Singular}, and do (as root, if
[6d0847]249chmod -R a+rX Singular
[3de58c]250@end smallexample
253Start up @sc{Singular}, and issue the command @code{system("Singular");}.
254If this does not return the correct and expanded location of the
255@sc{Singular} executable, then you found a bug in @sc{Singular}, which we
256ask you to report (see below).
258Check whether the directories containing the libraries and on-line help
259files can be found by @sc{Singular}: If @code{$bindir} denotes the
260directory where the @sc{Singular} executable resides, then @sc{Singular}
[3de58c]261looks for library files as follows:
262@* (0) the current directory
[354f3b]263@* (1) all dirs of the environment variable SINGULARPATH
264@* (2) @code{$bindir/LIB}
265@* (3) @code{$bindir/../LIB}
266@* (4) @code{/usr/local/Singular/@value{VERSION}/LIB}
267@* (4) @code{/usr/local/Singular/LIB}
268@* The on-line @code{info} files need to be at  @code{$bindir/../info} and the
269@code{html} pages at @code{$bindir/../html}.
270@end enumerate
272You can inspect the found library and @code{info}/@code{html}
273directories by starting up @sc{Singular} with the
274@code{--version} option, or by issuing the @sc{Singular} command
[1ccc0a]277@item Under previous SuSE-Linux releases, @sc{ESingular} did not display a prompt:
[3cc667]278@cindex SuSE, ESingular bug
279@cindex ESingular, no prompt
280@cindex bug, ESingular
[3de58c]281This is due to the very restrictive access rights of @code{/dev/pty*} of
[672950e]282the standard @uref{,SuSE} distribution (starting from
[1ccc0a]283version 6.3 on). The problem may still be present when working with the latest SuSE-Linux release.
284As root, do one of the following: Either
286chmod 666 /dev/pty*
287@end example
290chmod g+s $(which emacs)
291chgrp tty $(which emacs)
292chmod g+s $(which xemacs)
293chgrp tty $(which xemacs)
294@end example
[1ccc0a]296@c @item For @code{HPUX} systems:
297@c @*The /etc/termcap files which are pre-installed on these systems are
298@c broken which leads to messages like
299@c @example
300@c Name collision between 9826 9836
301@c @end example
302@c when @sc{Singular} is started. To fix this, you can get fixed termcap
303@c files from @uref{}
304@c by downloading the files termcap-<uname-description> and either
305@c replace your /etc/termcap file by the file found there, or view, and
306@c redo the respective changes by @code{diff}'ing the downloaded and the
307@c original file.
[354f3b]309@item For @code{ix86-Linux} systems:
310@*Due to some incompatibilities of shared libraries, the start-up of
311@sc{Singular} might fail with messages like
313  Can not find shared library ...
314@end example
[6d0847]315For DEBIAN systems, try to do
316@code{ln -s /usr/lib/ /usr/lib/}.
317@*If this fails (and on other systems)
318download and install
321@item For @code{AIX} systems:
[3de58c]322@*The default @code{info} program of the system is not GNU's texinfo
[354f3b]323browser which is used to display the on-line documentation in the
324@code{info} format. Therefore, the distribution of the AIX executable
[3de58c]325already contains the @code{info} browser program.
[354f3b]326If you remove this program, make sure that the GNU
327@code{info} program is executed if you call '@code{info}' from your shell.
[3de58c]329@item For any other troubles:
[354f3b]330@*Please send an email to @email{}
331and include the header which is displayed by starting up @sc{Singular}
332with the @code{-v} option, and a description of your machine (issue the
333command @code{uname -a} on your shell) in your report.
334@end itemize
[63cc19]336@include info.texi
338@ifclear singularmanual
[3de58c]339GOOD LUCK and ENJOY!
[354f3b]340Your @sc{Singular} team.
341@end ifclear
Note: See TracBrowser for help on using the repository browser.