PLplot Configuration, Build, and Installation
=============================================

The definitive set of instructions is given at
http://www.miscdebris.net/plplot_wiki/index.php?title=Building_PLplot.  The
material below is cut and pasted from there as of 2009-01-10.

All PLplot builds are done with our CMake-based build system which
gives good results on Unix, Linux, and Mac OS X and Cygwin, MinGW,
MinGW/MSYS, and bare windows.

Building PLplot with our CMake-based build system
=================================================

Our CMake-based build system has been made available as part of our
development releases of PLplot starting with version 5.7.0 and is now with
the exception of the DJGPP platform our sole build system. It is important
to consult the CMake documentation to get the most out of our build system.
That documentation is quite thorough but tends to be a bit scattered so we
have collected what we think are the best general CMake documentation links
for your convenience at
http://www.miscdebris.net/plplot_wiki/index.php?title=General_CMake_documentation_links.

After consulting that documentation, install the appropriate package of
CMake for your system platform. Note, you must use at least version 2.6.0 of
CMake for your PLplot configuration, but our build system works with the
latest version (2.6.2) of CMake as well.

Generic Unix instructions for our build system
==============================================

(Optional) set environment variables to help cmake find system components
that are installed in non-standard locations
-------------------------------------------------------------------------

Here is one particular example (which must be executed before the cmake
invocation discussed below).

export CMAKE_INCLUDE_PATH=/home/software/autotools/install/include:/home/software/cgmlib/cd1.3
export CMAKE_LIBRARY_PATH=/home/software/autotools/install/lib:/home/software/cgmlib/cd1.3
export PKG_CONFIG_PATH=/home/software/libLASi/install/lib/pkgconfig

For this particular example, CMAKE_INCLUDE_PATH helps cmake to find the
headers for libltdl and libcd in non-standard install locations;
CMAKE_LIBRARY_PATH helps cmake to find the libltdl and libcd libraries in
non-standard install locations; and PKG_CONFIG_PATH helps cmake to use the
pkg-config command internally to find a libLASi pkg-config module file that
is installed in a non-standard location.

In general, CMAKE_INCLUDE_PATH helps cmake find headers and other files that
are installed in non-standard locations; CMAKE_LIBRARY_PATH helps cmake find
libraries that are installed in non-standard locations; and PKG_CONFIG_PATH
helps pkg-config (either externally or internally from cmake) find
pkg-config modules installed in non-standard locations. Finally, although
not used in the specific example above, the colon-separated environment
variable PATH helps cmake find executables that are installed in
non-standard locations.

(Optional) set environment variables to specify the compilers and compiler
flags
--------------------------------------------------------------------------

Here is one particular example (which must be executed before the cmake
invocation discussed below).

export CC="gcc -O2"
export CXX="g++ -O2"
export FC="gfortran -O2"

If you don't set the environment variables above, then by default no
compiler options (i.e., no optimization and no debugging symbols) are used
for gcc-related compilers for our build system which makes for fast builds,
but slow execution.

CMake invocation
----------------

Here is one typical example.

mkdir build_dir
cd build_dir
cmake -DCMAKE_INSTALL_PREFIX=/my/prefix ../plplot_cmake >& cmake.out

(Note:
- "build_dir" is the directory where you want to build the libraries.
- "/my/prefix" is the directory where you want to install the PLplot libraries
  for actual use. If you leave the option -DCMAKE_INSTALL_PREFIX= out, a
  default installation directory will be selected. This actual default directory
  depends on the operating system you are using.
- "plplot_cmake" is the directory where all the source files are contained,
  most notably the file "CMakeLists.txt", as that is the file that CMake will
  start its build preparation from.
All of these directories can be given any name you like, of course.)

(CMake is capable of generating builds within the source tree, but we have
emphasized a build with a separate build tree here because of its
fundamental advantage that the source tree remains clean with no generated
files in it.)

Check the cmake.out file for any configuration issues, especially WARNING
messages which signal that a component of PLplot has been removed because
required system components for that component have not been found.

There are a large number of CMake options for PLplot (see
http://www.miscdebris.net/plplot_wiki/index.php?title=CMake_options_for_PLplot)
which can be set for cmake to personalize your build. Use the ccmake front
end to cmake to obtain documentation of all these options. In the above case
we have specified a particular install prefix "/my/prefix".

Note in the above example an initially empty build directory (arbitrarily)
named build_dir is used to insure a clean start, and ../plplot_cmake is the
(arbitrary) name of the top-level directory of a freshly checked out source
tree from our svn repository. If instead you use a freshly unpacked PLplot
source distribution tarball "../plplot_cmake" will need to be replaced by
"../plplot-5.9.2" (for our latest release at time of writing).

To start a fresh build, simply execute "cd build_dir; rm -rf *" before
invoking cmake. Of course, "rm -rf *" is an extremely dangerous command
(since it removes everything in the current directory and all
subdirectories), but you should be okay so long as you cd to the correct
directory before executing the "rm" command.

Build and install
-----------------

make >& make.out
make install >& make_install.out

Check make.out and make_install.out for any errors. Follow up by testing
PLplot (see
http://www.miscdebris.net/plplot_wiki/index.php?title=Testing_PLplot and
README.testing).

Platform-specific remarks about building PLplot
===============================================

See
http://www.miscdebris.net/plplot_wiki/index.php?title=Specifics_for_various_platforms.

