Michael De La Rue > makerpm > makerpm

Download:
makerpm-0.409.tar.gz

Annotate this POD

View/Report Bugs
Source  

NAME ^

makerpm - Build binary distributions of Perl packages

SYNOPSIS ^

Create a SPECS file:

  makerpm --specs --source=<package>-<version>.tar.gz \
          --copyright="GPL or Artistic"

Apply the SPECS file (which in turn uses makerpm.pl):

  rpm -ba <package>-<version>.spec

Create a PPM and a PPD file:

  makerpm --ppm --source=<package>-<version>.tar.gz

DESCRIPTION ^

The makerpm script is designed for creating binary distributions of Perl packages, for example RPM packages (Linux) or PPM files (Windows, running ActivePerl).

Creating RPM packages

To create a new binary and source RPM, from a perl tardist which has the standard perl naming scheme you just run

  makerpm <package-file-name>

And it should automagically do everything right including actually building the rpm. Please note, though, that that mode is new and I will be loading all reasonable features onto it so what works now might break later or, hopefully, the other way round.

Note, however, that you should at least look at the --copyright option below if you are going to distribute the perl package.

Taking more control

To just create a spec file which you can later use to build a new binary and source RPM, you typically store the tar.gz file in /usr/src/redhat/SOURCES (/usr/src/packages/SOURCES in case of SuSE) and do a

  makerpm --specs --source=<package>-<version>.tar.gz

This will create a SPECS file in /usr/src/redhat/SPECS (/usr/src/packages/SOURCES in case of SuSE) which you can use with

  rpmbuild -ba /usr/src/redhat/SPECS/<package>-<version>.spec

If the default behaviour is fine for you, that will do. Otherwise see the list of options below.

Creating PPM packages

**** I don't know if this works and can't support it - mikedlr *****

A PPM package consists of two files: The PPD (Perl Package description) file which contains XML source describing the package details and the PPM file which is nothing else than the archived blib directory.

You can create the package with

  makerpm --ppm -E -source=<package>-<version>.tar.gz

**** this feature will probably be removed soon!!! contact me if you use it!!!*****

Command Line Options

There are many command line options. For the most part you don't have to use them since makerpm will do the right thing. You should at least consider setting --copyright however.

Here is a full list:

--noauto-desc

Turn off automatic building of the description field. See full description below.

XS=item --build

**** this is an internal function DO NOT USE IT ANY MORE *****

Compile the perl package.

**** this feature will probably be removed soon!!! contact me if you use it!!!*****

--build-root=<dir>

Installation of the Perl package occurs into a separate directory, the build root directory. For example, a package DBI 1.07 could be installed into /var/tmp/DBI-1.07. Binaries are installed into $build_root/usr/bin rather than /usr/bin, man pages in $build_root/usr/man and so on.

The idea is making the build process really reproducible and building the package without destroying an existing installation.

You don't need to supply a build root directory, a default name is choosen.

--built-dir=<directory>

By default, even when just making a spec file, makerpm extracts and builds the package in order to get information from it. If the package has already been built somewhere then this option allows us to just use the given directory with no modification needed. You must ensure yourself that the directory contains a completely built package otherwise things could go horribl wrong.

--copyright=<msg>

Set the packages copyright message. The default is

  Probably the same terms as perl.  Check.

You are suggested to change this to match the actual package copyright. Code to automatically check licenses would be appreciated.

--nochown

Setting --nochown will stop makerpm from trying to change the ownership of files which means that it can be run as any user. This is now the defautlt unless running as root.

--data-dir=<directory>

The directory <directory>/<package-name> contains data for the package in files in there. See below.

--debug

Turns on debugging mode. Debugging mode prevents most things from really being done and implies verbose mode.

--desc-file=<file>

Uses the file given as the description field for the RPM.

--find-requires

When writing the spec file this option will write lines to use the special perl find-requires and find-provides programs which will then automatically generate dependancies between different perl rpms. This is automatic with RPM version 4 so you should never need to use this option.

--help

Print the usage message and exit.

--install

**** this is a deprecated internal function DO NOT USE IT ANY MORE *****

Install the sources, typically by running

        make install

Installation doesn't occur into the final destination. Instead a so-called buildroot directory (for example /var/tmp/build-root) is created and installation is adapted relative to that directory. See the --build-root option for details.

**** this feature will probably be removed soon!!! contact me if you use it!!!*****

--make=<path>

Set path of the make binary; defaults to the location read from Perl's Config module. Config(3).

