NAME

Common.smak

DESCRIPTION

Used as the common Slay::Makefile input for all the Text::Restructured tests. It contains all the infrastructure needed for executing the python tests from docutils, while still providing tailorability for tests that do not fit the framework. The tests are divided into suites (e.g., 10_parse), each of which can have more than one .t file in it with its associated .init directory to implement multiple related tests. The customizability comes the following files (relative to the .dir directory created by gress.pm):

../Suite.smak

If it exists, overrides variables for the entire suite.

Dir.smak

If it exists, allows overriding for the directory and for individual tests within the directory

TARGETS

pretest

Returns the dependencies in global variable @PRETESTS, which is initialized to the targets unpack and find_oks, but can be added to by the custom Slay::Makefile files above.

unpack

Checks for a python test file and, if it exists, calls the extract_tests script from the tbin directory on it to create a series of .rst and .dom files for testing.

find_oks

Sets the global variable @OKS to contain the list of .rst files in the directory with the .rst extension replaced by .ok. Override this target if there is a different way to determine the list of targets corresponding to tests.

test

Returns the global variable @OKS.

%.ok

Looks for an expect file for the $1 part (the part matching the first %) in order to determine which writer to use when calling prest. For writer xyz, the expect file should be one of

$1.xyz

The unpacked python expects all have this form.

$1.myxyz

Sometimes prest intentionally does not match the python output, so $1.myxyz is used in preference to $1.xyz if both exist.

$1.xyz.re

Sometimes a regular expression difference, using the rediff script in the tbin directory, needs to be done for fault grading. This file contains regular expressions and is used in preference to either of the previous two.

Note: There are two exceptions to the one-to-one mapping between xyz and the writer namely, namely tex runs the latex writer and idx runs the index writer.

This target returns an error if no expect file for a known writer is found.

After determining which writer is appropriate, this target returns two dependencies, one of which will be the output of the writer ($1.xyz.out), and the other of which is the file against which fault grading occurs. If the expect file has extension .xyz.re, then rediff is used for fault grading, and the fault grading file is $1.xyz.re. Otherwise, diff is used for fault grading and the fault grading file is $1.xyz.df. If a diff fault grading fails, then the <$1.ok> target repeats the fault grading using rediff.

%.%.df

Copies $1.stderr, if it exists, and the first of $1.my$2 or $1.$2 to the target, where $2 is the writer. Thus, any error messages printed to STDERR become part of the fault grading.

%.%.re

If there was already a $1.$2.re file, this rule does nothing. Otherwise, it was invoked because the straight diff failed. It passes $1.stderr, if it exists, and the first of $1.my$2 or $1.$2 as arguments to the script re$2 (e.g., redom), located in the tbin directory. The purpose of such a script is to elide with regular expressions that part of the output that can validly differ.

%.%.out%

Dependencies are $1.rst (if it exists), the prest script, and the file containing the implemention of the writer $2. Invokes

perl $PERL_FILE_FLAGS{$1} $PERL_DIR_FLAGS $PERL_SUITE_FLAGS \
     $PERL_WRT_FLAGS{$2} $PERL_FLAGS -I <root>/blib/lib \
     <root>/blib/script/prest -w $2 \
     $PREST_FLAGS $PREST_WRT_FLAGS{$2} $PREST_SUITE_FLAGS \
     $PREST_DIR_FLAGS $PREST_FILE_FLAGS{$1} [$1.rst] \
     $POSTPROC_FILE{$1} > $target

If $3 is null, then any output to STDERR is captured in the output file; otherwise the output file contains only the prest output to STDOUT. If there is no $1.rst file, then $PREST_FILE_FLAGS{$1} should contain the list of input files.

GLOBAL VARIABLES

As can be seen above, there are a number of global variables that affect the processing of the prest command:

$PERL_DIR_FLAGS (Dir.smak)

Flags for perl invocation of prest for a directory.

$PERL_SUITE_FLAGS (Suite.smak)

Flags for perl invocation of prest for a suite.

%PERL_WRT_FLAGS (Suite.smak or Perl.smak)

Flags for perl invocation of prest for specific writers (indexed by writer).

%PERL_FILE_FLAGS (Dir.smak)

Flags for perl invocation of prest for specific files (indexed by base filename).

$PREST_DIR_FLAGS (Dir.smak)

Writer- and file-independent flags for prest for a directory.

$PREST_FLAGS (Suite.smak or Dir.smak)

Writer- and file-independent flags for prest. Defaults to

-D source='test data' -D xformoff='.*' -D align=0

unless already set.

$PREST_SUITE_FLAGS (Suite.smak)

Writer- and file-independent flags for prest for a suite.

%PREST_WRT_FLAGS (Suite.smak or Dir.smak)

Flags for specific writers (indexed by writer). $PREST_WRT_FLAGS{dom} defaults to "-W nobackn" unless already set.

%PREST_FILE_FLAGS (Dir.smak)

Flags for specific files (indexed by base filename).

%POSTPROC_FILE (Dir.smak)

Text for postprocessing output before check for specific files (indexed by base filename). Usually starts with "|".

ENVIRONMENT VARIABLES

COVER

If set, runs perl with flags to create a coverage database using Devel::Cover.

DEBUG

If set, runs perl with the -d flag (debug mode).

PRINT

If set, echoes to STDERR the commands to be executed, but does not actually execute them.

TRACE

If set, echoes to STDERR the commands as they execute.