/ 
Rakudo-Star-2012.08002
/ Parrot::Configure::Compiler

NAME

Parrot::Configure::Compiler - C-Related methods for configuration and more

DESCRIPTION

The Parrot::Configure::Compiler module provides methods inherited by Parrot::Configure which prepare and/or run C programs during compilation. Other methods from this module will be used to generate makefiles and other files. Template entries of the form @key@ will be replaced with key's value from the configuration system's data.

Methods

cc_gen()
$conf->cc_gen($source)

Generates test_$$.c from the specified source file.

cc_build()
$conf->cc_build($cc_args, $link_args)

These items are used from current config settings:

$cc, $ccflags, $ldout, $o, $link, $linkflags, $cc_exe_out, $exe, $libs

Calls the compiler and linker on test_$$.c.

cc_run()
$conf->cc_run();

Calls the test (or test.exe) executable. Any output is directed to test.out.

cc_run_capture()
$conf->cc_run_capture();

Same as cc_run() except that warnings and errors are also directed to test.out.

cc_clean()
$conf->cc_clean();

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

shebang_mod()
$conf->shebang_mod($source, $target);

Takes the specified source file, replacing entries like @key@ with key's value from the configuration system's data, and writes the results to specified target file. The replacement is only done in the first line of the file normally to set the shebang value accordingly.

genfile()
$conf->genfile($source, $target, %options);

Takes the specified source file, replacing entries like @key@ with key's value from the configuration system's data, and writes the results to specified target file.

If a :: is present in the @key@, the replaced value will first try to use the full key, but if that is not present, the key up to the :: is used. For example, if @cc_warn::src/embed.c@ is used, and that key doesn't exist, the fallback key would be @cc_warn@.

Respects the following options when manipulating files (Note: most of the replacement syntax assumes the source text is on a single line.)

file_type

If set to a makefile, c or perl value, comment_type will be set to corresponding value. Moreover, when set to a makefile value, it will enable conditioned_lines.

Its value will be detected automatically by target file name unless you set it to a special value none.

conditioned_lines #IF #UNLESS #ELSIF #ELSE

If conditioned_lines is true, then lines beginning in #IF, #UNLESS, #ELSIF, and #ELSE are evaluated conditionally, and the content after the : is included or excluded, depending on the evaluation of the expression.

Lines beginning with #IF(expr): are skipped if the expr condition is false, otherwise the content after the : is inserted. Lines beginning with #UNLESS(expr): are skipped if the expr condition is true, otherwise the content after the : is inserted. Lines beginning with #ELSIF(expr): or #ELSE: are evaluated if the preceding #IF(expr): evaluated to false.

A condition expr may be:

  • A single key, which is true if a config key is true,

  • Equal to the platform name or the osname - case-sensitive,

  • A key==value expression, which is true if the config key has the expected value, or

  • A logical combination of |, OR, &, AND, !, NOT.

A key must only consist of the characters A-Z a-z 0-9 _ -, and is checked case-sensitively against the configuration key or the platform name. Truth is defined as any value that is not 0, an empty string, or undef.

The value in key==value expressions may not contain spaces. Quotes in values are not supported.

The word ops AND, OR and NOT are case-insensitive. ! and NOT bind closer than &, AND, |, and OR. The order of precedence for AND and OR is undefined.

For instance:

#IF(win32): src/atomic/gcc_x86$(O)

will be included if the platform is win32.

#IF(cpuarch==i386): src/atomic/gcc_x86$(O)

will be included if the value of the config key "cpuarch" is "i386".

#IF(cpuarch==i386): src/atomic/gcc_x86$(O)
#ELSIF(cpuarch==sparcv9): src/atomic/sparc_v9.s
#ELSE:

will include " src/atomic/gcc_x86$(O)" if the config key "cpuarch" is ste to "i386", will include " src/atomic/sparc_v9.s" instead if "cpuarch" is set to "sparcv9", and will include an empty line otherwise.

#IF(win32 and glut and not cygwin):

will be used on "win32" and if "glut" is defined, but not on "cygwin".

comment_type

This option takes has two possible values, # or /*. If present and set to one of these two values, the generated file will contain a generated header that is commented out appropriately.

ignore_pattern

A regular expression. Any lines in the file matching this expression are ignored when determining if the target file has changed (and should therefore be overwritten with a new copy).

feature_file

When feature_file is set to a true value, a lines beginning with #perl forces the remaining lines of the file to be evaluated as perl code. Before this evaluation occurs, any substitution of @@ values is performed on the original text.

expand_gmake_syntax

If set to a true value, then certain types of gmake syntax will be expanded into their full equivalents. For example:

$(wildcard PATTERN)

Will be replaced at config time with the list of files that match this pattern. Note! Be very careful when determining whether or not to disable this expansion during config time and letting gmake evaluate these: the config system itself may change state of the filesystem, causing the directives to expand differently depending on when they're run. Another potential issue to consider there is that most makefiles, while generated from the root directory, are run from a subdirectory. So relative path names become an issue.

The gmake replacements are done repeatedly on a single line, so nested syntax works ok.

addprefix
basename
wildcard
notdir

SEE ALSO

docs/configuration.pod