Mercurial > octave
comparison doc/interpreter/install.txi @ 3294:bfe1573bd2ae
[project @ 1999-10-19 10:06:07 by jwe]
author | jwe |
---|---|
date | Tue, 19 Oct 1999 10:08:42 +0000 |
parents | |
children | ab5ae0aca0f1 |
comparison
equal
deleted
inserted
replaced
3293:58950f032a06 | 3294:bfe1573bd2ae |
---|---|
1 @c Copyright (C) 1996, 1997 John W. Eaton | |
2 @c This is part of the Octave manual. | |
3 @c For copying conditions, see the file gpl.texi. | |
4 | |
5 @c The text of this file will eventually appear in the file INSTALL | |
6 @c in the Octave distribution, as well as in the Octave manual. | |
7 | |
8 @ifclear INSTALLONLY | |
9 @node Installation, Emacs, Trouble, Top | |
10 @appendix Installing Octave | |
11 @end ifclear | |
12 | |
13 @ifset INSTALLONLY | |
14 @include conf.texi | |
15 | |
16 This file documents the installation of Octave. | |
17 | |
18 Octave is free software; you can redistribute it and/or modify it | |
19 under the terms of the GNU General Public License as published by the | |
20 Free Software Foundation. | |
21 | |
22 @node Installation, , Installation | |
23 @chapter Installing Octave | |
24 @end ifset | |
25 | |
26 @cindex installing Octave | |
27 | |
28 Here is the procedure for installing Octave from scratch on a Unix | |
29 system. For instructions on how to install the binary distributions of | |
30 Octave, see @ref{Binary Distributions}. | |
31 | |
32 @itemize @bullet | |
33 @item | |
34 Run the shell script @file{configure}. This will determine the features | |
35 your system has (or doesn't have) and create a file named | |
36 @file{Makefile} from each of the files named @file{Makefile.in}. | |
37 | |
38 Here is a summary of the configure options that are most frequently used | |
39 when building Octave: | |
40 | |
41 @table @code | |
42 @item --prefix=@var{prefix} | |
43 Install Octave in subdirectories below @var{prefix}. The default value | |
44 of @var{prefix} is @file{/usr/local}. | |
45 | |
46 @item --srcdir=@var{dir} | |
47 Look for Octave sources in the directory @var{dir}. | |
48 | |
49 @item --with-f2c | |
50 Use @code{f2c} even if a Fortran compiler is available. | |
51 | |
52 @item --with-g77 | |
53 Use @code{g77} to compile Fortran code. | |
54 | |
55 @item --enable-shared | |
56 Create shared libraries. If you are planning to use | |
57 @code{--enable-lite-kernelel} or the dynamic loading features, you will | |
58 probably want to use this option. It will make your @file{.oct} files | |
59 much smaller and on some systems it may be necessary to build shared | |
60 libraries in order to use dynamically linked functions. | |
61 | |
62 You may also want to build a shared version of @code{libstdc++}, if your | |
63 system doesn't already have one. Note that a patch is needed to build | |
64 shared versions of version 2.7.2 of @code{libstdc++} on the HP-PA | |
65 architecture. You can find the patch at | |
66 @url{ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix}. | |
67 | |
68 @item --enable-dl | |
69 Use @code{dlopen} and friends to make Octave capable of dynamically | |
70 linking externally compiled functions. This only works on systems that | |
71 actually have these functions. If you plan on using this feature, you | |
72 should probably also use @code{--enable-shared} to reduce the size of | |
73 your @file{.oct} files. | |
74 | |
75 @item --enable-shl | |
76 Use @code{shl_load} and friends to make Octave capable of dynamically | |
77 linking externally compiled functions. This only works on systems that | |
78 actually have these functions (only HP-UX systems). If you plan on | |
79 using this feature, you should probably also use @code{--enable-shared} | |
80 to reduce the size of your @file{.oct} files. | |
81 | |
82 @item --enable-lite-kernel | |
83 Compile smaller kernel. This currently requires the dynamic linking | |
84 functions @code{dlopen} or @code{shl_load} and friends so that Octave | |
85 can load functions at run time that are not loaded at compile time. | |
86 | |
87 @item --help | |
88 Print a summary of the options recognized by the configure script. | |
89 @end table | |
90 | |
91 See the file @file{INSTALL} for more information about the command line | |
92 options used by configure. That file also contains instructions for | |
93 compiling in a directory other than where the source is located. | |
94 | |
95 @item | |
96 Run make. | |
97 | |
98 You will need a recent version of GNU Make. Modifying Octave's | |
99 makefiles to work with other make programs is probably not worth | |
100 your time. We recommend you get and compile GNU Make instead. | |
101 | |
102 For plotting, you will need to have gnuplot installed on your system. | |
103 Gnuplot is a command-driven interactive function plotting program. | |
104 Gnuplot is copyrighted, but freely distributable. The `gnu' in gnuplot | |
105 is a coincidence---it is not related to the GNU project or the FSF in | |
106 any but the most peripheral sense. | |
107 | |
108 To compile Octave, you will need a recent version of GNU Make. You | |
109 will also need @code{g++} 2.7.2 or later. Version 2.8.0 or @code{egcs} | |
110 1.0.x should work. Later versions may work, but C++ is still evolving, | |
111 so don't be too surprised if you run into some trouble. | |
112 | |
113 It is no longer necessary to have @code{libg++}, but you do need to have | |
114 the GNU implementation of @code{libstdc++}. If you are using @code{g++} | |
115 2.7.2, @code{libstdc++} is distributed along with @code{libg++}, but for | |
116 later versions, @code{libstdc++} is distributed separately. For | |
117 @code{egcs}, @code{libstdc++} is included with the compiler | |
118 distribution. | |
119 | |
120 If you plan to modify the parser you will also need GNU @code{bison} and | |
121 @code{flex}. If you modify the documentation, you will need GNU | |
122 Texinfo, along with the patch for the @code{makeinfo} program that is | |
123 distributed with Octave. | |
124 | |
125 GNU Make, @code{gcc}, and @code{libstdc++}, @code{gnuplot}, | |
126 @code{bison}, @code{flex}, and Texinfo are all available from many | |
127 anonymous ftp archives. The primary site is @url{ftp.gnu.org}, but it | |
128 is often very busy. A list of sites that mirror the software on | |
129 @url{ftp.gnu.org} is available by anonymous ftp from | |
130 @url{ftp://ftp.gnu.org/pub/gnu/GNUinfo/FTP}. | |
131 | |
132 If you don't have a Fortran compiler, or if your Fortran compiler | |
133 doesn't work like the traditional Unix f77, you will need to have the | |
134 Fortran to C translator @code{f2c}. You can get @code{f2c} from any | |
135 number of anonymous ftp archives. The most recent version of @code{f2c} | |
136 is always available from @url{netlib.att.com}. | |
137 | |
138 On an otherwise idle Pentium 133 running Linux, it will take somewhere | |
139 between 1-1/2 to 3 hours to compile everything, depending on whether you | |
140 are building shared libraries. You will need about 100 megabytes of disk | |
141 storage to work with (considerably less if you don't compile with debugging | |
142 symbols). To do that, use the command | |
143 | |
144 @example | |
145 make CFLAGS=-O CXXFLAGS=-O LDFLAGS= | |
146 @end example | |
147 | |
148 @noindent | |
149 instead of just @samp{make}. | |
150 | |
151 @item | |
152 If you encounter errors while compiling Octave, first check the list of | |
153 known problems below to see if there is a workaround or solution for | |
154 your problem. If not, | |
155 @ifclear INSTALLONLY | |
156 see @ref{Trouble}, | |
157 @end ifclear | |
158 @ifset INSTALLONLY | |
159 see the file BUGS | |
160 @end ifset | |
161 for information about how to report bugs. | |
162 | |
163 @item | |
164 Once you have successfully compiled Octave, run @samp{make install}. | |
165 | |
166 This will install a copy of octave, its libraries, and its documentation | |
167 in the destination directory. As distributed, Octave is installed in | |
168 the following directories. In the table below, @var{prefix} defaults to | |
169 @file{/usr/local}, @var{version} stands for the current version number | |
170 of the interpreter, and @var{arch} is the type of computer on which | |
171 Octave is installed (for example, @samp{i586-unknown-gnu}). | |
172 | |
173 @table @file | |
174 @item @var{prefix}/bin | |
175 Octave and other binaries that people will want to run directly. | |
176 | |
177 @item @var{prefix}/lib | |
178 Libraries like libcruft.a and liboctave.a. | |
179 | |
180 @item @var{prefix}/share | |
181 Architecture-independent data files. | |
182 | |
183 @item @var{prefix}/include/octave | |
184 Include files distributed with Octave. | |
185 | |
186 @item @var{prefix}/man/man1 | |
187 Unix-style man pages describing Octave. | |
188 | |
189 @item @var{prefix}/info | |
190 Info files describing Octave. | |
191 | |
192 @item @var{prefix}/share/octave/@var{version}/m | |
193 Function files distributed with Octave. This includes the Octave | |
194 version, so that multiple versions of Octave may be installed at the | |
195 same time. | |
196 | |
197 @item @var{prefix}/lib/octave/@var{version}/exec/@var{arch} | |
198 Executables to be run by Octave rather than the user. | |
199 | |
200 @item @var{prefix}/lib/octave/@var{version}/oct/@var{arch} | |
201 Object files that will be dynamically loaded. | |
202 | |
203 @item @var{prefix}/share/octave/@var{version}/imagelib | |
204 Image files that are distributed with Octave. | |
205 @end table | |
206 @end itemize | |
207 | |
208 @menu | |
209 * Installation Problems:: | |
210 * Binary Distributions:: | |
211 @end menu | |
212 | |
213 @node Installation Problems, Binary Distributions, Installation, Installation | |
214 @appendixsec Installation Problems | |
215 | |
216 This section contains a list of problems (and some apparent problems | |
217 that don't really mean anything is wrong) that may show up during | |
218 installation of Octave. | |
219 | |
220 @itemize @bullet | |
221 @item | |
222 On some SCO systems, @code{info} fails to compile if | |
223 @code{HAVE_TERMIOS_H} is defined int @file{config.h}. Simply removing | |
224 the definition from @file{info/config.h} should allow it to compile. | |
225 | |
226 @item | |
227 If @code{configure} finds @code{dlopen}, @code{dlsym}, @code{dlclose}, | |
228 and @code{dlerror}, but not the header file @file{dlfcn.h}, you need to | |
229 find the source for the header file and install it in the directory | |
230 @file{usr/include}. This is reportedly a problem with Slackware 3.1. | |
231 For Linux/GNU systems, the source for @file{dlfcn.h} is in the | |
232 @code{ldso} package. | |
233 | |
234 @item | |
235 Building @file{.oct} files doesn't work. | |
236 | |
237 You should probably have a shared version of @code{libstdc++}. A patch | |
238 is needed to build shared versions of version 2.7.2 of @code{libstdc++} | |
239 on the HP-PA architecture. You can find the patch at | |
240 @url{ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix}. | |
241 | |
242 @item | |
243 On FreeBSD systems Octave may hang while initializing some internal | |
244 constants. The fix appears to be to use | |
245 | |
246 @example | |
247 options GPL_MATH_EMULATE | |
248 @end example | |
249 | |
250 @noindent | |
251 rather than | |
252 | |
253 @example | |
254 options MATH_EMULATE | |
255 @end example | |
256 | |
257 @noindent | |
258 in the kernel configuration files (typically found in the directory | |
259 @file{/sys/i386/conf}. After making this change, you'll need to rebuild | |
260 the kernel, install it, and reboot. | |
261 | |
262 @item | |
263 If you encounter errors like | |
264 | |
265 @smallexample | |
266 @group | |
267 passing `void (*)()' as argument 2 of | |
268 `octave_set_signal_handler(int, void (*)(int))' | |
269 @end group | |
270 @end smallexample | |
271 | |
272 @noindent | |
273 or | |
274 | |
275 @smallexample | |
276 warning: ANSI C++ prohibits conversion from `(int)' to `(...)' | |
277 @end smallexample | |
278 | |
279 @noindent | |
280 while compiling @file{sighandlers.cc}, you may need to edit some files | |
281 in the @code{gcc} include subdirectory to add proper prototypes for functions | |
282 there. For example, Ultrix 4.2 needs proper declarations for the | |
283 @code{signal} function and the @code{SIG_IGN} macro in the file | |
284 @file{signal.h}. | |
285 | |
286 On some systems the @code{SIG_IGN} macro is defined to be something like | |
287 this: | |
288 | |
289 @example | |
290 #define SIG_IGN (void (*)())1 | |
291 @end example | |
292 | |
293 @noindent | |
294 when it should really be something like: | |
295 | |
296 @example | |
297 #define SIG_IGN (void (*)(int))1 | |
298 @end example | |
299 | |
300 @noindent | |
301 to match the prototype declaration for the @code{signal} function. This | |
302 change should also be made for the @code{SIG_DFL} and @code{SIG_ERR} | |
303 symbols. It may be necessary to change the definitions in | |
304 @file{sys/signal.h} as well. | |
305 | |
306 The @code{gcc} @code{fixincludes} and @code{fixproto} scripts should | |
307 probably fix these problems when @code{gcc} installs its modified set of | |
308 header files, but I don't think that's been done yet. | |
309 | |
310 @strong{You should not change the files in @file{/usr/include}}. You | |
311 can find the @code{gcc} include directory tree by running the command | |
312 | |
313 @example | |
314 gcc -print-libgcc-file-name | |
315 @end example | |
316 | |
317 @noindent | |
318 The directory of @code{gcc} include files normally begins in the same directory | |
319 that contains the file @file{libgcc.a}. | |
320 | |
321 @item | |
322 Some of the Fortran subroutines may fail to compile with older versions | |
323 of the Sun Fortran compiler. If you get errors like | |
324 | |
325 @smallexample | |
326 zgemm.f: | |
327 zgemm: | |
328 warning: unexpected parent of complex expression subtree | |
329 zgemm.f, line 245: warning: unexpected parent of complex | |
330 expression subtree | |
331 warning: unexpected parent of complex expression subtree | |
332 zgemm.f, line 304: warning: unexpected parent of complex | |
333 expression subtree | |
334 warning: unexpected parent of complex expression subtree | |
335 zgemm.f, line 327: warning: unexpected parent of complex | |
336 expression subtree | |
337 pcc_binval: missing IR_CONV in complex op | |
338 make[2]: *** [zgemm.o] Error 1 | |
339 @end smallexample | |
340 | |
341 @noindent | |
342 when compiling the Fortran subroutines in the @file{libcruft} | |
343 subdirectory, you should either upgrade your compiler or try compiling | |
344 with optimization turned off. | |
345 | |
346 @item | |
347 On NeXT systems, if you get errors like this: | |
348 | |
349 @example | |
350 /usr/tmp/cc007458.s:unknown:Undefined local symbol LBB7656 | |
351 /usr/tmp/cc007458.s:unknown:Undefined local symbol LBE7656 | |
352 @end example | |
353 | |
354 @noindent | |
355 when compiling @file{Array.cc} and @file{Matrix.cc}, try recompiling | |
356 these files without @code{-g}. | |
357 | |
358 @item | |
359 Some people have reported that calls to shell_cmd and the pager do not | |
360 work on SunOS systems. This is apparently due to having | |
361 @code{G_HAVE_SYS_WAIT} defined to be 0 instead of 1 when compiling | |
362 @code{libg++}. | |
363 | |
364 @item | |
365 On NeXT systems, linking to @file{libsys_s.a} may fail to resolve the | |
366 following functions | |
367 | |
368 @example | |
369 _tcgetattr | |
370 _tcsetattr | |
371 _tcflow | |
372 @end example | |
373 | |
374 @noindent | |
375 which are part of @file{libposix.a}. Unfortunately, linking Octave with | |
376 @code{-posix} results in the following undefined symbols. | |
377 | |
378 @example | |
379 .destructors_used | |
380 .constructors_used | |
381 _objc_msgSend | |
382 _NXGetDefaultValue | |
383 _NXRegisterDefaults | |
384 .objc_class_name_NXStringTable | |
385 .objc_class_name_NXBundle | |
386 @end example | |
387 | |
388 One kluge around this problem is to extract @file{termios.o} from | |
389 @file{libposix.a}, put it in Octave's @file{src} directory, and add it | |
390 to the list of files to link together in the makefile. Suggestions for | |
391 better ways to solve this problem are welcome! | |
392 | |
393 @item | |
394 If Octave crashes immediately with a floating point exception, it is | |
395 likely that it is failing to initialize the IEEE floating point values | |
396 for infinity and NaN. | |
397 | |
398 If your system actually does support IEEE arithmetic, you should be able | |
399 to fix this problem by modifying the function @code{octave_ieee_init} in | |
400 the file @file{lo-ieee.cc} to correctly initialize Octave's internal | |
401 infinity and NaN variables. | |
402 | |
403 If your system does not support IEEE arithmetic but Octave's configure | |
404 script incorrectly determined that it does, you can work around the | |
405 problem by editing the file @file{config.h} to not define | |
406 @code{HAVE_ISINF}, @code{HAVE_FINITE}, and @code{HAVE_ISNAN}. | |
407 | |
408 In any case, please report this as a bug since it might be possible to | |
409 modify Octave's configuration script to automatically determine the | |
410 proper thing to do. | |
411 | |
412 @item | |
413 After installing the binary distribution of Octave in an alternate | |
414 directory, the Emacs command @code{run-octave} doesn't work. Emacs | |
415 hangs in @code{accept-process-output} in @code{inferior-octave-startup}. | |
416 | |
417 This seems to be a problem with executing a shell script using the | |
418 comint package. You can avoid the problem by changing the way Octave is | |
419 installed to eliminate the need for the shell script. You can either | |
420 compile and install Octave using the source distribution, reinstall the | |
421 binary distribution in the default directory, or copy the commands in | |
422 the octave shell script wrapper to your shell startup files (and the | |
423 shell startup files for anyone else who is using Octave) and then | |
424 rename the file @file{octave.bin} to be @file{octave}. | |
425 @end itemize | |
426 | |
427 @node Binary Distributions, , Installation Problems, Installation | |
428 @appendixsec Binary Distributions | |
429 | |
430 Although Octave is not very difficult to build from its sources, it is a | |
431 relatively large program that does require a significant amount of time | |
432 and disk space to compile and install. Because of this, many people | |
433 want to be able to obtain binary distributions so they can start using | |
434 Octave immediately, without having to bother with the details of | |
435 compiling it first. This is understandable, so I try to maintain a | |
436 current collection of binary distributions at | |
437 @url{ftp://ftp.che.wisc.edu/pub/octave/BINARIES}. | |
438 | |
439 Please understand, however, that there is only a limited amount of time | |
440 available to devote to making binaries, so binaries may not be | |
441 immediately available for some platforms. (Please contact | |
442 @email{bug-octave@@bevo.che.wisc.edu} if you are interested in helping | |
443 make a binary distribution available for your system.) | |
444 | |
445 @menu | |
446 * Installing Octave from a Binary Distribution:: | |
447 * Creating a Binary Distribution:: | |
448 @end menu | |
449 | |
450 @node Installing Octave from a Binary Distribution, Creating a Binary Distribution, Binary Distributions, Binary Distributions | |
451 @appendixsubsec Installing Octave from a Binary Distribution | |
452 | |
453 To install Octave from a binary distribution, execute the command | |
454 | |
455 @example | |
456 sh ./install-octave | |
457 @end example | |
458 | |
459 @noindent | |
460 in the top level directory of the distribution. | |
461 | |
462 Binary distributions are normally compiled assuming that Octave will be | |
463 installed in the following subdirectories of @file{/usr/local}. | |
464 | |
465 @table @file | |
466 @item bin | |
467 Octave and other binaries that people will want to run directly. | |
468 | |
469 @item lib | |
470 Shared libraries that Octave needs in order to run. These files are | |
471 not included if you are installing a statically linked version of | |
472 Octave. | |
473 | |
474 @item man/man1 | |
475 Unix-style man pages describing Octave. | |
476 | |
477 @item info | |
478 Info files describing Octave. | |
479 | |
480 @item share/octave/@var{version}/m | |
481 Function files distributed with Octave. This includes the Octave | |
482 version, so that multiple versions of Octave may be installed at the | |
483 same time. | |
484 | |
485 @item libexec/octave/@var{version}/exec/@var{arch} | |
486 Executables to be run by Octave rather than the user. | |
487 | |
488 @item libexec/octave/@var{version}/oct/@var{arch} | |
489 Object files that will be dynamically loaded. | |
490 | |
491 @item share/octave/@var{version}/imagelib | |
492 Image files that are distributed with Octave. | |
493 @end table | |
494 | |
495 @noindent | |
496 where @var{version} stands for the current version number of the | |
497 interpreter, and @var{arch} is the type of computer on which Octave | |
498 is installed (for example, @samp{@value{TARGETHOSTTYPE}}). | |
499 | |
500 If these directories don't exist, the script @code{install-octave} will | |
501 create them for you. The installation script also creates the following | |
502 subdirectories of @file{/usr/local} that are intended for locally | |
503 installed functions: | |
504 | |
505 @table @file | |
506 @item share/octave/site/m | |
507 Locally installed M-files. | |
508 | |
509 @item libexec/octave/site/exec/@var{arch} | |
510 Locally installed binaries intended to be run by Octave rather than by | |
511 the user. | |
512 | |
513 @item libexec/octave/site/octave/@var{arch} | |
514 Local object files that will be dynamically linked. | |
515 @end table | |
516 | |
517 If it is not possible for you to install Octave in @file{/usr/local}, or | |
518 if you would prefer to install it in a different directory, you can | |
519 specify the name of the top level directory as an argument to the | |
520 @file{install-octave} script. For example: | |
521 | |
522 @example | |
523 sh ./install-octave /some/other/directory | |
524 @end example | |
525 | |
526 @noindent | |
527 will install Octave in subdirectories of the directory | |
528 @file{/some/other/directory}. | |
529 | |
530 @node Creating a Binary Distribution, , Installing Octave from a Binary Distribution, Binary Distributions | |
531 @appendixsubsec Creating a Binary Distribution | |
532 | |
533 Here is how to build a binary distribution for others to use. If you | |
534 want to make a binary distribution for your system available along with | |
535 the Octave sources and binaries on @url{ftp.che.wisc.edu}, please follow | |
536 this procedure. For directions explaining how to make the binary | |
537 available on the ftp site, please contact | |
538 @email{bug-octave@@bevo.che.wisc.edu}. | |
539 | |
540 @itemize @bullet | |
541 @item | |
542 Unpack the source distribution: | |
543 | |
544 @example | |
545 gunzip -c octave-@value{VERSION}.tar.gz | tar xf - | |
546 @end example | |
547 | |
548 @item | |
549 Change your current directory to the top-level directory of the source | |
550 distribution: | |
551 | |
552 @example | |
553 cd octave-@value{VERSION} | |
554 @end example | |
555 | |
556 @item | |
557 Make the binary distribution: | |
558 | |
559 @example | |
560 make binary-dist | |
561 @end example | |
562 | |
563 This will create a compressed tar file ready for distribution. | |
564 It will have a name like | |
565 @file{octave-@value{VERSION}-@value{TARGETHOSTTYPE}.tar.gz} | |
566 @end itemize |