--makeopts=<opts>

Set options for running "make" and "make install"; defaults to none.

--makemakeropts=<opts>

If you need certain options for running "perl Makefile.PL", this is your friend. By default no options are set.

N.B. New in makerpm2. To set multiple options this should be called multiple times. Whitespace included in the argument is passed through intact.

In order to get a module to work for multiple different versions of perl, (in several different versions of RedHat, for example), you should consider using

  "--makemakeropts=LIB=/usr/lib/perl5/site_perl"

But don't do that if you are packaging a perl module with binary parts.

--makeperlopts=<opts>

If you need to send certain options to the perl when running "perl Makefile.PL", this is your friend. By default no options are set.

These are set before Makefile.PL is named on the command line. It is possible also to run scripts etc. using this.

--mode=<mode>

**** I don't know if PPM mode works and can't support it - mikedlr *****

Set build mode, for example RPM or PPM. By default the build mode is read from the script name: If you invoke it as makerpm, then RPM mode is choosen. When running as makeppm, then PPM mode is enabled.

**** this feature will probably be removed soon!!! contact me if you use it!!!*****

--noname-prefix

With this option the package will be named without the prefix perl. This instead of Getopt::YAGO becoming perl-Getopt-YAGO, it will become simply Getopt-YAGO.

--package-name=<name>
--package-version=<version>

Set the package name and version. These options are required for --build and --install.

--ppm
--ppm-ppdfile
--ppm-ppmfile

**** I don't know if this works and can't support it - mikedlr *****

Create PPM related files. See creating PPD files above.

**** this feature will probably be removed soon!!! contact me if you use it!!!*****

--prep

**** this is a deprecated internal function DO NOT USE IT ANY MORE *****

Extract the sources and prepare the source directory.

--requre=<package name>

Add the name of a package to the requires list for RPM

--rpm-base-dir=<dir>
--rpm-build-dir=<dir>
--rpm-source-dir=<dir>
--rpm-specs-dir=<dir>

Sets certain directory names related to RPM mode, defaults to /usr/src/redhat (or /usr/src/packages on SuSE Linux) $topdir/BUILD, $topdir/SOURCES and $topdir/SPECS.

--rpm-group=<group>

Sets the RPM group; defaults to Development/Languages/Perl.

--rpm-version=<number>

Forces the makerpm to assume the given RPM version, writing a spec file for it as appropriate

--setup-dir=<dir>

Name of setup directory; defaults to <package>-<version>. The setup directory is the name of the directory that is created by extracting the sources. Example: DBI-1.07.

--source=<file>

Source file name; used to determine defaults for --package-name and --package-version. This option is required for --specs and --prep.

--summary=<msg>

Summary line; defaults to "The Perl package <name>".

--verbose

Turn on verbose mode. Lots of debugging messages are emitted.

--version

Print version string and exit.

INFLUENCING THE RPM WITH CONFIGURATION Files ^

By putting configuration files inside the module or in a given directory it is possible to influence the building of the package. This is currently only implemented for RPM, but could be extended to other formats..

When it is extended to other formats, I'd expect the current mechanism to change a little. See below.

the pkg-data-general directory

This is currently not implemented. Once I get a directory name reservation within the module directory it will be done.

The plan is that in the directory will contain those configuration values which can be shared between different package formats. Typical of this would be the description.

Currently I'm not clear about what else can be shared. Possibly the documentation list?

the pkg-data-XXX directory

If the module contains a directory pkg-data-rpm in the main directory of the distribution then files from there are used for package information. This is the best way for authors of perl modules to make their module easy to automatically convert into a fully featured RPM.

an override file

In order to provide your own descriptions of certain RPMs, you can put a file with the name of the module into a specified directory. This will then be used in the description field exactly as it is. This file will override all other possibilities since we assume that the package builder could delete the override file if wanted. Where there turns out to be an pkg-data-XXX/description as well as a description we give a warning.

files supported

AUTOMATIC FUNCTIONS ^

If no other source of a description is given then makerpm tries to automatically create a description from files contained in the perl module. You can turn this off using the --noauto-desc command line option. If automatic description finding fails or is turned off, we just use our normal summary line

   The Perl package XXXX
override files

Before considering automatic description discovery, the configuration files described above. If found the file description is used verbatim in the description field. This means that authors can provide a good description themselves and that if the automatic mechanisms fail, they can be overridden on an occasional basis whilst stil working for the other modules being built.

the README file

