PLplotWiki - User contributions [en]

Testing PLplot

2010-05-26T20:48:55Z

Hbabcock: /* Testing Reports */

We encourage those who build PLplot to test both their build-tree version and their installed-examples-tree version and report any problems back to either the plplot-general or plplot-devel mailing lists.

=== Testing Prerequisites ===

The legacy test for the build tree requires ctest (available as part of CMake) and bash on Unix systems or [http://win-bash.sourceforge.net/ win-bash] on Windows. The legacy test for the installed examples tree works only on Unix (Linux, Mac OS X, and presumably legacy Unix) and requires GNU-bash, make, and pkg-config.

In contrast to our legacy testing system, the new testing framework is essentially identical for both the build tree and installed examples tree. It just requires CMake (using any generator that is suitable for the Unix or Windows platform that is being used for the test), and bash on Unix or win-bash on Windows.

=== Build-tree tests ===

Build-tree tests can only be performed if cmake is invoked with the -DBUILD_TEST=ON option. Such tests are done from the top-level directory of the build tree (the directory where you invoke cmake command that configures the build of PLplot). The methods for invoking these tests are given below both for the legacy and new testing methods. These tests include executing all our 31 standard examples for all language interfaces and non-interactive device drivers that we currently support. This is a comprehensive test of the PLplot build. For example, our standard examples exercise virtually all of the PLplot API. Furthermore, this series of tests generates more than 2GB of plot files in various formats. The tests also include
a comparison of PostScript (-dev psc) results and stdout from each language interface to PLplot with the corresponding results for C. In general, these results are identical which is a stringent test of our language bindings. (Note it is the user's responsibility to insure the locales are consistent for all languages since inconsistent locales can produce inconsistent stdout results which have nothing to do with PLplot bindings or examples issues.)

You should search test results for obvious errors such as segfaults. In addition, you can test for rendering errors by viewing the file results using an appropriate viewer.

Results for -dev psc are a special case. To illustrate this, here are typical -dev psc results for example 1.

x01a.psc, x01c.psc, x01cxx.psc, x01d.psc, x01f.psc, x01f95.psc, x01j.psc, x01lua.psc, x01o.psc, x01ocaml.psc, x01p.psc, x01pdl.psc, and x01t.psc.

These correspond to Ada, C, C++, D, Fortran 77, Fortran 95, Java, Lua, Octave, OCaml, Python, Perl/PDL, and Tcl -dev psc (colour PostScript) results for our standard example 1. The test referred to above compares everything in this list, but x01c.psc against that file so rendering errors only need to be looked for in x01c.psc (with your favorite Postscript viewing application), and any of these files which the report shows are different from x01c.psc. And similarly for the -dev psc results for the rest of our 31 standard examples.

Here are typical plot file results from our standard example 1 for devices other than -dev psc.

x01c.pdfcairo, x01c.ps, x01c.psttf, x01c.psttfc, x01c01.bmpqt, x01c01.epsqt, x01c01.jpgqt, x01c01.pdfqt, x01c01.pngcairo, x01c01.pngqt, x01c01.ppmqt, x01c01.svg, x01c01.svgcairo, x01c01.svgqt, x01c01.tiffqt, and x01c01.xfig.

Since different devices are involved in all cases, these should be looked at individually for rendering errors (and similarly for the remaining 31 standard examples). Note such visual inspection is a huge job so we certainly don't expect it of our testers very often, but once every year or so and especially for newer examples that haven't been checked before is worth doing. On Unix platforms a general all-purpose viewer for all these file formats is the ImageMagick display application.

==== Invocation of legacy tests in the build tree ====

After running "make all" from the top-level of the build tree, then run

ctest --verbose >& ctest.out

This creates test plot file results in the plplot-test subdirectory of the build tree, and ctest.out should contain a table of comparisons of Postscript results from each of our standard examples and each of our language bindings against the corresponding C versions.

==== Invocation of tests in the build tree using the new testing framework ====

One advantage of the new testing framework is that it has full dependencies implemented (unlike ctest which requires "make all" to be run first).

A second advantage of the new testing framework is that for Generators with parallel execution ability, you can save a lot of time on hardware with more than one cpu by using the parallel execution options (e.g., the -j option for GNU make).

A final advantage of the new testing framework is the tests are finer grained. To see all the tests that are possible run

make help |grep test

(On platforms with CMake generators other than make, you will have to do something equivalent to this search to find all test targets.)

Three comprehensive test targets are test_diff_psc, test_noninteractive and test_interactive.

test_diff_psc generates all -dev psc results and compares them with the same report that is obtained from ctest. Note this target excludes anything but -dev psc results.

test_noninteractive runs test_diff_psc as well as every other PLplot example that produces a file. (Note that test_noninteractive is somewhat more comprehensive than legacy ctest and considerably more comprehensive than the test_diff_psc target.)

test_interactive runs all interactive devices for the standard C examples as well as all special interactive examples. Very little user-intervention is required to run these tests because, where possible, the PLplot -np (no-pause) command-line option is used for these tests.

=== Tests of the PLplot installation ===

After PLplot has been configured (with "cmake"), built (with "make"), and installed (with "make install"), you can test the installation using a legacy test system (implemented with Make, pkg-config, and GNU-bash) or our new test framework (implemented with CMake and bash [or win-bash]).

==== Legacy tests (Unix-only) of the PLplot installation ====

You can test the PLplot installation on Unix systems by doing the following commands:

cp -a $prefix/share/plplot$plplot_version/examples /tmp
cd /tmp/examples
make test_noninteractive >& make_test.out
make test_interactive

where "$prefix" is the installation prefix chosen at the configuration stage, and $plplot_version is the PLplot version (currently 5.9.4). The effect of the above "cp" and "cd" commands is to copy the examples subtree of the install tree to /tmp and build and test the examples in the copied subtree to keep a clean install tree. However, an alternative is to replace those two commands with

cd $prefix/share/plplot$plplot_version/examples

and build and test the install-tree examples right in the examples subtree of the install tree with the above "make" commands.

Regardless of whether you build and test the examples in a copy of the examples subtree of the install tree or directly in that subtree, check all the *.out files for any errors.

N.B. the above legacy "make test_noninteractive" command does the same tests for the installed PLplot version as ctest does for the build-tree version of PLplot. Although the tests are the same, the Makefile implementation is different from the ctest implementation in the build tree so that in particular you can do these install tree tests in parallel using the (GNU-)make -j option to greatly speed up these tests on a multi-processor computer. However, since make is required for this installed-examples implementation, it cannot be run on Windows.

N.B. the above legacy "make test_interactive" command executes our interactive examples. The results are similar to those of the test_interactive target implemented with our new test framework, but the implementation is very different (depending on a GNU-bash script rather than standard CMake cross-platform commands).

==== Cross-platform tests of the PLplot installation using the new test framework ====

Here is an example under Unix of how to test the PLplot installation using the new testing framework.
(Those using Windows platforms should be able to infer the equivalent of these commands.)

mkdir /tmp/build_dir
cd /tmp/build_dir
cmake $prefix/share/plplot$plplot_version/examples
make -j4 test_diff_psc >& make_test_diff_psc.out
make -j4 test_noninteractive >& make_test_noninteractive.out
make -j4 test_interactive >& make_test_interactive.out

Note these targets are essentially identical to the targets described above for the new test framework for the build tree because the same bash (or win-bash) scripts and essentially the same CMake logic is used to set up these targets. Similarly, all other fine-grained targets (which you can discover using the

make help |grep test

command) for the new test framework are available in this context as well. N.B. the test_noninteractive and test_interactive targets available here are more comprehensive than the same-named targets in the legacy installation test case and are implemented in a quite different (cross-platform) way with much
better dependencies.

===Testing Reports===
{| class="wikitable" style="text-align:center" border="5" cellspacing="5" cellpadding="2"
|+Table of test reports for PLplot
|-
!rowspan="5" valign="center"|Tester !! PLplot revision !! CMake version !! Platform
|-
! Pango/Cairo version !! Qt version !! Shared libraries? !! Dynamic drivers?
|-
! Build? !! test_ noninteractive? !! test_ interactive? !! ctest?
|-
! Traditional Installed examples? !! test_ noninteractive? !! test_ interactive?
|-
! CMake-based Installed examples? !! test_ noninteractive? !! test_ interactive? !! Notes
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Hazen Babcock || 11019 || 2.6.4 || Ubuntu Intrepid
|-
|system || 4.6.2 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|no || no || no || a B C
|}

Testing notes (lower case notes concern configuration and build options while upper case notes concern errors):

a. Testing done on 64-bit (AMD64) hardware.

b. Used parallel make option (-j4) for all builds, installs, and test targets.

c. All suitable dependent libraries have been installed on the system so there are no device drivers from the default list for this platform that are missing from this test.

d. All compilers and bindings-related development packages have been installed on the system so there are no bindings that are missing from this test.

e. Java, Python, Octave, Perl/PDL, LUA, and OCaml bindings/examples require shared PLplot libraries in order to work so were not available for testing for this static PLplot libraries case.

A. No obvious configure, build, or install errors. No run-time errors in tests other than those noted in additional "upper-case" notes (if any).

B. test_noninteractive hangs at unpredictable points in the Qt device driver tests.

C. We also see this bug in Qt 4.6.2 - http://bugreports.qt.nokia.com/browse/QTBUG-8537

Testing PLplot

2010-05-26T20:48:12Z

Hbabcock: /* Testing Reports */

We encourage those who build PLplot to test both their build-tree version and their installed-examples-tree version and report any problems back to either the plplot-general or plplot-devel mailing lists.

=== Testing Prerequisites ===

The legacy test for the build tree requires ctest (available as part of CMake) and bash on Unix systems or [http://win-bash.sourceforge.net/ win-bash] on Windows. The legacy test for the installed examples tree works only on Unix (Linux, Mac OS X, and presumably legacy Unix) and requires GNU-bash, make, and pkg-config.

In contrast to our legacy testing system, the new testing framework is essentially identical for both the build tree and installed examples tree. It just requires CMake (using any generator that is suitable for the Unix or Windows platform that is being used for the test), and bash on Unix or win-bash on Windows.

=== Build-tree tests ===

Build-tree tests can only be performed if cmake is invoked with the -DBUILD_TEST=ON option. Such tests are done from the top-level directory of the build tree (the directory where you invoke cmake command that configures the build of PLplot). The methods for invoking these tests are given below both for the legacy and new testing methods. These tests include executing all our 31 standard examples for all language interfaces and non-interactive device drivers that we currently support. This is a comprehensive test of the PLplot build. For example, our standard examples exercise virtually all of the PLplot API. Furthermore, this series of tests generates more than 2GB of plot files in various formats. The tests also include
a comparison of PostScript (-dev psc) results and stdout from each language interface to PLplot with the corresponding results for C. In general, these results are identical which is a stringent test of our language bindings. (Note it is the user's responsibility to insure the locales are consistent for all languages since inconsistent locales can produce inconsistent stdout results which have nothing to do with PLplot bindings or examples issues.)

You should search test results for obvious errors such as segfaults. In addition, you can test for rendering errors by viewing the file results using an appropriate viewer.

Results for -dev psc are a special case. To illustrate this, here are typical -dev psc results for example 1.

x01a.psc, x01c.psc, x01cxx.psc, x01d.psc, x01f.psc, x01f95.psc, x01j.psc, x01lua.psc, x01o.psc, x01ocaml.psc, x01p.psc, x01pdl.psc, and x01t.psc.

These correspond to Ada, C, C++, D, Fortran 77, Fortran 95, Java, Lua, Octave, OCaml, Python, Perl/PDL, and Tcl -dev psc (colour PostScript) results for our standard example 1. The test referred to above compares everything in this list, but x01c.psc against that file so rendering errors only need to be looked for in x01c.psc (with your favorite Postscript viewing application), and any of these files which the report shows are different from x01c.psc. And similarly for the -dev psc results for the rest of our 31 standard examples.

Here are typical plot file results from our standard example 1 for devices other than -dev psc.

x01c.pdfcairo, x01c.ps, x01c.psttf, x01c.psttfc, x01c01.bmpqt, x01c01.epsqt, x01c01.jpgqt, x01c01.pdfqt, x01c01.pngcairo, x01c01.pngqt, x01c01.ppmqt, x01c01.svg, x01c01.svgcairo, x01c01.svgqt, x01c01.tiffqt, and x01c01.xfig.

Since different devices are involved in all cases, these should be looked at individually for rendering errors (and similarly for the remaining 31 standard examples). Note such visual inspection is a huge job so we certainly don't expect it of our testers very often, but once every year or so and especially for newer examples that haven't been checked before is worth doing. On Unix platforms a general all-purpose viewer for all these file formats is the ImageMagick display application.

==== Invocation of legacy tests in the build tree ====

After running "make all" from the top-level of the build tree, then run

ctest --verbose >& ctest.out

This creates test plot file results in the plplot-test subdirectory of the build tree, and ctest.out should contain a table of comparisons of Postscript results from each of our standard examples and each of our language bindings against the corresponding C versions.

==== Invocation of tests in the build tree using the new testing framework ====

One advantage of the new testing framework is that it has full dependencies implemented (unlike ctest which requires "make all" to be run first).

A second advantage of the new testing framework is that for Generators with parallel execution ability, you can save a lot of time on hardware with more than one cpu by using the parallel execution options (e.g., the -j option for GNU make).

A final advantage of the new testing framework is the tests are finer grained. To see all the tests that are possible run

make help |grep test

(On platforms with CMake generators other than make, you will have to do something equivalent to this search to find all test targets.)

Three comprehensive test targets are test_diff_psc, test_noninteractive and test_interactive.

test_diff_psc generates all -dev psc results and compares them with the same report that is obtained from ctest. Note this target excludes anything but -dev psc results.

test_noninteractive runs test_diff_psc as well as every other PLplot example that produces a file. (Note that test_noninteractive is somewhat more comprehensive than legacy ctest and considerably more comprehensive than the test_diff_psc target.)

test_interactive runs all interactive devices for the standard C examples as well as all special interactive examples. Very little user-intervention is required to run these tests because, where possible, the PLplot -np (no-pause) command-line option is used for these tests.

=== Tests of the PLplot installation ===

After PLplot has been configured (with "cmake"), built (with "make"), and installed (with "make install"), you can test the installation using a legacy test system (implemented with Make, pkg-config, and GNU-bash) or our new test framework (implemented with CMake and bash [or win-bash]).

==== Legacy tests (Unix-only) of the PLplot installation ====

You can test the PLplot installation on Unix systems by doing the following commands:

cp -a $prefix/share/plplot$plplot_version/examples /tmp
cd /tmp/examples
make test_noninteractive >& make_test.out
make test_interactive

where "$prefix" is the installation prefix chosen at the configuration stage, and $plplot_version is the PLplot version (currently 5.9.4). The effect of the above "cp" and "cd" commands is to copy the examples subtree of the install tree to /tmp and build and test the examples in the copied subtree to keep a clean install tree. However, an alternative is to replace those two commands with

cd $prefix/share/plplot$plplot_version/examples

and build and test the install-tree examples right in the examples subtree of the install tree with the above "make" commands.

Regardless of whether you build and test the examples in a copy of the examples subtree of the install tree or directly in that subtree, check all the *.out files for any errors.

N.B. the above legacy "make test_noninteractive" command does the same tests for the installed PLplot version as ctest does for the build-tree version of PLplot. Although the tests are the same, the Makefile implementation is different from the ctest implementation in the build tree so that in particular you can do these install tree tests in parallel using the (GNU-)make -j option to greatly speed up these tests on a multi-processor computer. However, since make is required for this installed-examples implementation, it cannot be run on Windows.

N.B. the above legacy "make test_interactive" command executes our interactive examples. The results are similar to those of the test_interactive target implemented with our new test framework, but the implementation is very different (depending on a GNU-bash script rather than standard CMake cross-platform commands).

==== Cross-platform tests of the PLplot installation using the new test framework ====

Here is an example under Unix of how to test the PLplot installation using the new testing framework.
(Those using Windows platforms should be able to infer the equivalent of these commands.)

mkdir /tmp/build_dir
cd /tmp/build_dir
cmake $prefix/share/plplot$plplot_version/examples
make -j4 test_diff_psc >& make_test_diff_psc.out
make -j4 test_noninteractive >& make_test_noninteractive.out
make -j4 test_interactive >& make_test_interactive.out

Note these targets are essentially identical to the targets described above for the new test framework for the build tree because the same bash (or win-bash) scripts and essentially the same CMake logic is used to set up these targets. Similarly, all other fine-grained targets (which you can discover using the

make help |grep test

command) for the new test framework are available in this context as well. N.B. the test_noninteractive and test_interactive targets available here are more comprehensive than the same-named targets in the legacy installation test case and are implemented in a quite different (cross-platform) way with much
better dependencies.

===Testing Reports===
{| class="wikitable" style="text-align:center" border="5" cellspacing="5" cellpadding="2"
|+Table of test reports for PLplot
|-
!rowspan="5" valign="center"|Tester !! PLplot revision !! CMake version !! Platform
|-
! Pango/Cairo version !! Qt version !! Shared libraries? !! Dynamic drivers?
|-
! Build? !! test_ noninteractive? !! test_ interactive? !! ctest?
|-
! Traditional Installed examples? !! test_ noninteractive? !! test_ interactive?
|-
! CMake-based Installed examples? !! test_ noninteractive? !! test_ interactive? !! Notes
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Hazen Babcock || 11019 || 2.6.4 || Ubuntu Intrepid
|-
|system || 4.6.2 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || a B C
|}

Testing notes (lower case notes concern configuration and build options while upper case notes concern errors):

a. Testing done on 64-bit (AMD64) hardware.

b. Used parallel make option (-j4) for all builds, installs, and test targets.

c. All suitable dependent libraries have been installed on the system so there are no device drivers from the default list for this platform that are missing from this test.

d. All compilers and bindings-related development packages have been installed on the system so there are no bindings that are missing from this test.

e. Java, Python, Octave, Perl/PDL, LUA, and OCaml bindings/examples require shared PLplot libraries in order to work so were not available for testing for this static PLplot libraries case.

A. No obvious configure, build, or install errors. No run-time errors in tests other than those noted in additional "upper-case" notes (if any).

B. test_noninteractive hangs at unpredictable points in the Qt device driver tests.

C. We also see this bug in Qt 4.6.2 - http://bugreports.qt.nokia.com/browse/QTBUG-8537

Testing PLplot

2010-05-26T20:46:11Z

Hbabcock: /* Testing Reports */

We encourage those who build PLplot to test both their build-tree version and their installed-examples-tree version and report any problems back to either the plplot-general or plplot-devel mailing lists.

=== Testing Prerequisites ===

The legacy test for the build tree requires ctest (available as part of CMake) and bash on Unix systems or [http://win-bash.sourceforge.net/ win-bash] on Windows. The legacy test for the installed examples tree works only on Unix (Linux, Mac OS X, and presumably legacy Unix) and requires GNU-bash, make, and pkg-config.

In contrast to our legacy testing system, the new testing framework is essentially identical for both the build tree and installed examples tree. It just requires CMake (using any generator that is suitable for the Unix or Windows platform that is being used for the test), and bash on Unix or win-bash on Windows.

=== Build-tree tests ===

Build-tree tests can only be performed if cmake is invoked with the -DBUILD_TEST=ON option. Such tests are done from the top-level directory of the build tree (the directory where you invoke cmake command that configures the build of PLplot). The methods for invoking these tests are given below both for the legacy and new testing methods. These tests include executing all our 31 standard examples for all language interfaces and non-interactive device drivers that we currently support. This is a comprehensive test of the PLplot build. For example, our standard examples exercise virtually all of the PLplot API. Furthermore, this series of tests generates more than 2GB of plot files in various formats. The tests also include
a comparison of PostScript (-dev psc) results and stdout from each language interface to PLplot with the corresponding results for C. In general, these results are identical which is a stringent test of our language bindings. (Note it is the user's responsibility to insure the locales are consistent for all languages since inconsistent locales can produce inconsistent stdout results which have nothing to do with PLplot bindings or examples issues.)

You should search test results for obvious errors such as segfaults. In addition, you can test for rendering errors by viewing the file results using an appropriate viewer.

Results for -dev psc are a special case. To illustrate this, here are typical -dev psc results for example 1.

x01a.psc, x01c.psc, x01cxx.psc, x01d.psc, x01f.psc, x01f95.psc, x01j.psc, x01lua.psc, x01o.psc, x01ocaml.psc, x01p.psc, x01pdl.psc, and x01t.psc.

These correspond to Ada, C, C++, D, Fortran 77, Fortran 95, Java, Lua, Octave, OCaml, Python, Perl/PDL, and Tcl -dev psc (colour PostScript) results for our standard example 1. The test referred to above compares everything in this list, but x01c.psc against that file so rendering errors only need to be looked for in x01c.psc (with your favorite Postscript viewing application), and any of these files which the report shows are different from x01c.psc. And similarly for the -dev psc results for the rest of our 31 standard examples.

Here are typical plot file results from our standard example 1 for devices other than -dev psc.

x01c.pdfcairo, x01c.ps, x01c.psttf, x01c.psttfc, x01c01.bmpqt, x01c01.epsqt, x01c01.jpgqt, x01c01.pdfqt, x01c01.pngcairo, x01c01.pngqt, x01c01.ppmqt, x01c01.svg, x01c01.svgcairo, x01c01.svgqt, x01c01.tiffqt, and x01c01.xfig.

Since different devices are involved in all cases, these should be looked at individually for rendering errors (and similarly for the remaining 31 standard examples). Note such visual inspection is a huge job so we certainly don't expect it of our testers very often, but once every year or so and especially for newer examples that haven't been checked before is worth doing. On Unix platforms a general all-purpose viewer for all these file formats is the ImageMagick display application.

==== Invocation of legacy tests in the build tree ====

After running "make all" from the top-level of the build tree, then run

ctest --verbose >& ctest.out

This creates test plot file results in the plplot-test subdirectory of the build tree, and ctest.out should contain a table of comparisons of Postscript results from each of our standard examples and each of our language bindings against the corresponding C versions.

==== Invocation of tests in the build tree using the new testing framework ====

One advantage of the new testing framework is that it has full dependencies implemented (unlike ctest which requires "make all" to be run first).

A second advantage of the new testing framework is that for Generators with parallel execution ability, you can save a lot of time on hardware with more than one cpu by using the parallel execution options (e.g., the -j option for GNU make).

A final advantage of the new testing framework is the tests are finer grained. To see all the tests that are possible run

make help |grep test

(On platforms with CMake generators other than make, you will have to do something equivalent to this search to find all test targets.)

Three comprehensive test targets are test_diff_psc, test_noninteractive and test_interactive.

test_diff_psc generates all -dev psc results and compares them with the same report that is obtained from ctest. Note this target excludes anything but -dev psc results.

test_noninteractive runs test_diff_psc as well as every other PLplot example that produces a file. (Note that test_noninteractive is somewhat more comprehensive than legacy ctest and considerably more comprehensive than the test_diff_psc target.)

test_interactive runs all interactive devices for the standard C examples as well as all special interactive examples. Very little user-intervention is required to run these tests because, where possible, the PLplot -np (no-pause) command-line option is used for these tests.

=== Tests of the PLplot installation ===

After PLplot has been configured (with "cmake"), built (with "make"), and installed (with "make install"), you can test the installation using a legacy test system (implemented with Make, pkg-config, and GNU-bash) or our new test framework (implemented with CMake and bash [or win-bash]).

==== Legacy tests (Unix-only) of the PLplot installation ====

You can test the PLplot installation on Unix systems by doing the following commands:

cp -a $prefix/share/plplot$plplot_version/examples /tmp
cd /tmp/examples
make test_noninteractive >& make_test.out
make test_interactive

where "$prefix" is the installation prefix chosen at the configuration stage, and $plplot_version is the PLplot version (currently 5.9.4). The effect of the above "cp" and "cd" commands is to copy the examples subtree of the install tree to /tmp and build and test the examples in the copied subtree to keep a clean install tree. However, an alternative is to replace those two commands with

cd $prefix/share/plplot$plplot_version/examples

and build and test the install-tree examples right in the examples subtree of the install tree with the above "make" commands.

Regardless of whether you build and test the examples in a copy of the examples subtree of the install tree or directly in that subtree, check all the *.out files for any errors.

N.B. the above legacy "make test_noninteractive" command does the same tests for the installed PLplot version as ctest does for the build-tree version of PLplot. Although the tests are the same, the Makefile implementation is different from the ctest implementation in the build tree so that in particular you can do these install tree tests in parallel using the (GNU-)make -j option to greatly speed up these tests on a multi-processor computer. However, since make is required for this installed-examples implementation, it cannot be run on Windows.

N.B. the above legacy "make test_interactive" command executes our interactive examples. The results are similar to those of the test_interactive target implemented with our new test framework, but the implementation is very different (depending on a GNU-bash script rather than standard CMake cross-platform commands).

==== Cross-platform tests of the PLplot installation using the new test framework ====

Here is an example under Unix of how to test the PLplot installation using the new testing framework.
(Those using Windows platforms should be able to infer the equivalent of these commands.)

mkdir /tmp/build_dir
cd /tmp/build_dir
cmake $prefix/share/plplot$plplot_version/examples
make -j4 test_diff_psc >& make_test_diff_psc.out
make -j4 test_noninteractive >& make_test_noninteractive.out
make -j4 test_interactive >& make_test_interactive.out

Note these targets are essentially identical to the targets described above for the new test framework for the build tree because the same bash (or win-bash) scripts and essentially the same CMake logic is used to set up these targets. Similarly, all other fine-grained targets (which you can discover using the

make help |grep test

command) for the new test framework are available in this context as well. N.B. the test_noninteractive and test_interactive targets available here are more comprehensive than the same-named targets in the legacy installation test case and are implemented in a quite different (cross-platform) way with much
better dependencies.

===Testing Reports===
{| class="wikitable" style="text-align:center" border="5" cellspacing="5" cellpadding="2"
|+Table of test reports for PLplot
|-
!rowspan="5" valign="center"|Tester !! PLplot revision !! CMake version !! Platform
|-
! Pango/Cairo version !! Qt version !! Shared libraries? !! Dynamic drivers?
|-
! Build? !! test_ noninteractive? !! test_ interactive? !! ctest?
|-
! Traditional Installed examples? !! test_ noninteractive? !! test_ interactive?
|-
! CMake-based Installed examples? !! test_ noninteractive? !! test_ interactive? !! Notes
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Hazen Babcock || 11019 || 2.6.4 || Ubuntu Intrepid
|-
|system || 4.6.2 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || a B
|}

Testing notes (lower case notes concern configuration and build options while upper case notes concern errors):

a. Testing done on 64-bit (AMD64) hardware.

b. Used parallel make option (-j4) for all builds, installs, and test targets.

c. All suitable dependent libraries have been installed on the system so there are no device drivers from the default list for this platform that are missing from this test.

d. All compilers and bindings-related development packages have been installed on the system so there are no bindings that are missing from this test.

e. Java, Python, Octave, Perl/PDL, LUA, and OCaml bindings/examples require shared PLplot libraries in order to work so were not available for testing for this static PLplot libraries case.

A. No obvious configure, build, or install errors. No run-time errors in tests other than those noted in additional "upper-case" notes (if any).

B. test_noninteractive hangs at unpredictable points in the Qt device driver tests.

Testing PLplot

2010-05-26T20:45:45Z

Hbabcock: /* Testing Reports */

We encourage those who build PLplot to test both their build-tree version and their installed-examples-tree version and report any problems back to either the plplot-general or plplot-devel mailing lists.

=== Testing Prerequisites ===

The legacy test for the build tree requires ctest (available as part of CMake) and bash on Unix systems or [http://win-bash.sourceforge.net/ win-bash] on Windows. The legacy test for the installed examples tree works only on Unix (Linux, Mac OS X, and presumably legacy Unix) and requires GNU-bash, make, and pkg-config.

In contrast to our legacy testing system, the new testing framework is essentially identical for both the build tree and installed examples tree. It just requires CMake (using any generator that is suitable for the Unix or Windows platform that is being used for the test), and bash on Unix or win-bash on Windows.

=== Build-tree tests ===

Build-tree tests can only be performed if cmake is invoked with the -DBUILD_TEST=ON option. Such tests are done from the top-level directory of the build tree (the directory where you invoke cmake command that configures the build of PLplot). The methods for invoking these tests are given below both for the legacy and new testing methods. These tests include executing all our 31 standard examples for all language interfaces and non-interactive device drivers that we currently support. This is a comprehensive test of the PLplot build. For example, our standard examples exercise virtually all of the PLplot API. Furthermore, this series of tests generates more than 2GB of plot files in various formats. The tests also include
a comparison of PostScript (-dev psc) results and stdout from each language interface to PLplot with the corresponding results for C. In general, these results are identical which is a stringent test of our language bindings. (Note it is the user's responsibility to insure the locales are consistent for all languages since inconsistent locales can produce inconsistent stdout results which have nothing to do with PLplot bindings or examples issues.)

You should search test results for obvious errors such as segfaults. In addition, you can test for rendering errors by viewing the file results using an appropriate viewer.

Results for -dev psc are a special case. To illustrate this, here are typical -dev psc results for example 1.

x01a.psc, x01c.psc, x01cxx.psc, x01d.psc, x01f.psc, x01f95.psc, x01j.psc, x01lua.psc, x01o.psc, x01ocaml.psc, x01p.psc, x01pdl.psc, and x01t.psc.

These correspond to Ada, C, C++, D, Fortran 77, Fortran 95, Java, Lua, Octave, OCaml, Python, Perl/PDL, and Tcl -dev psc (colour PostScript) results for our standard example 1. The test referred to above compares everything in this list, but x01c.psc against that file so rendering errors only need to be looked for in x01c.psc (with your favorite Postscript viewing application), and any of these files which the report shows are different from x01c.psc. And similarly for the -dev psc results for the rest of our 31 standard examples.

Here are typical plot file results from our standard example 1 for devices other than -dev psc.

x01c.pdfcairo, x01c.ps, x01c.psttf, x01c.psttfc, x01c01.bmpqt, x01c01.epsqt, x01c01.jpgqt, x01c01.pdfqt, x01c01.pngcairo, x01c01.pngqt, x01c01.ppmqt, x01c01.svg, x01c01.svgcairo, x01c01.svgqt, x01c01.tiffqt, and x01c01.xfig.

Since different devices are involved in all cases, these should be looked at individually for rendering errors (and similarly for the remaining 31 standard examples). Note such visual inspection is a huge job so we certainly don't expect it of our testers very often, but once every year or so and especially for newer examples that haven't been checked before is worth doing. On Unix platforms a general all-purpose viewer for all these file formats is the ImageMagick display application.

==== Invocation of legacy tests in the build tree ====

After running "make all" from the top-level of the build tree, then run

ctest --verbose >& ctest.out

This creates test plot file results in the plplot-test subdirectory of the build tree, and ctest.out should contain a table of comparisons of Postscript results from each of our standard examples and each of our language bindings against the corresponding C versions.

==== Invocation of tests in the build tree using the new testing framework ====

One advantage of the new testing framework is that it has full dependencies implemented (unlike ctest which requires "make all" to be run first).

A second advantage of the new testing framework is that for Generators with parallel execution ability, you can save a lot of time on hardware with more than one cpu by using the parallel execution options (e.g., the -j option for GNU make).

A final advantage of the new testing framework is the tests are finer grained. To see all the tests that are possible run

make help |grep test

(On platforms with CMake generators other than make, you will have to do something equivalent to this search to find all test targets.)

Three comprehensive test targets are test_diff_psc, test_noninteractive and test_interactive.

test_diff_psc generates all -dev psc results and compares them with the same report that is obtained from ctest. Note this target excludes anything but -dev psc results.

test_noninteractive runs test_diff_psc as well as every other PLplot example that produces a file. (Note that test_noninteractive is somewhat more comprehensive than legacy ctest and considerably more comprehensive than the test_diff_psc target.)

test_interactive runs all interactive devices for the standard C examples as well as all special interactive examples. Very little user-intervention is required to run these tests because, where possible, the PLplot -np (no-pause) command-line option is used for these tests.

=== Tests of the PLplot installation ===

After PLplot has been configured (with "cmake"), built (with "make"), and installed (with "make install"), you can test the installation using a legacy test system (implemented with Make, pkg-config, and GNU-bash) or our new test framework (implemented with CMake and bash [or win-bash]).

==== Legacy tests (Unix-only) of the PLplot installation ====

You can test the PLplot installation on Unix systems by doing the following commands:

cp -a $prefix/share/plplot$plplot_version/examples /tmp
cd /tmp/examples
make test_noninteractive >& make_test.out
make test_interactive

where "$prefix" is the installation prefix chosen at the configuration stage, and $plplot_version is the PLplot version (currently 5.9.4). The effect of the above "cp" and "cd" commands is to copy the examples subtree of the install tree to /tmp and build and test the examples in the copied subtree to keep a clean install tree. However, an alternative is to replace those two commands with

cd $prefix/share/plplot$plplot_version/examples

and build and test the install-tree examples right in the examples subtree of the install tree with the above "make" commands.

Regardless of whether you build and test the examples in a copy of the examples subtree of the install tree or directly in that subtree, check all the *.out files for any errors.

N.B. the above legacy "make test_noninteractive" command does the same tests for the installed PLplot version as ctest does for the build-tree version of PLplot. Although the tests are the same, the Makefile implementation is different from the ctest implementation in the build tree so that in particular you can do these install tree tests in parallel using the (GNU-)make -j option to greatly speed up these tests on a multi-processor computer. However, since make is required for this installed-examples implementation, it cannot be run on Windows.

N.B. the above legacy "make test_interactive" command executes our interactive examples. The results are similar to those of the test_interactive target implemented with our new test framework, but the implementation is very different (depending on a GNU-bash script rather than standard CMake cross-platform commands).

==== Cross-platform tests of the PLplot installation using the new test framework ====

Here is an example under Unix of how to test the PLplot installation using the new testing framework.
(Those using Windows platforms should be able to infer the equivalent of these commands.)

mkdir /tmp/build_dir
cd /tmp/build_dir
cmake $prefix/share/plplot$plplot_version/examples
make -j4 test_diff_psc >& make_test_diff_psc.out
make -j4 test_noninteractive >& make_test_noninteractive.out
make -j4 test_interactive >& make_test_interactive.out

Note these targets are essentially identical to the targets described above for the new test framework for the build tree because the same bash (or win-bash) scripts and essentially the same CMake logic is used to set up these targets. Similarly, all other fine-grained targets (which you can discover using the

make help |grep test

command) for the new test framework are available in this context as well. N.B. the test_noninteractive and test_interactive targets available here are more comprehensive than the same-named targets in the legacy installation test case and are implemented in a quite different (cross-platform) way with much
better dependencies.

===Testing Reports===
{| class="wikitable" style="text-align:center" border="5" cellspacing="5" cellpadding="2"
|+Table of test reports for PLplot
|-
!rowspan="5" valign="center"|Tester !! PLplot revision !! CMake version !! Platform
|-
! Pango/Cairo version !! Qt version !! Shared libraries? !! Dynamic drivers?
|-
! Build? !! test_ noninteractive? !! test_ interactive? !! ctest?
|-
! Traditional Installed examples? !! test_ noninteractive? !! test_ interactive?
|-
! CMake-based Installed examples? !! test_ noninteractive? !! test_ interactive? !! Notes
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Hazen Babcock || 11019 || 2.6.4 || Ubuntu Intrepid
|-
|system || 4.6.2 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || a B
|}

Testing notes (lower case notes concern configuration and build options while upper case notes concern errors):

a. Testing done on 64-bit (AMD64) hardware.

b. Used parallel make option (-j4) for all builds, installs, and test targets.

c. All suitable dependent libraries have been installed on the system so there are no device drivers from the default list for this platform that are missing from this test.

d. All compilers and bindings-related development packages have been installed on the system so there are no bindings that are missing from this test.

e. Java, Python, Octave, Perl/PDL, LUA, and OCaml bindings/examples require shared PLplot libraries in order to work so were not available for testing for this static PLplot libraries case.

A. No obvious configure, build, or install errors. No run-time errors in tests other than those noted in additional "upper-case" notes (if any).

B. test_noninteractive hangs at unpredictable points in the Qt device driver test.

Testing PLplot

2010-05-26T20:45:23Z

Hbabcock: /* Testing Reports */

We encourage those who build PLplot to test both their build-tree version and their installed-examples-tree version and report any problems back to either the plplot-general or plplot-devel mailing lists.

=== Testing Prerequisites ===

The legacy test for the build tree requires ctest (available as part of CMake) and bash on Unix systems or [http://win-bash.sourceforge.net/ win-bash] on Windows. The legacy test for the installed examples tree works only on Unix (Linux, Mac OS X, and presumably legacy Unix) and requires GNU-bash, make, and pkg-config.

In contrast to our legacy testing system, the new testing framework is essentially identical for both the build tree and installed examples tree. It just requires CMake (using any generator that is suitable for the Unix or Windows platform that is being used for the test), and bash on Unix or win-bash on Windows.

=== Build-tree tests ===

Build-tree tests can only be performed if cmake is invoked with the -DBUILD_TEST=ON option. Such tests are done from the top-level directory of the build tree (the directory where you invoke cmake command that configures the build of PLplot). The methods for invoking these tests are given below both for the legacy and new testing methods. These tests include executing all our 31 standard examples for all language interfaces and non-interactive device drivers that we currently support. This is a comprehensive test of the PLplot build. For example, our standard examples exercise virtually all of the PLplot API. Furthermore, this series of tests generates more than 2GB of plot files in various formats. The tests also include
a comparison of PostScript (-dev psc) results and stdout from each language interface to PLplot with the corresponding results for C. In general, these results are identical which is a stringent test of our language bindings. (Note it is the user's responsibility to insure the locales are consistent for all languages since inconsistent locales can produce inconsistent stdout results which have nothing to do with PLplot bindings or examples issues.)

You should search test results for obvious errors such as segfaults. In addition, you can test for rendering errors by viewing the file results using an appropriate viewer.

Results for -dev psc are a special case. To illustrate this, here are typical -dev psc results for example 1.

x01a.psc, x01c.psc, x01cxx.psc, x01d.psc, x01f.psc, x01f95.psc, x01j.psc, x01lua.psc, x01o.psc, x01ocaml.psc, x01p.psc, x01pdl.psc, and x01t.psc.

These correspond to Ada, C, C++, D, Fortran 77, Fortran 95, Java, Lua, Octave, OCaml, Python, Perl/PDL, and Tcl -dev psc (colour PostScript) results for our standard example 1. The test referred to above compares everything in this list, but x01c.psc against that file so rendering errors only need to be looked for in x01c.psc (with your favorite Postscript viewing application), and any of these files which the report shows are different from x01c.psc. And similarly for the -dev psc results for the rest of our 31 standard examples.

Here are typical plot file results from our standard example 1 for devices other than -dev psc.

x01c.pdfcairo, x01c.ps, x01c.psttf, x01c.psttfc, x01c01.bmpqt, x01c01.epsqt, x01c01.jpgqt, x01c01.pdfqt, x01c01.pngcairo, x01c01.pngqt, x01c01.ppmqt, x01c01.svg, x01c01.svgcairo, x01c01.svgqt, x01c01.tiffqt, and x01c01.xfig.

Since different devices are involved in all cases, these should be looked at individually for rendering errors (and similarly for the remaining 31 standard examples). Note such visual inspection is a huge job so we certainly don't expect it of our testers very often, but once every year or so and especially for newer examples that haven't been checked before is worth doing. On Unix platforms a general all-purpose viewer for all these file formats is the ImageMagick display application.

==== Invocation of legacy tests in the build tree ====

After running "make all" from the top-level of the build tree, then run

ctest --verbose >& ctest.out

This creates test plot file results in the plplot-test subdirectory of the build tree, and ctest.out should contain a table of comparisons of Postscript results from each of our standard examples and each of our language bindings against the corresponding C versions.

==== Invocation of tests in the build tree using the new testing framework ====

One advantage of the new testing framework is that it has full dependencies implemented (unlike ctest which requires "make all" to be run first).

A second advantage of the new testing framework is that for Generators with parallel execution ability, you can save a lot of time on hardware with more than one cpu by using the parallel execution options (e.g., the -j option for GNU make).

A final advantage of the new testing framework is the tests are finer grained. To see all the tests that are possible run

make help |grep test

(On platforms with CMake generators other than make, you will have to do something equivalent to this search to find all test targets.)

Three comprehensive test targets are test_diff_psc, test_noninteractive and test_interactive.

test_diff_psc generates all -dev psc results and compares them with the same report that is obtained from ctest. Note this target excludes anything but -dev psc results.

test_noninteractive runs test_diff_psc as well as every other PLplot example that produces a file. (Note that test_noninteractive is somewhat more comprehensive than legacy ctest and considerably more comprehensive than the test_diff_psc target.)

test_interactive runs all interactive devices for the standard C examples as well as all special interactive examples. Very little user-intervention is required to run these tests because, where possible, the PLplot -np (no-pause) command-line option is used for these tests.

=== Tests of the PLplot installation ===

After PLplot has been configured (with "cmake"), built (with "make"), and installed (with "make install"), you can test the installation using a legacy test system (implemented with Make, pkg-config, and GNU-bash) or our new test framework (implemented with CMake and bash [or win-bash]).

==== Legacy tests (Unix-only) of the PLplot installation ====

You can test the PLplot installation on Unix systems by doing the following commands:

cp -a $prefix/share/plplot$plplot_version/examples /tmp
cd /tmp/examples
make test_noninteractive >& make_test.out
make test_interactive

where "$prefix" is the installation prefix chosen at the configuration stage, and $plplot_version is the PLplot version (currently 5.9.4). The effect of the above "cp" and "cd" commands is to copy the examples subtree of the install tree to /tmp and build and test the examples in the copied subtree to keep a clean install tree. However, an alternative is to replace those two commands with

cd $prefix/share/plplot$plplot_version/examples

and build and test the install-tree examples right in the examples subtree of the install tree with the above "make" commands.

Regardless of whether you build and test the examples in a copy of the examples subtree of the install tree or directly in that subtree, check all the *.out files for any errors.

N.B. the above legacy "make test_noninteractive" command does the same tests for the installed PLplot version as ctest does for the build-tree version of PLplot. Although the tests are the same, the Makefile implementation is different from the ctest implementation in the build tree so that in particular you can do these install tree tests in parallel using the (GNU-)make -j option to greatly speed up these tests on a multi-processor computer. However, since make is required for this installed-examples implementation, it cannot be run on Windows.

N.B. the above legacy "make test_interactive" command executes our interactive examples. The results are similar to those of the test_interactive target implemented with our new test framework, but the implementation is very different (depending on a GNU-bash script rather than standard CMake cross-platform commands).

==== Cross-platform tests of the PLplot installation using the new test framework ====

Here is an example under Unix of how to test the PLplot installation using the new testing framework.
(Those using Windows platforms should be able to infer the equivalent of these commands.)

mkdir /tmp/build_dir
cd /tmp/build_dir
cmake $prefix/share/plplot$plplot_version/examples
make -j4 test_diff_psc >& make_test_diff_psc.out
make -j4 test_noninteractive >& make_test_noninteractive.out
make -j4 test_interactive >& make_test_interactive.out

Note these targets are essentially identical to the targets described above for the new test framework for the build tree because the same bash (or win-bash) scripts and essentially the same CMake logic is used to set up these targets. Similarly, all other fine-grained targets (which you can discover using the

make help |grep test

command) for the new test framework are available in this context as well. N.B. the test_noninteractive and test_interactive targets available here are more comprehensive than the same-named targets in the legacy installation test case and are implemented in a quite different (cross-platform) way with much
better dependencies.

===Testing Reports===
{| class="wikitable" style="text-align:center" border="5" cellspacing="5" cellpadding="2"
|+Table of test reports for PLplot
|-
!rowspan="5" valign="center"|Tester !! PLplot revision !! CMake version !! Platform
|-
! Pango/Cairo version !! Qt version !! Shared libraries? !! Dynamic drivers?
|-
! Build? !! test_ noninteractive? !! test_ interactive? !! ctest?
|-
! Traditional Installed examples? !! test_ noninteractive? !! test_ interactive?
|-
! CMake-based Installed examples? !! test_ noninteractive? !! test_ interactive? !! Notes
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Hazen Babcock || 11019 || 2.6.4 || Ubuntu Intrepid
|-
|system || 4.6.2 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || a B
|}

Testing notes (lower case notes concern configuration and build options while upper case notes concern errors):

a. Testing done on 64-bit (AMD64) hardware.

b. Used parallel make option (-j4) for all builds, installs, and test targets.

c. All suitable dependent libraries have been installed on the system so there are no device drivers from the default list for this platform that are missing from this test.

d. All compilers and bindings-related development packages have been installed on the system so there are no bindings that are missing from this test.

e. Java, Python, Octave, Perl/PDL, LUA, and OCaml bindings/examples require shared PLplot libraries in order to work so were not available for testing for this static PLplot libraries case.

A. No obvious configure, build, or install errors. No run-time errors in tests other than those noted in additional "upper-case" notes (if any).
B. test_noninteractive hangs at unpredictable points in the Qt device driver test.

Testing PLplot

2010-05-26T20:43:33Z

Hbabcock: /* Testing Reports */

We encourage those who build PLplot to test both their build-tree version and their installed-examples-tree version and report any problems back to either the plplot-general or plplot-devel mailing lists.

=== Testing Prerequisites ===

The legacy test for the build tree requires ctest (available as part of CMake) and bash on Unix systems or [http://win-bash.sourceforge.net/ win-bash] on Windows. The legacy test for the installed examples tree works only on Unix (Linux, Mac OS X, and presumably legacy Unix) and requires GNU-bash, make, and pkg-config.

In contrast to our legacy testing system, the new testing framework is essentially identical for both the build tree and installed examples tree. It just requires CMake (using any generator that is suitable for the Unix or Windows platform that is being used for the test), and bash on Unix or win-bash on Windows.

=== Build-tree tests ===

Build-tree tests can only be performed if cmake is invoked with the -DBUILD_TEST=ON option. Such tests are done from the top-level directory of the build tree (the directory where you invoke cmake command that configures the build of PLplot). The methods for invoking these tests are given below both for the legacy and new testing methods. These tests include executing all our 31 standard examples for all language interfaces and non-interactive device drivers that we currently support. This is a comprehensive test of the PLplot build. For example, our standard examples exercise virtually all of the PLplot API. Furthermore, this series of tests generates more than 2GB of plot files in various formats. The tests also include
a comparison of PostScript (-dev psc) results and stdout from each language interface to PLplot with the corresponding results for C. In general, these results are identical which is a stringent test of our language bindings. (Note it is the user's responsibility to insure the locales are consistent for all languages since inconsistent locales can produce inconsistent stdout results which have nothing to do with PLplot bindings or examples issues.)

You should search test results for obvious errors such as segfaults. In addition, you can test for rendering errors by viewing the file results using an appropriate viewer.

Results for -dev psc are a special case. To illustrate this, here are typical -dev psc results for example 1.

x01a.psc, x01c.psc, x01cxx.psc, x01d.psc, x01f.psc, x01f95.psc, x01j.psc, x01lua.psc, x01o.psc, x01ocaml.psc, x01p.psc, x01pdl.psc, and x01t.psc.

These correspond to Ada, C, C++, D, Fortran 77, Fortran 95, Java, Lua, Octave, OCaml, Python, Perl/PDL, and Tcl -dev psc (colour PostScript) results for our standard example 1. The test referred to above compares everything in this list, but x01c.psc against that file so rendering errors only need to be looked for in x01c.psc (with your favorite Postscript viewing application), and any of these files which the report shows are different from x01c.psc. And similarly for the -dev psc results for the rest of our 31 standard examples.

Here are typical plot file results from our standard example 1 for devices other than -dev psc.

x01c.pdfcairo, x01c.ps, x01c.psttf, x01c.psttfc, x01c01.bmpqt, x01c01.epsqt, x01c01.jpgqt, x01c01.pdfqt, x01c01.pngcairo, x01c01.pngqt, x01c01.ppmqt, x01c01.svg, x01c01.svgcairo, x01c01.svgqt, x01c01.tiffqt, and x01c01.xfig.

Since different devices are involved in all cases, these should be looked at individually for rendering errors (and similarly for the remaining 31 standard examples). Note such visual inspection is a huge job so we certainly don't expect it of our testers very often, but once every year or so and especially for newer examples that haven't been checked before is worth doing. On Unix platforms a general all-purpose viewer for all these file formats is the ImageMagick display application.

==== Invocation of legacy tests in the build tree ====

After running "make all" from the top-level of the build tree, then run

ctest --verbose >& ctest.out

This creates test plot file results in the plplot-test subdirectory of the build tree, and ctest.out should contain a table of comparisons of Postscript results from each of our standard examples and each of our language bindings against the corresponding C versions.

==== Invocation of tests in the build tree using the new testing framework ====

One advantage of the new testing framework is that it has full dependencies implemented (unlike ctest which requires "make all" to be run first).

A second advantage of the new testing framework is that for Generators with parallel execution ability, you can save a lot of time on hardware with more than one cpu by using the parallel execution options (e.g., the -j option for GNU make).

A final advantage of the new testing framework is the tests are finer grained. To see all the tests that are possible run

make help |grep test

(On platforms with CMake generators other than make, you will have to do something equivalent to this search to find all test targets.)

Three comprehensive test targets are test_diff_psc, test_noninteractive and test_interactive.

test_diff_psc generates all -dev psc results and compares them with the same report that is obtained from ctest. Note this target excludes anything but -dev psc results.

test_noninteractive runs test_diff_psc as well as every other PLplot example that produces a file. (Note that test_noninteractive is somewhat more comprehensive than legacy ctest and considerably more comprehensive than the test_diff_psc target.)

test_interactive runs all interactive devices for the standard C examples as well as all special interactive examples. Very little user-intervention is required to run these tests because, where possible, the PLplot -np (no-pause) command-line option is used for these tests.

=== Tests of the PLplot installation ===

After PLplot has been configured (with "cmake"), built (with "make"), and installed (with "make install"), you can test the installation using a legacy test system (implemented with Make, pkg-config, and GNU-bash) or our new test framework (implemented with CMake and bash [or win-bash]).

==== Legacy tests (Unix-only) of the PLplot installation ====

You can test the PLplot installation on Unix systems by doing the following commands:

cp -a $prefix/share/plplot$plplot_version/examples /tmp
cd /tmp/examples
make test_noninteractive >& make_test.out
make test_interactive

where "$prefix" is the installation prefix chosen at the configuration stage, and $plplot_version is the PLplot version (currently 5.9.4). The effect of the above "cp" and "cd" commands is to copy the examples subtree of the install tree to /tmp and build and test the examples in the copied subtree to keep a clean install tree. However, an alternative is to replace those two commands with

cd $prefix/share/plplot$plplot_version/examples

and build and test the install-tree examples right in the examples subtree of the install tree with the above "make" commands.

Regardless of whether you build and test the examples in a copy of the examples subtree of the install tree or directly in that subtree, check all the *.out files for any errors.

N.B. the above legacy "make test_noninteractive" command does the same tests for the installed PLplot version as ctest does for the build-tree version of PLplot. Although the tests are the same, the Makefile implementation is different from the ctest implementation in the build tree so that in particular you can do these install tree tests in parallel using the (GNU-)make -j option to greatly speed up these tests on a multi-processor computer. However, since make is required for this installed-examples implementation, it cannot be run on Windows.

N.B. the above legacy "make test_interactive" command executes our interactive examples. The results are similar to those of the test_interactive target implemented with our new test framework, but the implementation is very different (depending on a GNU-bash script rather than standard CMake cross-platform commands).

==== Cross-platform tests of the PLplot installation using the new test framework ====

Here is an example under Unix of how to test the PLplot installation using the new testing framework.
(Those using Windows platforms should be able to infer the equivalent of these commands.)

mkdir /tmp/build_dir
cd /tmp/build_dir
cmake $prefix/share/plplot$plplot_version/examples
make -j4 test_diff_psc >& make_test_diff_psc.out
make -j4 test_noninteractive >& make_test_noninteractive.out
make -j4 test_interactive >& make_test_interactive.out

Note these targets are essentially identical to the targets described above for the new test framework for the build tree because the same bash (or win-bash) scripts and essentially the same CMake logic is used to set up these targets. Similarly, all other fine-grained targets (which you can discover using the

make help |grep test

command) for the new test framework are available in this context as well. N.B. the test_noninteractive and test_interactive targets available here are more comprehensive than the same-named targets in the legacy installation test case and are implemented in a quite different (cross-platform) way with much
better dependencies.

===Testing Reports===
{| class="wikitable" style="text-align:center" border="5" cellspacing="5" cellpadding="2"
|+Table of test reports for PLplot
|-
!rowspan="5" valign="center"|Tester !! PLplot revision !! CMake version !! Platform
|-
! Pango/Cairo version !! Qt version !! Shared libraries? !! Dynamic drivers?
|-
! Build? !! test_ noninteractive? !! test_ interactive? !! ctest?
|-
! Traditional Installed examples? !! test_ noninteractive? !! test_ interactive?
|-
! CMake-based Installed examples? !! test_ noninteractive? !! test_ interactive? !! Notes
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || yes
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abcd A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.6.4 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Alan W. Irwin || 10954 || 2.8.1 || Debian Lenny
|-
|system || 4.6.1 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|-
|rowspan="5" valign="center"|Hazen Babcock || 11019 || 2.6.4 || Ubuntu Intrepid
|-
|system || 4.6.2 || no || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|yes || yes || yes || abce A
|}

Testing notes (lower case notes concern configuration and build options while upper case notes concern errors):

a. Testing done on 64-bit (AMD64) hardware.

b. Used parallel make option (-j4) for all builds, installs, and test targets.

c. All suitable dependent libraries have been installed on the system so there are no device drivers from the default list for this platform that are missing from this test.

d. All compilers and bindings-related development packages have been installed on the system so there are no bindings that are missing from this test.

e. Java, Python, Octave, Perl/PDL, LUA, and OCaml bindings/examples require shared PLplot libraries in order to work so were not available for testing for this static PLplot libraries case.

A. No obvious configure, build, or install errors. No run-time errors in tests other than those noted in additional "upper-case" notes (if any).

Overview of the status on Windows

2010-04-28T02:04:58Z

Hbabcock: Add note about cairo and Qt status

This page presents an overview of the various Windows platforms and the status
of the CBS for them.

The platforms are "canonical": we assume typical or often encountered installations.
For "bare Windows" this means Windows XP, Microsoft Visual C/C++ (version 6.0, 2003 or 2005, but
currently with an emphasis on version 6.0). For Cygwin and MinGW this is the suite of GCC compilers.

Status per 27 April 2010, Arjen Markus, Werner Smekal and Hazen Babcock

<pre>
----------------------+----------------+----------------+----------------+----------------+----------------+
Build aspects | Bare Windows | Cygwin | MinGW | Borland 5.5 |Open Watcom 1.5 +
----------------------+----------------+----------------+----------------+----------------+----------------+
Library options: | | | | | |
Static libraries | Yes | Yes | Yes | Yes | Yes |
Shared libraries (DLL)| Yes | Yes | Yes | Yes | Yes |
Dynamic drivers | Yes | Yes | Yes | . | . |
Freetype support | Yes | Yes | Yes | . | . |
QHull support | Yes | . | Yes | . | . |
AGG support | Yes | . | Yes | . | . |
| | | | | |
Languages: | | | | | |
C++ | Yes | Yes(1) | Yes | No | No(9) |
Fortran77 | Yes(10) | Yes(3) | Yes | - | |
Fortran95 | Yes(10) | Yes | Yes(3) | . | . |
Java | Yes | . | No | - | - |
Perl | . | . | . | - | - |
Python | Yes | . | Yes | - | - |
Ada | - | . | Yes | - | - |
Tcl | Yes(4) | Yes | Yes | - | - |
Tk | . | (5) | . | - | - |
| | | | | |
Drivers: | | | | | |
PostScript (psc) | Yes | Yes | Yes | Yes | Yes |
PostScript (psttf) | . | . | Yes | . | . |
Wingcc (7) | Yes | Yes | Yes | . | Yes |
gd (png, jpeg, gif) | Yes | Yes | Yes | Yes | No |
wxWidgets | Yes | . | Yes | . | . |
cgm | Yes | Yes | Yes | Yes | Yes |
svg | Yes | . | Yes | . | . |
pdf | Yes | . | Yes | . | . |
cairo (11) | . | . | Yes | . | . |
Qt | . | . | Yes | . | . |
----------------------+----------------+----------------+----------------+----------------+----------------+
</pre>

Notes:

* A dot (.) simply means this aspect has not yet been tested.
* A dash (-) means that this option will not be supported for this compiler, as others covers this field.
* (1) GNU C++ caused a problem on one machine, but others were successful. Something wrong with the toolchain?
* (2) Obsolete
* (3) The Fortran compilers used are g77 and gfortran. For MingW it was tested with g95.
* (4) The build succeeds currently, but pltcl.exe, the shell that is built, is missing DLLs. You need to copy these into the proper directory manually. (And you need to tell it where to find the Tcl initialisation files).
* (5) The Tk bindings may use more of the X Window library than has been ported to the Cygwin/MinGW platform. There is also the issue of several UNIX specific Tcl routines that have no equivalent on Windows.
* (7) The fact that the wingcc driver works under bare Windows, means that the win3 driver is redundant. We could phase it out in due time.
* (8) (Regarding extra CMake module) Obsolete
* (9) C++ Bindings are in the moment not available, because of invalid characters in the foldername.
* (10) Compaq Visual Fortran works now with the extra CMake module, when using shared libraries (DLL). Main issue: the location of all DLLs that are used.
* (11) Cairo was obtained as part of GTK here: http://www.gtk.org/download-windows.html

Configure PLplot for MinGW/CLI

2010-01-11T00:18:14Z

Hbabcock:

You need a working MinGW installation. Start the command line interface (NOT MSYS - see below) and issue the following commands:

cd plplot
mkdir buildmingw
cd buildmingw
cmake -G "MinGW Makefiles" -DCMAKE_INSTALL_PREFIX=install ..
mingw32-make
mingw32-make install

For a shared plplot build you need to have the dll directory in the build tree (i.e. the buildmingw\dll folder) in your system path. This will also enable you to run the build tree examples (see below) without having to copy all the dlls.

This will build a shared plplot library and install all files into the directory <tt>plplot\buildmingw\install</tt>. The following options are available for cmake:

* <tt>-DBUILD_SHARED_LIBS=OFF</tt>: static build of plplot
* <tt>-DCMAKE_VERBOSE_MAKEFILE=ON</tt>: makefiles provide verbose informations
* <tt>-DBUILD_TEST=ON</tt>: all examples will be built also (for test purposes)
* [[Configuration of wxWidgets driver]]

If you used the <tt>-DBUILD_TEST=ON</tt> option, you need to copy some files in order to run the examples:

cd examples\c
copy ..\..\..\data\*.fnt .

and additionally some dlls for a shared plplot built:

copy ..\..\src\libplplotd.dll .
copy "..\..\bindings\c++\libplplotcxxd.dll" . (for c++ examples)
copy ..\..\lib\csa\libcsirocsa.dll . (if library as built)

and for the wxWidgets driver (if wxWidgets library is shared):

copy %WXWIN%\lib\gcc_dll\wxmsw26d_gcc_custom.dll .

if this dll is not in the path.

Note on MSYS:

The MSYS command window (rxvt) is somewhat awkward to use with an interactive program. It buffers
the output, so that the question what device you want (as printed by plinit()) appears only after
you have given an answer. The net effect is that the program appears to hang. It is easier to use an
ordinary DOS-box.

Note on Python:

You need to either add the install tree directory plplot\lib\site-packages to your PYTHONPATH or copy the contents of that directory to your PythonX.Y\Lib\site-packages directory. You may also need to rename _plplotcmodule.dll to _plplotc.pyd, plplot_pyqt4.dll to plplot_pyqt4.pyd and plplot_widgetmodule.dll to plplot_widgetmodule.pyd

Mac OSX Status

2007-11-18T00:41:57Z

Hbabcock:

Mac OSX Status

2007-11-17T19:58:41Z

Hbabcock: Updated to reflect what works with 5.8.0

Mac OSX Status

2007-11-17T19:53:47Z

Hbabcock:

Mac OSX

2006-11-14T04:00:06Z

Hbabcock: Addded a note about Tcl/Tk

Once you have installed cmake and downloaded cvs plplot, the following commands should get you up and running:

cd plplot-working-directory
mkdir plplot-build
cd plplot-build
ccmake /path/to/cvs-plplot/directory
make
make install (possibly as root)

ccmake is a command-line interface to the cmake command which presents an annotated list of the possible PLplot build options that can be set. (More experienced users may want to use the cmake command directly where all build options are set using -D options.)

The following specific options are recommended at this time:

1. Set CMAKE_INSTALL_PREFIX to your installation prefix.
2. Set PLD_wxwidgets to OFF, unless you have a more recent version than that which comes standard with OS-X.
3. Depending on the location of swig, you may have to specify SWIG_DIR.

Things to watch out for:

1. cmake is really good at finding libraries, but not so good at using the same library when multiple
options are present. For example, I found that I had no less than 4 versions of Python on my
system, and cmake was trying to use all of them for different purposes (library from one, executable
from another, etc...). This also a problem for Tcl/Tk where cmake will try really hard to use
Tk.framework and Tcl.framework instead of the fink equivalents.
2. Once you have specified the location of swig (i.e. SWIG_DIR), you will need to configure again,
then set ENABLE_python to ON, then configure again to get python setup properly.

Please see that status page for what is known to work on OS-X.

Mac OSX Status

2006-11-14T03:57:31Z

Hbabcock:

Mac OSX Status

2006-11-14T03:57:02Z

Hbabcock: Updated status of Tcl/Tk on OS-X

Mac OSX Status

2006-10-19T01:53:51Z

Hbabcock: Updated to reflect the current status

Mac OSX

2006-10-03T04:38:39Z

Hbabcock:

Once you have installed cmake and downloaded cvs plplot, the following commands should get you up and running:

cd plplot-working-directory
mkdir plplot-build
cd plplot-build
cmake /path/to/cvs-plplot/directory
ccmake . (setting explained below)
make
make install (possibly as root)

Configuring the build with ccmake:

1. Set PLD_wxwidgets to OFF, unless you have a more recent version than that which comes standard with OS-X.
2. Set ENABLE_tcl and ENABLE_tk to off.
3. Depending on the location of swig, you may have to specify SWIG_DIR.

Things to watch out for:

1. cmake is really good at finding libraries, but not so good at using the same library when multiple
options are present. For example, I found that I had no less than 4 versions of Python on my
system, and cmake was trying to use all of them for different purposes (library from one, executable
from another, etc...).
2. Once you have specified the location of swig (i.e. SWIG_DIR), you will need to configure again,
then set ENABLE_python to ON, then configure again to get python setup properly.

Please see that status page for what is known to work on OS-X.

Mac OSX

2006-10-03T04:38:24Z

Hbabcock: Changed to reflect existence of a separate status page

Once you have installed cmake and downloaded cvs plplot, the following commands should get you up and running:

cd plplot-working-directory
mkdir plplot-build
cd plplot-build
cmake /path/to/cvs-plplot/directory
ccmake . (setting explained below)
make
make install (possibly as root)

Configuring the build with ccmake:

1. Set PLD_wxwidgets to OFF, unless you have a more recent version than that which comes standard with OS-X.
2. Set ENABLE_tcl and ENABLE_tk to off.
3. Depending on the location of swig, you may have to specify SWIG_DIR.

Things to watch out for:

1. cmake is really good at finding libraries, but not so good at using the same library when multiple
options are present. For example, I found that I had no less than 4 versions of Python on my
system, and cmake was trying to use all of them for different purposes (library from one, executable
from another, etc...).
2. Once you have specified the location of swig (i.e. SWIG_DIR), you will need to configure again,
then set ENABLE_python to ON, then configure again to get python setup properly.

Plase see that status page for what is known to work on OS-X.

Mac OSX Status

2006-10-03T04:33:11Z

Hbabcock: Initial record of PLplot status on OS-X

Main Page

2006-10-03T04:00:26Z

Hbabcock: Changed OS-X section

This is the (un-)official Wiki for [http://plplot.sf.net PLplot]. It should provide additional information to complement the PLplot [http://plplot.sourceforge.net/docbook-manual/ documentation].

== Building PLplot ==
Our traditional Autotools Build System (ABS) may be used to configure the PLplot build on Unix platforms. Alternatively, our new CMake Build System (CBS) may be used to configure the PLplot build on both Unix and Windows platforms.

=== Building PLplot with our traditional ABS ===

=== Building PLplot with our new CBS ===

Our CMake Build System (CBS) is a build-system paradigm shift compared to our traditional Autotools Build System (ABS) so it is important to consult the CMake documentation to get the most out of our CBS. That documentation is quite thorough but tends to be a bit scattered so we have collected what we think our the best [[general CMake documentation links]] for your convenience.

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

Our ABS does some source-code preparation just before the distribution tarball is built; it prepares source code for a private copy of the libltdl library that is required to dynamically load plotting devices and it uses SWIG to generate the source code needed for our Python and Java interfaces to PLplot. In contrast, our CBS does source-code preparation at build time rather than distribution time. The result is that our CBS has the following two important prerequisites beyond what is required for our ABS: the libltdl library (a small part of the libtool software package) and SWIG. If the user does not have these additional prerequisites installed, our CBS emits a WARNING message and removes the corresponding components of PLplot (i.e., dynamic devices or the Python and Java interfaces) from the build.

There are also several [[CMake options for PLplot]] which can be set for cmake to personalize your build.

==== Unix ====

===== (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 PKG_CONFIG_PATH=/home/software/libLASi/install/lib/pkgconfig
export CMAKE_LIBRARY_PATH=/home/software/autotools/install/lib:/home/software/cgmlib/cd1.3
export CMAKE_INCLUDE_PATH=/home/software/autotools/install/include:/home/software/cgmlib/cd1.3

In these special cases, <tt>PKG_CONFIG_PATH</tt> helps CMake to use the <tt>pkg-config</tt> command for a non-standard libLASi install location; <tt>CMAKE_LIBRARY_PATH</tt> helps CMake to find <tt>libltdl</tt> and <tt>libcd</tt> in non-standard install locations; and <tt>CMAKE_INCLUDE_PATH</tt> helps CMake to find the headers for <tt>libltdl</tt> and <tt>libcd</tt> in non-standard install 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 CBS which makes for very fast builds, but slow execution.

===== cmake invocation =====

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. In this 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). You can also specify options using the convenient ccmake command-line interface to cmake. That interface also presents annotations for the options.

Note 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 processing =====
[[The PLplot build and install]] follows the cmake invocation. The installed tree can be tested with [[the PLplot install-tree test]] for a large variety of PLplot device drivers. In addition, build-tree tests may be done with the "ctest" command. Note, these ctests 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).

===== Specifics for various Unix platforms =====
* [[Linux]]

==== Mac OSX ====
* [[Mac OSX]] instructions
* [[Mac OSX Status]] current status

==== Windows ====

===== Instructions per Windows platform =====

* [[Configure PLplot for Visual CXX]]
* [[Configure PLplot for MinGW/CLI]]
* [[Configure PLplot for cygwin]]
* [[Configure PLplot for Borland CXX 5.5 (free command line tools)]]

===== Status of CBS on Windows =====

* [[Overview of the status on Windows]]

== Edit Wiki pages ==

Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software. More information can be found here:
* [http://www.mediawiki.org/wiki/Help:Configuration_settings Configuration settings list]
* [http://www.mediawiki.org/wiki/Help:FAQ MediaWiki FAQ]
* [http://mail.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]

Mac OSX

2006-09-28T03:12:38Z

Hbabcock:

Once you have installed cmake and downloaded cvs plplot, the following commands should get you up and running:

cd plplot-working-directory
mkdir plplot-build
cd plplot-build
cmake /path/to/cvs-plplot/directory
ccmake . (setting explained below)
make
make install (possibly as root)

Configuring the build with ccmake:

1. Set PLD_wxwidgets to OFF, unless you have a more recent version than that which comes standard with OS-X.
2. Set ENABLE_tcl and ENABLE_tk to off.
3. Depending on the location of swig, you may have to specify SWIG_DIR.

Things to watch out for:

1. cmake is really good at finding libraries, but not so good at using the same library when multiple
options are present. For example, I found that I had no less than 4 versions of Python on my
system, and cmake was trying to use all of them for different purposes (library from one, executable
from another, etc...).
2. Once you have specified the location of swig (i.e. SWIG_DIR), you will need to configure again,
then set ENABLE_python to ON, then configure again to get python setup properly.

What is known to work on OS-X:

1. The AquaTerm driver.
2. Fortran77 [GNU Fortran (GCC) 3.4.4]
3. Fortran95 [GNU Fortran 95 (GCC) 4.2.0 20060512 (experimental)]
4. Python2.4 [Python 2.4.2 (#1, Feb 11 2006, 21:54:49)]
(I think that this version came with my OS-X box, or was part of the XCode (v2.1) developer tools.

Mac OSX

2006-09-18T03:29:54Z

Hbabcock:

Once you have installed cmake and downloaded cvs plplot, the following commands should get you up and running:

cd plplot-cvs
cmake .
ccmake . (setting explained below)
make
make install (possibly as root)

Configuring the build with ccmake:

1. Set PLD_wxwidgets to OFF, unless you have a more recent version than that which comes standard with OS-X.
2. Set ENABLE_tcl and ENABLE_tk to off.
3. Depending on the location of swig, you may have to specify SWIG_DIR.

Things to watch out for:

1. cmake is really good at finding libraries, but not so good at using the same library when multiple
options are present. For example, I found that I had no less than 4 versions of Python on my
system, and cmake was trying to use all of them for different purposes (library from one, executable
from another, etc...).
2. Once you have specified the location of swig (i.e. SWIG_DIR), you will need to configure again,
then set ENABLE_python to ON, then configure again to get python setup properly.

What is known to work on OS-X:

1. The AquaTerm driver.
2. Fortran77 [GNU Fortran (GCC) 3.4.4]
3. Fortran95 [GNU Fortran 95 (GCC) 4.2.0 20060512 (experimental)]
4. Python2.4 [Python 2.4.2 (#1, Feb 11 2006, 21:54:49)]
(I think that this version came with my OS-X box, or was part of the XCode (v2.1) developer tools.

Mac OSX

2006-09-18T03:29:03Z

Hbabcock: Initial OS-X notes

Once you have installed cmake and cvs plplot, the following commands should get you up and running:

cd plplot-cvs
cmake .
ccmake . (setting explained below)
make
make install (possibly as root)

Configuring the build with ccmake:

1. Set PLD_wxwidgets to OFF, unless you have a more recent version than that which comes standard with OS-X.
2. Set ENABLE_tcl and ENABLE_tk to off.
3. Depending on the location of swig, you may have to specify SWIG_DIR.

Things to watch out for:

1. cmake is really good at finding libraries, but not so good at using the same library when multiple
options are present. For example, I found that I had no less than 4 versions of Python on my
system, and cmake was trying to use all of them for different purposes (library from one, executable
from another, etc...).
2. Once you have specified the location of swig (i.e. SWIG_DIR), you will need to configure again,
then set ENABLE_python to ON, then configure again to get python setup properly.

What is known to work on OS-X:

1. The AquaTerm driver.
2. Fortran77 [GNU Fortran (GCC) 3.4.4]
3. Fortran95 [GNU Fortran 95 (GCC) 4.2.0 20060512 (experimental)]
4. Python2.4 [Python 2.4.2 (#1, Feb 11 2006, 21:54:49)]
(I think that this version came with my OS-X box, or was part of the XCode (v2.1) developer tools.