Linux Certif

Toute la documentation sur la certification Linux LPI

Test::AutoBuild::Stage.3pm

NAME

Test::AutoBuild::Stage - The base class for an AutoBuild stage

SYNOPSIS

   use Test::AutoBuild::Stage
 
   my $stage = Test::AutoBuild::Stage->new(name => $token,
                                           label => $string,
                                           [critical => $boolean,]
                                           [enabled => $boolean]);
 
   # Execute the stage
   $stage->run($runtime);
 
 
   if ($stage->aborted()) {         # Very badly wrong
     die $stage->log();
   } elsif ($stage->failed()) {   # Expected failure
     if ($stage->is_critical()) { # Non-recoverable
       .. do failure case ...
     } else {
       .. do recovery case ...
     }
   } elsif ($stage->success() ||  # Everything's ok
            $stage->skipped()) {
     .. do normal case ...
   }
 
 

DESCRIPTION

This module is an abstract base class for all AutoBuild stages. If defines a handful of common methods and the abstract method "process" to be implemented by sub-classes to provide whatever custom processing is required.

STATUS

The status of a stage starts off as 'pending', and when the "run" method is invoked, the status will changed to one of the following:

success

If the stage completed its processing without encountering any problems. Stages will automatically have their status set to this value if their "process" method completes without the "fail" method having been called.

failed

If the stage completed its processing, but encountered and handled one or more problems. Such problems may include failure of a module build, failure of a test suite. Upon encountering such an problem, the stage should call the "fail" method providing a description of the problem, and then return from the "process" method.

aborted

If the stage died as a result of an error during processing. Stages should simply call the "die" method to abort processing. NB, the "confess" method should not be used to abort since, autobuilder will automatically hook "confess" into the perl SIG{__DIE__} handler.

skipped

If the stage was not executed due to the "is_enabled" flag being set to false.

CONFIGURATION

All stage modules have a number of standard configuration options that are used. Sub-classes are not permitted to define additional configuration parameters, rather, they should use the "options" parameter for their custom configuration needs.

name

A short alpha-numeric token representing the stage, typically based on the last component of the name of the stage module

label

An arbitrary string describing the purpose of the stage, suitable for presenting to users through email alerts, or HTML status pages.

enabled

A boolean flag indicating whether the stage is to be executed, or skipped.

critical

A boolean flag indicating whether failure of a stage should be considered fatal to the build process. NB, if a stage aborts, it is always considered fatal, regardless of this flag.

options

A hash containing options specific to the particular stage sub-class.

METHODS

my $stage = Test::AutoBuild::Stage->new(name => $name, label => $label, [critical => $boolean,] [enabled => $boolean,] [options => \%options]);

Creates a new stage, with a name specified by the "name" parameter and label by the "label" parameter. The optional "critical" parameter can be used to change the behaviour of stages upon failure, if omitted, will default to "true". The optional "enabled" parameter can be used to disable execution of the stage, if omitted, will default to "true". Finally, the "options" parameter can be used to specify sub-class specific options.

$stage->init(%params);

A method to initialize the stage called automatically by the "run" method, so see the docs for that method for details of the keys accepted in the %params parameter.

my $boolean = $stage->pending();

Returns a true value if the stage is still pending execution.

my $boolean = $stage->failed();

Returns a true value if the stage encountered one or more problems during execution. To mark a stage as failed, use the "fail" method supplying a explanation of the failure.

my $boolean = $stage->succeeded();

Returns a true value if the stage completed execution without encountering any problems

my $boolean = $stage->skipped();

Returns a true value if the stage was skipped, due to the "is_enabled" flag being disabled.

my $boolean = $stage->aborted();

Returns a true value if the stage aborted, due to the "process" method calling "die".

my $seconds = $stage->duration();

Returns the duration of the stage execution, rounded to the nearest second.

$stage->fail($message);

Marks the stage as failing, providing an explanation with the $message parameter. Should be called from the "process" method if an expected error condition arises.

$value = $stage->option($name[, $newvalue]);

Retrieves the subclass specific configuration option specified by the $name parameter. If the $newvalue parameter is supplied, then the configuration option is updated.

$stage->run($runtime);

Executes the stage, recording the start and end time, and updating the stage status to reflect the result of its execution. The $runtime parameter should be an instance of the Test::AutoBuild::Runtime module.

$stage->process($runtime);

This method should be implemented by subclasses to provide whatever processing logic is required. The $runtime parameter should be an instance of the Test::AutoBuild::Runtime module. The "process" method should call the "fail" method is an expected error occurrs, otherwise it should simply call "die".

AUTHORS

Daniel Berrange <dan@berrange.com>, Dennis Gregorovic <dgregorovic@alum.mit.edu>

COPYRIGHT

Copyright (C) 2004 Red Hat, Inc.

SEE ALSO

perl(1), Test::AutoBuild, Test::AutoBuild::Runtime