[e9dfcf] | 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 | |
---|
| 22 | To install @sc{Singular::Plural} on a |
---|
| 23 | @ifset UNAME |
---|
| 24 | @value{_UNAME} |
---|
| 25 | @end ifset |
---|
| 26 | @ifclear UNAME |
---|
| 27 | Unix |
---|
| 28 | @end ifclear |
---|
| 29 | platform, you need the following two |
---|
| 30 | archives: |
---|
| 31 | @table @code |
---|
| 32 | @item SingularPlural-@value{VERSION}-share.tar.gz |
---|
| 33 | contains 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 |
---|
| 37 | contains architecture dependent executables, like the @sc{Singular::Plural} |
---|
| 38 | program. |
---|
| 39 | @end table |
---|
| 40 | @ifclear UNAME |
---|
| 41 | @* |
---|
| 42 | @code{@value{_UNAME}} is a description of the processor and operating system |
---|
| 43 | for which @sc{Singular::Plural} is compiled (e.g, @code{ix86-Linux}). Please contact us if |
---|
[437efdf] | 44 | you cannot find an appropriate architecture dependent archive. |
---|
[e9dfcf] | 45 | @end ifclear |
---|
| 46 | |
---|
| 47 | You 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 | |
---|
| 56 | Make sure that you have approximately 12MByte of free disk space and follow |
---|
| 57 | these steps. |
---|
| 58 | @enumerate |
---|
| 59 | @item |
---|
| 60 | Simply change to the directory in which you wish to install |
---|
| 61 | @sc{Singular} (usually wherever you install 3rd-party software), for example: |
---|
| 62 | @smallexample |
---|
| 63 | cd /usr/local |
---|
| 64 | or |
---|
| 65 | mkdir 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 |
---|
| 70 | that multiple versions and multiple architecture dependent files |
---|
| 71 | of @sc{Singular} can peaceably coexist under the same @code{/usr/local} |
---|
| 72 | tree. |
---|
| 73 | |
---|
| 74 | @item |
---|
| 75 | Unpack the archives: |
---|
| 76 | @smallexample |
---|
| 77 | gzip -dc <path_to>/SingularPlural-@value{VERSION}-@value{_UNAME}.tar.gz | tar -pxf - |
---|
| 78 | gzip -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 | |
---|
[7e96fe] | 87 | This creates the directory Plural/@value{VERSION} with |
---|
[e9dfcf] | 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 | |
---|
| 107 | For the executable to work, the directory layout must look pretty much |
---|
[7e96fe] | 108 | like this; the executable will look for "sibling" directories at run-time |
---|
[e9dfcf] | 109 | to figure out where its @sc{Singular::Plural} libraries and on-line |
---|
| 110 | documentation files are. These constraints on the local directory layout |
---|
| 111 | are necessary to avoid having to hard-code pathnames into the |
---|
| 112 | executables, or require that environment variables be set before |
---|
| 113 | running the executable. In particular, you @strong{must not move or copy} |
---|
| 114 | the @sc{Singular::Plural} executables to another place, but use soft-links |
---|
| 115 | instead. |
---|
| 116 | @end enumerate |
---|
| 117 | |
---|
| 118 | The following steps are optional: |
---|
| 119 | |
---|
| 120 | @itemize @bullet |
---|
| 121 | @item |
---|
| 122 | Arrange that typing @code{Plural} at the shell prompt starts up the |
---|
| 123 | installed @sc{Singular::Plural} executable. |
---|
| 124 | |
---|
| 125 | If you have root permission, do: |
---|
| 126 | @smallexample |
---|
| 127 | ln -s `pwd`/Plural/@value{VERSION}/@value{_UNAME}/Plural /usr/local/bin/Plural-@value{VERSION} |
---|
| 128 | ln -s `pwd`/Plural/@value{VERSION}/@value{_UNAME}/EPlural /usr/local/bin/EPlural-@value{VERSION} |
---|
| 129 | ln -s /usr/local/bin/Plural-@value{VERSION} /usr/local/bin/Plural |
---|
| 130 | ln -s /usr/local/bin/EPlural-@value{VERSION} /usr/local/bin/EPlural |
---|
| 131 | @end smallexample |
---|
| 132 | |
---|
| 133 | Otherwise, append the directory |
---|
| 134 | @code{`pwd`/Plural/@value{VERSION}/@value{_UNAME}/} to your @code{$PATH} |
---|
| 135 | environment variable. For the @code{csh} (or, @code{tcsh}) shell do: |
---|
| 136 | @smallexample |
---|
| 137 | set path=(`pwd`/Plural/@value{VERSION}/@value{_UNAME} $path) |
---|
| 138 | @end smallexample |
---|
| 139 | For the @code{bash} (or, @code{ksh}) shell do: |
---|
| 140 | @smallexample |
---|
| 141 | export PATH=`pwd`/Plural/@value{VERSION}/@value{_UNAME}/:$PATH |
---|
| 142 | @end smallexample |
---|
| 143 | |
---|
| 144 | You 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, |
---|
| 147 | so 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 |
---|
| 151 | place, but use soft-links instead. |
---|
| 152 | |
---|
| 153 | @item |
---|
[7e96fe] | 154 | If you wish to use any of the following features of |
---|
[e9dfcf] | 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 |
---|
[437efdf] | 160 | @tab @uref{http://www.gnu.org/software/emacs/emacs.html,,Emacs} version |
---|
[e9dfcf] | 161 | 20 or higher, or, @uref{http://www.xemacs.org,,XEmacs} version 20.3 or |
---|
[7e96fe] | 162 | higher (EPlural is only included in the Linux distribution. |
---|
| 163 | On other Unix platforms you can download the |
---|
[e9dfcf] | 164 | @uref{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/src/,, |
---|
[437efdf] | 165 | @sc{Singular} emacs lisp files} but we give no warranties for specific platforms). |
---|
[e9dfcf] | 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} |
---|
| 173 | library, i.e. @code{/usr/lib/libreadline.so} |
---|
| 174 | @item visualization of curves and surfaces |
---|
| 175 | @tab |
---|
[437efdf] | 176 | @uref{http://www.imaginary2008.de/surfer.php,,surfer} |
---|
| 177 | Setup executable for the visualization tool surfer. |
---|
[e9dfcf] | 178 | @end multitable |
---|
| 179 | |
---|
| 180 | You 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 | |
---|
[7e96fe] | 187 | By default, on-line help is displayed in @code{html} format using |
---|
[e9dfcf] | 188 | the @code{netscape} program. |
---|
| 189 | |
---|
| 190 | However, this behavior can be customized in several ways |
---|
| 191 | using the @sc{Singular::Plural} commands @code{system("--browser",<browser>)} |
---|
| 192 | and @code{system("--allow-net", 1)} (or, by starting up @sc{Singular} |
---|
| 193 | with the respective command line options). |
---|
| 194 | |
---|
| 195 | In particular, creating the file |
---|
| 196 | @code{Plural/@value{VERSION}/LIB/.singularrc} and putting the |
---|
| 197 | @sc{Singular::Plural} command |
---|
| 198 | @smallexample |
---|
| 199 | system("--allow-net", 1); |
---|
| 200 | @end smallexample |
---|
| 201 | in it, allows the on-line help system to fetch its @code{html} pages |
---|
| 202 | from @uref{http://www.singular.uni-kl.de, Singular's WWW |
---|
| 203 | home site} |
---|
| 204 | in case its local html pages are not found. That is, you may delete your |
---|
| 205 | local html pages, after setting this option. |
---|
| 206 | |
---|
| 207 | See 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 |
---|
| 213 | the sections @emph{The online help system}, @emph{Command line options}, and |
---|
| 214 | @emph{Startup sequence} in the @sc{Singular} manual |
---|
| 215 | @end ifclear |
---|
| 216 | for more details on customizing the on-line help system. |
---|
| 217 | |
---|
| 218 | @item |
---|
| 219 | Add the line |
---|
| 220 | @smallexample |
---|
[21ebf68] | 221 | * Plural:(plural.hlp). A system for non-commutative polynomial computations |
---|
[e9dfcf] | 222 | @end smallexample |
---|
| 223 | to 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} |
---|
| 226 | to the directory of your @code{dir} file. |
---|
| 227 | @*This assures that the |
---|
| 228 | @sc{Singular::Plural} manual can be accessed from stand-alone texinfo |
---|
| 229 | browser programs such as @code{info} or @code{Emacs}. |
---|
[7e96fe] | 230 | (This is not a prerequisite for using the help system from within @code{Plural}.) |
---|
[e9dfcf] | 231 | @end itemize |
---|
| 232 | |
---|
| 233 | @heading Troubleshooting |
---|
| 234 | |
---|
| 235 | @itemize @bullet |
---|
[437efdf] | 236 | @item General: @sc{Plural} cannot find its libraries or on-line help |
---|
[e9dfcf] | 237 | @enumerate |
---|
| 238 | @item |
---|
[7e96fe] | 239 | Make sure that you have read and/or execute permission for files and |
---|
[437efdf] | 240 | directories of the @sc{Singular} distribution. If in doubt, @code{cd} to the |
---|
[e9dfcf] | 241 | directory where you unpacked @sc{Singular}, and do (as root, if |
---|
| 242 | necessary): |
---|
| 243 | @smallexample |
---|
| 244 | chmod -R a+rX Plural |
---|
| 245 | @end smallexample |
---|
| 246 | |
---|
| 247 | @item |
---|
| 248 | Start up @sc{Plural}, and issue the command @code{system("Singular");}. |
---|
| 249 | If 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 |
---|
| 251 | ask you to report (see below). |
---|
| 252 | @item |
---|
| 253 | Check whether the directories containing the libraries and on-line help |
---|
| 254 | files can be found by @sc{Plural}: If @code{$bindir} denotes the |
---|
| 255 | directory where the @sc{Plural} executable resides, then @sc{Plural} |
---|
| 256 | looks 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 | |
---|
| 267 | You can inspect the found library and @code{info}/@code{html} |
---|
| 268 | directories 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 |
---|
| 276 | This is due to the very restrictive access rights of @code{/dev/pty*} of |
---|
| 277 | the standard @uref{http:/www.suse.de,SuSE} distribution (starting from |
---|
[7e96fe] | 278 | version 6.3 onwards). As root, do one of the following: Either |
---|
[e9dfcf] | 279 | @example |
---|
| 280 | chmod 666 /dev/pty* |
---|
| 281 | @end example |
---|
| 282 | or, |
---|
| 283 | @example |
---|
| 284 | chmod g+s $(which emacs) |
---|
| 285 | chgrp tty $(which emacs) |
---|
| 286 | chmod g+s $(which xemacs) |
---|
| 287 | chgrp tty $(which xemacs) |
---|
| 288 | @end example |
---|
| 289 | See also @uref{http://sdb.suse.de/sdb/de/html/ke_devpts-63.html} for |
---|
| 290 | details. |
---|
| 291 | |
---|
| 292 | @item For @code{HPUX} systems: |
---|
| 293 | @*The /etc/termcap files which are pre-installed on these systems are |
---|
| 294 | broken which leads to messages like |
---|
| 295 | @example |
---|
| 296 | Name collision between 9826 9836 |
---|
| 297 | @end example |
---|
| 298 | when @sc{Plural} is started. To fix this, you can get fixed termcap |
---|
| 299 | files from @uref{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/utils} |
---|
| 300 | by downloading the files termcap-<uname-description> and either |
---|
| 301 | replace your /etc/termcap file by the file found there, or view, and |
---|
| 302 | redo the respective changes by @code{diff}'ing the downloaded and the |
---|
| 303 | original 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 |
---|
| 311 | For 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) |
---|
| 314 | download 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 |
---|
| 319 | browser which is used to display the on-line documentation in the |
---|
| 320 | @code{info} format. Therefore, the distribution of the AIX executable |
---|
| 321 | already contains the @code{info} browser program. |
---|
| 322 | If 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} |
---|
| 327 | and include the header which is displayed by starting up @sc{Plural} |
---|
| 328 | with the @code{-v} option, and a description of your machine (issue the |
---|
| 329 | command @code{uname -a} on your shell) in your report. |
---|
| 330 | @end itemize |
---|
| 331 | |
---|
| 332 | @include info.texi |
---|
| 333 | |
---|
| 334 | @ifclear singularmanual |
---|
| 335 | GOOD LUCK and ENJOY! |
---|
| 336 | Your @sc{Singular::Plural} team. |
---|
| 337 | @end ifclear |
---|
| 338 | |
---|