.\" -*- 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 "CPAN::Checksums 3pm"
.TH CPAN::Checksums 3pm 2024-01-21 "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
CPAN::Checksums \- Write a "CHECKSUMS" file for a directory as on CPAN
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  use CPAN::Checksums qw(updatedir);
\&  my $success = updatedir($directory, $root);
.Ve
.SH "INCOMPATIBILITY ALERT"
.IX Header "INCOMPATIBILITY ALERT"
Since version 1.0 the generation of the attribute \f(CW\*(C`shortname\*(C'\fR is
turned off by default. It was too slow and was not used as far as I
know, and above all, it could fail on large directories. The shortname
feature can still be turned on by setting the global variable
\&\f(CW$TRY_SHORTNAME\fR to a true value.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
.ie n .IP "$success = updatedir($dir[, $root])" 2
.el .IP "\f(CW$success\fR = updatedir($dir[, \f(CW$root\fR])" 2
.IX Item "$success = updatedir($dir[, $root])"
\&\f(CW$dir\fR is a directory. \fBUpdatedir()\fR writes a \f(CW\*(C`CHECKSUMS\*(C'\fR file into that
directory, unless a previously written \f(CW\*(C`CHECKSUMS\*(C'\fR file is there that
is still valid. Returns 2 if a new \f(CW\*(C`CHECKSUMS\*(C'\fR file has been written,
1 if a valid \f(CW\*(C`CHECKSUMS\*(C'\fR file is already there, otherwise dies.
.Sp
If \f(CW$root\fR is given, the hash entry with the key \f(CW\*(C`cpan_path\*(C'\fR is
relative to this root directory.
.Sp
Note: since version 2.0 updatedir on empty directories behaves just
the same. In older versions it silently did nothing.
.SS "Global Variables in package CPAN::Checksums"
.IX Subsection "Global Variables in package CPAN::Checksums"
.ie n .IP $IGNORE_MATCH 4
.el .IP \f(CW$IGNORE_MATCH\fR 4
.IX Item "$IGNORE_MATCH"
If the global variable \f(CW$IGNORE_MATCH\fR is set, then all files matching
this expression will be completely ignored and will not be included in
the CPAN \f(CW\*(C`CHECKSUMS\*(C'\fR files. Per default this variable is set to
.Sp
.Vb 1
\&    qr{(?i\-xsm:readme$)}
.Ve
.ie n .IP $CAUTION 4
.el .IP \f(CW$CAUTION\fR 4
.IX Item "$CAUTION"
Setting the global variable \f(CW$CAUTION\fR causes \fBupdatedir()\fR to report
changes of files in the attributes \f(CW\*(C`size\*(C'\fR, \f(CW\*(C`mtime\*(C'\fR, \f(CW\*(C`md5\*(C'\fR, or
\&\f(CW\*(C`md5\-ungz\*(C'\fR to STDERR.
.ie n .IP $TRY_SHORTNAME 4
.el .IP \f(CW$TRY_SHORTNAME\fR 4
.IX Item "$TRY_SHORTNAME"
By setting the global variable \f(CW$TRY_SHORTNAME\fR to a true value, you can
tell \fBupdatedir()\fR to include an attribute \f(CW\*(C`shortname\*(C'\fR in the resulting
hash that is 8.3\-compatible. Please note, that \fBupdatedir()\fR in this
case may be slow and may even fail on large directories, because it
will always only try 1000 iterations to find a name that is not yet
taken and then give up.
.ie n .IP $SIGNING_KEY 4
.el .IP \f(CW$SIGNING_KEY\fR 4
.IX Item "$SIGNING_KEY"
Setting the global variable \f(CW$SIGNING_KEY\fR makes the generated \f(CW\*(C`CHECKSUMS\*(C'\fR
file to be clear-signed by the command specified in \f(CW$SIGNING_PROGRAM\fR
(defaults to \f(CW\*(C`gpg \-\-clearsign \-\-default\-key \*(C'\fR), passing the signing
key as an extra argument.  The resulting \f(CW\*(C`CHECKSUMS\*(C'\fR file should look like:
.Sp
.Vb 3
\&    0&&<<\*(Aq\*(Aq; # this PGP\-signed message is also valid perl
\&    \-\-\-\-\-BEGIN PGP SIGNED MESSAGE\-\-\-\-\-
\&    Hash: SHA1
\&
\&    # CHECKSUMS file written on ... by CPAN::Checksums (v...)
\&    $cksum = {
\&        ...
\&    };
\&
\&    _\|_END_\|_
\&    \-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-
\&    ...
\&    \-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-
.Ve
.Sp
note that the actual data remains intact, but two extra lines are
added to make it legal for both OpenPGP and perl syntax.
.ie n .IP $MIN_MTIME_CHECKSUMS 4
.el .IP \f(CW$MIN_MTIME_CHECKSUMS\fR 4
.IX Item "$MIN_MTIME_CHECKSUMS"
If the global variable \f(CW$MIN_MTIME_CHECKSUMS\fR is set, then updatedir
will renew signatures on checksum files that have an older mtime than
the given value.
.SH PREREQUISITES
.IX Header "PREREQUISITES"
DirHandle, IO::File, Digest::MD5, Digest::SHA, Compress::Bzip2,
Compress::Zlib, File::Spec, Data::Dumper, Data::Compare, File::Temp
.SH BUGS
.IX Header "BUGS"
If updatedir is interrupted, it may leave a temporary file lying
around. These files have the File::Temp template \f(CW\*(C`CHECKSUMS.XXXX\*(C'\fR and
should be harvested by a cronjob.
.SH AUTHOR
.IX Header "AUTHOR"
Andreas Koenig, andreas.koenig@anima.de; GnuPG support by Autrijus Tang
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright (c) 2002\-2008 Andreas Koenig, Audrey Tang, Steve Peters.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1).