source: git/doc/INSTALL_unix.texi @ cdd964

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