Test::AutoBuild::Module - represents a code module to be built

  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();

The Test::AutoBuild::Module module provides a representation of a single code module to be built / tested.

The valid configuration options for the modules block are

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'.

Daniel Berrange <dan@berrange.com>

Copyright (C) 2002-2004 Daniel Berrange <dan@berrange.com>

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