Installation
************

   This document is divided into five parts: the first part (For the
impatient) provides a quick overview of configuration and compilation
instructions.  It also lists those options to the configure shell script
which are unique to gnuplot.  Part two describes the environment variables
used by gnuplot.  Part three (Basic Installation) describes generic
installation instructions, which are common between most packages using
GNU autoconf.  Part four explains in detail how --with-PACKAGE=PATH
works, and how this option interacts with --libdir and --includedir.
Part five addresses some platform specific problems and testing issues.
There are also some hints how to build gnuplot with pre-ANSI C compilers.

 The description of preprocessor options previously found here has been
moved to a new file called 0PORTING.

For the impatient
=================

   First, tune term.h to choose which terminal drivers you wish to enable.
If you want to support gif output, you need to download, compile and
install the gd library : see term/gif.trm for details.

   If you want to support png output (free gif alternative), you need
png and z libraries : see term/png.trm for details.  Note that the
png library will probably not compile without an ANSI/ISO C compiler.

   A complete overview of configure options is below in the Basic
Installation section. On platforms which do not support GNU
autoconf/configure, ie. most non-Unix platforms, look for a makefile
that looks suitable, (makefile.emx for emx on dos, makefile.nt for
MS VC++ 4.x on NT and probably win95, makefile.win for borland c on
win95/nt, makefile.wc for DOS Watcom C etc.)

File location defaults
----------------------

PREFIX                          /usr/local
gnuplot                         PREFIX/bin
gnuplot_x11                     PREFIX/bin
gnuplot.1                       PREFIX/man/man1
gnuplot.gih                     PREFIX/share

   The only file where the runtime location is defined at compile time is
gnuplot.gih. This is important if gnuplot is not installed by running
'make install'. The default path for the help library, gnuplot.gih, can be
controlled in several different ways:

 o with configure's --prefix= option, eg.
   ./configure --prefix=/gnuplot
   Attention: This affects the location of *all* installed files!

 o with configure's --datadir= option, eg.
   ./configure --datadir='/gnuplot/docs'

 o at make time, eg.
   make HELPFILE='/gnuplot/docs/gnuplot.gih'

 o at execution time by specifying the helpfile with the environment
   variable GNUHELP (see "Environment Variables" below).

   The gnuplot demo files are not installed by default. If desired, they
should be copied manually to a location of choice.

Unix, configure
---------------

   On Unix, use
$ ./configure
$ make

   If gcc is installed, it is used by default. A different compiler can be
used through the CC environment variable:

(Bourne shell)
$ CC=c89 ./configure

(C shell)
$ setenv CC c89
$ ./configure
 
   There are several options available for configure that you may want
to change.  A complete list of options is available through

$ ./configure --help

  --prefix=PREFIX         Install architecture-independent files in PREFIX
                          [/usr/local]. The gnuplot (and gnuplot_x11) binary
                          is installed in PREFIX/bin.
  --bindir=DIR            user executables in DIR [PREFIX/bin]
  --datadir=DIR           Read-only architecture-independent data in DIR
                          [PREFIX/share]. The gnuplot help file is installed
                          in this directory.
  --libdir=DIR            object code libraries in DIR [EPREFIX/lib]
  --includedir=DIR        C header files in DIR [PREFIX/include]
  --mandir=DIR            Man documentation in DIR [PREFIX/man]
  --without-readline      Do not use the included readline function
  --with-gnu-readline     Use the GNU readline version  If you don't use this,
                          you won't have file name completion.
  --with-gnu-readline=PATH        Specify the location of libreadline.
                          Use this form if your libreadline is not installed
                          where your linker can find it.
  --with-plot             use the Unix plot library
  --with-plot=PATH                Specify the location of GNU libplot
  --with-gd (*)           Enable gif terminal with Tom Boutell's gd library
                          (requires GD library)
  --with-gd=PATH                  Specify the location of libgd
  --with-png (*)          Enable png terminal
                          (requires libpng and libz)
  --with-png=PATH                 Specify the location of libpng
  --with-cwdrc            Check current directory for .gnuplotrc file,
                          normally disabled for security reasons. However,
                          the home directory is always checked for a
                          .gnuplotrc file.
  --with-lasergnu         Install lasergnu printer script
  --without-linux-vga (*) Do not use the Linux console driver
                          (requires Linux SVGAlib /usr/lib/libvga)
  --enable-apollo         Apollo Graphics Primitive Resource
  --enable-gpr            Apollo Graphics Primitive Resource (fixed-size window)
  --enable-cgi            enable CGI terminal (SCO only)
  --enable-iris           enable IRIS terminal (IRIS4D only)
  --enable-sun            enable sunview terminal (Sun only)
  --enable-unixpc         enable unixpc terminal (ATT 3b1 or ATT 7300)
  --with-x (*)            Use the X Window System

 Options marked with (*) are on by default, ie. these features or packages
