--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/interpreter/install.txi	Tue Oct 19 10:08:42 1999 +0000
@@ -0,0 +1,566 @@
+@c Copyright (C) 1996, 1997 John W. Eaton
+@c This is part of the Octave manual.
+@c For copying conditions, see the file gpl.texi.
+
+@c The text of this file will eventually appear in the file INSTALL
+@c in the Octave distribution, as well as in the Octave manual.
+
+@ifclear INSTALLONLY
+@node Installation, Emacs, Trouble, Top
+@appendix Installing Octave
+@end ifclear
+
+@ifset INSTALLONLY
+@include conf.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.
+
+@node Installation,  , Installation
+@chapter Installing Octave
+@end ifset
+
+@cindex 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 @ref{Binary Distributions}.
+
+@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 --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 --with-f2c
+Use @code{f2c} even if a Fortran compiler is available.
+
+@item --with-g77
+Use @code{g77} to compile Fortran code.
+
+@item --enable-shared
+Create shared libraries.  If you are planning to use
+@code{--enable-lite-kernelel} or 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.  Note that 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 --enable-dl
+Use @code{dlopen} and friends to make Octave capable of dynamically
+linking externally compiled functions.  This only works on systems that
+actually have these functions.  If you plan on using this feature, you
+should probably also use @code{--enable-shared} to reduce the size of
+your @file{.oct} files.
+
+@item --enable-shl
+Use @code{shl_load} and friends to make Octave capable of dynamically
+linking externally compiled functions.  This only works on systems that
+actually have these functions (only HP-UX systems).  If you plan on
+using this feature, you should probably also use @code{--enable-shared}
+to reduce the size of your @file{.oct} files.
+
+@item --enable-lite-kernel
+Compile smaller kernel.  This currently requires the dynamic linking
+functions @code{dlopen} or @code{shl_load} and friends so that Octave
+can load functions at run time that are not loaded at compile time.
+
+@item --help
+Print a summary of the options recognized by the configure script.
+@end table
+
+See the file @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.
+
+@item
+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.
+
+To compile Octave, you will need a recent version of GNU Make.  You
+will also need @code{g++} 2.7.2 or later.  Version 2.8.0 or @code{egcs}
+1.0.x should work.  Later versions may work, but C++ is still evolving,
+so don't be too surprised if you run into some trouble.
+
+It is no longer necessary to have @code{libg++}, but you do need to have
+the GNU implementation of @code{libstdc++}.  If you are using @code{g++}
+2.7.2, @code{libstdc++} is distributed along with @code{libg++}, but for
+later versions, @code{libstdc++} is distributed separately.  For
+@code{egcs}, @code{libstdc++} is included with the compiler
+distribution.
+
+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, along with the patch for the @code{makeinfo} program that is
+distributed with Octave.
+
+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}.
+
+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 @code{f2c}.  You can get @code{f2c} from any
+number of anonymous ftp archives.  The most recent version of @code{f2c}
+is always available from @url{netlib.att.com}.
+
+On an otherwise idle Pentium 133 running Linux, it will take somewhere
+between 1-1/2 to 3 hours to compile everything, depending on whether you
+are building shared libraries.  You will need about 100 megabytes of disk
+storage to work with (considerably less if you don't compile with debugging
+symbols).  To do that, use the command
+
+@example
+make CFLAGS=-O CXXFLAGS=-O LDFLAGS=
+@end example
+
+@noindent
+instead of just @samp{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 @samp{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
+Libraries like libcruft.a and liboctave.a.
+
+@item @var{prefix}/share
+Architecture-independent data files.
+
+@item @var{prefix}/include/octave
+Include files distributed with Octave.
+
+@item @var{prefix}/man/man1
+Unix-style man pages describing Octave.
+
+@item @var{prefix}/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}/lib/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
+* Installation Problems::       
+* Binary Distributions::        
+@end menu
+
+@node Installation Problems, Binary Distributions, Installation, Installation
+@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
+@code{HAVE_TERMIOS_H} is defined int @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 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
+
+@smallexample
+@group
+passing `void (*)()' as argument 2 of
+  `octave_set_signal_handler(int, void (*)(int))'
+@end group
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+warning: ANSI C++ prohibits conversion from `(int)' to `(...)'
+@end smallexample
+
+@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 @code{SIG_IGN} macro in the file
+@file{signal.h}.
+
+On some systems the @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 @code{SIG_DFL} and @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
+
+@smallexample
+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 smallexample
+
+@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
+/usr/tmp/cc007458.s:unknown:Undefined local symbol LBB7656
+/usr/tmp/cc007458.s:unknown:Undefined local symbol LBE7656
+@end example
+
+@noindent
+when compiling @file{Array.cc} and @file{Matrix.cc}, try recompiling
+these files without @code{-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
+@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
+_tcgetattr
+_tcsetattr
+_tcflow
+@end example
+
+@noindent
+which are part of @file{libposix.a}.  Unfortunately, linking Octave with
+@code{-posix} results in the following undefined symbols.
+
+@example
+.destructors_used
+.constructors_used
+_objc_msgSend
+_NXGetDefaultValue
+_NXRegisterDefaults
+.objc_class_name_NXStringTable
+.objc_class_name_NXBundle
+@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
+@code{HAVE_ISINF}, @code{HAVE_FINITE}, and @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
+After installing the binary distribution of Octave in an alternate
+directory, the Emacs command @code{run-octave} doesn't work.  Emacs
+hangs in @code{accept-process-output} in @code{inferior-octave-startup}.
+
+This seems to be a problem with executing a shell script using the
+comint package.  You can avoid the problem by changing the way Octave is
+installed to eliminate the need for the shell script.  You can either
+compile and install Octave using the source distribution, reinstall the
+binary distribution in the default directory, or copy the commands in
+the octave shell script wrapper to your shell startup files (and the
+shell startup files for anyone else who is using Octave) and then
+rename the file @file{octave.bin} to be @file{octave}.
+@end itemize
+
+@node Binary Distributions,  , Installation Problems, Installation
+@appendixsec Binary Distributions
+
+Although Octave is not very difficult to build from its sources, it is a
+relatively large program that does require a significant amount of time
+and disk space to compile and install.  Because of this, many people
+want to be able to obtain binary distributions so they can start using
+Octave immediately, without having to bother with the details of
+compiling it first.  This is understandable, so I try to maintain a
+current collection of binary distributions at
+@url{ftp://ftp.che.wisc.edu/pub/octave/BINARIES}.
+
+Please understand, however, that there is only a limited amount of time
+available to devote to making binaries, so binaries may not be
+immediately available for some platforms.  (Please contact
+@email{bug-octave@@bevo.che.wisc.edu} if you are interested in helping
+make a binary distribution available for your system.)
+
+@menu
+* Installing Octave from a Binary Distribution::  
+* Creating a Binary Distribution::  
+@end menu
+
+@node Installing Octave from a Binary Distribution, Creating a Binary Distribution, Binary Distributions, Binary Distributions
+@appendixsubsec Installing Octave from a Binary Distribution
+
+To install Octave from a binary distribution, execute the command
+
+@example
+sh ./install-octave
+@end example
+
+@noindent
+in the top level directory of the distribution.
+
+Binary distributions are normally compiled assuming that Octave will be
+installed in the following subdirectories of @file{/usr/local}.
+
+@table @file
+@item bin
+Octave and other binaries that people will want to run directly.
+
+@item lib
+Shared libraries that Octave needs in order to run.  These files are
+not included if you are installing a statically linked version of
+Octave.
+
+@item man/man1
+Unix-style man pages describing Octave.
+
+@item info
+Info files describing Octave.
+
+@item 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 libexec/octave/@var{version}/exec/@var{arch}
+Executables to be run by Octave rather than the user.
+
+@item libexec/octave/@var{version}/oct/@var{arch}
+Object files that will be dynamically loaded.
+
+@item share/octave/@var{version}/imagelib
+Image files that are distributed with Octave.
+@end table
+
+@noindent
+where @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{@value{TARGETHOSTTYPE}}).
+
+If these directories don't exist, the script @code{install-octave} will
+create them for you.  The installation script also creates the following
+subdirectories of @file{/usr/local} that are intended for locally
+installed functions:
+
+@table @file
+@item share/octave/site/m
+Locally installed M-files.
+
+@item libexec/octave/site/exec/@var{arch}
+Locally installed binaries intended to be run by Octave rather than by
+the user.
+
+@item libexec/octave/site/octave/@var{arch}
+Local object files that will be dynamically linked.
+@end table
+
+If it is not possible for you to install Octave in @file{/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
+@file{install-octave} script.  For example:
+
+@example
+sh ./install-octave /some/other/directory
+@end example
+
+@noindent
+will install Octave in subdirectories of the directory
+@file{/some/other/directory}.
+
+@node Creating a Binary Distribution,  , Installing Octave from a Binary Distribution, Binary Distributions
+@appendixsubsec Creating a Binary Distribution
+
+Here is how to build a binary distribution for others to use.  If you
+want to make a binary distribution for your system available along with
+the Octave sources and binaries on @url{ftp.che.wisc.edu}, please follow
+this procedure.  For directions explaining how to make the binary
+available on the ftp site, please contact
+@email{bug-octave@@bevo.che.wisc.edu}.
+
+@itemize @bullet
+@item
+Unpack the source distribution:
+
+@example
+gunzip -c octave-@value{VERSION}.tar.gz | tar xf -
+@end example
+
+@item
+Change your current directory to the top-level directory of the source
+distribution:
+
+@example
+cd octave-@value{VERSION}
+@end example
+
+@item
+Make the binary distribution:
+
+@example
+make binary-dist
+@end example
+
+This will create a compressed tar file ready for distribution.
+It will have a name like
+@file{octave-@value{VERSION}-@value{TARGETHOSTTYPE}.tar.gz}
+@end itemize