This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
my email address changed
[perl5.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 42ce893..ab8d63f 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -163,9 +163,8 @@ way to make a "bundle" of your currently installed modules.
 The complete perl5 source tree takes up about 60 MB of disk space.
 After completing make, it takes up roughly 100 MB, though the actual
 total is likely to be quite system-dependent.  The installation
-directories need something on the order of 45 MB, though again that
-value is system-dependent.  A perl build with debug symbols and
--DDEBUGGING will require something on the order of 10 MB extra.
+directories need something on the order of 50 MB, though again that
+value is quite system-dependent.
 
 =head1 Start with a Fresh Distribution
 
@@ -194,17 +193,15 @@ version and architecture-specific questions and answers.  For example,
 the default directory for architecture-dependent library modules
 includes the version name.  By default, Configure will reuse your old
 name (e.g. /opt/perl/lib/i86pc-solaris/5.003) even if you're running
-Configure for a different version, e.g. 5.004.  Yes, Configure should
-probably check and correct for this, but it doesn't.  Similarly, if you
-used a shared libperl.so (see below) with version numbers, you will
-probably want to adjust them as well.
+Configure for a different version, e.g. 5.004.  Similarly, if you used
+a shared libperl.so (see below) with version numbers, you will probably
+want to adjust them as well.
 
 Also, be careful to check your architecture name.  For example, some
-Linux distributions use i386, while others may use i486.  If you build
-it yourself, Configure uses the output of the arch command, which
-might be i586 or i686 instead.  If you pick up a precompiled binary, or
-compile extensions on different systems, they might not all agree on
-the architecture name.
+Linux distributions use i386, but Configure uses the output of the arch
+command, which might be i686 instead.  If you pick up a precompiled
+binary, or compile extensions on different systems, they might not all
+agree on the architecture name.
 
 In short, if you wish to use your old config.sh, I recommend running
 Configure interactively rather than blindly accepting the defaults.
@@ -332,7 +329,12 @@ after the platform hints have been run by using Configure's -A switch.
 For example, here's how to add a couple of extra flags to C compiler
 invocations:
 
-       sh Configure -Accflags="-DPERL_Y2KWARN -DPERL_POLLUTE_MALLOC"
+       sh Configure -Accflags="-DPERL_EXTERNAL_GLOB -DPERL_POLLUTE_MALLOC"
+
+To clarify, those ccflags values are not Configure options; if passed to
+Configure directly, they won't do anything useful (that will define a config.sh
+variable, but without taking any action based upon it).  When passed to the
+compiler, those flags will activate #ifdefd code.
 
 For more help on Configure switches, run
 
@@ -470,33 +472,6 @@ line with
 
 or interactively at the appropriate Configure prompt.
 
-With the PerlIO abstraction layer, there is another possibility for
-the underlying IO calls, AT&T's "sfio".  This has superior performance
-to stdio.h in many cases, and is extensible by the use of "discipline"
-modules ("Native" PerlIO has them too).  Sfio currently only builds on
-a subset of the UNIX platforms perl supports.  Because the data
-structures are completely different from stdio, perl extension modules
-or external libraries may not work.  This configuration exists to
-allow these issues to be worked on.
-
-This option requires the 'sfio' package to have been built and installed.
-The latest sfio is available from http://www.research.att.com/sw/tools/sfio/
-
-You select this option by
-
-       sh Configure -Duseperlio -Dusesfio
-
-If you have already selected -Duseperlio, and if Configure detects
-that you have sfio, then sfio will be the default suggested by
-Configure.
-
-Note:  On some systems, sfio's iffe configuration script fails to
-detect that you have an atexit function (or equivalent).  Apparently,
-this is a problem at least for some versions of Linux and SunOS 4.
-Configure should detect this problem and warn you about problems with
-_exit vs. exit.  If you have this problem, the fix is to go back to
-your sfio sources and correct iffe's guess about atexit.
-
 =head3 Algorithmic Complexity Attacks on Hashes
 
 In Perls 5.8.0 and earlier it was easy to create degenerate hashes.
@@ -560,8 +535,7 @@ you can use the Configure command line option -Uusedl.
 
 Currently, for most systems, the main perl executable is built by
 linking the "perl library" libperl.a with perlmain.o, your static