will be used if configure can detect them, even if the corresponding option
is not specified.  Please note that the `--with-PACKAGE' options can have
additional arguments:

 o `--with-PACKAGE' is equivalent to `--with-PACKAGE=yes'
 o `--with-PACKAGE=no' will disable checking for PACKAGE. It has the same
   effect as `--without-PACKAGE'.
 o `--with-PACKAGE=PATH' will check for PACKAGE in PATH

Unix, no configure
------------------

  The older, no-longer-preferred, way is to copy makefile.unx to Makefile
      cp makefile.unx Makefile
  Look through the Makefile to see if you need to make any changes.
  See especially the HELPDEST and TERMFLAGS variables.  Edit if needed.
  Alternatively, all these variables may be set as command line arguments to
  'make'. For example:

        make <MACHINE> HELPDEST='/usr/um/misc/lib' \
                DEST='/usr/um/misc/bin' READLINE=

  Type
      make
  For further instructions.
  If that works, try
      make install
  For further instructions.

VMS
---

   On VMS, invoke MAKE_VMS.COM (or BUILDVMS.COM if you have MMS or MMK
but don't want to use the supplied DESCRIP.MMS).  You may get warnings
or more serious errors depending on the versions of the C compiler, the 
C run-time libraries, and {Open}VMS on your system.  


  To compile using DEC MMS or MMK (PD clone),
     invoke MMS or MMK with the supplied descrip.mms
  Or if you have a unix-like make utility
     copy makefile.vms makefile
     make
  Or if you don't have a suitable make:
     @buildvms
  To tell gnuplot where to find the help library:
      $ define gnuplot$help disk:[directory]gnuplot.hlb
  Alternatively (and preferably) put the help in the main system help library.

AmigaOS
-------

Using Aztec C 5.2a
      make -f makefile.ami
Using SAS/C 6.1 or later versions
      smake -f makefile.amg
Using gcc: see Unix

Atari/TOS
---------

Using gcc 2.x as unix cross- or native compiler
	make -f makefile.st
(Edit top of makefile.st for name of crosscompiler or choose native setting)
Using PureC
	use gnuplot.prj
Using TurboC
	use gnuplot.prj
(Edit gnuplot.prj according to notes at the beginning)

MS-Windows
----------

Using Microsoft C 7.0 and compiling for MS-Windows
      copy makefile.msw makefile
      nmake
  Put wgnuplot.exe, wgnuplot.dll, wgnuplot.hlp and wgnuplot.mnu
  in the windows directory.

Using Borland C++ 3.1 and compiling for MS-Windows
      copy makefile.win makefile
  Edit makefile to change TC.
      make
  Put wgnuplot.exe, wgnuplot.dll, wgnuplot.hlp and wgnuplot.mnu
  in the windows directory.

MSDOS
-----

Using Microsoft C 7.0.
      copy makefile.msc makefile
      nmake 

Using Borland C++ 3.0
      copy makefile.tc makefile
  Edit makefile to change TC, BIN, BGI, BGIOBJ. You may also want to turn
  off overlays (See manual for more on overlays).
      make

The file gnuplot.gih is needed for help on the PC.
If the file gnuplot.gih is not in the default directory, then use:
    set GNUHELP={full path name of gnuplot.gih}

OS/2
----

To compile under OS/2 (2.x and above) you need the development
suite EMX 0.9 (including gcc). To build the complete set
of files you should also have GNUMake and IPFC (Information Presentation
Facility Compiler; available from the Developer's Toolkit; nowadays it's
accessible through an IBM website for free!).

At the beginning of Makefile.os2 you will find a configuration
section where you have to adjust all settings which control the build
process. Most important is probably to select the terminal devices
which should be supported. You can create a version offering
PM graphics as well as X11 support (to use with XFree86).
Be sure to enable only those devices for which you have the 
necessary software already installed!

Finally executing 
  make -f Makefile.os2
will show you all pre-defined targets.

See other sections of the manuals for more information about
installing gnuplot on OS/2.

Environment Variables
=====================

See 'help environment'.

If the environment variable GNUTERM is found, it is used as the terminal
type. Otherwise, in some cases the variable TERM will be used, or the
hardware may be automatically detected.

The PC version looks for the environment variable GNUPLOT to contain
the name of the directory from which to load the initialization file
GNUPLOT.INI.  See the help on 'start_up' for more information.

HOME is examined as a directory where a .gnuplot startup file might be
found. See help on "start-up".

If defined, the environment variable GNUHELP is used for the name
of the .gih help file, otherwise HELPFILE (defined in makefile or
command.c) is used.

The VMS version looks for the logical name GNUPLOT$HELP to locate
the help library.

The CGI drivers need the CGIPATH environment variable to set the path
to the CGI agents, and the CGIDISP and/or CGIPRNT environment variables
to set the output devices.

 If using dynamically linked executables with the X11 Window System, it
may be necessary to define LD_LIBRARY_PATH - see man ld for details.


Basic Installation
******************

   These are generic installation instructions.

   The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, a file
`config.cache' that saves the results of its tests to speed up
reconfiguring, and a file `config.log' containing compiler output
(useful mainly for debugging `configure').

   If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If at some point `config.cache'
contains results you don't want to keep, you may remove or edit it.

   The file `configure.in' is used to create `configure' by a program
