ExtUtils::configPL - Perl extension to automagiclly configure perl scripts

NAME

ExtUtils::configPL - Perl extension to automagiclly configure perl scripts

SYNOPSIS

  use ExtUtils::configPL;
  <<--startperl-->> -w
  ...
  no ExtUtils::configPL;
  ...

DESCRIPTION

This module is used to add configuration information to a perl script, and is meant to be used with the ExtUtils::MakeMaker module.

ExtUtils::configPL is not a ``normal'' Perl extension. It does add or encapsulate functionality to your script, but it filters the script, replacing tags with items from the Config module, writing the resulting script to a new file.

The normal use for this module is to add the ``shebang'' line as the first line of a script.

    use ExtUtils::ConfigPL;
    <<--startperl-->> -w

would be replaced with:

    #/usr/local/bin/perl -w

(or where ever your perl executable is located.)

The use ExtUtils::configPL; line must be the first line in the script! Anything that comes before that line will not be in the filtered script.

This module is intended to work with ExtUtils::MakeMaker. You would create your script, as above, with the .PL extension, and add a PL_FILE option to the WriteMakefile() call (see the ExtUtils::MakeMaker manpage for more details.)

For example:

    'PL_FILES' => { 'foo.PL' => 'foo.pl' }

Creating the Makefile would create a rule that would call your script like:

    $(PERL) -I$(INST_ARCHLIB) -I$(INST_LIB) -I$(PERL_ARCHLIB) -I$(PERL_LIB)
        foo.PL foo.pl

although the line could be as simple as:

    perl foo.PL foo.pl

ExtUtils::configPL takes the first argument, and uses it as the name of filtered script, and will write the new script into it.

TAGS

Tags are use to mark the location that a substitution will be made. By default, tags are in the form of:

    <<--variable-->>

where the variable is one of the Config.pm variables.

The tag will be replaced anywhere it is found in the script. You can stop the substitution in a section of the script by surrounding the section like:

    no ExtUtils::configPL;
    ...
    # Nothing will be substituted.
    ...
    use ExtUtils::configPL;
    ...
    # Substituting is resumed.

The use and no lines above are removed from the filtered script so that, when you run the script, ExtUtils::configPL will not be re-ran.

OPTIONS

There are several options that control how ExtUtils::configPL operation. The options follow as a LIST only on the first use ExtUtils::configPL call. Any other use, and the options are ignored.

    use ExtUtils::configPL identifier => '\$Config\{(\w+)\}', mode => 0700;
identifier = 'regular expression'>
The identifier option allows you to change what the default tag looks like. By default, a tag will match the regular expression: 
    <<--(\w+)-->>

By creating your own custom tag identifer, you can change the default behavour.

    identifier => '\$Config\{(\w+)\}'

would recognize the Config.pm variable syntax.

There must be only one set of parenthesis. If you must include them, escape them with a backslash ('\').

mode = octal number>
This option is used to set the permissions list for the outputted script. By default, the permissions are set to 0755. Here is an example to set the permissions so only the owner has access to the script: 
    mode => 0700

head1 AUTHOR

Mark Pease <peasem@home.com>

SEE ALSO

the ExtUtils::MakeMaker manpage

 ExtUtils::configPL - Perl extension to automagiclly configure perl scripts