From: Perl 5 Porters Date: Wed, 10 Jul 1996 23:21:48 +0000 (+0000) Subject: Update documentation X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=21c92a1de962a30d8936572d83b08b08e916d3e4;p=p5sagit%2Fp5-mst-13.2.git Update documentation --- diff --git a/lib/AutoLoader.pm b/lib/AutoLoader.pm index 566ca86..e24e139 100644 --- a/lib/AutoLoader.pm +++ b/lib/AutoLoader.pm @@ -15,8 +15,59 @@ AutoLoader - load functions only on demand =head1 DESCRIPTION -This module tells its users that functions in the FOOBAR package are to be -autoloaded from F. See L. +This module tells its users that functions in the FOOBAR package are +to be autoloaded from F. See +L and L. + +=head2 __END__ + +The module using the autoloader should have the special marker C<__END__> +prior to the actual subroutine declarations. All code that is before the +marker will be loaded and compiled when the module is used. At the marker, +perl will cease reading and parsing. See also the B module, a +utility that automatically splits a module into a collection of files for +autoloading. + +When a subroutine not yet in memory is called, the C function +attempts to locate it in a directory relative to the location of the module +file itself. As an example, assume F is located in +F. The autoloader will look for perl +subroutines for this package in F. +The C<.al> file is named using the subroutine name, sans package. + +=head2 Package Lexicals + +Package lexicals declared with C in the main block of a package using +the B will not be visible to auto-loaded functions, 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. + +The C pragma (see L) 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 AutoLoader vs. SelfLoader + +The B is a counterpart to the B module. Both delay +the loading of subroutines, but the B accomplishes the goal via +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, the B suffers a disadvantage in the one-time parsing of +the lines after C<__DATA__>, after which routines are cached. B +can also handle multiple packages in a file. + +B only reads code as it is requested, and in many cases should be +faster, but requires a machanism like B be used to create the +individual files. + +=head1 CAVEAT + +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 package warns of these potential +conflicts when used to split a module. =cut diff --git a/lib/AutoSplit.pm b/lib/AutoSplit.pm index f9e3ad6..b1d797a 100644 --- a/lib/AutoSplit.pm +++ b/lib/AutoSplit.pm @@ -16,14 +16,81 @@ AutoSplit - split a package for autoloading =head1 SYNOPSIS - perl -e 'use AutoSplit; autosplit_modules(@ARGV)' ... + perl -e 'use AutoSplit; autosplit_lib_modules(@ARGV)' ... + + use AutoSplit; autosplit($file, $dir, $keep, $check, $modtime); + +for perl versions 5.002 and later: + + perl -MAutoSplit -e 'autosplit($ARGV[0], $ARGV[1], $k, $chk, $modtime)' ... =head1 DESCRIPTION This function will split up your program into files that the AutoLoader -module can handle. Normally only used to build autoloading Perl library -modules, especially extensions (like POSIX). You should look at how -they're built out for details. +module can handle. It is used by both the standard perl libraries and by +the MakeMaker utility, to automatically configure libraries for autoloading. + +The C interface splits the specified file into a hierarchy +rooted at the directory C<$dir>. It creates directories as needed to reflect +class hierarchy, and creates the file F. This file acts as +both forward declaration of all package routines, and as timestamp for the +last update of the hierarchy. + +The remaining three arguments to C govern other options to the +autosplitter. If the third argument, I<$keep>, is false, then any pre-existing +C<.al> files in the autoload directory are removed if they are no longer +part of the module (obsoleted functions). The fourth argument, I<$check>, +instructs C to check the module currently being split to ensure +that it does include a C specification for the AutoLoader module, and +skips the module if AutoLoader is not detected. Lastly, the I<$modtime> +argument specifies that C is to check the modification time of the +module against that of the C file, and only split the module +if it is newer. + +Typical use of AutoSplit in the perl MakeMaker utility is via the command-line +with: + + perl -e 'use AutoSplit; autosplit($ARGV[0], $ARGV[1], 0, 1, 1)' + +Defined as a Make macro, it is invoked with file and directory arguments; +C will split the specified file into the specified directory and +delete obsolete C<.al> files, after checking first that the module does use +the AutoLoader, and ensuring that the module is not already currently split +in its current form (the modtime test). + +The C form is used in the building of perl. It takes +as input a list of files (modules) that are assumed to reside in a directory +B relative to the current directory. Each file is sent to the +autosplitter one at a time, to be split into the directory B. + +In both usages of the autosplitter, only subroutines defined following the +perl special marker I<__END__> are split out into separate files. Some +routines may be placed prior to this marker to force their immediate loading +and parsing. + +=head1 CAVEATS + +Currently, C cannot handle multiple package specifications +within one file. + +=head1 DIAGNOSTICS + +C will inform the user if it is necessary to create the top-level +directory specified in the invocation. It is preferred that the script or +installation process that invokes C have created the full directory +path ahead of time. This warning may indicate that the module is being split +into an incorrect path. + +C will warn the user of all subroutines whose name causes potential +file naming conflicts on machines with drastically limited (8 characters or +less) file name length. Since the subroutine name is used as the file name, +these warnings can aid in portability to such systems. + +Warnings are issued and the file skipped if C cannot locate either +the I<__END__> marker or a "package Name;"-style specification. + +C will also emit general diagnostics for inability to create +directories or files. =cut @@ -53,7 +120,7 @@ sub autosplit{ # This function is used during perl building/installation -# ./miniperl -e 'use AutoSplit; autosplit_modules(@ARGV)' ... +# ./miniperl -e 'use AutoSplit; autosplit_lib_modules(@ARGV)' ... sub autosplit_lib_modules{ my(@modules) = @_; # list of Module names