docs/configuration.pod

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