Test::AutoBuild::Runtime - Builder runtime state

  use Test::AutoBuild::Runtime;

  my $runtime = new Test::AutoBuild::Runtime (archive_manager => $archive_manager,
					      monitors => \%monitors,
					      repositories => \%repositories,
					      modules => \%modules,
					      package_types => \%package_types,
					      publishers => \%publishers,
					      groups => \%groups,
					      platforms => \%platforms,
					      source_root => $dir,
					      install_root => $dir,
					      package_root => $dir,
					      log_root => $dir,
					      counter => $counter);

  my $archive = $runtime->archive;

  my @monitor_names = $runtime->monitors;
  my @repository_names = $runtime->repositories;
  my @module_names = $runtime->modules;
  my @package_types_names = $runtime->package_types;
  my @publisher_names = $runtime->publishers;
  my @group_names = $runtime->groups;
  my @platform_names = $runtime->platforms;

  my $monitor = $runtime->monitor($name);
  my $repository = $runtime->repository($name);
  my $module = $runtime->module($name);
  my $package_type = $runtime->package_type($name);
  my $publisher = $runtime->publisher($name);
  my $group = $runtime->group($name);
  my $platform = $runtime->platform($name);

  $runtime->attribute($key, $value);
  my $value = $runtime->attribute($key);
  my %attributes = $runtime->attributes()

  my $dir = $runtime->source_root();
  my $dir = $runtime->install_root();
  my $dir = $runtime->package_root();
  my $dir = $runtime->log_root();

This module provides access to the core objects comprising the build engine, including monitors, repositories, modules, package types, publishers and groups. The runtime state object is made available to the run method of stages in the build engine.

my $runtime = Test::AutoBuild::Runtime->new(archive => $archive, monitors => \%monitors, repositories => \%repositories, modules => \%modules, package_types => \%package_types, publishers => \%publishers, groups => \%groups, platforms => \%platforms, source_root => $dir, counter => $counter);

Creates a new runtime state object. The archive parameter requires an instance of the Test::AutoBuild::Archive module. The monitors parameter requires an hash reference of Test::AutoBuild::Monitor objects. The monitors parameter requires an hash reference of Test::AutoBuild::Repository objects. The repositories parameter requires an hash reference of Test::AutoBuild::Module objects. The package_types parameter requires an hash reference of Test::AutoBuild::PackageType objects. The publishers parameter requires an hash reference of Test::AutoBuild::Publisher objects. The groups parameter requires an hash reference of Test::AutoBuild::Group objects. The platforms parameter requires an hash reference of Test::AutoBuild::Platform objects.

$runtime->_sort_modules()

Regenerates the internally cached sorted list of modules, by performing a topological sort of modules against their declared build dependancies. There is generally no need to call this method.

my $archive = $runtime->archive_manager;

Returns an instance of the Test::AutoBuild::ArchiveManager module to use for persisting build state across cycles.

my $archive = $runtime->archive;

Returns the active archive object

my $monitor_names = $runtime->monitors;

Returns a list of monitor names, which can be used to retrieve a Test::AutoBuild::Monitor object from the monitor method.

my $monitor = $runtime->monitor($name);

Retrieves the Test::AutoBuild::Monitor object corresponding to the name specified by the $name parameter.

my $repository_names = $runtime->repositories;

Returns a list of repository names, which can be used to retrieve a Test::AutoBuild::Repository object from the repository method.

my $repository = $runtime->repository($name);

Retrieves the Test::AutoBuild::Repository object corresponding to the name specified by the $name parameter.

my $module_names = $runtime->modules;

Returns a list of module names, which can be used to retrieve a Test::AutoBuild::Module object from the module method.

my $module_names = $runtime->sorted_modules;

Returns a list of module names, sorted topologically according to their declared build dependancies. The names can be used to retrieve a Test::AutoBuild::Module object from the module method.

my $module = $runtime->module($name);

Retrieves the Test::AutoBuild::Module object corresponding to the name specified by the $name parameter.

my $package_type_names = $runtime->package_types;

Returns a list of package type names, which can be used to retrieve a Test::AutoBuild::PackageType object from the package_type method.

my $package_type = $runtime->package_type($name);

Retrieves the Test::AutoBuild::PackageType object corresponding to the name specified by the $name parameter.

my $publisher_names = $runtime->publishers;

Returns a list of publisher names, which can be used to retrieve a Test::AutoBuild::Publisher object from the publisher method.

my $publisher = $runtime->publisher($name);