-extensions (usually just DynaLoader.a) and various extra libraries,
-such as -lm.
+extensions, and various extra libraries, such as -lm.
 
 On some systems that support dynamic loading, it may be possible to
 replace libperl.a with a shared libperl.so.  If you anticipate building
@@ -666,21 +640,18 @@ to avoid these leaks. The default is now to perform direct manipulation
 whenever perl is running as a stand alone interpreter, and to call the safe
 but potentially leaky C<putenv()> function when the perl interpreter is
 embedded in another application. You can force perl to always use C<putenv()>
-by compiling with -DPERL_USE_SAVE_PUTENV. You can force an embedded perl to
+by compiling with -DPERL_USE_SAFE_PUTENV. You can force an embedded perl to
 use direct manipulation by setting C<PL_use_safe_putenv = 0;> after the
 C<perl_construct()> call.
 
 =head2 Installation Directories
 
 The installation directories can all be changed by answering the
-appropriate questions in Configure.  For convenience, all the
-installation questions are near the beginning of Configure.
-Do not include trailing slashes on directory names.
-
-I highly recommend running Configure interactively to be sure it puts
-everything where you want it.  At any point during the Configure
-process, you can answer a question with  &-d  and Configure will use
-the defaults from then on.  Alternatively, you can
+appropriate questions in Configure.  For convenience, all the installation
+questions are near the beginning of Configure.  Do not include trailing
+slashes on directory names.  At any point during the Configure process,
+you can answer a question with  &-d  and Configure will use the defaults
+from then on.  Alternatively, you can
 
        grep '^install' config.sh
 
@@ -858,23 +829,12 @@ entries to @INC.
 
 =item Man Pages
 
-In versions 5.005_57 and earlier, the default was to store module man
-pages in a version-specific directory, such as
-/usr/local/lib/perl5/$version/man/man3.  The default for 5.005_58 and
-after is /usr/local/man/man3 so that most users can find the man pages
-without resetting MANPATH.
-
-You can continue to use the old default from the command line with
-
-       sh Configure -Dman3dir=/usr/local/lib/perl5/5.9.0/man/man3
-
-Some users also prefer to use a .3pm suffix.  You can do that with
+By default, man pages will be installed in $man1dir and $man3dir, which
+are normally /usr/local/man/man1 and /usr/local/man/man3.  If you
+want to use a .3pm suffix for perl man pages, you can do that with
 
        sh Configure -Dman3ext=3pm
 
-Again, these are just the defaults, and can be changed as you run
-Configure.
-
 =item HTML pages
 
 Currently, the standard perl installation does not do anything with
@@ -923,10 +883,8 @@ wish to install perl into a different directory and use that
 management software to move perl to its final destination.  This
 section describes how to do that.
 
-Suppose you want to install perl under the /tmp/perl5 directory.  You
-could edit config.sh and change all the install* variables to point to
-/tmp/perl5 instead of /usr/local, or you could simply use the
-following command line:
+To install perl under the /tmp/perl5 directory, use the following
+command line:
 
        sh Configure -Dinstallprefix=/tmp/perl5
 
@@ -961,7 +919,12 @@ answers (such as installation directories and the local perl contact
 person) in the Policy.sh file.  If you want to build perl on another
 system using the same policy defaults, simply copy the Policy.sh file
 to the new system and Configure will use it along with the appropriate
-hint file for your system.
+hint file for your system. This will work even if Policy.sh was
+generated for another version of Perl, or on a system with a
+different architecture and/or operating system. However, in such cases,
+you should review the contents of the file before using it: for
+example, your new target may not keep its man pages in the same place
+as the system on which the file was generated.
 
 Alternatively, if you wish to change some or all of those policy
 answers, you should
@@ -1015,7 +978,21 @@ as usual, and Perl will be built in /tmp/perl/build/directory.
 
 You can run perl scripts under the perl debugger at any time with
 B<perl -d your_script>.  If, however, you want to debug perl itself,
