Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

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

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


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 not build the html documentation.

no_ppm4 => 1
If specified, do not add ppm4 extensions to the ppd file.

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) =back

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.

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.


COPYRIGHT

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


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, the PPM::Make::Install manpage, and PPM.

The software needed to run the remote SOAP server used here for fetching author, module, and distribution information is available in the Cpan-Search-Lite project at http://sourceforge.net/projects/cpan-search/ as cgi-bin/ppminfo.cgi - see also the CPAN::Search::Lite manpage.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy