INSTALL

Table of contents:
==================

    * Installation from sources
    * Use of ./configure script to customize your build
    * More details about ./configure --with-PACKAGE[=OPTION]
    * Inclusion of optional features --enable-FEATURE
    * Platform-specific tips
        linux Ubuntu
	macOS homebrew
	Windows MSDOS
	OS/2 and WPS
    * Environment variables
    * How to test gnuplot

If you are installing a binary package, you may still want to check out
some sections of this document, particularly the sections at the end
about environment variables and testing gnuplot after installation.


Installation from sources
=========================

For the impatient
-----------------

   Configuration options are in the Makefile and in src/term.h, where you
select additional terminal drivers to be compiled in.

   The recommended way to configure both of these is the GNU-style
"./configure" script described below and described further in INSTALL.gnu.
This script is provided as part of the distributed source package, but if you
are using sources downloaded directly from a code repository you may need to
regenerate it using the preliminary script "./prepare".

  The ./configure script inspects your system to see what support libraries
are available, then modifies the gnuplot Makefile and header file config.h
to use them.  Assuming you have already installed the necessary support
libraries, the process is:

      ./configure              # prepare Makefile and config.h
      make                     # build the program and documentation
      make check               # run unit tests to confirm successful build
      make install             # install the program and documentation


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

PREFIX                          /usr/local
gnuplot                         PREFIX/bin
gnuplot_x11                     PREFIX/libexec/gnuplot/$VERSION
gnuplot_qt                      PREFIX/libexec/gnuplot/$VERSION
gnuplot.1                       PREFIX/man/man1
gnuplot.gih                     PREFIX/share/gnuplot/$VERSION
terminal support files          PREFIX/share/gnuplot/$VERSION/js
                                PREFIX/share/gnuplot/$VERSION/PostScript
                                PREFIX/share/gnuplot/$VERSION/lua
                                PREFIX/share/gnuplot/$VERSION/qt


   The default path for the help library, gnuplot.gih, can be controlled in
several different ways:

 o use configure's --with-gihdir option to specify the full path to the
   directory where gnuplot.gih is to be installed, e.g.
   ./configure --with-gihdir=/opt/docs

 o use configure's --datadir= option to specify a version and package
   independent data dir prefix, e.g.
   ./configure --datadir='/opt/docs'
   gnuplot will look for the online help file, gnuplot.gih, in
   /opt/docs/gnuplot/$VERSION.

 o with configure's --prefix= option, eg.
   ./configure --prefix=/gnuplot
   gnuplot will look for the online help file, gnuplot.gih, in
   /gnuplot/share/gnuplot/$VERSION.
   Attention: This option affects the location of *all* installed files!

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

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

   The default location of the main executable 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.

   The default location of the additional executables, including gnuplot_x11
   and gnuplot_qt, can be controlled in different ways:

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

 o with configure's --libexecdir= option, eg.
   ./configure --libexecdir='/gnuplot/lib'
   gnuplot_x11 will be installed as /gnuplot/lib/gnuplot/6.0/gnuplot_x11

 o at make time, eg.
   make X11_DRIVER_DIR='/gnuplot/lib/6.0'
   gnuplot_x11 will be installed as /gnuplot/lib/6.0/gnuplot_x11

   If you don't install the program at the place chosen by ./configure,