-you probably want to do
+you probably want to have support for perl internal debugging code
+(activated by adding -DDEBUGGING to ccflags), and/or support for the
+system debugger by adding -g to optimize.
+
+       sh Configure -DDEBUGGING=<mode>
+
+For a more eye appealing call, -DEBUGGING is defined to be an alias
+for -DDEBUGGING. For both, the -U calls are also supported, in order
+to be able to overrule the hints or Policy.sh settings.
+
+=over 4
+
+=item -DEBUGGING=old
+
+Which is the default, and supports the old convention of
 
        sh Configure -Doptimize='-g'
 
@@ -1034,6 +1011,26 @@ L<"Propagating your changes to config.sh"> below.)
 You can actually specify -g and -DDEBUGGING independently, but usually
 it's convenient to have both.
 
+=over 4
+
+=item -DDEBUGGING
+
+=item -DEBUGGING
+
+=item -DEBUGGING=both
+
+Sets both -DDEBUGGING in the ccflags, and add -g to optimize.
+
+=item -DEBUGGING=-g
+
+Adds -g to optimize, but does not set -DDEBUGGING.
+
+=item -DEBUGGING=none
+
+Removes -g from optimize, and -DDEBUGGING from ccflags.
+
+=back
+
 If you are using a shared libperl, see the warnings about multiple
 versions of perl under L<Building a shared Perl library>.
 
@@ -1308,35 +1305,51 @@ instead.  You'll probably save yourself time in the long run.
 
 =item Hint files
 
-The perl distribution includes a number of system-specific hints files
-in the hints/ directory.  If one of them matches your system, Configure
-will offer to use that hint file.
+Hint files tell Configure about a number of things:
+
+=over 4
+
+=item o
+
+The peculiarities or conventions of particular platforms -- non-standard
+library locations and names, default installation locations for binaries,
+and so on.
+
+=item o
+
+The deficiencies of the platform -- for example, library functions that,
+although present, are too badly broken to be usable; or limits on
+resources that are generously available on most platforms.
+
+=item o
+
+How best to optimize for the platform, both in terms of binary size and/or
+speed, and for Perl feature support. Because of wide variations in the
+implementation of shared libraries and of threading, for example, Configure
+often needs hints in order to be able to use these features.
+
+=back
+
+The perl distribution includes many system-specific hints files
+in the hints/ directory. If one of them matches your system, Configure
+will offer to use that hint file. Unless you have a very good reason
+not to, you should accept its offer.
 
 Several of the hint files contain additional important information.
 If you have any problems, it is a good idea to read the relevant hint file
 for further information.  See hints/solaris_2.sh for an extensive example.
 More information about writing good hints is in the hints/README.hints
-file.
-
-=item *** WHOA THERE!!! ***
-
-Occasionally, Configure makes a wrong guess.  For example, on SunOS
-4.1.3, Configure incorrectly concludes that tzname[] is in the
-standard C library.  The hint file is set up to correct for this.  You
-will see a message:
+file, which also explains hint files known as callback-units.
 
-    *** WHOA THERE!!! ***
-       The recommended value for $d_tzname on this machine was "undef"!
-       Keep the recommended value? [y]
+Note that any hint file is read before any Policy file, meaning that
+Policy overrides hints -- see L</Site-wide Policy settings>.
 
-You should always keep the recommended value unless, after reading the
-relevant section of the hint file, you are sure you want to try
-overriding it.
+=item *** WHOA THERE!!! ***
 
-If you are re-using an old config.sh, the word "previous" will be
-used instead of "recommended".  Again, you will almost always want
-to keep the previous value, unless you have changed something on your
-system.
+If you are re-using an old config.sh, it's possible that Configure detects
+different values from the ones specified in this file.  You will almost
+always want to keep the previous value, unless you have changed something
+on your system.
 
 For example, suppose you have added libgdbm.a to your system
 and you decide to reconfigure perl to use GDBM_File.  When you run
@@ -1859,41 +1872,81 @@ to avoid the BIND.
 
 =head2 Cross-compilation
 