called `autoconf'.  You only need `configure.in' if you want to change
it or regenerate `configure' using a newer version of `autoconf'.

The simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.  If you're
     using `csh' on an old version of System V, you might need to type
     `sh ./configure' instead to prevent `csh' from trying to execute
     `configure' itself.

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with
     the package.

  4. Type `make install' to install the programs and any data files and
     documentation.

  5. You can remove the program binaries and object files from the
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.  There is
     also a `make maintainer-clean' target, but that is intended mainly
     for the package's developers.  If you use it, you may have to get
     all sorts of other programs in order to regenerate files that came
     with the distribution.

Compilers and Options
=====================

   Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  You can give `configure'
initial values for variables by setting them in the environment.  Using
a Bourne-compatible shell, you can do that on the command line like
this:
     CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure

Or on systems that have the `env' program, you can do it like this:
     env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure

Compiling For Multiple Architectures
====================================

   You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory.  To do this, you must use a version of `make' that
supports the `VPATH' variable, such as GNU `make'.  `cd' to the
directory where you want the object files and executables to go and run
the `configure' script.  `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.

   If you have to use a `make' that does not supports the `VPATH'
variable, you have to compile the package for one architecture at a time
in the source code directory.  After you have installed the package for
one architecture, use `make distclean' before reconfiguring for another
architecture.

Installation Names
==================

   By default, `make install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc.  You can specify an
installation prefix other than `/usr/local' by giving `configure' the
option `--prefix=PATH'.

   You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If you
give `configure' the option `--exec-prefix=PATH', the package will use
PATH as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.

   In addition, if you use an unusual directory layout you can give
options like `--bindir=PATH' to specify different values for particular
kinds of files.  Run `configure --help' for a list of the directories
you can set and what kinds of files go in them.

   If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

Optional Features
=================

   Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System).  The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.

   For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.

Specifying the System Type
==========================

   There may be some features `configure' can not figure out
automatically, but needs to determine by the type of host the package
will run on.  Usually `configure' can figure that out, but if it prints
a message saying it can not guess the host type, give it the
`--host=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name with three fields:
     CPU-COMPANY-SYSTEM

See the file `config.sub' for the possible values of each field.  If
`config.sub' isn't included in this package, then this package doesn't
need to know the host type.

   If you are building compiler tools for cross-compiling, you can also
use the `--target=TYPE' option to select the type of system they will
produce code for and the `--build=TYPE' option to select the type of
system on which you are compiling the package.

Sharing Defaults
================

   If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.

Operation Controls
==================

   `configure' recognizes the following options to control how it
