This chapter provides some information on the issue of delivering programs that use PLplot: what files should be installed and where, what environment variables are involved and related matters.
The scenario is this: You have created one or more programs that run successfully on your development machine and now you need to install them on the machine of a user.
One solution is to provide him or her with the full development environment that you use, but that is in general only an option if your user is comfortable with making programs themselves. A more common situation is that your user just wants the executable programs and wants to get using them right away. We will focus on this particular solution, as there are a few non-trivial issues.
To be absolutely clear about what we are describing, here is a summary:
Your program must run on a machine that does not have PLplot installed from the sources.
There is no development environment that you can rely on.
The program should be installed in a self-contained directory
structure (which can be
/usr/local or c:\program
files or whatever, but need not be so).
Under Linux, the easiest way to install a binary version of PLplot on a
user's machine is to use PLplot deb binary packages for the Debian distribution, and PLplot rpm
binary packages for rpm-based distributions. (See the download
area of the PLplot web site for locations of debs and rpms.)
Build the application on the build machine using the results of the
pkg-config --cflags --libs plplotd command, and copy
the resulting executable(s) to the users' machines.
Under Unix (and also under Linux if you would prefer to use a newer version of PLplot than is available in the debs or rpms), a good way to deploy binary PLplot and applications that depend on that binary PLplot on users' machines is as follows:
Use the cmake option
-DCMAKE_INSTALL_PREFIX=/usr/local/plplot (or some other
unique but consistent directory that is available on the build
machine and all users' machines).
Build and install as normal on the build machine.
Copy the installed PLplot tree,
/usr/local/plplot, into a tarball.
Unpack that tarball on all users' machines in the same location
/usr/local/plplot.
Build the application(s) on the build machine using either the make or cmake based build system in /usr/local/plplot/share/plplotX.Y.Z/examples where X.Y.Z is the plplot version, and copy the resulting executable(s) to the users' machines. Since the PLplot install location is consistent on all machines, the application should work the same way on all machines.
On Windows, and also those rare Linux/Unix cases where you cannot install the PLplot install tree in a consistent location on users' machines, then there are some additional options you need to consider.
There are three situations depending on how you configure and build the PLplot libraries:
You use the static versions of the PLplot libraries and devices which are not dynamically loaded. [1]
You use the shared versions of the PLplot libraries and devices which are not dynamically loaded.
You use the shared versions of the PLplot library and devices which are dynamically loaded. This combination is the default option under Unix/Linux.
In the first case the program will contain all the
code it needs to work, but to run successfully, it needs to find the
font files, plstnd5.fnt and
plxtnd5.fnt. The mechanism used in PLplot to find
these files is fairly simple:
It looks at a number of built-in places, determined at the time the PLplot library itself was installed and built. For deployment these places are irrelevant in general.
It looks at the environment variables
PLPLOT_LIB and PLPLOT_HOME.
(Actually, this happens only, if the corresponding compiler
macros PLPLOT_LIB_ENV and
PLPLOT_HOME_ENV were defined at compile time.)
(TODO: remark about Mac)
Note: This is also the place to put the geographical map files, if you happen to use them.
The environment variables should point to the directory holding the two font files or the one above (one variable is enough though):
PLPLOT_LIB should point to the directory
actually holding these files
PLPLOT_HOME should point to the directory that
holds a subdirectory “lib”
which in turn holds these files.
If it can find these, PLplot can do its job.
Note: This is the case for instance when you use the static PLplot
library on Windows (see the directory
sys\win32\msdev\plplib).
In the second case the font and map files are found as in the first case. In addition, you also require another environment variable so the PLplot shared libraries can be found at run time by the run-time loader. The details depend on the system you are working on, but here are some common platforms:
Most UNIX, BSD and Linux systems use an environment variable
LD_LIBRARY_PATH which indicates
directories where shared libraries can be found. Some use
SHLIB_PATH, like HPUX.
On Windows the PATH variable is used to find the DLLs, but beware: Windows uses a number of places to find the DLLs a program needs and the ordering seems to depend on some intricate details. It seems easiest and safest to put the DLLs in the same directory as your program.
On MacOSX, ... TODO
In the third (default) case, the PLplot fonts and maps are found as in the first case, and the shared libraries are found as in the second case, but in addition the separated dynamic devices have to be found as well.
When PLplot uses dynamic devices, it first builds up a list of them, by
examining a directory which contains files describing those devices:
the *.driver_info files. Each of these files indicates what
the relevant properties for the device or devices. Then when the
device is actually needed, the corresponding shared object (or plug-in
or DLL depending on your terminology) is dynamically loaded.
The directory that contains all these files (the device descriptions as
well as the actual libraries and the description files that libtool
uses) is a directory determined at the time you configured
PLplot which is typically something like
/usr/local/plplot/lib/plplot5.3.1/driversd. This
directory must be pointed to by the PLPLOT_DRV_DIR
environment variable. Again for deployment, only the environment
variable is of real interest.
To summarize the case where you don't have a deb or rpm option, and you must use inconsistent install locations on your users' machines:
The following environment variables are important:
PLPLOT_HOME or
PLPLOT_LIB to indicate the position of
font files (and also of the various geographic maps)
LD_LIBRARY_PATH,
SHLIB_PATH or PATH to
find the dynamic/shared libraries
PLPLOT_DRV_DIR to find the device
descriptions
The following files being part of PLplot must be distributed along with your program:
The font files (plstnd5.fnt and
plxtnd5.fnt) and, possibly, if you use
them, the geographic map files.
The PLplot shared libraries
The device description files and the device shared object files
All the environment variables, except
LD_LIBRARY_PATH and equivalents, can be set within
the program (by using a small configuration file or by determining the
position of the files relative to the program's location). They just
have be set before PLplot is initialized.
[1] UNIX-like systems libraries can be static or shared, the first type becoming part of the program, the second existing as a separate file. On Windows the terms are respectively static and dynamic (the latter type is also known as DLL).