-Starting from version 5.8, Perl has the beginnings of cross-compilation
-support.  What is known to work is running Configure in a
-cross-compilation environment and building the miniperl executable.
-What is known not to work is building the perl executable because
-that would require building extensions: Dynaloader statically and
-File::Glob dynamically, for extensions one needs MakeMaker and
-MakeMaker is not yet cross-compilation aware, and neither is
-the main Makefile.
-
-Since the functionality is so lacking, it must be considered
-highly experimental.  It is so experimental that it is not even
-mentioned during an interactive Configure session, a direct command
-line invocation (detailed shortly) is required to access the
-functionality.
-
-    NOTE: Perl is routinely built using cross-compilation
-    in the EPOC environment, in the WinCE, and in the OpenZaurus
-    project, but all those use something slightly different setup
-    than what described here.  For the WinCE setup, read the
-    wince/README.compile.  For the OpenZaurus setup, read the
-    Cross/README.
-
-The one environment where this cross-compilation setup has
-successfully been used as of this writing is the Compaq iPAQ running
-ARM Linux.  The build host was Intel Linux, the networking setup was
-PPP + SSH.  The exact setup details are beyond the scope of this
-document, see http://www.handhelds.org/ for more information.
-
-To run Configure in cross-compilation mode the basic switch is
-C<-Dusecrosscompile>.
+Perl can be cross-compiled.  It is just not trivial, cross-compilation
+rarely is.  Perl is routinely cross-compiled for many platforms (as of
+June 2005 at least PocketPC aka WinCE, Open Zaurus, EPOC, Symbian, and
+the IBM OS/400).  These platforms are known as the B<target> platforms,
+while the systems where the compilation takes place are the B<host>
+platforms.
+
+What makes the situation difficult is that first of all,
+cross-compilation environments vary significantly in how they are set
+up and used, and secondly because the primary way of configuring Perl
+(using the rather large Unix-tool-dependent Configure script) is not
+awfully well suited for cross-compilation.  However, starting from
+version 5.8.0, the Configure script also knows one way of supporting
+cross-compilation support, please keep reading.
+
+See the following files for more information about compiling Perl for
+the particular platforms:
+
+=over 4
+
+=item WinCE/PocketPC
+
+README.ce
+
+=item Open Zaurus
+
+Cross/README
+
+=item EPOC
+
+README.epoc
+
+=item Symbian
+
+README.symbian
+
+=item OS/400
+
+README.os400
+
+=back
+
+Packaging and transferring either the core Perl modules or CPAN
+modules to the target platform is also left up to the each
+cross-compilation environment.  Often the cross-compilation target
+platforms are somewhat limited in diskspace: see the section
+L<Minimizing the Perl installation> to learn more of the minimal set
+of files required for a functional Perl installation.
+
+For some cross-compilation environments the Configure option
+C<-Dinstallprefix=...> might be handy, see L<Changing the installation
+directory>.
+
+About the cross-compilation support of Configure: what is known to
+work is running Configure in a cross-compilation environment and
+building the miniperl executable.  What is known not to work is
+building the perl executable because that would require building
+extensions: Dynaloader statically and File::Glob dynamically, for
+extensions one needs MakeMaker and MakeMaker is not yet
+cross-compilation aware, and neither is the main Makefile.
+
+The cross-compilation setup of Configure has successfully been used in
+at least two Linux cross-compilation environments.  The setups were
+both such that the host system was Intel Linux with a gcc built for
+cross-compiling into ARM Linux, and there was a SSH connection to the
+target system.
+
+To run Configure in cross-compilation mode the basic switch that
+has to be used is C<-Dusecrosscompile>.
 
    sh ./Configure -des -Dusecrosscompile -D...
 
 This will make the cpp symbol USE_CROSS_COMPILE and the %Config
-symbol C<usecrosscompile> available.
+symbol C<usecrosscompile> available, and C<xconfig.h> will be used
+for cross-compilation.
 
 During the Configure and build, certain helper scripts will be created
 into the Cross/ subdirectory.  The scripts are used to execute a
@@ -1957,13 +2010,23 @@ Putting it all together:
         -Dlibpth=/skiff/local/arm-linux/lib \
         -D...
 
-or if you are happy with the defaults
+or if you are happy with the defaults:
 
     sh ./Configure -des -Dusecrosscompile \
         -Dtargethost=so.me.ho.st \
         -Dcc=arm-linux-gcc \
         -D...
 
