3294
|
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 |