Test::AutoBuild::ModulUser Contributed Perl DocumentTest::AutoBuild::Module(3)NAMETest::AutoBuild::Module - represents a code module to be built
SYNOPSIS
use Test::AutoBuild::Module;
my $module = Test::AutoBuild::Module->new(name => $name,
label => $label,
sources => $sources,
[dependencies => \@modules,]
[env => \%env,]
[options => \%options,]
[groups => \@groups,]
[dir => $directory]);
$module->build();
$module->install();
DESCRIPTION
The Test::AutoBuild::Module module provides a representation of a
single code module to be built / tested.
OPTIONS
The valid configuration options for the "modules" block are
METHODS
my $module = Test::AutoBuild::Module->new(name => $name, label =>
$label, sources => $sources, [depends => \@modules,] [links =>
\%links,] [artifacts => \%artifacts,] [env => \%env,] [options =>
\%options,] [groups => \@groups,] [dir => $directory]);
Creates a new code module object. "name" is a alphanumeric token
for the name of the module. "label" is a short human friendly title
for the module. "depends" is an array ref containing a list of
dependant module names. "env" is a hash ref of environment
variables to define when building the module. "groups" is the
optional list of groups to which the module belongs. "dir" is the
directory in which the module was checked out, if different from
"name". The "controlfile" parameter is the name of the build
control file to run if different from the global default.
my $label = $module->label([$newlabel]);
Returns the label of this module, a short human friendly title. If
the "newlabel" parameter is supplied the label is also updated.
my $name = $module->name([$newname]);
Returns the name of this module, a short alphanumeric token. If the
"newname" parameter is supplied the name is also updated.
my $sources = $module->sources($newsources)
Returns an array references, where each element is as hash with two
keys. The value associated with the key "repository" is the name of
the soruce repository. The value associated with the key "path" is
the path within the source repository to checkout. If the
$newsources parameter is supplied, the list of sources is updated
my $path = $module->dir($newpath);
Returns the path for the directory checked out of source control.
Typically this is the same as the module name. If the "newpath"
parameter is supplied the dir is updated.
my \@modules = $module->depends([\@modules]);
Returns an array ref of dependant module names. If the "modules"
parameter is supplied then the list of dependants is updated.
my $value = $module->option($name[, $newvalue]);
Returns the value of the option referenced by "name". If the
"newvalue" parameter is supplied, then the option is also updated.
Options are arbitrary key + value pairs intended for stages to use
for configuring module specific options. For example the
Test::AutoBuild::Stage::Build module uses the "control-file" option
key to allow override of the shell script used to perform a build.
To avoid clashes between multiple different stages, try to use
reasonably description option key names, preferrably at least 2
words long.
my $bool = $module->is_installed($dir);
Returns a true value if this modules files are installed into the
directory $dir.
$module->install($runtime, $dir);
Installs all this module's files from a previously populated build
cache, into the directory $dir. If any dependant modules have not
yet been installed, they will be installed first.
$module->test_status($name);
Retrieves the status of the test called $name. The status will be
one of the "success", "failed", "cached". If there is no test
called $name, an error will be thrown.
$module->test_output_log_file($name);
Retrieves the name of the logfile into which console output for the
test called $name should be saved. The logfile name will be
relative to the runtime's log root directory.
$module->test_result_log_file($name);
Retrieves the name of the logfile into which formal results for the
test called $name should be saved. The logfile name will be
relative to the runtime's log root directory.
my $seconds = $module->test_start_date($name);
Retrieves the timestamp at which the test called $name began
execution. If no test called $name has been run yet, an error will
be thrown.
my $seconds = $module->test_end_date($name);
Retrieves the timestamp at which the test called $name completed
execution. If no test called $name has been run yet, an error will
be thrown.
my @names = $module->tests
Retrieves the list of all known test names which have been executed
for this module.
my $status = $module->build_status;
Retrieves the status of the module build. If the module has not yet
been built, it will return 'pending'; if the build has been run it
will return one of 'success', 'failed', or 'cached'; if the
module's build was skipped due to a dependant module failing, the
status will be 'skipped'.
$module->build_output_log_file();
Retrieves the name of the logfile into which console output for the
build process should be saved. The logfile name will be relative to
the runtime's log root directory.
$module->build_result_log_file();
Retrieves the name of the logfile into which results for the build
process unittests should be saved. The logfile name will be
relative to the runtime's log root directory.
my $seconds = $module->test_start_date();
Retrieves the timestamp at which the build process began execution.
If the build has not run yet, an undefined value will be returned.
my $seconds = $module->test_end_date();
Retrieves the timestamp at which the build process completed
execution. If the build has not run yet, an undefined value will be
returned.
my $status = $module->checkout_status;
Retrieves the status of the module SCM checkout. If the module has
not yet been checked out, it will return 'pending'; Ff the checkout
has been run it will return one of 'success', 'failed'. If it was
'success' then the "changes" method will return a list of
changesets.
$module->checkout_output_log_file();
Retrieves the name of the logfile into which console output for the
checkout process should be saved. The logfile name will be relative
to the runtime's log root directory.
my $seconds = $module->test_start_date();
Retrieves the timestamp at which the checkout process began
execution. If the checkout has not run yet, an undefined value will
be returned.
my $seconds = $module->test_end_date();
Retrieves the timestamp at which the checkout process completed
execution. If the checkout has not run yet, an undefined value will
be returned.
my $stauts = $module->status
Retrieves the overall status of this module. If the module failed
to checkout from SCM, then the SCM status is returned. If the
module build failed, is pending, or was skipped, then this returns
'failed', 'pending', or 'skipped' respectively; If any test script
failed, this returns 'failed'; otherwise it returns 'success'.
my @paths = $module->paths($repository)
Returns the list of source paths to be checked out from the
repository $repository. If there are no paths associated with that
repository, returns an empty list.
my $status = $module->invoke_shell($runtime, $controlfile, $logfile,
\@args);
This method spawns a shell, and executes the command $controlfile
saving its combined stdout/stderr output to the file $logfile. The
command will have @args passed as command line arguments, and will
be run in the context of the environment returned by the
"get_shell_env" method. The return value of this method will be
zero upon success, otherwise it will return the exit status of the
command. Before invoking the command $controlfile the current
directory will be changed to the directory returned by the "dir"
method beneath the runtime's source root. Any errors encountered
while trying to spawn the shell, or invoke the command will also be
logged in the file given by the $logfile parameter.
$module->run_task($runtime, $taskname, $controlfile);
This method runs a task named $taskname by invoking the shell
command $controlfile in the source directory for this module. The
taskname must either be "build" or be prefixed by the string
"test-". If the taskname is build then after execution any files
created in the install root will be recorded as installed files -
later available by invoking the "installed" method. Likewise any
files created in the package root, matching known package types
will be recorded as generated packages - later available by
invoking the "packags" method. The start and end times of the task,
along with its success/failure status will be record and later
available from the corresponding "build_XXX" or "test_XXX" methods
matching the $taskname. The controfile will be invoked with a
single command line argument, which is the full path to a file into
which formal test results should be saved. Regular, free format,
build / test output will automatically be captured to an alternate
log file.
$module->cachable_run_task
This is a wrapper around the "run_task" method which makes use of
the currently configured Test::AutoBuild::ArchiveManager to cache
successfull invocations of a task. On subsequent invocations,
provided there have been no source code checkout changes since the
previous archive, and no dependant modules have been re-built, the
archived result will be restored, rather than invoking the task
again. From the caller's POV, there should be no functional
difference between "cachable_run_task" and "run_task", with the
exception that the former will be alot faster if the archive is
used.
$module->unarchive_result($runtime, $cache, $taskname)
This method restores the result of the task $taskname from an old
archive $cache. $cache will be a subclass of the
"Test::AutoBuild::Archive" module. If the taskname is "build", then
the log files, build results, intalled files, generated packages,
and source changelogs will all be restored. If the taskname is
prefixed by "test-", then the log files and test results will be
restored.
my $bool = $module->archive_usable($runtime, $archive, $taskname)
Returns a true value, if the archive $archive contains a usable
saved entry for the task $taskname. An archive for a module's task
is defined to be usable if all dependant modules are also usable;
if the archive contains a bucket with the name $taskname; if the
status of the save task is "success" or "cached"; and if no source
code changes have been made.
$module->archive_result($runtime, $archive, $taskname)
This method saves the result of the task $taskname to a new archive
$archive. $archive will be a subclass of the
"Test::AutoBuild::Archive" module. If the taskname is "build", then
the log files, build results, intalled files, generated packages,
and source changelogs will all be saved. If the taskname is
prefixed by "test-", then the log files and test results will be
saved.
$module->build($runtime, $controlfile);
Runs the build task, by invoking the shell command $controlfile in
the source directory of this module. Refer to the "run_task" and
"invoke_shell" methods for further details of the context of
execution. Results and information about the task can later be
invoking the various "build_XXX" methods.
$module->test($runtime, $testname, $controlfile);
Runs a test task with the name $testname, by invoking the shell
command $controlfile in the source directory of this module. Refer
to the "run_task" and "invoke_shell" methods for further details of
the context of execution. Results and information about the task
can later be retrieved passing the $testname to the various
"test_XXX" methods.
my $bool = $module->should_skip($runtime);
Determines if execution of tasks for this module should be skipped.
A module should be skipped, if any of its dependant modules have a
value returned by their "build_status" methods of 'failed',
'pending' or 'skipped'.
AUTHORS
Daniel Berrange <dan@berrange.com>
COPYRIGHT
Copyright (C) 2002-2004 Daniel Berrange <dan@berrange.com>
SEE ALSOperl(1), Test::AutoBuild::Runtime, Test::AutoBuild::Repository,
Test::AutoBuild::Stage
perl v5.14.1 2011-09-01 Test::AutoBuild::Module(3)
