+=head3 Building a shared Perl library
+
+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.
+
+On some systems that support dynamic loading, it may be possible to
+replace libperl.a with a shared libperl.so. If you anticipate building
+several different perl binaries (e.g. by embedding libperl into
+different programs, or by using the optional compiler extension), then
+you might wish to build a shared libperl.so so that all your binaries
+can share the same library.
+
+The disadvantages are that there may be a significant performance
+penalty associated with the shared libperl.so, and that the overall
+mechanism is still rather fragile with respect to different versions
+and upgrades.
+
+In terms of performance, on my test system (Solaris 2.5_x86) the perl
+test suite took roughly 15% longer to run with the shared libperl.so.
+Your system and typical applications may well give quite different
+results.
+
+The default name for the shared library is typically something like
+libperl.so.6.2 (for Perl 5.6.2), or libperl.so.602, or simply
+libperl.so. Configure tries to guess a sensible naming convention
+based on your C library name. Since the library gets installed in a
+version-specific architecture-dependent directory, the exact name
+isn't very important anyway, as long as your linker is happy.
+
+For some systems (mostly SVR4), building a shared libperl is required
+for dynamic loading to work, and hence is already the default.
+
+You can elect to build a shared libperl by
+
+ sh Configure -Duseshrplib
+
+To build a shared libperl, the environment variable controlling shared
+library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
+NeXTSTEP/OPENSTEP/Darwin, LIBRARY_PATH for BeOS, LD_LIBRARY_PATH/SHLIB_PATH
+for HP-UX, LIBPATH for AIX, PATH for Cygwin) must be set up to include
+the Perl build directory because that's where the shared libperl will
+be created. Configure arranges makefile to have the correct shared
+library search settings. You can find the name of the environment
+variable Perl thinks works in your your system by
+
+ grep ldlibpthname config.sh
+
+However, there are some special cases where manually setting the
+shared library path might be required. For example, if you want to run
+something like the following with the newly-built but not-yet-installed
+./perl:
+
+ cd t; ./perl misc/failing_test.t
+or
+ ./perl -Ilib ~/my_mission_critical_test
+
+then you need to set up the shared library path explicitly.
+You can do this with
+
+ LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
+
+for Bourne-style shells, or
+
+ setenv LD_LIBRARY_PATH `pwd`
+
+for Csh-style shells. (This procedure may also be needed if for some
+unexpected reason Configure fails to set up makefile correctly.) (And
+again, it may be something other than LD_LIBRARY_PATH for you, see above.)
+
+You can often recognize failures to build/use a shared libperl from error
+messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
+for example:
+18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
+
+There is also an potential problem with the shared perl library if you
+want to have more than one "flavor" of the same version of perl (e.g.
+with and without -DDEBUGGING). For example, suppose you build and
+install a standard Perl 5.8.0 with a shared library. Then, suppose you
+try to build Perl 5.8.0 with -DDEBUGGING enabled, but everything else
+the same, including all the installation directories. How can you
+ensure that your newly built perl will link with your newly built
+libperl.so.8 rather with the installed libperl.so.8? The answer is
+that you might not be able to. The installation directory is encoded
+in the perl binary with the LD_RUN_PATH environment variable (or
+equivalent ld command-line option). On Solaris, you can override that
+with LD_LIBRARY_PATH; on Linux, you can only override at runtime via
+LD_PRELOAD, specifying the exact filename you wish to be used; and on
+Digital Unix, you can override LD_LIBRARY_PATH by setting the
+_RLD_ROOT environment variable to point to the perl build directory.
+
+In other words, it is generally not a good idea to try to build a perl
+with a shared library if $archlib/CORE/$libperl already exists from a
+previous build.
+
+A good workaround is to specify a different directory for the
+architecture-dependent library for your -DDEBUGGING version of perl.
+You can do this by changing all the *archlib* variables in config.sh to
+point to your new architecture-dependent library.
+
+=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
+
+ grep '^install' config.sh
+
+after Configure has run to verify the installation paths.
+
+The defaults are intended to be reasonable and sensible for most
+people building from sources. Those who build and distribute binary
+distributions or who export perl to a range of systems will probably
+need to alter them. If you are content to just accept the defaults,
+you can safely skip the next section.
+
+The directories set up by Configure fall into three broad categories.
+
+=over 4
+
+=item Directories for the perl distribution
+
+By default, Configure will use the following directories for 5.9.0.
+$version is the full perl version number, including subversion, e.g.
+5.9.0 or 5.9.1, and $archname is a string like sun4-sunos,
+determined by Configure. The full definitions of all Configure
+variables are in the file Porting/Glossary.
+
+ Configure variable Default value
+ $prefixexp /usr/local
+ $binexp $prefixexp/bin
+ $scriptdirexp $prefixexp/bin
+ $privlibexp $prefixexp/lib/perl5/$version
+ $archlibexp $prefixexp/lib/perl5/$version/$archname
+ $man1direxp $prefixexp/man/man1
+ $man3direxp $prefixexp/man/man3
+ $html1direxp (none)
+ $html3direxp (none)
+
+$prefixexp is generated from $prefix, with ~ expansion done to convert home
+directories into absolute paths. Similarly for the other variables listed. As
+file system calls do not do this, you should always reference the ...exp
+variables, to support users who build perl in their home directory.
+
+Actually, Configure recognizes the SVR3-style
+/usr/local/man/l_man/man1 directories, if present, and uses those
+instead. Also, if $prefix contains the string "perl", the library
+directories are simplified as described below. For simplicity, only
+the common style is shown here.
+
+=item Directories for site-specific add-on files
+
+After perl is installed, you may later wish to add modules (e.g. from
+CPAN) or scripts. Configure will set up the following directories to
+be used for installing those add-on modules and scripts.
+
+ Configure variable Default value
+ $siteprefixexp $prefixexp
+ $sitebinexp $siteprefixexp/bin
+ $sitescriptexp $siteprefixexp/bin
+ $sitelibexp $siteprefixexp/lib/perl5/site_perl/$version
+ $sitearchexp $siteprefixexp/lib/perl5/site_perl/$version/$archname
+ $siteman1direxp $siteprefixexp/man/man1
+ $siteman3direxp $siteprefixexp/man/man3
+ $sitehtml1direxp (none)
+ $sitehtml3direxp (none)
+
+By default, ExtUtils::MakeMaker will install architecture-independent
+modules into $sitelib and architecture-dependent modules into $sitearch.
+
+=item Directories for vendor-supplied add-on files
+
+Lastly, if you are building a binary distribution of perl for
+distribution, Configure can optionally set up the following directories
+for you to use to distribute add-on modules.
+
+ Configure variable Default value
+ $vendorprefixexp (none)
+ (The next ones are set only if vendorprefix is set.)
+ $vendorbinexp $vendorprefixexp/bin
+ $vendorscriptexp $vendorprefixexp/bin
+ $vendorlibexp
+ $vendorprefixexp/lib/perl5/vendor_perl/$version
+ $vendorarchexp
+ $vendorprefixexp/lib/perl5/vendor_perl/$version/$archname
+ $vendorman1direxp $vendorprefixexp/man/man1
+ $vendorman3direxp $vendorprefixexp/man/man3
+ $vendorhtml1direxp (none)
+ $vendorhtml3direxp (none)
+
+These are normally empty, but may be set as needed. For example,
+a vendor might choose the following settings:
+
+ $prefix /usr
+ $siteprefix /usr/local
+ $vendorprefix /usr
+
+This would have the effect of setting the following:
+
+ $binexp /usr/bin
+ $scriptdirexp /usr/bin
+ $privlibexp /usr/lib/perl5/$version
+ $archlibexp /usr/lib/perl5/$version/$archname
+ $man1direxp /usr/man/man1
+ $man3direxp /usr/man/man3
+
+ $sitebinexp /usr/local/bin
+ $sitescriptexp /usr/local/bin
+ $sitelibexp /usr/local/lib/perl5/site_perl/$version
+ $sitearchexp /usr/local/lib/perl5/site_perl/$version/$archname
+ $siteman1direxp /usr/local/man/man1
+ $siteman3direxp /usr/local/man/man3
+
+ $vendorbinexp /usr/bin
+ $vendorscriptexp /usr/bin
+ $vendorlibexp /usr/lib/perl5/vendor_perl/$version
+ $vendorarchexp /usr/lib/perl5/vendor_perl/$version/$archname
+ $vendorman1direxp /usr/man/man1
+ $vendorman3direxp /usr/man/man3
+
+Note how in this example, the vendor-supplied directories are in the
+/usr hierarchy, while the directories reserved for the end-user are in
+the /usr/local hierarchy.
+
+The entire installed library hierarchy is installed in locations with
+version numbers, keeping the installations of different versions distinct.
+However, later installations of Perl can still be configured to search the
+installed libraries corresponding to compatible earlier versions.
+See L<"Coexistence with earlier versions of perl5"> below for more details
+on how Perl can be made to search older version directories.
+
+Of course you may use these directories however you see fit. For
+example, you may wish to use $siteprefix for site-specific files that
+are stored locally on your own disk and use $vendorprefix for
+site-specific files that are stored elsewhere on your organization's
+network. One way to do that would be something like
+
+ sh Configure -Dsiteprefix=/usr/local -Dvendorprefix=/usr/share/perl
+
+=item otherlibdirs
+
+As a final catch-all, Configure also offers an $otherlibdirs
+variable. This variable contains a colon-separated list of additional
+directories to add to @INC. By default, it will be empty.
+Perl will search these directories (including architecture and
+version-specific subdirectories) for add-on modules and extensions.
+
+For example, if you have a bundle of perl libraries from a previous
+installation, perhaps in a strange place:
+
+ Configure -Dotherlibdirs=/usr/lib/perl5/site_perl/5.8.1
+
+=item APPLLIB_EXP
+
+There is one other way of adding paths to @INC at perl build time, and
+that is by setting the APPLLIB_EXP C pre-processor token to a colon-
+separated list of directories, like this
+
+ sh Configure -Accflags='-DAPPLLIB_EXP=\"/usr/libperl\"'
+
+The directories defined by APPLLIB_EXP get added to @INC I<first>,
+ahead of any others, and so provide a way to override the standard perl
+modules should you, for example, want to distribute fixes without
+touching the perl distribution proper. And, like otherlib dirs,
+version and architecture specific subdirectories are also searched, if
+present, at run time. Of course, you can still search other @INC
+directories ahead of those in APPLLIB_EXP by using any of the standard
+run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc.
+
+=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
+
+ 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
+HTML documentation, but that may change in the future. Further, some
+add-on modules may wish to install HTML documents. The html Configure
+variables listed above are provided if you wish to specify where such
+documents should be placed. The default is "none", but will likely
+eventually change to something useful based on user feedback.