[p5sagit/p5-mst-13.2.git] / lib / AutoLoader.pm

package AutoLoader;

use 5.005_64;
our(@EXPORT, @EXPORT_OK, $VERSION);

my $is_dosish;
my $is_epoc;
my $is_vms;

BEGIN {
    require Exporter;
    @EXPORT = @EXPORT = ();
    @EXPORT_OK = @EXPORT_OK = qw(AUTOLOAD);
    $is_dosish = $^O eq 'dos' || $^O eq 'os2' || $^O eq 'MSWin32';
    $is_epoc = $^O eq 'epoc';
    $is_vms = $^O eq 'VMS';
    $VERSION = '5.57';
}

AUTOLOAD {
    my $sub = $AUTOLOAD;
    my $filename;
    # Braces used to preserve $1 et al.
    {
	# Try to find the autoloaded file from the package-qualified
	# name of the sub. e.g., if the sub needed is
	# Getopt::Long::GetOptions(), then $INC{Getopt/Long.pm} is
	# something like '/usr/lib/perl5/Getopt/Long.pm', and the
	# autoload file is '/usr/lib/perl5/auto/Getopt/Long/GetOptions.al'.
	#
	# However, if @INC is a relative path, this might not work.  If,
	# for example, @INC = ('lib'), then $INC{Getopt/Long.pm} is
	# 'lib/Getopt/Long.pm', and we want to require
	# 'auto/Getopt/Long/GetOptions.al' (without the leading 'lib').
	# In this case, we simple prepend the 'auto/' and let the
	# C<require> take care of the searching for us.

	my ($pkg,$func) = ($sub =~ /(.*)::([^:]+)$/);
	$pkg =~ s#::#/#g;
	if (defined($filename = $INC{"$pkg.pm"})) {
	    $filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s;

	    # if the file exists, then make sure that it is a
	    # a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al',
	    # or './lib/auto/foo/bar.al'.  This avoids C<require> searching
	    # (and failing) to find the 'lib/auto/foo/bar.al' because it
	    # looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib').

	    if (-r $filename) {
		unless ($filename =~ m|^/|s) {
		    if ($is_dosish) {
			unless ($filename =~ m{^([a-z]:)?[\\/]}is) {
			     $filename = "./$filename";
			}
		    }
		    elsif ($is_epoc) {
			unless ($filename =~ m{^([a-z?]:)?[\\/]}is) {
			     $filename = "./$filename";
			}
		    }elsif ($is_vms) {
			# XXX todo by VMSmiths
			$filename = "./$filename";
		    }
		    else {
			$filename = "./$filename";
		    }
		}
	    }
	    else {
		$filename = undef;
	    }
	}
	unless (defined $filename) {
	    # let C<require> do the searching
	    $filename = "auto/$sub.al";
	    $filename =~ s#::#/#g;
	}
    }
    my $save = $@;
    eval { local $SIG{__DIE__}; require $filename };
    if ($@) {
	if (substr($sub,-9) eq '::DESTROY') {
	    *$sub = sub {};
	} else {
	    # The load might just have failed because the filename was too
	    # long for some old SVR3 systems which treat long names as errors.
	    # If we can succesfully truncate a long name then it's worth a go.
	    # There is a slight risk that we could pick up the wrong file here
	    # but autosplit should have warned about that when splitting.
	    if ($filename =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
		eval { local $SIG{__DIE__}; require $filename };
	    }
	    if ($@){
		$@ =~ s/ at .*\n//;
		my $error = $@;
		require Carp;
		Carp::croak($error);
	    }
	}
    }
    $@ = $save;
    goto &$sub;
}

