Debian Codegraph @

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