.\" -*- 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 "CPAN2AUR 1"
.TH CPAN2AUR 1 2023-07-25 "perl v5.38.0" "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
cpan2aur \- AUR maintainer utility for CPAN perl modules
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& cpan2aur [\-v \-f]
\&
\& cpan2aur [\-v \-f] \-\-directory
\&
\& cpan2aur [\-v \-f] \-\-upload [Module::Names filenames.src.tar.gz
\& /pkg/dirs/]
\&
\& cpan2aur [\-v \-f] \-\-check
\&
\& \-h, \-\-help Display this usage message.
\& \-m, \-\-man Display full help manual page.
\& \-v, \-\-verbose Allow CPANPLUS to be more verbose.
\& \-f, \-\-force Overwrite files without asking.
\&
\& \-d, \-\-directory Create a source package directory with a standard
\& PKGBUILD.tt template file.
\& \-r, \-\-reverse Convert a PKGBUILD in the current directory to a
\& template file (PKGBUILD.tt).
\&
\& TODO: The upload feature is currently disabled due to AUR v4.0 changing
\& to a Git backend and HTTP Uploads removed.
\& \-u, \-\-upload [dir] Upload the generated source package to the AUR.
\& [file] * If a dir is specified cd to that dir and
\& [module] convert PKGBUILD.tt to a PKGBUILD to a
\& source package, then upload it.
\& * If a file is specified, upload it if it appears
\& to be a source package.
\& * If a module is specified, package and upload it.
\& * If nothing is specified, act upon the current
\& directory.
\& \-c, \-\-check Check if a source package or directory (with a
\& source package or PGKBUILD in it) is outdated.
\& If so, then \-\-upload a new version.
\& \-n, \-\-name Specify a different username to login to the AUR,
\& instead of the last one used.
\& \-p, \-\-pass Specify a password to use to login to AUR.
\& \-m, \-\-mono Disable color output, use monochrome black/white.
\& \-i, \-\-inc Rebuild the source package, incrementing the
\& release number.
\&
\& (Unlike GNU options, single\-letter options need their own hyphens
\& example: \-u \-d)
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This is a utility made for creating and uploading perl packages for
the AUR (Archlinux User Repository). cpan2aur's simplest usage,
without any flags, creates AUR source packages:
.IP \(bu 4
If you specify a \fIModule::Name\fR we create a source package file in
the current directory.
.IP \(bu 4
If you specify a \fIdirectory\fR we will generate that template
directory's source package.
.SS TEMPLATES
.IX Subsection "TEMPLATES"
With the \fI\-d\fR or \fI\-\-directory\fR flag cpan2aur will create a
directory to contain the source package and generate a \f(CW\*(C`PKGBUILD.tt\*(C'\fR
template inside it. This is best when starting to maintain a new
AUR package that requires manual PKGBUILD tweaking.
.PP
Templates are a powerful way to make maintaining packages on the AUR
easier. Most of the time you will not have to update the PKGBUILD.tt
template, you will just use the \fI\-\-upload\fR flag on a source package
directory containing a template. This will convert the template
to a PKGBUILD by filling in the new info for the new CPAN version.
.SS UPLOADING
.IX Subsection "UPLOADING"
With the \fI\-u\fR or \fI\-\-upload\fR flag cpan2aur will upload a source
package to the AUR. It will try to Do The Right Thing (tm) for
command line arguments. Arguments can be source package files,
directories for source packages, or module/distribution names.
.PP
We store previous logins inside the file \f(CW\*(C`~/.cpan2aur\*(C'\fR. The last
username that was used will be retried. To use a different username,
use the \fI\-n\fR or \fI\-\-name\fR flag or delete the \f(CW\*(C`~/.cpan2aur\*(C'\fR file.
.SS "AUTOMATIC UPDATING"
.IX Subsection "AUTOMATIC UPDATING"
You can even use the \fI\-\-check\fR flag to check if a new version
of the perl distribution is available on CPAN. If it is, cpan2aur
will go through the \fI\-\-upload\fR process. This is done by checking
the versions of previously build .src.tar.gz files or PKGBUILDs.
.SH EXAMPLE
.IX Header "EXAMPLE"
For example, I keep a copy of the source packages I maintain inside my
\&\f(CW\*(C`~/aur\*(C'\fR directory. Some of these packages I have created directories
and PKGBUILD.tt files for, because they require more customization.
.PP
.Vb 6
\& [juster@virtuarch ~]$ cd ~/aur
\& [juster@virtuarch aur]$ ls
\& perl\-alpm\-0.05\-1.src.tar.gz perl\-text\-csv\-xs\-0.70\-1.src.tar.gz
\& perl\-sepia perl\-text\-xsv\-0.21\-1.src.tar.gz
\& perl\-text\-csv perl\-tkx
\& [juster@virtuarch aur]$
.Ve
.PP
Now to check and see if any of these packages need updating, I just use the
\&\-\-check flag to find new versions and upload them automatically.
.PP
.Vb 10
\& [juster@virtuarch aur]$ cpan2aur \-\-check perl\-*
\& ==> Checking if perl\-alpm\-0.05\-1.src.tar.gz is up to date...
\& ==> Looking up module for ALPM on CPAN...
\& perl\-alpm\-0.05\-1.src.tar.gz is up to date.
\& ==> Checking if perl\-sepia is up to date...
\& ==> Looking up module for Sepia on CPAN...
\& perl\-sepia is up to date.
\& ==> Checking if perl\-text\-csv is up to date...
\& ==> Looking up module for Text\-CSV on CPAN...
\& perl\-text\-csv is up to date.
\& ==> Checking if perl\-text\-csv\-xs\-0.70\-1.src.tar.gz is up to date...
\& ==> Looking up module for Text\-CSV_XS on CPAN...
\& perl\-text\-csv\-xs\-0.70\-1.src.tar.gz is up to date.
\& ==> Checking if perl\-text\-xsv\-0.21\-1.src.tar.gz is up to date...
\& ==> Looking up module for Text\-xSV on CPAN...
\& perl\-text\-xsv\-0.21\-1.src.tar.gz is up to date.
\& ==> Checking if perl\-tkx is up to date...
\& ==> Looking up module for Tkx on CPAN...
\& perl\-tkx is up to date.
\& [juster@virtuarch aur]$
.Ve
.PP
It's kind of boring since I don't have anything outdated to upload but
I hope you get the idea...
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP \(bu 4
CPANPLUS::Dist::Arch
.IP \(bu 4
.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
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.