sub import {
    my $pkg = shift;
    my $callpkg = caller;

    #
    # Export symbols, but not by accident of inheritance.
    #

    if ($pkg eq 'AutoLoader') {
      local $Exporter::ExportLevel = 1;
      Exporter::import $pkg, @_;
    }

    #
    # Try to find the autosplit index file.  Eg., if the call package
    # is POSIX, then $INC{POSIX.pm} is something like
    # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
    # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
    #
    # However, if @INC is a relative path, this might not work.  If,
    # for example, @INC = ('lib'), then
    # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
    # 'auto/POSIX/autosplit.ix' (without the leading 'lib').
    #

    (my $calldir = $callpkg) =~ s#::#/#g;
    my $path = $INC{$calldir . '.pm'};
    if (defined($path)) {
	# Try absolute path name.
	$path =~ s#^(.*)$calldir\.pm$#$1auto/$calldir/autosplit.ix#;
	eval { require $path; };
	# If that failed, try relative path with normal @INC searching.
	if ($@) {
	    $path ="auto/$calldir/autosplit.ix";
	    eval { require $path; };
	}
	if ($@) {
	    my $error = $@;
	    require Carp;
	    Carp::carp($error);
	}
    } 
}

sub unimport {
  my $callpkg = caller;
  eval "package $callpkg; sub AUTOLOAD;";
}

1;

__END__

=head1 NAME

AutoLoader - load subroutines only on demand

=head1 SYNOPSIS

    package Foo;
    use AutoLoader 'AUTOLOAD';   # import the default AUTOLOAD subroutine

    package Bar;
    use AutoLoader;              # don't import AUTOLOAD, define our own
    sub AUTOLOAD {
        ...
        $AutoLoader::AUTOLOAD = "...";
        goto &AutoLoader::AUTOLOAD;
    }

=head1 DESCRIPTION

The B<AutoLoader> module works with the B<AutoSplit> module and the
C<__END__> token to defer the loading of some subroutines until they are
used rather than loading them all at once.

To use B<AutoLoader>, the author of a module has to place the
definitions of subroutines to be autoloaded after an C<__END__> token.
(See L<perldata>.)  The B<AutoSplit> module can then be run manually to
extract the definitions into individual files F<auto/funcname.al>.

B<AutoLoader> implements an AUTOLOAD subroutine.  When an undefined
subroutine in is called in a client module of B<AutoLoader>,
B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
file with a name related to the location of the file from which the
client module was read.  As an example, if F<POSIX.pm> is located in
F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
the C<.al> file has the same name as the subroutine, sans package.  If
such a file exists, AUTOLOAD will read and evaluate it,
thus (presumably) defining the needed subroutine.  AUTOLOAD will then
C<goto> the newly defined subroutine.

Once this process completes for a given function, it is defined, so
future calls to the subroutine will bypass the AUTOLOAD mechanism.

=head2 Subroutine Stubs

In order for object method lookup and/or prototype checking to operate
correctly even when methods have not yet been defined it is necessary to
"forward declare" each subroutine (as in C<sub NAME;>).  See
L<perlsub/"SYNOPSIS">.  Such forward declaration creates "subroutine
stubs", which are place holders with no code.

The AutoSplit and B<AutoLoader> modules automate the creation of forward
declarations.  The AutoSplit module creates an 'index' file containing
forward declarations of all the AutoSplit subroutines.  When the
AutoLoader module is 'use'd it loads these declarations into its callers
package.

Because of this mechanism it is important that B<AutoLoader> is always
C<use>d and not C<require>d.

=head2 Using B<AutoLoader>'s AUTOLOAD Subroutine

In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
explicitly import it:

    use AutoLoader 'AUTOLOAD';

=head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine

Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
They typically need to check for some special cases (such as constants)
and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.

Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
Instead, they should define their own AUTOLOAD subroutines along these
lines:

    use AutoLoader;
    use Carp;

    sub AUTOLOAD {
        my $sub = $AUTOLOAD;
        (my $constname = $sub) =~ s/.*:://;
        my $val = constant($constname, @_ ? $_[0] : 0);
        if ($! != 0) {
            if ($! =~ /Invalid/ || $!{EINVAL}) {
                $AutoLoader::AUTOLOAD = $sub;
                goto &AutoLoader::AUTOLOAD;
            }
            else {
                croak "Your vendor has not defined constant $constname";
            }
        }
        *$sub = sub { $val }; # same as: eval "sub $sub { $val }";
        goto &$sub;
    }

