1CPAN2RPM(1) User Contributed Perl Documentation CPAN2RPM(1)
2
6 cpan2rpm - A Perl module packager
7
9 To download the tarball from CPAN and create an RPM package, its source
10 package and the specfile:
11 cpan2rpm Proc::Daemon /tmp/String-Canonical-1.2.tar.gz
13 To install from a URL:
15 cpan2rpm -i http://.../Proc-Daemon-0.03.tar.gz
17 To make a package out of the current directory (that contains a mod‐
19 ule):
20 cpan2rpm .
22 To create a list of packages stored in a file:
24 cpan2rpm -f module-list
26
28 This script generates an RPM package from a Perl module. It uses the
29 standard RPM file structure and creates a spec file, a source RPM, and
30 a binary, leaving these in their respective directories.
31 The script can operate on local files, directories, urls and CPAN mod‐
33 ule names. Install this package if you want to create RPMs out of Perl
34 modules.
35 The syntax for cpan2rpm supports multiple distribution names, which can
37 take one of four different forms:
38 1. a CPAN module name (e.g. XML::Simple) - When a module name is
40 passed, the script will "walk" search.cpan.org to determine the latest
41 distribution. If an exact match is not found, the CPAN module is used
42 to make this determination. If you have not yet configured this mod‐
43 ule, please refer to the REQUIREMENTS section below for further
44 instructions.
45 2. a URL (both http:// and ftp:// style locators will work) - In this
46 and the above case, an automatic download of the needed tarball is per‐
47 formed (see notes for how). The tarball is deposited in the SOURCES
48 directory.
49 3. a path to a tarball (e.g. /tmp/XML-Simple-1.05.tar.gz) - In this
50 case, the tarball indicated gets copied to the SOURCES directory.
51 4. a directory path - The directory specified must contain a Make‐
52 file.PL. If the user intends to build a package from a directory (i.e.
53 user does NOT specify --spec-only), the commands:
54 perl Makefile.PL
55 make
56 make dist
57 will be performed in that directory in order to create the tarball
59 necessary for package creation.
60
62 At present the script will handle .tar.gz, .tgz, .bz2 and .zip tarballs
63 but each of these types requires the appropriate decompression programs
64 installed on the system.
65 Spec files generated will generally assume header values as configured
67 in the RPM macro files which are evaluated in the following order:
68 /usr/lib/rpm/macros, /etc/rpm/macros and ~/.rpmmacros. Most of these
69 headers can, however, be overridden through options. Whenever a header
70 is neither configured in the RPM macro files nor is passed at the com‐
71 mand line, the script will seek to calculate a proper value and sup‐
72 plies a default as stated for each option below. It is thus typically
73 sufficient to provide only the distribution name.
74
76 The distribution name may be preceded by a number of optional arguments
77 which modify the behaviour of the script. These options are grouped
78 into three main categories as described below. Additionally, options
79 may be stored in a configuration file - see the CONFIGURATION FILE sec‐
80 tion below.
81 SPEC Options
83 The following options control the contents of the specification file
85 generated. They come in four flavours as follows:
86 Simple Tags
88 These represent all tags which get inserted in the package with single
90 values. The option may be used on the command line only once.
91 --name="string-value"
93 This option corresponds to the Name tag in the spec file. As is
94 customary with Perl RPMs, the string "perl-" will be prepended to
95 any value passed here. If no value is supplied, the script will
96 use the NAME field found in the module's Makefile.PL
97 --no-prfx
99 Even though this script is meant to build RPM packages from CPAN
100 modules, it may be used on a more generic basis, thus the "perl-"
101 prefix in a package may be undesirable. As an example, cpan2rpm
102 generates itself but is not called "perl-cpan2rpm". This option
103 suppresses the aforementioned prefix in the package name.
104 --no-depchk
106 At times the user may want to package a module that depends on
107 other CPAN modules not presently installed. This is generally not
108 possible since cpan2rpm does an up-front check for modules listed
109 in the PREREQ_PM field of the Makefile.PL. This switch turns this
110 checking off so that the process may continue and implies the
111 --make-no-test since testing with missing module dependencies will
112 certainly fail.
113 --summary="string-value"
115 A one-line description of the package. If left unspecified the
116 script will use the module name, appending an abstract whenever
117 available.
118 --version="float-value"
120 The script determines the version number of the module by consult‐
121 ing the Makefile.PL's VERSION or VERSION_FROM fields. If neither
122 is specified, it parses the tarball name. Note: If you're looking
123 to get the version of cpan2rpm itself, see the -V option.
124 --release="integer-value"
126 The package release number. Defaults to 1. Allows alphanumerics.
127 --epoch="integer-value"
129 By default, this tag is not written to the spec file. Enter a
130 value here when needed.
131 --author="string-value"
133 This is the name and address of the person who authored the module.
134 Typically it should be in the format: Name <e-mail-address>. If
135 left unspecified, the script will attempt to extract it from the
136 tarball's MakeMaker file, failing to build the package otherwise.
137 There is no default for this option.
138 --packager="string-value"
140 This is you (if you're packaging someone else's module). The
141 string should be in the same format as for --author and defaults
142 to: "Arix International <cpan2rpm@arix.com>" unless the RPM macro
143 files provide a value.
144 --distribution="string-value"
146 This key overrides the %{distribution} tag as defined in the macros
147 files. There is no default for this tag and will be left out
148 unless specified.
149 --license="string-value"
151 The license header specified in the spec file. This field is also
152 sometimes referred to as Copyright, but License is a more suitable
153 name and has become more common. Defaults to "Artistic", Perl's
154 own license.
155 --group="string-value"
157 This is the RPM group. For further information on available groups
158 please see your RPM documentation. Defaults to "Applica‐
159 tions/CPAN".
160 --url="string-value"
162 The home url for the package. Defaults to http://www.cpan.org.
163 --buildarch="string-value"
165 The architecture for a package is determined by whether the tarball
166 includes files matching *.xs or *.c. If it does, %_arch macro from
167 rpm is used as the target architecture, otherwise noarch is used.
168 This value may be overridden with this parameter. Typically the
169 package build will be found in the RPMS directory, under the indi‐
170 cated architecture.
171 --buildroot="string-value"
173 Allows specifying a directory to use as a BuildRoot. Don't mess
174 with this is you don't know what it is. Defaults to: "%{_tmp‐
175 path}/%{name}-%{version}".
176 --defattr="-,root,root"
178 Upon installation of a package created with cpan2rpm, the files
179 installed are owned according to the contents of the %defattr tag
180 inserted into the %files section of the spec file. The value of
181 this tag may be passed using this switch and defaults to the value
182 shown above.
183 --description="string-value"
185 This text describes the package/module. This value is picked up
186 from the POD's Synopsis section in the module. Defaults to
187 "None.".
188 Aggregate Tags
190 These represent tags which may be repeated in the spec file. With all
192 of the following, users may either specify a single option with a
193 comma-delimited string of values, or multiple options, each with a sin‐
194 gle value.
195 exempli gratia
197 --requires="rpm, rpm-build"
199 --requires="rpm" --requires="rpm-build"
200 --provides="string-value"
202 Indicates that a package is provided by the module being built.
203 RPM will generate an appropriate list of provide dependencies and
204 any passed here will be in addition to those calculated.
205 --requires="string-value"
207 Indicates packages that should be required for installation. This
208 option works precisely as --provides above.
209 --no-requires="string-value"
211 Suppresses generation of a given required dependency. Sometimes
212 authors create dependencies on modules the packager can't find,
213 sometimes RPM generates spurious dependencies. This option allows
214 the packager to arbitrarily supress a given requirement.
215 --buildrequires="string-value"
217 This option indicates dependencies at build time.
218 --patch="string-value"
220 Allows for specifying patch files to be inserted into the spec file
221 and applied when building the source.
222 --define="name body"
224 Works much like the rpm --define syntax to define rpm macro ini‐
225 tializations. A comma-delimited list of macro definitions is not
226 supported, but ut may be used multiple times to define more than
227 one macro.
228 exempli gratia
230 --define="suidperl 1"
232 --define "usethreads 1"
233 --define admindir=/var/www/html/admin
234 --doc="string-value"
236 This option may be used to add values to the %doc line in the
237 spec's %files section. By default, cpan2rpm examines the contents
238 of a tarball, using a regular expression to pick up files it recog‐
239 nises as belonging to the /usr/share/doc directory. If your module
240 contains files cpan2rpm does not recognise, they may be added with
241 this option.
242 Additionally, the user may replace the calculated list by providing
244 values prepended with an equal sign. In the following example,
245 ONLY the "Changes" file is added to the list, dismissing any files
246 found by the script:
247 --doc "=Changes"
249 Section options
251 These represent tags which may be repeated in the spec file. Users may
253 specify these either with a single option and a comma-delimited string
254 of values, or by repeating the option, each with a single value.
255 --prologue="<section>:<code>"
257 This option allows the user to insert arbitrary code at the top of
258 a given section of the spec file. The section is named in the
259 value passed to the option as the first word followed by a colon.
260 At present, the following sections are supported: prep, build,
261 install, clean, changelog.
262 --epilogue="<section>:<code>"
264 As with the previous option, this may be used to insert code at the
265 end of a given section. This option also supports the tag and
266 files sections which allow for the user to insert extra tags or
267 files to the spec file.
268 exempli gratia
270 --epilogue="tag:epoch: 1"
272 Building options
274 The following options control the package making process.
276 --spec-only
278 This option instructs the script to only generate a spec file and
279 not build the RPM package.
280 --spec=path
282 This option allows the user to specify the full-path of the spec
283 file to produce. By default, the specfile is placed in the SPECS
284 directory and is named after the module with a .spec extension.
285 Please note that cpan2rpm will overwrite existing files, so if you
286 care about your current spec file, save it!
287 --make-maker="string-value"
289 This option allows passing a string to the MakeMaker process (i.e.
290 perl Makefile.PL <your-arguments-here>). At present there is no
291 support for passing parameters to Module::Build->new() - if this is
292 either possible or desired, please mail the author.
293 --make="string-value"
295 Arguments supplied here get passed directly to the make process.
296 (As with the above, no support is offered for Module::Build).
297 --make-no-test
299 Use this option to suppress running a module's test suite during
300 build.
301 --make-install="string-value"
303 Allows user to supply arguments to the make install process. (As
304 with the above, no support is offered for Module::Build).
305 --find-provides="string-value"
307 --find-requires="string-value"
308 These two options allow for redefining the RPM macros of the same
309 name in the spec file.
310 --tempdir="string-value"
312 Specify a temporary working directory instead of utilizing
313 File::Temp.
314 --req-scan-all
316 By default, the rpm-build requirements script scans all files in a
317 tarball for requirements information. As this may on occasion gen‐
318 erate requirements on the produced rpm that belong only to sample
319 programs or other files not critical to the module being installed,
320 we provide a patch the user may apply (included in this distribu‐
321 tion as perl.req.patch) which causes dependencies to be harvested
322 from only .pm files. When this patch is installed, this switch
323 reverses the behaviour, causing cpan2rpm to scan all files as orig‐
324 inally intended.
325 --no-clean
327 By default, the system passes --clean to rpmbuild, thus removing
328 the unpacked sources from the BUILD directory. This option sup‐
329 presses that functionality.
330 --shadow-pure
332 Forces installation under installarchlib even if the module is pure
333 perl. This is significant because it is first in the @INC search
334 for module determination. This will not do any good for modules
335 with XS code or those that are already installed into an architec‐
336 ture dependent path. This is most useful for those pure perl mod‐
337 ules that come stock with the perl rpm itself (i.e. Test::Harness)
338 but you wish to try another version without having to be forced to
339 use "rpm --replacefiles" and destroying the old files. Using this
340 option will allow both versions of the module to be installed, but
341 the new version will just mask the old version later in the @INC.
342 Additionally, the new man pages will mask the old man pages even
343 though the man pages for both version will be installed. This
344 option should only be used as a last resort to install a module
345 when "conflicts" errors occur on rpm installation such as the fol‐
346 lowing: "file from install of perl-Module-1.11-1 conflicts with
347 file from package perl-5.x.x" User may be required to use --force
348 (see below) in conjuction with this option to build a fresh rpm
349 before attempting to --install again.
350 --force
352 By default the script will do as little work as possible i.e. if it
353 has already previously retrieved a module from CPAN, it will not
354 retrieve it again. If it has already generated a spec file it will
355 not generate it again. This option allows the packager to force
356 all actions, starting from scratch.
357 --no-sign
359 Suppresses package signatures. By default, cpan2rpm will sign the
360 packages it generates IF the the RPM macros file has been config‐
361 ured to use signatures - this option prevents this behaviour. See
362 also the --sign-setup option below.
363 --install ⎪ -i
365 Install the RPM after building it. If non-root user, you must have
366 "sudo rpm" privileges to use this option.
367 Miscellaneous options
369 The options below perform functions not closely related to the quoti‐
371 dien process of building a package.
372 --fetch="string-value"
374 One of cpanplus, cpan or web, this parameter specifies which method
375 to use when retrieving a module from CPAN. Web retrievals are by
376 parsing the CPAN website and may be faster though more error prone.
377 To use either the CPAN or CPAN+ modules, these must be installed.
378 Default: web.
379 If your environment requires the use of a proxy, simply set the
381 environment variable as indicated below in (bash format):
382 export HTTP_PROXY=http://user:password@host.org:8080
384 --modules, -f ="string-value"
386 Lists of modules to be processed can be stored in a file. Pass
387 this parameter the name of your file. The file should contain the
388 name of each module in a single line and the modules can be speci‐
389 fied in any of their many forms (e.g. url, path to tarball, CPAN
390 module name, etc.). Comments (begining with #) will be ignore and
391 so will empty lines.
392 --mk-rpm-dirs="string-value"
394 This option allows the non-root user to easily set up his account
395 for building packages. The option requires a directory path where
396 the RPMS, SPECS, etc. subdirectories will be created. These direc‐
397 tories will contain the spec files, binaries and the source pack‐
398 ages generated. Additionally the %_topdir macro will be defined in
399 the ~/.rpmmacros file. If this file doesn't exist it will be cre‐
400 ated, if it does but does not contain a definition for this macro,
401 it will be appended to it. Suggested value is ~/rpm but it's up to
402 user.
403 Additionally, the script will create architecture directories i386,
405 i686 and noarch and allows the user to pass --buildarch to also
406 create a directory for that architecture.
407 --sign-setup=["type:user"]
409 This option sets up your RPM macros file to support the signing of
410 packages. The option may be passed a value consisting of the sig‐
411 nature type to use (currently only gpg and pgp are valid but con‐
412 sult the RPM man pages), a colon, and the user name to sign with.
413 If no value is passed "gpg" is used for the signature type and the
414 first key listed in the secure keyring is taken for signing.
415 Note: unless you know what you're doing, do not pass any arguments
417 to this option! Also, make sure not to pass a module name as an
418 argument.
419 To further tailor your macros file please refer to the GPG SIGNA‐
421 TURES section of the RPM man page.
422 --upgrade
424 Whenever a new version of this program becomes available, an auto‐
425 matic notification will be issued to the user of this fact. The
426 user may then choose to upgrade via this option. The option takes
427 no parameters.
428 --no-upgrade-chk⎪-U
430 During version checks, the script will time out within 5 seconds if
431 the arix.com server is unavailable (when working offline or if the
432 server is down). Should the 5 seconds become annoying, users may
433 pass this option to skip the version check.
434 --debug[=n]
436 This option produces debugging output. An optional integer
437 increases the level of verbosity for this output. If no integer is
438 given, 1 is assumed.
439 --help, -h
441 Displays a terse syntax message.
442 -V This option displays the version number of cpan2rpm itself.
444 -D This option runs cpan2rpm in the Perl debugger. Useful for anyone
446 willing to dig on my behalf.
447
449 In addition to reading options from the command line, cpan2rpm will
450 slurp the configuration file ~/.cpan2rpm, if it exists. Please note
451 that for this functionality to work, the module Getopt::ArgvFile must
452 be installed. If the config file exists but the module is not avail‐
453 able, cpan2rpm will puke.
454 Additionally, please note that if no config file exists in the $HOME
456 directory, one may be passed explicitly on the command line as shown in
457 the example below:
458 # cpan2rpm @options-file -V
460 Note that options from command line will override options from config
462 file.
463 The configuration file should contain options in same format as they
465 would be used in command line. Place one option per line.
466 Example:
468 --packager="John Doe <john.doe@example.com>"
470 --url="http://example.com/johndoe/perlmodules/"
471
473 This script requires that RPM be installed. Both the rpm and rpm-build
474 packages must be installed on the local machine. Please see the RPM
475 documentation (man rpm) for further information.
476 Additionally, the Perl package will be needed :) and the CPAN module
478 (which is bundled with the Perl distribution) will need to be config‐
479 ured. To configure CPAN (CPAN.pm or CPAN/MyConfig.pm) use the follow‐
480 ing:
481 perl -MCPAN -e shell
483 For further information please refer to the CPAN manpage.
485
487 At present, cpan2rpm has been tested and is known to work under the
488 following environments:
489 Operating Systems
491 The script has been tested under the OS list below:
492 - Linux RedHat: 6.1, 6.2, 7.0, 7.2, 7.3, 8.0, 9.0
494 - Redhat Enterprise v3 (RHELv3), AS4 (Nahant)
495 - SuSE 8.1, 9.0
496 Rumour has it it's been tested on Solaris and FreeBSD as well but I
498 don't know for sure. See README.redhat6 for 6.x issues to be aware
499 of.
500 Perl
502 The script is known to work with Perl versions 5.005_03, 5.6.0,
503 5.6.1 and 5.8.0.
504 ExtUtils::MakeMaker
506 This module is used for making and installing the CPAN modules.
507 However many of MakeMaker's versions are broken and incompatible
508 with other versions. For that reason, cpan2rpm works well with
509 versions < 5.91 and > 6.05 but in between it requires an upgrade.
510 Module::Build
512 This module replaces the old and crusty MakeMaker. At present not
513 all modules yet use this new install method so cpan2rpm autodetects
514 the install method and supports both. Please note that some of the
515 meta-data retrieval functions may not work as well with this module
516 as it requires less information to be present in the initial script
517 than does MakeMaker.
518 Redhat Package Manager
520 The RPM system has undergone a lot of change. At present, cpan2rpm
521 runs on version 4.0.4-7x but requires certain special attention
522 (see README for more information). Earlier versions of RPM are
523 borked in various ways and are not currently supported, though on
524 SuSE version 3.0.6 appears to work.
525 If you are running on a platform not listed above, do drop us a note
527 and let us know!
528
530 Erick Calder <ecalder@cpan.org>
531
533 The script was inspired by cpanflute which is distributed with the rpm-
534 build package from RedHat. Many thanks to Robert Brown <bbb@cpan.org>
535 for all his cool tricks, advice and patient support.
536
538 Thank you notes can be mailed directly to the author :)
539 For help, you can subscribe to our mailing list at:
541 http://lists.sourceforge.net/lists/listinfo/cpan2rpm-general
543 or send a message to cpan2rpm-general-request@lists.sourceforge.net
545 with "help" as the subject header. Please note, when submitting
546 patches, please first retrieve the latest (unreleased version of the
547 script from the home page).
548 Feature requests, bug reports and patch submissions should also be han‐
550 dled through SourceForge.
551
553 Some things we're working on/thinking about:
554 1. extract all functionality into a perl module and make cpan2rpm a
556 thin script 2. allow macro definitions like "%_sourcedir
557 %_topdir/%name" in .rpmmacros file (%name isn't defined till later) 3.
558 a --recursive option to install perl rpm dependencies 4. Provides:
559 requirements are generated in the form "perl(POE::Filter) = 1.12" but
560 not "perl-POE-Filter = 1.12" which is for SuSE. 5. PREREQ_PM should be
561 added to the unique list of requirements for the RPM 6. look into
562 --make-test-continue to move past failed testing 7. rethink --force
563
565 The latest version of the tarball, RPM and SRPM may always be found at:
566 http://perl.arix.com/
568 Additionally, the module is available on CPAN at:
570 http://search.cpan.org/author/ECALDER/cpan2rpm/
572 and the project is also hosted on SourceForge at:
574 http://sourceforge.net/projects/cpan2rpm/
576
578 The distribution includes a Changes file which details the evolution of
579 this utility. For your convenience, this file may also be found online
580 at:
581 http://perl.arix.com/cpan2rpm/Changes
583
585 Copyright (c) 2002-2003 Erick Calder <ecalder@cpan.org>
586 This product is free and distributed under the Gnu Public License
588 (GPL). A copy of this license was included in this distribution in a
589 file called LICENSE. If for some reason, this file was not included,
590 please see http://www.gnu.org/licenses/ to obtain a copy of this
591 license.
592 $Id: cpan2rpm,v 2.301 2005/06/18 05:06:54 ekkis Exp $
594perl v5.8.8 2005-06-18 CPAN2RPM(1)