NAME

PPM::Make - Make a ppm package from a CPAN distribution

SYNOPSIS

my $ppm = PPM::Make->new( [options] );
$ppm->make_ppm();

DESCRIPTION

See the supplied make_ppm script for a command-line interface.

This module automates somewhat some of the steps needed to make a ppm (Perl Package Manager) package from a CPAN distribution. It attempts to fill in the ABSTRACT and AUTHOR attributes of Makefile.PL, if these are not supplied, and also uses pod2html to generate a set of html documentation. It also adjusts CODEBASE of package.ppd to reflect the generated package.tar.gz or package.zip archive. Such packages are suitable both for local installation via

C:\.cpan\build\package_src> ppm install

and for distribution via a repository.

OPTIONS

The available options accepted by the new constructor are

dist => value

If dist is not specified, it will be assumed that one is working inside an already unpacked source directory, and the ppm distribution will be built from there. A value for dist will be interpreted either as a CPAN-like source distribution to fetch and build, or as a module name, in which case CPAN.pm will be used to infer the corresponding distribution to grab.

binary => value

The value of binary is used in the BINARY_LOCATION attribute passed to perl Makefile.PL, and arises in setting the HREF attribute of the CODEBASE field in the ppd file.

arch_sub => boolean

Setting this option will insert the value of $Config{archname} (or the value of the arch option, if given) as a relative subdirectory in the HREF attribute of the CODEBASE field in the ppd file.

script => value

The value of script is used in the PPM_INSTALL_SCRIPT attribute passed to perl Makefile.PL, and arises in setting the value of the INSTALL field in the ppd file.

exec => value

The value of exec is used in the PPM_INSTALL_EXEC attribute passed to perl Makefile.PL, and arises in setting the EXEC attribute of the INSTALL field in the ppd file. This defaults to perl when a value of script is specified.

zip => boolean

By default, a .tar.gz distribution will be built, if possible. Giving zip a true value forces a .zip distribution to be made.

force => boolean

If a blib/ directory is detected, it will be assumed that the distribution has already been made. Setting force to be a true value forces remaking the distribution.

ignore => boolean

If when building and testing a distribution, failure of any supplied tests will be treated as a fatal error. Setting ignore to a true value causes failed tests to just issue a warning.

os => value

If specified, this value will be used instead of the default for the NAME attribute of the OS field of the ppd file.

arch => value

If specified, this value will be used instead of the default for the NAME attribute of the ARCHITECTURE field of the ppd file.

STEPS

The steps to make the PPM distribution are as follows.

determine available programs

For building and making the distribution, certain programs will be needed. For unpacking and making .tar.gz files, either Archive::Tar and Compress::Zlib must be installed, or a tar and gzip program must be available. For unpacking and making .zip archives, either Archive::Zip must be present, or a zip and unzip program must be available. Finally, a make program must be present.

fetch and unpack the distribution

If dist is specified, the corresponding file is fetched (by LWP::Simple, if a URL is specified). If dist appears to be a module name, the associated distribution is determined by CPAN.pm. The distribution is then unpacked.

build the distribution

If needed, or if specied by the force option, the distribution is built by the usual

C:\.cpan\build\package_src> perl Makefile.PL
C:\.cpan\build\package_src> nmake
C:\.cpan\build\package_src> nmake test

procedure. A failure in any of the tests will be considered fatal unless the ignore option is used. Additional arguments to these commands present in either CPAN::Config or present in the binary option to specify BINARY_LOCATION in Makefile.PL will be added.

parse Makefile.PL

Some information contained in the WriteMakefile attributes of Makefile.PL is then extracted.

parse Makefile

If certain information in Makefile.PL can't be extracted, Makefile is tried.

determining the ABSTRACT

If an ABSTRACT or ABSTRACT_FROM attribute in Makefile.PL is not given, an attempt is made to extract an abstract from the pod documentation of likely files.

determining the AUTHOR

If an AUTHOR attribute in Makefile.PL is not given, an attempt is made to get the author information using CPAN.pm.

HTML documentation

pod2html is used to generate a set of html documentation. This is placed under the blib/html/site/lib/ subdirectory, which ppm install will install into the user's html tree.

Make the PPM distribution

A distribution file based on the contents of the blib/ directory is then made. If possible, this will be a .tar.gz file, unless suitable software isn't available or if the zip option is used, in which case a .zip archive is made, if possible.

adjust the PPD file

The package_name.ppd file generated by nmake ppd will be edited appropriately. This includes filling in the ABSTRACT and AUTHOR fields, if needed and possible, and also filling in the CODEBASE field with the name of the generated archive file. This will incorporate a possible binary option used to specify the HREF attribute of the CODEBASE field. Two routines are used in doing this - parse_ppd, for parsing the ppd file, and print_ppd, for generating the modified file.

REQUIREMENTS

As well as the needed software for unpacking and making .tar.gz and .zip archives, and a make program, it is assumed in this that CPAN.pm is available and already configured, either site-wide or through a user's $HOME/.cpan/CPAN/MyConfig.pm.

Although the examples given above had a Win32 flavour, like PPM, no assumptions on the operating system are made in the module.

COPYRIGHT

This program is copyright, 2002, by Randy Kobes <randy@theoryx5.uwinnipeg.ca>. It is distributed under the same terms as Perl itself.

SEE ALSO

make_ppm, and PPM.