# HG changeset patch # User John W. Eaton # Date 1325802870 18000 # Node ID 87f06b9990bbc6bc583df47f854f4df22d1fd082 # Parent f1ff06a1d73a8bebfa01f9a521b1322eb3f4b679 doc: improve documentation for building Octave * install.txi, contrib.txi: Improve documentation for building Octave, including listing dependencies. diff -r f1ff06a1d73a -r 87f06b9990bb doc/interpreter/contrib.txi --- a/doc/interpreter/contrib.txi Thu Jan 05 10:34:04 2012 -0500 +++ b/doc/interpreter/contrib.txi Thu Jan 05 17:34:30 2012 -0500 @@ -1,3 +1,4 @@ +@c Copyright (C) 2012 John W. Eaton @c Copyright (C) 2008-2012 Jaroslav Hajek @c @c This file is part of Octave. @@ -25,6 +26,8 @@ @menu * How to Contribute:: +* Building the Development Sources:: +* Basics of Generating a Changeset:: * General Guidelines:: * Octave Sources (m-files):: * C++ Sources:: @@ -41,6 +44,86 @@ (@url{http://octave.sf.net}). Note that the Octave project is inherently more conservative and follows narrower rules. +@node Building the Development Sources +@section Building the Development Sources + +In addition to all the tools (both optional and required) that are +listed in @ref{Build Dependencies} you will need: + +@table @asis +@item Mercurial +Distributed version control system (@url{http://mercurial.selenic.com}). +Octave's sources are stored in a Mercurial archive. + +@item Git +Distributed version control system (@url{http://git-scm.com}). The +gnulib sources that Octave depends on are stored in a Git archive. +@end table + +Once you have the required tools installed, you can build Octave by +doing + +@itemize @bullet +@item +Check out a copy of the Octave sources: +@example +hg clone http://hg.savannah.gnu.org/hgweb/octave +@end example + +@item +Change to the top-level directory of the newly checked out sources: +@example +cd octave +@end example + +@item +Generate the necessary configuration files: +@example +./autogen.sh +@end example + +@item +Create a build directory and change to it: +@example +mkdir build +cd build +@end example +By using a separate build directory, you will keep the source directory +clean and it will be easy to completely remove all files generated by +the build. You can also have parallel build trees for different +purposes that all share the same sources. For example, one build tree +may be configured to disable compiler optimization in order to allow for +easier debugging while another may be configured to test building with +other specialized compiler flags. + +@item +Run Octave's configure script from the build directory: +@example +../configure +@end example + +@item +Run make in the build directory: +@example +make +@end example +@end itemize + +Once the build is finished, you will see a message like the following: + +@example +@group +Octave successfully built. Now choose from the following: + + ./run-octave - to run in place to test before installing + make check - to run the tests + make install - to install (PREFIX=...) +@end group +@end example + +@node Basics of Generating a Changeset +@section Basics of Generating a Changeset + The preferable form of contribution is creating a Mercurial changeset and sending it via e-mail to the octave-maintainers mailing list. Mercurial is the source code management system currently used to develop diff -r f1ff06a1d73a -r 87f06b9990bb doc/interpreter/install.txi --- a/doc/interpreter/install.txi Thu Jan 05 10:34:04 2012 -0500 +++ b/doc/interpreter/install.txi Thu Jan 05 17:34:30 2012 -0500 @@ -44,7 +44,188 @@ @cindex installing Octave The procedure for installing Octave from source on a Unix-like system is -described below. Building on other platforms will follow similar steps. +described below. Building on other platforms will follow similar +steps. Note that this description applies to Octave releases. Building +the development sources from the Mercurial archive requires additional +steps as described in @ref{Building the Development Sources}. + +@menu +* Build Dependencies:: +* Running Configure and Make:: +* Compiling Octave with 64-bit Indexing:: +* Installation Problems:: +@end menu + +@node Build Dependencies +@section Build Dependencies + +Octave is a fairly large program with many build dependencies. You may +be able to find pre-packaged versions of the dependencies distributed as +part of your system, or you may have to build some or all of them +yourself. + +The following tools are required: + +@table @asis +@item C++, C, and Fortran compilers +The Octave sources are primarily written in C++, but some portions are +also written in C and Fortran. The Octave sources are intended to be +portable. Recent versions of the GNU compiler collection (GCC) should +work (@url{http://gcc.gnu.org}). If you use GCC, you should avoid +mixing versions. For example, be sure that you are not using the +obsolete @code{g77} Fortran compiler with modern versions of @code{gcc} +and @code{g++}. + +@item GNU Make +Tool for building software (@url{http://www.gnu.org/software/make}). +Octave's build system requires GNU Make. Other versions of Make will +not work. Fortunately, GNU Make is highly portable and easy to install. + +@item AWK, sed, and other Unix utilities +Basic Unix system utilities are required for building Octave. All will +be available with any modern Unix system and also on Windows with either +Cygwin or MinGW and MSYS. +@end table + +Additionally, the following tools may be needed: + +@table @asis +@item Bison +Parser generator (@url{http://www.gnu.org/software/bison}). +You will need Bison if you modify the @code{oct-parse.yy} source file or +if you delete the files that are generated from it. + +@item Flex +Lexer analyzer (@url{http://www.gnu.org/software/flex}). You will need +Flex if you modify the @code{lex.ll} source file or if you delete the +files that are generated from it. + +@item Autoconf +Package for software configuration +(@url{http://www.gnu.org/software/autoconf}). Autoconf is required if +you modify Octave's @code{configure.ac} file or other files that it +requires. + +@item Automake +Package for Makefile generation +(@url{http://www.gnu.org/software/automake}). Automake is required if +you modify Octave's @code{Makefile.am} files or other files that they +depend on. + +@item Libtool +Package for building software libraries +(@url{http://www.gnu.org/software/libtool}). Libtool is required by +Automake. +@end table + +The following external packages are required: + +@table @asis +@item PCRE +The Perl Compatible Reular Expression library (http://www.pcre.org). +@item BLAS +Basic Linear Algebra Subroutine library +(@url{http://www.netlib.org/blas}). Accelerated BLAS libraries such as +ATLAS (@url{http://math-atlas.sourceforge.net}) are recommeded for +better performance. +@item LAPACK +Linear Algebra Package (@url{http://www.netlib.org/lapack}). +@end table + +The following external package is optional but strongly recommended: + +@table @asis +@item GNU Readline +Command-line editing library (@url{www.gnu.org/s/readline}). +@end table + +If you wish to build Octave without GNU readline installed, you must use +the @code{--disable-readline} option when running the configure script. + +The following external software packages are optional but recommended: + +@table @asis +@item ARPACK +Library for the solution of large-scale eigenvalue problems +(@url{http://forge.scilab.org/index.php/p/arpack-ng}). ARPACK is +required to provide the functions @code{eigs} and @code{svds}. + +@item cURL +Library for transferring data with URL syntax +(@url{http://curl.haxx.se}). cURL is required to provide the +@code{urlread} and @code{urlwrite} functions and the @code{ftp} class. + +@item FFTW3 +Library for computing discrete Fourier transforms +(@url{http://www.fftw.org}). FFTW3 is used to provide better +performance for functions that compute discrete Fourier transforms +(@code{fft}, @code{ifft}, @code{fft2}, etc.) + +@item FLTK +Portable GUI toolkit (@url{http://www.fltk.org}). FLTK is currently +used to provide windows for Octave's OpenGL-based graphics functions. + +@item fontconfig +Library for configuring and customizing font access +(@url{http://www.freedesktop.org/wiki/Software/fontconfig}). Fontconfig +is used to manage fonts for Octave's OpenGL-based graphics functions. + +@item FreeType +Portable font engine (@url{http://www.freetype.org}). FreeType is used +to peform font rendering Octave's OpenGL-based graphics functions. + +@item GLPK +GNU Linear Programming Kit (@url{http://www.gnu.org/software/glpk}). +GPLK is required for the function @code{glpk}. + +@item gnuplot +Interactive graphics program (@url{http://www.gnuplot.info}). gnuplot +is currently the default graphics renderer for Octave. + +@item GraphicsMagick++ +Image processing library (@url{http://www.graphicsmagick.org}). +GraphicsMagick++ is used to provide the @code{imread} and @code{imwrite} +functions. + +@item HDF5 +Library for manipulating portable data files +(@url{http://www.hdfgroup.org/HDF5}). HDF5 is required for Octave's +@code{save} and @code{load} commands to write and read HDF data files. + +@item OpenGL +API for portable 2D and 3D graphics (@url{http://www.opengl.org}). An +OpenGL implementation is required to provide Octave's OpenGL-based +graphics functions. Octave's OpenGL-based graphics functions usually +outperform the gnuplot-based graphics functions because plot data can be +rendered directly instead of sending data and commands to gnuplot for +interpretation and rendering. + +@item Qhull +Computational geometry library (@url{http://www.qhull.org}). Qhull is +required to provide the functions @code{convhull}, @code{convhulln}, +@code{delaunay}, @code{delaunay3}, @code{delaunayn}, @code{voronoi}, and +@code{voronoin}. + +@item QRUPDATE +QR factorization updating library +(@url{http://sourceforge.net/projects/qrupdate}). QRUPDATE is used to +provide improved performance for the functions @code{qrdelete}, +@code{qrinsert}, @code{qrshift}, and @code{qrupdate}. + +@item SuiteSparse +Sparse matrix factorization library +(@url{http://www.cise.ufl.edu/research/sparse/SuiteSparse}). +SuiteSparse is required to provide sparse matrix factorizations and +solution of linear equations for sparse systems. + +@item zlib +Data compression library (@url{http://zlib.net}). The zlib library is +required for Octave's @code{load} and @code{save} commands to handle +compressed data, including @sc{Matlab} v5 MAT files. +@end table + +@node Running Configure and Make +@section Running Configure and Make @itemize @bullet @item @@ -314,13 +495,8 @@ @end table @end itemize -@menu -* Compiling Octave with 64-bit Indexing:: -* Installation Problems:: -@end menu - @node Compiling Octave with 64-bit Indexing -@appendixsec Compiling Octave with 64-bit Indexing +@section Compiling Octave with 64-bit Indexing Note: the following only applies to systems that have 64-bit pointers. Configuring Octave with @option{--enable-64} cannot magically make a @@ -585,7 +761,7 @@ @end itemize @node Installation Problems -@appendixsec Installation Problems +@section Installation Problems This section contains a list of problems (and some apparent problems that don't really mean anything is wrong) that may show up during diff -r f1ff06a1d73a -r 87f06b9990bb doc/interpreter/octave.texi --- a/doc/interpreter/octave.texi Thu Jan 05 10:34:04 2012 -0500 +++ b/doc/interpreter/octave.texi Thu Jan 05 17:34:30 2012 -0500 @@ -860,6 +860,8 @@ Contributing Guidelines * How to Contribute:: +* Building the Development Sources:: +* Basics of Generating a Changeset:: * General Guidelines:: * Octave Sources (m-files):: * C++ Sources:: @@ -880,6 +882,9 @@ Installation +* Build Dependencies:: +* Running Configure and Make:: +* Compiling Octave with 64-bit Indexing:: * Installation Problems:: Emacs Octave Support