If any module's own AUTOLOAD subroutine has no need to fallback to the
AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
subroutines), then that module should not use B<AutoLoader> at all.

=head2 Package Lexicals

Package lexicals declared with C<my> in the main block of a package
using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
the fact that the given scope ends at the C<__END__> marker.  A module
using such variables as package globals will not work properly under the
B<AutoLoader>.

The C<vars> pragma (see L<perlmod/"vars">) may be used in such
situations as an alternative to explicitly qualifying all globals with
the package namespace.  Variables pre-declared with this pragma will be
visible to any autoloaded routines (but will not be invisible outside
the package, unfortunately).

=head2 Not Using AutoLoader

You can stop using AutoLoader by simply

	no AutoLoader;

=head2 B<AutoLoader> vs. B<SelfLoader>

The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
loading of subroutines.

B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
While this avoids the use of a hierarchy of disk files and the
associated open/close for each routine loaded, B<SelfLoader> suffers a
startup speed disadvantage in the one-time parsing of the lines after
C<__DATA__>, after which routines are cached.  B<SelfLoader> can also
handle multiple packages in a file.

B<AutoLoader> only reads code as it is requested, and in many cases
should be faster, but requires a mechanism like B<AutoSplit> be used to
create the individual files.  L<ExtUtils::MakeMaker> will invoke
B<AutoSplit> automatically if B<AutoLoader> is used in a module source
file.

=head1 CAVEATS

AutoLoaders prior to Perl 5.002 had a slightly different interface.  Any
old modules which use B<AutoLoader> should be changed to the new calling
style.  Typically this just means changing a require to a use, adding
the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
from C<@ISA>.

On systems with restrictions on file name length, the file corresponding
to a subroutine may have a shorter name that the routine itself.  This
can lead to conflicting file names.  The I<AutoSplit> package warns of
these potential conflicts when used to split a module.

AutoLoader may fail to find the autosplit files (or even find the wrong
ones) in cases where C<@INC> contains relative paths, B<and> the program
does C<chdir>.

=head1 SEE ALSO

L<SelfLoader> - an autoloader that doesn't use external files.

