1 # Copyright (C) 2004-2008, Parrot Foundation.
8 docs/configuration.pod - Parrot Configuration System
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).
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>.
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.
33 =head2 Initialization Steps
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>.
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.
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.
50 Note that, by default, these prompts are turned off. To enable them run
51 F<Configure.pl> with the C<--ask> option.
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.
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
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>
71 =head2 Prompt or Probe?
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.
81 =head2 Configuring Configuration
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()>.
88 =head2 Adding New Steps
90 New steps should be added in one of the four folders mentioned above.
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.
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()>.
101 The C<_init()> method should follow the following example, defining three
102 elements within an internal hash:
107 $data{description} = q{This is the step description};
116 Of these three elements, C<description> is the most important as it is
117 used extensively within C<lib/Parrot/Configure.pm>.
119 Returns a short descriptive message that should be printed before the step
122 Some example descriptions:
126 =item F<gen/config_h.pm>
128 Generate C headers...
132 Note that on non-interactive steps, the text I<done> will be printed after the
133 description when the step finishes executing; for example, the user will see:
135 Determine flags for building shared libraries.....-fPIC
139 The C<result> is initialized to an empty string mainly to quiet
140 'uninitialized variable' warnings. Most configuration steps override
141 the C<result> value inside their C<runstep()> method.
145 This method is called to actually execute the step. The return
146 value should be C<1> if the step accomplishes what it is intended to do.
147 Otherwise, the step should simply C<return>, I<i.e.>, return an
152 The configuration system won't execute your step by default unless it's
153 specifically told to. To do this, edit F<lib/Parrot/Configure/Step/List.pm>.
154 Steps are run in the order in which that are registered with the
155 L<Parrot::Configure> object.
157 Various utility functions for configuration steps are provided by the
158 L<Parrot::Configure::Utils> module.
160 A template for a new step might look like this:
162 package auto::newstep;
166 our qw($description $result);
168 use base qw(Parrot::Configure::Step);
170 use Parrot::Configure::Utils;
175 $data{description} = q{This is the step description};
181 my ($self, $conf) = @_
184 $self->set_result('yes');
187 $self->set_result('no');
192 The step's C<runstep()> method should return C<1> upon success and do a
193 bare return on failure (thereby returning an undefined value).
195 =head2 Command-line Arguments
197 Command-line arguments look like C</--[-\w]+(=.*)?/>; the equals sign separates
198 the name and the value. If the value is omitted, it's assumed to be C<1>. The
199 options C<--help> and C<--version> are built in to Configure; any others are
202 Command-line arguments are now processed by C<process_options()>, a subroutine
203 exported by L<Parrot::Configure::Options>. If you add a new option, don't
204 forget to add it to this documentation and to appropriate locations. Most
205 options should be added to C<@shared_valid_options> in
206 F<lib/Parrot/Configure/Options/Conf/Shared.pm>.
208 Arguments passed to F<Configure.pl> are held in a L<Parrot::Configure::Data>
209 object stored inside the L<Parrot::Configure> object. The options data object
210 may be accessed via the C<Parrot::Configure::options()> method.
212 =head2 Configuration by File
214 As an alternative to typing a long string of options on the command-line,
215 Parrot can now be configured from a configuration file. You put the options
216 in a configuration file, then call F<Configure.pl> as follows:
218 perl Configure.pl --file=/path/to/config/file
220 That's it! No other command-line arguments needed (or permitted)! To learn
221 how to create such a configuration file, call:
225 =head2 Building Up Configuration Data
227 The second step is F<config/init/defaults.pm>, which sets up some defaults in
228 a L<Parrot::Configure::Data> object contained by the main L<Parrot::Configure>
229 object. It can be accessed via the C<Parrot::Configure::data()> method. You
230 get and set configuration system's data by interacting with this object. Some
231 of its methods are summarized below.
237 Returns the values for the given keys.
239 =item C<set(key, value, [key, value, ...])>
241 Sets the given keys to the given values.
243 =item C<add(delim, key, value, [key, value, ...])>
245 Sets the given keys to the given values or appends values delimited by I<delim>
250 Returns a list of all keys.
254 Returns a string that can be C<eval>ed by Perl to create a hash representing
255 the configuration system's data.
257 See the L<Parrot::Configure::Data> documentation for further details.
261 =head2 Special Configuration Items
263 Some configuration items, by convention, have a special meaning (mainly
264 prefixes) and are handled with some magic internally.
268 =item C<i_(\w+)> include files
270 defines or undefs PARROT_HAS_HEADER_XXX in F<include/parrot/has_header.h>
272 =item C<HAS_(\w+)> features
274 defines PARROT_HAS_XXX in F<include/parrot/has_header.h>
276 =item C<TEMP_(\w+)> temporary settings
278 These settings are deleted before F<lib/Parrot/Config.pm> is written. These
279 entries are only used e.g. for Makefile creation.
283 =head2 Accessing Configuration Information via Perl 5 Variables
285 Parrot configuration is currently jump-started by extracting
286 considerable information from variables associated with the instance of
287 Perl 5 which the user is using to run F<Configure.pl>. These variables
288 are largely looked up in the C<%Config> found in the Perl 5
289 F<Config.pm>, but may also be sought in Perl 5 special variables such as
290 C<$^O>. All such lookups should be done in configuration step
291 C<init::defaults> and B<only> in that step. Special accessors are
292 available for working with such variables; see
293 F<config/init/defaults.pm> and F<lib/Parrot/Configure/Data.pm>.
297 The Parrot configuration system was created by Brent Dax and has been heavily
298 mangled by Joshua Hoblitt. James Keenan refactored the configuration system.
302 L<Parrot::Configure>, L<Parrot::Configure::Data>,
303 L<Parrot::Configure::Utils>, L<Parrot::Configure::Step>