6778
|
1 @c Copyright (C) 1996, 1997, 2007 John W. Eaton |
7018
|
2 @c |
|
3 @c This file is part of Octave. |
|
4 @c |
|
5 @c Octave is free software; you can redistribute it and/or modify it |
|
6 @c under the terms of the GNU General Public License as published by the |
|
7 @c Free Software Foundation; either version 3 of the License, or (at |
|
8 @c your option) any later version. |
|
9 @c |
|
10 @c Octave is distributed in the hope that it will be useful, but WITHOUT |
|
11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
13 @c for more details. |
|
14 @c |
|
15 @c You should have received a copy of the GNU General Public License |
|
16 @c along with Octave; see the file COPYING. If not, see |
|
17 @c <http://www.gnu.org/licenses/>. |
3294
|
18 |
7018
|
19 @c The text of this file appears in the file INSTALL in the Octave |
|
20 @c distribution, as well as in the Octave manual. |
3294
|
21 |
|
22 @ifclear INSTALLONLY |
4167
|
23 @node Installation |
3294
|
24 @appendix Installing Octave |
|
25 @end ifclear |
|
26 |
|
27 @ifset INSTALLONLY |
|
28 @include conf.texi |
|
29 |
|
30 This file documents the installation of Octave. |
|
31 |
|
32 Octave is free software; you can redistribute it and/or modify it |
|
33 under the terms of the GNU General Public License as published by the |
|
34 Free Software Foundation. |
|
35 |
4167
|
36 @node Installation |
3294
|
37 @chapter Installing Octave |
|
38 @end ifset |
|
39 |
|
40 @cindex installing Octave |
|
41 |
|
42 Here is the procedure for installing Octave from scratch on a Unix |
3862
|
43 system. |
3294
|
44 |
|
45 @itemize @bullet |
|
46 @item |
|
47 Run the shell script @file{configure}. This will determine the features |
|
48 your system has (or doesn't have) and create a file named |
|
49 @file{Makefile} from each of the files named @file{Makefile.in}. |
|
50 |
|
51 Here is a summary of the configure options that are most frequently used |
|
52 when building Octave: |
|
53 |
|
54 @table @code |
|
55 @item --prefix=@var{prefix} |
|
56 Install Octave in subdirectories below @var{prefix}. The default value |
|
57 of @var{prefix} is @file{/usr/local}. |
|
58 |
|
59 @item --srcdir=@var{dir} |
|
60 Look for Octave sources in the directory @var{dir}. |
|
61 |
7091
|
62 @item --enable-bounds-check |
|
63 Enable bounds checking for indexing operators in the internal array |
|
64 classes. This option is primarily used for debugging Octave. Building |
|
65 Octave with this option has a negative impact on performace and is not |
|
66 recommended for general use. |
3294
|
67 |
7091
|
68 @item --enable-64 |
|
69 This is an @strong{experimental} option to enable Octave to use 64-bit |
|
70 integers for array dimensions and indexing on 64-bit platforms. You |
|
71 probably don't want to use this option unless you know what you are |
|
72 doing. |
|
73 |
|
74 If you use @code{--enable-64}, you must ensure that your Fortran |
|
75 compiler generates code with 8 byte signed @code{INTEGER} values, and |
|
76 that your BLAS and LAPACK libraries are compiled to use 8 byte |
|
77 signed integers for array dimensions and indexing. |
3294
|
78 |
|
79 @item --enable-shared |
7091
|
80 Create shared libraries (this is the default). If you are planning to |
|
81 use the dynamic loading features, you will probably want to use this |
|
82 option. It will make your @file{.oct} files much smaller and on some |
|
83 systems it may be necessary to build shared libraries in order to use |
|
84 dynamically linked functions. |
3294
|
85 |
|
86 You may also want to build a shared version of @code{libstdc++}, if your |
7081
|
87 system doesn't already have one. |
3294
|
88 |
|
89 @item --enable-dl |
|
90 Use @code{dlopen} and friends to make Octave capable of dynamically |
7091
|
91 linking externally compiled functions (this is the default if |
|
92 @code{--enable-shared} is specified). This option only works on systems |
|
93 that actually have these functions. If you plan on using this feature, you |
3294
|
94 should probably also use @code{--enable-shared} to reduce the size of |
|
95 your @file{.oct} files. |
|
96 |
7091
|
97 @item --without-blas |
|
98 Compile and use the generic BLAS and LAPACK versions included with |
|
99 Octave. By default, configure first looks for BLAS and LAPACK matrix |
|
100 libraries on your system, including optimized BLAS implementations such |
|
101 as the free ATLAS 3.0, as well as vendor-tuned libraries. (The use of |
|
102 an optimized BLAS will generally result in several-times faster matrix |
|
103 operations.) Only use this option if your system has BLAS/LAPACK |
|
104 libraries that cause problems for some reason. You can also use |
|
105 @code{--with-blas=lib} to specify a particular BLAS library |
|
106 @code{-llib} that configure doesn't check for automatically. |
|
107 |
|
108 @item --without-ccolamd |
|
109 Don't use CCOLAMD, disable some sparse matrix functionality. |
|
110 |
|
111 @item --without-colamd |
|
112 Don't use COLAMD, disable some sparse matrix functionality. |
|
113 |
|
114 @item --without-curl |
|
115 Don't use the cURL, disable the @code{urlread} and @code{urlwrite} |
|
116 functions. |
3294
|
117 |
7091
|
118 @item --without-cxsparse |
|
119 Don't use CXSPARSE, disable some sparse matrix functionality. |
|
120 |
|
121 @item --without-umfpack |
|
122 Don't use UMFPACK, disable some sparse matrix functionality. |
|
123 |
|
124 @item --without-fftw |
|
125 Use the included fftpack library instead of the FFTW library. |
3294
|
126 |
7091
|
127 @item --without-glpk |
|
128 Don't use the GLPK library for linear programming. |
|
129 |
|
130 @item --without-hdf5 |
|
131 Don't use the HDF5 library for reading and writing HDF5 files. |
|
132 |
|
133 @item --without-zlib |
|
134 Don't use the zlib library, disable data file compression and support |
|
135 for recent MAT file formats. |
|
136 |
|
137 @item --without-lapack |
3690
|
138 Compile and use the generic BLAS and LAPACK versions included with |
|
139 Octave. By default, configure first looks for BLAS and LAPACK matrix |
|
140 libraries on your system, including optimized BLAS implementations such |
|
141 as the free ATLAS 3.0, as well as vendor-tuned libraries. (The use of |
|
142 an optimized BLAS will generally result in several-times faster matrix |
|
143 operations.) Only use this option if your system has BLAS/LAPACK |
|
144 libraries that cause problems for some reason. You can also use |
3960
|
145 @code{--with-blas=lib} to specify a particular BLAS library |
3690
|
146 @code{-llib} that configure doesn't check for automatically. |
|
147 |
3294
|
148 @item --help |
|
149 Print a summary of the options recognized by the configure script. |
|
150 @end table |
|
151 |
|
152 See the file @file{INSTALL} for more information about the command line |
|
153 options used by configure. That file also contains instructions for |
|
154 compiling in a directory other than where the source is located. |
|
155 |
|
156 @item |
|
157 Run make. |
|
158 |
|
159 You will need a recent version of GNU Make. Modifying Octave's |
|
160 makefiles to work with other make programs is probably not worth |
|
161 your time. We recommend you get and compile GNU Make instead. |
|
162 |
|
163 For plotting, you will need to have gnuplot installed on your system. |
|
164 Gnuplot is a command-driven interactive function plotting program. |
|
165 Gnuplot is copyrighted, but freely distributable. The `gnu' in gnuplot |
|
166 is a coincidence---it is not related to the GNU project or the FSF in |
|
167 any but the most peripheral sense. |
|
168 |
7091
|
169 To compile Octave, you will need a recent version of GNU Make. You will |
|
170 also need a recent version of @code{g++} or other ANSI C++ compiler. You |
|
171 will also need a Fortran 77 compiler or @code{f2c}. If you use |
|
172 @code{f2c}, you will need a script like @code{fort77} that works like a |
|
173 normal Fortran compiler by combining @code{f2c} with your C compiler in |
|
174 a single script. |
3294
|
175 |
|
176 If you plan to modify the parser you will also need GNU @code{bison} and |
|
177 @code{flex}. If you modify the documentation, you will need GNU |
|
178 Texinfo, along with the patch for the @code{makeinfo} program that is |
|
179 distributed with Octave. |
|
180 |
|
181 GNU Make, @code{gcc}, and @code{libstdc++}, @code{gnuplot}, |
|
182 @code{bison}, @code{flex}, and Texinfo are all available from many |
|
183 anonymous ftp archives. The primary site is @url{ftp.gnu.org}, but it |
|
184 is often very busy. A list of sites that mirror the software on |
|
185 @url{ftp.gnu.org} is available by anonymous ftp from |
|
186 @url{ftp://ftp.gnu.org/pub/gnu/GNUinfo/FTP}. |
|
187 |
7091
|
188 You will need about 925 megabytes of disk storage to work with when |
|
189 building Octave from source (considerably less if you don't compile with |
|
190 debugging symbols). To do that, use the command |
3294
|
191 |
|
192 @example |
|
193 make CFLAGS=-O CXXFLAGS=-O LDFLAGS= |
|
194 @end example |
|
195 |
|
196 @noindent |
|
197 instead of just @samp{make}. |
|
198 |
|
199 @item |
|
200 If you encounter errors while compiling Octave, first check the list of |
|
201 known problems below to see if there is a workaround or solution for |
|
202 your problem. If not, |
|
203 @ifclear INSTALLONLY |
|
204 see @ref{Trouble}, |
|
205 @end ifclear |
|
206 @ifset INSTALLONLY |
|
207 see the file BUGS |
|
208 @end ifset |
|
209 for information about how to report bugs. |
|
210 |
|
211 @item |
|
212 Once you have successfully compiled Octave, run @samp{make install}. |
|
213 |
|
214 This will install a copy of octave, its libraries, and its documentation |
|
215 in the destination directory. As distributed, Octave is installed in |
|
216 the following directories. In the table below, @var{prefix} defaults to |
|
217 @file{/usr/local}, @var{version} stands for the current version number |
|
218 of the interpreter, and @var{arch} is the type of computer on which |
|
219 Octave is installed (for example, @samp{i586-unknown-gnu}). |
|
220 |
|
221 @table @file |
|
222 @item @var{prefix}/bin |
|
223 Octave and other binaries that people will want to run directly. |
|
224 |
|
225 @item @var{prefix}/lib |
|
226 Libraries like libcruft.a and liboctave.a. |
|
227 |
|
228 @item @var{prefix}/share |
|
229 Architecture-independent data files. |
|
230 |
|
231 @item @var{prefix}/include/octave |
|
232 Include files distributed with Octave. |
|
233 |
|
234 @item @var{prefix}/man/man1 |
|
235 Unix-style man pages describing Octave. |
|
236 |
|
237 @item @var{prefix}/info |
|
238 Info files describing Octave. |
|
239 |
|
240 @item @var{prefix}/share/octave/@var{version}/m |
|
241 Function files distributed with Octave. This includes the Octave |
|
242 version, so that multiple versions of Octave may be installed at the |
|
243 same time. |
|
244 |
|
245 @item @var{prefix}/lib/octave/@var{version}/exec/@var{arch} |
|
246 Executables to be run by Octave rather than the user. |
|
247 |
|
248 @item @var{prefix}/lib/octave/@var{version}/oct/@var{arch} |
|
249 Object files that will be dynamically loaded. |
|
250 |
|
251 @item @var{prefix}/share/octave/@var{version}/imagelib |
|
252 Image files that are distributed with Octave. |
|
253 @end table |
|
254 @end itemize |
|
255 |
|
256 @menu |
|
257 * Installation Problems:: |
|
258 @end menu |
|
259 |
4167
|
260 @node Installation Problems |
3294
|
261 @appendixsec Installation Problems |
|
262 |
|
263 This section contains a list of problems (and some apparent problems |
|
264 that don't really mean anything is wrong) that may show up during |
|
265 installation of Octave. |
|
266 |
|
267 @itemize @bullet |
|
268 @item |
|
269 On some SCO systems, @code{info} fails to compile if |
|
270 @code{HAVE_TERMIOS_H} is defined int @file{config.h}. Simply removing |
|
271 the definition from @file{info/config.h} should allow it to compile. |
|
272 |
|
273 @item |
|
274 If @code{configure} finds @code{dlopen}, @code{dlsym}, @code{dlclose}, |
|
275 and @code{dlerror}, but not the header file @file{dlfcn.h}, you need to |
|
276 find the source for the header file and install it in the directory |
|
277 @file{usr/include}. This is reportedly a problem with Slackware 3.1. |
|
278 For Linux/GNU systems, the source for @file{dlfcn.h} is in the |
|
279 @code{ldso} package. |
|
280 |
|
281 @item |
|
282 Building @file{.oct} files doesn't work. |
|
283 |
|
284 You should probably have a shared version of @code{libstdc++}. A patch |
|
285 is needed to build shared versions of version 2.7.2 of @code{libstdc++} |
|
286 on the HP-PA architecture. You can find the patch at |
|
287 @url{ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix}. |
|
288 |
|
289 @item |
3464
|
290 On some alpha systems there may be a problem with the @code{libdxml} |
|
291 library, resulting in floating point errors and/or segmentation faults in |
|
292 the linear algebra routines called by Octave. If you encounter such |
|
293 problems, then you should modify the configure script so that |
|
294 @code{SPECIAL_MATH_LIB} is not set to @code{-ldxml}. |
|
295 |
|
296 @item |
3294
|
297 On FreeBSD systems Octave may hang while initializing some internal |
|
298 constants. The fix appears to be to use |
|
299 |
|
300 @example |
|
301 options GPL_MATH_EMULATE |
|
302 @end example |
|
303 |
|
304 @noindent |
|
305 rather than |
|
306 |
|
307 @example |
|
308 options MATH_EMULATE |
|
309 @end example |
|
310 |
|
311 @noindent |
|
312 in the kernel configuration files (typically found in the directory |
|
313 @file{/sys/i386/conf}. After making this change, you'll need to rebuild |
|
314 the kernel, install it, and reboot. |
|
315 |
|
316 @item |
|
317 If you encounter errors like |
|
318 |
6670
|
319 @example |
3294
|
320 @group |
|
321 passing `void (*)()' as argument 2 of |
|
322 `octave_set_signal_handler(int, void (*)(int))' |
|
323 @end group |
6670
|
324 @end example |
3294
|
325 |
|
326 @noindent |
|
327 or |
|
328 |
6670
|
329 @example |
7081
|
330 warning: ANSI C++ prohibits conversion from `(int)' |
|
331 to `(...)' |
6670
|
332 @end example |
3294
|
333 |
|
334 @noindent |
|
335 while compiling @file{sighandlers.cc}, you may need to edit some files |
|
336 in the @code{gcc} include subdirectory to add proper prototypes for functions |
|
337 there. For example, Ultrix 4.2 needs proper declarations for the |
|
338 @code{signal} function and the @code{SIG_IGN} macro in the file |
|
339 @file{signal.h}. |
|
340 |
|
341 On some systems the @code{SIG_IGN} macro is defined to be something like |
|
342 this: |
|
343 |
|
344 @example |
|
345 #define SIG_IGN (void (*)())1 |
|
346 @end example |
|
347 |
|
348 @noindent |
|
349 when it should really be something like: |
|
350 |
|
351 @example |
|
352 #define SIG_IGN (void (*)(int))1 |
|
353 @end example |
|
354 |
|
355 @noindent |
|
356 to match the prototype declaration for the @code{signal} function. This |
|
357 change should also be made for the @code{SIG_DFL} and @code{SIG_ERR} |
|
358 symbols. It may be necessary to change the definitions in |
|
359 @file{sys/signal.h} as well. |
|
360 |
|
361 The @code{gcc} @code{fixincludes} and @code{fixproto} scripts should |
|
362 probably fix these problems when @code{gcc} installs its modified set of |
|
363 header files, but I don't think that's been done yet. |
|
364 |
|
365 @strong{You should not change the files in @file{/usr/include}}. You |
|
366 can find the @code{gcc} include directory tree by running the command |
|
367 |
|
368 @example |
|
369 gcc -print-libgcc-file-name |
|
370 @end example |
|
371 |
|
372 @noindent |
|
373 The directory of @code{gcc} include files normally begins in the same directory |
|
374 that contains the file @file{libgcc.a}. |
|
375 |
|
376 @item |
|
377 Some of the Fortran subroutines may fail to compile with older versions |
|
378 of the Sun Fortran compiler. If you get errors like |
|
379 |
6670
|
380 @example |
3294
|
381 zgemm.f: |
|
382 zgemm: |
|
383 warning: unexpected parent of complex expression subtree |
|
384 zgemm.f, line 245: warning: unexpected parent of complex |
|
385 expression subtree |
|
386 warning: unexpected parent of complex expression subtree |
|
387 zgemm.f, line 304: warning: unexpected parent of complex |
|
388 expression subtree |
|
389 warning: unexpected parent of complex expression subtree |
|
390 zgemm.f, line 327: warning: unexpected parent of complex |
|
391 expression subtree |
|
392 pcc_binval: missing IR_CONV in complex op |
|
393 make[2]: *** [zgemm.o] Error 1 |
6670
|
394 @end example |
3294
|
395 |
|
396 @noindent |
|
397 when compiling the Fortran subroutines in the @file{libcruft} |
|
398 subdirectory, you should either upgrade your compiler or try compiling |
|
399 with optimization turned off. |
|
400 |
|
401 @item |
|
402 On NeXT systems, if you get errors like this: |
|
403 |
|
404 @example |
7081
|
405 /usr/tmp/cc007458.s:unknown:Undefined local |
|
406 symbol LBB7656 |
|
407 /usr/tmp/cc007458.s:unknown:Undefined local |
|
408 symbol LBE7656 |
3294
|
409 @end example |
|
410 |
|
411 @noindent |
|
412 when compiling @file{Array.cc} and @file{Matrix.cc}, try recompiling |
|
413 these files without @code{-g}. |
|
414 |
|
415 @item |
|
416 Some people have reported that calls to shell_cmd and the pager do not |
|
417 work on SunOS systems. This is apparently due to having |
|
418 @code{G_HAVE_SYS_WAIT} defined to be 0 instead of 1 when compiling |
|
419 @code{libg++}. |
|
420 |
|
421 @item |
|
422 On NeXT systems, linking to @file{libsys_s.a} may fail to resolve the |
|
423 following functions |
|
424 |
|
425 @example |
|
426 _tcgetattr |
|
427 _tcsetattr |
|
428 _tcflow |
|
429 @end example |
|
430 |
|
431 @noindent |
|
432 which are part of @file{libposix.a}. Unfortunately, linking Octave with |
|
433 @code{-posix} results in the following undefined symbols. |
|
434 |
|
435 @example |
|
436 .destructors_used |
|
437 .constructors_used |
|
438 _objc_msgSend |
|
439 _NXGetDefaultValue |
|
440 _NXRegisterDefaults |
|
441 .objc_class_name_NXStringTable |
|
442 .objc_class_name_NXBundle |
|
443 @end example |
|
444 |
|
445 One kluge around this problem is to extract @file{termios.o} from |
|
446 @file{libposix.a}, put it in Octave's @file{src} directory, and add it |
|
447 to the list of files to link together in the makefile. Suggestions for |
|
448 better ways to solve this problem are welcome! |
|
449 |
|
450 @item |
|
451 If Octave crashes immediately with a floating point exception, it is |
|
452 likely that it is failing to initialize the IEEE floating point values |
|
453 for infinity and NaN. |
|
454 |
|
455 If your system actually does support IEEE arithmetic, you should be able |
|
456 to fix this problem by modifying the function @code{octave_ieee_init} in |
|
457 the file @file{lo-ieee.cc} to correctly initialize Octave's internal |
|
458 infinity and NaN variables. |
|
459 |
|
460 If your system does not support IEEE arithmetic but Octave's configure |
|
461 script incorrectly determined that it does, you can work around the |
|
462 problem by editing the file @file{config.h} to not define |
|
463 @code{HAVE_ISINF}, @code{HAVE_FINITE}, and @code{HAVE_ISNAN}. |
|
464 |
|
465 In any case, please report this as a bug since it might be possible to |
|
466 modify Octave's configuration script to automatically determine the |
|
467 proper thing to do. |
|
468 |
|
469 @end itemize |