@c Copyright (C) 1996-2015 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
@include macros.texi

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

@menu
* Obtaining the Dependencies Automatically::
* Build Tools::
* External Packages::
@end menu

@node Obtaining the Dependencies Automatically
@subsection Obtaining the Dependencies Automatically

On some systems you can obtain many of Octave's build dependencies
automatically.  The commands for doing this vary by system.  Similarly,
the names of pre-compiled packages vary by system and do not always
match exactly the names listed in @ref{Build Tools} and @ref{External
Packages}.

You will usually need the development version of an external dependency
so that you get the libraries and header files for building software,
not just for running already compiled programs.  These packages
typically have names that end with the suffix @code{-dev} or @code{-devel}.

On systems with @code{apt-get} (Debian, Ubuntu, etc.), you may be able
to install most of the tools and external packages using a command
similar to

@example
apt-get build-dep octave
@end example

@noindent
The specific package name may be @code{octave3.2} or @code{octave3.4}.
The set of required tools and external dependencies does not change
frequently, so it is not important that the version match exactly, but
you should use the most recent one available.

On systems with @code{yum} (Fedora, Red Hat, etc.), you may be able to
install most of the tools and external packages using a command similar to

@example
yum-builddep octave
@end example

@noindent
The @code{yum-builddep} utility is part of the @code{yum-utils} package.

For either type of system, the package name may include a version
number.  The set of required tools and external dependencies does not
change frequently, so it is not important that the version exactly match
the version you are installing, but you should use the most recent one
available.

@node Build Tools
@subsection Build Tools

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.

@item gperf
Perfect hash function generator (@url{http://www.gnu.org/software/gperf}).
You will need gperf if you modify the @code{octave.gperf} file or if you
delete the file that is generated from it.

@item Texinfo
Package for generating online and print documentation
(@url{http://www.gnu.org/software/texinfo}).  You will need Texinfo to
build Octave's documentation or if you modify the documentation source
files or the docstring of any Octave function.
@end table

@node External Packages
@subsection External Packages

The following external packages are required:

@table @asis
@item BLAS
Basic Linear Algebra Subroutine library.  Accelerated @sc{blas} libraries such
as OpenBLAS (@url{http://www.openblas.net/}) or
ATLAS (@url{http://math-atlas.sourceforge.net}) are recommended for best
performance.  The reference implementation (@url{http://www.netlib.org/blas})
is slow, unmaintained, and suffers from certain bugs in corner case inputs.

@item LAPACK
Linear Algebra Package (@url{http://www.netlib.org/lapack}).

@item PCRE
The Perl Compatible Regular Expression library (@url{http://www.pcre.org}).
@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 @option{--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}).  @sc{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 perform font rendering for 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 @nospell{gl2ps}
OpenGL to PostScript printing library (@url{http://www.geuz.org/gl2ps/}).
@nospell{gl2ps} is required for printing when using the FLTK toolkit.

@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}).  @sc{hdf5} is required for Octave's
@code{load} and @code{save} commands to read and write HDF data files.

@item Java Development Kit
Java programming language compiler and libraries.  The OpenJDK free
software implementation is recommended (@url{http://openjdk.java.net/}),
although other JDK implementations may work.  Java is required to be able
to call Java functions from within Octave.

@item LLVM
Compiler framework, (@url{http://www.llvm.org}).  LLVM is required for
Octave's experimental just-in-time (JIT) compilation for speeding up the
interpreter.

@item OpenGL
API for portable 2-D and 3-D 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{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 QScintilla
Source code highlighter and manipulator; a Qt port of Scintilla
(@url{http://www.riverbankcomputing.co.uk/software/qscintilla}).
QScintilla is used for syntax highlighting and code completion in the
GUI.

@item Qt
GUI and utility libraries (@url{}).  Qt is required for building the GUI.
It is a large framework, but the only components required are the GUI,
core, and network modules.

@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
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
@qcode{"GraphicsMagick"} (default) or @qcode{"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% compatible, 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
see @ref{Installation Problems} for a list of
known problems and if there is a workaround or solution for
your problem.  If not, see
@ifclear INSTALLONLY
@ref{Trouble}
@end ifclear
@ifset INSTALLONLY
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 liboctave.a and liboctinterp.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

@node 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
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})

Pass the following options to @command{make} to enable 64-bit integers
for @sc{blas} library calls.  On 64-bit Windows systems, use
@code{-DLONGBLAS="long long"} instead.

@example
@group
CFLAGS='-DLONGBLAS=long'
CXXFLAGS='-DLONGBLAS=long'
@end group
@end example

The SuiteSparse makefiles don't generate shared libraries.  On some
systems, you can generate them by doing something as simple as

@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

@noindent
Other systems may require a different solution.

@item @sc{arpack} (http://forge.scilab.org/index.php/p/arpack-ng/)

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

@item Run @code{make} to build the library.

@item Run @code{make install} to install the library.
@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}

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

Both @sc{glpk} and Qhull use @code{int} internally so maximum problem
sizes may be limited.

@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{liboctave/cruft/ranlib} directory are compiled such that INTEGERS are
8-bytes wide.  If you are using gfortran, 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{liboctave/cruft/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
@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
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{liboctave/cruft}
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 system() 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 systems where the reference @sc{blas} library is used the following
matrix-by-vector multiplication incorrectly handles NaN values of the
form @code{NaN * 0}.

@example
@group
[NaN, 1; 0, 0] * [0; 1]
@result{}
[ 1
  0 ]

correct result @result{}
[ NaN
  0   ]
@end group
@end example

Install a different @sc{blas} library such as OpenBLAS or ATLAS to correct
this issue.

@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 @qcode{"-g -O2"} and
@env{FFLAGS} is set to @qcode{"-O"}.

@end itemize