e.g. by overriding the "prefix" at "make install" time, files written
by the `save' command cannot be used as self-executing scripts on Un*x
platforms (but they still work as input scripts to gnuplot).

   The gnuplot demo files are not installed by default, mainly because
there is no universally agreed place where such files should go.
If desired, they should be copied manually to a location of choice.


Use of ./configure script to customize your build
=================================================

   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 by passing its name to configure:

$ ./configure CC=clang CXX=clang++

   Any environment settings for CFLAGS and CXXFLAGS are included into the
Makefile, so please make sure that these are appropriate.  Example:

$ export CXXFLAGS="-Wall -g -Og -fPIC -std=c++11"

   There are several options available for configure that you may want
to change.  A complete list of options is available through

$ ./configure --help

   Many of the available options are generic to programs built with the
   autotools/autoconf build system.  A few example options specifically
   relevant to gnuplot are shown below:

  --with-readline={gnu|bsd|builtin}
			  Override the automatic choice of terminal input modes.
			  See below for more detail.

  --disable-history-file  do not use history file
  --without-latex         do not install latex support files
  --with-textdir=DIR      where to install latex support files

  Source files for many older terminal types, legacy output modes, and
hardware or platform-specific devices are included in the distribution.
These can be included in the gnuplot executable by selecting a corresponding
configure option.  For example to build in support for physical terminals or
terminal emulators that accept Tektronix graphics protocols (1970s-1980s),
and also build in support for a large set of 1990s era dot matrix printers
(HP deskjet, epson, tandy, etc):

  ./configure --with-tektronix --with-bitmap-terminals

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=DIR' checks for PACKAGE in DIR


More details about ./configure --with-PACKAGE[=OPTION]
======================================================

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=DIR        DIR
--without-package         no

In gnuplot, the following --with-PACKAGE options are available. The
--with-PACKAGE=DIR form is always required if a package is installed in a
non-default location that is not searched by the preprocessor or linker.

  --with-readline

   Use whatever readline support is detected automatically, either an
   external library or gnuplot's built-in version. This is the default.

  --with-readline=builtin

   Use gnuplot's own builtin readline routines even if a GNU or BSD readline
   library is detected.

  --without-readline

   (same as --with-readline=no) Do not use any readline processing.

  --with-readline=gnu

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

  --with-readline[=DIR]

   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[=DIR]

   Thomas Boutell's gd library is needed to support jpeg and gif output.
   It is also one of several options for producing png or sixel output.
   This option is on by default, i.e. configure will check if the library exists
   and use it if found.

   The gd library is also use to read in png, jpeg, or gif image files.
   If libgd is not found or if you configure --without-gd the configure script
   will fall back to looking for libstbi instead, which provides an alternative
   means of reading (not writing) image files.

  --with-amos=DIR
  --with-libcerf

   Gnuplot includes support for additional complex special functions provided
   by one or more of the external libraries libcerf, libamos, or libopenspecfun.
   The ./configure script will search for these in standard system library
   locations and include support for the routines that are found.
   These libraries are relatively uncommon, however, so you might want to
   build them separately and tell the ./configure script where they are
   using for example --with-amos=/usr/local/lib/
   If these libraries are not found, gnuplot will configure and build
   successfully but it will not provide the corresponding special functions.


Inclusion of optional features
==============================

Each release of gnuplot may include features that are experimental or of
limited general interest.  These may be optionally included or excluded
from the configuration using the --enable or --disable flags.
Examples from gnuplot 6 include

  --enable-watchpoints      support setting watchpoints in 2D plots
  --enable-function-blocks  support defining a function as a here document

These features may become standard in a subsequent release and will then
no longer require a special configuration option.


Platform-specific tips
======================

Linux
-----
	
  lua: ./configure may fail to find lua support if the package configuration
  tool is installed as "lua5.1" or "lua5.3" rather than "lua".  If necessary,
  you can fix this by adding a symlink prior to running ./configure

	ln -s /usr/lib/pkgconfig/lua5.3.pc  /usr/lib/pkgconfig/lua.pc

  wxt: Some wxWidgets configurations require linking to the X11 library but
  fail to include "-lX11" in the string provided for auto-configuration.
  You may have to add this manually when configuring gnuplot:
      TERMLIBS="-lX11" ./configure
  Note that some people have reported runtime problems with wxgtk 3.0.
  If you have the option of linking to libraries for wxgtk 2.8 instead,
  this may be preferable.  The -lX11 flag is not need in this case.

Ubuntu
------

  These instructions were tested on Ubuntu 22.04

  Install build tools, libraries, and documentation tools (TeX) for
  building gnuplot binary (5.4.2).
	sudo apt build-dep gnuplot

  Install additonal tools and libraries for development version

	sudo apt install gfortran libcerf-dev libwebp-dev adwaita-icon-theme-full \
		unzip texlive-science

        # openspecfun provides the Amos routines (except for cexint)
	git clone /~https://github.com/JuliaMath/openspecfun.git
	cd openspecfun
	make
	sudo make install

  Add the below to ~/.profile
	export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

  install picins.sty to LaTeX

	wget https://mirrors.ctan.org/macros/latex209/contrib/picins.zip
	unzip picins.zip
	sudo cp -pR ./picins /usr/share/texlive/texmf-dist/tex/latex
	sudo texhash

  git clone, build, install and documantation

	git clone https://git.code.sf.net/p/gnuplot/gnuplot-main gnuplot-dev
	cd gnuplot-dev
	# change configure line according to your condition
	./configure --enable-function-blocks
	make
	sudo make install
	make check
	# gnuplot.pdf
	make pdf

Mac OSX
-------

  Readline: As I understand the situation, OSX ships with a "fake" libreadline
  shared library. The file /usr/lib/libreadline.dylib is really a symlink to a
  compatibility layer over the BSD libedit library.  But the compatibility is not
  complete. The ./configure script should be able to cope with this, but you
  may be left without some of the functionality of the "real" libreadline.
  If you find that libedit does not work for you, there are several options:

  1) Delete the fake libreadline libraries from OSX and install
  the real gnu libreadline as a system library.

  2) Install the real gnu libreadline into your personal account and
  tell gnuplot to use it:
  ./configure --with-readline=/my/private/readline/installdir
  This may require some playing around with additional -L and -I
  definitions in CFLAGS, and is probably harder than replacing the
  system copy of the library.

  3) Use gnuplot's built-in readline routines.  These now support UTF-8
  input and tab-completion of file names.
  ./configure --with-readline=builtin

  wxt: This interactive terminal is in principle cross-platform and you
  needn't do anything special.  However if you discover that practice
  diverges from principle, the notes below collected from problems
  encountered in the past might help.

  Cairo & pango need to be installed first on Mac,
  I recommend using MacPorts building universal (i386 libraries):
  sudo port install cairo +no_x11 +quartz +universal
  sudo port install pango +no_x11 +quartz +universal

  Next gnuplot may be compiled with Mac OS X 10.6 SL wxWidgets using:
  ./configure CPPFLAGS='-arch i386' LDFLAGS='-arch i386'

  NOTE: 10.6 SL by default generates x86_64 code, but wxWidgets stable is using
  Carbon API on Mac which is 32-bit only, that makes compiling gnuplot,
  cairo and pango to i386 necessary.

macOS + homebrew
----------------

  As of the time of writing (Feb 2023) homebrew provides a bottled gnuplot
  with Qt support.  However it was not built with all the optional features
  or terminals that you might want.  This is a quick summary of what is
  needed to configure and build from source.

  If you have gnuplot installed from homebrew you can do
	brew info gnuplot
  to see that it has already installed these dependencies:
	Build: pkg-config ✔
	Required: gd ✔, libcerf ✔, lua ✔, pango ✔, qt@5 ✔, readline ✔
  Otherwise you must install these first.  Depending on what you intend to
  add to the configuration you may have to install other dependencies also.

  Gnuplot's default ./configure and make will automatically compile gnuplot
  support for the x11 terminal and for the qt terminal if it finds the Qt
  libraries.  However, it seems that the Qt installed by homebrew is not
  found automatically.   If you say, for example,  ./configure --with-qt
  you get a problem like "fatal error: 'QtCore' file not found".
  To solve this you can add the homebrew installation path to the environment
  prior to running ./configure so that it knows where to look:

	$ CXXFLAGS=' -std=c++11 ' \
	  PKG_CONFIG_PATH='/opt/homebrew/opt/qt5/lib/pkgconfig' \
	  configure --with-qt

  If for some reason your qt5/lib/pkgconfig is installed somewhere else,
  change that command accordingly.

  Look carefully at the summary of terminal support printed out by the
  configure command.  If all looks well, continue with

	$ make
	$ make check
	$ sudo make install

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

We provide binary packages on SourceForge, either as a self-installing
executable or as a "portable" version packed in 7z format.

We currently support and test building with the following compilers and
Makefiles:

    Mingw-w64/MSYS2: config/mingw/Makefile
    Microsoft Visual C++: config/msvc/Makefile
    OpenWatcom: config/watcom/Makefile
    Cygwin: config/cygwin/Makefile

These Makefiles contain a configuration section which you have to
adopt to your actual setup.  Further building instructions are given in Makefiles.
For MSYS2/Mingw-w64 you can find detailed instructions at
https://sourceforge.net/p/gnuplot/support-requests/199/
Some of the Makefiles include an "install" target (e.g. config/mingw/Makefile).

In order to build the help file you require the "Microsoft HTML Help Workshop",
which is freely downloadable here:
https://www.helpandmanual.com/downloads_mscomp.html

MSDOS
-----

Using DJGPP (32-bit DOS port of GNU CC)
  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.
  Only if you don't have a complete Unix toolset installed with your
  DJGPP, it is recommended to use makefile.dj2 instead:
      copy makefile.dj2 makefile
      make

[NOTE: the 16-bit DOS versions of gnuplot no longer work.  gnuplot has
outgrown this platform.]

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.

WPS object for gnuplot on OS/2
------------------------------

GNUPLOT can be run from the command line of an OS/2 session, or can be set up
as a program object in the WPS.

GNUPLOT starts up as a command line session which accepts the usual GNUPLOT
input. The Presentation Manager (PM) window for graphics display is only opened
when the first 'plot' or 'splot' command is entered.

If GNUPLOT is set up as a program object, it can be configured for 'drag and
drop' in the usual way, by specifying '%*' as the program parameter.

The PM window has facilities for printing the plot, for changing the fonts
used in the plot, and so on. These of course are handled through the usual
PM interface. In addition, you can 'drop' a font onto the window to change
the font.

The usual GNUPLOT commands can also be used to produce output on supported
devices.

Settings and the positions and sizes of the windows can be saved in the file
gnushell.ini. This file is saved in the program's working directory; several
different directories can be set up (as program objects) with different
options, if you wish.

PM terminal is fully mouse-capable. Type 'm' to switch the mouse on/off (see
'help mouse' for more details), or 'h' for the full list of current hotkeys
(see also 'help bind').


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 detected automatically.  If all else
fails, a compile-time default will be used.

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 and also to be used as the home directory in ~
substitution.  See the help on 'start_up' for more information.

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 usual system-wide environment variable is used to locate a command
line shell to be used for executing commands and starting sub-shells.
On all versions of Windows and OS/2 the variable looked at is COMSPEC.
Other platforms will consult SHELL.

The x11 and qt terminals each require an auxiliary program (gnuplot_x11
gnuplot_qt) to manage the displayed plots.  These are installed by
default in /usr/local/libexec/gnuplot/<version>/ but this default can be
overridden by the environmental variable GNUPLOT_DRIVER_DIR.

GDFONTPATH is the directory where the libgd terminals (jpeg png gif)
search for fonts.  You should set it to directory where files like
arial.ttf and Symbol.pfa exist.

GNUPLOT_DEFAULT_GDFONT is the default font to be used by the png and
jpeg terminal types. This must either be a full path to the font file
or the face name of a font found in the GDFONTPATH search path.

GNUPLOT_FONTPATH is used by the postscript driver as search path for
postscript (Adobe Type 1 and Type 2) fonts (only needed if you want
to embed a copy of the font in the output file, which is not common).

GNUPLOT_PS_DIR is used by the postscript driver to use external prologue
files. Depending on the build process, gnuplot contains either a builtin
copy of those files or simply a default hardcoded path. Use this variable
to test the postscript terminal with custom prologue files.

GNUPLOT_LIB may be used to define additional search directories for
data and command files. The variable may contain a single directory
name, or a list of directories separated by a platform-specific path
separator, eg. ':' on Unix, or ';' on DOS/Windows/OS2 platforms.
The contents of GNUPLOT_LIB are appended to the `loadpath`
variable but are not saved with the `save` and `save set` commands.

GNUFITLOG holds the name of a file that saves fit results. The default
is fit.log. If the name ends with a "/" or "\", it is treated as a
directory name, and "fit.log" will be created as a file in that directory.


How to test gnuplot
===================

The demo files distributed with the program source act also as unit
tests for various gnuplot syntax, plotting, and terminal features.
Output can be compared to the on-line demo output collection on the
gnuplot web site.

All command line examples below assume Unix Bourne shell syntax.

   Individual demo files can be run interactively by eg.

$ cd gnuplot/demo
$ gnuplot simple.dem
    or
$ GNUPLOT_DRIVER_DIR=../src ../src/gnuplot simple.dem

and gnuplot prompts the user to "Hit return to continue" to cycle through
all the plots (the GNUPLOT_DRIVER_DIR= part 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 if 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

$ gnuplot simple.dem </bin/yes
$ GNUPLOT_DRIVER_DIR=../src ../src/gnuplot simple.dem </bin/yes

   To run all demos non-interactively, use

$ gnuplot all.dem </bin/yes
$ GNUPLOT_DRIVER_DIR=../src ../src/gnuplot all.dem </bin/yes
   For convenience, the special make target 'check' will run the above
   if you run it from the demo directory of the source tree:
$ make check

   To use a different plotting device than the default, use eg.

$ GNUTERM=dumb make check
or
gnuplot> set term dumb
gnuplot> load 'all.dem'

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

gnuplot> test

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