Chapter 4. Deploying programs that use PLplot
Prev | Part II. Programming | Next

## Chapter 4. Deploying programs that use PLplot

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:

1. You use the static versions of the PLplot libraries and devices which are not dynamically loaded. [1]

2. You use the shared versions of the PLplot libraries and devices which are not dynamically loaded.

3. 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).

Prev | Up | Next
Legends and color bars | Home | Chapter 5. Drivers which implement file devices