/ 
Rakudo-Star-2012.08_001
/ Configure.pl

NAME

Configure.pl - Parrot's configuration script

SYNOPSIS

% perl Configure.pl [options]

or:

% perl Configure.pl --file=/path/to/configuration/directives

DESCRIPTION

This is Parrot's configuration program. It should be run to create the necessary system-specific files before building Parrot.

We now offer two interfaces to configuration:

  • Command-Line Interface

    All configuration options are placed on the command-line. You may request interactive configuration with the --ask option. You may not use the --file option, as that is reserved for the Configuration-File interface.

  • Configuration-File Interface

    All configuration options are placed in a special configuration file whose full path is invoked on the command-line as --file=/path/to/configuration/directives as the sole command-line option. You may not request interactive configuration. For specific instructions, see "CONFIGURATION-FILE INTERFACE" below.

General Options

--help

Prints out a description of the options and exits.

--version

Prints out the version number of Configure.pl and exits.

--verbose

Tells Configure.pl to output extra information about the configuration data it is setting.

--verbose=2

Tells Configure.pl to output information about i<every> setting added or changed.

--verbose-step={N|regex}

Run --verbose=2 for step number N or matching description.

--fatal

Tells Configure.pl to halt completely if any configuration step fails.

--fatal-step={init::alpha,inter::beta,auto::gamma}

Tells Configure.pl to halt completely if any configuration step in comma-delimited string individually fails.

--nomanicheck

Tells Configure.pl not to run the MANIFEST check.

--prefix

Sets the location where parrot will be installed.

--ask

This turns on the user prompts during configuration. Available only in Command-Line interface. Not available in Configuration-File interface.

--test

Run certain tests along with Configure.pl:

--test=configure

Run tests found in t/configure/ before beginning configuration. These tests demonstrate that Parrot's configuration tools will work properly once configuration has begun.

--test=build

Run tests found in t/steps/, t/postconfigure/ and t/pharness.

--test

Run the tests described in --test=configure, conduct configuration, then run the tests described in --test=build.

--configure_trace

Store the results of each configuration step in a Storable .sto file on disk, for later analysis by Parrot::Configure::Trace methods.

--coveragedir

In preparation for calling make cover to perform coverage analysis, provide a user-specified directory for top level of HTML output.

Operating system-specific configuration options
--hintsfile=filename

Use filename as the hints file.

--darwin_no_fink

On Darwin, do not probe for Fink libraries.

--darwin_no_macports

On Darwin, do not probe for Macports libraries.

Compile Options

--debugging=0

Debugging is turned on by default. Use this to disable it.

--parrot_is_shared

Link parrot dynamically.

--m=32

Create a 32-bit executable on 64-architectures like x86_64. This option appends -m32 to compiler and linker programs and does s/lib64/lib/g on link flags.

This option is experimental. See config/init/defaults.pm for more.

--profile

Turn on profiled compile (gcc only for now)

--cage

[CAGE] compile includes many additional warnings

--optimize

Add Perl 5's $Config{optimize} to the compiler flags.

--optimize=flags

Add flags to the compiler flags.

--inline

Tell Configure that the compiler supports inline.

--cc=(compiler)

Specify which C compiler to use.

--cxx=(compiler)

Specify which C++ compiler to use.

--ccflags=(flags)

Use the given compiler flags.

--ccwarn=(flags)

Use the given compiler warning flags.

--libs=(libs)

Use the given libraries.

--link=(linker)

Specify which linker to use.

--linkflags=(flags)

Use the given linker flags

--ar=(archiver)

Specify which librarian to use for static libraries

--arflags=(flags)

Use the given librarian flags for static libraris

--ld=(linker)

Specify which loader to use for shared libraries.

--ldflags=(flags)

Use the given loader flags for shared libraries

--disable-rpath

Specify that rpath should not be included in linking flags. With this configuration option, you must append the library build directory (usually blib/lib) to the LD_LIBRARY_PATH environment variable (or your platform equivalent). This option is primarily used for building Linux packages.

--lex=(lexer)

Specify which lexer to use.

--yacc=(parser)

Specify which parser to use.

--define=val1[,val2]

Generate "#define PARROT_DEF_VAL1 1" ... entries in has_header.h. Currently needed to use inet_aton for systems that lack inet_pton:

--define=inet_aton
--no-line-directives

Disables the creation of C #line directives when generating C from PMCs and ops. Useful when debugging internals.

Parrot Options

--intval=(type)

Use the given type for INTVAL.

--floatval=(type)

Use the given type for FLOATVAL.

--opcode=(type)

Use the given type for opcodes.

--ops=(files)

Use the given ops files.

International Components For Unicode (ICU) Options

--icu-config=/path/to/icu-config

Use the specified icu-config script to determine the necessary ICU options.

Use --icu-config=none to disable the autodetect feature. Parrot will then be build without ICU.

Note: If you specify another ICU option than --icu-config, the autodetection functionality will be disabled.

--icushared=(linkeroption)

Linker command to link against ICU library.

E.g.

--icushared='-L /opt/openoffice/program -licudata -licuuc'

(The libs in openoffice are actually version 2.2 and do not work)

--icuheaders=(header_dir)

Location of ICU header files without the /unicode suffix.

E.g.

--icuheaders='/home/lt/icu/'

Other Options

--maintainer

Use this option if you want imcc's parser and lexer files to be generated. Needs a working parser and lexer.

--with-llvm

