Debian Codegraph @

upstream/opensuse-tumbleweed/man3/ExtUtils::Manifest.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::Manifest 3pm"
61 .TH ExtUtils::Manifest 3pm 2026-03-09 "perl v5.42.1" "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::Manifest \- Utilities to write and check a MANIFEST file
68 .SH VERSION
69 .IX Header "VERSION"
70 version 1.75
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 1
74 \& use ExtUtils::Manifest qw(...funcs to import...);
75 \&
76 \& mkmanifest();
77 \&
78 \& my @missing_files = manicheck;
79 \& my @skipped = skipcheck;
80 \& my @extra_files = filecheck;
81 \& my($missing, $extra) = fullcheck;
82 \&
83 \& my $found = manifind();
84 \&
85 \& my $manifest = maniread();
86 \&
87 \& manicopy($read,$target);
88 \&
89 \& maniadd({$file => $comment, ...});
90 .Ve
91 .SH DESCRIPTION
92 .IX Header "DESCRIPTION"
93 \&...
94 .SH FUNCTIONS
95 .IX Header "FUNCTIONS"
96 ExtUtils::Manifest exports no functions by default. The following are
97 exported on request:
98 .SS mkmanifest
99 .IX Subsection "mkmanifest"
100 .Vb 1
101 \& mkmanifest();
102 .Ve
103 .PP
104 Writes all files in and below the current directory to your \fIMANIFEST\fR.
105 It works similar to the result of the Unix command
106 .PP
107 .Vb 1
108 \& find . > MANIFEST
109 .Ve
110 .PP
111 All files that match any regular expression in a file \fIMANIFEST.SKIP\fR
112 (if it exists) are ignored.
113 .PP
114 Any existing \fIMANIFEST\fR file will be saved as \fIMANIFEST.bak\fR.
115 .SS manifind
116 .IX Subsection "manifind"
117 .Vb 1
118 \& my $found = manifind();
119 .Ve
120 .PP
121 returns a hash reference. The keys of the hash are the files found
122 below the current directory.
123 .SS manicheck
124 .IX Subsection "manicheck"
125 .Vb 1
126 \& my @missing_files = manicheck();
127 .Ve
128 .PP
129 checks if all the files within a \f(CW\*(C`MANIFEST\*(C'\fR in the current directory
130 really do exist. If \f(CW\*(C`MANIFEST\*(C'\fR and the tree below the current
131 directory are in sync it silently returns an empty list.
132 Otherwise it returns a list of files which are listed in the
133 \&\f(CW\*(C`MANIFEST\*(C'\fR but missing from the directory, and by default also
134 outputs these names to STDERR.
135 .SS filecheck
136 .IX Subsection "filecheck"
137 .Vb 1
138 \& my @extra_files = filecheck();
139 .Ve
140 .PP
141 finds files below the current directory that are not mentioned in the
142 \&\f(CW\*(C`MANIFEST\*(C'\fR file. An optional file \f(CW\*(C`MANIFEST.SKIP\*(C'\fR will be
143 consulted. Any file matching a regular expression in such a file will
144 not be reported as missing in the \f(CW\*(C`MANIFEST\*(C'\fR file. The list of any
145 extraneous files found is returned, and by default also reported to
146 STDERR.
147 .SS fullcheck
148 .IX Subsection "fullcheck"
149 .Vb 1
150 \& my($missing, $extra) = fullcheck();
151 .Ve
152 .PP
153 does both a \fBmanicheck()\fR and a \fBfilecheck()\fR, returning then as two array
154 refs.
155 .SS skipcheck
156 .IX Subsection "skipcheck"
157 .Vb 1
158 \& my @skipped = skipcheck();
159 .Ve
160 .PP
161 lists all the files that are skipped due to your \f(CW\*(C`MANIFEST.SKIP\*(C'\fR
162 file.
163 .SS maniread
164 .IX Subsection "maniread"
165 .Vb 2
166 \& my $manifest = maniread();
167 \& my $manifest = maniread($manifest_file);
168 .Ve
169 .PP
170 reads a named \f(CW\*(C`MANIFEST\*(C'\fR file (defaults to \f(CW\*(C`MANIFEST\*(C'\fR in the current
171 directory) and returns a HASH reference with files being the keys and
172 comments being the values of the HASH. Blank lines and lines which
173 start with \f(CW\*(C`#\*(C'\fR in the \f(CW\*(C`MANIFEST\*(C'\fR file are discarded.
174 .SS maniskip
175 .IX Subsection "maniskip"
176 .Vb 2
177 \& my $skipchk = maniskip();
178 \& my $skipchk = maniskip($manifest_skip_file);
179 \&
180 \& if ($skipchk\->($file)) { .. }
181 .Ve
182 .PP
183 reads a named \f(CW\*(C`MANIFEST.SKIP\*(C'\fR file (defaults to \f(CW\*(C`MANIFEST.SKIP\*(C'\fR in
184 the current directory) and returns a CODE reference that tests whether
185 a given filename should be skipped.
186 .SS manicopy
187 .IX Subsection "manicopy"
188 .Vb 2
189 \& manicopy(\e%src, $dest_dir);
190 \& manicopy(\e%src, $dest_dir, $how);
191 .Ve
192 .PP
193 Copies the files that are the keys in \f(CW%src\fR to the \f(CW$dest_dir\fR. \f(CW%src\fR is
194 typically returned by the \fBmaniread()\fR function.
195 .PP
196 .Vb 1
197 \& manicopy( maniread(), $dest_dir );
198 .Ve
199 .PP
200 This function is useful for producing a directory tree identical to the
201 intended distribution tree.
202 .PP
203 \&\f(CW$how\fR can be used to specify a different methods of "copying". Valid
204 values are \f(CW\*(C`cp\*(C'\fR, which actually copies the files, \f(CW\*(C`ln\*(C'\fR which creates
205 hard links, and \f(CW\*(C`best\*(C'\fR which mostly links the files but copies any
206 symbolic link to make a tree without any symbolic link. \f(CW\*(C`cp\*(C'\fR is the
207 default.
208 .SS maniadd
209 .IX Subsection "maniadd"
210 .Vb 1
211 \& maniadd({ $file => $comment, ...});
212 .Ve
213 .PP
214 Adds an entry to an existing \fIMANIFEST\fR unless its already there.
215 .PP
216 \&\f(CW$file\fR will be normalized (ie. Unixified). \fBUNIMPLEMENTED\fR
217 .SS MANIFEST
218 .IX Subsection "MANIFEST"
219 A list of files in the distribution, one file per line. The MANIFEST
220 always uses Unix filepath conventions even if you\*(Aqre not on Unix. This
221 means \fIfoo/bar\fR style not \fIfoo\ebar\fR.
222 .PP
223 Anything between white space and an end of line within a \f(CW\*(C`MANIFEST\*(C'\fR
224 file is considered to be a comment. Any line beginning with # is also
225 a comment. Beginning with ExtUtils::Manifest 1.52, a filename may
226 contain whitespace characters if it is enclosed in single quotes; single
227 quotes or backslashes in that filename must be backslash\-escaped.
228 .PP
229 .Vb 4
230 \& # this a comment
231 \& some/file
232 \& some/other/file comment about some/file
233 \& \*(Aqsome/third file\*(Aq comment
234 .Ve
235 .SS MANIFEST.SKIP
236 .IX Subsection "MANIFEST.SKIP"
237 The file MANIFEST.SKIP may contain regular expressions of files that
238 should be ignored by \fBmkmanifest()\fR and \fBfilecheck()\fR. The regular
239 expressions should appear one on each line. Blank lines and lines
240 which start with \f(CW\*(C`#\*(C'\fR are skipped. Use \f(CW\*(C`\e#\*(C'\fR if you need a regular
241 expression to start with a \f(CW\*(C`#\*(C'\fR.
242 .PP
243 For example:
244 .PP
245 .Vb 5
246 \& # Version control files and dirs.
247 \& \ebRCS\eb
248 \& \ebCVS\eb
249 \& ,v$
250 \& \eB\e.svn\eb
251 \&
252 \& # Makemaker generated files and dirs.
253 \& ^MANIFEST\e.
254 \& ^Makefile$
255 \& ^blib/
256 \& ^MakeMaker\-\ed
257 \&
258 \& # Temp, old and emacs backup files.
259 \& ~$
260 \& \e.old$
261 \& ^#.*#$
262 \& ^\e.#
263 .Ve
264 .PP
265 If no MANIFEST.SKIP file is found, a default set of skips will be
266 used, similar to the example above. If you want nothing skipped,
267 simply make an empty MANIFEST.SKIP file.
268 .PP
269 In one\*(Aqs own MANIFEST.SKIP file, certain directives
270 can be used to include the contents of other MANIFEST.SKIP
271 files. At present two such directives are recognized.
272 .IP #!include_default 4
273 .IX Item "#!include_default"
274 This tells ExtUtils::Manifest to read the default \fIMANIFEST.SKIP\fR
275 file and skip files accordingly, but \fInot\fR to include it in the local
276 \&\fIMANIFEST.SKIP\fR. This is intended to skip files according to a system
277 default, which can change over time without requiring further changes
278 to the distribution\*(Aqs \fIMANIFEST.SKIP\fR.
279 .IP "#!include /Path/to/another/manifest.skip" 4
280 .IX Item "#!include /Path/to/another/manifest.skip"
281 This inserts the contents of the specified external file in the local
282 \&\fIMANIFEST.SKIP\fR. This is intended for authors to have a central
283 \&\fIMANIFEST.SKIP\fR file, and to include it with their various distributions.
284 .PP
285 The included contents will be inserted into the MANIFEST.SKIP
286 file in between \fI#!start included /path/to/manifest.skip\fR
287 and \fI#!end included /path/to/manifest.skip\fR markers.
288 The original MANIFEST.SKIP is saved as MANIFEST.SKIP.bak.
289 .SS EXPORT_OK
290 .IX Subsection "EXPORT_OK"
291 \&\f(CW&mkmanifest\fR, \f(CW&manicheck\fR, \f(CW&filecheck\fR, \f(CW&fullcheck\fR,
292 \&\f(CW&maniread\fR, and \f(CW&manicopy\fR are exportable.
293 .SS "GLOBAL VARIABLES"
294 .IX Subsection "GLOBAL VARIABLES"
295 \&\f(CW$ExtUtils::Manifest::MANIFEST\fR defaults to \f(CW\*(C`MANIFEST\*(C'\fR. Changing it
296 results in both a different \f(CW\*(C`MANIFEST\*(C'\fR and a different
297 \&\f(CW\*(C`MANIFEST.SKIP\*(C'\fR file. This is useful if you want to maintain
298 different distributions for different audiences (say a user version
299 and a developer version including RCS).
300 .PP
301 \&\f(CW$ExtUtils::Manifest::Quiet\fR defaults to 0. If set to a true value,
302 all functions act silently.
303 .PP
304 \&\f(CW$ExtUtils::Manifest::Debug\fR defaults to 0. If set to a true value,
305 or if PERL_MM_MANIFEST_DEBUG is true, debugging output will be
306 produced.
307 .SH DIAGNOSTICS
308 .IX Header "DIAGNOSTICS"
309 All diagnostic output is sent to \f(CW\*(C`STDERR\*(C'\fR.
310 .ie n .IP """Not in MANIFEST:"" \fIfile\fR" 4
311 .el .IP "\f(CWNot in MANIFEST:\fR \fIfile\fR" 4
312 .IX Item "Not in MANIFEST: file"
313 is reported if a file is found which is not in \f(CW\*(C`MANIFEST\*(C'\fR.
314 .ie n .IP """Skipping"" \fIfile\fR" 4
315 .el .IP "\f(CWSkipping\fR \fIfile\fR" 4
316 .IX Item "Skipping file"
317 is reported if a file is skipped due to an entry in \f(CW\*(C`MANIFEST.SKIP\*(C'\fR.
318 .ie n .IP """No such file:"" \fIfile\fR" 4
319 .el .IP "\f(CWNo such file:\fR \fIfile\fR" 4
320 .IX Item "No such file: file"
321 is reported if a file mentioned in a \f(CW\*(C`MANIFEST\*(C'\fR file does not
322 exist.
323 .ie n .IP """MANIFEST:"" \fI$!\fR" 4
324 .el .IP "\f(CWMANIFEST:\fR \fI$!\fR" 4
325 .IX Item "MANIFEST: $!"
326 is reported if \f(CW\*(C`MANIFEST\*(C'\fR could not be opened.
327 .ie n .IP """Added to MANIFEST:"" \fIfile\fR" 4
328 .el .IP "\f(CWAdded to MANIFEST:\fR \fIfile\fR" 4
329 .IX Item "Added to MANIFEST: file"
330 is reported by \fBmkmanifest()\fR if \f(CW$Verbose\fR is set and a file is added
331 to MANIFEST. \f(CW$Verbose\fR is set to 1 by default.
332 .SH ENVIRONMENT
333 .IX Header "ENVIRONMENT"
334 .IP \fBPERL_MM_MANIFEST_DEBUG\fR 4
335 .IX Item "PERL_MM_MANIFEST_DEBUG"
336 Turns on debugging
337 .SH "SEE ALSO"
338 .IX Header "SEE ALSO"
339 ExtUtils::MakeMaker which has handy targets for most of the functionality.
340 .SH AUTHOR
341 .IX Header "AUTHOR"
342 Andreas Koenig \f(CW\*(C`[email protected]\*(C'\fR
343 .PP
344 Currently maintained by the Perl Toolchain Gang.
345 .SH "COPYRIGHT AND LICENSE"
346 .IX Header "COPYRIGHT AND LICENSE"
347 This software is copyright (c) 1996\- by Andreas Koenig.
348 .PP
349 This is free software; you can redistribute it and/or modify it under
350 the same terms as the Perl 5 programming language system itself.