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 |
|
62 @item --with-f2c |
|
63 Use @code{f2c} even if a Fortran compiler is available. |
|
64 |
4838
|
65 @item --with-f77 |
|
66 Use @code{f77} to compile Fortran code. You may also specify the name |
|
67 of the compiler to use as an optional argument. For example, |
|
68 @code{--with-f77=g77} sets the name of the Fortran compiler to |
|
69 @code{g77}. |
3294
|
70 |
|
71 @item --enable-shared |
|
72 Create shared libraries. If you are planning to use |
3690
|
73 @code{--enable-lite-kernel} or the dynamic loading features, you will |
3294
|
74 probably want to use this option. It will make your @file{.oct} files |
|
75 much smaller and on some systems it may be necessary to build shared |
|
76 libraries in order to use dynamically linked functions. |
|
77 |
|
78 You may also want to build a shared version of @code{libstdc++}, if your |
7081
|
79 system doesn't already have one. |
3294
|
80 |
|
81 @item --enable-dl |
|
82 Use @code{dlopen} and friends to make Octave capable of dynamically |
|
83 linking externally compiled functions. This only works on systems that |
|
84 actually have these functions. If you plan on using this feature, you |
|
85 should probably also use @code{--enable-shared} to reduce the size of |
|
86 your @file{.oct} files. |
|
87 |
|
88 @item --enable-shl |
|
89 Use @code{shl_load} and friends to make Octave capable of dynamically |
|
90 linking externally compiled functions. This only works on systems that |
|
91 actually have these functions (only HP-UX systems). If you plan on |
|
92 using this feature, you should probably also use @code{--enable-shared} |
|
93 to reduce the size of your @file{.oct} files. |
|
94 |
|
95 @item --enable-lite-kernel |
|
96 Compile smaller kernel. This currently requires the dynamic linking |
|
97 functions @code{dlopen} or @code{shl_load} and friends so that Octave |
|
98 can load functions at run time that are not loaded at compile time. |
|
99 |
3960
|
100 @item --without-blas |
3690
|
101 Compile and use the generic BLAS and LAPACK versions included with |
|
102 Octave. By default, configure first looks for BLAS and LAPACK matrix |
|
103 libraries on your system, including optimized BLAS implementations such |
|
104 as the free ATLAS 3.0, as well as vendor-tuned libraries. (The use of |
|
105 an optimized BLAS will generally result in several-times faster matrix |
|
106 operations.) Only use this option if your system has BLAS/LAPACK |
|
107 libraries that cause problems for some reason. You can also use |
3960
|
108 @code{--with-blas=lib} to specify a particular BLAS library |
3690
|
109 @code{-llib} that configure doesn't check for automatically. |
|
110 |
3294
|
111 @item --help |
|
112 Print a summary of the options recognized by the configure script. |
|
113 @end table |
|
114 |
|
115 See the file @file{INSTALL} for more information about the command line |
|
116 options used by configure. That file also contains instructions for |
|
117 compiling in a directory other than where the source is located. |
|
118 |
|
119 @item |
|
120 Run make. |
|
121 |
|
122 You will need a recent version of GNU Make. Modifying Octave's |
|
123 makefiles to work with other make programs is probably not worth |
|
124 your time. We recommend you get and compile GNU Make instead. |
|
125 |
|
126 For plotting, you will need to have gnuplot installed on your system. |
|
127 Gnuplot is a command-driven interactive function plotting program. |
|
128 Gnuplot is copyrighted, but freely distributable. The `gnu' in gnuplot |
|
129 is a coincidence---it is not related to the GNU project or the FSF in |
|
130 any but the most peripheral sense. |
|
131 |
|
132 To compile Octave, you will need a recent version of GNU Make. You |
|
133 will also need @code{g++} 2.7.2 or later. Version 2.8.0 or @code{egcs} |
|
134 1.0.x should work. Later versions may work, but C++ is still evolving, |
|
135 so don't be too surprised if you run into some trouble. |
|
136 |
|
137 It is no longer necessary to have @code{libg++}, but you do need to have |
|
138 the GNU implementation of @code{libstdc++}. If you are using @code{g++} |
|
139 2.7.2, @code{libstdc++} is distributed along with @code{libg++}, but for |
|
140 later versions, @code{libstdc++} is distributed separately. For |
|
141 @code{egcs}, @code{libstdc++} is included with the compiler |
|
142 distribution. |
|
143 |
|
144 If you plan to modify the parser you will also need GNU @code{bison} and |
|
145 @code{flex}. If you modify the documentation, you will need GNU |
|
146 Texinfo, along with the patch for the @code{makeinfo} program that is |
|
147 distributed with Octave. |
|
148 |
|
149 GNU Make, @code{gcc}, and @code{libstdc++}, @code{gnuplot}, |
|
150 @code{bison}, @code{flex}, and Texinfo are all available from many |
|
151 anonymous ftp archives. The primary site is @url{ftp.gnu.org}, but it |
|
152 is often very busy. A list of sites that mirror the software on |
|
153 @url{ftp.gnu.org} is available by anonymous ftp from |
|
154 @url{ftp://ftp.gnu.org/pub/gnu/GNUinfo/FTP}. |
|
155 |
|
156 If you don't have a Fortran compiler, or if your Fortran compiler |
|
157 doesn't work like the traditional Unix f77, you will need to have the |
|
158 Fortran to C translator @code{f2c}. You can get @code{f2c} from any |
|
159 number of anonymous ftp archives. The most recent version of @code{f2c} |
|
160 is always available from @url{netlib.att.com}. |
|
161 |
|
162 On an otherwise idle Pentium 133 running Linux, it will take somewhere |
|
163 between 1-1/2 to 3 hours to compile everything, depending on whether you |
|
164 are building shared libraries. You will need about 100 megabytes of disk |
|
165 storage to work with (considerably less if you don't compile with debugging |
|
166 symbols). To do that, use the command |
|
167 |
|
168 @example |
|
169 make CFLAGS=-O CXXFLAGS=-O LDFLAGS= |
|
170 @end example |
|
171 |
|
172 @noindent |
|
173 instead of just @samp{make}. |
|
174 |
|
175 @item |
|
176 If you encounter errors while compiling Octave, first check the list of |
|
177 known problems below to see if there is a workaround or solution for |
|
178 your problem. If not, |
|
179 @ifclear INSTALLONLY |
|
180 see @ref{Trouble}, |
|
181 @end ifclear |
|
182 @ifset INSTALLONLY |
|
183 see the file BUGS |
|
184 @end ifset |
|
185 for information about how to report bugs. |
|
186 |
|
187 @item |
|
188 Once you have successfully compiled Octave, run @samp{make install}. |
|
189 |
|
190 This will install a copy of octave, its libraries, and its documentation |
|
191 in the destination directory. As distributed, Octave is installed in |
|
192 the following directories. In the table below, @var{prefix} defaults to |
|
193 @file{/usr/local}, @var{version} stands for the current version number |
|
194 of the interpreter, and @var{arch} is the type of computer on which |
|
195 Octave is installed (for example, @samp{i586-unknown-gnu}). |
|
196 |
|
197 @table @file |
|
198 @item @var{prefix}/bin |
|
199 Octave and other binaries that people will want to run directly. |
|
200 |
|
201 @item @var{prefix}/lib |
|
202 Libraries like libcruft.a and liboctave.a. |
|
203 |
|
204 @item @var{prefix}/share |
|
205 Architecture-independent data files. |
|
206 |
|
207 @item @var{prefix}/include/octave |
|
208 Include files distributed with Octave. |
|
209 |
|
210 @item @var{prefix}/man/man1 |
|
211 Unix-style man pages describing Octave. |
|
212 |
|
213 @item @var{prefix}/info |
|
214 Info files describing Octave. |
|
215 |
|
216 @item @var{prefix}/share/octave/@var{version}/m |
|
217 Function files distributed with Octave. This includes the Octave |
|
218 version, so that multiple versions of Octave may be installed at the |
|
219 same time. |
|
220 |
|
221 @item @var{prefix}/lib/octave/@var{version}/exec/@var{arch} |
|
222 Executables to be run by Octave rather than the user. |
|
223 |
|
224 @item @var{prefix}/lib/octave/@var{version}/oct/@var{arch} |
|
225 Object files that will be dynamically loaded. |
|
226 |
|
227 @item @var{prefix}/share/octave/@var{version}/imagelib |
|
228 Image files that are distributed with Octave. |
|
229 @end table |
|
230 @end itemize |
|
231 |
|
232 @menu |
|
233 * Installation Problems:: |
|
234 @end menu |
|
235 |
4167
|
236 @node Installation Problems |
3294
|
237 @appendixsec Installation Problems |
|
238 |
|
239 This section contains a list of problems (and some apparent problems |
|
240 that don't really mean anything is wrong) that may show up during |
|
241 installation of Octave. |
|
242 |
|
243 @itemize @bullet |
|
244 @item |
|
245 On some SCO systems, @code{info} fails to compile if |
|
246 @code{HAVE_TERMIOS_H} is defined int @file{config.h}. Simply removing |
|
247 the definition from @file{info/config.h} should allow it to compile. |
|
248 |
|
249 @item |
|
250 If @code{configure} finds @code{dlopen}, @code{dlsym}, @code{dlclose}, |
|
251 and @code{dlerror}, but not the header file @file{dlfcn.h}, you need to |
|
252 find the source for the header file and install it in the directory |
|
253 @file{usr/include}. This is reportedly a problem with Slackware 3.1. |
|
254 For Linux/GNU systems, the source for @file{dlfcn.h} is in the |
|
255 @code{ldso} package. |
|
256 |
|
257 @item |
|
258 Building @file{.oct} files doesn't work. |
|
259 |
|
260 You should probably have a shared version of @code{libstdc++}. A patch |
|
261 is needed to build shared versions of version 2.7.2 of @code{libstdc++} |
|
262 on the HP-PA architecture. You can find the patch at |
|
263 @url{ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix}. |
|
264 |
|
265 @item |
3464
|
266 On some alpha systems there may be a problem with the @code{libdxml} |
|
267 library, resulting in floating point errors and/or segmentation faults in |
|
268 the linear algebra routines called by Octave. If you encounter such |
|
269 problems, then you should modify the configure script so that |
|
270 @code{SPECIAL_MATH_LIB} is not set to @code{-ldxml}. |
|
271 |
|
272 @item |
3294
|
273 On FreeBSD systems Octave may hang while initializing some internal |
|
274 constants. The fix appears to be to use |
|
275 |
|
276 @example |
|
277 options GPL_MATH_EMULATE |
|
278 @end example |
|
279 |
|
280 @noindent |
|
281 rather than |
|
282 |
|
283 @example |
|
284 options MATH_EMULATE |
|
285 @end example |
|
286 |
|
287 @noindent |
|
288 in the kernel configuration files (typically found in the directory |
|
289 @file{/sys/i386/conf}. After making this change, you'll need to rebuild |
|
290 the kernel, install it, and reboot. |
|
291 |
|
292 @item |
|
293 If you encounter errors like |
|
294 |
6670
|
295 @example |
3294
|
296 @group |
|
297 passing `void (*)()' as argument 2 of |
|
298 `octave_set_signal_handler(int, void (*)(int))' |
|
299 @end group |
6670
|
300 @end example |
3294
|
301 |
|
302 @noindent |
|
303 or |
|
304 |
6670
|
305 @example |
7081
|
306 warning: ANSI C++ prohibits conversion from `(int)' |
|
307 to `(...)' |
6670
|
308 @end example |
3294
|
309 |
|
310 @noindent |
|
311 while compiling @file{sighandlers.cc}, you may need to edit some files |
|
312 in the @code{gcc} include subdirectory to add proper prototypes for functions |
|
313 there. For example, Ultrix 4.2 needs proper declarations for the |
|
314 @code{signal} function and the @code{SIG_IGN} macro in the file |
|
315 @file{signal.h}. |
|
316 |
|
317 On some systems the @code{SIG_IGN} macro is defined to be something like |
|
318 this: |
|
319 |
|
320 @example |
|
321 #define SIG_IGN (void (*)())1 |
|
322 @end example |
|
323 |
|
324 @noindent |
|
325 when it should really be something like: |
|
326 |
|
327 @example |
|
328 #define SIG_IGN (void (*)(int))1 |
|
329 @end example |
|
330 |
|
331 @noindent |
|
332 to match the prototype declaration for the @code{signal} function. This |
|
333 change should also be made for the @code{SIG_DFL} and @code{SIG_ERR} |
|
334 symbols. It may be necessary to change the definitions in |
|
335 @file{sys/signal.h} as well. |
|
336 |
|
337 The @code{gcc} @code{fixincludes} and @code{fixproto} scripts should |
|
338 probably fix these problems when @code{gcc} installs its modified set of |
|
339 header files, but I don't think that's been done yet. |
|
340 |
|
341 @strong{You should not change the files in @file{/usr/include}}. You |
|
342 can find the @code{gcc} include directory tree by running the command |
|
343 |
|
344 @example |
|
345 gcc -print-libgcc-file-name |
|
346 @end example |
|
347 |
|
348 @noindent |
|
349 The directory of @code{gcc} include files normally begins in the same directory |
|
350 that contains the file @file{libgcc.a}. |
|
351 |
|
352 @item |
|
353 Some of the Fortran subroutines may fail to compile with older versions |
|
354 of the Sun Fortran compiler. If you get errors like |
|
355 |
6670
|
356 @example |
3294
|
357 zgemm.f: |
|
358 zgemm: |
|
359 warning: unexpected parent of complex expression subtree |
|
360 zgemm.f, line 245: warning: unexpected parent of complex |
|
361 expression subtree |
|
362 warning: unexpected parent of complex expression subtree |
|
363 zgemm.f, line 304: warning: unexpected parent of complex |
|
364 expression subtree |
|
365 warning: unexpected parent of complex expression subtree |
|
366 zgemm.f, line 327: warning: unexpected parent of complex |
|
367 expression subtree |
|
368 pcc_binval: missing IR_CONV in complex op |
|
369 make[2]: *** [zgemm.o] Error 1 |
6670
|
370 @end example |
3294
|
371 |
|
372 @noindent |
|
373 when compiling the Fortran subroutines in the @file{libcruft} |
|
374 subdirectory, you should either upgrade your compiler or try compiling |
|
375 with optimization turned off. |
|
376 |
|
377 @item |
|
378 On NeXT systems, if you get errors like this: |
|
379 |
|
380 @example |
7081
|
381 /usr/tmp/cc007458.s:unknown:Undefined local |
|
382 symbol LBB7656 |
|
383 /usr/tmp/cc007458.s:unknown:Undefined local |
|
384 symbol LBE7656 |
3294
|
385 @end example |
|
386 |
|
387 @noindent |
|
388 when compiling @file{Array.cc} and @file{Matrix.cc}, try recompiling |
|
389 these files without @code{-g}. |
|
390 |
|
391 @item |
|
392 Some people have reported that calls to shell_cmd and the pager do not |
|
393 work on SunOS systems. This is apparently due to having |
|
394 @code{G_HAVE_SYS_WAIT} defined to be 0 instead of 1 when compiling |
|
395 @code{libg++}. |
|
396 |
|
397 @item |
|
398 On NeXT systems, linking to @file{libsys_s.a} may fail to resolve the |
|
399 following functions |
|
400 |
|
401 @example |
|
402 _tcgetattr |
|
403 _tcsetattr |
|
404 _tcflow |
|
405 @end example |
|
406 |
|
407 @noindent |
|
408 which are part of @file{libposix.a}. Unfortunately, linking Octave with |
|
409 @code{-posix} results in the following undefined symbols. |
|
410 |
|
411 @example |
|
412 .destructors_used |
|
413 .constructors_used |
|
414 _objc_msgSend |
|
415 _NXGetDefaultValue |
|
416 _NXRegisterDefaults |
|
417 .objc_class_name_NXStringTable |
|
418 .objc_class_name_NXBundle |
|
419 @end example |
|
420 |
|
421 One kluge around this problem is to extract @file{termios.o} from |
|
422 @file{libposix.a}, put it in Octave's @file{src} directory, and add it |
|
423 to the list of files to link together in the makefile. Suggestions for |
|
424 better ways to solve this problem are welcome! |
|
425 |
|
426 @item |
|
427 If Octave crashes immediately with a floating point exception, it is |
|
428 likely that it is failing to initialize the IEEE floating point values |
|
429 for infinity and NaN. |
|
430 |
|
431 If your system actually does support IEEE arithmetic, you should be able |
|
432 to fix this problem by modifying the function @code{octave_ieee_init} in |
|
433 the file @file{lo-ieee.cc} to correctly initialize Octave's internal |
|
434 infinity and NaN variables. |
|
435 |
|
436 If your system does not support IEEE arithmetic but Octave's configure |
|
437 script incorrectly determined that it does, you can work around the |
|
438 problem by editing the file @file{config.h} to not define |
|
439 @code{HAVE_ISINF}, @code{HAVE_FINITE}, and @code{HAVE_ISNAN}. |
|
440 |
|
441 In any case, please report this as a bug since it might be possible to |
|
442 modify Octave's configuration script to automatically determine the |
|
443 proper thing to do. |
|
444 |
|
445 @end itemize |