In most modules the primary source of the description is the README file. In most cases, if it exists this should be a good guess.

the DESCRIPTION in a module

If a module can be found which seems to have a reasonable name or is the only perl module which is found in the package then the DESCRIPTION section of the POD documentation will be extracted and used as the RPM description.

HANDLING RPM VERSIONS ^

Since the format of the RPM spec file has changed in the past and will probably change in the future, there must be some handling of the version of RPM. In the normal case, makerpm runs rpm --version and examines the output. This can be overridden by using the --rpm-version option to makerpm.

Currently only RPM version 2 up to 4 are fully supported. Earlier versions should cause an abort. We assume that newer versions of RPM will attempt to keep compatibility with current versions so we proceed with building the spec file, giving only a warning.

When later versions are verified/made correct, the program should be updated so that it doesn't give a warning. As always, it is up to the user to verify that makerpm runs succesfully :-)

EXCLUDING FILES ^

Sometimes there is a clash between two different perl distribution packages about the modules included. This happens, for example, when one module from a package becomes standard but the others aren't.

In this case the solution is to build the package as normal, but to exclude those extensions..

INSTALLATION ^

Before using this script, you need to install the required packages:

  C<File::Spec>

If you are using Perl 5.00502 or later, then this package is already part of your Perl installation. It is recommended to use the

  C<Archive::Tar>
  C<Compress::Zlib>

packages, if possible.

All of these packages are available on any CPAN mirror, for example

  ftp://ftp.funet.fi/pub/languages/perl/CPAN/modules/by-module

To install a package, fetch the corresponding distribution file, for example

  Archive/Archive-Tar-0.21.tar.gz

extract it with

  gzip -cd Archive-Tar-0.21.tar.gz

and install it with

  cd Archive-Tar-0.21
  perl Makefile.PL
  make
  make test
  make install

Alternatively you might try automatic installation via the CPAN module:

  cpan          (until Perl 5.00503 you need: perl -MCPAN -e shell)
  install Archive::Tar
  install Compress::Zlib
  install File::Spec  (only with Perl 5.004 or lower)

AUTHOR AND COPYRIGHT ^

This script is Copyright (C) 1999

        Jochen Wiedmann
        Am Eisteich 9
        72555 Metzingen
        Germany

        E-Mail: joe@ispsoft.de

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README.

And Copyright (C) 2001 Michael De La Rue with the same terms.

CPAN ^

This file is available as a CPAN script. The following subsections are for CPAN's automatic link generation and not for humans. You can safely ignore them.

SCRIPT CATEGORIES

UNIX/System_administration

README

This script can be used to build RPM or PPM packages automatically.

PREREQUISITES

This script requires the File::Spec package.

TODO ^

-

make a set of test cases

-

Add handling of configuration files: suggest anything in /etc/ is automatically a config file.

-

When we use POD files to generate the description field of the RPM we should process the POD directives.

-

Handling of prerequisites by reading PREREQ_PM from the Makefile

-

Make package relocatable

-

Research the best heuristic for generating descriptions from Perl modules.

THE FUTURE ^

The current configuration system is designed by Michael. Two alternative mechanisms have been proposed.

a

Using a single file containing configuration in a perl hash.

b

Using an XML file.

Suggestion b is currently ruled out since XML support is not included in the default installation of perl. As a build tool, MakeRPM should rely on nothing which isn't available by default.

Suggestion a seems to be quite resonable. It has the advantage that the mechanism for inheriting configuration from one package format to another is obvious.

I currently prefer the implementation given with directories.

Anyway, the summary of attributes I think the system should have is as follows.

I'd definitely consider any mechanism which fits this. The easiest way to get this change made is to send me the patch.

It seems to me that the name of the configuration directory must be accepted by "the perl community" because it would then be impossible to use a directory of the same name for other reasons. Since this hasn't yet been agreed with "the perl community" it is subject to change. If a future version does change this then at the very least a warning will be issued when ignoring this directory. More likely some simple auto-detection will be used.

MAINTAINANCE STATUS ^

As a temporary measure, I, Michael, will attempt to maintain this software for a short while. My aim is to get a full build of all of the RPMs I need for support of software I'm writing widely available.

If you have some change to make, please send it to me in an email at the address <mikedlr@tardis.ed.ac.uk>. This is a pretty public address and so gets junkmail so doesn't get answered very well...

If I don't respond within two weeks, feel free to increment the version number and release it onto CPAN.

CHANGES ^

