NAME

cpan2rpm - A Perl module packager

SYNOPSIS

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, directories, urls and CPAN module names. Install this package if you want to create RPMs out of Perl modules.

DESCRIPTION

cpan2rpm [options] <distribution>

The syntax for cpan2rpm requires a single distribution name, which can take one of four different forms:

1) a CPAN module name (e.g. XML::Simple) - When a module name is passed, the script will "walk" search.cpan.org to determine the latest distribution. If an exact match is not found, the CPAN module is used to make this determination. If you have not yet configured this module, please refer to the REQUIREMENTS section below for further instructions.

2) a URL (both http:// and ftp:// style locators will work) - In this and the above case, an automatic download of the needed tarball is performed (see notes for how). The tarball is deposited in the SOURCES directory.

3) a path to a tarball (e.g. /tmp/XML-Simple-1.05.tar.gz) - In this case, the tarball indicated gets copied to the SOURCES directory.

4) a directory path - The directory specified must contain a Makefile.PL. If the user intends to build a package from a directory (i.e. user does NOT specify --spec-only), the commands:

perl Makefile.PL
make
make dist

will be performed in that directory in order to create the tarball necessary for package creation.

NOTES

At present the script will handle .tar.gz, .tgz, .bz2 and .zip tarballs but each of these types requires the appropriate decompression programs installed on the system.

Spec files 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 typically sufficient to provide only the distribution name.

OPTIONS

The distribution name may be preceded by a number of optional arguments which modify the behaviour of the script. These options are grouped into three main categories as follows:

SPEC Options

The following options control the contents of the specification file generated. They come in four flavours as follows:

Simple Tags

These represent all tags which get inserted in the package with single values. The option may be used on the command line only once.

--name=string-value

This option corresponds to the Name tag in the spec file. As is customary with Perl RPMs, 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

--no-prfx

Even though this script is meant to build RPM packages from CPAN modules, it may be used on a more generic basis, thus the perl- prefix in a package may be undesirable. As an example, cpan2rpm generates itself but is not called perl-cpan2rpm. This option suppresses the aforementioned prefix in the package name.

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

--version=float-value

The script determines the version number of the module by consulting the Makefile.PL's VERSION or VERSION_FROM fields. If neither is specified, it parses the tarball name. Note: If you're looking to get the version of cpan2rpm itself, see the -V option.

--release=integer-value

The package release number. Defaults to 1.

--epoch=integer-value

By default, this tag is not written to the spec file. Enter a value here when needed.

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

--distribution=string-value

This key overrides the %{distribution} tag as defined in the macros files. There is no default for this tag and will be left out unless specified.

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

--group=string-value

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

--url=string-value

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

--buildarch=string-value

Allows specification of an architecture for building the RPM. Currently defaults to the %_arch macro from rpm.

--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}.

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

Aggregate Tags

These represent tags which may be repeated in the spec file. With all of the following, users may either specify a single option with a comma-delimited string of values, or multiple options, each with a single value.

exempli gratia

--requires="rpm, rpm-build" --requires="rpm" --requires="rpm-build"

--provides=string-value

Indicates that a package is provided by the module being built. RPM will generate an appropriate list of provide 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 --provides 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.

--buildrequires=string-value

This option indicates dependencies at build time.

--patch=string-value

Allows for specifying patch files to be inserted into the spec file and applied when building the source.

--doc=string-value

This option may be used to add values to the %doc line in the spec's %files section. By default, cpan2rpm examines the contents of a tarball, using a regular expression to pick up files it recognises as belonging to the /usr/share/doc directory. If your module contains files cpan2rpm does not recognise, they may be added with this option.

Additionally, the user may replace the calculated list by providing values prepended with an equal sign. In the following example, ONLY the Changes file is added to the list, dismissing any files found by the script:

--doc "=Changes"

Section options

These represent tags which may be repeated in the spec file. Users may specify these either with a single option and a comma-delimited string of values, or by repeating the option, each with a single value.

--prologue=<section>:<code>

