Debian Codegraph @

upstream/mageia-cauldron/man3pm/ExtUtils::Packlist.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "ExtUtils::Packlist 3pm"
61 .TH ExtUtils::Packlist 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 ExtUtils::Packlist \- manage .packlist files
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 5
71 \& use ExtUtils::Packlist;
72 \& my ($pl) = ExtUtils::Packlist\->new(\*(Aq.packlist\*(Aq);
73 \& $pl\->read(\*(Aq/an/old/.packlist\*(Aq);
74 \& my @missing_files = $pl\->validate();
75 \& $pl\->write(\*(Aq/a/new/.packlist\*(Aq);
76 \&
77 \& $pl\->{\*(Aq/some/file/name\*(Aq}++;
78 \& or
79 \& $pl\->{\*(Aq/some/other/file/name\*(Aq} = { type => \*(Aqfile\*(Aq,
80 \& from => \*(Aq/some/file\*(Aq };
81 .Ve
82 .SH DESCRIPTION
83 .IX Header "DESCRIPTION"
84 ExtUtils::Packlist provides a standard way to manage .packlist files.
85 Functions are provided to read and write .packlist files. The original
86 \&.packlist format is a simple list of absolute pathnames, one per line. In
87 addition, this package supports an extended format, where as well as a filename
88 each line may contain a list of attributes in the form of a space separated
89 list of key=value pairs. This is used by the installperl script to
90 differentiate between files and links, for example.
91 .SH USAGE
92 .IX Header "USAGE"
93 The hash reference returned by the \fBnew()\fR function can be used to examine and
94 modify the contents of the .packlist. Items may be added/deleted from the
95 \&.packlist by modifying the hash. If the value associated with a hash key is a
96 scalar, the entry written to the .packlist by any subsequent \fBwrite()\fR will be a
97 simple filename. If the value is a hash, the entry written will be the
98 filename followed by the key=value pairs from the hash. Reading back the
99 \&.packlist will recreate the original entries.
100 .SH FUNCTIONS
101 .IX Header "FUNCTIONS"
102 .IP \fBnew()\fR 4
103 .IX Item "new()"
104 This takes an optional parameter, the name of a .packlist. If the file exists,
105 it will be opened and the contents of the file will be read. The \fBnew()\fR method
106 returns a reference to a hash. This hash holds an entry for each line in the
107 \&.packlist. In the case of old\-style .packlists, the value associated with each
108 key is undef. In the case of new\-style .packlists, the value associated with
109 each key is a hash containing the key=value pairs following the filename in the
110 \&.packlist.
111 .IP \fBread()\fR 4
112 .IX Item "read()"
113 This takes an optional parameter, the name of the .packlist to be read. If
114 no file is specified, the .packlist specified to \fBnew()\fR will be read. If the
115 \&.packlist does not exist, Carp::croak will be called.
116 .IP \fBwrite()\fR 4
117 .IX Item "write()"
118 This takes an optional parameter, the name of the .packlist to be written. If
119 no file is specified, the .packlist specified to \fBnew()\fR will be overwritten.
120 .IP \fBvalidate()\fR 4
121 .IX Item "validate()"
122 This checks that every file listed in the .packlist actually exists. If an
123 argument which evaluates to true is given, any missing files will be removed
124 from the internal hash. The return value is a list of the missing files, which
125 will be empty if they all exist.
126 .IP \fBpacklist_file()\fR 4
127 .IX Item "packlist_file()"
128 This returns the name of the associated .packlist file
129 .SH EXAMPLE
130 .IX Header "EXAMPLE"
131 Here\*(Aqs \f(CW\*(C`modrm\*(C'\fR, a little utility to cleanly remove an installed module.
132 .PP
133 .Vb 1
134 \& #!/usr/local/bin/perl \-w
135 \&
136 \& use strict;
137 \& use IO::Dir;
138 \& use ExtUtils::Packlist;
139 \& use ExtUtils::Installed;
140 \&
141 \& sub emptydir($) {
142 \& my ($dir) = @_;
143 \& my $dh = IO::Dir\->new($dir) || return(0);
144 \& my @count = $dh\->read();
145 \& $dh\->close();
146 \& return(@count == 2 ? 1 : 0);
147 \& }
148 \&
149 \& # Find all the installed packages
150 \& print("Finding all installed modules...\en");
151 \& my $installed = ExtUtils::Installed\->new();
152 \&
153 \& foreach my $module (grep(!/^Perl$/, $installed\->modules())) {
154 \& my $version = $installed\->version($module) || "???";
155 \& print("Found module $module Version $version\en");
156 \& print("Do you want to delete $module? [n] ");
157 \& my $r = <STDIN>; chomp($r);
158 \& if ($r && $r =~ /^y/i) {
159 \& # Remove all the files
160 \& foreach my $file (sort($installed\->files($module))) {
161 \& print("rm $file\en");
162 \& unlink($file);
163 \& }
164 \& my $pf = $installed\->packlist($module)\->packlist_file();
165 \& print("rm $pf\en");
166 \& unlink($pf);
167 \& foreach my $dir (sort($installed\->directory_tree($module))) {
168 \& if (emptydir($dir)) {
169 \& print("rmdir $dir\en");
170 \& rmdir($dir);
171 \& }
172 \& }
173 \& }
174 \& }
175 .Ve
176 .SH AUTHOR
177 .IX Header "AUTHOR"
178 Alan Burlison <[email protected]>