Debian Codegraph @

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