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.

Installing Octave
*****************

   Here is the procedure for installing Octave from scratch on a Unix
system.  For instructions on how to install the binary distributions of
Octave, see *Note Binary Distributions::.

   * Run the shell script `configure'.  This will determine the features
     your system has (or doesn't have) and create a file named Makefile
     from each of the files named Makefile.in.

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

    `--prefix=PREFIX'
          Install Octave in subdirectories below PREFIX.  The default
          value of PREFIX is `/usr/local'.

    `--srcdir=DIR'
          Look for Octave sources in the directory DIR.

    `--with-f2c'
          Use f2c even if Fortran compiler is available.

    `--enable-dld'
          Use DLD to make Octave capable of dynamically linking
          externally compiled functions.  This only works on systems
          that have a working port of DLD.

    `--enable-lite-kernel'
          Compile smaller kernel.  This currently requires DLD so that
          Octave can load functions at run time that are not loaded at
          compile time.

    `--help'
          Print a summary of the options recognized by the configure
          script.

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

   * Run make.

     You will need a recent version of GNU make.  Modifying Octave's
     Makefiles to work with other make programs is probably not worth
     your time.  We recommend you get and compile GNU make instead.

     For plotting, you will need to have gnuplot installed on your
     system.  Gnuplot is a command-driven interactive function plotting
     program.  Gnuplot is copyrighted, but freely distributable.  The
     `gnu' in gnuplot is a coincidence--it is not related to the GNU
     project or the FSF in any but the most peripheral sense.

     For version 1.1.1, you must have the GNU C++ compiler (gcc)
     version 2.6.3 or later to compile Octave.  You will also need
     version 2.6.1 of the GNU C++ class library (libg++).  If you plan
     to modify the parser you will also need GNU bison and fles.  If
     you modify the documentation, you will need GNU Texinfo, along
     with the patch for the makeinfo program that is distributed with
     Octave.

     GNU make, gcc, and libg++, gnuplot, bison, flex, and Texinfo are
     all available from many anonymous ftp archives, including
     ftp.che.utexas.edu, ftp.uu.net, prep.ai.mit.edu, and
     wuarchive.wustl.edu.

     If you don't have a Fortran compiler, or if your Fortran compiler
     doesn't work like the traditional Unix f77, you will need to have
     the Fortran to C translator f2c.  You can get f2c from any number
     of anonymous ftp archives.  The most recent version of f2c is
     always available from research.att.com.

     On an otherwise idle SPARCstation II, it will take somewhere
     between 60 and 90 minutes to compile everything, depending on
     whether you are compiling the Fortran libraries with f2c or using
     the Fortran compiler directly.  You will need about 50 megabytes
     of disk storage to work with (considerably less if you don't
     compile with debugging symbols).  To do that, use the command

          make CFLAGS=-O CXXFLAGS=-O LDFLAGS=

     instead of just `make'.

   * 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, see the file BUGS for
     information about how to report bugs.

   * Once you have successfully compiled Octave, run `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:

    `PREFIX/bin'
          Octave and other binaries that people will want to run
          directly.

    `PREFIX/lib'
          Libraries like libcruft.a and liboctave.a.

    `PREFIX/include/octave'
          Include files distributed with Octave.

    `PREFIX/man/man1'
          Unix-style man pages describing Octave.

    `PREFIX/info'
          Info files describing Octave.

    `PREFIX/lib/octave/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.

    `PREFIX/lib/octave/VERSION/exec/HOST_TYPE'
          Executables to be run by Octave rather than the user.

    `PREFIX/lib/octave/VERSION/oct/HOST_TYPE'
          Object files that will be dynamically loaded.

    `PREFIX/lib/octave/VERSION/imagelib'
          Image files that are distributed with Octave.

     where PREFIX defaults to `/usr/local', VERSION stands for the
     current version number of the interpreter, and HOST_TYPE is the
     type of computer on which Octave is installed (for example,
     `i486-unknown-gnu').

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.

   * On AIX (and possibly other) systems, GCC 2.6.2 generates invalid
     assembly code when compiling some parts of Octave.  On AIX
     systems, it is possible to get a working binary by not using the
     compiler flag `-fno-implicit-templates'.  You can specify this as
     an option to make by using a command like

          make NO_IMPLICIT_TEMPLATES=

   * You may need to edit some files in the gcc include subdirectory to
     add prototypes for functions there.  For example, Ultrix 4.2 needs
     proper declarations for the `signal()' and the `SIG_IGN' macro in
     the file `signal.h'.

     On some systems the `SIG_IGN' macro is defined to be something like
     this:

          #define  SIG_IGN  (void (*)())1

     when it should really be something like:

          #define  SIG_IGN  (void (*)(int))1

     to match the prototype declaration for `signal()'.

     The gcc fixincludes/fixproto script should probably fix this when
     gcc installs its modified set of header files, but I don't think
     that's been done yet.

   * There is a bug with the makeinfo program that is distributed with
     texinfo-3.1 that causes the indices in Octave's on-line manual to
     be generated incorrectly.  If you need to recreate the on-line
     documentation, you should get the makeinfo program that is
     distributed with texinfo-3.1 and apply the patch for makeinfo that
     is distributed with Octave.  See the file MAKEINFO.PATCH for more
     details.

   * If you don't have NPSOL but you still want to be able to solve
     NLPs, or if you don't have QPSOL but you still want to solve QPs,
     you'll need to find replacements or order them from Stanford.  If
     you know of a freely redistributable replacement, please let us
     know--we might be interested in distributing it with Octave.

     You can get more information about NPSOL and QPSOL from

          Stanford University
          Office of Technology Licensing
          857 Serra Street
          Stanford CA 94305-6225
          Tel: (415) 723-0651
          Fax: (415) 725-7295

     Octave may soon support FSQP, an NLP solver from Andre Tits
     (andre@src.umd.edu) of the University of Maryland.  FSQP is
     available free of charge to academic sites, but can not be
     redistributed to third parties.

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

          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

     when compiling the Fortran subroutines in the `libcruft'
     subdirectory, you should either upgrade your compiler or try
     compiling with optimization turned off.

   * On NeXT systems, if you get errors like this:

          /usr/tmp/cc007458.s:unknown:Undefined local symbol LBB7656
          /usr/tmp/cc007458.s:unknown:Undefined local symbol LBE7656

     when compiling `Array.cc' and `Matrix.cc', try recompiling these
     files without `-g'.

   * Some people have reported that calls to shell_cmd and the pager do
     not work on SunOS systems.  This is apparently due to having
     `G_HAVE_SYS_WAIT' defined to be 0 instead of 1 when compiling
     libg++.

   * On NeXT systems, linking to `libsys_s.a' may fail to resolve the
     following functions

          _tcgetattr
          _tcsetattr
          _tcflow

     which are part of `libposix.a'.  Unfortunately, linking Octave with
     `-posix' results in the following undefined symbols.

          .destructors_used
          .constructors_used
          _objc_msgSend
          _NXGetDefaultValue
          _NXRegisterDefaults
          .objc_class_name_NXStringTable
          .objc_class_name_NXBundle

     One kludge around this problem is to extract `termios.o' from
     `libposix.a', put it in Octave's `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!

   * With g++ 2.6.3 (and possibly other 2.6.x versions) on some Intel
     x86 systems, compiling `Array-d.cc' fails with the messages like

          as: /tmp/cc005254.s:4057: Local symbol LBB103 never defined.
          as: /tmp/cc005254.s:4057: Local symbol LBE103 never defined.

     A possible workaround for this is to compile without `-g'.

   * 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
     `octave_ieee_init' in the file `sysdep.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 `config.h' to not define
     `HAVE_ISINF', `HAVE_FINITE', and `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.

Binary Distributions
====================

   This section contains instructions for creating and installing a
binary distribution.

Installing Octave from a Binary Distribution
--------------------------------------------

   * To install Octave from a binary distribution, execute the command

          sh ./doinstall.sh

     in the top level directory of the distribution.

     Binary distributions are normally compiled assuming that Octave
     will be installed in the following subdirectories of `/usr/local'.

    `bin'
          Octave and other binaries that people will want to run
          directly.

    `man/man1'
          Unix-style man pages describing Octave.

    `info'
          Info files describing Octave.

    `lib/octave/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.

    `lib/octave/VERSION/exec/HOST_TYPE'
          Executables to be run by Octave rather than the user.

    `lib/octave/VERSION/imagelib'
          Image files that are distributed with Octave.

     where VERSION stands for the current version number of the
     interpreter, and HOST_TYPE is the type of computer on which Octave
     is installed (for example, `i486-unknown-gnu').

     If these directories don't exist, the script `doinstall.sh' will
     create them for you.

     If this is possible for you to install Octave in `/usr/local', or
     if you would prefer to install it in a different directory, you can
     specify the name of the top level directory as an argument to the
     doinstall.sh script.  For example:

          sh ./doinstall.sh /some/other/directory

     Octave will then be installed in subdirectories of the directory
     `/some/other/directory'

Creating a Binary Distribution
------------------------------

   Here is how to build a binary distribution for others.

   * Build Octave in the same directory as the source.  This is required
     since the `binary-dist' targets in the Makefiles will not work if
     you compile outside the source tree.

   * Use `CFLAGS=-O CXXFLAGS=-O LDFLAGS=' as arguments for Make because
     most people who get the binary distributions are probably not
     going to be interested in debugging Octave.

   * Type `make binary-dist'.  This will build everything and then pack
     it up for distribution.