Retrieves the Test::AutoBuild::Publisher object corresponding to the name specified by the $name parameter.

my $group_names = $runtime->groups;

Returns a list of group names, which can be used to retrieve a Test::AutoBuild::Group object from the group method.

my $group = $runtime->group($name);

Retrieves the Test::AutoBuild::Group object corresponding to the name specified by the $name parameter.

my $platform_names = $runtime->platforms;

Returns a list of platform names, which can be used to retrieve a Test::AutoBuild::Platform object from the platform method.

my $platform = $runtime->platform($name);

Retrieves the Test::AutoBuild::Platform object corresponding to the name specified by the $name parameter.

my $value = $runtime->attribute($name[, $value]);

Retrieves the attribute value corresponding to the key given in the $name parameter. If the optional $value parameter is supplied, then the attribute value is set.

my @names = $runtime->attributes;

Returns the names of the runtime attributes passed between stages

my $build_counter = $runtime->build_counter;

Returns the unique counter for this cycle of the builder

my $timestamp = $runtime->timestamp;

Returns the time to which the source repositories are synchronized

$runtime->notify($event_name, @args);

Notify all monitors about the event specified by the $event_name parameter. The following @args are event dependant and passed through to monitors unchanged.

my $dir = $runtime->source_root();

Retrieve the directory in which modules' sources are checked out from the repositories

my $dir = $runtime->install_root();

Retrieve the directory into which modules install built files.

my $dir = $runtime->package_root();

Retrieve the directory in which binary packages are placed.

my $dir = $runtime->log_root();

Retrieve the directory in which log files are placed.

my \%packages = $runtime->package_snapshot();

Takes a snapshot of all packages on disk for each package type. The keys in the returned hash ref will be the fully qualified filenames of the packages, while the values will be instances of Test::AutoBuild::Package class.

my @values = $runtime->expand_macros($value[, \%restrictions]);

Replaces macros of the form %key in the string provided in the $value argument. A macro can expand to multiple values, so the single input, can turn into multiple outputs, hence the return from this method is an array of strings. A macro which usually expands to multiple values can be restricted to a single value by specifying the value in the optional %restrictions parameter.

The macros which will be expanded are:

%m

List of modules, or the 'module' entry in the %restrictions parameter

%p

List of package types, or the 'package_type' entry in the %restrictions parameter

%g

List of groups, or the 'group' entry in the %restrictions parameter

%r

List of repositories, or the 'reposiry' entry in the %restrictions parameter

%h

Hostname of the builder

%c

Build cycle counter

my %env = $module->get_shell_environment($module);

Returns a hash containing the set of shell environment variables to set when running the commands for the module $module. The following environment variables are set

$AUTO_BUILD_ROOT

Legacy variable for compatability with Test-AutoBuild 1.0.x. Use $AUTOBUILD_INSTALL_ROOT instead.

$AUTO_BUILD_COUNTER

Legacy variable for compatability with Test-AutoBuild 1.0.x. Use $AUTOBUILD_COUNTER instead.

$AUTOBUILD_INSTALL_ROOT

The location into which a module will install its files, typically used as value for --prefix argument to configure scripts. This is based on the value return by the install_root method.

$AUTOBUILD_PACKAGE_ROOT

The location into which a module will create binary packages. For example, $AUTOBUILD_PACKAGE_ROOT/rpm would be used to set %_topdir when building RPMs. This is based on the value return by the package_root method.

$AUTOBUILD_SOURCE_ROOT

The location into which the module was checked out. This is based on the value return by the install_root method.

$AUTOBUILD_MODULE

The name of the module being built. This can be used in conjunction with the $AUTOBUILD_SOURCE_ROOT to determine the top level directory of the module's source.

$AUTOBUILD_COUNTER

The build counter value, based on the value return by the build_counter method. This counter is not guarenteed to be different on each build cycle

$AUTOBUILD_TIMESTAMP

The build counter value, based on the value return by the build_counter method. This counter will uniquely refer to a particular checkout of the source code.

The returned hash will also include module specific environment entries from the env method.

Daniel P. Berrange <dan@berrange.com>

Copyright (C) 2005 Daniel Berrange <dan@berrange.com>

perl(1), Test::AutoBuild::Stage, Test::AutoBuild::Module, Test::AutoBuild::Repository, Test::AutoBuild::PackageType, Test::AutoBuild::Monitor, Test::AutoBuild::Group, Test::AutoBuild::Publisher