NAME

Configure.pl - Parrot Configure

SYNOPSIS

% perl Configure.pl [options]

DESCRIPTION

This is Parrot's configuration script.

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.

--nomanicheck

Tells Configure.pl not to run the MANIFEST check.

--maintainer

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

--miniparrot

Build parrot assuming only pure ANSI C is available.

--buildicu

Build Parrot and ICU. Runs icu/source/configure with the options in icu/README.parrot.

Parrot Configuration Options

You can add and remove option values with <:rem{<opt}>> and <:add{<opt}>>. For example:

perl Configure.pl --ccflags="rem{-g} :add{-O2}"

--ask

This turns on the user prompts.

--debugging=0

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

--optimize

Tell the compiler to do an optimization phase.

--inline

Tell Configure that the compiler supports inline.

--expnetwork

Enable experimental networking. This is an unused option and should probably be removed.

--cc=(compiler)

Specify which 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

--ld=(linker)

Specify which loader to use for shared libraries.

--ldflags=(flags)

Use the given loader flags for shared libraries

--lex=(lexer)

Specify which lexer to use.

--yacc=(parser)

Specify which parser to use.

--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.

--pmc=(files)

Use the given PMC files.

--cgoto=0

Don't build cgoto core. This is recommended when you are short of memory.

--jitcapable

Use JIT system.

--execcapable

Use JIT to emit a native executable.

--gc=(type)

Determine the type of garbage collection. The value for type should be one of: gc, libc, malloc or malloc-trace. The default is gc.

--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

Parrot Configuration System

Configure is broken up into steps. Each step contains several related prompts, probes, or generations. Steps should be mostly of a single type, though some overlap is allowed (for example, allowing a probe to ask the user what to do in an exceptional situation).

The directory config contains subdirectories for each type of step. Each step should consist of exactly one .pl file and any number of supporting .c, .in, etc. files. Any supporting files should be in a folder whose name is the same as the basename of the step's .pl file; for example, if foo.pl uses bar_c.in, bar_c.in should be in a directory called foo; the full path might be config/auto/foo/bar_c.in.

Generally, when adding a new test you should add a new step unless a test clearly belongs in a current step. For example, if we added a new user-configurable type called FOOVAL, you should add the test for its size in auto/sizes.pl; however, if you were testing what dynaloading capabilities are available, you should create a new step.

Initialization Steps

Initialization steps are run before any other steps. They do tasks such as preparing Configure's data structures and checking the MANIFEST. These will rarely be added; when they are, it usually means that Configure is getting significant new capabilities. They're kept in the directory config/init.

Initialization steps usually do not output anything under normal circumstances.

Prompts

Prompts ask the user for some information. These should be used sparingly. A step containing prompts is an interactive step. Interactive steps should be in the config/inter folder.

Interactive steps often include simple probes to determine good guesses of what the user will answer. See "Prompt or Probe?" for more information.

Interactive steps virtually always output something.

Note that, by default, these prompts are turned off. To enable them run Configure with the "--ask" option.

Probes

Probes are automated tests of some feature of the computer. These should be used wherever a value will not often need to be modified by the user. A step containing probes is an automatic step. Automatic steps should be in the config/auto folder.

Automatic steps usually do not output anything under normal circumstances.

Generations

Generations create files needed after Configure has completed, such as Makefiles and configuration headers. A step containing generations is a generation step. Generation steps should be in the config/gen folder.

Generation steps usually do not output anything under normal circumstances.

Prompt or Probe?

It can sometimes be hard to decide whether a given step should be an automatic or an interactive step. The guiding question is Would a user ever want to change this?, or conversely, Is this something that can be completely determined without user intervention? A step figuring out what the compiler's command is would probably be an interactive step; conversely, a step figuring out if that command is connected to a specific compiler (like gcc) would be an automatic step.

Adding Steps

New steps should be added in one of the three folders mentioned above. They should include the Parrot::Configure::Step module, described below.

All steps are really modules; they should start with a declaration setting the current package to Configure::Step. They should define the following:

$description

A short descriptive message that should be printed before the step executes. Usually, interactive steps have long, friendly descriptions and other steps have terse descriptions ending in "...".

Some example descriptions:

inter/progs.pl

Okay, I'm going to start by asking you a couple questions about your
compiler and linker.  Default values are in square brackets;
you can hit ENTER to accept them.  If you don't understand a question,
the default will usually work--they've been intuited from your Perl 5
configuration.

auto/cgoto.pl

Determining if your compiler supports computed goto...

gen/config_h.pl

Generating config.h...

Note that on non-interactive steps, the text "done." will be printed after the description when the step finishes executing; for example, the user will see:

Determining if your compiler supports computed goto...done.

@args

This contains the names of any command-line arguments the step cares about. Command-line arguments are standardized in Configure; this will be described later in more detail.

Configure::Step::runstep

This is called to actually execute the step. The command-line arguments that your module said it cared about are passed in; they come in the same order as in @args, and any that weren't specified are passed as undef.

Configure won't execute your step by default unless it's specifically told to. To do this, edit the Parrot::Configure::RunSteps module's @steps array. Steps are run in the sequence in which they appear in @steps.

A template for a new step might look like this:

package Configure::Step;

use strict;
use vars qw($description @args);
use Parrot::Configure::Step;

$description="<description>";
@args=qw(<args>);

sub runstep {
    <code>
}

Command-line Arguments

Command-line arguments look like /--\w+(=.*)?/; the equals sign separates the name and the value. If the value is omitted, it's assumed to be 1. The options --help and --version are built in to Configure; any others are defined by steps.

If you add a new option, don't forget to add it to this documentation and the "--help" listing in Configure.pl.

Steps use the @args array to list any options they're interested in. They should be listed without the dashes.

Building Up Configuration Data

The second step is config/init/data.pl, which sets up a Configure::Data package. You get and set Configure's data by calling methods on this package. The methods are listed below.

Configure::Data->get(keys)

Returns the values for the given keys.

Configure::Data->set(key, value, key, value, ...)

Sets the given keys to the given values.

Configure::Data->keys()

Returns a list of all keys.

Configure::Data->dump()

Returns a string that can be evaled by Perl to create a hash representing Configure's data.

Parrot::Configure::Step

The Parrot::Configure::Step module contains utility functions for steps to use. They include the following:

prompt(message, default)

Prints out "message [default] " and waits for the user's response. Returns the response, or the default if the user just hit ENTER.

cc_gen(file)

Calls genfile(file, 'test.c').

cc_build()

Calls the compiler and linker on test.c.

cc_run()

Calls the test (or test.exe) executable.

cc_clean()

Cleans up all files in the root folder that match the glob test.*.

genfile(infile, outfile)

Takes the given infile, substitutes any sequences matching /\$\{\w+\}/ for the given key's value in Configure's data, and writes the results to outfile.

AUTHOR

Brent Dax

cpanm Make

perl -MCPAN -e shell
install Make