Mercurial > octave-nkf
annotate doc/faq/Octave-FAQ.texi @ 8215:518789a0539d
FAQ entry about split development packages in distributions
author | Thomas Weber <thomas.weber.mail@gmail.com> |
---|---|
date | Tue, 14 Oct 2008 14:34:56 -0400 |
parents | de8b07e95d1b |
children | 242756f065f0 |
rev | line source |
---|---|
7018 | 1 % Copyright (C) 1997, 1998, 1999, 2001, 2003, 2004, 2005, 2007 John W. Eaton |
2 % | |
3 % This file is part of Octave. | |
4 % | |
5 % Octave is free software; you can redistribute it and/or modify it | |
6 % under the terms of the GNU General Public License as published by the | |
7 % Free Software Foundation; either version 3 of the License, or (at | |
8 % your option) any later version. | |
9 % | |
10 % Octave is distributed in the hope that it will be useful, but WITHOUT | |
11 % ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
12 % FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
13 % for more details. | |
14 % | |
15 % You should have received a copy of the GNU General Public License | |
16 % along with Octave; see the file COPYING. If not, see | |
17 % <http://www.gnu.org/licenses/>. | |
18 | |
2866 | 19 \input texinfo.tex @c -*-texinfo-*- |
20 | |
3030 | 21 @setfilename Octave-FAQ.info |
2866 | 22 @settitle Frequently asked questions about Octave (with answers) |
23 | |
24 @setchapternewpage off | |
5099 | 25 @direntry |
6584 | 26 * Octave-FAQ: (Octave-FAQ). Frequently asked questions about Octave |
5099 | 27 @end direntry |
2866 | 28 @titlepage |
29 @title Octave FAQ | |
30 @subtitle Frequently asked questions about Octave | |
8128 | 31 @subtitle September 2008 |
2866 | 32 @sp 1 |
6900 | 33 @author John W. Eaton and David Bateman |
2866 | 34 @page |
35 @end titlepage | |
36 | |
5423 | 37 @ifnottex |
4830 | 38 @node Top |
2866 | 39 @top |
40 @unnumbered Preface | |
41 @cindex FAQ for Octave, latest version | |
5423 | 42 @end ifnottex |
2866 | 43 |
44 This is a list of frequently asked questions (FAQ) for Octave users. | |
45 | |
6584 | 46 We are always looking for new questions (@emph{with} answers), better |
47 answers, or both. Please send suggestions to @email{bug@@octave.org}. | |
48 If you have general questions about Octave, or need help for something | |
49 that is not covered by the Octave manual or the FAQ, please use the | |
50 @email{help@@octave.org} mailing list. | |
2866 | 51 |
52 This FAQ is intended to supplement, not replace, the Octave manual. | |
6584 | 53 Before posting a question to the @email{help@@octave.org} mailing list, |
54 you should first check to see if the topic is covered in the manual. | |
2866 | 55 |
56 @menu | |
6583 | 57 * What is Octave?:: |
58 * How can I cite Octave?:: | |
8128 | 59 * Series 3.0.N:: |
6583 | 60 * Octave Features:: |
61 * Learning more about Octave:: | |
62 * Getting Octave:: | |
63 * Installation:: | |
2866 | 64 * Common problems:: |
6584 | 65 * How do I ...?:: |
6583 | 66 * MATLAB compatibility:: |
2866 | 67 * Index:: |
68 @end menu | |
69 | |
4830 | 70 @node What is Octave? |
2866 | 71 @chapter What is Octave? |
72 | |
73 Octave is a high-level interactive language, primarily intended for | |
74 numerical computations that is mostly compatible with | |
75 @sc{Matlab}.@footnote{@sc{Matlab} is a registered trademark of The MathWorks, | |
6583 | 76 Inc.} |
2866 | 77 |
6583 | 78 Octave can do arithmetic for real, complex or integer-valued scalars |
79 and matrices, solve sets of nonlinear algebraic equations, integrate | |
80 functions over finite and infinite intervals, and integrate systems of | |
81 ordinary differential and differential-algebraic equations. | |
2866 | 82 |
83 Octave uses the GNU readline library to handle reading and editing | |
84 input. By default, the line editing commands are similar to the | |
85 cursor movement commands used by GNU Emacs, and a vi-style line | |
86 editing interface is also available. At the end of each session, the | |
87 command history is saved, so that commands entered during previous | |
88 sessions are not lost. | |
89 | |
6879 | 90 The Octave distribution includes a 590+ page Texinfo manual. Access |
2866 | 91 to the complete text of the manual is available via the help command |
6583 | 92 @c really, the *complete* text? |
2866 | 93 at the Octave prompt. |
94 | |
6583 | 95 @menu |
96 * Who develops Octave?:: | |
6584 | 97 * Why GNU Octave?:: |
6583 | 98 * What version should I use?:: |
99 * On what platforms does Octave run?:: | |
100 @end menu | |
101 | |
102 @node Who develops Octave? | |
103 @section Who develops Octave? | |
104 | |
6584 | 105 Discussions about writing the software that would eventually become |
106 Octave started in about 1988 with James B. Rawlings and John W. Eaton at | |
107 the University of Texas. John W. Eaton was the original author of | |
108 Octave, starting full-time development in February 1992. He is still | |
109 the primary maintainer. The community | |
110 of users/developers has in addition contributed some code and fuels the | |
111 discussion on the mailing lists @email{help@@octave.org} (user forum), | |
112 @email{bug@@octave.org} (bug reports), @email{maintainers@@octave.org} | |
113 (development issues), and @email{octave-dev@@lists.sourceforge.net} (all | |
114 things related to the Octave Forge repository of user-contributed | |
115 functions). | |
6583 | 116 |
6584 | 117 @node Why GNU Octave? |
118 @section Why GNU Octave? | |
6583 | 119 |
6584 | 120 The GNU Project was launched in 1984 to develop a complete Unix-like |
121 operating system which is free software: the GNU system. | |
122 | |
123 GNU is a recursive acronym for ``GNU's Not Unix''; it is pronounced | |
124 guh-noo, approximately like canoe. | |
6583 | 125 |
6584 | 126 The Free Software Foundation (FSF) is the principal organizational |
127 sponsor of the GNU Project. | |
128 | |
129 Octave became GNU Octave in 1997 (beginning with version 2.0.6). This | |
130 meant agreeing to consider Octave a part of the GNU Project and support | |
131 the efforts of the FSF. However, Octave is not and has never been | |
132 developed by the FSF. | |
133 | |
134 For more information about the GNU project, see @url{www.gnu.org}. | |
6583 | 135 |
136 @cindex FSF [Free Software Foundation] | |
137 @cindex GNU [GNU's not unix] | |
138 | |
139 @node What version should I use? | |
140 @section What version should I use? | |
141 | |
142 In general, you will find the latest version on | |
6584 | 143 @url{http://www.octave.org/download.html}. It is |
6583 | 144 recommended to use the ``testing'' version of octave for general use, |
145 and the ``development'' version if you want the latest features. | |
146 | |
147 A list of user-visible changes since the last release is available in | |
148 the file @file{NEWS}. The file @file{ChangeLog} in the source | |
149 distribution contains a more detailed record of changes made since the | |
150 last release. | |
151 | |
152 @node On what platforms does Octave run? | |
153 @section On what platforms does Octave run? | |
154 | |
6584 | 155 Octave runs on various Unices---at least Linux and Solaris, Mac OS X, |
156 Windows and anything you can compile it on. Binary distributions exist | |
6583 | 157 at least for Debian, Suse, Fedora and RedHat Linuxes (Intel and AMD |
158 CPUs, at least), for Mac Os X and Windows' 98, 2000 and XP. | |
159 | |
2866 | 160 Two and three dimensional plotting is fully supported using gnuplot. |
161 | |
162 The underlying numerical solvers are currently standard Fortran ones | |
163 like Lapack, Linpack, Odepack, the Blas, etc., packaged in a library | |
164 of C++ classes. If possible, the Fortran subroutines are compiled | |
165 with the system's Fortran compiler, and called directly from the C++ | |
166 functions. If that's not possible, you can still compile Octave if | |
167 you have the free Fortran to C translator f2c. | |
168 | |
169 Octave is also free software; you can redistribute it and/or modify it | |
170 under the terms of the GNU General Public License as published by the | |
171 Free Software Foundation. | |
172 | |
4830 | 173 @node How can I cite Octave? |
174 @chapter How can I cite Octave? | |
4831 | 175 |
176 Pointing to @url{http://www.octave.org} is good, because that gives | |
177 people a direct way to find out more. If citation of a URL is not | |
178 allowed by a publisher, or if you also want to point to a traditional | |
179 reference, then you can cite the Octave manual: | |
4830 | 180 |
181 @example | |
182 @group | |
6584 | 183 @@BOOK@{eaton:2002, |
184 author = "John W. Eaton", | |
185 title = "GNU Octave Manual", | |
186 publisher = "Network Theory Limited", | |
187 year = "2002", | |
188 isbn = "0-9541617-2-6" | |
189 @} | |
4830 | 190 @end group |
191 @end example | |
192 | |
8128 | 193 @node Series 3.0.N |
194 @chapter What's new in version series 3.0.N and 3.1.N of Octave | |
6583 | 195 |
8128 | 196 The 3.0.N series has enough new features to justify a major version |
197 number change. The 3.0.N series brings | |
6583 | 198 |
199 @itemize @bullet | |
200 | |
201 @item integer types | |
202 | |
203 @item fixed point arithmetic | |
204 | |
205 @item sparse matrices | |
206 | |
207 @item Linear programming code based on GLPK | |
208 | |
209 @item 64-bit compilation support | |
210 | |
211 @item gzipped files and stream and consequently support of matlab v7 files | |
2866 | 212 |
6583 | 213 @item better support for both msvc and mingw |
214 | |
7116 | 215 @item a fully compatible MEX interface |
6583 | 216 |
6606 | 217 @item many many other minor features and compatibility changes |
6583 | 218 |
219 @end itemize | |
220 | |
6735 | 221 Here are some features that have been around since 2.1.N |
6583 | 222 |
223 @itemize @bullet | |
2866 | 224 |
6583 | 225 @item NDarrays |
226 | |
227 @item cells | |
228 | |
229 @end itemize | |
230 | |
8128 | 231 The 3.1.N series is the current development release and will become a |
232 3.2.N release in the future. This series brings the new features | |
233 | |
234 @itemize | |
235 @item OpenGL backend | |
236 | |
237 An experimental OpenGL graphics backend to replace the gnuplot | |
238 | |
239 @item Object Orient Programming | |
240 | |
241 @item Block comments | |
242 | |
243 @item imwrite and imread | |
244 | |
245 The functions are based on the GraphicsMagick library. | |
246 | |
247 @item Lazy transpose | |
248 | |
249 Special treatment in the parser of things like "a' * b", where the | |
250 transpose is never explicitly formed but a flag is rather passed to the | |
251 underlying LAPACK code. | |
252 | |
253 @item Single precision type | |
254 @end itemize | |
255 | |
256 | |
4830 | 257 @node Octave Features |
2866 | 258 @chapter What features are unique to Octave? |
259 | |
260 @menu | |
6583 | 261 * Functions defined on the command-line:: |
262 * Comments with #:: | |
263 * Strings delimitted by double quotes ":: | |
264 * Line continuation by backslash:: | |
265 * Informative block closing:: | |
266 * Coherent syntax:: | |
267 * Exclamation mark as not operator:: | |
2866 | 268 * Increment and decrement operators:: |
269 * Unwind-protect:: | |
6583 | 270 * Built-in ODE and DAE solvers:: |
2866 | 271 @end menu |
272 | |
8128 | 273 This section refers to Matlab R2008b and Octave 2.1.51. |
2866 | 274 |
6583 | 275 @node Functions defined on the command-line |
276 @section Functions defined on the command-line | |
2866 | 277 |
6583 | 278 Functions can be defined by entering code on the command line, a |
6584 | 279 feature not supported by the other leading brand. For example, you may |
6583 | 280 type: |
2866 | 281 |
282 @example | |
283 @group | |
6583 | 284 octave:1> function s = hello_string (to_who) |
285 > ## Say hello | |
286 > if nargin<1, to_who = "World"; end | |
287 > s = ["Hello ",\ | |
288 > to_who]; | |
289 > endfunction | |
290 octave:2> hello_string ("Moon") | |
291 ans = Hello Moon | |
2866 | 292 @end group |
293 @end example | |
294 | |
6583 | 295 @node Comments with # |
296 @section Comments with # | |
297 | |
6584 | 298 The pound character, @samp{#}, may be used to start comments, in addition |
299 to @samp{%}. See the previous example. The major advantage of this is | |
300 that as @samp{#} is also a comment character for unix script files, any | |
301 file that starts with a string like @samp{#! /usr/bin/octave -q} will be | |
302 treated as an octave script and be executed by octave. | |
2866 | 303 |
6583 | 304 @node Strings delimitted by double quotes " |
305 @section Strings delimitted by double quotes " | |
6584 | 306 The double quote, @samp{"}, may be used to delimit strings, in addition to |
307 the single quote @samp{'}. See the previous example. Also, double-quoted | |
308 strings include backslash interpretation (like C++, C, and Perl) while | |
309 single quoted are uninterpreted (like Matlab and Perl). | |
6583 | 310 |
311 @node Line continuation by backslash | |
312 @section Line continuation by backslash | |
313 | |
6584 | 314 Lines can be continued with a backslash, @samp{\}, in addition to three |
315 points @samp{@dots{}}. See the previous example. | |
6583 | 316 |
317 @node Informative block closing | |
318 @section Informative block closing | |
319 | |
6584 | 320 You may close @code{function}, @code{for}, @code{while}, @code{if}, |
321 @dots{} blocks with @code{endfunction}, @code{endfor}, @code{endwhile}, | |
322 @dots{} keywords in addition to using @code{end}. As with Matlab, the | |
323 @code{end} (or @code{endfunction}) keyword that marks the end of a | |
324 function defined in a @file{.m} file is optional. | |
2866 | 325 |
6583 | 326 @node Coherent syntax |
327 @section Coherent syntax | |
328 | |
329 Indexing other things than variables is possible, as in: | |
330 @example | |
331 @group | |
332 octave:1> [3 1 4 1 5 9](3) | |
333 ans = 4 | |
334 octave:2> cos([0 pi pi/4 7])(3) | |
335 ans = 0.70711 | |
336 @end group | |
337 @end example | |
338 | |
339 @node Exclamation mark as not operator | |
340 @section Exclamation mark as not operator | |
341 | |
342 The exclamation mark '!' (aka ``Bang!'') is a negation operator, just | |
343 like the tilde '~': | |
2866 | 344 |
345 @example | |
346 @group | |
6583 | 347 octave:1> if ! strcmp (program_name, "octave"), |
348 > "It's an error" | |
349 > else | |
350 > "It works!" | |
351 > end | |
352 ans = It works! | |
2866 | 353 @end group |
354 @end example | |
355 | |
4830 | 356 @node Increment and decrement operators |
2866 | 357 @section Increment and decrement operators |
358 | |
359 @cindex Increment operators | |
360 @cindex Decrement operators | |
361 @cindex Operators, increment | |
362 @cindex Operators, decrement | |
363 | |
6584 | 364 If you like the @samp{++}, @samp{+=} etc operators, rejoice! |
2866 | 365 Octave includes the C-like increment and decrement operators @samp{++} |
6583 | 366 and @samp{--} in both their prefix and postfix forms, in addition to |
367 @samp{+=}, @samp{-=}, @samp{*=}, @samp{/=}, @samp{^=}, @samp{.*=}, | |
368 @samp{./=}, and @samp{.^=}. | |
2866 | 369 |
370 For example, to pre-increment the variable @var{x}, you would write | |
371 @code{++@var{x}}. This would add one to @var{x} and then return the new | |
372 value of @var{x} as the result of the expression. It is exactly the | |
373 same as the expression @code{@var{x} = @var{x} + 1}. | |
374 | |
6584 | 375 To post-increment a variable @var{x}, you would write @code{x++}. |
2866 | 376 This adds one to the variable @var{x}, but returns the value that |
377 @var{x} had prior to incrementing it. For example, if @var{x} is equal | |
6584 | 378 to 2, the result of the expression @code{x++} is 2, and the new |
2866 | 379 value of @var{x} is 3. |
380 | |
381 For matrix and vector arguments, the increment and decrement operators | |
382 work on each element of the operand. | |
383 | |
384 | |
4830 | 385 @node Unwind-protect |
2866 | 386 @section Unwind-protect |
387 | |
388 @cindex Unwind-protect | |
389 | |
390 Octave supports a limited form of exception handling modelled after the | |
391 unwind-protect form of Lisp. The general form of an | |
392 @code{unwind_protect} block looks like this: | |
393 | |
394 @example | |
395 @group | |
396 unwind_protect | |
397 @var{body} | |
398 unwind_protect_cleanup | |
399 @var{cleanup} | |
400 end_unwind_protect | |
401 @end group | |
402 @end example | |
403 | |
404 @noindent | |
405 Where @var{body} and @var{cleanup} are both optional and may contain any | |
406 Octave expressions or commands. The statements in @var{cleanup} are | |
407 guaranteed to be executed regardless of how control exits @var{body}. | |
408 | |
409 The @code{unwind_protect} statement is often used to reliably restore | |
410 the values of global variables that need to be temporarily changed. | |
411 | |
8128 | 412 Matlab can be made to do something similar with their @code{OnCleanUp} |
413 function that was introduced in 2008a. | |
414 | |
4830 | 415 @node Built-in ODE and DAE solvers |
2866 | 416 @section Built-in ODE and DAE solvers |
417 | |
418 @cindex DASSL | |
419 @cindex LSODE | |
420 | |
421 Octave includes LSODE and DASSL for solving systems of stiff ordinary | |
422 differential and differential-algebraic equations. These functions are | |
423 built in to the interpreter. | |
424 | |
6583 | 425 @node Learning more about Octave |
426 @chapter What documentation exists for Octave? | |
427 | |
428 @menu | |
429 * Documentation:: | |
430 * Getting additional help:: | |
431 * User community:: | |
432 * Bug reports:: | |
433 @end menu | |
434 | |
435 | |
4830 | 436 @node Documentation |
6583 | 437 @section What documentation exists for Octave? |
2866 | 438 |
439 @cindex Octave, documentation | |
440 | |
6879 | 441 The Octave distribution includes a 590+ page manual that is also |
2866 | 442 distributed under the terms of the GNU GPL. |
6583 | 443 It is available on the web at |
444 @url{http://www.octave.org/docs.html} and you will also | |
445 find there instructions on how to order a paper version. | |
446 | |
447 The complete text of the Octave manual is also available using the GNU | |
448 Info system via the GNU Emacs, info, or xinfo programs, or by using | |
449 the @samp{help -i} command to start the GNU info browser directly from | |
450 the Octave prompt. | |
451 | |
452 If you have problems using this documentation, or find that some topic | |
453 is not adequately explained, indexed, or cross-referenced, please send | |
6584 | 454 a bug report to @email{bug@@octave.org}. |
6583 | 455 |
2866 | 456 |
6583 | 457 @node Getting additional help |
458 @section Getting additional help | |
459 | |
460 @cindex Additional help | |
461 @cindex Mailing lists, help-octave | |
462 | |
6584 | 463 If you can't find an answer to your question, the |
464 @email{help@@octave.org} mailing list is available for questions related | |
465 to using, installing, and porting Octave that are not adequately | |
466 answered by the Octave manual or by this document. | |
6583 | 467 |
468 @node User community | |
469 @section User community | |
470 | |
6584 | 471 To subscribe to the list, go to @url{www.octave.org/archive.html} and |
472 follow the link to the subscription page for the list. | |
2866 | 473 |
6653 | 474 @strong{Please do not} send requests to be added or removed from the |
6583 | 475 mailing list, or other administrative trivia to the list itself. |
476 | |
477 An archive of old postings to the help-octave mailing list is maintained | |
478 on @url{http://www.octave.org/archive.html}. | |
479 | |
6584 | 480 You will also find some user advice and code spread over the web. Good |
6583 | 481 starting points are the Octave Wiki @url{http://wiki.octave.org} and |
7483
fb66330b2608
don't special case SH_LD for FreeBSD and OpenBSD
John W. Eaton <jwe@octave.org>
parents:
7116
diff
changeset
|
482 Octave-Forge @url{http://octave.sourceforge.net} |
6583 | 483 |
484 @node Bug reports | |
485 @section I think I have found a bug in Octave. | |
486 | |
487 @cindex Bug in Octave, newly found | |
488 | |
489 ``I think I have found a bug in Octave, but I'm not sure. How do I know, | |
490 and who should I tell?'' | |
2866 | 491 |
6583 | 492 @cindex Manual, for Octave |
493 | |
494 First, see the section on bugs and bug reports in the Octave manual. | |
495 When you report a bug, make sure to describe the type of computer you | |
496 are using, the version of the operating system it is running, and the | |
497 version of Octave that you are using. Also provide enough code so that | |
498 the Octave maintainers can duplicate your bug. | |
499 | |
500 If you have Octave working at all, the easiest way to do this is to use | |
501 the Octave function @code{bug_report}. When you execute this function, | |
502 Octave will prompt you for a subject and then invoke the editor on a | |
503 file that already contains all the configuration information. When you | |
504 exit the editor, Octave will mail the bug report for you (in a unix-like | |
505 operating system). | |
506 | |
507 @cindex Octave bug report | |
508 @cindex Mailing lists, bug-octave | |
509 | |
510 If for some reason you cannot use Octave's @code{bug_report} function, | |
6584 | 511 mail your bug report to @email{bug@@octave.org}. Your message needs to |
6583 | 512 include enough information to allow the maintainers of Octave to fix the |
513 bug. Please read the section on bugs and bug reports in the Octave | |
514 manual for a list of things that should be included in every bug report. | |
515 | |
2866 | 516 |
4830 | 517 @node Getting Octave |
6583 | 518 @chapter Getting Octave |
2866 | 519 |
520 @menu | |
6583 | 521 * Source code:: |
522 * Pre-compiled binary packages:: | |
523 * Octave for other platforms:: | |
2866 | 524 @end menu |
525 | |
6583 | 526 @node Source code |
527 @section Source code | |
528 @cindex Source code | |
2866 | 529 |
6583 | 530 Source code is available on the Octave development site, where you are |
531 sure to get the latest version. | |
2866 | 532 |
6583 | 533 @itemize @bullet |
534 @item @url{http://www.octave.org/download.html} | |
535 @item @url{ftp://ftp.octave.org/pub/octave/} | |
536 @end itemize | |
2866 | 537 |
6583 | 538 Since Octave is distrubted under the terms of the GPL, you can get |
539 Octave from a friend who has a copy, by anonymous FTP, or by ordering | |
540 a tape or CD-ROM from the Free Software Foundation (FSF). | |
2866 | 541 |
6583 | 542 @node Pre-compiled binary packages |
543 @section Pre-compiled binary packages | |
544 @cindex Pre-compiled binary packages | |
545 @cindex Binaries | |
2866 | 546 |
6584 | 547 The Octave project does not distribute binary packages, but other |
548 projects do. For an up-to-date listing of packagers, see: | |
2866 | 549 |
6583 | 550 @itemize @bullet |
551 @item @url{http://www.octave.org/download.html} | |
552 @item @url{http://wiki.octave.org/wiki.pl?CategoryInstall} | |
553 @end itemize | |
2866 | 554 |
6583 | 555 As of today, Octave binaries are available at least on Debian, RedHat, |
556 Suse and Fedora Linuxes, Mac OS X, Windows' 98, 2000 and XP. | |
2866 | 557 |
4830 | 558 @node Octave for other platforms |
2866 | 559 @section How do I get a copy of Octave for (some other platform)? |
560 | |
561 @cindex VMS support | |
562 @cindex VAX | |
563 @cindex MS-DOS support | |
3154 | 564 @cindex Windows support |
2866 | 565 @cindex DJGPP |
566 @cindex EMX | |
567 @cindex OS/2 support | |
568 | |
6879 | 569 Octave currently runs on Unix-like systems, Mac OS X, and Windows. |
570 It should be possible to make Octave work on other systems as well. | |
571 If you are interested in porting Octave to other systems, please contact | |
6584 | 572 @email{bug@@octave.org}. |
2866 | 573 |
6583 | 574 @c @menu |
575 @c * Octave for Unix:: | |
576 @c * Octave for other platforms:: | |
577 @c * latest versions:: | |
578 @c @end menu | |
2866 | 579 |
6583 | 580 @c @cindex Octave, ordering |
581 @c @cindex Octave, getting a copy | |
2866 | 582 |
4830 | 583 @node Installation |
2866 | 584 @chapter Installation Issues and Problems |
585 | |
586 @cindex Octave, building | |
587 | |
8128 | 588 Octave 3.2 require approximately 800MB of disk storage to unpack |
6584 | 589 and compile from source (considerably less if you don't compile with |
590 debugging symbols). Once installed, Octave requires approximately 200MB | |
591 of disk space (again, considerably less if you don't compile with | |
592 debugging symbols). | |
2866 | 593 |
594 @menu | |
595 * What else do I need?:: | |
596 * Other C++ compilers?:: | |
597 @end menu | |
598 | |
4830 | 599 @node What else do I need? |
2866 | 600 @section What else do I need? |
601 | |
602 @cindex GNU gcc | |
603 @cindex GNU g++ | |
604 @cindex libg++ | |
605 @cindex GNU Make | |
606 @cindex Flex | |
607 @cindex GNU Bison | |
608 | |
3154 | 609 To compile Octave, you will need a recent version of GNU Make. You |
6584 | 610 will also need GCC 3.3 or later, although GCC 4.1 or later is |
611 recommended. | |
3154 | 612 |
6584 | 613 @strong{You must have GNU Make to compile octave}. Octave's Makefiles |
3154 | 614 use features of GNU Make that are not present in other versions of make. |
615 GNU Make is very portable and easy to install. | |
2866 | 616 |
4830 | 617 @node Other C++ compilers? |
2866 | 618 @section Can I compile Octave with another C++ compiler? |
619 | |
6584 | 620 Yes, but development is done primarily with GCC, so you may hit some |
621 incompatibilities. Octave is intended to be portable to any standard | |
622 conforming compiler. If you have difficulties that you think are bugs, | |
623 please report them to the @email{bug@@octave.org} mailing list, or ask | |
624 for help on the @email{help@@octave.org} mailing list. | |
2866 | 625 |
4830 | 626 @node Common problems |
2866 | 627 @chapter Common problems |
628 | |
629 This list is probably far too short. Feel free to suggest additional | |
630 questions (preferably with answers!) | |
631 | |
632 @itemize @bullet | |
633 @item | |
634 Octave takes a long time to find symbols. | |
635 | |
6606 | 636 Octave uses the @code{genpath} function to recursively add directories |
6900 | 637 to the list of directories searched for function files. Check the list |
6606 | 638 of directories with the @code{path} command. If the path list is very |
639 long check your use of the @code{genpath} function. | |
6735 | 640 |
641 @item | |
6900 | 642 When plotting Octave occasionally gives me errors like @samp{gnuplot> 9 0.735604 |
643 line 26317: invalid command}. | |
6735 | 644 |
645 There is a known bug in gnuplot 4.2 that can cause an off by one error | |
646 while piping data to gnuplot. The relevant gnuplot bug report can be | |
647 found at @url{http://sourceforge.net/tracker/index.php?func=detail&aid=1716556&group_id=2055&atid=102055} | |
648 | |
649 If you have obtained your copy of Octave from a distribution please file | |
650 a bug report requesting that the fix reported in the above bug report be | |
651 included. | |
8215
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
652 |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
653 @item |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
654 I cannot install a package. Octave complains about a missing @code{mkoctfile}. |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
655 |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
656 Most distributions split Octave into several packages. The script |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
657 @code{mkoctfile} is then part of a separate package: |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
658 @itemize @minus |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
659 @item |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
660 Debian/Ubuntu |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
661 |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
662 @code{aptitude install octave3.0-headers} |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
663 |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
664 @item |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
665 Fedora |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
666 |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
667 @code{yum install octave-devel} |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
668 |
518789a0539d
FAQ entry about split development packages in distributions
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
8130
diff
changeset
|
669 @end itemize |
2866 | 670 @end itemize |
671 | |
6584 | 672 @node How do I ...? |
673 @chapter How do I ...? | |
2866 | 674 |
6583 | 675 @menu |
676 * How do I set the number of displayed decimals?:: | |
677 @end menu | |
2866 | 678 |
6583 | 679 @cindex Tips and tricks |
6584 | 680 @cindex How do I @dots{} ? |
2866 | 681 |
6583 | 682 @node How do I set the number of displayed decimals? |
683 @section How do I set the number of displayed decimals? | |
2866 | 684 |
685 @example | |
686 @group | |
6583 | 687 octave:1> format long |
688 octave:2> pi | |
689 pi = 3.14159265358979 | |
690 octave:3> format short | |
691 octave:4> pi | |
692 pi = 3.1416 | |
2866 | 693 @end group |
694 @end example | |
695 | |
4830 | 696 @node MATLAB compatibility |
2866 | 697 @chapter Porting programs from @sc{Matlab} to Octave |
698 | |
699 @cindex @sc{Matlab} compatibility | |
700 @cindex Compatibility with @sc{Matlab} | |
701 | |
6612 | 702 People often ask |
703 | |
2866 | 704 ``I wrote some code for @sc{Matlab}, and I want to get it running under |
705 Octave. Is there anything I should watch out for?'' | |
706 | |
6612 | 707 or alternatively |
708 | |
709 ``I wrote some code in Octave, and want to share it with @sc{Matlab} | |
6900 | 710 users. Is there anything I should watch out for?'' |
6612 | 711 |
6900 | 712 which is not quite the same thing. There are still a number of |
6612 | 713 differences between Octave and @sc{Matlab}, however in general |
714 differences between the two are considered as bugs. Octave might | |
715 consider that the bug is in @sc{Matlab} and do nothing about it, but | |
716 generally functionality is almost identical. If you find a difference | |
717 between Octave behavior and @sc{Matlab}, then you should send a | |
718 description of this difference (with code illustrating the difference, | |
719 if possible) to @email{bug@@octave.org}. | |
720 | |
721 Furthermore, Octave adds a few syntactical extensions to Matlab that | |
722 might cause some issues when exchanging files between Matlab and Octave | |
723 users. As both Octave and @sc{Matlab} are under constant development the | |
724 information in this section is subject to change at anytime. | |
725 | |
726 You should also look at the page | |
727 @url{http://octave.sourceforge.net/packages.html} and | |
728 @url{http://octave.sourceforge.net/doc/} that has a function reference | |
729 that is up to date. You can use this function reference to see the | |
730 number of octave function that are available and their @sc{Matlab} | |
731 compatibility. | |
732 | |
8128 | 733 The major differences between Octave 3.2.N and @sc{Matlab} R2008a are: |
6612 | 734 |
735 @itemize @bullet | |
736 @item Nested Functions | |
737 | |
6900 | 738 Octave doesn't yet have nested functions. That is |
2866 | 739 |
6612 | 740 @example |
741 @group | |
742 function y = foo (x) | |
6900 | 743 y = bar(x) |
744 function y = bar (x) | |
745 y = @dots{}; | |
746 end | |
6612 | 747 end |
748 @end group | |
749 @end example | |
750 | |
751 There was discussion in Octave of having these even prior to @sc{Matlab}, | |
752 and the decision was made not to have these in Octave at the time for | |
6900 | 753 compatibility. The above written with sub-functions functions would be |
6612 | 754 |
755 @example | |
756 @group | |
757 function y = foo (x) | |
758 y = bar(x) | |
759 end | |
760 function y = bar (x) | |
761 y = @dots{}; | |
762 end | |
763 @end group | |
764 @end example | |
765 | |
766 Now that @sc{Matlab} has recently introduced nested functions, Octave will | |
6900 | 767 probably have them soon as well. Until then nested functions in Octave |
6612 | 768 are treated as sub-functions with the same scoping rules as |
769 sub-functions. | |
770 | |
771 The authors of Octave consider the nested function scoping rules of | |
772 Matlab to be more problems than they are worth as they introduce | |
773 diffiult to find bugs as inadvertantly modifying a variable in a | |
774 nested function that is also used in the parent is particularly easy. | |
775 | |
776 @item Differences in core syntax | |
777 There a few core @sc{Matlab} syntaxes that are not accepted by Octave, | |
778 these being | |
779 | |
780 @itemize @bullet | |
2866 | 781 @item |
6612 | 782 Some limitations on the use of function handles. The major difference is |
6879 | 783 related to nested function scoping rules (as above) and their use with |
6612 | 784 function handles. |
2866 | 785 |
786 @item | |
6612 | 787 Some limitations of variable argument lists on the LHS of an expression, |
788 though the most common types are accepted. | |
789 | |
2866 | 790 @item |
8128 | 791 @sc{Matlab} classdef object oriented programming is not yet supportted, |
792 though work is underway and when development more on to Octave 3.3 this | |
793 will be included in teh development tree. | |
6612 | 794 @end itemize |
795 | |
796 @item Differences in core functions | |
797 A large number of the @sc{Matlab} core functions (ie those that are in | |
798 the core and not a toolbox) are implemented, and certainly all of the | |
799 commonly used ones. There are a few functions that aren't implemented, | |
6879 | 800 for example @code{condest} or to do with specific missing Octave functionality |
6612 | 801 (gui, dll, java, activex, dde, web, and serial functions). Some of the |
802 core functions have limitations that aren't in the @sc{Matlab} | |
6900 | 803 version. For example the @code{sprandn} function can not force a |
6735 | 804 particular condition number for the matrix like @sc{Matlab} can. |
6612 | 805 |
806 @item Just-In-Time compiler | |
807 @sc{Matlab} includes a "Just-In-Time" compiler. This compiler allows the | |
808 acceleration of for-loops in @sc{Matlab} to almost native performance with | |
809 certain restrictions. The JIT must know the return type of all functions | |
810 called in the loops and so you can't include user functions in the loop | |
6900 | 811 of JIT optimized loops. Octave doesn't have a JIT and so to some might |
812 seem slower than @sc{Matlab}. For this reason you must vectorize your code as | |
813 much as possible. The MathWorks themselves have a good document | |
814 discussing vectorization at | |
6612 | 815 @url{http://www.mathworks.com/support/tech-notes/1100/1109.html}. |
816 | |
817 @item Compiler | |
818 On a related point, there is no Octave compiler, and so you can't | |
819 convert your Octave code into a binary for additional speed or | |
6900 | 820 distribution. There is an example of how to do this at |
6612 | 821 @url{http://www.stud.tu-ilmenau.de/~rueckn/}, but this is a very early |
822 example code and would need lots of work to complete it. | |
823 | |
824 @item Graphic Handles | |
825 Up to Octave 2.9.9 there was no support for graphic handles in Octave | |
8128 | 826 itself. In the 3.2.N versions of Octave the support for graphics |
827 handles is converging towards full compatibility. The @code{patch} | |
828 function is currently limited to 2-D patches, due to an underlying | |
829 limitation in gnuplot. | |
6612 | 830 |
831 @item GUI | |
6900 | 832 There are no @sc{Matlab} compatible GUI functions. There are a number of |
833 bindings from Octave to Tcl/Tk, Vtk and zenity included in the | |
834 Octave Forge project (@url{http://octave.sourceforge.net}) for example | |
6612 | 835 that can be used for a GUI, but these are not @sc{Matlab} |
7116 | 836 compatible. Work on a matlab compatible GUI is in an alpha stage in the |
6879 | 837 JHandles package (@url{http://octave.sourceforge.net/jhandles/index.html}). |
838 This might be an issue if you intend to exchange Octave code with | |
839 @sc{Matlab} users. | |
6612 | 840 |
841 @item Simulink | |
842 Octave itself includes no Simulink support. Typically the simulink | |
843 models lag research and are less flexible, so shouldn't really be used | |
6900 | 844 in a research environment. However, some @sc{Matlab} users that try to |
845 use Octave complain about this lack. There is a similar package to | |
846 simulink for the Octave and R projects available at | |
847 @url{http://www.scicraft.org/} | |
6612 | 848 |
849 @item Mex-Files | |
850 Octave includes an API to the matlab MEX interface. However, as MEX is | |
6900 | 851 an API to the internals of @sc{Matlab} and the internals of Octave |
852 differ from @sc{Matlab}, there is necessarily a manipulation of the data | |
853 to convert from a MEX interface to the Octave equivalent. This is | |
854 notable for all complex matrices, where @sc{Matlab} stores complex | |
855 arrays as real and imaginary parts, whereas Octave respects the C99/C++ | |
856 standards of co-locating the real/imag parts in memory. Also due to the | |
857 way @sc{Matlab} allows access to the arrays passed through a pointer, | |
858 the MEX interface might require copies of arrays (even non complex | |
8128 | 859 ones). |
6612 | 860 |
861 @item Block comments | |
8128 | 862 Block comments denoted by "%@{" and "%@}" markers are supported by |
863 Octave with some limitations. The major limitation is that block | |
8130
de8b07e95d1b
Octave-FAQ.texi: fix markup
John W. Eaton <jwe@octave.org>
parents:
8128
diff
changeset
|
864 comments are not supported with [] or @{@}. |
6612 | 865 |
866 @item Mat-File format | |
867 There are some differences in the mat v5 file format accepted by | |
868 Octave. @sc{Matlab} recently introduced the "-V7.3" save option which is | |
6900 | 869 an HDF5 format which is particularly useful for 64-bit platforms where |
6612 | 870 the standard matlab format can not correctly save variables.. Octave |
6900 | 871 accepts HDF5 files, but is not yet compatible with the "-v7.3" versions |
6612 | 872 produced by @sc{Matlab}. |
873 | |
8128 | 874 Although Octave can load inline abd function handles saved by |
875 @sc{Matlab}, it can not yet save them. | |
6612 | 876 |
877 Finally, Some multi-byte unicode characters aren't yet treated in | |
878 mat-files. | |
879 | |
880 @item Profiler | |
881 Octave doesn't have a profiler. Though there is a patch for a flat | |
882 profiler, that might become a real profiler sometime in the future. see | |
883 the thread | |
884 | |
885 @url{http://www.cae.wisc.edu/pipermail/octave-maintainers/2007-January/001685.html} | |
886 | |
887 for more details | |
888 | |
889 @item Toolboxes | |
890 Octave is a community project and so the toolboxes that exist are | |
6900 | 891 donated by those interested in them through the Octave Forge website |
6612 | 892 (@url{http://octave.sourceforge.net}). These might be lacking in certain |
893 functionality relative to the @sc{Matlab} toolboxes, and might not | |
894 exactly duplicate the matlab functionality or interface. | |
895 | |
896 @item Short-circuit & and | operators | |
6900 | 897 The @code{&} and @code{|} operators in @sc{Matlab} short-circuit when |
898 included in an if statemant and not otherwise. In Octave only the | |
899 @code{&&} and @code{||} short circuit. Note that this means that | |
6612 | 900 |
901 @example | |
902 @group | |
903 if (a | b) | |
904 @dots{} | |
905 end | |
906 @end group | |
907 @end example | |
908 | |
909 and | |
910 | |
911 @example | |
912 @group | |
913 t = a | b; | |
914 if t | |
915 @dots{} | |
916 end | |
917 @end group | |
918 @end example | |
919 | |
6900 | 920 @noindent |
6612 | 921 are different in @sc{Matlab}. This is really a @sc{Matlab} bug, but |
922 there is too much code out there that relies on this behavior to change | |
923 it. Prefer the || and && operators in if statements if possible. | |
2866 | 924 |
6612 | 925 Note that the difference is also significant when either argument is a |
926 function with side effects or if the first argument is a scalar and the | |
927 second argument is an empty matrix. For example, note the difference | |
928 between | |
929 | |
930 @example | |
931 @group | |
932 t = 1 | []; ## results in [], so... | |
933 if (t) 1, end ## in if ([]), this is false. | |
934 @end group | |
935 @end example | |
936 | |
937 and | |
938 | |
939 @example | |
940 if (1 | []) 1, end ## short circuits so condition is true. | |
941 @end example | |
942 | |
943 Another case that is documented in the @sc{Matlab} manuals is that | |
944 | |
945 @example | |
946 @group | |
947 t = [1, 1] | [1, 2, 3]; ## error | |
948 if ([1, 1] | [1, 2, 3]) 1, end ## OK | |
949 @end group | |
950 @end example | |
951 | |
952 Also @sc{Matlab} requires the operands of && and || to be scalar values but | |
953 Octave does not (it just applies the rule that for an operand to be | |
954 considered true, every element of the object must be nonzero or | |
955 logically true). | |
956 | |
957 Finally, note the inconsistence of thinking of the condition of an if | |
958 statement as being equivalent to @code{all(X(:))} when @var{X} is a | |
959 matrix. This is true for all cases EXCEPT empty matrices: | |
960 | |
961 @example | |
962 @group | |
963 if ([0, 1]) == if (all ([0, 1])) ==> i.e., condition is false. | |
964 if ([1, 1]) == if (all ([1, 1])) ==> i.e., condition is true. | |
965 @end group | |
966 @end example | |
967 | |
968 However, | |
969 | |
970 @example | |
971 if ([]) != if (all ([])) | |
972 @end example | |
973 | |
6900 | 974 because @code{samp ([]) == 1} (because, despite the name, it is really |
6612 | 975 returning true if none of the elements of the matrix are zero, and since |
976 there are no elements, well, none of them are zero). But, somewhere | |
977 along the line, someone decided that if @code{([])} should be false. | |
978 Mathworks probably thought it just looks wrong to have @code{[]} be true | |
979 in this context even if you can use logical gymnastics to convince | |
980 yourself that "all" the elements of a matrix that doesn't actually have | |
981 any elements are nonzero. Octave however duplicates this behavior for if | |
982 statements containing empty matrices. | |
983 | |
984 @item Octave extensions | |
985 The extensions in Octave over @sc{Matlab} syntax are | |
986 very useful, but might cause issues when sharing with @sc{Matlab} users. | |
987 A list of the major extensions that should be avoided to be compatible | |
988 with @sc{Matlab} are | |
989 | |
990 @itemize @bullet | |
991 @item | |
6900 | 992 Comments in octave can be marked with @samp{#}. This allows POSIX |
993 systems to have the first line as @samp{#! octave -q} and mark the script | |
6653 | 994 itself executable. @sc{Matlab} doesn't have this feature due to the |
6900 | 995 absence of comments starting with @samp{#}". |
2866 | 996 |
6612 | 997 @item |
998 Code blocks like if, for, while, etc can be terminated with block | |
999 specific terminations like "endif". @sc{Matlab} doesn't have this and | |
1000 all blocks must be terminated with "end" | |
1001 | |
1002 @item | |
1003 Octave has a lisp like unwind_protect block that allows blocks of | |
1004 code that terminate in an error to ensure that the variables that | |
1005 are touched are restored. You can do something similar with | |
6900 | 1006 @code{try}/@code{catch} combined with @samp{rethrow (lasterror ())} in |
1007 @sc{Matlab}, however rethrow and lasterror are only available in Octave 2.9.10 and later. | |
6612 | 1008 |
6900 | 1009 Note that using @code{try}/@code{catch} combined with @samp{rethrow |
1010 (lasterror ())} can not guarentee that global variables will be | |
1011 correctly reset, as it won't catch user interrupts with Ctrl-C. For | |
1012 example | |
6612 | 1013 |
1014 @example | |
1015 @group | |
1016 global a | |
1017 a = 1; | |
1018 try | |
1019 _a = a; | |
1020 a = 2 | |
1021 while true | |
1022 end | |
1023 catch | |
1024 fprintf ('caught interrupt\n'); | |
1025 a = _a; | |
1026 rethrow (lasterror()); | |
1027 end | |
1028 @end group | |
1029 @end example | |
1030 | |
1031 @noindent | |
1032 compared to | |
1033 | |
1034 @example | |
1035 @group | |
1036 global a | |
1037 a = 1; | |
1038 unwind_protect | |
1039 _a = a; | |
1040 a = 2 | |
1041 while true | |
1042 end | |
1043 unwind_protect_cleanup | |
1044 fprintf ('caught interrupt\n'); | |
1045 a = _a; | |
1046 end | |
1047 @end group | |
1048 @end example | |
1049 | |
1050 Typing Ctrl-C in the first case returns the user directly to the | |
6879 | 1051 prompt, and the variable "a" is not reset to the saved value. In the |
6900 | 1052 second case the variable "a" is reset correctly. Therefore @sc{Matlab} |
6612 | 1053 gives no save way of temporarily changing global variables. |
1054 | |
1055 @item | |
1056 Indexing can be applied to all objects in Octave and not just | |
1057 variable. Therefore @code{sin(x)(1:10);} for example is perfectly valid | |
1058 in Octave but not @sc{Matlab}. To do the same in @sc{Matlab} you must do | |
1059 @code{y = sin(x); y = y([1:10]);} | |
1060 | |
1061 @item | |
6900 | 1062 Octave has the operators "++", "--", "-=", "+=", "*=", etc. As |
6612 | 1063 @sc{Matlab} doesn't, if you are sharing code these should be avoided. |
1064 | |
1065 @item | |
6900 | 1066 Character strings in Octave can be denoted with double or single |
1067 quotes. There is a subtle difference between the two in that escaped | |
1068 characters like @code{\n} (newline), @code{\t} (tab), etc are | |
1069 interpreted in double quoted strings but not single quoted strings. This | |
1070 difference is important on Windows platforms where the "\" character is | |
1071 used in path names, and so single quoted strings should be used in | |
1072 paths. @sc{Matlab} doesn't have double quoted strings and so they should | |
1073 be avoided if the code will be transfered to a @sc{Matlab} user. | |
6612 | 1074 @end itemize |
1075 | |
1076 @end itemize | |
2866 | 1077 |
4830 | 1078 @node Index |
2866 | 1079 @appendix Concept Index |
1080 | |
1081 @printindex cp | |
1082 | |
1083 @page | |
1084 @contents | |
1085 @bye |