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 | |
---|
23 | The possibilities for installing @sc{Singular} on a Unix or Linux system range from |
---|
24 | a purely manual installation over a convenient installation of RPM or DEB |
---|
25 | packages up to a completely automated installation via a package tool like |
---|
26 | apt or yum. |
---|
27 | |
---|
28 | For a Linux system with RPM (like Redhat/Fedora, Mandrake/Mandriva, SuSE etc.), |
---|
29 | or with DEB (like Debian, Ubuntu etc.) one should follow |
---|
30 | the intructions at @url{http://www.singular.uni-kl.de/UNIX/}. |
---|
31 | |
---|
32 | The manual installation (for all other Unix systems) is described below: |
---|
33 | |
---|
34 | To install @sc{Singular} on a |
---|
35 | @ifset UNAME |
---|
36 | @value{_UNAME} |
---|
37 | @end ifset |
---|
38 | @ifclear UNAME |
---|
39 | Unix |
---|
40 | @end ifclear |
---|
41 | platform, you need the following two |
---|
42 | archives: |
---|
43 | @table @code |
---|
44 | @item a: |
---|
45 | Singular-@value{VERSION}-share.tar.gz |
---|
46 | contains architecture independent data like documentation and libraries. |
---|
47 | @item b: |
---|
48 | Singular-@value{VERSION}-@value{_UNAME}.tar.gz |
---|
49 | contains architecture dependent executables, like the @sc{Singular} |
---|
50 | program. |
---|
51 | @end table |
---|
52 | @ifclear UNAME |
---|
53 | @* |
---|
54 | @code{@value{_UNAME}} is a description of the processor and operating system |
---|
55 | for which @sc{Singular} is compiled (e.g, @code{ix86-Linux}). Please contact us if |
---|
56 | you cannot find an appropriate architecture dependent archive. |
---|
57 | @end ifclear |
---|
58 | |
---|
59 | You 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 | |
---|
68 | Make sure that you have approximately 20 MByte of free disk space and follow |
---|
69 | these steps. |
---|
70 | @enumerate |
---|
71 | @item |
---|
72 | Simply change to the directory in which you wish to install |
---|
73 | @sc{Singular} (usually wherever you install 3rd-party software), for example: |
---|
74 | @smallexample |
---|
75 | cd /usr/local |
---|
76 | or |
---|
77 | mkdir 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 |
---|
82 | that multiple versions and multiple architecture dependent files |
---|
83 | of @sc{Singular} can peaceably coexist under the same @code{/usr/local} |
---|
84 | tree. |
---|
85 | |
---|
86 | @item |
---|
87 | Unpack the archives: |
---|
88 | @smallexample |
---|
89 | gzip -dc <path_to>/Singular-@value{VERSION}-@value{_UNAME}.tar.gz | tar -pxf - |
---|
90 | gzip -dc <path_to>/Singular-@value{VERSION}-share.tar.gz | tar -pxf - |
---|
91 | @end smallexample |
---|
92 | |
---|
93 | This 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 | |
---|
113 | For the executable to work, the directory layout must look pretty much |
---|
114 | like this; the executable will look for "sibling" directories at run-time |
---|
115 | to figure out where its @sc{Singular} libraries and on-line |
---|
116 | documentation files are. These constraints on the local directory layout |
---|
117 | are necessary to avoid having to hard-code pathnames into the |
---|
118 | executables, or require that environment variables be set before |
---|
119 | running the executable. In particular, you @strong{must not move or copy} |
---|
120 | the @sc{Singular} executables to another place, but use soft-links |
---|
121 | instead. |
---|
122 | @end enumerate |
---|
123 | |
---|
124 | The following steps are optional: |
---|
125 | |
---|
126 | @itemize @bullet |
---|
127 | @item |
---|
128 | Arrange that typing @code{Singular} at the shell prompt starts up the |
---|
129 | installed @sc{Singular} executable. |
---|
130 | |
---|
131 | If you have root permission, do: |
---|
132 | @smallexample |
---|
133 | ln -s `pwd`/Singular/@value{VERSION}/@value{_UNAME}/Singular /usr/local/bin/Singular-@value{VERSION} |
---|
134 | ln -s `pwd`/Singular/@value{VERSION}/@value{_UNAME}/ESingular /usr/local/bin/ESingular-@value{VERSION} |
---|
135 | ln -s /usr/local/bin/Singular-@value{VERSION} /usr/local/bin/Singular |
---|
136 | ln -s /usr/local/bin/ESingular-@value{VERSION} /usr/local/bin/ESingular |
---|
137 | @end smallexample |
---|
138 | |
---|
139 | Otherwise, append the directory |
---|
140 | @code{`pwd`/Singular/@value{VERSION}/@value{_UNAME}/} to your @code{$PATH} |
---|
141 | environment variable. For the @code{csh} (or, @code{tcsh}) shell do: |
---|
142 | @smallexample |
---|
143 | set path=(`pwd`/Singular/@value{VERSION}/@value{_UNAME} $path) |
---|
144 | @end smallexample |
---|
145 | For the @code{bash} (or, @code{ksh}) shell do: |
---|
146 | @smallexample |
---|
147 | export PATH=`pwd`/Singular/@value{VERSION}/@value{_UNAME}/:$PATH |
---|
148 | @end smallexample |
---|
149 | |
---|
150 | You 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, |
---|
153 | so 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 |
---|
157 | place, but use soft-links instead. |
---|
158 | |
---|
159 | @item |
---|
160 | If 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 |
---|
167 | 20 or higher, or, @uref{http://www.xemacs.org,,XEmacs} version 20.3 or |
---|
168 | higher (ESingular is only included in the Linux distribution. |
---|
169 | On 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} |
---|
179 | library, 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} |
---|
183 | Setup executable for the visualization tool surfer. |
---|
184 | @end multitable |
---|
185 | |
---|
186 | You 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 | |
---|
193 | By default, on-line help is displayed in @code{html} format using |
---|
194 | the @code{netscape} program. |
---|
195 | |
---|
196 | However, this behavior can be customized in several ways |
---|
197 | using the @sc{Singular} commands @code{system("--browser",<browser>)} |
---|
198 | and @code{system("--allow-net", 1)} (or, by starting up @sc{Singular} |
---|
199 | with the respective command line options). |
---|
200 | |
---|
201 | In particular, creating the file |
---|
202 | @code{Singular/@value{VERSION}/LIB/.singularrc} and putting the |
---|
203 | @sc{Singular} command |
---|
204 | @smallexample |
---|
205 | system("--allow-net", 1); |
---|
206 | @end smallexample |
---|
207 | in it, allows the on-line help system to fetch its @code{html} pages |
---|
208 | from @uref{http://www.singular.uni-kl.de, Singular's WWW |
---|
209 | home site} |
---|
210 | in case its local html pages are not found. That is, you may delete your |
---|
211 | local html pages, after setting this option. |
---|
212 | |
---|
213 | See 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 |
---|
219 | the sections @emph{The online help system}, @emph{Command line options}, and |
---|
220 | @emph{Startup sequence} in the @sc{Singular} manual |
---|
221 | @end ifclear |
---|
222 | for more details on customizing the on-line help system. |
---|
223 | |
---|
224 | @item |
---|
225 | Add the line |
---|
226 | @smallexample |
---|
227 | * Singular:(singular.hlp). A system for polynomial computations |
---|
228 | @end smallexample |
---|
229 | to 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} |
---|
232 | to the directory of your @code{dir} file. |
---|
233 | @*This assures that the |
---|
234 | @sc{Singular} manual can be accessed from stand-alone texinfo |
---|
235 | browser 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 |
---|
245 | Make sure that you have read and/or execute permission the files and |
---|
246 | directories of the @sc{Singular} distribution. If in doubt, @code{cd} to the |
---|
247 | directory where you unpacked @sc{Singular}, and do (as root, if |
---|
248 | necessary): |
---|
249 | @smallexample |
---|
250 | chmod -R a+rX Singular |
---|
251 | @end smallexample |
---|
252 | |
---|
253 | @item |
---|
254 | Start up @sc{Singular}, and issue the command @code{system("Singular");}. |
---|
255 | If 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 |
---|
257 | ask you to report (see below). |
---|
258 | @item |
---|
259 | Check whether the directories containing the libraries and on-line help |
---|
260 | files can be found by @sc{Singular}: If @code{$bindir} denotes the |
---|
261 | directory where the @sc{Singular} executable resides, then @sc{Singular} |
---|
262 | looks 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 | |
---|
273 | You can inspect the found library and @code{info}/@code{html} |
---|
274 | directories 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 |
---|
282 | This is due to the very restrictive access rights of @code{/dev/pty*} of |
---|
283 | the standard @uref{http://www.suse.de,SuSE} distribution (starting from |
---|
284 | version 6.3 on). The problem may still be present when working with the latest SuSE-Linux release. |
---|
285 | As root, do one of the following: Either |
---|
286 | @example |
---|
287 | chmod 666 /dev/pty* |
---|
288 | @end example |
---|
289 | or, |
---|
290 | @example |
---|
291 | chmod g+s $(which emacs) |
---|
292 | chgrp tty $(which emacs) |
---|
293 | chmod g+s $(which xemacs) |
---|
294 | chgrp 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 |
---|
316 | For 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) |
---|
319 | download 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 |
---|
324 | browser which is used to display the on-line documentation in the |
---|
325 | @code{info} format. Therefore, the distribution of the AIX executable |
---|
326 | already contains the @code{info} browser program. |
---|
327 | If 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} |
---|
332 | and include the header which is displayed by starting up @sc{Singular} |
---|
333 | with the @code{-v} option, and a description of your machine (issue the |
---|
334 | command @code{uname -a} on your shell) in your report. |
---|
335 | @end itemize |
---|
336 | |
---|
337 | @include info.texi |
---|
338 | |
---|
339 | @ifclear singularmanual |
---|
340 | GOOD LUCK and ENJOY! |
---|
341 | Your @sc{Singular} team. |
---|
342 | @end ifclear |
---|
343 | |
---|