Return to 0INSTALL CVS log

Up to [local] / OpenXM_contrib / gnuplot

Import gnuplot 3.7.3

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

   This document is divided into four 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 explains in detail how --with-PACKAGE=PATH
works, and how this option interacts with --libdir and --includedir.
Part four addresses some platform specific problems and testing issues.
There are also some hints how to build gnuplot with pre-ANSI C compilers.
Part five finally describes a few graphical front ends for gnuplot.

 The description of preprocessor options previously found here has been
moved to a new file called 0PORTING. Generic installation instructions
for `configure', such as distributed with FSF/GNU packages, have been
moved to the file INSTALL.gnu.

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.

   There's a special section in term.h to be used by 16bit DOS or Windows
builds of gnuplot.  This preselection is necessary because it's quite
hard to squeeze a sufficient set of drivers through the many 64K 
barriers imposed by 16bit environments.  For any driver you add
in this selection, you'll quite probably have to remove some other one.

   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 files where the runtime location is defined at compile time are
gnuplot.gih and show.c. 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
   gnuplot will look for the online help file, gnuplot.gih, in /gnuplot/share.
   Attention: This option affects the location of *all* installed files!

 o with configure's --datadir= option, eg.
   ./configure --datadir='/gnuplot/docs'
   gnuplot will look for the online help file, gnuplot.gih, in /gnuplot/docs.

 o at make time, eg.
   make HELPFILE='/gnuplot/docs/gnuplot.gih'
   gnuplot will look for the online help file /gnuplot/docs/gnupot.gih.

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

   The default location of the executables can be controlled in different
ways:

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

 o with configure's --bindir= option, eg.
   ./configure --bindir='/gnuplot/bin'
   gnuplot will be installed as /gnuplot/bin/gnuplot.

 o at make time, eg.
   make BINDIR='/gnuplot/bin'
   gnuplot will be installed as /gnuplot/bin/gnuplot.

   If the executables are not installed in the default location, files
written by the `save' command cannot be used as scripts on Un*x platforms.
There is no way to specify the location of the executables during
runtime. Other platforms are not affected by this. 

   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
[ Optionally run demos--see "How to test gnuplot" below. ]
$ make install

   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)
$ env CC=c89 ./configure
 
   Any environment settings for CFLAGS are included into the Makefile,
so please make sure that these are really needed.
 
   There are several options available for configure that you may want
to change.  A complete list of options is available through

$ ./configure --help

   The options relevant to gnuplot are listed below:

  --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]
  --with-x (*)            use the X Window System
  --with-lasergnu         install lasergnu printer script
  --with-linux-vga        use the Linux SVGA console driver
                          (requires /usr/lib/libvga)
  --with-readline (*)     use the builtin minimal readline function (default)
  --without-readline      do not use the builtin readline function
  --with-readline=gnu     use the GNU readline library
  --with-readline[=PATH]          Specify the location of GNU readline
  --with-gd[=PATH]        enable gif terminal with Tom Boutell's gd library
                          (requires GD library)
  --with-plot[=PATH]      use the Unix plot library
  --with-png[=PATH] (*)   enable png terminal
                          (requires libpng and libz)
  --with-pdf[=PATH]       enable pdf terminal 
                          (requires PDFLib)
  --with-cwdrc            check current directory for .gnuplot file,
                          normally disabled for security reasons
  --enable-ggi            enable ggi driver (EXPERIMENTAL)
  --enable-iris           enable IRIS terminal (IRIS4D only)
  --enable-mgr            enable MGR terminal
  --enable-rgip           enable Redwood Graphics Interface Protocol

 Options marked with (*) are enabled by default, ie. these features or
packages are used if configure detects 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' disables checking for PACKAGE. It has the same
   effect as `--without-PACKAGE'.
 o `--with-PACKAGE=PATH' checks 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
---

   John Hasstedt <John.Hasstedt@sunysb.edu> has written configure.vms,
a command file that creates the necessary make and option files to build
gnuplot.  See the file for instructions on using it.  If you have problems
with it, the old build files are still included; instructions for using
them follow.

   On VMS, you can use MMS, MMK, or another make utility, or you can
use BUILDVMS.COM.  The supplied files work with Alpha/VMS V6.2 and
DECC V5.7; you may get warnings or more serious errors depending on
the versions of the C compiler, the C run-time libraries, and VMS on
your system.

  To compile using MMK:
     MMK/DESCRIPTION=MAKEFILE.VMS
  To compile using MMS on VAX:
     MMS/DESCRIPTION=MAKEFILE.VMS
  To compile using MMS on Alpha:
     MMS/DESCRIPTION=MAKEFILE.VMS/MACRO=__ALPHA__=1

  Alternatively, you can use MAKE_VMS.COM.  This command file will run
