This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
VMS build patch (from Peter Prymmer)
[perl5.git] / lib / lib.pm
CommitLineData
e50aee73
AD
1package lib;
2
17f410f9 3use 5.005_64;
4633a7c4
LW
4use Config;
5
c645ec3f
GS
6my $archname = defined($Config{'archname'}) ? $Config{'archname'} : '';
7my $ver = defined($Config{'version'}) ? $Config{'version'} : '';
8my @inc_version_list = defined($Config{'inc_version_list'}) ?
9 reverse split / /, $Config{'inc_version_list'} : ();
4633a7c4 10
17f410f9
GS
11our @ORIG_INC = @INC; # take a handy copy of 'original' value
12our $VERSION = '0.5564';
e50aee73
AD
13
14sub import {
15 shift;
aeb5d71d
GS
16
17 my %names;
a5f75d66 18 foreach (reverse @_) {
016609bc 19 if ($_ eq '') {
af3dad46 20 require Carp;
774d564b 21 Carp::carp("Empty compile time value given to use lib");
af3dad46 22 }
20408e3c
GS
23 if (-e && ! -d _) {
24 require Carp;
25 Carp::carp("Parameter to use lib must be directory, not file");
26 }
4633a7c4 27 unshift(@INC, $_);
29d82f8d
GS
28 # Add any previous version directories we found at configure time
29 foreach my $incver (@inc_version_list)
30 {
31 unshift(@INC, "$_/$incver") if -d "$_/$incver";
32 }
4633a7c4
LW
33 # Put a corresponding archlib directory infront of $_ if it
34 # looks like $_ has an archlib directory below it.
29d82f8d
GS
35 unshift(@INC, "$_/$ver") if -d "$_/$ver";
36 unshift(@INC, "$_/$ver/$archname") if -d "$_/$ver/$archname";
4633a7c4 37 }
abef537a
GS
38
39 # remove trailing duplicates
40 @INC = grep { ++$names{$_} == 1 } @INC;
41 return;
e50aee73
AD
42}
43
44
45sub unimport {
46 shift;
e50aee73
AD
47
48 my %names;
aeb5d71d 49 foreach (@_) {
4633a7c4
LW
50 ++$names{$_};
51 ++$names{"$_/$archname"} if -d "$_/$archname/auto";
52 }
e50aee73 53
aeb5d71d
GS
54 # Remove ALL instances of each named directory.
55 @INC = grep { !exists $names{$_} } @INC;
abef537a 56 return;
e50aee73
AD
57}
58
4633a7c4 591;
e50aee73
AD
60__END__
61
62=head1 NAME
63
64lib - manipulate @INC at compile time
65
66=head1 SYNOPSIS
67
68 use lib LIST;
69
70 no lib LIST;
71
72=head1 DESCRIPTION
73
74This is a small simple module which simplifies the manipulation of @INC
75at compile time.
76
77It is typically used to add extra directories to perl's search path so
78that later C<use> or C<require> statements will find modules which are
79not located on perl's default search path.
80
aeb5d71d 81=head2 Adding directories to @INC
e50aee73
AD
82
83The parameters to C<use lib> are added to the start of the perl search
84path. Saying
85
86 use lib LIST;
87
4633a7c4 88is I<almost> the same as saying
e50aee73
AD
89
90 BEGIN { unshift(@INC, LIST) }
91
4633a7c4
LW
92For each directory in LIST (called $dir here) the lib module also
93checks to see if a directory called $dir/$archname/auto exists.
94If so the $dir/$archname directory is assumed to be a corresponding
95architecture specific directory and is added to @INC in front of $dir.
96
aeb5d71d
GS
97To avoid memory leaks, all trailing duplicate entries in @INC are
98removed.
4633a7c4 99
aeb5d71d 100=head2 Deleting directories from @INC
e50aee73
AD
101
102You should normally only add directories to @INC. If you need to
103delete directories from @INC take care to only delete those which you
104added yourself or which you are certain are not needed by other modules
105in your script. Other modules may have added directories which they
106need for correct operation.
107
aeb5d71d
GS
108The C<no lib> statement deletes all instances of each named directory
109from @INC.
e50aee73 110
4633a7c4
LW
111For each directory in LIST (called $dir here) the lib module also
112checks to see if a directory called $dir/$archname/auto exists.
113If so the $dir/$archname directory is assumed to be a corresponding
114architecture specific directory and is also deleted from @INC.
115
aeb5d71d 116=head2 Restoring original @INC
e50aee73
AD
117
118When the lib module is first loaded it records the current value of @INC
119in an array C<@lib::ORIG_INC>. To restore @INC to that value you
4633a7c4 120can say
e50aee73
AD
121
122 @INC = @lib::ORIG_INC;
123
e50aee73
AD
124
125=head1 SEE ALSO
126
af3dad46 127FindBin - optional module which deals with paths relative to the source file.
e50aee73
AD
128
129=head1 AUTHOR
130
131Tim Bunce, 2nd June 1995.
132
133=cut