This option allows the user to insert arbitrary code at the top of a given section of the spec file. The section is named in the value passed to the option as the first word followed by a colon. At present, the following sections are supported: prep, build, install, clean, changelog.

--epilogue=<section>:<code>

As with the previous option, this may be used to insert code at the end of a given section. This option also supports the tag and files sections which allow for the user to insert extra tags or files to the spec file.

exempli gratia

--epilogue="tag:epoch 1"

Building options

The following options control the package making process.

--spec-only

This option instructs the script to only generate a spec file and not build the RPM package.

--spec=path

This option allows the user to specify the full-path of the spec file to produce. By default, the specfile is placed in the SPECS directory and is named after the module with a .spec extension. Please note that cpan2rpm will overwrite existing files, so if you care about your current spec file, save it!

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

--find-provides=string-value

--find-requires=string-value

These two options allow for redefining the RPM macros of the same name in the spec file.

--tempdir=string-value

Specify a temporary working directory instead of utilizing File::Temp.

--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 originally intended.

--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 User may be required to use --force (see below) in conjuction with this option to build a fresh rpm before attempting to --install again.

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

Miscellaneous options

The options below perform functions not closely related to the quotidien process of building a package.

--mk-rpm-dirs=string-value

This option allows the non-root user to easily set up his account for building packages. The option requires a directory path where the RPMS, SPECS, etc. subdirectories will be created. These directories will contain the spec files, binaries and the source packages generated. Additionally the %_topdir macro will be defined in the ~/.rpmmacros file. If this file doesn't exist it will be created, if it does but does not contain a definition for this macro, it will be appended to it. Suggested value is ~/redhat but it's up to user.

Additionally, the script will create architecture directories i386, i686 and noarch and allows the user to pass --buildarch to also create a directory for that architecture.

--upgrade

Whenever a new version of this program becomes available, an automatic notification will be issued to the user of this fact. The user may then choose to upgrade via this option. The option takes no parameters.

--no-upgrade-chk|-U

During version checks, the script will time out within 5 seconds if the arix.com server is unavailable (when working offline or if the server is down). Should the 5 seconds become annoying, users may pass this option to skip the version check.

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

-V

This option displays the version number of cpan2rpm itself.

-D

This option runs cpan2rpm in the Perl debugger. Useful for anyone willing to dig on my behalf.

REQUIREMENTS

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

Additionally, the Perl package will be needed :) and the CPAN module (which is bundled with the Perl distribution) will need to be configured. To configure CPAN (CPAN.pm or CPAN/MyConfig.pm) use the following:

perl -MCPAN -e shell

For further information please refer to the CPAN manpage.

SUPPORTED PLATFORMS

At present, cpan2rpm has been tested and is known to work under the following environments:

Operating Systems

The script has been tested with Linux RedHat 6.1, 6.2, 7.0, 7.2, 7.3 and 8.0 and SuSE 8.1. Rumour has it it's been tested on Solaris as well but I don't know for sure. See README.redhat6 for 6.x issues to be aware of.

Perl

The script is known to work with Perl versions 5.005_03, 5.6.0, 5.6.1 and 5.8.0.

ExtUtils::MakeMaker

This module is used for making and installing the CPAN modules. However many of MakeMaker's versions are broken and incompatible with other versions. For that reason, cpan2rpm works well with versions < 5.91 and > 6.05 but in between it requires an upgrade.

Redhat Package Manager

The RPM system has undergone a lot of change. At present, cpan2rpm runs on version 4.0.4-7x but requires certain special attention (see README for more information). Earlier versions of RPM are borked in various ways and are not currently supported, though on SuSE version 3.0.6 appears to work.

If you are running on a platform not listed above, do drop us a note and let us know!

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.

SUPPORT/BUGS/TODO

For help and thank you notes, e-mail the author directly. To review known issues, report a new bug, submit a patch, or add to our wishlist, please visit:

http://rt.cpan.org/NoAuth/Bugs.html?Dist=cpan2rpm

AVAILABILITY

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.187 2003/02/21 04:54:06 ekkis Exp $

cpanm cpan2rpm

perl -MCPAN -e shell
install cpan2rpm