2004-02-08 Michael De La Rue <mikedlr@tardis.ed.ac.uk>

      * lots of improved diagnostics
      * handling of Makefile.PM which returns undef
      * new default "do everything" mode 

2004-01-05 Michael De La Rue <mikedlr@tardis.ed.ac.uk> + Ed Avis.

      * --spec option is now default 
      * --auto-doc is now default
      * --nochown is default in the case of non root build
      * --defattr is now the default in all cases
      * clearly deprecate ppm mode 
      * clearly deprecate prep/build/install modes
      * multiple small cleanups

2003-08-22 Michael De La Rue <mikedlr@tardis.ed.ac.uk>

      * removed --recursive option
      * built a proper test suite
      * fixes to get tests to complete

2003-07-09 Michael De La Rue <mikedlr@tardis.ed.ac.uk>

      * changes from Ed Avis added - protection against non working
        Archive::Tar, extra file checks

2003-06-12 Michael De La Rue <mikedlr@tardis.ed.ac.uk>

      * force LANG=C during build for RH9.. we will reconsider this in
        future, but it's likely that this is a safe way
      * fix (apparently old) bugs in various options 

2001-06-01 Michael De La Rue <mikedlr@tardis.ed.ac.uk>

      * add support for find_provides.perl and find_requires.perl
        since RedHat has started using them.
      * fix (apparently old) bugs in various options 

2001-02-11 Michael De La Rue <mikedlr@tardis.ed.ac.uk>

      * change to only adjust interpreter paths that contain 'perl'.
        This allows the user to create e.g. shell scripts.

2001-01-26 Michael De La Rue <mikedlr@tardis.ed.ac.uk>

       * ignore any perllocal.pod files (new version of Perl?)
       * updates to build on RPM 4.
          - convert man page filenames to be gzip compressed.

2001-01-25 Michael De La Rue <mikedlr@tardis.ed.ac.uk>

       * Change of RPM version handling so that we can cope with
         RPM version 4 and up.

2001-01-20 Michael De La Rue <mikedlr@tardis.ed.ac.uk>

       * Changed defualt copyright to be a little clearer that
         the system doesn't actually check.
       * Added documentation collection.

2000-05-20 Michael De La Rue <mikedlr@tardis.ed.ac.uk>

       * Added support for descriptions
       * Added primitive support for automatically creating descriptions
       * Clearer help messages for bad options
       * made changelog formatting consistent with Jochen.
       * make messges come out of stderr so we see them before actions.
       * test that directory rmtrees take place (aim at non root use)

2000-01-02 Peter J. Braam <braam@redhat.com>

       * Added support for $ENV{RPM_SOURCE_DIR} and $ENV{RPM_BUILD_DIR}.
       * Added --nochown.

1999-12-16 Jochen Wiedmann <joe@ispsoft.de>

       * Added --ppm-noversion

1999-12-14 Jochen Wiedmann <joe@ispsoft.de>

       * Added PPM support

1999-12-10 Peter J. Braam <braam@redhat.com>

       * Fixed the $base_dir: correct naming is topdir and compute it
         from the rpm --showrc like the rest

1999-09-13 Jochen Wiedmann <joe@ispsoft.de>

      * Modes: Fixed the use of ||= instead of |=; thanks to Tim Potter,
        Tim Potter <Tim.Potter@anu.edu.au>
      * Now using %files -f <listfile>

1999-07-22 Jochen Wiedmann <joe@ispsoft.de>

      * Now falling back to use of "tar" and "gzip", if Archive::Tar and
        Compress::Zlib are not available.
      * Added --runtests, suggested by Seth Chaiklin <seth@pc126.psy.aau.dk>.

1999-07-09 Jochen Wiedmann <joe@ispsoft.de>

      * Now using 'rpm --showrc' to determine RPM's base dirs.

1999-07-01 Jochen Wiedmann <joe@ispsoft.de>

      * /usr/src/redhat was used rather than $Distribution::RPM::BASE_DIR.
      * The AdjustPaths function is now handling files zero size files
        properly.
      * An INSTALLATION section was added to the docs that describes
        the installation of prerequisites.
      * A warning for <HANDLE> being possibly "0" is now suppressed with
        Perl 5.004.

1999-05-24 Jochen Wiedmann <joe@ispsoft.de>

      * Added --perl-path and support for fixing startperl in scripts.
        Some authors don't know how to fix it. :-(

SEE ALSO ^

ExtUtils::MakeMaker(3), rpm(1), ppm(1)

syntax highlighting: