This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: shared lib compilation problem with miniperl5.003_97
[perl5.git] / lib / AutoLoader.pm
CommitLineData
8990e307 1package AutoLoader;
a0d0e21e 2use Carp;
1a4c2889 3$DB::sub = $DB::sub; # Avoid warning
8990e307 4
f06db76b
AD
5=head1 NAME
6
7AutoLoader - load functions only on demand
8
9=head1 SYNOPSIS
10
11 package FOOBAR;
12 use Exporter;
13 use AutoLoader;
e14baed2 14 @ISA = qw(Exporter AutoLoader);
f06db76b
AD
15
16=head1 DESCRIPTION
17
21c92a1d 18This module tells its users that functions in the FOOBAR package are
19to be autoloaded from F<auto/$AUTOLOAD.al>. See
20L<perlsub/"Autoloading"> and L<AutoSplit>.
21
22=head2 __END__
23
24The module using the autoloader should have the special marker C<__END__>
25prior to the actual subroutine declarations. All code that is before the
26marker will be loaded and compiled when the module is used. At the marker,
27perl will cease reading and parsing. See also the B<AutoSplit> module, a
28utility that automatically splits a module into a collection of files for
29autoloading.
30
31When a subroutine not yet in memory is called, the C<AUTOLOAD> function
32attempts to locate it in a directory relative to the location of the module
33file itself. As an example, assume F<POSIX.pm> is located in
34F</usr/local/lib/perl5/POSIX.pm>. The autoloader will look for perl
35subroutines for this package in F</usr/local/lib/perl5/auto/POSIX/*.al>.
36The C<.al> file is named using the subroutine name, sans package.
37
e14baed2 38=head2 Loading Stubs
39
40The B<AutoLoader> module provide a special import() method that will
41load the stubs (from F<autosplit.ix> file) of the calling module.
42These stubs are needed to make inheritance work correctly for class
43modules.
44
45Modules that inherit from B<AutoLoader> should always ensure that they
46override the AutoLoader->import() method. If the module inherit from
47B<Exporter> like shown in the I<synopis> section this is already taken
48care of. For class methods an empty import() would do nicely:
49
50 package MyClass;
51 use AutoLoader; # load stubs
52 @ISA=qw(AutoLoader);
53 sub import {} # hide AutoLoader::import
54
55You can also set up autoloading by importing the AUTOLOAD function
56instead of inheriting from B<AutoLoader>:
57
58 package MyClass;
59 use AutoLoader; # load stubs
60 *AUTOLOAD = \&AutoLoader::AUTOLOAD;
61
62
21c92a1d 63=head2 Package Lexicals
64
65Package lexicals declared with C<my> in the main block of a package using
66the B<AutoLoader> will not be visible to auto-loaded functions, due to the
67fact that the given scope ends at the C<__END__> marker. A module using such
68variables as package globals will not work properly under the B<AutoLoader>.
69
70The C<vars> pragma (see L<perlmod/"vars">) may be used in such situations
71as an alternative to explicitly qualifying all globals with the package
72namespace. Variables pre-declared with this pragma will be visible to any
73autoloaded routines (but will not be invisible outside the package,
74unfortunately).
75
76=head2 AutoLoader vs. SelfLoader
77
78The B<AutoLoader> is a counterpart to the B<SelfLoader> module. Both delay
79the loading of subroutines, but the B<SelfLoader> accomplishes the goal via
80the C<__DATA__> marker rather than C<__END__>. While this avoids the use of
81a hierarchy of disk files and the associated open/close for each routine
82loaded, the B<SelfLoader> suffers a disadvantage in the one-time parsing of
83the lines after C<__DATA__>, after which routines are cached. B<SelfLoader>
84can also handle multiple packages in a file.
85
86B<AutoLoader> only reads code as it is requested, and in many cases should be
87faster, but requires a machanism like B<AutoSplit> be used to create the
e14baed2 88individual files. The B<ExtUtils::MakeMaker> will invoke B<AutoSplit>
89automatically if the B<AutoLoader> is used in a module source file.
21c92a1d 90
91=head1 CAVEAT
92
93On systems with restrictions on file name length, the file corresponding to a
94subroutine may have a shorter name that the routine itself. This can lead to
95conflicting file names. The I<AutoSplit> package warns of these potential
96conflicts when used to split a module.
f06db76b
AD
97
98=cut
99
8990e307 100AUTOLOAD {
5a556d17
NIS
101 my $name;
102 # Braces used to preserve $1 et al.
103 {
104 my ($pkg,$func) = $AUTOLOAD =~ /(.*)::([^:]+)$/;
105 $pkg =~ s#::#/#g;
106 if (defined($name=$INC{"$pkg.pm"}))
107 {
108 $name =~ s#^(.*)$pkg\.pm$#$1auto/$pkg/$func.al#;
109 $name = undef unless (-r $name);
110 }
111 unless (defined $name)
112 {
113 $name = "auto/$AUTOLOAD.al";
114 $name =~ s#::#/#g;
115 }
116 }
e14baed2 117 my $save = $@;
8990e307
LW
118 eval {require $name};
119 if ($@) {
e14baed2 120 if (substr($AUTOLOAD,-9) eq '::DESTROY') {
4633a7c4 121 *$AUTOLOAD = sub {};
e14baed2 122 } else {
123 # The load might just have failed because the filename was too
124 # long for some old SVR3 systems which treat long names as errors.
125 # If we can succesfully truncate a long name then it's worth a go.
126 # There is a slight risk that we could pick up the wrong file here
127 # but autosplit should have warned about that when splitting.
128 if ($name =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
129 eval {require $name};
130 }
131 if ($@){
132 $@ =~ s/ at .*\n//;
133 croak $@;
134 }
a0d0e21e 135 }
8990e307 136 }
e14baed2 137 $@ = $save;
5b930e62 138 $DB::sub = $AUTOLOAD; # Now debugger know where we are.
8990e307
LW
139 goto &$AUTOLOAD;
140}
f06db76b 141
c2960299
AD
142sub import {
143 my ($callclass, $callfile, $callline,$path,$callpack) = caller(0);
144 ($callpack = $callclass) =~ s#::#/#;
145 # Try to find the autosplit index file. Eg., if the call package
146 # is POSIX, then $INC{POSIX.pm} is something like
147 # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
148 # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
149 #
150 # However, if @INC is a relative path, this might not work. If,
151 # for example, @INC = ('lib'), then
152 # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
153 # 'auto/POSIX/autosplit.ix' (without the leading 'lib').
154 #
155 if (defined($path = $INC{$callpack . '.pm'})) {
156 # Try absolute path name.
157 $path =~ s#^(.*)$callpack\.pm$#$1auto/$callpack/autosplit.ix#;
158 eval { require $path; };
159 # If that failed, try relative path with normal @INC searching.
160 if ($@) {
161 $path ="auto/$callpack/autosplit.ix";
162 eval { require $path; };
163 }
164 carp $@ if ($@);
f06db76b 165 }
f06db76b 166}
8990e307
LW
167
1681;