From f8b2bf8e57bc513f4e52e94043ecde6806f064f5 Mon Sep 17 00:00:00 2001 From: lhecking Date: Sat, 27 Mar 1999 14:56:08 +0000 Subject: [PATCH] Renamed from 0INSTALL. --- INSTALL | 630 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 630 insertions(+) create mode 100644 INSTALL diff --git a/INSTALL b/INSTALL new file mode 100644 index 000000000..790b347fa --- /dev/null +++ b/INSTALL @@ -0,0 +1,630 @@ +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 GNUPLOT_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 + + 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-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-history enable history (requires GNU readline) + --enable-thin-splines enable thin plate splines (EXPERIMENTAL) + --enable-iris enable IRIS terminal (IRIS4D only) + --enable-mgr enable MGR terminal + --enable-rgip enable Redwood Graphics Interface Protocol + --with-x (*) Use the X Window System + + 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 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 + 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 described method of finding library and header files using the +--with-package configure option 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 or no; default set in configure +--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. It is probaly impossible to write such a test suite, because +it would need to cover all possible variations allwed by gnuplot's +command language, or a significant subset thereof. +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 or BeOS plotting device and the gnuplot_x11/gnuplot_be +binary has not been installed yet, or you want to test the external +binaries you just compiled at the same time). + + 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 + To compile from 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/. + Future distributions of gnuplot will hopefully include Bruce's + version. +