+Another example where the cross-compiler has been installed under
+F</usr/local/arm/2.95.5>:
+
+    sh ./Configure -des -Dusecrosscompile \
+        -Dtargethost=so.me.ho.st \
+        -Dcc=/usr/local/arm/2.95.5/bin/arm-linux-gcc \
+        -Dincpth=/usr/local/arm/2.95.5/include \
+        -Dusrinc=/usr/local/arm/2.95.5/include \
+        -Dlibpth=/usr/local/arm/2.95.5/lib
+
 =head1 make test
 
 This will run the regression tests on the perl you just made.  If
@@ -2135,13 +2198,13 @@ indicate the alternate name on the "make install" line, such as:
     make install PERLNAME=myperl
 
 You can separately change the base used for versioned names (like
-"perl5.005") by setting PERLNAME_VERBASE, like
+"perl5.8.9") by setting PERLNAME_VERBASE, like
 
     make install PERLNAME=perl5 PERLNAME_VERBASE=perl
 
 This can be useful if you have to install perl as "perl5" (e.g. to
 avoid conflicts with an ancient version in /usr/bin supplied by your vendor).
-Without this the versioned binary would be called "perl55.005".
+Without this the versioned binary would be called "perl55.8.8".
 
 =head2 Installing perl under a different directory
 
@@ -2153,7 +2216,6 @@ the DESTDIR variable during C<make install>, with a command like
 DESTDIR is automatically prepended to all the installation paths.  See
 the example in L<"Creating an installable tar archive"> above.
 
-
 =head2 Installed files
 
 If you want to see exactly what will happen without installing
@@ -2167,10 +2229,10 @@ make install will install the following:
     binaries
 
        perl,
-           perl5.nnn   where nnn is the current release number.  This
+           perl5.n.n   where 5.n.n is the current release number.  This
                        will be a link to perl.
        suidperl,
-           sperl5.nnn  If you requested setuid emulation.
+           sperl5.n.n  If you requested setuid emulation.
        a2p             awk-to-perl translator
 
     scripts
@@ -2246,8 +2308,8 @@ with 5.8.2, simply replace the '#!/usr/local/bin/perl' line at the
 top of the script with the particular version you want to run, e.g.
 #!/usr/local/bin/perl5.8.2.
 
-Usually, most extensions will probably not need to be recompiled to use
-with a newer version of Perl Here is how it is supposed to work.
+Usually, most extensions will probably not need to be recompiled to be
+used with a newer version of Perl.  Here is how it is supposed to work.
 (These examples assume you accept all the Configure defaults.)
 
 Suppose you already have version 5.005_03 installed.  The directories
@@ -2447,113 +2509,121 @@ Firstly, the bare minimum to run this script
      print("$f\n");
   }
 
-in Solaris is as follows (under $Config{prefix}):
+in Linux is as follows (under $Config{prefix}):
 
   ./bin/perl
-  ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/autosplit.ix
-  ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_expandspec.al
-  ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_find_symbol_anywhere.al
-  ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_findfile.al
-  ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/Glob.so
-  ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/autosplit.ix
-  ./lib/perl5/5.6.1/sun4-solaris-64int/Config.pm
-  ./lib/perl5/5.6.1/sun4-solaris-64int/XSLoader.pm
-  ./lib/perl5/5.6.1/sun4-solaris-64int/DynaLoader.pm
-  ./lib/perl5/5.6.1/sun4-solaris-64int/CORE/libperl.so
-  ./lib/perl5/5.6.1/strict.pm
-  ./lib/perl5/5.6.1/warnings.pm
-  ./lib/perl5/5.6.1/Carp.pm
-  ./lib/perl5/5.6.1/Exporter.pm
-  ./lib/perl5/5.6.1/File/Glob.pm
-  ./lib/perl5/5.6.1/AutoLoader.pm
-  ./lib/perl5/5.6.1/vars.pm
-  ./lib/perl5/5.6.1/warnings/register.pm
-  ./lib/perl5/5.6.1/Carp/Heavy.pm
-  ./lib/perl5/5.6.1/Exporter/Heavy.pm
+  ./lib/perl5/5.9.3/strict.pm
+  ./lib/perl5/5.9.3/warnings.pm
+  ./lib/perl5/5.9.3/i686-linux/File/Glob.pm
+  ./lib/perl5/5.9.3/i686-linux/XSLoader.pm
+  ./lib/perl5/5.9.3/i686-linux/auto/File/Glob/Glob.so
 
 Secondly, Debian perl-base package contains the following files,
