NAME

Parrot::Configure::Trace - Trace development of Parrot::Configure object through the configuration steps

SYNOPSIS

When calling perl Configure.pl:

    $ perl Configure.pl --configure_trace

After configuration has completed:

    use Parrot::Configure::Trace;

    $obj = Parrot::Configure::Trace->new();

    $steps_list = $obj->list_steps();

    $steps_index = $obj->index_steps();

    $attr = $obj->trace_options_c( {
        attr        => 'some_attr',
        verbose     => 1,               # optional
    } );

    $attr = $obj->trace_options_triggers( {
        trig        => 'some_trig',
        verbose     => 1,               # optional
    } );

    $attr = $obj->trace_data_c( {
        attr        => 'some_attr',
        verbose     => 1,               # optional
    } );

    $attr = $obj->trace_data_triggers( {
        trig        => 'some_trig',
        verbose     => 1,               # optional
    } );

    $state = $obj->get_state_at_step($step_no);

    $state = $obj->get_state_at_step('some::step');

DESCRIPTION

This module provides ways to trace the evolution of the data structure within the Parrot::Configure object over the various steps in the configuration process. An understanding of this data structure's development may be useful to Parrot developers working on the configuration process or its results.

To make use of Parrot::Configure::Trace's methods, first configure with the --configure_trace option. As configuration proceeds through what are currently 56 individual steps, the state of the Parrot::Configuration object is recorded in a Perl array reference. That array ref is stored on disk via the Storable module in a file called .configure_trace.sto found in the top-level of your Parrot sandbox directory.

Once that storable file has been created, you can write programs which retrieve its data into a Parrot::Configure::Trace object and then call methods on that object.

METHODS

new()

    $obj = Parrot::Configure::Trace->new();

• Purpose

Parrot::Configure::Trace constructor. Retrieve configuration data recorded on disk over the course of the configuration steps and populate a Parrot::Configure::Trace object with that data.

• Arguments

None currently required. However, to provide for future extensibility, you may provide a reference to a hash in which various attributes are set which will affect the Parrot::Configure::Trace object. Currently, the only such attribute is storable, whose value is the name of the Storable file holding configuration data if that file is named something other than .configure_trace.sto.

• Return Value

Parrot::Configure::Trace object.

• Comment

The Parrot::Configure::Trace object is a blessed array reference. Element 0 of that array is a reference to an array holding the names of the individual configuration steps; elements 1 through $#array hold the state of the Parrot::Configure object at the conclusion of each step.

Since the purpose of Parrot::Configure::Trace is to track the evolution of the Parrot::Configure object through the configuration steps, there is no point in recording information about those parts of the Parrot::Configure object which are invariant. The steps element is set in Configure.pl before the configuration steps are run and does not change during those steps. Hence, no information about the steps element is recorded and no methods are provided herein to retrieve that information. Since the options and (especially) data elements of the Parrot::Configure object do change over the course of configuration, methods are provided to access that data.

list_steps()

    $steps_list = $obj->list_steps();

• Purpose

Provide list of the names of the configuration steps.

• Arguments

None.

• Return Value

Array reference:

    [
        'init::manifest',
        'init::defaults',
        ...
        'gen::config_pm'
    ]

index_steps()

    $steps_index = $obj->index_steps();

• Purpose

Provide lookup table showing which step number a given configuration step is.

• Arguments

None.

• Return Value

Hash reference:

    {
        'inter::ops'        => 19,
        'init::optimize'    => 13,
        ...
        'init::defaults'    =>  2,
    }

trace_options_c()

• Purpose

Provide a list of the values which a given attribute in the {options}-{c}> part of the Parrot::Configure object takes over the course of the configuration steps.

• Arguments

Hash reference. Key attr is mandatory; it is the key whose value you wish to trace over the course of the configuration steps. Key verbose is optional.

• Return Value

Array reference. Element n of this array holds the value of the attribute in the {options}-{c}> part of the Parrot::Configure object at configuration step n + 1.

If, however, verbose is set, each element n of the array holds a hash reference where the hash key is the name of configuration step n + 1 and the value is the value of the attribute at step n + 1.

trace_data_triggers()

• Purpose

Provide a list of the values which a given attribute in the {options}-{triggers}> part of the Parrot::Configure object takes over the course of the configuration steps.

• Arguments

Hash reference. Key attr is mandatory; it is the key whose value you wish to trace over the course of the configuration steps. Key verbose is optional.

• Return Value

Array reference. Element n of this array holds the value of the attribute in the {options}-{triggers}> part of the Parrot::Configure object at configuration step n + 1.

If, however, verbose is set, each element n of the array holds a hash reference where the hash key is the name of configuration step n + 1 and the value is the value of the attribute at step n + 1.

trace_data_c()

• Purpose

Provide a list of the values which a given attribute in the {data}-{c}> part of the Parrot::Configure object takes over the course of the configuration steps.

• Arguments

Hash reference. Key attr is mandatory; it is the key whose value you wish to trace over the course of the configuration steps. Key verbose is optional.

• Return Value

Array reference. Element n of this array holds the value of the attribute in the {data}-{c}> part of the Parrot::Configure object at configuration step n + 1.

If, however, verbose is set, each element n of the array holds a hash reference where the hash key is the name of configuration step n + 1 and the value is the value of the attribute at step n + 1.

trace_data_triggers()

• Purpose

Provide a list of the values which a given attribute in the {data}-{triggers}> part of the Parrot::Configure object takes over the course of the configuration steps.

• Arguments

Hash reference. Key attr is mandatory; it is the key whose value you wish to trace over the course of the configuration steps. Key verbose is optional.

• Return Value

Array reference. Element n of this array holds the value of the attribute in the {data}-{triggers}> part of the Parrot::Configure object at configuration step n + 1.

If, however, verbose is set, each element n of the array holds a hash reference where the hash key is the name of configuration step n + 1 and the value is the value of the attribute at step n + 1.

get_state_at_step()

• Purpose

Get a snapshot of the data structure in the Parrot::Configure object at the conclusion of a given configuration step.

• Arguments

Either a positive integer corresponding to the step number:

    $state = $obj->get_state_at_step(54);

... or the x::y string corresponding to the step's name in Parrot::Configure::Step::List.

    $state = $obj->get_state_at_step('gen::makefiles');

• Return Value

Hash reference.

AUTHOR

James E Keenan (jkeenan@cpan.org)

SEE ALSO

Parrot::Configure, Parrot::Configure::Options, Configure.pl.