Ticket #330: Configure.pl

File Configure.pl, 14.9 KB (added by quevlar, 5 years ago)
Line 
1#! perl
2
3# Copyright (C) 2001-2009, Parrot Foundation.
4# $Id: Configure.pl 79697 2009-02-13 05:22:59Z allison $
5
6use 5.008;
7use strict;
8use warnings;
9use lib 'lib';
10
11use Parrot::Configure;
12use Parrot::Configure::Options qw( process_options );
13use Parrot::Configure::Options::Test;
14use Parrot::Configure::Options::Test::Prepare qw(
15    get_preconfiguration_tests
16    get_postconfiguration_tests
17);
18use Parrot::Configure::Messages qw(
19    print_introduction
20    print_conclusion
21);
22use Parrot::Revision;
23
24$| = 1;    # $OUTPUT_AUTOFLUSH = 1;
25
26# Install Option text was taken from:
27#
28# autoconf (GNU Autoconf) 2.59
29# Written by David J. MacKenzie and Akim Demaille.
30#
31# Copyright (C) 2003 Free Software Foundation, Inc.
32# This is free software; see the source for copying conditions.  There is NO
33# warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
34
35# from Parrot::Configure::Options
36my ($args, $steps_list_ref) = process_options(
37    {
38        mode => (defined $ARGV[0]  and $ARGV[0] =~ /^--file=/)
39                    ? 'file'
40                    : 'configure',
41        argv => [@ARGV],
42    }
43);
44exit(1) unless defined $args;
45
46my $opttest = Parrot::Configure::Options::Test->new($args);
47
48# configuration tests will only be run if you requested them
49# as command-line option
50$opttest->run_configure_tests( get_preconfiguration_tests() );
51
52my $parrot_version = $Parrot::Configure::Options::Conf::parrot_version;
53
54# from Parrot::Configure::Messages
55print_introduction($parrot_version);
56
57# Update revision number if needed
58Parrot::Revision::update();
59
60my $conf = Parrot::Configure->new();
61
62$conf->add_steps( @{ $steps_list_ref } );
63
64# from Parrot::Configure::Data
65$conf->options->set( %{$args} );
66# save the command-line for make reconfig
67$conf->data->set(configure_args => @ARGV ? '"'.join("\" \"", map {qq($_)} @ARGV).'"'
68                                         : '');
69
70# Log files created by Configure.pl in MANIFEST.configure.generated
71$conf->{active_configuration} = 1;
72unlink 'MANIFEST.configure.generated';
73
74# Run the actual steps from Parrot::Configure
75$conf->runsteps or exit(1);
76
77# build tests will only be run if you requested them
78# as command-line option
79$opttest->run_build_tests( get_postconfiguration_tests() );
80
81my $make = $conf->data->get('make');
82# from Parrot::Configure::Messages
83( print_conclusion( $conf, $make ) ) ? exit 0 : exit 1;
84
85################### DOCUMENTATION ###################
86
87=head1 NAME
88
89Configure.pl - Parrot's configuration script
90
91=head1 SYNOPSIS
92
93    % perl Configure.pl [options]
94
95or:
96
97    % perl Configure.pl --file=/path/to/configuration/directives
98
99=head1 DESCRIPTION
100
101This is Parrot's configuration program. It should be run to create
102the necessary system-specific files before building Parrot.
103
104We now offer two interfaces to configuration:
105
106=over 4
107
108=item * Command-Line Interface
109
110All configuration options are placed on the command-line.  You may request
111interactive configuration with the C<--ask> option.  You may not use the
112C<--file> option, as that is reserved for the Configuration-File interface.
113
114=item * Configuration-File Interface
115
116All configuration options are placed in a special configuration file whose
117full path is invoked on the command-line as
118C<--file=/path/to/configuration/directives> as the sole command-line option.
119You may not request interactive configuration.  For specific instructions, see
120L</"CONFIGURATION-FILE INTERFACE"> below.
121
122=back
123
124=head2 General Options
125
126=over 4
127
128=item C<--help>
129
130Prints out a description of the options and exits.
131
132=item C<--version>
133
134Prints out the version number of Configure.pl and exits.
135
136=item C<--verbose>
137
138Tells Configure.pl to output extra information about the configuration data it
139is setting.
140
141=item C<--verbose=2>
142
143Tells Configure.pl to output information about i<every> setting added or
144changed.
145
146=item C<--verbose-step={N|regex}>
147
148Run C<--verbose=2> for step number C<N> or matching description.
149
150=item C<--fatal>
151
152Tells Configure.pl to halt completely if any configuration step fails.
153
154=item C<--fatal-step={init::alpha,inter::beta,auto::gamma}>
155
156Tells Configure.pl to halt completely if any configuration step in
157comma-delimited string individually fails.
158
159=item C<--nomanicheck>
160
161Tells Configure.pl not to run the MANIFEST check.
162
163=item C<--prefix>
164
165Sets the location where parrot will be installed.
166
167=item C<--languages="list of languages">
168
169Specify a list of languages to process (space separated.)
170Used in combination with C<--step=gen::languages> to regenerate makefiles.
171
172=item C<--ask>
173
174This turns on the user prompts during configuration.  Available only in
175Command-Line interface.  Not available in Configuration-File interface.
176
177=item C<--test>
178
179Run certain tests along with F<Configure.pl>:
180
181=over 4
182
183=item C<--test=configure>
184
185Run tests found in F<t/configure/> I<before> beginning configuration.  These
186tests demonstrate that Parrot's configuration tools will work properly once
187configuration has begun.
188
189=item C<--test=build>
190
191Run tests found in F<t/postconfigure/>, F<t/tools/pmc2cutils/>,
192F<t/tools/ops2cutils/> and F<t/tools/ops2pm/> I<after> configuration has
193completed.  These tests demonstrate (a) that certain of Parrot's configuration
194tools are working properly post-configuration; and (b) that certain of
195Parrot's build tools will work properly once you call F<make>.
196
197=item C<--test>
198
199Run the tests described in C<--test=configure>, conduct configuration, then
200run the tests described in C<--test=build>.
201
202=back
203
204=back
205
206=head2 Compile Options
207
208=over 4
209
210=item C<--debugging=0>
211
212Debugging is turned on by default. Use this to disable it.
213
214=item C<--parrot_is_shared>
215
216Link parrot dynamically.
217
218=item C<--m=32>
219
220Create a 32-bit executable on 64-architectures like x86_64. This
221option appends -m32 to compiler and linker programs and does
222s/lib64/lib/g on link flags.
223
224This option is experimental. See F<config/init/defaults.pm> for more.
225
226=item C<--profile>
227
228Turn on profiled compile (gcc only for now)
229
230=item C<--cage>
231
232[CAGE] compile includes many additional warnings
233
234=item C<--optimize>
235
236Add perl5's $Config{optimize} to the compiler flags.
237
238=item C<--optimize=flags>
239
240Add C<flags> to the compiler flags.
241
242=item C<--inline>
243
244Tell Configure that the compiler supports C<inline>.
245
246=item C<--cc=(compiler)>
247
248Specify which compiler to use.
249
250=item C<--ccflags=(flags)>
251
252Use the given compiler flags.
253
254=item C<--ccwarn=(flags)>
255
256Use the given compiler warning flags.
257
258=item C<--cxx=(compiler)>
259
260Specify which C++ compiler to use (for ICU).
261
262=item C<--libs=(libs)>
263
264Use the given libraries.
265
266=item C<--link=(linker)>
267
268Specify which linker to use.
269
270=item C<--linkflags=(flags)>
271
272Use the given linker flags
273
274=item C<--ld=(linker)>
275
276Specify which loader to use for shared libraries.
277
278=item C<--ldflags=(flags)>
279
280Use the given loader flags for shared libraries
281
282=item C<--lex=(lexer)>
283
284Specify which lexer to use.
285
286=item C<--yacc=(parser)>
287
288Specify which parser to use.
289
290=item C<--define=val1[,val2]>
291
292Generate "#define PARROT_DEF_VAL1 1" ... entries in has_header.h. Currently
293needed to use inet_aton for systems that lack inet_pton:
294
295  --define=inet_aton
296
297=back
298
299=head2 Parrot Options
300
301=over 4
302
303=item C<--intval=(type)>
304
305Use the given type for C<INTVAL>.
306
307=item C<--floatval=(type)>
308
309Use the given type for C<FLOATVAL>.
310
311=item C<--opcode=(type)>
312
313Use the given type for opcodes.
314
315=item C<--ops=(files)>
316
317Use the given ops files.
318
319=item C<--pmc=(files)>
320
321Use the given PMC files.
322
323=item C<--cgoto=0>
324
325Don't build cgoto core. This is recommended when you are short of memory.
326
327=item C<--jitcapable>
328
329Use JIT system.
330
331=item C<--execcapable>
332
333Use JIT to emit a native executable.
334
335=item C<--gc=(type)>
336
337Determine the type of garbage collection. The value for C<type> should be one
338of: C<gc>, C<libc>, C<malloc> or C<malloc-trace>. The default is C<gc>.
339
340=back
341
342=head2 International Components For Unicode (ICU) Options
343
344=over 4
345
346=item C<--icu-config=/path/to/icu-config>
347
348Use the specified icu-config script to determine the necessary ICU options.
349
350Use --icu-config=none to disable the autodetect feature. Parrot will then be
351build without ICU.
352
353B<Note:> If you specify another ICU option than --icu-config, the autodetection
354functionality will be disabled.
355
356=item C<--icushared=(linkeroption)>
357
358Linker command to link against ICU library.
359
360E.g.
361
362   --icushared='-L /opt/openoffice/program -licudata -licuuc'
363
364(The libs in openoffice are actually version 2.2 and do not work)
365
366=item C<--icuheaders=(header_dir)>
367
368Location of ICU header files without the /unicode suffix.
369
370E.g.
371
372--icuheaders='/home/lt/icu/'
373
374=back
375
376=head2 Other Options
377
378=over 4
379
380=item C<--maintainer>
381
382Use this option if you want imcc's parser and lexer files to be generated.
383Needs a working parser and lexer.
384
385=back
386
387=head1 CONFIGURATION-FILE INTERFACE
388
389In the Configuration-File interface, unlike the Command-Line interface, you
390may delete configuration steps or run them in an order different from that
391listed in Parrot::Configure::Step::List.
392
393A configuration file is a plain-text file located somewhere in or under your
394top-level Parrot directory.  Unless indicated otherwise, all lines in this
395file must have no leading whitespace.  As in Perl 5, lines beginning with C<#>
396marks are comments and are ignored during parsing of the file.  Unlike Perl 5,
397you may not begin comments in the middle of a line.
398
399The configuration file must contain these three sections:
400
401=over 4
402
403=item * variables
404
405=over 4
406
407=item *
408
409Section begins with line C<=variables> and must be followed by at least one
410blank line.  All other content in this section is optional.
411
412=item *
413
414Section may contain one or more I<key=value> pairs which assign strings to
415variables much in the way that you would do in a shell script wrapping around
416F<Configure.pl>.
417
418    =variables
419
420    CC=/usr/bin/gcc
421    CX=/usr/bin/g++
422
423So if you typically invoked F<Configure.pl> by wrapping it in a shell script
424for the purpose of setting environmental variables used in options, like this:
425
426    CC="/usr/bin/gcc"
427    CX="/usr/bin/g++"
428    /usr/local/bin/perl Configure.pl \
429        --cc="$CC" \
430        --cxx="$CX" \
431        --link="$CX" \
432        --ld="$CX"
433
434... you would now place the assignments to C<CC> and C<CX> in the
435I<=variables> section of the configuration file (as above).
436
437=back
438
439=item * general
440
441=over 4
442
443=item *
444
445Section begins with line C<=general> and must be followed by at least one
446blank line.  All other content in this section is optional.
447
448=item *
449
450This section is the location recommended for listing options whose impact is
451not conceptually limited to a single step.  It is also the location where the
452variables defined in the I<=variables> section are assigned to particular
453Parrot configuration options.  Entries in this section must be either
454I<option=value> pairs or be options which will be assigned a true value.
455
456    cc=$CC
457    cxx=$CX
458    link=$CX
459    ld=/usr/bin/g++
460    verbose
461
462Note that when the value is a variable defined in the I<=variables> section,
463it must be preceded by a C<$> sign.
464
465=item *
466
467You I<may> list options here which are I<conceptually> limited to a single
468configuration step.  For example, if you wished to skip validation of the
469F<MANIFEST> during configuration and to configure without ICU, you I<could>,
470in this section, say:
471
472    nomanicheck
473    without-icu
474
475However, as we shall quickly see, it's conceptually clearer to place these
476values next to those configuration steps that actually use them.
477
478=back
479
480=item * steps
481
482=over 4
483
484=item *
485
486Section begins with line C<=steps> and must be followed by at least one
487blank line, in turn followed by the list of configuration steps, followed by
488another blank line followed by a line C<=cut> (just like POD).
489
490=item *
491
492The order in which you list the steps is the order in which they will be
493executed.  If you delete a step from the canonical list or comment a step out,
494it will not be executed.
495
496    ...
497    auto::snprintf
498    # auto::perldoc
499    auto::ctags
500    ...
501
502In the above example, step C<auto::perldoc> will be completely skipped.  You
503will not see it listed as C<....skipped> in F<Configure.pl>'s output; it will
504simply not be there at all.
505
506=item *
507
508This is the recommended location to call options whose impact is
509I<conceptually> limited to a single configuration step.  Type the
510configuration step's name, type a whitespace, type the option (with no leading
511C<-->) and repeat as needed for additional step-specific options.
512
513    init::manifest nomanicheck
514    ...
515
516=item *
517
518This is also the location to call options whose impact is limited to one step
519at a time but which may be applied to more than one configuration step.  The
520C<fatal-step> and C<verbose-step> options are the best examples of this case.
521Rather than requesting verbose output from all configuration steps, you may,
522for example, wish to designate only a few steps for verbose output:
523
524    ...
525    init::hints verbose-step
526    init::headers
527    inter::progs fatal-step
528    ...
529    auto::gcc verbose-step
530    ...
531
532In the above example, F<Configure.pl> will grind to a halt if C<inter::progs>
533does not complete successfully.  You will get verbose output only from
534C<init::hints> and C<auto::gcc>; the other 60+ steps will be terse.
535
536=item *
537
538Nothing prevents you from listing general options anywhere in this section.
539
540    init::manifest nomanicheck cc=$CC ld=/usr/bin/g++ verbose
541    init::defaults
542    ...
543
544That will work -- but why would you want to do something that messy?
545
546=back
547
548=back
549
550=head2 Example
551
552Ignoring leading whitespace, this is an example of a correctly formed
553configuration file.
554
555    =variables
556
557    CC=/usr/bin/gcc
558    CX=/usr/bin/g++
559
560    =general
561
562    cc=$CC
563    cxx=$CX
564    link=$CX
565    ld=/usr/bin/g++
566
567    =steps
568
569    init::manifest nomanicheck
570    init::defaults
571    init::install
572    init::hints verbose-step
573    init::headers
574    inter::progs
575    inter::make
576    inter::lex
577    inter::yacc
578    auto::gcc
579    auto::glibc
580    auto::backtrace
581    auto::fink
582    auto::macports
583    auto::msvc
584    auto::attributes
585    auto::warnings
586    init::optimize
587    inter::shlibs
588    inter::libparrot
589    inter::charset
590    inter::encoding
591    inter::types
592    auto::ops
593    auto::pmc
594    auto::alignptrs
595    auto::headers
596    auto::sizes
597    auto::byteorder
598    auto::va_ptr
599    auto::format
600    auto::isreg
601    auto::arch
602    auto::jit
603    auto::cpu
604    auto::funcptr
605    auto::cgoto
606    auto::inline
607    auto::gc
608    auto::memalign
609    auto::signal
610    auto::socklen_t
611    auto::env
612    auto::gmp
613    auto::readline
614    auto::gdbm
615    auto::pcre
616    auto::opengl
617    auto::crypto
618    auto::gettext
619    auto::snprintf
620    # auto::perldoc
621    auto::ctags
622    auto::revision
623    auto::icu
624    gen::config_h
625    gen::core_pmcs
626    gen::crypto
627    gen::parrot_include
628    gen::opengl
629    gen::call_list
630    gen::languages
631    gen::makefiles
632    gen::platform
633    gen::config_pm
634
635    =cut
636
637You may see how this works in practice by calling:
638
639    perl Configure.pl --file=xconf/samples/yourfoobar
640
641or
642
643    perl Configure.pl --file=xconf/samples/testfoobar
644
645=head1 SEE ALSO
646
647F<lib/Parrot/Configure.pm>,
648F<lib/Parrot/Configure/Step.pm>, F<docs/configuration.pod>
649
650=cut
651
652# Local Variables:
653#   mode: cperl
654#   cperl-indent-level: 4
655#   fill-column: 100
656# End:
657# vim: expandtab shiftwidth=4:
658