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 can be given as some combination of key/value pairs passed to the new() constructor (described below) and those specified in a configuration file. This file can either be that given by the value of the PPM_CFG environment variable or, if not set, a file called .ppmcfg at the top-level directory (on Win32) or under HOME (on Unix).

The configuration file is of an INI type. If a section default is specified as

  [ default ]
  option1 = value1
  option2 = value2

these values will be used as the default. Architecture-specific values may be specified within their own section:

  [ MSWin32-x86-multi-thread-5.8 ]
  option1 = new_value1
  option3 = value3

In this case, an architecture specified as MSWin32-x86-multi-thread-5.8 within PPM::Make will have option1 = new_value1, option2 = value2, and option3 = value3, while any other architecture will have option1 = value1 and option2 = value2. Options specified within the configuration file can be overridden by passing the option into the new() method of PPM::Make.

Valid options that may be specified within the configuration file are those of PPM::Make, described below. For the program and upload options (which take hash references), the keys (make, zip, unzip, tar, gzip), or (ppd, ar, host, user, passwd), respectively, should be specified. For binary options, a value of yes|on in the configuration file will be interpreted as true, while no|off will be interpreted as false.

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. If this begins with http:// or ftp://, so that the script is assumed external, this will be used as the HREF attribute for INSTALL.
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.
add => \@files: The specified array reference contains a list of files outside of the blib directory to be added to the archive.
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 this option specified, the value, if present, will be used instead of the default for the NAME attribute of the OS field of the ppd file. If a value of an empty string is given, the OS field will not be included in the ppd file.
arch => value: If this option is specified, the value, if present, will be used instead of the default for the NAME attribute of the ARCHITECTURE field of the ppd file. If a value of an empty string is given, the ARCHITECTURE field will not be included in the ppd file.
install => boolean: If specified, the ppm utility will be used to install the module.
remove => boolean: If specified, the directory used to build the ppm distribution (with the dist option) will be removed after a successful install.
program => { p1 => '/path/to/q1', p2 => '/path/to/q2', ...}: This option specifies that /path/to/q1 should be used for program p1, etc., rather than the ones PPM::Make finds. The programs specified can be one of tar, gzip, zip, unzip, or make.
as => boolean: Beginning with Perl-5.8, Activestate adds the Perl version number to the NAME of the ARCHITECTURE tag in the ppd file. This option, which is true by default, will make a ppd file compatible with this practice.
vs => boolean: This option, if enabled, will add a version string (based on the VERSION reported in the ppd file) to the ppd and archive filenames.
upload => {key1 => val1, key2 => val2, ...}: If given, this option will copy the ppd and archive files to the specified locations. The available options are

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.

install the distribution

If the install option is specified, the ppm utility, if available, will be used to install the distribution. The clean option, if specified, will remove the build directory and the distribution file for a distribution specified with the dist option.

upload the ppm files

If the upload option is specified, the ppd and archive files will be copied to the given locations.

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.