Linux Certif

Toute la documentation sur la certification Linux LPI

Test::AutoBuild::Module.3pm

NAME

Test::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 ALSO

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