=cut
Commit	Line	Data
8990e307	1	package AutoLoader;
21c92a1d	2
17f410f9	3	use 5.005_64;
17f410f9	4	our(@EXPORT, @EXPORT_OK, $VERSION);
f06db76b	5
adaafad2	6	my $is_dosish;
ed79a026	7	my $is_epoc;
adaafad2	8	my $is_vms;
adaafad2	9
1be0b951	10	BEGIN {
1be0b951	11	require Exporter;
e3d0cac0	12	@EXPORT = @EXPORT = ();
e3d0cac0	13	@EXPORT_OK = @EXPORT_OK = qw(AUTOLOAD);
adaafad2	14	$is_dosish = $^O eq 'dos' \|\| $^O eq 'os2' \|\| $^O eq 'MSWin32';
ed79a026	15	$is_epoc = $^O eq 'epoc';
adaafad2	16	$is_vms = $^O eq 'VMS';
9426adcd	17	$VERSION = '5.57';
1be0b951	18	}
f06db76b	19
8990e307	20	AUTOLOAD {
7d4fbd98	21	my $sub = $AUTOLOAD;
7d4fbd98	22	my $filename;
5a556d17	23	# Braces used to preserve $1 et al.
5a556d17	24	{
adaafad2	25	# Try to find the autoloaded file from the package-qualified
	26	# name of the sub. e.g., if the sub needed is
	27	# Getopt::Long::GetOptions(), then $INC{Getopt/Long.pm} is
	28	# something like '/usr/lib/perl5/Getopt/Long.pm', and the
	29	# autoload file is '/usr/lib/perl5/auto/Getopt/Long/GetOptions.al'.
	30	#
	31	# However, if @INC is a relative path, this might not work. If,
	32	# for example, @INC = ('lib'), then $INC{Getopt/Long.pm} is
	33	# 'lib/Getopt/Long.pm', and we want to require
	34	# 'auto/Getopt/Long/GetOptions.al' (without the leading 'lib').
	35	# In this case, we simple prepend the 'auto/' and let the
	36	# C<require> take care of the searching for us.
	37
7d4fbd98	38	my ($pkg,$func) = ($sub =~ /(.*)::([^:]+)$/);
adaafad2	39	$pkg =~ s#::#/#g;
7d4fbd98	40	if (defined($filename = $INC{"$pkg.pm"})) {
14a089c5	41	$filename =~ s#^(.*)$pkg\.pm\z#$1auto/$pkg/$func.al#s;
adaafad2	42
	43	# if the file exists, then make sure that it is a
	44	# a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al',
	45	# or './lib/auto/foo/bar.al'. This avoids C<require> searching
	46	# (and failing) to find the 'lib/auto/foo/bar.al' because it
	47	# looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib').
	48
7d4fbd98	49	if (-r $filename) {
14a089c5	50	unless ($filename =~ m\|^/\|s) {
adaafad2	51	if ($is_dosish) {
14a089c5	52	unless ($filename =~ m{^([a-z]:)?[\\/]}is) {
7d4fbd98	53	$filename = "./$filename";
adaafad2	54	}
adaafad2	55	}
ed79a026	56	elsif ($is_epoc) {
	57	unless ($filename =~ m{^([a-z?]:)?[\\/]}is) {
	58	$filename = "./$filename";
	59	}
	60	}elsif ($is_vms) {
7d4fbd98	61	# XXX todo by VMSmiths
7d4fbd98	62	$filename = "./$filename";
adaafad2	63	}
adaafad2	64	else {
7d4fbd98	65	$filename = "./$filename";
adaafad2	66	}
	67	}
	68	}
	69	else {
7d4fbd98	70	$filename = undef;
adaafad2	71	}
adaafad2	72	}
7d4fbd98	73	unless (defined $filename) {
adaafad2	74	# let C<require> do the searching
7d4fbd98	75	$filename = "auto/$sub.al";
7d4fbd98	76	$filename =~ s#::#/#g;
adaafad2	77	}
5a556d17	78	}
e14baed2	79	my $save = $@;
7d4fbd98	80	eval { local $SIG{__DIE__}; require $filename };
8990e307	81	if ($@) {
7d4fbd98	82	if (substr($sub,-9) eq '::DESTROY') {
7d4fbd98	83	*$sub = sub {};
e14baed2	84	} else {
	85	# The load might just have failed because the filename was too
	86	# long for some old SVR3 systems which treat long names as errors.
	87	# If we can succesfully truncate a long name then it's worth a go.
	88	# There is a slight risk that we could pick up the wrong file here
	89	# but autosplit should have warned about that when splitting.
7d4fbd98	90	if ($filename =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
7d4fbd98	91	eval { local $SIG{__DIE__}; require $filename };
e14baed2	92	}
	93	if ($@){
	94	$@ =~ s/ at .*\n//;
fb73857a	95	my $error = $@;
	96	require Carp;
	97	Carp::croak($error);
e14baed2	98	}
a0d0e21e	99	}
8990e307	100	}
e14baed2	101	$@ = $save;
7d4fbd98	102	goto &$sub;
8990e307	103	}
1be0b951	104
c2960299	105	sub import {
1be0b951	106	my $pkg = shift;
	107	my $callpkg = caller;
	108
	109	#
	110	# Export symbols, but not by accident of inheritance.
	111	#
	112
e3d0cac0	113	if ($pkg eq 'AutoLoader') {
	114	local $Exporter::ExportLevel = 1;
	115	Exporter::import $pkg, @_;
	116	}
1be0b951	117
1be0b951	118	#
c2960299	119	# Try to find the autosplit index file. Eg., if the call package
	120	# is POSIX, then $INC{POSIX.pm} is something like
	121	# '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in
	122	# '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that.
	123	#
	124	# However, if @INC is a relative path, this might not work. If,
	125	# for example, @INC = ('lib'), then
	126	# $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require
	127	# 'auto/POSIX/autosplit.ix' (without the leading 'lib').
	128	#
1be0b951	129
1c1c7f20	130	(my $calldir = $callpkg) =~ s#::#/#g;
1be0b951	131	my $path = $INC{$calldir . '.pm'};
1be0b951	132	if (defined($path)) {
c2960299	133	# Try absolute path name.
1be0b951	134	$path =~ s#^(.*)$calldir\.pm$#$1auto/$calldir/autosplit.ix#;
c2960299	135	eval { require $path; };
	136	# If that failed, try relative path with normal @INC searching.
	137	if ($@) {
1be0b951	138	$path ="auto/$calldir/autosplit.ix";
c2960299	139	eval { require $path; };
c2960299	140	}
fb73857a	141	if ($@) {
	142	my $error = $@;
	143	require Carp;
	144	Carp::carp($error);
	145	}
f06db76b	146	}
f06db76b	147	}
8990e307	148
cb0cff20	149	sub unimport {
	150	my $callpkg = caller;
	151	eval "package $callpkg; sub AUTOLOAD;";
	152	}
	153
