1# Copyright (C) 2001-2009, Parrot Foundation.
2
3package Parrot::Configure::Step::Test;
4
5use strict;
6use warnings;
7use lib qw( lib );
8our @ISA = qw( Parrot::Configure );
9use Parrot::Config;
10use Parrot::Configure::Data;
11
12=head1 NAME
13
14Parrot::Configure::Step::Test - Populate Parrot::Configure object with results of configuration
15
16=head1 SYNOPSIS
17
18    use Parrot::Configure::Step::Test;
19
20    $conf = Parrot::Configure::Step::Test->new;
21    $conf->include_config_results( $args );
22
23Methods below are inherited from Parrot::Configure:
24
25    $conf->add_steps( 'some_package' );
26    $serialized = $conf->pcfreeze();
27    $conf->options->set( %options );
28    $conf->runsteps();
29    $conf->replenish($serialized);
30
31=head1 DESCRIPTION
32
33This module is a close simulation of Parrot::Configure to be used for testing
34of individual configuration steps once F<Configure.pl> has run.  Its
35constructor is structured in the same way as C<Parrot::Configure::new()> --
36the Parrot::Configure constructor -- and inherits all Parrot::Configure
37methods.  It adds just one method:
38C<Parrot::Configure::Step::Test::include_config_results()>.  This method
39populates the C<data> section of the Parrot::Configure object's data structure
40with the results of Parrot configuration, I<i.e.,> C<%PConfig> from
41Parrot::Config (F<lib/Parrot/Config.pm>).
42
43=head2 Rationale
44
45I<You may skip this section on first reading.>
46
47Consider these questions:
48
49=over 4
50
51=item 1
52
53Why test a Parrot configuration step after that step has already been run by
54F<Configure.pl>?
55
56=item 2
57
58If F<Configure.pl> has completed successfully, doesn't that, in some sense,
59I<prove> that the code in the configuration step class was correct?  If so,
60why bother to test it at all?
61
62=item 3
63
64Conversely, wouldn't it make more sense to test a configuration step I<before>
65that step has been run by F<Configure.pl>?
66
67=back
68
69Parrot developers have debated these questions for years.  Between mid-2007
70and late-2009, the position reflected in our testing practices was that found
71in Question 3 above.  We included tests of the configuration steps in the set
72of I<preconfiguration tests> run when you called:
73
74    perl Configure.pl --test=configure
75
76The primary reason for taking this approach was the conviction that the
77B<building blocks> of the Parrot configuration process ought to be tested
78before that whole process is executed.
79
80It should be noted that at the point in time when this approach was
81implemented, there was B<no testing of the configuration step classes
82whatsoever>.  Previously, it was just assumed that if F<Configure.pl> completed
83successfully, the code in the various configuration step classes did not need
84more fine-grained testing.
85
86So, B<some> testing of the Parrot configuration steps was clearly an
87improvement over B<no> testing of those steps.
88
89Nonetheless, there were limits to how well we could apply standard testing
90practices to the Parrot configuration step classes.  The following factors
91delimited what we could do:
92
93=over 4
94
95=item *
96
97TK
98
99=back
100
101=head1 METHODS
102
103=head2 C<new()>
104
105Constructor, structured the same way as that of Parrot::Configure.
106
107See F<lib/Parrot/Configure.pm>.
108
109=cut
110
111my $singleton;
112
113BEGIN {
114    $singleton = {
115        steps   => [],
116        data    => Parrot::Configure::Data->new,
117        options => Parrot::Configure::Data->new,
118    };
119    bless $singleton, 'Parrot::Configure::Step::Test';
120}
121
122sub new {
123    my $class = shift;
124    return $singleton;
125}
126
127=head2 C<include_config_results()>
128
129B<Purpose:>  Populate the Parrot::Configure object with the results of Parrot
130configuration as recorded in C<%Parrot::Config::PConfig>.
131
132B<Arguments:>  One argument: Hash-reference which is the first return value of
133Parrot::Configure::Options::process_options();
134
135    ($args, $step_list_ref) = process_options( {
136        argv => [ ],
137        mode => q{configure},
138    } );
139
140    $conf = Parrot::Configure::Step::Test->new;
141
142    $conf->include_config_results( $args );
143
144B<Return Value:>  None.
145
146=cut
147
148sub include_config_results {
149    my ($conf, $args) = @_;
150    while ( my ($k, $v) = each %PConfig ) {
151        $conf->data->set( $k => $v );
152    }
153    $conf->options->set( %{$args} );
154}
155
156=head1 AUTHOR
157
158James E Keenan C<jkeenan@cpan.org>
159
160=head1 SEE ALSO
161
162L<Parrot::Configure>.
163
164=cut
165
1661;
167
168# Local Variables:
169#   mode: cperl
170#   cperl-indent-level: 4
171#   fill-column: 100
172# End:
173# vim: expandtab shiftwidth=4:
174