source: git/doc/INSTALL_unix.plural.texi @ 3aa7f9

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