/ 
PPM-Make-0.9904
River stage zero No dependents
/ PPM::Make

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). If the no_cfg argument is passed into new(), this file will be ignored.

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 that take multiple values, such as reps, can be specified as

  reps = <<END
http://theoryx5.uwinnipeg.ca/ppms/
http://ppm.activestate.com/PPMPackages/5.8-windows/
END

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

no_cfg => 1

If specified, do not attempt to read a .ppmcfg configuration file.

no_html => 1

If specified, do not build the html documentation.

no_ppm4 => 1

If specified, do not add ppm4 extensions to the ppd file.

no_remote_lookup => 1

If specified, do not consult remote databases nor CPAN.pm for information not contained within the files of the distribution.

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.

no_case => boolean

If no_case is specified, a case-insensitive search of a module name will be performed.

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

skip => boolean

If this option is true, the tests when building a distribution won't be run.

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.

remove => boolean

If specified, the directory used to build the ppm distribution (with the dist option) will be removed after a successful install.

zipdist => boolean

If enabled, this option will create a zip file archive.zip consisting of the archive.ppd ppd file and the archive.tar.gz archive file, suitable for local installations. A short README file giving the command for installation is also included.

cpan => boolean

If specified, a distribution will be made using make dist which will include the ppd and archive file.

reps => \@repositories

This specifies a list of repositories to search for when making a bundle file with PPM::Make::Bundle.

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.

no_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 will make a ppd file without 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.

vsr => boolean

This option, if enabled, will add a version string (based on the VERSION reported in the ppd file) to the archive filename.

vsp => boolean

This option, if enabled, will add a version string (based on the VERSION reported in the ppd file) to the ppd filename.

upload => {key1 => val1, key2 => val2, ...}

If given, this option will copy the ppd and archive files to the specified locations. The available options are

ppd => $path_to_ppd_files

This is the location where the ppd file should be placed, and must be given as an absolute pathname.

ar => $path_to_archive_files

This is the location where the archive file should be placed. This may either be an absolute pathname or a relative one, in which case it is interpreted to be relative to that specified by ppd. If this is not given, and yet ppd is specified, then this defaults, first of all, to the value of arch_sub, if given, or else to the value of ppd.

zip => $path_to_zip_file

This is the location where the zipped file created with the --zipdist options should be placed. This may either be an absolute pathname or a relative one, in which case it is interpreted to be relative to that specified by ppd. If this is not given, but ppd is specified, this will default to the value of ppd.

bundle => $path_to_bundles

This is the location where the bundle file created with PPM::Make::Bundle should be placed. This may either be an absolute pathname or a relative one, in which case it is interpreted to be relative to that specified by ppd. If this is not given, but ppd is specified, this will default to the value of ppd.

host => $hostname

If specified, an ftp transfer to the specified host is done, with ppd and ar as described above.

user => $username

This specifies the user name to login as when transferring via ftp.

passwd => $passwd

This is the associated password to use for user

no_upload => 1

This option instructs upload to be ignored (used by PPM::Make::Bundle)

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. This is done through the fetch_file method, which fetches a file, and if successful, returns the stored filename. If the file is specified beginning with http:// or ftp://:

my $fetch = 'http://my.server/my_file.tar.gz';
my $filename = $obj->fetch_file($fetch);

will grab this file directly. Otherwise, if the file is specified with an absolute path name, has an extension \.(tar\.gz|tgz|tar\.Z|zip), and if the file exists locally, it will use that; otherwise, it will assume this is a CPAN distribution and grab it from a CPAN mirror:

my $dist = 'A/AB/ABC/file.tar.gz';
my $filename = $obj->fetch_file($dist);

which assumes the file lives under $CPAN/authors/id/. If neither of the above are satisfied, it will assume this is, first of all, a module name, and if not found, a distribution name, and if found, will fetch the corresponding CPAN distribution.

my $mod = 'Net::FTP';
my $filename = $obj->fetch_file($mod);

Assuming this succeeds, 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.

determining Bundle information

If the distribution is a Bundle, extract the prerequisites from the associated module for insertion in the ppd file.

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.

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.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc PPM::Make

You can also look for information at:

COPYRIGHT

This program is copyright, 2003, 2006, 2008 by Randy Kobes <r.kobes@uwinnipeg.ca>. It is distributed under the same terms as Perl itself.

CURRENT MAINTAINER

Kenichi Ishigaki <ishigaki@cpan.org>

SEE ALSO

make_ppm for a command-line interface for making ppm packages, ppm_install for a command line interface for installing CPAN packages via ppm, PPM::Make::Install, and PPM.