-size about 1.2MB in its i386 version:
+size about 1.9MB in its i386 version:
 
-  /usr/share/doc/perl/Documentation
-  /usr/share/doc/perl/README.Debian
-  /usr/share/doc/perl/copyright
+  /usr/bin/perl
+  /usr/bin/perl5.8.4
+  /usr/lib/perl/5.8
+  /usr/lib/perl/5.8.4/B.pm
+  /usr/lib/perl/5.8.4/B/Deparse.pm
+  /usr/lib/perl/5.8.4/Config.pm
+  /usr/lib/perl/5.8.4/Cwd.pm
+  /usr/lib/perl/5.8.4/Data/Dumper.pm
+  /usr/lib/perl/5.8.4/DynaLoader.pm
+  /usr/lib/perl/5.8.4/Errno.pm
+  /usr/lib/perl/5.8.4/Fcntl.pm
+  /usr/lib/perl/5.8.4/File/Glob.pm
+  /usr/lib/perl/5.8.4/IO.pm
+  /usr/lib/perl/5.8.4/IO/File.pm
+  /usr/lib/perl/5.8.4/IO/Handle.pm
+  /usr/lib/perl/5.8.4/IO/Pipe.pm
+  /usr/lib/perl/5.8.4/IO/Seekable.pm
+  /usr/lib/perl/5.8.4/IO/Select.pm
+  /usr/lib/perl/5.8.4/IO/Socket.pm
+  /usr/lib/perl/5.8.4/POSIX.pm
+  /usr/lib/perl/5.8.4/Socket.pm
+  /usr/lib/perl/5.8.4/XSLoader.pm
+  /usr/lib/perl/5.8.4/auto/Cwd/Cwd.bs
+  /usr/lib/perl/5.8.4/auto/Cwd/Cwd.so
+  /usr/lib/perl/5.8.4/auto/Data/Dumper/Dumper.bs
+  /usr/lib/perl/5.8.4/auto/Data/Dumper/Dumper.so
+  /usr/lib/perl/5.8.4/auto/DynaLoader/DynaLoader.a
+  /usr/lib/perl/5.8.4/auto/DynaLoader/autosplit.ix
+  /usr/lib/perl/5.8.4/auto/DynaLoader/dl_expandspec.al
+  /usr/lib/perl/5.8.4/auto/DynaLoader/dl_find_symbol_anywhere.al
+  /usr/lib/perl/5.8.4/auto/DynaLoader/dl_findfile.al
+  /usr/lib/perl/5.8.4/auto/DynaLoader/extralibs.ld
+  /usr/lib/perl/5.8.4/auto/Fcntl/Fcntl.bs
+  /usr/lib/perl/5.8.4/auto/Fcntl/Fcntl.so
+  /usr/lib/perl/5.8.4/auto/File/Glob/Glob.bs
+  /usr/lib/perl/5.8.4/auto/File/Glob/Glob.so
+  /usr/lib/perl/5.8.4/auto/IO/IO.bs
+  /usr/lib/perl/5.8.4/auto/IO/IO.so
+  /usr/lib/perl/5.8.4/auto/POSIX/POSIX.bs
+  /usr/lib/perl/5.8.4/auto/POSIX/POSIX.so
+  /usr/lib/perl/5.8.4/auto/POSIX/autosplit.ix
+  /usr/lib/perl/5.8.4/auto/POSIX/load_imports.al
+  /usr/lib/perl/5.8.4/auto/Socket/Socket.bs
+  /usr/lib/perl/5.8.4/auto/Socket/Socket.so
+  /usr/lib/perl/5.8.4/lib.pm
+  /usr/lib/perl/5.8.4/re.pm
+  /usr/share/doc/perl-base
   /usr/share/doc/perl/AUTHORS.gz
