@c Copyright (C) 1996-2019 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
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License 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 <https://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 the development source itself.

@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{https://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{https://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{https://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{https://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{https://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{https://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{https://www.gnu.org/software/libtool}).  Libtool is required by
Automake.

@item gperf
Perfect hash function generator (@url{https://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{https://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{https://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{https://www.pcre.org}).
@end table

The following external package is optional but strongly recommended:

@table @asis
@item GNU Readline
Command-line editing library (@url{https://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{https://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{https://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 can be
used to provide windows for Octave's OpenGL-based graphics functions.

@item fontconfig
Library for configuring and customizing font access
(@url{https://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{https://www.freetype.org}).  FreeType is used
to perform font rendering for Octave's OpenGL-based graphics functions.

@item GLPK
GNU Linear Programming Kit (@url{https://www.gnu.org/software/glpk}).
GPLK is required for the function @code{glpk}.

@item @nospell{gl2ps}
OpenGL to PostScript printing library (@url{https://www.geuz.org/gl2ps/}).
@nospell{gl2ps} is required for printing when using OpenGL-based
graphics toolkits (currently either FLTK or Qt).

@item gnuplot
Interactive graphics program (@url{http://www.gnuplot.info}).  gnuplot
can be used as a graphics renderer for Octave; prior to Octave 4.0,
gnuplot was the default graphics renderer.

@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{https://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 OpenGL
API for portable 2-D and 3-D graphics (@url{https://www.opengl.org}).  An
OpenGL implementation can be used to provide a renderer for Octave's
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.  Since Octave 4.0, the default graphics
renderer (@qcode{"qt"}) has been OpenGL-based.

@item PortAudio
PortAudio (@url{http://www.portaudio.com/}) provides a very simple API
for recording and/or playing sound using a simple callback function or
a blocking read/write interface.  It is required for the audio processing
functions @code{audioplayer}, @code{audiorecorder}, and
@code{audiodevinfo}.

@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{https://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{https://www.qt.io}).  Qt is required for
building the GUI@.  It is a large framework, but the only components
required are the GUI, core, and network modules.  Since Octave 4.0, the
default graphics renderer (@qcode{"qt"}) has been Qt-based, which has
been OpenGL-based.

@item SuiteSparse
Sparse matrix factorization library
(@url{http://faculty.cse.tamu.edu/davis/suitesparse.html}).
SuiteSparse is required to provide sparse matrix factorizations and
solution of linear equations for sparse systems.

@item SUNDIALS
@nospell{The SUite of Nonlinear and DIfferential/ALgebraic Equation Solvers}
(@url{https://computation.llnl.gov/projects/sundials}) is required for
the Ordinary Differential Equations (ODE) solvers @code{ode15i} and
@code{ode15s}.

@item zlib
Data compression library (@url{https://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 --disable-64
Disable using 64-bit integers for indexing arrays and use 32-bit
integers instead.  On systems with 32-bit pointers, this option is
always disabled.  If the configure script determines that your @sc{blas}
library uses 32-bit integers, then operations using the following
libraries are limited to arrays with dimensions that are smaller than
@math{2^{31}} elements:

@itemize @bullet
@item @sc{blas}

@item @sc{lapack}

@item QRUPDATE

@item SuiteSparse

@item @sc{arpack}
@end itemize

Additionally, the following libraries use @code{int} internally, so
maximum problem sizes are always limited:

@itemize @bullet
@item @sc{glpk}

@item Qhull
@end itemize

@xref{Compiling Octave with 64-bit Indexing}, for more details
about building Octave with more complete support for large arrays.

@item --enable-address-sanitizer-flags
Enable compiler options @option{-fsanitize=address} and
@option{-fomit-frame-pointer} for memory access checking.  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.  It may also interfere with proper functioning of the GUI.

@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 --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 three options for plotting in Octave: the external
program gnuplot, the internal graphics engine using OpenGL coupled with
either FLTK or Qt widgets.  Gnuplot is a command-driven interactive
function plotting program.

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://ftp.gnu.org}, but it
is often very busy.  A list of sites that mirror the software on
@url{ftp://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}/include/octave-@var{version}/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 uses 64-bit integers for indexing arrays
by default.  If the configure script determines that your @sc{blas}
library uses 32-bit integers, then operations using the following
libraries are limited to arrays with dimensions that are smaller than
@math{2^{31}} elements:

@itemize @bullet
@item @sc{blas}

@item @sc{lapack}

@item QRUPDATE

@item SuiteSparse

@item @sc{arpack}
@end itemize

Additionally, the following libraries use @code{int} internally, so
maximum problem sizes are always limited:

@itemize @bullet
@item @sc{glpk}

@item Qhull
@end itemize

Except for @sc{glpk} and Qhull, these libraries may also be configured
to use 64-bit integers, but most systems do not provide packages built
this way.  If you wish to experiment with large arrays, the following
information may be helpful.

To determine the integer size of the @sc{blas} library used by Octave, the
following code can be executed:

@example
@group
clear all;
N = 2^31;
## The following line requires about 8 GB of RAM!
a = b = ones (N, 1, "single");
c = a' * b
@end group
@end example

If the @sc{blas} library uses 32-bit integers, an error will be thrown:

@example
@group
error: integer dimension or index out of range for Fortran
INTEGER type
@end group
@end example

Otherwise, if the @sc{blas} library uses 64-bit integers, the result is:

@example
c = 2^31 = 2147483648
@end example

Note that the test case above usually requires twice the memory, if
@var{a} and @var{b} are not assigned by @code{a = b = @dots{}}.
Note further, that the data type @code{single} has a precision of
about 23 binary bits.  In this particular example no rounding errors
occur.

The following instructions were tested with the development version of
Octave and GCC 4.3.4 on an x86_64 Debian system and may be out of date
now.  Please report any problems or corrections on the Octave bug
tracker.

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{http://www.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{https://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://faculty.cse.tamu.edu/davis/suitesparse.html})

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} (@url{https://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/external/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/external/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/external}
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 @nospell{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