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. 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) $ setenv 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 --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-readline (*) use the builtin minimal readline function --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-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 .gnuplot file, normally disabled for security reasons --with-lasergnu install lasergnu printer script --with-linux-vga use the Linux SVGA console driver (requires /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) --enable-system-time use the system time routines in time.c --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 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, 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 ---------- 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. Using Visual C++ and compiling for Windows NT/95/98 nmake -f makefile.nt or copy makefile.nt makefile nmake Using the MinGW32 port of egcs: you need the Micrsoft SDK for the moment. copy makefile.mgw makefile Look through the Makefile to see if you need to make any changes. make make install Using the Cygwin port of gcc, which includes MinGW32: you need the Micrsoft SDK for the moment. copy makefile.cyg makefile Look through the Makefile to see if you need to make any changes. make Put wgnuplot.exe, wgnuplot.dll, wgnuplot.hlp and wgnuplot.mnu in the windows directory. MSDOS ----- Using DJGPP Basically the same as Unix+configure. Andris Pavenis 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 make 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). 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] *************************** 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 three different 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_SEARCH_LIBDIRS' and `gp_SEARCH_HEADERDIRS' 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 a `-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_SEARCH_HEADERDIRS' macro should only be used after the corresponding `gp_SEARCH_LIBDIRS' 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' should work, though). - HP-UX 9.x It is recommended to use gcc, although the native compiler cc 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. In the cases reported, we have yet to establish whether the compiler is at fault, or the compiler setup/configuration is broken. - 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 $ CC='cc -B/full/path/to/unproto/dir/ -tp' ./configure or (C shell syntax) prompt (41) cd gnuplot prompt (42) setenv CC 'cc -B/full/path/to/unproto/dir/ -tp' prompt (43) ./configure 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 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 , available from http://von-mises.home.ml.org/xgfe/xgfe.html If you download the source, you need Qt library from http://www.troll.no/ o Bruce Ravel 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/