operates.

`--cache-file=FILE'
     Use and save the results of the tests in FILE instead of
     `./config.cache'.  Set FILE to `/dev/null' to disable caching, for
     debugging `configure'.

`--help'
     Print a summary of the options to `configure', and exit.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

`--version'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`configure' also accepts some other, not widely useful, options.

About --with-PACKAGE[=PATH]
***************************

 The following description applies to gnuplot only.

 Every `--with-PACKAGE' option sets a `with_package' variable in
configure.  Depending on how `--with-PACKAGE' was invoked, there are
only a few possible values for the `with_package' variable:

 Option                   $with_package
----------------------------------------
(not specified)           yes
--with-package            yes
--with-package=yes        yes
--with-package=no         no
--with-package=PATH       PATH
--without-package         no

 This means that configure will always (by default) try to locate PACKAGE
unless `--with-package=no' or `--without-package' was specified. Examples
for with-PACKAGE options used by gnuplot's configure are `--with-gd',
`--with-png'. The corresponding package variables are `with_gd',
and `with_png'.

 For gnuplot, configure uses the macros `gp_CHECK_LIB_PATH' and
`gp_CHECK_HEADER' to search for libraries and includes, resp.  These
macros are different from the standard GNU autoconf macros for this purpose,
`AC_CHECK_LIB' and `AC_CHECK_HEADER/S' (see autoconf manual). The
gp_XXX macros are closely tied to gnuplot, and cannot be used for other
packages without modification.

 The difference between these package specific macros and standard
autoconf macros is that they do search more than one (the default)
directory to determine the location of the specified file.

 Libraries will be searched in at least three, and up to five different
directories, depending on the PATH specified with `--with-PACKAGE=PATH':

 o the default linker path (this is really more than one directory)
 o /usr/local/lib, which is a fairly common place for 3rd party libs
 o the PATH directory, trailing `/lib/libPACKAGE.a' stripped off
 o the PATH directory, trailing `/lib/libPACKAGE.a' stripped off and
   `/lib' added
 o the PATH directory, trailing `/libPACKAGE.a' stripped off.

 Using the default linker path as the first search directory has one
big, but not so obvious advantage: if all libraries are in the same
directory, the path to the first library specified with --with-PACKAGE
is added to the linker path with an `-L' option.  The library searched
for with the next --with-PACKAGE option will now be found faster, because
only one additional directory is checked.  This is also true for header files.

 Example: the user has unpacked the gd library distribution into
/home/user/source/gd:

$ configure --with-gd=/home/user/source/gd

will search the following directories for libgd.a:

 o the default linker path
 o /usr/local/lib
 o /home/user/source/gd
 o /home/user/source/gd/lib
 o /home/user/source/gd

 Include files will be searched in at least two, and up to three different
directories, depending on the PATH specified with `--with-PACKAGE=PATH':

 o the default include path (can be more than one diretcory)
 o /usr/local/include, a fairly common place for 3rd party headers
 o the PATH directory, trailing `/lib/libPACKAGE.a' stripped off
 o the PATH directory, trailing `/lib/libPACKAGE.a' stripped off and
   `/include' added

 Caveat: the `gp_CHECK_HEADER' macro should only be used after the
corresponding `gp_CHECK_LIB_PATH' macro to take full advantage of the
search algorithm.  This is a reasonable assumption nevertheless, because
it allows for structuring configure.in so that the test for a header file
is skipped if the corresponding library is not found.

 Here are some more examples:

 o the gd and png libraries are in /usr/local/gnu/lib, which is
   automatically searched by gcc.  The corresponding header files are
   in /usr/local/gnu/include, which is not in gcc's include search path.
   Solution:

   $ ./configure --with-gd=/usr/local/gnu

 o the gd and png libraries are in /opt/gnu/lib, the header files are
   in /opt/gnu/include.  Solution:
 
   $ ./configure --with-gd=/opt/gnu

 o the gd and png libraries and headers are all in different directories,
   none of which is in the compilers search path:

   $ ./configure --with-gd=/tmp/gd --with-png=/tmp/libpng

