~ubuntu-branches/ubuntu/intrepid/plplot/intrepid

PLplot installation
===================

- (For UNIX, Linux, MacOS X, Cygwin, MinGW, MinGW/MSYS, and bare windows,
i.e., all systems other than DJGPP.) Use our CMake-based build system.

- DJGPP on (Free)DOS.  Follow the directions at sys/dos/djgpp/readme


PLplot installation notes for our CMake-based build system.
=========================================================================

The definitive set of instructions is given at
http://www.miscdebris.net/plplot_wiki/.  The material below is cut and pasted
from there as of 2006-12-02.

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
(http://www.miscdebris.net/plplot_wiki/index.php?title=General_CMake_documentation_links)
for your convenience.

After consulting that documentation, install
(http://cmake.org/HTML/Install.html) the appropriate package of
CMake for your system platform. Note, you must use at least version 2.4.5 of
CMake for your PLplot configuration.


------------------------------------------------------------------------------
Some general remarks on CMake
------------------------------------------------------------------------------

The CMake build system (from http://www.cmake.org) is a portable system
to prepare makefiles and project files for software like PLplot that
needs to be built on many different platforms (hardware, operating
system, compilers).

The approach we have found most useful in using CMake to build PLplot is
this:

* Copy the sources in one directory
* Create a separate directory to build and install the software itself
  (libraries and the executables for the examples)

This way, you can simply remove all files in the build/install directory
and start all over, if you want to change a build option. Or build
PLplot in a third directory with the new build options.

CMake has two interfaces:

* The command-line interface "cmake"

* The graphical user-interface ccmake (or CmakeSetup under Windows)

The advantage of the command-line interface is that you can set the
various options (and environment variables) in a shell script or batch
file so that you can not forget to set them.

The advantage of the GUI is of course that you have an overview of all
possible options. But you will need to be careful to set all
environment variables _before_ running CMake.

Whichever of two you take, the steps are:

* Set up the environment (if this is needed, for instance to find the
  compilers and extra libraries)

* Run CMake with the right options to create makefiles or project files

* Run the native build system (nmake or the proper IDE) to actually
  build the library.

------------------------------------------------------------------------------
Generic Unix instructions for our CMake-based 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="g77 -O2"

   Note a better option is to set CMAKE_BUILD_TYPE to one of Debug, Release,
   RelWithDebInfo, or MinSizeRel. If you don't set this variable and 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 \
   -DCMAKE_VERBOSE_MAKEFILE=ON  ../plplot_cmake >& cmake.out

   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.

   Everything can be controlled with -D options to the cmake command. There
   are a large number of CMake options for PLplot
   (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" and
   verbose make results (essential if you want to see the exact commands
   used for the build).

   Note in the above example an empty build directory called build_dir is
   used to insure a clean start, and ../plplot_cmake is a freshly checked
   out source tree (which remains clean because you never actually create
   any files in that directory tree). To start fresh, simply execute "cd
   build_dir; rm -rf *". Of course, this 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.

  + Post-cmake build, install, and build-tree and install-tree tests

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

   ctest

   cp -a /my/prefix/share/plplot5.6.1/examples /tmp
   cd /tmp/examples
   make >& make_examples.out
   ./plplot-test.sh >& plplot_test.out

   Note, the build-tree tests done with ctest are limited to just the psc
   (colour postscript) device and can only be performed if cmake is invoked
   with the -DBUILD_TEST=ON option (which roughly doubles the build time
   because all the examples must be built).

   Check all the *.out files for any errors.  Check that the large number of
   postscript files generated by plplot-test.sh look good with a postscript
   viewer.  Also, use the --help option to ./plplot-test.sh to see ways you
   can test your PLplot install for devices other than the default psc
   device.

   ---------------------------------------------------------------------------
   Linux instructions for our build system.
   ---------------------------------------------------------------------------

   No changes from the generic Unix instructions.

   ---------------------------------------------------------------------------
   MacOS X instructions for our build system.
   ---------------------------------------------------------------------------

   No changes from the generic Unix instructions.

   Things to be aware of on OS-X are the following:
   1. The wxWidgets driver should be off as the version of wxWidgets that
      OS-X (10.4) ships with is not a recent enough version.
      (PLD_wxwidgets = OFF).
   2. Cmake is really good at finding libraries, but not so good at figuring
      out which is the right library to use when multiple options are present.
      Since a typical OS-X installation will often (unfortunately) have
      multiple versions of the same library in different locations (e.g.
      /sw, /opt, /usr and various Framework directories), care must be taken
      to make sure that the desired library is being used. Furthermore it is
      important to make sure it is the only one being used, and that you are
      not instead pulling the header files from one place and the library
      itself from another.

------------------------------------------------------------------------------
Windows instructions for our build system (needs updating from
http://www.miscdebris.net/plplot_wiki/
------------------------------------------------------------------------------

* Here is a typical way to use cmake on windows systems.
CMake comes with a graphical user-interface that allows you to set the
various build parameters interactively. It will try and find the
available compilers and other language tools that can be used for
PLplot and then generate a set of makefiles or project files depending
on what you chose.

Alternatively you can use the command-line version. This is particularly
useful if you need to set one or more environment variables - you can
do that in a small batch file and then run CMake several times until
you have fine-tuned the build system.

Once you have the makefiles or project files, you can use nmake or
Visual Studio to actually build the library and the examples.

Typically the steps are:

   + Set any environment variables you need to set (if the
     right compilers are not already in your path for instance)
     - If you set them in a DOS-box, be sure to run CMake in
     that same DOS-box!


   + Run CMakeSetup (the GUI version of CMake) or cmake (the
     command-line version) to set the build parameters and
     generate the make/project files

   + Run nmake or Visual Studio to build the library and
     the examples

For instance (sources copied in c:\plplot\plplot):

     c:\plplot> mkdir build
     c:\plplot> cd build
     c:\plplot\build> vcvarss32
     c:\plplot\build> cmake -DBUILD_TEST=ON -G "NMake Makefiles" ..\plplot
     c:\plplot\build> nmake

CMake supports most flavours of Visual Studio project files (ranging
from VS 6.0 to VS.net 2005) and it can create makefiles suitable for
the nmake utility.

Currently (january 2007) there are the following limitations:

   + Support for additional libraries is limited:
     - freetype (antialiasing fonts, smooth text): see notes below
     - BGD (output in the form of GIF, JPEG or PNG files): none yet
     - Qhull (advanced spatial interpolation): none yet

   + An important issue is that on Windows there is no standard
     location to install _libraries_ as opposed to programs.
     We are working on that.

On the other hand:

   + Bindings for C and C++ (MSVC compiler) are no problem
   + You can build both static (.lib) and dynamic link libraries (.dll)

Note on the examples
--------------------
If you want to run the examples _before_ actually installing PLplot,
then you must copy some files into the directory holding the example
programs:

   + plstnd5.fnt and plxtnd5.fnt in the directory ...\data

Dealing with freetype on Windows
--------------------------------
N.B. We need a lot more information here.  For now we only have Werner's
instructions for dealing with the freetype library on two different windows
systems.

MinGW:
* download and unzip freetype 2.2.1 (ft221.zip)
* mingw32-make (compiler is detected)
* mingw32-make (to compile the library)
* copy objs\freetype.a objs\libfreetype.a
* set FREETYPEDIR=C:\DevZone\freetype-2.2.1
* set PATH=%FREETYPEDIR%\objs;%PATH%
* set CMAKE_INCLUDE_PATH=%FREETYPEDIR%\include
* run cmake with your options

Visual C++ 2005
* download and unzip freetype 2.2.1 (ft221.zip)
* change line 69 of freetype-2.2.1\builds\compiler\visualc.mk to
    CFLAGS ?= /nologo /c /Ox /W3 /WX /D_CRT_SECURE_NO_DEPRECATE
    otherwise it stops the build because of warnings (/WX) since it
    doesn't know the /G5 option (this may not be necessary for
     Visual C++ 6.0 and/or 2003
* path_to_gnu_make\mingw32-make setup visualc
* path_to_gnu_make\mingw32-make
* set FREETYPEDIR=C:\DevZone\freetype-2.2.1
* set PATH=%FREETYPEDIR%\objs;%PATH%
* set CMAKE_INCLUDE_PATH=%FREETYPEDIR%\include
* run cmake with your options


------------------------------------------------------------------------------
Cygwin instructions for our build system
------------------------------------------------------------------------------

* Building and installing PLplot under Cygwin is done in the same way as
  under UNIX or Linux. There is one caveat, however, that has to do with
  the way the Windows platform finds dynamic libraries:

  In contrast to UNIX and Linux, there is no facility to build
  into an executable the path to the dynamic libraries (DLLs) it
  requires. Under UNIX and Linux this facility is called the "rpath"
  option. Under Windows and - therefore - under Cygwin there is no such
  option at all. Nor is there is a search path via an environment
  variable like LD_LIBRARY_PATH.

  Instead, programs find their libraries exclusively via the PATH
  environment variable.

  So, when you have built PLplot and installed it, you must add the
  install directory to your PATH before the examples can run
  successfully.

* This lack of an rpath option is important at build time too, when
  you use dynamic drivers: before building PLplot, add the following
  directories to your path:

  + <build>/src
  + <build>/lib/csa

  where "build" points to the directory in which you build PLplot.
  This is the easiest way to do so:

  export PATH=`pwd`/src:`pwd`/libcsa:$PATH
  cmake ...