@c Copyright (C) 1996-2011 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@c The text of this file appears in the file INSTALL in the Octave
@c distribution, as well as in the Octave manual.

@ifclear INSTALLONLY
@node Installation
@appendix Installing Octave
@end ifclear

@ifset INSTALLONLY

This file documents the installation of Octave.

Octave is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation.

@strong{Note:} This file is automatically generated from
@file{doc/interpreter/install.txi} in the Octave sources.  To update
the documentation make changes to the .txi source file rather than this
derived file.

@node Installation
@chapter Installing Octave
@end ifset

@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.

@itemize @bullet
@item
Run the shell script @file{configure}.  This will determine the features
your system has (or doesn't have) and create a file named
@file{Makefile} from each of the files named @file{Makefile.in}.

Here is a summary of the configure options that are most frequently used
when building Octave:

@table @code
@item --help
Print a summary of the options recognized by the configure script.

@item --prefix=@var{prefix}
Install Octave in subdirectories below @var{prefix}.  The default value
of @var{prefix} is @file{/usr/local}.

@item --srcdir=@var{dir}
Look for Octave sources in the directory @var{dir}.

@item --enable-64
This is an @strong{experimental} option to enable Octave to use 64-bit
integers for array dimensions and indexing on 64-bit platforms.  You
probably don't want to use this option unless you know what you are
doing.  @xref{Compiling Octave with 64-bit Indexing}, for more details
about building Octave with this option.

@item --enable-bounds-check
Enable bounds checking for indexing operators in the internal array
classes.  This option is primarily used for debugging Octave.  Building
Octave with this option has a negative impact on performance and is not
recommended for general use.

@item --disable-docs
Disable building all forms of the documentation (Info, PDF, HTML).  The
default is to build documentation, but your system will need functioning
Texinfo and Tex installs for this to succeed.

@item --enable-float-truncate
This option allows for truncation of intermediate floating point results
in calculations.  It is only necessary for certain platforms.

@item --enable-readline
Use the readline library to provide for editing of the command line in
terminal environments.  This option is on by default.

@item --enable-shared
Create shared libraries (this is the default).  If you are planning to
use the dynamic loading features, you will probably want to use this
option.  It will make your @file{.oct} files much smaller and on some
systems it may be necessary to build shared libraries in order to use
dynamically linked functions.

You may also want to build a shared version of @code{libstdc++}, if your
system doesn't already have one.

@item --enable-dl
Use @code{dlopen} and friends to make Octave capable of dynamically
linking externally compiled functions (this is the default if
@option{--enable-shared} is specified).  This option only works on
systems that actually have these functions.  If you plan on using this
feature, you should probably also use @option{--enable-shared} to reduce
the size of your @file{.oct} files.

@item --with-blas=<lib>
By default, configure looks for the best @sc{blas} matrix libraries on
your system, including optimized implementations such as the free ATLAS
3.0, as well as vendor-tuned libraries.  (The use of an optimized
@sc{blas} will generally result in several-times faster matrix
operations.)  Use this option to specify a particular @sc{blas} library
that Octave should use.

@item --with-lapack=<lib>
By default, configure looks for the best @sc{lapack} matrix libraries on
your system, including optimized implementations such as the free ATLAS
3.0, as well as vendor-tuned libraries.  (The use of an optimized
@sc{lapack} will generally result in several-times faster matrix
operations.)  Use this option to specify a particular @sc{lapack}
library that Octave should use.

@item --with-magick=<lib>
Select the library to use for image I/O@.  The two possible values are
"GraphicsMagick" (default) or "ImageMagick".

@item --with-sepchar=<char>
Use <char> as the path separation character.  This option can help when
running Octave on non-Unix systems.

@item --without-amd
Don't use @sc{amd}, disable some sparse matrix functionality.

@item --without-camd
Don't use @sc{camd}, disable some sparse matrix functionality.

@item --without-colamd
Don't use @sc{colamd}, disable some sparse matrix functionality.

@item --without-ccolamd
Don't use @sc{ccolamd}, disable some sparse matrix functionality.

@item --without-cholmod
Don't use @sc{cholmod}, disable some sparse matrix functionality.

@item --without-curl
Don't use the cURL library, disable the ftp objects, @code{urlread} and
@code{urlwrite} functions.

@item --without-cxsparse
Don't use @sc{cxsparse}, disable some sparse matrix functionality.

@item --without-fftw3
Use the included @sc{fftpack} library for computing Fast Fourier
Transforms instead of the @sc{fftw3} library.

@item --without-fftw3f
Use the included @sc{fftpack} library for computing Fast Fourier
Transforms instead of the @sc{fftw3} library when operating on single
precision (float) values.

@item --without-glpk
Don't use the @sc{glpk} library for linear programming.

@item --without-hdf5
Don't use the @sc{hdf5} library, disable reading and writing of
@sc{hdf5} files.

@item --without-opengl
Don't use OpenGL, disable native graphics toolkit for plotting.  You
will need @code{gnuplot} installed in order to make plots.

@item --without-qhull
Don't use Qhull, disable @code{delaunay}, @code{convhull}, and
related functions.

@item --without-qrupdate
Don't use @sc{qrupdate}, disable QR and Cholesky update functions.

@item --without-umfpack
Don't use @sc{umfpack}, disable some sparse matrix functionality.

@item --without-zlib
Don't use the zlib library, disable data file compression and support
for recent MAT file formats.

@item --without-framework-carbon
Don't use framework Carbon headers, libraries, or specific source code
even if the configure test succeeds (the default is to use Carbon
framework if available).  This is a platform specific configure option
for Mac systems.

@item --without-framework-opengl
Don't use framework OpenGL headers, libraries, or specific source code
even if the configure test succeeds.  If this option is given then
OpenGL headers and libraries in standard system locations are tested
(the default value is @option{--with-framework-opengl}).  This is a
platform specific configure option for Mac systems.

@end table

See the file @file{INSTALL} for more general information about the 
command line options used by configure.  That file also contains 
instructions for compiling in a directory other than the one where
the source is located.

@item
Run make.

You will need a recent version of GNU Make as Octave relies on certain
features not generally available in all versions of make.  Modifying
Octave's makefiles to work with other make programs is probably not
worth your time; instead, we simply recommend installing GNU Make.

There are currently two options for plotting in Octave: (1) the external
program gnuplot, or (2) the internal graphics engine using OpenGL and
FLTK@.  Gnuplot is a command-driven interactive function plotting
program.  Gnuplot is copyrighted, but freely distributable.  As of
Octave release 3.4, gnuplot is the default option for plotting.  But,
the internal graphics engine is nearly 100% compatibile, certainly for
most ordinary plots, and users are encouraged to test it.  It is
anticipated that the internal engine will become the default option at
the next major release of Octave.

To compile Octave, you will need a recent version of @code{g++} or other
ANSI C++ compiler.  In addition, you will need a Fortran 77 compiler or
@code{f2c}.  If you use @code{f2c}, you will need a script like
@code{fort77} that works like a normal Fortran compiler by combining
@code{f2c} with your C compiler in a single script.

If you plan to modify the parser you will also need GNU @code{bison} and
@code{flex}.  If you modify the documentation, you will need GNU
Texinfo.

GNU Make, @code{gcc} (and @code{libstdc++}), @code{gnuplot},
@code{bison}, @code{flex}, and Texinfo are all available from many
anonymous ftp archives.  The primary site is @url{ftp.gnu.org}, but it
is often very busy.  A list of sites that mirror the software on
@url{ftp.gnu.org} is available by anonymous ftp from
@url{ftp://ftp.gnu.org/pub/gnu/GNUinfo/FTP}.

Octave requires approximately 1.4 GB of disk storage to unpack and
compile from source (significantly less, 400 MB, if you don't compile
with debugging symbols).  To compile without debugging symbols try the
command

@example
make CFLAGS=-O CXXFLAGS=-O LDFLAGS=
@end example

@noindent
instead of just @command{make}.

@item
If you encounter errors while compiling Octave, first check the list of
known problems below to see if there is a workaround or solution for
your problem.  If not,
@ifclear INSTALLONLY
see @ref{Trouble},
@end ifclear
@ifset INSTALLONLY
see the file BUGS
@end ifset
for information about how to report bugs.

@item
Once you have successfully compiled Octave, run @code{make install}.

This will install a copy of Octave, its libraries, and its documentation
in the destination directory.  As distributed, Octave is installed in
the following directories.  In the table below, @var{prefix} defaults to
@file{/usr/local}, @var{version} stands for the current version number
of the interpreter, and @var{arch} is the type of computer on which
Octave is installed (for example, @samp{i586-unknown-gnu}).

@table @file
@item @var{prefix}/bin
Octave and other binaries that people will want to run directly.

@item @var{prefix}/lib/octave-@var{version}
Libraries like libcruft.a and liboctave.a.

@item @var{prefix}/octave-@var{version}/include/octave
Include files distributed with Octave.

@item @var{prefix}/share
Architecture-independent data files.

@item @var{prefix}/share/man/man1
Unix-style man pages describing Octave.

@item @var{prefix}/share/info
Info files describing Octave.

@item @var{prefix}/share/octave/@var{version}/m
Function files distributed with Octave.  This includes the Octave
version, so that multiple versions of Octave may be installed at the
same time.

@item @var{prefix}/libexec/octave/@var{version}/exec/@var{arch}
Executables to be run by Octave rather than the user.

@item @var{prefix}/lib/octave/@var{version}/oct/@var{arch}
Object files that will be dynamically loaded.

@item @var{prefix}/share/octave/@var{version}/imagelib
Image files that are distributed with Octave.
@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

Note: the following only applies to systems that have 64-bit pointers.
Configuring Octave with @option{--enable-64} cannot magically make a
32-bit system have a 64-bit address space.

On 64-bit systems, Octave is limited to (approximately) the following
array sizes when using the default 32-bit indexing mode:

@example
@group
double:         16GB
single:          8GB 
uint64, int64:  16GB
uint32, int32:   8GB
uint16, int16:   4GB
uint8, int8:     2GB
@end group
@end example

In each case, the limit is really (approximately) @math{2^{31}} elements
because of the default type of the value used for indexing arrays
(signed 32-bit integer, corresponding to the size of a Fortran INTEGER
value).

Trying to create larger arrays will produce the following error:

@example
@group
octave:1> a = zeros (1024*1024*1024*3, 1, 'int8');
error: memory exhausted or requested size too large
       for range of Octave's index type --
       trying to return to prompt
@end group
@end example

@noindent
You will obtain this error even if your system has enough memory to
create this array (4 GB in the above case).

To use arrays larger than 2 GB, Octave has to be configured with the
option @option{--enable-64}.  This option is experimental and you are
encouraged to submit bug reports if you find a problem.  With this
option, Octave will use 64-bit integers internally for array dimensions
and indexing.  However, all numerical libraries used by Octave will
@strong{also} need to use 64-bit integers for array dimensions and
indexing.  In most cases, this means they will need to be compiled from
source since most (all?) distributions which package these libraries
compile them with the default Fortran integer size, which is normally
32-bits wide.

The following instructions were tested with the development version of
Octave and GCC 4.3.4 on an x86_64 Debian system.

The versions listed below are the versions used for testing.  If newer
versions of these packages are available, you should try to use them,
although there may be some differences.

All libraries and header files will be installed in subdirectories of
@code{$prefix64} (you must choose the location of this directory).

@itemize @bullet
@item @sc{blas} and @sc{lapack} (@url{http://www.netlib.org/lapack})

Reference versions for both libraries are included in the reference
@sc{lapack} 3.2.1 distribution from @url{netlib.org}.

@itemize @minus
@item
Copy the file @file{make.inc.example} and name it @file{make.inc}.
The options @option{-fdefault-integer-8} and @option{-fPIC} (on 64-bit
CPU) have to be added to the variable @code{OPTS} and @code{NOOPT}.

@item
Once you have compiled this library make sure that you use it for
compiling Suite Sparse and Octave.  In the following we assume that
you installed the @sc{lapack} library as $prefix64/lib/liblapack.a.
@end itemize

@item QRUPDATE (@url{http://sourceforge.net/projects/qrupdate})

In the @file{Makeconf} file:

@itemize @minus
@item
Add @option{-fdefault-integer-8} to @env{FFLAGS}.

@item
Adjust the @sc{blas} and @sc{lapack} variables as needed if your 64-bit
aware @sc{blas} and @sc{lapack} libraries are in a non-standard
location.

@item
Set @env{PREFIX} to the top-level directory of your install tree.

@item
Run @code{make solib} to make a shared library.

@item
Run @code{make install} to install the library.
@end itemize

@item
SuiteSparse (@url{http://www.cise.ufl.edu/research/sparse/SuiteSparse})

@itemize @minus
@item
In @file{UFconfig/UFconfig.mk} use the following options for
@env{CFLAGS} and @env{F77FLAGS}:

@example
@group
CC = gcc
CFLAGS = -fPIC -O -DLP64 -DLONGBLAS='long int' -DLONG='long int'
F77 = gfortran
F77FLAGS = -fPIC -O -fdefault-integer-8
BLAS = -L$BLAS/lib -lblas -lgfortran"
LAPACK = -L$LAPACK/lib -llapack"
@end group
@end example

@item
Disable the GPL-incompatible @code{METIS} library:

@example
@group
CHOLMOD_CONFIG = -DNPARTITION
SPQR_CONFIG = -DNPARTITION
METIS_PATH =
METIS =
@end group
@end example

@item
Disable the @code{DI} versions of the @code{CHOLMOD} library files by
setting

@example
OBJ = $(DL)
@end example

@noindent
in @file{CHOLMOD/Lib/Makefile}.

@item
Disable the @code{DI} versions of the @code{CHOLMOD} tests by commenting
out or deleting the following lines in @file{CHOLMOD/Demo/Makefile}:

@example
@group
./cholmod_demo < Matrix/bcsstk01.tri
./cholmod_demo < Matrix/lp_afiro.tri
./cholmod_demo < Matrix/can___24.mtx
./cholmod_demo < Matrix/c.tri
./cholmod_simple < Matrix/c.tri
./cholmod_simple < Matrix/can___24.mtx
./cholmod_simple < Matrix/bcsstk01.tri
@end group
@end example

@item
Run @command{make} to build the libraries.

@item
The SuiteSparse @file{Makefile} does not have an install target so
you must install the files by hand:

@example
@group
mkdir $prefix64/include/suitesparse
cp UFconfig/UFconfig.h $prefix64/include/suitesparse
for d in AMD BTF CAMD CCOLAMD \
         CHOLMOD COLAMD CXSparse UMFPACK; do
  cp $d/Lib/lib*a $prefix64/lib
  cp $d/Include/*h $prefix64/include/suitesparse
done
@end group
@end example

@item
You can generate shared versions of these libraries by doing the
following in the @file{$prefix64/lib} directory: 

@example
@group
top=$(pwd)
for f in *.a; do
  mkdir tmp
  cd tmp
  ar vx ../$f
  gcc -shared -o ../$@{f%%.a@}.so *.o
  cd $top
  rm -rf tmp
done
@end group
@end example

@end itemize

@item ATLAS instead of reference @sc{blas} and @sc{lapack}

Suggestions on how to compile ATLAS would be most welcome.

@item @sc{glpk}

Suggestions on how to compile @sc{glpk} would be most welcome.

@item Qhull (@url{http://www.qhull.org})

Suggestions on how to compile Qhull would be most welcome.

@item Octave

Octave's 64-bit index support is activated with the configure option
@option{--enable-64}.

@example
@group
./configure \
  LD_LIBRARY_PATH="$prefix64/lib" \
  CPPFLAGS="-I$prefix64/include" LDFLAGS="-L$prefix64/lib" \
  --enable-64
@end group
@end example

You must ensure that all Fortran sources except those in the
@file{libcruft/ranlib} directory are compiled such that INTEGERS are
8-bytes wide.  If you are using gfortan, the configure script should
automatically set the Makefile variable @w{@env{F77_INTEGER_8_FLAG}} to 
@option{-fdefault-integer-8}.  If you are using another compiler, you
must set this variable yourself.  You should NOT set this flag in
@env{FFLAGS}, otherwise the files in @file{libcruft/ranlib} will be
miscompiled.

@item Other dependencies

Probably nothing special needs to be done for the following
dependencies.  If you discover that something does need to be done,
please submit a bug report.

@itemize @minus
@item pcre

@item zlib

@item hdf5

@item fftw3

@item cURL

@item GraphicsMagick++

@item OpenGL

@item freetype

@item fontconfig

@item fltk
@end itemize

@end itemize

@node Installation Problems
@appendixsec 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
installation of Octave.

@itemize @bullet
@item
On some SCO systems, @code{info} fails to compile if
@w{@code{HAVE_TERMIOS_H}} is defined in @file{config.h}.  Simply
removing the definition from @file{info/config.h} should allow it to
compile.

@item
If @code{configure} finds @code{dlopen}, @code{dlsym}, @code{dlclose},
and @code{dlerror}, but not the header file @file{dlfcn.h}, you need to
find the source for the header file and install it in the directory
@file{usr/include}.  This is reportedly a problem with Slackware 3.1.
For Linux/GNU systems, the source for @file{dlfcn.h} is in the
@code{ldso} package.

@item
Building @file{.oct} files doesn't work.

You should probably have a shared version of @code{libstdc++}.  A patch
is needed to build shared versions of version 2.7.2 of @code{libstdc++}
on the HP-PA architecture.  You can find the patch at
@url{ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix}.

@item
On some DEC alpha systems there may be a problem with the @code{libdxml}
library, resulting in floating point errors and/or segmentation faults
in the linear algebra routines called by Octave.  If you encounter such
problems, then you should modify the configure script so that
@w{@code{SPECIAL_MATH_LIB}} is not set to @code{-ldxml}.

@item
On FreeBSD systems Octave may hang while initializing some internal
constants.  The fix appears to be to use

@example
options      GPL_MATH_EMULATE
@end example

@noindent
rather than 

@example
options      MATH_EMULATE 
@end example

@noindent
in the kernel configuration files (typically found in the directory
@file{/sys/i386/conf}.  After making this change, you'll need to rebuild
the kernel, install it, and reboot.

@item
If you encounter errors like

@example
@group
passing `void (*)()' as argument 2 of
  `octave_set_signal_handler(int, void (*)(int))'
@end group
@end example

@noindent
or

@example
@group
warning: ANSI C++ prohibits conversion from `(int)' 
         to `(@dots{})'
@end group
@end example

@noindent
while compiling @file{sighandlers.cc}, you may need to edit some files
in the @code{gcc} include subdirectory to add proper prototypes for
functions there.  For example, Ultrix 4.2 needs proper declarations for
the @code{signal} function and the @w{@code{SIG_IGN}} macro in the file
@file{signal.h}.

On some systems the @w{@code{SIG_IGN}} macro is defined to be something
like this:

@example
#define  SIG_IGN  (void (*)())1
@end example

@noindent
when it should really be something like:

@example
#define  SIG_IGN  (void (*)(int))1
@end example

@noindent
to match the prototype declaration for the @code{signal} function.  This
change should also be made for the @w{@code{SIG_DFL}} and
@w{@code{SIG_ERR}} symbols.  It may be necessary to change the
definitions in @file{sys/signal.h} as well.

The @code{gcc} @code{fixincludes} and @code{fixproto} scripts should
probably fix these problems when @code{gcc} installs its modified set of
header files, but I don't think that's been done yet.

@strong{You should not change the files in @file{/usr/include}}.  You
can find the @code{gcc} include directory tree by running the command

@example
gcc -print-libgcc-file-name
@end example

@noindent
The directory of @code{gcc} include files normally begins in the same
directory that contains the file @file{libgcc.a}.

@item
Some of the Fortran subroutines may fail to compile with older versions
of the Sun Fortran compiler.  If you get errors like

@example
@group
zgemm.f:
        zgemm:
warning: unexpected parent of complex expression subtree
zgemm.f, line 245: warning: unexpected parent of complex
  expression subtree
warning: unexpected parent of complex expression subtree
zgemm.f, line 304: warning: unexpected parent of complex
  expression subtree
warning: unexpected parent of complex expression subtree
zgemm.f, line 327: warning: unexpected parent of complex
  expression subtree
pcc_binval: missing IR_CONV in complex op
make[2]: *** [zgemm.o] Error 1
@end group
@end example

@noindent
when compiling the Fortran subroutines in the @file{libcruft}
subdirectory, you should either upgrade your compiler or try compiling
with optimization turned off.

@item
On NeXT systems, if you get errors like this:

@example
@group
/usr/tmp/cc007458.s:unknown:Undefined local 
      symbol LBB7656
/usr/tmp/cc007458.s:unknown:Undefined local
      symbol LBE7656
@end group
@end example

@noindent
when compiling @file{Array.cc} and @file{Matrix.cc}, try recompiling
these files without @option{-g}.

@item
Some people have reported that calls to shell_cmd and the pager do not
work on SunOS systems.  This is apparently due to having
@w{@code{G_HAVE_SYS_WAIT}} defined to be 0 instead of 1 when compiling
@code{libg++}.

@item
On NeXT systems, linking to @file{libsys_s.a} may fail to resolve the
following functions

@example
@group
_tcgetattr
_tcsetattr
_tcflow
@end group
@end example

@noindent
which are part of @file{libposix.a}.  Unfortunately, linking Octave with
@option{-posix} results in the following undefined symbols.

@example
@group
.destructors_used
.constructors_used
_objc_msgSend
_NXGetDefaultValue
_NXRegisterDefaults
.objc_class_name_NXStringTable
.objc_class_name_NXBundle
@end group
@end example

One kluge around this problem is to extract @file{termios.o} from
@file{libposix.a}, put it in Octave's @file{src} directory, and add it
to the list of files to link together in the makefile.  Suggestions for
better ways to solve this problem are welcome!

@item
If Octave crashes immediately with a floating point exception, it is
likely that it is failing to initialize the IEEE floating point values
for infinity and NaN.

If your system actually does support IEEE arithmetic, you should be able
to fix this problem by modifying the function @code{octave_ieee_init} in
the file @file{lo-ieee.cc} to correctly initialize Octave's internal
infinity and NaN variables.

If your system does not support IEEE arithmetic but Octave's configure
script incorrectly determined that it does, you can work around the
problem by editing the file @file{config.h} to not define
@w{@code{HAVE_ISINF}}, @w{@code{HAVE_FINITE}}, and
@w{@code{HAVE_ISNAN}}.

In any case, please report this as a bug since it might be possible to
modify Octave's configuration script to automatically determine the
proper thing to do.

@item
If Octave is unable to find a header file because it is installed in a
location that is not normally searched by the compiler, you can add the
directory to the include search path by specifying (for example)
@code{CPPFLAGS=-I/some/nonstandard/directory} as an argument to
@code{configure}.  Other variables that can be specified this way are
@env{CFLAGS}, @env{CXXFLAGS}, @env{FFLAGS}, and @env{LDFLAGS}.  Passing
them as options to the configure script also records them in the
@file{config.status} file.  By default, @env{CPPFLAGS} and @env{LDFLAGS}
are empty, @env{CFLAGS} and @env{CXXFLAGS} are set to @code{"-g -O"} and
@env{FFLAGS} is set to @code{"-O"}.

@end itemize