Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::Packlist.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ExtUtils::Packlist 3perl"
58 .TH ExtUtils::Packlist 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ExtUtils::Packlist \- manage .packlist files
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 5
68 \& use ExtUtils::Packlist;
69 \& my ($pl) = ExtUtils::Packlist\->new(\*(Aq.packlist\*(Aq);
70 \& $pl\->read(\*(Aq/an/old/.packlist\*(Aq);
71 \& my @missing_files = $pl\->validate();
72 \& $pl\->write(\*(Aq/a/new/.packlist\*(Aq);
73 \&
74 \& $pl\->{\*(Aq/some/file/name\*(Aq}++;
75 \& or
76 \& $pl\->{\*(Aq/some/other/file/name\*(Aq} = { type => \*(Aqfile\*(Aq,
77 \& from => \*(Aq/some/file\*(Aq };
78 .Ve
79 .SH DESCRIPTION
80 .IX Header "DESCRIPTION"
81 ExtUtils::Packlist provides a standard way to manage .packlist files.
82 Functions are provided to read and write .packlist files. The original
83 \&.packlist format is a simple list of absolute pathnames, one per line. In
84 addition, this package supports an extended format, where as well as a filename
85 each line may contain a list of attributes in the form of a space separated
86 list of key=value pairs. This is used by the installperl script to
87 differentiate between files and links, for example.
88 .SH USAGE
89 .IX Header "USAGE"
90 The hash reference returned by the \fBnew()\fR function can be used to examine and
91 modify the contents of the .packlist. Items may be added/deleted from the
92 \&.packlist by modifying the hash. If the value associated with a hash key is a
93 scalar, the entry written to the .packlist by any subsequent \fBwrite()\fR will be a
94 simple filename. If the value is a hash, the entry written will be the
95 filename followed by the key=value pairs from the hash. Reading back the
96 \&.packlist will recreate the original entries.
97 .SH FUNCTIONS
98 .IX Header "FUNCTIONS"
99 .IP \fBnew()\fR 4
100 .IX Item "new()"
101 This takes an optional parameter, the name of a .packlist. If the file exists,
102 it will be opened and the contents of the file will be read. The \fBnew()\fR method
103 returns a reference to a hash. This hash holds an entry for each line in the
104 \&.packlist. In the case of old-style .packlists, the value associated with each
105 key is undef. In the case of new-style .packlists, the value associated with
106 each key is a hash containing the key=value pairs following the filename in the
107 \&.packlist.
108 .IP \fBread()\fR 4
109 .IX Item "read()"
110 This takes an optional parameter, the name of the .packlist to be read. If
111 no file is specified, the .packlist specified to \fBnew()\fR will be read. If the
112 \&.packlist does not exist, Carp::croak will be called.
113 .IP \fBwrite()\fR 4
114 .IX Item "write()"
115 This takes an optional parameter, the name of the .packlist to be written. If
116 no file is specified, the .packlist specified to \fBnew()\fR will be overwritten.
117 .IP \fBvalidate()\fR 4
118 .IX Item "validate()"
119 This checks that every file listed in the .packlist actually exists. If an
120 argument which evaluates to true is given, any missing files will be removed
121 from the internal hash. The return value is a list of the missing files, which
122 will be empty if they all exist.
123 .IP \fBpacklist_file()\fR 4
124 .IX Item "packlist_file()"
125 This returns the name of the associated .packlist file
126 .SH EXAMPLE
127 .IX Header "EXAMPLE"
128 Here's \f(CW\*(C`modrm\*(C'\fR, a little utility to cleanly remove an installed module.
129 .PP
130 .Vb 1
131 \& #!/usr/local/bin/perl \-w
132 \&
133 \& use strict;
134 \& use IO::Dir;
135 \& use ExtUtils::Packlist;
136 \& use ExtUtils::Installed;
137 \&
138 \& sub emptydir($) {
139 \& my ($dir) = @_;
140 \& my $dh = IO::Dir\->new($dir) || return(0);
141 \& my @count = $dh\->read();
142 \& $dh\->close();
143 \& return(@count == 2 ? 1 : 0);
144 \& }
145 \&
146 \& # Find all the installed packages
147 \& print("Finding all installed modules...\en");
148 \& my $installed = ExtUtils::Installed\->new();
149 \&
150 \& foreach my $module (grep(!/^Perl$/, $installed\->modules())) {
151 \& my $version = $installed\->version($module) || "???";
152 \& print("Found module $module Version $version\en");
153 \& print("Do you want to delete $module? [n] ");
154 \& my $r = <STDIN>; chomp($r);
155 \& if ($r && $r =~ /^y/i) {
156 \& # Remove all the files
157 \& foreach my $file (sort($installed\->files($module))) {
158 \& print("rm $file\en");
159 \& unlink($file);
160 \& }
161 \& my $pf = $installed\->packlist($module)\->packlist_file();
162 \& print("rm $pf\en");
163 \& unlink($pf);
164 \& foreach my $dir (sort($installed\->directory_tree($module))) {
165 \& if (emptydir($dir)) {
166 \& print("rmdir $dir\en");
167 \& rmdir($dir);
168 \& }
169 \& }
170 \& }
171 \& }
172 .Ve
173 .SH AUTHOR
174 .IX Header "AUTHOR"
175 Alan Burlison <[email protected]>