docs/configuration.pod

   1 # Copyright (C) 2004-2006, 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 test you should add a new step unless a test
  25 I<clearly> belongs in a current step. For example, if we added a new
  26 user-configurable type called C<FOOVAL>, you should add the test for its size
  27 in F<config/auto/sizes.pm>; however, if you were testing what dynaloading
  28 capabilities are available, you should create a new step.
  29
  30 =head2 Initialization Steps
  31
  32 I<Initialization steps> are run before any other steps. They do tasks such as
  33 preparing the configuration system's data structures and checking the
  34 F<MANIFEST>. These will rarely be added; when they are, it usually means that
  35 the configuration system is getting significant new capabilities. They're kept
  36 in the directory F<config/init>.
  37
  38 Initialization steps usually do not output anything under normal circumstances.
  39
  40 =head2 Prompts
  41
  42 Prompts ask the user for some information. These should be used sparingly. A
  43 step containing prompts is an I<interactive step>.  Interactive steps should be
  44 in the F<config/inter> folder.
  45
  46 Interactive steps often include simple probes to determine good guesses of what
  47 the user will answer. See L</Prompt or Probe?> for more information.
  48
  49 Interactive steps virtually always output something.
  50
  51 Note that, by default, these prompts are turned off. To enable them run
  52 F<Configure.pl> with the C<--ask> option.
  53
  54 =head2 Probes
  55
  56 Probes are automated tests of some feature of the computer. These should be
  57 used wherever a value will not often need to be modified by the user.  A step
  58 containing probes is an I<automatic step>. Automatic steps should be in the
  59 F<config/auto> folder.
  60
  61 Automatic steps usually do not output anything under normal circumstances.
  62
  63 =head2 Generations
  64
  65 Generations create files needed after configuration has completed, such as
  66 Makefiles and configuration headers. A step containing generations is a
  67 I<generation step>. Generation steps should be in the F<config/gen> folder.
  68
  69 Generation steps usually do not output anything under normal circumstances.
  70
  71 Templates for to be generated files usually have the extension '.in'.  There is
  72 variable substitutes and funny macros like 'CONDITIONED_LINE' and
  73 INVERSE_CONDITIONED_LINE'.
  74
  75 =head2 Prompt or Probe?
  76
  77 It can sometimes be hard to decide whether a given step should be an automatic
  78 or an interactive step. The guiding question is I<Would a user ever want to
  79 change this?>, or conversely, I<Is this something that can be completely
  80 determined without user intervention?>  A step figuring out what the compiler's
  81 command is would probably be an interactive step; conversely, a step figuring
  82 out if that command is connected to a specific compiler (like gcc) would be an
  83 automatic step.
  84
  85 =head2 Configuring Configuration
  86
  87 The configuration system gets its own configuration data from, and is invoked
  88 via, the F<Configure.pl> script.  The system is invoked by instantiating a
  89 L<Parrot::Configure> object, registering one or more steps with that object,
  90 and then calling its L<Parrot::Configure/runsteps> method.
  91
  92 =head2 Adding New Steps
  93
  94 New steps should be added in one of the three folders mentioned above.
  95
  96 All steps are really classes; they each exist in a unique namespace.  The
  97 namespace used depends on the tests relative path in the source tree minus sans
  98 the F<config> prefix.  For example, the step F<config/init/defaults.pm> uses
  99 the C<init::defaults> namespace.
 100
 101 They should define the following methods:
 102
 103 =over 4
 104
 105 =item C<description>
 106
 107 Returns a short descriptive message that should be printed before the step
 108 executes.  Usually, interactive steps have long, friendly descriptions and
 109 other steps have terse descriptions ending in "...".
 110
 111 Some example descriptions:
 112
 113 =over 4
 114
 115 =item F<config/inter/progs.pm>
 116
 117     Okay, I'm going to start by asking you a couple questions about your
 118     compiler and linker. Default values are in square brackets; you can
 119     hit ENTER to accept them. If you don't understand a question, the
 120     default will usually work--they've been intuited from your Perl 5
 121     configuration.
 122
 123 =item F<config/auto/cgoto.pm>
 124
 125     Determining if your compiler supports computed goto...
 126
 127 =item F<gen/config_h.pm>
 128
 129     Generating config.h...
 130
 131 =back
 132
 133 Note that on non-interactive steps, the text I<done> will be printed after the
 134 description when the step finishes executing; for example, the user will see:
 135
 136     Determining if your compiler supports computed goto...done.
 137
 138 =item C<args>
 139
 140 Returns a list of the names of any command-line arguments the step cares about.
 141 Command-line arguments are standardized in F<Configure.pl>; this will be
 142 described L<later|/"Command-line Arguments"> in more detail.
 143
 144 I<XXX> Note that this method is currently unused but will be used in the futher
 145 to register acceptable CLI parameters.  New steps should continue to define
 146 this method.
 147
 148 =item L<runstep>
 149
 150 This method is called to actually execute the step.  The global
 151 L<Parrot::Configure> is passed is as the first parameter.  The return value is
 152 undefined.
 153
 154 I<XXX> In the near future the return value of this method will be signifigant
 155 and there will be a means of passing additional parameters.
 156
 157 =back
 158
 159 The configuration system won't execute your step by default unless it's
 160 specifically told to. To do this, edit F<lib/Parrot/Configure/Step/List.pm>.
 161 Steps are run in the order in which that are registered with the
 162 L<Parrot::Configure> object.
 163
 164 Various utility functions for configuration steps are provided by the
 165 L<Parrot::Configure::Step> module.
 166
 167 A template for a new step might look like this:
 168
 169     package auto::newstep;
 170
 171     use strict;
 172     use warnings;
 173     use vars qw($description $result @args);
 174
 175     use base qw(Parrot::Configure::Step::Base);
 176
 177     use Parrot::Configure::Step;
 178
 179     $description = '<description>';
 180     @args = qw(<args>);
 181
 182     sub runstep {
 183         my ($self, $conf) = @_
 184         ...
 185     }
 186
 187 =head2 Command-line Arguments
 188
 189 Command-line arguments look like C</--[-\w]+(=.*)?/>; the equals sign separates
 190 the name and the value. If the value is omitted, it's assumed to be 1. The
 191 options C<--help> and C<--version> are built in to Configure; any others are
 192 defined by steps.
 193
 194 Command-line arguments are now processed by C<process_options()>, a subroutine
 195 exported by L<Parrot::Configure::Options>.  If you add a new option, don't
 196 forget to add it to this documentation and to two locations in
 197 F<lib/Parrot/Configure/Options.pm>:
 198
 199 =over 4
 200
 201 =item *
 202
 203 the list of valid command-line arguments in
 204 C<Parrot::Configure::Options::get_valid_options()>; and
 205
 206 =item *
 207
 208 the description of command-line arguments found in
 209 C<Parrot::Configure::Options::print_help()>.
 210
 211 =back
 212
 213 Arguments passed to F<Configure.pl> are held in a L<Parrot::Configure::Data>
 214 object stored inside the L<Parrot::Configure> object.  The options data object
 215 may be accessed via the L<Parrot::Configure/options> method.
 216
 217 Steps use the C<args> method to list any options they're interested in.  They
 218 should be listed without the dashes.
 219
 220 =head2 Building Up Configuration Data
 221
 222 The second step is F<config/init/defaults.pm>, which sets up some defaults in a
 223 L<Parrot::Configure::Data> object contained by the main L<Parrot::Configure>
 224 object.  It can be accessed via the L<Parrot::Configure/data>method.  You get
 225 and set configuration system's data by interacting with this object.  Some of
 226 its methods are summarized below.
 227
 228 =over 4
 229
 230 =item C<get(keys)>
 231
 232 Returns the values for the given keys.
 233
 234 =item C<set(key, value, [key, value, ...])>
 235
 236 Sets the given keys to the given values.
 237
 238 =item C<add(delim, key, value, [key, value, ...])>
 239
 240 Sets the given keys to the given values or appends values delimited by I<delim>
 241 to existing keys.
 242
 243 =item C<keys()>
 244
 245 Returns a list of all keys.
 246
 247 =item C<dump()>
 248
 249 Returns a string that can be C<eval>ed by Perl to create a hash representing
 250 the configuration system's data.
 251
 252 See the L<Parrot::Configure::Data> documentation for further details.
 253
 254 =back
 255
 256 =head2 Special Configuration Items
 257
 258 Some configuration items, by convention, have a special meaning (mainly
 259 prefixes) and are handled with some magic internally.
 260
 261 =over 4
 262
 263 =item C<i_(\w+)> include files
 264
 265 defines or undefs PARROT_HAS_HEADER_XXX in F<include/parrot/has_header.h>
 266
 267 =item C<HAS_(\w+)> features
 268
 269 defines PARROT_HAS_XXX in F<include/parrot/has_header.h>
 270
 271 =item C<TEMP_(\w+)> temporary settings
 272
 273 These settings are deleted before F<lib/Parrot/Config.pm> is written. These
 274 entries are only used e.g. for Makefile creation.
 275
 276 =back
 277
 278 =head1 HISTORY
 279
 280 The Parrot configuration system was created by Brent Dax and has been heavily
 281 mangled by Joshua Hoblitt.
 282
 283 =head1 SEE ALSO
 284
 285 L<Parrot::Configure>, L<Parrot::Configure::Data>,
 286 L<Parrot::Configure::Step>, L<Parrot::Configure::Step::Base>
 287
 288 =cut
 289