/ 
PITA-XML-0.52
River stage one • 3 direct dependents • 4 total dependents
/ PITA::XML::Guest

NAME

PITA::XML::Guest - A testing environment, typically a system image

SYNOPSIS

# A simple guest using the local Perl
# (mostly used for test purposes)
my $dist = PITA::XML::Guest->new(
    driver => 'Local',
    params => {},
);

DESCRIPTION

PITA::XML::Guest is an object for holding information about a testing guest environment. A PITA Guest is a container with specific operating system and hardware that contains one or more testing contexts, represented in PITA::XML by PITA::XML::Platform objects.

METHODS

new

# The most correct way to specify a guest
my $guest1 = PITA::XML::Guest->new(
    driver => 'Qemu',
    config => {
        memory   => 256,
        snapshot => 1,
    }
);

# Equivalent, using shorthand.
# Anything other that 'driver' is considered a config entry.
my $guest = PITA::XML::Guest->new(
    driver   => 'Qemu',
    memory   => 256,
    snapshot => 1,
    );

The new constructor creates a new <guest> element.

It has a single compulsory parameter of the guest driver name, and takes optionally a set of named params to provide as creation params for the guest driver object.

Returns a new PITA::XML::Guest or throw an exception on error.

read

$guest = PITA::XML::Guest->new( 'guest.xml' );

The read constructor loads a guest from an existing PITA::XML file.

Returns a new PITA::XML::Guest object, or throws an exception on error.

id

The id accessor returns the unique identifier of the request, if it has one. This will generally be some form of Data::UUID string.

Returns the identifier as a string, or undef if the request has not been assigned an id.

set_id

If an object does not already have an id property, the set_id method will let you assign one to the guest. Takes a valid GUID "8-4-4-4-12" string and sets the object with it, or croaks on error.

driver

The driver accessor returns the shorthand name of the driver, as it is stored in the PITA-XML xml file.

For example, if the guest uses the PITA::Guest::Driver::Qemu driver, the driver method return 'Qemu'.

driver_available

The driver_available method will check your local system to see if the driver for this guest is available in the current Perl environment.

Returns true if the driver is available, or false if not.

config

The config accessor returns the configuration for the driver.

This configuration is entirely driver-specific, and although conventions may exist, you should not rely on the contents of the configuration to have any specific meaning.

Returns a reference to a HASH containing plain scalar keys and values.

base

If the guest XML was loaded from a file via read the base method will return the directory that the XML file was loaded from.

This base directory identifies where any relative file paths should be mapped from.

files

Each guest will require zero or more file resources. In most cases, this consists of drive images or emulator configuration files.

The files method returns all existing files for this guest.

Returns a list of PITA::XML::File objects

platforms

Each guest should contain one or more testing contexts, where packages of some specific type can be automatically tested. In PITA parlance, a scheme-specific testing context is known as a Platform.

The platforms method returns all existing known platforms for this guest.

Returns a list of one of more PITA::XML::Platform objects.

If this method returns a zero-length list, then the guest may be unprocessed, and has not been 'discovered' yet.

add_file

The add_file method adds a new driver-specific file to the guest.

It takes as it's only parameter a PITA::XML::File object.

Returns true if added, or throws an exception if not passed a valid PITA::XML::File object.

add_platform

The add_platform method adds a new testing context to the guest.

In general, you should not be manually adding platform definitions to the guest unless you are implementing a driver auto-discovery mechanism for your new or custom PITA::Guest::Driver class.

That is, the PITA driver system itself will take you unprocessed guest, load it, query the guest for its platform list, and update the XML file independantly, without the help of any external system.

It takes as it's only parameter a PITA::XML::Platform object.

Returns true if added, or throws an exception if not passed a valid PITA::XML::File object.

discovered

The discovered method is a convenience method, and checks to see if platform discovery has been done on the guest, or if it is unprocessed.

Returns true if the platforms have been discovered, or false if not.

SUPPORT

Bugs should be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PITA-XML

For other issues, contact the author.

AUTHOR

Adam Kennedy <adamk@cpan.org>, http://ali.as/

SEE ALSO

PITA::XML

The Perl Image Testing Architecture (http://ali.as/pita/)

COPYRIGHT

Copyright 2005 - 2013 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.