NAME

cpan2rpm - A Perl module packager

SYNOPSIS

cpan2rpm [options] <module>

This script generates an RPM package from a Perl module. It uses the standard RPM file structure and creates a spec file, a source RPM, and a binary, leaving these in their respective directories.

The script can operate on local files, urls and CPAN module names. Install this package if you want to create RPMs out of Perl modules.

DESCRIPTION

The syntax for cpan2rpm requires a single module name, which can take one of three different forms: 1) a CPAN module name (e.g. XML::Simple), 2) a URL (both http:// and ftp:// style locators will work), and 3) a local filename reference to a tarball (e.g. /tmp/XML-Simple-1.05.tar.gz). The module name may be preceded by a number of optional arguments which modify the behaviour of the script.

By default, the search.cpan.org website is "walked" to determine the latest tarball for the specified module. If an exact match is not found, the CPAN module is used to determine and download the module.

If you have not configured CPAN (CPAN.pm or CPAN/MyConfig.pm) you can configure it with the following:

perl -MCPAN -eshell

If the <module> passed is either a CPAN module name or a URL the script automatically does a download (when CPAN module names are specified, the latest distribution is used), putting it in the SOURCES directory. If <module> is given as a local filename, the tarball gets copied to the SOURCES directory. NOTE: at present the script will not handle .bz2 tarballs.

The spec file generated will generally assume header values as configured in the RPM macro files which are evaluated in the following order: /usr/lib/rpm/macros, /etc/rpm/macros and ~/.rpmmacros. Most of these headers can, however, be overridden through options. Whenever a header is neither configured in the RPM macro files nor is passed at the command line, the script will seek to calculate a proper value and supplies a default as stated for each option below. It is thus typicall sufficient to provide only the <module> name.

The options available are as follows:

--pkgname=string-value

The RPM package name. This is the Name header in the RPM's spec file. Please note that the string perl- will be prepended to any value passed here. If no value is supplied, the script will use the NAME field found in the module's Makefile.PL

--version=float-value

The script determines the version number of the module by parsing the tarball name.

--release=integer-value

The package release number. Defaults to 1.

--summary=string-value

A one-line description of the package. If left unspecified the script will use the module name, appending an abstract whenever available.

--description=string-value

This text describes the package/module. This value is picked up from the POD's Synopsis section in the module. Defaults to "None.".

--url=string-value

The home url for the package. Defaults to http://www.cpan.org.

--group=string-value

This is the RPM group. For further information on available groups please see your RPM documentation. Defaults to Applications/CPAN.

--author=string-value

This is the name and address of the person who authored the module. Typically it should be in the format: Name <e-mail-address>. If left unspecified, the script will attempt to extract it from the tarball's MakeMaker file, failing to build the package otherwise. There is no default for this option.

--packager=string-value

This is you (if you're packaging someone else's module). The string should be in the same format as for --author and defaults to: Arix International <cpan2rpm@arix.com> unless the RPM macro files provide a value.

--license=string-value

The license header specified in the spec file. This field is also sometimes referred to as Copyright, but License is a more suitable name and has become more common. Defaults to Artistic, Perl's own license.

--distribution=string-value

The script will use the %{distribution} tag defined in the RPM macros file. If this tag is not set, the script will attempt to determine the distribution name by looking at the /etc/issue file. If this file does not exist, the distribution will be left blank.

--buildarch=string-value

Allows specification of an architecture for building the RPM. Currently defaults to whatever matches $Config{config_args} =~ /-march=(\S+)/ from "use Config;".

--buildroot=string-value

Allows specifying a directory to use as a BuildRoot. Don't mess with this is you don't know what it is. Defaults to: %{_tmppath}/%{name}-%{version}.

--provides=string-value

Indicates that a package should be provided by the module being built. RPM will generate an appropriate list of provided dependencies and any passed here will be in addition to those calculated.

--requires=string-value

Indicates packages that should be required for installation. This option works precisely as --requires above.

--no-requires=string-value

Suppresses generation of a given required dependency. Sometimes authors create dependencies on modules the packager can't find, sometimes RPM generates spurious dependencies. This option allows the packager to arbitrarily supress a given requirement. The value may be a comma-separated list.

--req-scan-all

By default, the rpm-build requirements script scans all files in a tarball for requirements information. As this may on occasion generate requirements on the produced rpm that belong only to sample programs or other files not critical to the module being installed, we provide a patch the user may apply (included in this distribution as perl.req.patch) which causes dependencies to be harvested from only .pm files. When this patch is installed, this switch reverses the behaviour, causing cpan2rpm to scan all files as originall intended.

--spec-only

This option instructs the script to not build the RPM package but instead to only display the generated spec file on stdout.

--make-maker=string-value

This option allows passing a string to the MakeMaker process (i.e. perl Makefile.PL <your-arguments-here>)

--make=string-value

Arguments supplied here get passed directly to the make process.

--make-no-test

Use this option to suppress running a module's test suite during build.

--make-install=string-value

Allows user to supply arguments to the make install process.

--no-clean

By default, the system passes --clean to rpmbuild, thus removing the unpacked sources from the BUILD directory. This option suppresses that functionality.

--shadow-pure

Forces installation under installarchlib even if the module is pure perl. This is significant because it is first in the @INC search for module determination. This will not do any good for modules with XS code or those that are already installed into an architecture dependent path. This is most useful for those pure perl modules that come stock with the perl rpm itself (i.e. Test::Harness) but you wish to try another version without having to be forced to use "rpm --replacefiles" and destroying the old files. Using this option will allow both versions of the module to be installed, but the new version will just mask the old version later in the @INC. Additionally, the new man pages will mask the old man pages even though the man pages for both version will be installed. This option should only be used as a last resort to install a module when "conflicts" errors occur on rpm installation such as the following:

file from install of perl-Module-1.11-1 conflicts with file from package perl-5.x.x

Use may be required to use --force (see below) in conjuction with this option to build a fresh rpm before attempting to --install again.

--patch=string-value

This option allows specifying patch files to be inserted into the spec file and applied when building the source. Please note the option may be used multiple time to specify multiple patches.

--nopkgprfx

Suppresses prefixing the package name with the string perl-.

--force

By default the script will do as little work as possible i.e. if it has already previously retrieved a module from CPAN, it will not retrieve it again. If it has already generated a spec file it will not generate it again. This option allows the packager to force all actions, starting from scratch.

--install

Install the RPM after building it. If non-root user, you must have "sudo rpm" privileges to use this option.

--debug[=n]

This option produces debugging output. An optional integer increases the level of verbosity for this output. If no integer is given, 1 is assumed.

--help, -h

Displays a terse syntax message.

NOTES

This script requires that RPM be installed. Both rpm and rpm-build must be installed on the local machine. Please see the RPM documentation (man rpm) for further information.

Additionally, the Perl module will be needed :) and the CPAN module (which is bundled with the Perl distribution) will need to be configured. For further information please refer to the CPAN manpage.

TODO

For now, the list below is what's awaits my attention, but I'm happy to work on any feature requests you may have :)

1. should really have an /etc file + ~/.cpan2rpm

BUGS

Same goes for bugs.

AUTHOR

Erick Calder <ecalder@cpan.org>

ACKNOWLEDGEMENTS

The script was inspired by cpanflute which is distributed with the rpm-build package from RedHat. Many thanks to Robert Brown <bbb@cpan.org> for all his cool tricks, advice and patient support.

AVAILABILITY + SUPPORT

For help, comments or suggestions pleawe e-mail cpan2rpm@arix.com. To subscribe to an announcements mailing list address a blank message to the above address with subject header "subscribe" (or "unsubscribe" as need dictates).

The latest version of the tarball, RPM and SRPM may always be found at:

http://perl.arix.com/

LICENCE AND COPYRIGHT

This utility is free and distributed under GPL, the Gnu Public License.

$Id: cpan2rpm,v 2.17 2002/12/17 21:07:45 ekkis Exp $