Use this option if you have a recent version of LLVM installed and wish Parrot to link to it.

CONFIGURATION-FILE INTERFACE

In the Configuration-File interface, unlike the Command-Line interface, you may delete configuration steps or run them in an order different from that listed in Parrot::Configure::Step::List.

A configuration file is a plain-text file located somewhere in or under your top-level Parrot directory. Unless indicated otherwise, all lines in this file must have no leading whitespace. As in Perl 5, lines beginning with # marks are comments and are ignored during parsing of the file. Unlike Perl 5, you may not begin comments in the middle of a line.

The configuration file must contain these three sections:

  • variables

    • Section begins with line =variables and must be followed by at least one blank line. All other content in this section is optional.

    • Section may contain one or more key=value pairs which assign strings to variables much in the way that you would do in a shell script wrapping around Configure.pl.

      =variables

CC=/usr/bin/gcc
CX=/usr/bin/g++

      So if you typically invoked Configure.pl by wrapping it in a shell script for the purpose of setting environmental variables used in options, like this:

      CC="/usr/bin/gcc"
CX="/usr/bin/g++"
/usr/local/bin/perl Configure.pl \
    --cc="$CC" \
    --link="$CX" \
    --ld="$CX"

      ... you would now place the assignments to CC and CX in the =variables section of the configuration file (as above).

      In addition, should you wish to use an option whose value contains whitespace and would, if presented on the command-line, require quoting, you may assign that string to a variable and then use the variable in the general section below.

      LONGLONG=long long

  • general

    • Section begins with line =general and must be followed by at least one blank line. All other content in this section is optional.

    • This section is the location recommended for listing options whose impact is not conceptually limited to a single step. It is also the location where the variables defined in the =variables section are assigned to particular Parrot configuration options. Entries in this section must be either option=value pairs or be options which will be assigned a true value.

      cc=$CC
link=$CX
ld=/usr/bin/g++
verbose

      Note that when the value is a variable defined in the =variables section, it must be preceded by a $ sign.

      intval=$LONGLONG

      Alternatively, if assignment of a value to an option on the command-line would require quoting due to the presence of whitespace in the value, you may assign it to a value in the =general section by double-quoting the value.

      intval="long long"

    • You may list options here which are conceptually limited to a single configuration step. For example, if you wished to skip validation of the MANIFEST during configuration and to configure without ICU, you could, in this section, say:

      nomanicheck
without-icu

      However, as we shall quickly see, it's conceptually clearer to place these values next to those configuration steps that actually use them.

  • steps

    • Section begins with line =steps and must be followed by at least one blank line, in turn followed by the list of configuration steps, followed by another blank line followed by a line =cut (just like POD).

    • The order in which you list the steps is the order in which they will be executed. If you delete a step from the canonical list or comment a step out, it will not be executed.

      ...
auto::snprintf
# auto::perldoc
auto::ctags
...

      In the above example, step auto::perldoc will be completely skipped. You will not see it listed as ....skipped in Configure.pl's output; it will simply not be there at all.

    • This is the recommended location to call options whose impact is conceptually limited to a single configuration step. Type the configuration step's name, type a whitespace, type the option (with no leading --) and repeat as needed for additional step-specific options.

      init::manifest nomanicheck
...

    • This is also the location to call options whose impact is limited to one step at a time but which may be applied to more than one configuration step. The fatal-step and verbose-step options are the best examples of this case. Rather than requesting verbose output from all configuration steps, you may, for example, wish to designate only a few steps for verbose output:

      ...
init::hints verbose-step
...
inter::progs fatal-step
...
auto::gcc verbose-step
...

      In the above example, Configure.pl will grind to a halt if inter::progs does not complete successfully. You will get verbose output only from init::hints and auto::gcc; the other 60+ steps will be terse.

    • Nothing prevents you from listing general options anywhere in this section.

      init::manifest nomanicheck cc=$CC ld=/usr/bin/g++ verbose
init::defaults
...

      That will work -- but why would you want to do something that messy?

Example

Ignoring leading whitespace, this is an example of a correctly formed configuration file.

=variables

CC=/usr/bin/gcc
CX=/usr/bin/g++

=general

cc=$CC
link=$CX
ld=/usr/bin/g++

=steps

init::manifest nomanicheck
init::defaults
init::install
init::hints verbose-step
inter::progs
inter::make
inter::lex
inter::yacc
auto::gcc
auto::glibc
auto::backtrace
auto::fink
auto::macports
auto::msvc
auto::attributes
auto::warnings
init::optimize
inter::shlibs
inter::libparrot
inter::types
auto::ops
auto::alignptrs
auto::headers
auto::sizes
auto::byteorder
auto::va_ptr
auto::format
auto::isreg
auto::arch
auto::jit
auto::cpu
auto::inline
auto::gc
auto::memalign
auto::signal
auto::socklen_t
auto::env
auto::gmp
auto::readline
auto::pcre
auto::opengl
auto::gettext
auto::snprintf
# auto::perldoc
auto::ctags
auto::revision
auto::icu
auto::platform
gen::config_h
gen::core_pmcs
gen::opengl
gen::makefiles
gen::config_pm

=cut

You may see how this works in practice by calling:

perl Configure.pl --file=examples/config/file/configcompiler

or

perl Configure.pl --file=examples/config/file/configwithfatalstep

SEE ALSO

lib/Parrot/Configure.pm, lib/Parrot/Configure/Step.pm, docs/configuration.pod