Debian Codegraph @

upstream/mageia-cauldron/man3pm/lib.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 "lib 3pm"
61 .TH lib 3pm 2026-05-26 "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 lib \- manipulate @INC at compile time
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use lib LIST;
72 \&
73 \& no lib LIST;
74 .Ve
75 .SH DESCRIPTION
76 .IX Header "DESCRIPTION"
77 This is a small simple module which simplifies the manipulation of \f(CW@INC\fR
78 at compile time.
79 .PP
80 It is typically used to add extra directories to perl\*(Aqs search path so
81 that later \f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR statements will find modules which are
82 not located on perl\*(Aqs default search path.
83 .ie n .SS "Adding directories to @INC"
84 .el .SS "Adding directories to \f(CW@INC\fP"
85 .IX Subsection "Adding directories to @INC"
86 The parameters to \f(CW\*(C`use lib\*(C'\fR are added to the start of the perl search
87 path. Saying
88 .PP
89 .Vb 1
90 \& use lib LIST;
91 .Ve
92 .PP
93 is \fIalmost\fR the same as saying
94 .PP
95 .Vb 1
96 \& BEGIN { unshift(@INC, LIST) }
97 .Ve
98 .PP
99 For each directory in LIST (called \f(CW$dir\fR here) the lib module also
100 checks to see if a directory called \f(CW$dir\fR/$archname/auto exists.
101 If so the \f(CW$dir\fR/$archname directory is assumed to be a corresponding
102 architecture specific directory and is added to \f(CW@INC\fR in front of \f(CW$dir\fR.
103 lib.pm also checks if directories called \f(CW$dir\fR/$version and \f(CW$dir\fR/$version/$archname
104 exist and adds these directories to \f(CW@INC\fR.
105 .PP
106 The current value of \f(CW$archname\fR can be found with this command:
107 .PP
108 .Vb 1
109 \& perl \-V:archname
110 .Ve
111 .PP
112 The corresponding command to get the current value of \f(CW$version\fR is:
113 .PP
114 .Vb 1
115 \& perl \-V:version
116 .Ve
117 .PP
118 To avoid memory leaks, all trailing duplicate entries in \f(CW@INC\fR are
119 removed.
120 .ie n .SS "Deleting directories from @INC"
121 .el .SS "Deleting directories from \f(CW@INC\fP"
122 .IX Subsection "Deleting directories from @INC"
123 You should normally only add directories to \f(CW@INC\fR. If you need to
124 delete directories from \f(CW@INC\fR take care to only delete those which you
125 added yourself or which you are certain are not needed by other modules
126 in your script. Other modules may have added directories which they
127 need for correct operation.
128 .PP
129 The \f(CW\*(C`no lib\*(C'\fR statement deletes all instances of each named directory
130 from \f(CW@INC\fR.
131 .PP
132 For each directory in LIST (called \f(CW$dir\fR here) the lib module also
133 checks to see if a directory called \f(CW$dir\fR/$archname/auto exists.
134 If so the \f(CW$dir\fR/$archname directory is assumed to be a corresponding
135 architecture specific directory and is also deleted from \f(CW@INC\fR. lib.pm also
136 checks if directories called \f(CW$dir\fR/$version and \f(CW$dir\fR/$version/$archname
137 exist and deletes these directories from \f(CW@INC\fR.
138 .ie n .SS "Restoring original @INC"
139 .el .SS "Restoring original \f(CW@INC\fP"
140 .IX Subsection "Restoring original @INC"
141 When the lib module is first loaded it records the current value of \f(CW@INC\fR
142 in an array \f(CW@lib::ORIG_INC\fR. To restore \f(CW@INC\fR to that value you
143 can say
144 .PP
145 .Vb 1
146 \& @INC = @lib::ORIG_INC;
147 .Ve
148 .SH CAVEATS
149 .IX Header "CAVEATS"
150 In order to keep lib.pm small and simple, it only works with Unix
151 filepaths. This doesn\*(Aqt mean it only works on Unix, but non\-Unix
152 users must first translate their file paths to Unix conventions.
153 .PP
154 .Vb 3
155 \& # VMS users wanting to put [.stuff.moo] into
156 \& # their @INC would write
157 \& use lib \*(Aqstuff/moo\*(Aq;
158 .Ve
159 .SH NOTES
160 .IX Header "NOTES"
161 In the future, this module will likely use File::Spec for determining
162 paths, as it does now for Mac OS (where Unix\-style or Mac\-style paths
163 work, and Unix\-style paths are converted properly to Mac\-style paths
164 before being added to \f(CW@INC\fR).
165 .PP
166 If you try to add a file to \f(CW@INC\fR as follows:
167 .PP
168 .Vb 1
169 \& use lib \*(Aqthis_is_a_file.txt\*(Aq;
170 .Ve
171 .PP
172 \&\f(CW\*(C`lib\*(C'\fR will warn about this. The sole exceptions are files with the
173 \&\f(CW\*(C`.par\*(C'\fR extension which are intended to be used as libraries.
174 .SH "SEE ALSO"
175 .IX Header "SEE ALSO"
176 FindBin \- optional module which deals with paths relative to the source file.
177 .PP
178 PAR \- optional module which can treat \f(CW\*(C`.par\*(C'\fR files as Perl libraries.
179 .SH AUTHOR
180 .IX Header "AUTHOR"
181 Tim Bunce, 2nd June 1995.
182 .PP
183 \&\f(CW\*(C`lib\*(C'\fR is maintained by the perl5\-porters. Please direct
184 any questions to the canonical mailing list. Anything that
185 is applicable to the CPAN release can be sent to its maintainer,
186 though.
187 .PP
188 Maintainer: The Perl5\-Porters <perl5\[email protected]>
189 .PP
190 Maintainer of the CPAN release: Steffen Mueller <[email protected]>
191 .SH "COPYRIGHT AND LICENSE"
192 .IX Header "COPYRIGHT AND LICENSE"
193 This package has been part of the perl core since perl 5.001.
194 It has been released separately to CPAN so older installations
195 can benefit from bug fixes.
196 .PP
197 This package has the same copyright and license as the perl core.