source: git/doc/INSTALL_unix.plural.texi @ 780081

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