8990e307	154	1;
1be0b951	155
	156	__END__
	157
	158	=head1 NAME
	159
	160	AutoLoader - load subroutines only on demand
	161
	162	=head1 SYNOPSIS
	163
	164	package Foo;
	165	use AutoLoader 'AUTOLOAD'; # import the default AUTOLOAD subroutine
	166
	167	package Bar;
	168	use AutoLoader; # don't import AUTOLOAD, define our own
	169	sub AUTOLOAD {
	170	...
	171	$AutoLoader::AUTOLOAD = "...";
	172	goto &AutoLoader::AUTOLOAD;
	173	}
	174
	175	=head1 DESCRIPTION
	176
	177	The B<AutoLoader> module works with the B<AutoSplit> module and the
	178	C<__END__> token to defer the loading of some subroutines until they are
	179	used rather than loading them all at once.
	180
	181	To use B<AutoLoader>, the author of a module has to place the
	182	definitions of subroutines to be autoloaded after an C<__END__> token.
	183	(See L<perldata>.) The B<AutoSplit> module can then be run manually to
	184	extract the definitions into individual files F<auto/funcname.al>.
	185
	186	B<AutoLoader> implements an AUTOLOAD subroutine. When an undefined
	187	subroutine in is called in a client module of B<AutoLoader>,
	188	B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a
	189	file with a name related to the location of the file from which the
	190	client module was read. As an example, if F<POSIX.pm> is located in
	191	F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl
	192	subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/*.al>, where
	193	the C<.al> file has the same name as the subroutine, sans package. If
	194	such a file exists, AUTOLOAD will read and evaluate it,
	195	thus (presumably) defining the needed subroutine. AUTOLOAD will then
	196	C<goto> the newly defined subroutine.
	197
f610777f	198	Once this process completes for a given function, it is defined, so
1be0b951	199	future calls to the subroutine will bypass the AUTOLOAD mechanism.
	200
	201	=head2 Subroutine Stubs
	202
	203	In order for object method lookup and/or prototype checking to operate
	204	correctly even when methods have not yet been defined it is necessary to
	205	"forward declare" each subroutine (as in C<sub NAME;>). See
	206	L<perlsub/"SYNOPSIS">. Such forward declaration creates "subroutine
	207	stubs", which are place holders with no code.
	208
	209	The AutoSplit and B<AutoLoader> modules automate the creation of forward
	210	declarations. The AutoSplit module creates an 'index' file containing
	211	forward declarations of all the AutoSplit subroutines. When the
	212	AutoLoader module is 'use'd it loads these declarations into its callers
	213	package.
	214
	215	Because of this mechanism it is important that B<AutoLoader> is always
	216	C<use>d and not C<require>d.
	217
	218	=head2 Using B<AutoLoader>'s AUTOLOAD Subroutine
	219
	220	In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must>
	221	explicitly import it:
	222
	223	use AutoLoader 'AUTOLOAD';
	224
	225	=head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine
	226
	227	Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
	228	They typically need to check for some special cases (such as constants)
	229	and then fallback to B<AutoLoader>'s AUTOLOAD for the rest.
	230
	231	Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine.
	232	Instead, they should define their own AUTOLOAD subroutines along these
	233	lines:
	234
	235	use AutoLoader;
fb73857a	236	use Carp;
1be0b951	237
1be0b951	238	sub AUTOLOAD {
7d4fbd98	239	my $sub = $AUTOLOAD;
7d4fbd98	240	(my $constname = $sub) =~ s/.*:://;
1be0b951	241	my $val = constant($constname, @_ ? $_[0] : 0);
1be0b951	242	if ($! != 0) {
265f5c4a	243	if ($! =~ /Invalid/ \|\| $!{EINVAL}) {
7d4fbd98	244	$AutoLoader::AUTOLOAD = $sub;
1be0b951	245	goto &AutoLoader::AUTOLOAD;
	246	}
	247	else {
	248	croak "Your vendor has not defined constant $constname";
	249	}
	250	}
7d4fbd98	251	*$sub = sub { $val }; # same as: eval "sub $sub { $val }";
7d4fbd98	252	goto &$sub;
1be0b951	253	}
	254
	255	If any module's own AUTOLOAD subroutine has no need to fallback to the
	256	AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
	257	subroutines), then that module should not use B<AutoLoader> at all.
	258
	259	=head2 Package Lexicals
	260
	261	Package lexicals declared with C<my> in the main block of a package
	262	using B<AutoLoader> will not be visible to auto-loaded subroutines, due to
	263	the fact that the given scope ends at the C<__END__> marker. A module
	264	using such variables as package globals will not work properly under the
	265	B<AutoLoader>.
	266
	267	The C<vars> pragma (see L<perlmod/"vars">) may be used in such
	268	situations as an alternative to explicitly qualifying all globals with
	269	the package namespace. Variables pre-declared with this pragma will be
	270	visible to any autoloaded routines (but will not be invisible outside
	271	the package, unfortunately).
	272
cb0cff20	273	=head2 Not Using AutoLoader
	274
	275	You can stop using AutoLoader by simply
	276
	277	no AutoLoader;
	278
1be0b951	279	=head2 B<AutoLoader> vs. B<SelfLoader>
	280
	281	The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the
	282	loading of subroutines.
	283
	284	B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>.
	285	While this avoids the use of a hierarchy of disk files and the
	286	associated open/close for each routine loaded, B<SelfLoader> suffers a
	287	startup speed disadvantage in the one-time parsing of the lines after
	288	C<__DATA__>, after which routines are cached. B<SelfLoader> can also
	289	handle multiple packages in a file.
	290
	291	B<AutoLoader> only reads code as it is requested, and in many cases
f610777f	292	should be faster, but requires a mechanism like B<AutoSplit> be used to
1be0b951	293	create the individual files. L<ExtUtils::MakeMaker> will invoke
	294	B<AutoSplit> automatically if B<AutoLoader> is used in a module source
	295	file.
	296
	297	=head1 CAVEATS
	298
	299	AutoLoaders prior to Perl 5.002 had a slightly different interface. Any
	300	old modules which use B<AutoLoader> should be changed to the new calling
	301	style. Typically this just means changing a require to a use, adding
	302	the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader>
	303	from C<@ISA>.
	304
	305	On systems with restrictions on file name length, the file corresponding
	306	to a subroutine may have a shorter name that the routine itself. This
	307	can lead to conflicting file names. The I<AutoSplit> package warns of
	308	these potential conflicts when used to split a module.
	309
adaafad2	310	AutoLoader may fail to find the autosplit files (or even find the wrong
	311	ones) in cases where C<@INC> contains relative paths, B<and> the program
	312	does C<chdir>.
	313
1be0b951	314	=head1 SEE ALSO
	315
	316	L<SelfLoader> - an autoloader that doesn't use external files.
	317
	318	=cut