+  /usr/share/doc/perl/Documentation
+  /usr/share/doc/perl/README.Debian.gz
   /usr/share/doc/perl/changelog.Debian.gz
+  /usr/share/doc/perl/copyright
   /usr/share/man/man1/perl.1.gz
-  /usr/share/perl/5.6.1/AutoLoader.pm
-  /usr/share/perl/5.6.1/Carp.pm
-  /usr/share/perl/5.6.1/Carp/Heavy.pm
-  /usr/share/perl/5.6.1/Cwd.pm
-  /usr/share/perl/5.6.1/Exporter.pm
-  /usr/share/perl/5.6.1/Exporter/Heavy.pm
-  /usr/share/perl/5.6.1/File/Spec.pm
-  /usr/share/perl/5.6.1/File/Spec/Unix.pm
-  /usr/share/perl/5.6.1/FileHandle.pm
-  /usr/share/perl/5.6.1/Getopt/Long.pm
-  /usr/share/perl/5.6.1/IO/Socket/INET.pm
-  /usr/share/perl/5.6.1/IO/Socket/UNIX.pm
-  /usr/share/perl/5.6.1/IPC/Open2.pm
-  /usr/share/perl/5.6.1/IPC/Open3.pm
-  /usr/share/perl/5.6.1/SelectSaver.pm
-  /usr/share/perl/5.6.1/Symbol.pm
-  /usr/share/perl/5.6.1/Text/Tabs.pm
-  /usr/share/perl/5.6.1/Text/Wrap.pm
-  /usr/share/perl/5.6.1/attributes.pm
-  /usr/share/perl/5.6.1/auto/Getopt/Long/GetOptions.al
-  /usr/share/perl/5.6.1/auto/Getopt/Long/FindOption.al
-  /usr/share/perl/5.6.1/auto/Getopt/Long/Configure.al
-  /usr/share/perl/5.6.1/auto/Getopt/Long/config.al
-  /usr/share/perl/5.6.1/auto/Getopt/Long/Croak.al
-  /usr/share/perl/5.6.1/auto/Getopt/Long/autosplit.ix
-  /usr/share/perl/5.6.1/base.pm
-  /usr/share/perl/5.6.1/constant.pm
-  /usr/share/perl/5.6.1/fields.pm
-  /usr/share/perl/5.6.1/integer.pm
-  /usr/share/perl/5.6.1/lib.pm
-  /usr/share/perl/5.6.1/locale.pm
-  /usr/share/perl/5.6.1/overload.pm
-  /usr/share/perl/5.6.1/strict.pm
-  /usr/share/perl/5.6.1/vars.pm
-  /usr/share/perl/5.6.1/warnings.pm
-  /usr/share/perl/5.6.1/warnings/register.pm
-  /usr/bin/perl
-  /usr/lib/perl/5.6.1/Config.pm
-  /usr/lib/perl/5.6.1/Data/Dumper.pm
-  /usr/lib/perl/5.6.1/DynaLoader.pm
-  /usr/lib/perl/5.6.1/Errno.pm
-  /usr/lib/perl/5.6.1/Fcntl.pm
-  /usr/lib/perl/5.6.1/File/Glob.pm
-  /usr/lib/perl/5.6.1/IO.pm
-  /usr/lib/perl/5.6.1/IO/File.pm
-  /usr/lib/perl/5.6.1/IO/Handle.pm
-  /usr/lib/perl/5.6.1/IO/Pipe.pm
-  /usr/lib/perl/5.6.1/IO/Seekable.pm
-  /usr/lib/perl/5.6.1/IO/Select.pm
-  /usr/lib/perl/5.6.1/IO/Socket.pm
-  /usr/lib/perl/5.6.1/POSIX.pm
-  /usr/lib/perl/5.6.1/Socket.pm
-  /usr/lib/perl/5.6.1/XSLoader.pm
-  /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.so
-  /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.bs
-  /usr/lib/perl/5.6.1/auto/DynaLoader/dl_findfile.al
-  /usr/lib/perl/5.6.1/auto/DynaLoader/dl_expandspec.al
-  /usr/lib/perl/5.6.1/auto/DynaLoader/dl_find_symbol_anywhere.al
-  /usr/lib/perl/5.6.1/auto/DynaLoader/autosplit.ix
-  /usr/lib/perl/5.6.1/auto/DynaLoader/DynaLoader.a
-  /usr/lib/perl/5.6.1/auto/DynaLoader/extralibs.ld
-  /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.so
-  /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.bs
-  /usr/lib/perl/5.6.1/auto/File/Glob/Glob.bs
-  /usr/lib/perl/5.6.1/auto/File/Glob/Glob.so
-  /usr/lib/perl/5.6.1/auto/File/Glob/autosplit.ix
-  /usr/lib/perl/5.6.1/auto/IO/IO.so
-  /usr/lib/perl/5.6.1/auto/IO/IO.bs
-  /usr/lib/perl/5.6.1/auto/POSIX/POSIX.bs
-  /usr/lib/perl/5.6.1/auto/POSIX/POSIX.so
-  /usr/lib/perl/5.6.1/auto/POSIX/autosplit.ix
-  /usr/lib/perl/5.6.1/auto/POSIX/load_imports.al
-  /usr/lib/perl/5.6.1/auto/Socket/Socket.so
-  /usr/lib/perl/5.6.1/auto/Socket/Socket.bs
+  /usr/share/perl/5.8
+  /usr/share/perl/5.8.4/AutoLoader.pm
+  /usr/share/perl/5.8.4/Carp.pm
+  /usr/share/perl/5.8.4/Carp/Heavy.pm
+  /usr/share/perl/5.8.4/Exporter.pm
+  /usr/share/perl/5.8.4/Exporter/Heavy.pm
+  /usr/share/perl/5.8.4/File/Spec.pm
+  /usr/share/perl/5.8.4/File/Spec/Unix.pm
+  /usr/share/perl/5.8.4/FileHandle.pm
+  /usr/share/perl/5.8.4/Getopt/Long.pm
+  /usr/share/perl/5.8.4/IO/Socket/INET.pm
+  /usr/share/perl/5.8.4/IO/Socket/UNIX.pm
+  /usr/share/perl/5.8.4/IPC/Open2.pm
+  /usr/share/perl/5.8.4/IPC/Open3.pm
+  /usr/share/perl/5.8.4/List/Util.pm
+  /usr/share/perl/5.8.4/Scalar/Util.pm
+  /usr/share/perl/5.8.4/SelectSaver.pm
+  /usr/share/perl/5.8.4/Symbol.pm
+  /usr/share/perl/5.8.4/Text/ParseWords.pm
+  /usr/share/perl/5.8.4/Text/Tabs.pm
+  /usr/share/perl/5.8.4/Text/Wrap.pm
+  /usr/share/perl/5.8.4/attributes.pm
+  /usr/share/perl/5.8.4/base.pm
+  /usr/share/perl/5.8.4/bytes.pm
+  /usr/share/perl/5.8.4/bytes_heavy.pl
+  /usr/share/perl/5.8.4/constant.pm
+  /usr/share/perl/5.8.4/fields.pm
+  /usr/share/perl/5.8.4/integer.pm
+  /usr/share/perl/5.8.4/locale.pm
+  /usr/share/perl/5.8.4/overload.pm
+  /usr/share/perl/5.8.4/strict.pm
+  /usr/share/perl/5.8.4/utf8.pm
+  /usr/share/perl/5.8.4/utf8_heavy.pl
+  /usr/share/perl/5.8.4/vars.pm
+  /usr/share/perl/5.8.4/warnings.pm
+  /usr/share/perl/5.8.4/warnings/register.pm
+
+A nice trick to find out the minimal set of Perl library files you will
+need to run a Perl program is
+
+   perl -e 'do "prog.pl"; END { print "$_\n" for sort keys %INC }'
+
+(this will not find libraries required in runtime, unfortunately, but
+it's a minimal set) and if you want to find out all the files you can
+use something like the below
+
+   strace perl -le 'do "x.pl"' 2>&1 | perl -nle '/^open\(\"(.+?)"/ && print $1'
+
+(The 'strace' is Linux-specific, other similar utilities include 'truss'
+and 'ktrace'.)
 
 =head1 DOCUMENTATION