MMK or MMS to build gnuplot.  If you don't have either one installed, it
will use the command file.  The first parameter on the command line is
the compiler you want to use (default DECC).

  It may sometimes be useful to add  `/IGNORE=WARNING' to the `MMS' call.

  To compile using GNUC or VAXC:
     add /MACRO=GNUC or /MACRO=VAXC to the above command
  To compile with another make utility:
     check the documentation of your utility to specify the description
     file and any necessary macros (__ALPHA__, GNUC, or VAXC)
  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, 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
      You can also copy makefile.amg to smakefile and just type `smake'.

      At the beginning of makefile.amg 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
      png graphics as well as gif support. Use the appropriate settings
      for CPU and MATH to compile for a specific machine type.
      Be sure to enable only those devices for which you have the 
      necessary software already installed. Also ensure that the
      libraries and the sources are all compiled using the same
      settings for CPU and MATH.
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
----------

Common for all Windows builds: The program doesn't need to be installed
specially.  Just copy all the relevant files mentioned a single directory,
and you're done.  You'll probably want to generate a desktop icon 
(program manager group/icon, desktop shortcut, or Start->Programs menu
entry) for wgnuplot.exe or wgnupl32.exe, and optionally register
wgnuplot/wgnupl32 as the program to open plot script file with.
Suggested filename extensions would be *.plt or *.gpl. 

Using Microsoft C 7.0 and compiling for 16bit MS-Windows (3.x, WfW)
      copy makefile.msw makefile
      nmake
  Put wgnuplot.exe, wgnuplot.dll, wgnuplot.hlp and wgnuplot.mnu
  in some directory.

Using Borland C++ 3.1 and compiling for 16bit MS-Windows (3.x, WfW)
      copy makefile.win makefile
  Edit makefile to change TC, and check other possible options to set.
  You may want to edit the 16bit-only section of term.h to select a
  different set of terminal drivers.
      make
  Put wgnuplot.exe, wgnuplot.dll, wgnuplot.hlp and wgnuplot.mnu
  in some directory.

Using Borland C++ 4.52, C++ Builder 1.0 or the "free" command line
version 5.5, compiling for 32bit MS-Windows (XP/2K/NT/95/98/ME)
      copy makefile.win makefile
  Edit makefile to change TC, LINK32, RUNTIME_LIB and other 
  configuration options as documented in the makefile itself. 
      make -DWIN32=1
  Copy wgnupl32.exe, wgnuplot.hlp and wgnuplot.mnu to some directory.

Using Visual C++ and compiling for 32bit Windows (XP/2K/NT/95/98/ME)
      nmake -f makefile.nt
 or
      copy makefile.nt makefile
      nmake

Using the MinGW32 port of GCC, plus the Microsoft Help Compiler (part
of the "Platform SDK", but also available individually): 
      copy makefile.mgw makefile
  Look through the Makefile to see if you need to make any changes.
      make 
  Optionally check the target directory in the makefile and
      make install

Using the Cygwin port of GCC, which includes MinGW32. Again, you need the
MS Help Compiler in addition to a reasonably complete Cygwin install.
      copy makefile.cyg makefile
  Look through the Makefile to see if you need to make any changes.
      make
  Put wgnuplot.exe, wgnuplot.hlp and wgnuplot.mnu
  in some directory.


MSDOS
-----

Using DJGPP
  Basically the same as Unix+configure. Andris Pavenis <pavenis@lanet.lv>
  has contributed a shell script which makes the whole process even easier:
  just run djconfig.sh, and then make.
  For novices, it is recommended to use makefile.dj2 instead:
      copy makefile.dj2 makefile
  Optionally check and adapt the makefile to turn on additional features.
      make
  or even simpler
      make -fmakefile.dj2

Using Microsoft C 7.0.
      copy makefile.msc makefile
      nmake 

Using Borland C++ 3.0 or 3.1
      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).
  Optionally edit the 16-bit special selection of terminal drivers in
  term.h if you need any driver that isn't part of the default collection.
      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). You should also have
GNU Make and IBM's 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).
Support for these two terminals is provided by additional
executables.
Be sure to enable only those devices for which you have the 
necessary software already installed. Also ensure that the
libraries and the sources are all compiled (not) using
the '-Zmt' flags.

Executing 
  make -f makefile.os2
should create a default build while
  make -f makefile.os2 help
will show you all pre-defined targets.

See other sections of the manuals for more information about
installing/using 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 creating dynamically linked executables for the X11 Window System, it
may be necessary to add flags to the LIBS variable in Makefile
to make sure gnuplot finds all required libraries at runtime.  Systems like
SunOS and Solaris use -R to specify the runtime library search path, whereas
OSF/Dec Unix, Irix and Linux use -rpath. If this is not possible, the
LD_LIBRARY_PATH environment variable should be set.

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

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

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

 In gnuplot, the following --with-PACKAGE options are available:

  --with-readline

   Use gnuplot's builtin readline function. This is enabled by default.

  --without-readline

   (same as --with-readline=no) Do not use gnuplot's builtin readline function.

  --with-readline=gnu

   Use the GNU readline library instead of gnuplot's builtin readline.

  --with-readline[=PATH]

   Use the GNU readline library instead of gnuplot's builtin readline.
   This form is required if GNU readline is not installed in a default
   location.

  --with-gd[=PATH]

   Dto. for Thomas Boutell's gd library. This option is off by default,
   as the developers want to encourage users to use the png format instead
   of gif.

  --with-png[=PATH]

   Dto. for the png library. This option is on by default.

  --with-pdf[=PATH]

   Dto. for the pdf library. This option off on by default.

  --with-plot[=PATH]

   If used without the PATH argument, this option selects the standard
   UNIX plot library, if available. If used with the PATH argument,
   configure looks for the plot library from GNU plotutils. Version 2.2
   or better is required. The option is off by default.

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

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

Platform and compiler 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'
should work, though).

 - gcc -ansi
   If you wish to compile with gcc -ansi (CC='gcc -ansi -pedantic'
  ./configure), additional platform specific defines may be necessary
  to include non-ANSI function prototypes. E.g. on Solaris, -D__EXTENSIONS__
  is needed. Otherwise, non-declared functions not returning int will be
  assumed to return int, with possibly dangerous consequences. Especially
  scpecfun.c is vulnerable here.

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

 - HP-UX 10.x and above
   GCC has known problems on this platform if configured to use HP's
  assembler. The telltale symptom are tic labels all ending up at
  position 0.0. So either make sure you use a GCC configured to use
  GNU as, or use HP's ANSI cc (the unbundled one).

 - 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. Note that you need be very careful to select the
  correct compiler options/ABI's.

 - 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 for Unix (with configure).

 - SunOS 4.x
   An ANSI/ISO C compiler should be used 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.
  See entry below for instructions.

  As of 1998-11-18, gnuplot compiles again with the native compiler cc.

 - System V.2/Ultrix 4.x/M88 SysV.3
   An ANSI/ISO C compiler should be used 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/unproto5.shar.Z
  ftp://ftp.porcupine.org/pub/lang/unproto5.shar.Z

  After installing unproto, configure gnuplot with

  (Bourne shell syntax)

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

  or (C shell syntax)

  $ cd gnuplot-3.7.3
  $ env CC='cc -B/full/path/to/unproto/dir/ -tp' ./configure <options>

  The required compiler options shown here are for System V.2.  For other
  platforms, consult the unproto documentation. `/full/path/to/unproto/dir'
  is the full path name of the directory where unproto is installed. It is
  not necessary to "install" unproto, one can just create a subdirectory
  in gnuplot's source directory and use it from there.

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 interactively by eg.

$ cd gnuplot/demo
$ PATH=..:$PATH ../gnuplot simple.dem

and gnuplot prompts the user to "Hit return to continue" to cycle
through all the plots.  (The PATH= statement is only required if you are 
using the X11 plotting device and the gnuplot_x11 binary has not been
installed yet.)

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

$ PATH=..:$PATH ../gnuplot simple.dem </dev/null

   To run all demos non-interactively, use

$ PATH=..:$PATH ../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.7 patchlevel 2
        last modified Sat Jan 19 15:23:37 GMT 2002

        Copyright(C) 1986 - 1993, 1993, 1998 - 2002
        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.

Front Ends for gnuplot
======================

 o Xgfe by David Ishee <dmishee@jasper.he.net>, available from
   http://von-mises.home.ml.org/xgfe/xgfe.html
   To compile from source, you need Qt library from
   http://www.troll.no/.

 o Bruce Ravel <ravel@phys.washington.edu> has written a new version of
   gnuplot-mode for GNU emacs and XEmacs. This version is based on
   the gnuplot.el file by Gershon Elber which is included with this
   distribution. The package is available from
   http://feff.phys.washington.edu/~ravel/gnuplot/.
   Future distributions of gnuplot will hopefully include Bruce's
   version.