.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPANPLUS::Dist::Arch 3" .TH CPANPLUS::Dist::Arch 3 2024-07-13 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME CPANPLUS::Dist::Arch \- CPANPLUS backend for building Archlinux pacman packages .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 2 \& (First, setup cpan to use us automatically) \& $ setupdistarch \& \& (Install the module as a pacman package) \& $ cpanp \-i Perl::Module::Here \& \& (Use cpan2dist to make a package, but don\*(Aqt install it) \& $ cpan2dist Acme::Bleach \& \& (Use our included cpan2aur to make a source package in current dir) \& $ cpan2aur CPANPLUS::Dist::Arch \& \& (In case we need to customize our package build, create a directory \& with a template we can use for future versions.) \& $ cpan2aur \-d CPANPLUS::Dist::Arch \& ==> Creating new directory for CPANPLUS::Dist::Arch... \& \-> Looking up module for CPANPLUS::Dist::Arch on CPAN... \& Running [/usr/bin/perl /usr/bin/perlbin/core/cpanp\-run\-perl /home/jnbek/.cpanplus/5.22.1/build/CPANPLUS\-Dist\-Arch\-1.32/Makefile.PL INSTALLDIRS=site]... \& Writing Makefile for CPANPLUS::Dist::Arch \& \-> Creating new PKGBUILD.tt template file... \& ==> Created perl\-cpanplus\-dist\-arch source package directory. \& \& (Customize the template... add a optdepends, library depends, etc. \& Just leave the rest of it alone.) \& $ cd perl\-cpanplus\-dist\-arch \& $ ed PKGBUILD.tt \& \& (Submit it to AUR! Will ask for a login username/password or remember \& the last one used) \& $ cpan2aur \-u .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This module is used as a plugin of CPANPLUS to transparently package CPAN distribution files into pacman packages as they are installed. This module can also be used by programmers to build packages in more complex ways. For example, it can create source packages for the AUR by using the included cpan2aur program. .SH REQUIREMENTS .IX Header "REQUIREMENTS" You will need to have pacman installed, of course, to create package and to install these new packages. Pacman is included with Archlinux but can even be used on other Linux distributions. (see http://wiki.archlinux.org/index.php/Pacman) .SH SETUP .IX Header "SETUP" Type setupdistarch at the command line to install CPAN modules as packages by default. .SH "WHERE IS THE PACKAGE" .IX Header "WHERE IS THE PACKAGE" By default, packages are stored under the user's home directory in the \&\fI.cpanplus\fR directory. Two seperate directories are created for building packages and for storing the resulting package file. .PP \&\fI5.10.1\fR represents the version of perl you used to build the package and \fI~/.cpanplus\fR represents the base directory chosen in your CPANPLUS config. .IP \(bu 4 Build Directory: \f(CW\*(C`~/.cpanplus/5.10.1/pacman/build\*(C'\fR .IP \(bu 4 Package Directory: \f(CW\*(C`~/.cpanplus/5.10.1/pacman/pkg\*(C'\fR .SH CUSTOMIZATION .IX Header "CUSTOMIZATION" You can change defaults settings machine-wide (for every user) or for one user or package. The machine-wide settings are set in the \&\fI/etc/makepkg.conf\fR file. The user/package customizations are set using environment variables. .IP \fBPKGDEST\fR 4 .IX Item "PKGDEST" Override where the package files end up. .IP \fBPACKAGER\fR 4 .IX Item "PACKAGER" Override the Contributor comment line at the top of the PKGBUILD. .SS EXAMPLE .IX Subsection "EXAMPLE" Here is how you can use environment variables to put the package files in our \fI~/pkgs\fR directory for the ALPM module. (along with any modules we have to build and install to create it) .PP .Vb 1 \& PACKAGER=\*(Aqjnbek1972 \*(Aq PKGDEST=~/pkgs cpanp \-i ALPM .Ve .SH "COMMAND LINE OPTIONS" .IX Header "COMMAND LINE OPTIONS" There are many command line options to cpan2dist and cpanp. A small number of these options are recognized by CPANPLUS::Dist::Arch. .IP "\fB\-\-verbose\fR \fI(DISABLED)\fR" 4 .IX Item "--verbose (DISABLED)" We are now verbose by default! Hope this is okay. .IP \fB\-\-skiptest\fR 4 .IX Item "--skiptest" This will pass the \-\-nocheck option to makepkg. Automated tests that the module author has written for your benefit will be avoided when building a package for the module. .Sp .Vb 2 \& WARNING: This affects all pre\-requisite module/packages that are \& built and installed; not just the module you specify. .Ve .SH "DIST OPTIONS" .IX Header "DIST OPTIONS" cpan2dist allows you specify CPANPLUS::Dist::Arch specific options on the command line using the \fI\-\-dist\-opts\fR switch. You can also pass these arguments when using CPANPLUS::Module methods like \fBdist()\fR. .IP \fBpkgtype\fR 4 .IX Item "pkgtype" This specifies whether to make a source package or a binary package. The default is to make a binary package. .IP \fBdestdir\fR 4 .IX Item "destdir" This overrides every other package destination specified. Whether from the makepkg.conf file, environment variable, or default. .IP \fBquiet\fR 4 .IX Item "quiet" If set to a true value, pipe makepkg output to /dev/null. .IP \fBnocolor\fR 4 .IX Item "nocolor" If set to a true value, disable colorized output from makepkg. Use monochrome output only. .SH "PROGRAMMERS API" .IX Header "PROGRAMMERS API" The rest of the document describes how a programmer can use the module. You can use this module with the CPANPLUS module in order to install distributions/packages in more complex ways. .PP Here is a quick example of how you use C::D::A with CPANPLUS::Backend. .SS EXAMPLE .IX Subsection "EXAMPLE" .Vb 3 \& use CPANPLUS::Backend; \& use warnings; \& use strict; \& \& # Create a source package in our current directory, no verbosity. \& my $cb = CPANPLUS::Backend\->new(); \& my $mod = $cb\->module_tree( \*(AqALPM\*(Aq ); \& $mod\->install( target => \*(Aqcreate\*(Aq, \& format => \*(AqCPANPLUS::Dist::Arch\*(Aq, \& pkg => \*(Aqsrc\*(Aq, \& destdir => \*(Aq.\*(Aq, \& verbose => 0 \& ); .Ve .PP See also CPANPLUS::Module. The \f(CW\*(C`create_dist_arch\*(C'\fR sub in the cpan2aur script shows how to use CPANPLUS::Module's \fBdist()\fR method, which is a little funky. \fI(I want to submit a patch to it when I get the chance)\fR .SS "EXPORT TAGS" .IX Subsection "EXPORT TAGS" .IP \fB:all\fR 4 .IX Item ":all" This will import the functions \f(CW\*(C`dist_pkgname\*(C'\fR and \f(CW\*(C`dist_pkgver\*(C'\fR into your package. These functions are not imported by default. .SS "EXPORTED FUNCTIONS" .IX Subsection "EXPORTED FUNCTIONS" \fIdist_pkgname\fR .IX Subsection "dist_pkgname" .PP .Vb 6 \& Usage : my $pkgname = dist_pkgname( \*(AqAcme\-Drunk\*(Aq ); \& Purpose : Converts a module\*(Aqs distribution name to an \& Archlinux style perl package name. \& Params : $dist_name \- The name of the distribution (ex: Acme\-Drunk) \& Returns : The Archlinux perl package name (ex: perl\-acme\-drunk). \& following the Archlinux packaging standards. .Ve .PP \fIdist_pkgver\fR .IX Subsection "dist_pkgver" .PP .Vb 6 \& Usage : my $pkgver = dist_pkgver( \*(Aq1.20.1_2A\*(Aq ); \& Purpose : Convert a module\*(Aqs CPAN distribution version into our more \& restrictive pacman package version number. \& Params : The version of the CPAN distribution file. \& Returns : The Archlinux package version following the Archlinux \& packaging standards. .Ve .SS "PUBLIC METHODS" .IX Subsection "PUBLIC METHODS" When using the CPANPLUS module in a perl script to create packages, these public methods are available. See the cpanpkgbuild.pl script included in the examples directory for an example. .PP \fIget_pkgname\fR .IX Subsection "get_pkgname" .PP .Vb 2 \& Usage : say $dist\->get_pkgname; \& Returns : The name of the package. .Ve .PP \fIget_pkgver\fR .IX Subsection "get_pkgver" .PP .Vb 2 \& Usage : say $dist\->get_pkgver; \& Returns : The version of the package. .Ve .PP \fIget_pkgrel\fR .IX Subsection "get_pkgrel" .PP .Vb 3 \& Usage : say "Release: ", $dist\->get_pkgrel; \& Notes : Default is 1, unless set_pkgrel is used. \& Returns : The package release number. .Ve .PP \fIset_pkgrel\fR .IX Subsection "set_pkgrel" .PP .Vb 3 \& Usage : $newrel = $dist\->set_pkgrel( 2 ); \& Params : $new_relnum \- Croaks if this is not a number. \& Returns : The new release number. .Ve .PP \fIset_destdir\fR .IX Subsection "set_destdir" .PP .Vb 4 \& Usage : $dist\->set_destdir(\*(Aq~/pkg/perl\*(Aq); \& Purpose : Overrides the directory to store the built package \& for this particular object. \& Returns : The directory that was set. .Ve .PP \fIget_destdir\fR .IX Subsection "get_destdir" .PP .Vb 2 \& Usage : my $dest = $dist\->get_destdir; \& Returns : The directory previously specified by set_destdir. .Ve .PP \fIget_pkgpath\fR .IX Subsection "get_pkgpath" .PP .Vb 3 \& Usage : my $fqp = $dist\->get_pkgpath; \& Returns : The fully qualified path of the built package \& or undef if no package was built yet. .Ve .PP \fIget_cpandistdir\fR .IX Subsection "get_cpandistdir" .PP .Vb 8 \& Usage : my $distdir = $dist\->get_cpandistdir; \& Returns : The main directory name that will be inside the distribution \& tarball. This directory contains the entire distribution. \& Example : If the distribution file of Acme\-Bleach is in the tarball \& Acme\-Bleach\-1.12.tar.gz or Acme\-Bleach\-1.12.tar.bz2 \& then $dist\->get_cpandistdir will return \*(AqAcme\-Bleach\-1.12\*(Aq. \& Notes : Does not actually check if the directory exists in the tarball. \& So far it always has... .Ve .PP \fIget_pkgvars\fR .IX Subsection "get_pkgvars" .PP .Vb 7 \& Usage : my %pkgvars = $dist\->get_pkgvars; \& Returns : A hash containing all the PKGBUILD variables. \& Keys are the bash variable names in the PKGBUILD. \& Dependencies are converted to their pacman names. \& Notes : The keys are: pkgname, pkgver, pkgdesc, depends, url, source \& md5sums, arch, pkglinks, and sha512sums (if Digest::SHA is \& installed). \& \& One key not named after a PKGBUILD field is \*(Aqpkglinks\*(Aq whose \& value is a hashref. Inside this hashref, the keys \*(Aqdepends\*(Aq \& and \*(Aqmakedepends\*(Aq are always present, even if they are an \& empty arrayref. The keys \*(Aqcheckdepends\*(Aq and \*(Aqconflicts\*(Aq are \& only present if they contain a non\-empty arrayref. \& \& These values are package specifications. Each specification \& is an arrayref of package name, a comparison operator, \& and a version number. .Ve .PP \fIget_pkgvars_ref\fR .IX Subsection "get_pkgvars_ref" .PP .Vb 2 \& Usage : my $pkgvars_ref = $dist\->get_pkgvars_ref; \& Returns : The same as get_pkgvars except as a hashref. .Ve .PP \fIget_pkgbuild\fR .IX Subsection "get_pkgbuild" .PP .Vb 3 \& Usage : my $pkgbuildtext = $dist\->get_pkgbuild; \& Returns : A scalar containing the full text of the PKGBUILD that would \& be generated in the perl pacman package. .Ve .PP \fIcreate_pkgbuild\fR .IX Subsection "create_pkgbuild" .PP .Vb 9 \& Usage : $self\->create_pkgbuild( \*(Aq/tmp\*(Aq, 1 ); \& Purpose : Creates a PKGBUILD file in the specified directory. \& Params : $destdir \- The directory to put the new PKGBUILD in. \& Precond : You must first call prepare or have CPANPLUS do it automatically. \& Throws : unknown installer type: \*(Aq...\*(Aq \& failed to write PKGBUILD: ... \& Invalid arguments to create_pkgbuild \& Invalid directoy passed to create_pkgbuild: ... \& Returns : Nothing. .Ve .SS "TEMPLATE METHODS" .IX Subsection "TEMPLATE METHODS" \fIget_pkgbuild_templ\fR .IX Subsection "get_pkgbuild_templ" .PP .Vb 3 \& Usage : my $tt_text = $self\->get_pkgbuild_templ(); \& Purpose : Mostly just to compliment L. \& Returns : The template used internally by L .Ve .PP See "PKGBUILD TEMPLATE". .PP \fIset_pkgbuild_templ\fR .IX Subsection "set_pkgbuild_templ" .PP .Vb 4 \& Usage : my $new_tt_text = $self\->set_pkgbuild_templ( $templ_text ); \& Purpose : Create PKGBUILDs based on a custom template. \& Params : $templ_text \- New template text to use for creating the PKGBUILD. \& Returns : The new template text. .Ve .PP See "PKGBUILD TEMPLATE". .PP \fIset_tt_init_args\fR .IX Subsection "set_tt_init_args" .PP .Vb 6 \& Usage : $self\->set_tt_init_args( INCLUDE_PATH => \*(Aq/home/jnbek/aur4/tt\*(Aq, \& EVAL_PERL => 1 ); \& Purpose : Change arguments that are given to the template module\*(Aqs \& constructor when we create an object to process templates. \& Params : %init_args \- A hash of config key/value pairs. \& Returns : A hash reference to %init_args. .Ve .PP What config value are supported depends on what template module is being used. You'll have to look at the module's docs to be sure. .PP \fIset_tt_module\fR .IX Subsection "set_tt_module" .PP .Vb 6 \& Usage : $obj\->set_tt_module( 0 ); \& Params : $modname \- The name of a template module to use or \& 0 to force using the internal engine. \& Warning : This sets the template module to use for ALL \& CPANPLUS::Dist::Arch objects. \& Returns : $modname .Ve .PP \fIget_tt_module\fR .IX Subsection "get_tt_module" .PP .Vb 4 \& Usage : my $modname = $obj\->get_tt_module(); \& my $modname = CPANPLUS::Dist::Arch\->get_tt_module(); \& Returns : The name of the template module that is being used or 0 \& if we are using our own internal template engine. .Ve .SS "PKGBUILD TEMPLATE" .IX Subsection "PKGBUILD TEMPLATE" Since version 0.19 we now use template modules if they are available. So if any of the following modules are installed and can be used, they will be used instead of our builtin template engine: .IP "1. Template::Toolkit" 4 .IX Item "1. Template::Toolkit" .PD 0 .IP "2. Template::Alloy" 4 .IX Item "2. Template::Alloy" .IP "3. Template::Tiny" 4 .IX Item "3. Template::Tiny" .PD .PP The modules have the priority listed above. We go through the list sequentially and use the first module that we find. .PP \fIBUILTIN TEMPLATE FORMAT\fR .IX Subsection "BUILTIN TEMPLATE FORMAT" .PP The builtin template format is an extremely simplified ripoff of Template::Toolkit syntax. It only implements variable interpolation and the \f(CW\*(C`IF\*(C'\fR directive. To insert a template variable use the syntax \f(CW\*(C`[% foo %]\*(C'\fR. This will insert the value of the variable named 'foo'. The \f(CWget_pkgbuild()\fR method will croak with the message \fI"Template variable ... was not provided"\fR if the variable was not defined. \f(CW\*(C`[% IF var_name %] ... [% END %]\*(C'\fR will remove what is in-between the \f(CW\*(C`IF\*(C'\fR and \f(CW\*(C`END\*(C'\fR tags if the variable named \f(CW\*(C`var_name\*(C'\fR is not set to a true value. .PP Trailing newlines will also be stripped if you use the \f(CW\*(C`\-%]\*(C'\fR syntax (notice the \f(CW\*(C`\-\*(C'\fR) to close the Template::Toolkit style blocks. .PP See "get_pkgvars" for a list of the variables that can be used inside the template. .SH LIMITATIONS .IX Header "LIMITATIONS" There are some limitations in the way CPANPLUS and pacman works together that I am not sure can be fixed automatically. Instead you might need a human to intervene. I called these limitations because they aren't exactly bugs. More specific bugs with exact error messages are in the "BUGS" section. .IP "\fBCannot detect non-perl dependencies\fR" 4 .IX Item "Cannot detect non-perl dependencies" As of version 0.09, CPANPLUS will \fItry\fR to find non-perl dependencies. This only works with ExtUtils::MakeMaker distributions. .Sp This means if you plan on distributing a perl module package (ie uploading to AUR) you should edit the PKGBUILD by hand to include the libraries needed by the XS module. .Sp The included cpan2aur script helps creating customized AUR packages. .IP "\fBA module is installed, but pacman says it isn't\fR" 4 .IX Item "A module is installed, but pacman says it isn't" CPAN[PLUS] considers a module installed if it can \f(CW\*(C`use\*(C'\fR it. That is, if it is in \f(CW@INC\fR somewhere on your system. .Sp \&\fIPacman\fR considers a module installed if it has been packaged and installed with \fIpacman\fR. .Sp So if you installed some modules in the past without packaging them first, they don't exist as far as \fIpacman\fR is concerned. Usually, you can just reinstall them using this module because CPANPLUS::Dist::Arch installs modules under the \f(CW\*(C`vendor_perl/\*(C'\fR directories, such as \&\f(CW\*(C`/usr/share/perl5/vendor_perl/...\*(C'\fR, and CPAN installs under the \&\f(CW\*(C`site_perl/\*(C'\fR directories, such as \f(CW\*(C`/usr/share/perl5/site_perl/...\*(C'\fR. .Sp Installing with this module will appease \fIpacman\fR, but you may want to manually delete the previously installed modules to prevent version mismatch problems. .IP "\fBPre-requisites are always installed\fR" 4 .IX Item "Pre-requisites are always installed" CPANPLUS by default installs the pre-requisite modules before the module you requested. This module does the same only it creates an Arch package and installs it with \fIpacman\fR instead. .Sp You should be able to run \fIpacman\fR under sudo for this to work properly. Or you could run cpan2dist as root, but I wouldn't recommend it. .IP "\fBReadline is broken and I can't use cpanplus!\fR" 4 .IX Item "Readline is broken and I can't use cpanplus!" I had this problem recently. A system upgrade had updated my readline package but the Term::ReadLine::Gnu module was not updated. Or perhaps I had the termcap-compat package, which breaks Term::ReadLine::Gnu. .Sp I forget, in any case Term::ReadLine::Gnu was broken. To be able to update the perl-term-readline-gnu package, I had to force the Term::ReadLine module to not try to load Term::ReadLine::Gnu with the PERL_RL environment variable: .Sp .Vb 1 \& PERL_RL=0 cpanp \-i Term::ReadLine::Gnu .Ve .SH BUGS .IX Header "BUGS" Please email me or report any bugs or feature requests to \f(CW\*(C`\*(C'\fR, or through the web interface at . We will be notified, and then you'll automatically be notified of progress on your bug as we make changes. .SS "Known Bugs" .IX Subsection "Known Bugs" .IP "\fBDist creation of '...' skipped, build time exceeded: 300 seconds\fR" 4 .IX Item "Dist creation of '...' skipped, build time exceeded: 300 seconds" If compiling a module takes a long time, this message will pop up. Interestingly, though, the module keeps compiling in the background...? .Sp This is something CPANPLUS does automatically. If you had been trying to install the module, the install step will be aborted. The package will still be created in the usual directory, so you can install it manually. .Sp We haven't been able to track this down yet... I think it has only happened with cpan2dist so far. It happened when building PDL, by the way. .Sp If you have any ideas or patches, feel free to create a pull request on GitHub .Sp .SH TODO .IX Header "TODO" .IP \(bu 4 Extract license information from META.yml, maybe use a YAML module. .SH SUPPORT .IX Header "SUPPORT" Email me at \f(CW\*(C`\*(C'\fR or message me as \fIjnbek\fR on IRC .PP Freenode: #archlinux .PP really anywhere you see \fIjnbek\fR or \fIjnbek1972\fR online, it's me. .PP To check why the build process failed, read the build logs CPANPLUS keeps in \f(CW\*(C`~/.cpanplus/install_logs/\*(C'\fR. The problem may be specific to the module you're building and not this module. .SH ACKNOWLEDGEMENTS .IX Header "ACKNOWLEDGEMENTS" This module was inspired by the perl-cpanplus-pacman package and CPANPLUS::Dist::Pacman by Firmicus which is available at . .PP This mostly started from CPANPLUS::Dist::RPM which is on Google Code at . This was a very helpful starting point to try to understand the internals of CPANPLUS. .SH CONTRIBUTORS .IX Header "CONTRIBUTORS" Contributors are credited in detail in the ChangeLog file. The following people have been kind enough to submit bug reports: .IP \(bu 4 Xenoterracide .IP \(bu 4 IsaacG .PP \&\fIThank you for your help!\fR .SH "SEE ALSO" .IX Header "SEE ALSO" .IP \(bu 4 AUR Package: perl-cpanplus-dist-arch .Sp .IP \(bu 4 Git Repository .Sp .IP \(bu 4 Archlinux Perl Package Guidelines .Sp .IP \(bu 4 pacman .Sp .IP \(bu 4 makepkg .Sp .IP \(bu 4 CPANPLUS .Sp .SH AUTHOR .IX Header "AUTHOR" Created by: Justin Davis \f(CW\*(C`\*(C'\fR .PP Serendipitously maintained by: John D Jones III \f(CW\*(C`\*(C'\fR .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2010\-2015 Justin Davis, all rights reserved. .PP Copyright 2015 John D Jones III, all rights reserved .PP Justin Davis \f(CW\*(C`\*(C'\fR .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2010 Justin Davis, all rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.