docs/configuration.pod

   1 # Copyright (C) 2004-2008, The Perl Foundation.
   2 # $Id$
   3
   4 =pod
   5
   6 =head1 NAME
   7
   8 docs/configuration.pod - Parrot Configuration System
   9
  10 =head1 DESCRIPTION
  11
  12 Parrot configuration is broken up into I<steps>. Each step contains several
  13 related I<prompts>, I<probes>, or I<generations>. Steps should be mostly of a
  14 single type, though some overlap is allowed (for example, allowing a probe to
  15 ask the user what to do in an exceptional situation).
  16
  17 The directory F<config> contains subdirectories for each type of step.  Each
  18 step should consist of I<exactly one> F<.pm> file and any number of supporting
  19 F<.c>, F<.in>, etc. files. Any supporting files should be in a folder whose
  20 name is the same as the basename of the step's F<.pm> file; for example, if
  21 F<foo.pm> uses F<bar_c.in>, F<bar_c.in> should be in a directory called F<foo>;
  22 the full path might be F<config/auto/foo/bar_c.in>.
  23
  24 Generally, when adding a new component to the configuration process you should
  25 add a new step unless that component I<clearly> belongs in a current step. For
  26 example, if you added a new user-configurable type called C<FOOVAL>, you would
  27 add the code used to determine its size in F<config/auto/sizes.pm>.  However,
  28 if you were determining what dynaloading capabilities are available, you would
  29 create a new step.
  30
  31 =head2 Initialization Steps
  32
  33 I<Initialization steps> are run before any other steps. They do tasks
  34 such as preparing the configuration system's data structures and
  35 checking the F<MANIFEST>. New initialization steps will only be added
  36 when the configuration system is getting significant new capabilities.
  37 They're kept in the directory F<config/init>.
  38
  39 =head2 Prompts
  40
  41 Prompts ask the user for some information. These should be used sparingly. A
  42 step containing prompts is an I<interactive step>.  Interactive steps should be
  43 in the F<config/inter> folder.
  44
  45 Interactive steps often include simple probes to determine good guesses of what
  46 the user will answer. See L</Prompt or Probe?> for more information.
  47
  48 Note that, by default, these prompts are turned off. To enable them run
  49 F<Configure.pl> with the C<--ask> option.
  50
  51 =head2 Probes
  52
  53 Probes are automated tests of some feature of the computer. These should be
  54 used wherever a value will not need to be modified often by the user.  A step
  55 containing probes is an I<automatic step>. Automatic steps should be in the
  56 F<config/auto> folder.
  57
  58 =head2 Generations
  59
  60 Generations create files needed after configuration has completed, such as
  61 Makefiles and configuration headers. A step containing generations is a
  62 I<generation step>. Generation steps should be in the F<config/gen> folder.
  63
  64 Templates for files to be generated usually have the extension F<.in>.  There
  65 are variable substitutes and funny macros like 'CONDITIONED_LINE' and
  66 'INVERSE_CONDITIONED_LINE'.
  67
  68 =head2 Prompt or Probe?
  69
  70 It can sometimes be hard to decide whether a given step should be an automatic
  71 or an interactive step. The guiding question is I<Would a user ever want to
  72 change this?>, or conversely, I<Is this something that can be completely
  73 determined without user intervention?>  A step figuring out what the compiler's
  74 command is would probably be an interactive step; conversely, a step figuring
  75 out if that command is connected to a specific compiler (like F<gcc>) would be an
  76 automatic step.
  77
  78 =head2 Configuring Configuration
  79
  80 The configuration system gets its own configuration data from, and is invoked
  81 via, the F<Configure.pl> script.  The system is invoked by instantiating a
  82 L<Parrot::Configure> object, registering one or more steps with that object,
  83 and then calling C<Parrot::Configure::runsteps()>.
  84
  85 =head2 Adding New Steps
  86
  87 New steps should be added in one of the four folders mentioned above.
  88
  89 All steps are really classes; each exists in a unique namespace.  The
  90 namespace used depends on the step's relative path in the source tree sans the
  91 F<config> prefix.  For example, the step F<config/init/defaults.pm> uses the
  92 C<init::defaults> namespace.
  93
  94 Each step inherits its constructor and some other methods from
  95 F<lib/Parrot/Configure/Step.pm>.  Each step needs to define only
  96 two methods:  C<_init()> and C<runstep()>.
  97
  98 The C<_init()> method should follow the following example, defining three
  99 elements within an internal hash:
 100
 101     sub _init {
 102         my $self = shift;
 103         my %data;
 104         $data{description} = q{This is the step description};
 105         $data{result}      = q{};
 106         return \%data;
 107     }
 108
 109 =over 4
 110
 111 =item C<description>
 112
 113 Of these three elements, C<description> is the most important as it is
 114 used extensively within C<lib/Parrot/Configure.pm>.
 115
 116 Returns a short descriptive message that should be printed before the step
 117 executes.  Usually, interactive steps have long, friendly descriptions and
 118 other steps have terse descriptions ending in "...".
 119
 120 Some example descriptions:
 121
 122 =over 4
 123
 124 =item F<config/auto/cgoto.pm>
 125
 126     Determining if your compiler supports computed goto...
 127
 128 =item F<gen/config_h.pm>
 129
 130     Generating config.h...
 131
 132 =back
 133
 134 Note that on non-interactive steps, the text I<done> will be printed after the
 135 description when the step finishes executing; for example, the user will see:
 136
 137     Determining if your compiler supports computed goto...done.
 138
 139 =item C<result>
 140
 141 The C<result> is initialized to an empty string mainly to quiet
 142 'uninitialized variable' warnings.  Most configuration steps override
 143 the C<result> value inside their C<runstep()> method.
 144
 145 =item L<_run_this_step>
 146
 147 This method is called to actually execute the step.  The return
 148 value should be C<1> if the step accomplishes what it is intended to do.
 149 Otherwise, the step should simply C<return>, I<i.e.>, return an
 150 undefined value.
 151
 152 =back
 153
 154 The configuration system won't execute your step by default unless it's
 155 specifically told to. To do this, edit F<lib/Parrot/Configure/Step/List.pm>.
 156 Steps are run in the order in which that are registered with the
 157 L<Parrot::Configure> object.
 158
 159 Various utility functions for configuration steps are provided by the
 160 L<Parrot::Configure::Utils> module.
 161
 162 A template for a new step might look like this:
 163
 164     package auto::newstep;
 165
 166     use strict;
 167     use warnings;
 168     use vars qw($description $result);
 169
 170     use base qw(Parrot::Configure::Step);
 171
 172     use Parrot::Configure::Utils;
 173
 174     sub _init {
 175         my $self = shift;
 176         my %data;
 177         $data{description} = q{This is the step description};
 178         $data{result}      = q{};
 179         return \%data;
 180     }
 181
 182     sub runstep {
 183         my ($self, $conf) = @_
 184         ...
 185         if ($success) {
 186             $self->set_result('yes');
 187             return 1;
 188         } else {
 189             $self->set_result('no');
 190             return;
 191         }
 192     }
 193
 194 The step's C<runstep()> method should return C<1> upon success and do a
 195 bare return on failure (thereby returning an undefined value).
 196
 197 =head2 Command-line Arguments
 198
 199 Command-line arguments look like C</--[-\w]+(=.*)?/>; the equals sign separates
 200 the name and the value. If the value is omitted, it's assumed to be 1. The
 201 options C<--help> and C<--version> are built in to Configure; any others are
 202 defined by steps.
 203
 204 Command-line arguments are now processed by C<process_options()>, a subroutine
 205 exported by L<Parrot::Configure::Options>.  If you add a new option, don't
 206 forget to add it to this documentation and to two locations in
 207 F<lib/Parrot/Configure/Options/Conf.pm> and F<lib/Parrot/Configure/Options/ReConf.pm>:
 208
 209 =over 4
 210
 211 =item *
 212
 213 the list of valid command-line arguments in the array
 214 C<@valid_options> and
 215
 216 =item *
 217
 218 the description of command-line arguments found in
 219 C<print_help()>.
 220
 221 =back
 222
 223 Arguments passed to F<Configure.pl> are held in a L<Parrot::Configure::Data>
 224 object stored inside the L<Parrot::Configure> object.  The options data object
 225 may be accessed via the L<Parrot::Configure/options> method.
 226
 227 =head2 Building Up Configuration Data
 228
 229 The second step is F<config/init/defaults.pm>, which sets up some defaults in a
 230 L<Parrot::Configure::Data> object contained by the main L<Parrot::Configure>
 231 object.  It can be accessed via the L<Parrot::Configure/data>method.  You get
 232 and set configuration system's data by interacting with this object.  Some of
 233 its methods are summarized below.
 234
 235 =over 4
 236
 237 =item C<get(keys)>
 238
 239 Returns the values for the given keys.
 240
 241 =item C<set(key, value, [key, value, ...])>
 242
 243 Sets the given keys to the given values.
 244
 245 =item C<add(delim, key, value, [key, value, ...])>
 246
 247 Sets the given keys to the given values or appends values delimited by I<delim>
 248 to existing keys.
 249
 250 =item C<keys()>
 251
 252 Returns a list of all keys.
 253
 254 =item C<dump()>
 255
 256 Returns a string that can be C<eval>ed by Perl to create a hash representing
 257 the configuration system's data.
 258
 259 See the L<Parrot::Configure::Data> documentation for further details.
 260
 261 =back
 262
 263 =head2 Special Configuration Items
 264
 265 Some configuration items, by convention, have a special meaning (mainly
 266 prefixes) and are handled with some magic internally.
 267
 268 =over 4
 269
 270 =item C<i_(\w+)> include files
 271
 272 defines or undefs PARROT_HAS_HEADER_XXX in F<include/parrot/has_header.h>
 273
 274 =item C<HAS_(\w+)> features
 275
 276 defines PARROT_HAS_XXX in F<include/parrot/has_header.h>
 277
 278 =item C<TEMP_(\w+)> temporary settings
 279
 280 These settings are deleted before F<lib/Parrot/Config.pm> is written. These
 281 entries are only used e.g. for Makefile creation.
 282
 283 =back
 284
 285 =head2 Accessing Configuration Information via Perl 5 Variables
 286
 287 Parrot configuration is currently jump-started by extracting
 288 considerable information from variables associated with the instance of
 289 Perl 5 which the user is using to run F<Configure.pl>.  These variables
 290 are largely looked up in the C<%Config> found in the Perl 5
 291 F<Config.pm>, but may also be sought in Perl 5 special variables such as
 292 C<$^O>.  All such lookups should be done in configuration step
 293 C<init::defaults> and B<only> in that step.  Special accessors are
 294 available for working with such variables; see
 295 F<config/init/defaults.pm> and F<lib/Parrot/Configure/Data.pm>.
 296
 297 =head1 HISTORY
 298
 299 The Parrot configuration system was created by Brent Dax and has been heavily
 300 mangled by Joshua Hoblitt.
 301 James Keenan refactored the configuration system.
 302
 303 =head1 SEE ALSO
 304
 305 L<Parrot::Configure>, L<Parrot::Configure::Data>,
 306 L<Parrot::Configure::Utils>, L<Parrot::Configure::Step>
 307
 308 =cut