PLplotWiki - User contributions [en]

Testing PLplot

2010-05-27T07:59:34Z

Andrewr:

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
|-
|rowspan="5" valign="center"|Andrew Ross || 11024 || 2.8.0 || Ubuntu Lucid
|-
|system || 4.6.2 || yes || no
|-
|yes || yes || yes || no
|-
|no || no || no
|-
|no || no || no || c d
|}

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

Building PLplot with a cross-compiler

2009-03-03T12:44:19Z

Andrewr: Initial instructions on using cmake to build a cross-compiled version of plplot

From version 2.6.0 cmake includes support for cross-compiling. The [http://www.cmake.org/Wiki/CMake_Cross_Compiling CMake wiki] provides a useful source of background information here.

Cross-compiling plplot is complicated because a full build involves lots of external libraries for different drivers and multiple different compilers /interpreters for the language bindings. However, it is possible to build a cut-down version of PLplot using cmake. PLplot compiles and runs several executables to create source files / data for the project at build time. Obviously it is not generally possible to run the cross-compiled versions and so access is also required to a native build tree in which to find the native versions of the build-time executables. Support for this was only added to PLplot on 3rd March 2009 (svn revision 9665).

The following instructions were written and tested on using the mingw32 cross-compiler for Windows running under Linux. Debian and Ubuntu supply packages for this environment so it is simple to install and test.

==Build a native version of PLplot==
This can just be a normal PLplot build. The only thing to be careful of it to ensure that it uses dynamic drivers if you intend to use them for the cross compiler otherwise get-drv-info will not be built.

==Create a CMake toolchain==
See the [http://www.cmake.org/Wiki/CMake_Cross_Compiling CMake wiki] for details of this for individual platforms. The mingw32 example worked fine for me.

==Building a cross-compiled version of PLplot==
* Create a new directory for the cross-compile build and change to that directory.
* Run cmake.

** You probably want to disable all languages and drivers by default and then just enable the ones you need. You can achieve this by setting DEFAULT_NO_DEVICES=ON and DEFAULT_NO_BINDINGS=ON. Failure to do this can lead to strange results if cmake picks up native rather than cross-compiler versions of tools, for example the fortran compiler, which are not part of your toolchain.
** You will need to set the following CMake variables.
*** CMAKE_TOOLCHAIN_FILE: points to the CMake toolchain file for this cross-compiler.
*** CMAKE_NATIVE_BINARY_DIR: points to the top-level directory in the native PLplot build tree.
** You will need to disable pkg-config support or ensure that pkg-config is using the correct package information files for the cross-platform. The simplest way of disabling this is by setting PKG_CONFIG_EXECUTABLE to something like NOT-FOUND.
** You will either need to disable support for the CSA library, or explicitly set NanAwareCCompiler (probably to ON) since this uses a build-time executable to check for support. This can't be executed for a cross-compiled environment.

* Run make to build the cross-compiled version of PLplot.

Using this method I have successfully cross-compiled the C++ bindings and the ps and svg drivers. Note that neither of these has external dependencies. For reference the cmake command line looked like
cmake -DCMAKE_TOOLCHAIN_FILE=~/Toolchain-mingw32.cmake -DDEFAULT_NO_DEVICES=ON -DPLD_ps=ON -DPLD_svg=ON -DPKG_CONFIG_EXECUTABLE=Not-Found -DDEFAULT_NO_BINDINGS=ON -DENABLE_cxx=ON -DNaNAwareCCompiler=ON -DCMAKE_NATIVE_BINARY_DIR=/home/andrew/software/plplot/build
../plplot

Main Page

2009-03-03T11:10:12Z

Andrewr:

This is the official Wiki for [http://plplot.sf.net PLplot]. It should provide additional information to complement the PLplot [http://plplot.sourceforge.net/docbook-manual/ documentation].
* [http://plplot.sf.net PLplot Homepage]
* [http://sourceforge.net/projects/plplot/ PLplot sourceforge project page]
* Download source: [http://sourceforge.net/project/showfiles.php?group_id=2915&package_id=2865&release_id=555104 stable] [http://sourceforge.net/project/showfiles.php?group_id=2915&package_id=2865&release_id=575403 development], [http://www.miscdebris.net/plplot_weeklies weekly source packages]

{| style="margin: 5px 0px 10px 0px;" cellpadding="0" cellspacing="0" border="0"
| valign="top" width="50%" style="background: #f6f6f6; border: #bbb 1px solid; padding: 0px 10px 5px 10px;" |
<h2>Configure and build PLplot</h2>
* [[Building PLplot|Generic instructions for the CMake-based build system]]
* [[Specifics for various platforms|Specific instructions for Linux, Mac OS X and Windows]]
* [[CMake options for PLplot|CMake options specific for PLplot]]
* [[Building PLplot with a cross-compiler]]
* [[Third-party libraries]]
| <div style="width: 10px;"></div>
| valign="top" width="50%" style="background: #f6f6f6; border: #bbb 1px solid; padding: 0px 10px 5px 10px;" |
<h2>Using PLplot</h2>
* Tutorials for C, C++, Python
* [[Using PLplot|Specific instructions for Linux, Mac OS X and Windows]]
* Templates C, C++, Python
* [[Frequently Asked Questions]]
* [[User supplied Screenshots and examples]]
| <div style="width: 10px;"></div>
|-
| colspan="4" | <div style="height: 10px;"></div>
|-
| valign="top" width="50%" style="background: #f6f6f6; border: #bbb 1px solid; padding: 0px 10px 5px 10px;" |
<h2>Available Drivers and Language Bindings</h2>
* Drivers: svg, pdf, cairo, ...
* Language Bindings: C, C++, D, Python, Tcl/Tk,
* [[Overview of the status on Windows|Driver/Binding status on Windows]]
* [[Mac OSX Status|Driver/Binding status on Mac OS X]]
| <div style="width: 10px;"></div>
| valign="top" width="50%" style="background: #f6f6f6; border: #bbb 1px solid; padding: 0px 10px 5px 10px;" |
<h2>Documentation and Support</h2>
* [http://plplot.sourceforge.net/documentation.php Official PLplot Documentation]
* [http://plplot.sourceforge.net/examples.php Screenshots and examples]
* [http://sourceforge.net/mailarchive/forum.php?forum_name=plplot-general User mailing list] ([http://www.mail-archive.com/plplot-general@lists.sourceforge.net/ Search])
* [http://sourceforge.net/mailarchive/forum.php?forum_name=plplot-devel Developer mailing list] ([http://www.mail-archive.com/plplot-devel@lists.sourceforge.net/ Search])
| <div style="width: 10px;"></div>
|-
| colspan="4" | <div style="height: 10px;"></div>
|-
| valign="top" width="50%" style="background: #f6f6f6; border: #bbb 1px solid; padding: 0px 10px 5px 10px;" |
<h2>Developer sections</h2>
* [[Subversion access]]
* [[Submit a patch]]
* [[Debugging code]]
* [[Documenting the undocumented]]
* [[Todo List]]
| <div style="width: 10px;"></div>
| valign="top" width="50%" style="background: #f6f6f6; border: #bbb 1px solid; padding: 0px 10px 5px 10px;" |
<h2>Miscellaneous</h2>
* Setup Compiler Suites: [[setup_mingw|MinGW]], [[setup_watcom|Open Watcom]], [[setup_visualc|Visual C++]], [[setup_cygwin|Cygwin]], [[setup_cli|Windows CLI]]
| <div style="width: 10px;"></div>
|}

=== 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]

=== Maintain Wiki ===
This wiki will be backed up on a regular basis. Use these [[BackupInstructions]].
To restore a backup follow these [[RestoreInstructions]].
__NOTOC__ __NOEDITSECTION__

Todo List

2009-01-26T10:19:58Z

Andrewr: /* Bindings */

== PLplot Core ==

== Drivers ==

=== wxWidgets ===
* fix crash in example 14 when master window is closed (ws)
* only master should handle return key in example 14 (ws)

== Bindings ==
* AGG backend can't be used in wxWidgets bindings (ws)

* octave style graphics routines follow the style of older octave / matlab versions. Need extensive updating to be more like octave 3.0 (and current matlab). This is a non-trivial exercise, but exceedingly worthwhile. Volunteers? (AR)

== Examples ==
* return should end wxPLplotdemo (ws)
* backend name in title of wxPLplotdemo (ws)

== Documentation ==

== Webpage ==

== Testing ==
* replace the example 14 call in the test scripts, so that it also works in Windows (ws)

Additional notes for ifort users

2008-08-18T09:38:38Z

Andrewr:

Some versions of ifort may need additional command line options to ensure all examples work correctly. To set options for the fortran compiler you need to set the FC environment variable before running cmake. The syntax depends on which shell you are using, e.g.

export FC="ifort --assume byterecl" (bash / sh)

setenv FC "ifort --assume byterecl" (csh / tcsh)

=== Useful command line options ===

; --assume byterecl
: Assume fortran records are 1 byte long when reading in unformatted files. The default for ifort is 4 bytes (as for v8.1) however example 20 currently assumes 1 byte records. This option will ensure example 20 works correctly. It is not necessary for building the core plplot library and fortran bindings.

Additional notes for ifort users

2008-08-18T09:38:19Z

Andrewr:

Some versions of ifort may need additional command line options to ensure all examples work correctly. To set options for the fortran compiler you need to set the FC environment variable before running cmake. The syntax depends on which shell you are using, e.g.

export FC="ifort --assume byterecl" (bash / sh)

setenv FC "ifort --assume byterecl" (csh / tcsh)

=== Useful command line options ===

; --assume byterecl
: Assume fortran records are a byte long when reading in unformatted files. The default for ifort is 4 bytes (as for v8.1) however example 20 currently assumes 1 byte records. This option will ensure example 20 works correctly. It is not necessary for building the core plplot library and fortran bindings.

Additional notes for ifort users

2008-08-18T09:38:05Z

Andrewr: Specific command line options for ifort compiler

Some versions of ifort may need additional command line options to ensure all examples work correctly. To set options for the fortran compiler you need to set the FC environment variable before running cmake. The syntax depends on which shell you are using, e.g.

export FC="ifort --assume byterecl" (bash / sh)
setenv FC "ifort --assume byterecl" (csh / tcsh)

=== Useful command line options ===

; --assume byterecl
: Assume fortran records are a byte long when reading in unformatted files. The default for ifort is 4 bytes (as for v8.1) however example 20 currently assumes 1 byte records. This option will ensure example 20 works correctly. It is not necessary for building the core plplot library and fortran bindings.

Specifics for various platforms

2008-08-18T09:32:19Z

Andrewr: /* Linux */

==== Linux ====
* [[Linux]]
* [[List of Debian/Ubuntu packages]] - in order to be able to configure and compile the PLplot library this page contains a list of Debian/Ubuntu packages needed.
* [[Additional notes for ifort users]]

==== Mac OSX ====
* [[Mac OSX]] instructions

==== 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)]]
* [[Configure PLplot for Borland Turbo C++ Explorer Edition (free IDE and compiler)]]
* [[Install 3rd party libraries]]