Information for developers

The configured bash test scripts in this directory are designed to be used in 5
(!) different testing contexts.  These contexts are the following:

1. Ordinary CMake targets that perform tests for the CMake-based build
   system for the source tree (if -DBUILD_TEST=ON).  Scripts are
   configured into the ${CMAKE_BINARY_DIR}/plplot_test directory.

2. CMake ctest targets that perform tests for the CMake-based build
   system for the source tree (if -DBUILD_TEST=ON).  Scripts are
   configured into the ${CMAKE_BINARY_DIR}/plplot_test directory

3. Ordinary CMake targets that perform tests for the CMake-based build
   system for the installed examples.  Scripts are configured
   separately for the install-tree case and installed at the top-level
   directory of the installed examples = ${DATA_DIR}/examples.

4. (Planned) CMake ctest targets that perform tests for the
   CMake-based build system for the installed examples.  Scripts are
   configured separately for the install-tree case and installed at
   the top-level directory of the installed examples =
   ${DATA_DIR}/examples.

5. Traditional make targets that perform tests for the traditional
   (Makefile + pkg-config) build system for the installed examples.
   Scripts are configured separately for the install-tree case and
   installed at the top-level directory of the installed examples =
   ${DATA_DIR}/examples.

EXAMPLES_PREFIX and SRC_EXAMPLES_PREFIX are the environment
variables that designates where the examples are found for the
front ends for these different contexts.  These environment variables
can be set externally or internally (in, e.g., the plplot-test.sh
script using the script options --examples-prefix and/or
--src-examples-prefix).  The default values of these environment
variables are ".", i.e., the current directory.  Furthermore,
$EXAMPLES_PREFIX/c must be an existing directory.  Note that SRC_EXAMPLES_PREFIX
is only used in a fairly limited number of cases.  Those are the octave
case (where it is used in both the core build and installed examples cases) and the
python and lua cases (where it is used in just the installed examples case).

These environment variables are set for the 5 different contexts
as follows:

1 and 2: EXAMPLES_PREFIX=${CMAKE_BINARY_DIR}/examples SRC_EXAMPLES_PREFIX=${CMAKE_SOURCE_DIR}/examples

3 and 4: EXAMPLES_PREFIX=default ("." = top-level of build-tree for installed examples) SRC_EXAMPLES_PREFIX=${CMAKE_CURRENT_SOURCE_DIR} (= top-level of source tree for installed examples)

5. EXAMPLES_PREFIX=default (= "." = top-level of source-tree for installed examples) SRC_EXAMPLES_PREFIX= default (= "." = top-level of source-tree for installed examples)

Notes on the "front ends" for each of these contexts:

* Ada, C, C++, D, Fortran, Java, and OCaml:
Thse are all languages where the examples are compiled and linked for
all contexts with the build results stored in the ada, c, cxx, d,
fortran, java, and ocaml subdirectories of EXAMPLES_PREFIX.  For this
group of compiled languages SRC_EXAMPLES_PREFIX is ignored, and the
only configurable template file in the examples is
examples/fortran/plfortrandemos.inc.in where the configuration has
nothing to do with location so is the same for all contexts.

* plrender:
This is a special case that is virtually identical to the C case
(including ignoring SRC_EXAMPLES_PREFIX) except that -dev plmeta is
used to provide intermediate results and plrender used to provide
final results to compare with the C results.  N.B. I am not sure
whether this works anymore since -dev plmeta and plrender are no
longer enabled by default (because of -dev plmeta and plrender UTF-8
and other issues) so may have fallen into disrepair.

* Tcl:

This is also a case where SRC_EXAMPLES_PREFIX is ignored.  The plmeta
application (corresponding to the prefixed "plmeta" CMake targets, i.e.,
PLPLOT::plmeta and ${WRITEABLE_TARGET}plmeta) is used
to help render results.  The Tcl examples use the following
configured files:

examples/tcl/pltcl_standard_examples(.in)
examples/tcl/tclsh_standard_examples(.in)
examples/tcl/x??(.in)

For contexts 1 and 2 these files are configured from the source tree
to corresponding build directory by the core CMake-based build system
and for contexts 3 and 4 the file templates must be installed (by the
core build system) to examples/tcl in the installed examples and
configured from there to the corresponding build directory by the
CMake-based build system for the installed examples.  The traditional
build system for the installed examples (context 5) is too primitive
to configure files so for this special context these files must be
preconfigured and installed in the installed examples by the
CMake-based core build system where they are accessed by the
traditional build system using the (default) EXAMPLES_PREFIX of ".".

* Octave:
The tests are done from one octave session rather than for individual
octave sessions.  The setup of that octave session (in test_octave.sh
and test_octave_interactive.sh) is configured in the present directory
and depends on a fairly large number of different locations that occur
in two prefix locations.  For this reason, both EXAMPLES_PREFIX and
SRC_EXAMPLES_PREFIX are used for this case.  Note, that although all
test shell scripts in the present directory are configured (including
the octave-related test scripts), the octave examples themselves
contain no configured files.

* Python and Lua:
This is the set of front-ends that use the EXAMPLES_PREFIX environment
variable to help find the examples in the core build tree, and the
SRC_EXAMPLES_PREFIX environment variable to help find the examples in the
installed examples tree.  Additional notes for these languages:

 + Python:
 The Python examples use the following configured files:

 examples/python/plplot_python_start.py(.in)
 examples/python/test_plsmem.py(.in)

 In the core build case (contexts 1 and 2) these files are configured
 to the build tree and the relevant examples files also copied over to
 the build tree so that all Python examples are run there.  In the
 installed examples case (contexts 3, 4 and 5) the Python examples are
 run in situ in the source tree (see remarks concerning
 SRC_EXAMPLES_PREFIX above) so special configurations of the above
 files need to be installed for that case by the core build system
 and the installed examples build systems do not configure the
 above files.

 + Lua:
 The Lua examples use the following configured file:

 examples/lua/plplot_examples.lua(.in)

 Lua uses exactly the same paradigm as the above Python case concerning
 how this file is configured and installed and how the Lua examples
 are copied to the build tree for the core build case.