[I would like to implement the more generic `--site-includes' and
`--site-libraries' options for additional flexibility, but this is
painfully difficult with the current autoconf.  It also seems that such
a feature would not comply with GNU coding standards.]

Platform problems and testing
*****************************

   This section addresses trouble shooting and testing issues. Userland
questions are answered in the FAQ.

Platform notes
==============

   Generally, if you think that configure has made a mistake in detecting
platform features, there are two ways to switch these off. 

   Example:
configure was for some reason unable to detect the memset() function, but
you are sure it is ok to use on your platform. Now you can either edit
config.cache and change

 ac_cv_func_memset=${ac_cv_func_memset='no'}  to
 ac_cv_func_memset=${ac_cv_func_memset='yes'}  

and rerun configure, or, edit config.h and change

/* #undef HAVE_MEMSET */ to
#define HAVE_MEMSET 1

   Note that changing such defines at compile time, eg. via
'make DEFS=-DHAVE_MEMSET' is wrong, because the DEFS variable in Makefile
may contain other defines (make DEFS='-DHAVE_CONFIG_H -DHAVE_MEMSET'
may work, though).

 - HP-UX 9.x
   It is recommended to use gcc, although the native compiler may
  work with warnings.

 - HP-UX 10.x
   It is recommended to use the native compiler cc, as problems
  have been reported when using gcc. This will be looked at in the
  near future.

 - IRIX 6.x
   If you want to use the png terminal, you must install your own
  versions of libpng and zlib. The versions supplied with the OS
  are too old.

 - MS-DOS
   If ports of common Unix utilities (bash, sed etc) are available,
  gnuplot can be built with DJGPP. Install instructions are the same
  as under Unix (with configure).

 - SunOS 4.x/System V.2/Ultrix 4.x/M88 SysV.3
   An ANSI/ISO C compiler is reqiured to compile gnuplot. It is
  recommended to install gcc. If this is not an option, the system
  compiler cc can be made to work with Wietse Venema's unproto tool.

  unproto is available from
  ftp://ftp.win.tue.nl/pub/unix/unproto4.shar.Z
  ftp://ftp.porcupine.org/pub/lang/unproto5.shar.Z

  After installing unproto, configure gnuplot with

  (Bourne shell syntax)

  $ cd gnuplot
  $ CC='cc -Qpath /full/path/to/unproto/dir' ./configure <options>

  or (C shell syntax)

  prompt (41) cd gnuplot
  prompt (42) setenv CC 'cc -Qpath /full/path/to/unproto/dir''
  prompt (43) ./configure <options>

  The `-Qpath path' option shown here is for SunOS 4.x. For other
  platforms, check the unproto documentation. `/full/path/to/unproto/dir'
  is the full path name of the directory where unproto is installed.
 
How to test gnuplot
===================

   No comprehensive test suite for gnuplot's features has been written
to date. However, the supplied demo files provide a good method of
testing commonly used features. All command line examples below assume
Unix Bourne shell syntax.

   The demo files can be run by eg.

$ cd gnuplot/demo
$ ../gnuplot simple.dem

and gnuplot prompts the user to "Hit return to continue" to cycle
through all the plots.

   To run the demos in a specified file without interaction, one
can use

$ ../gnuplot simple.dem </dev/null

   To run all demos non-interactively, use

$ ../gnuplot all.dem </dev/null

   To use a different plotting device than the default (usually X11
under Unix), use eg.

$ GNUTERM=dumb ../gnuplot all.dem </dev/null

   To test the capabilities of the terminal you are using, there is
the 'test' command:

$ gnuplot

        G N U P L O T
        Unix version 3.5 (pre 3.6)
        patchlevel beta 347
        last modified Mon Jun 22 13:22:33 BST 1998

        Copyright(C) 1986 - 1993, 1998
        Thomas Williams, Colin Kelley and many others

        Send comments and requests for help to info-gnuplot@dartmouth.edu
        Send bugs, suggestions and mods to bug-gnuplot@dartmouth.edu

Terminal type set to 'x11'
gnuplot> test

   `test` creates a display of line and point styles and other useful things
appropriate for the terminal you are using.

