=head1 SYNOPSIS
-The basic steps to build and install perl5 on a Unix system are:
+First, make sure you are installing an up-to-date version of Perl. If
+you didn't get your Perl source from CPAN, check the latest version at
+<URL:http://www.perl.com/CPAN/src/>.
+
+The basic steps to build and install perl5 on a Unix system
+with all the defaults are:
rm -f config.sh Policy.sh
sh Configure -de
make test
make install
-Full configuration instructions can be found in the INSTALL file.
-
For information on non-Unix systems, see the section on
L<"Porting information"> below.
pod/perldelta.pod file. For more detailed information about specific
changes, see the Changes file.
-IMPORTANT NOTE: 5.005_53 and later releases do not export unadorned
-global symbols anymore. This means most CPAN modules probably won't
-build under this release without adding '-DPERL_POLLUTE' to ccflags
-in config.sh. This is not the default because we want the modules
-to get fixed *before* the 5.6 release. pod/perldelta.pod contains
-additional notes about this.
-
=head1 DESCRIPTION
This document is written in pod format as an easy way to indicate its
C<code> literal code
L<name> A link (cross reference) to name
-You should probably at least skim through this entire document before
+Although most of the defaults are probably fine for most users,
+you should probably at least skim through this entire document before
proceeding.
If you're building Perl on a non-Unix system, you should also read
there is a README file for your platform, then you should read
that too. Additional information is in the Porting/ directory.
-=head1 WARNING: This version is not binary compatible with Perl 5.005.
+=head1 WARNING: This version requires an extra step to build old extensions.
+
+5.005_53 and later releases do not export unadorned
+global symbols anymore. This means you may need to build older
+extensions that have not been updated for the new naming convention
+with:
+
+ perl Makefile.PL POLLUTE=1
+
+Alternatively, you can enable CPP symbol pollution wholesale by
+building perl itself with:
+
+ sh Configure -Accflags=-DPERL_POLLUTE
+
+pod/perldelta.pod contains more details about this.
+
+=head1 WARNING: This version may not be binary compatible with Perl 5.005.
+
+Using the default Configure options for building perl should get you
+a perl that will be binary compatible with the 5.005 release.
-If you have dynamically loaded extensions that you built under perl
-5.005, you will need to rebuild and reinstall those extensions to use
-them with 5.6. Pure perl modules should continue to work just fine
-without reinstallation. See the discussions below on L<"Coexistence
-with earlier versions of perl5"> and L<"Upgrading from 5.005 to
-5.6"> for more details.
+However, if you run Configure with any custom options, such as
+-Dusethreads, -Dusemultiplicity, -Dusemymalloc, -Ubincompat5005 etc.,
+the resulting perl will not be binary compatible. Under these
+circumstances, if you have dynamically loaded extensions that were
+built under perl 5.005, you will need to rebuild and reinstall all
+those extensions to use them with 5.6.
+
+Pure perl modules without XS or C code should continue to work fine
+without reinstallation. See the discussions below on
+L<"Coexistence with earlier versions of perl5"> and
+L<"Upgrading from 5.005 to 5.6"> for more details.
The standard extensions supplied with Perl will be handled automatically.
-In a related issue, old modules may possibly be affected by the
+On a related issue, old modules may possibly be affected by the
changes in the Perl language in the current release. Please see
pod/perldelta.pod (and pod/perl500Xdelta.pod) for a description of
-what's changed. See also your installed copy of the perllocal.pod
+what's changed. See your installed copy of the perllocal.pod
file for a (possibly incomplete) list of locally installed modules.
Also see CPAN::autobundle for one way to make a "bundle" of your
currently installed modules.
=head1 Space Requirements
-The complete perl5 source tree takes up about 15 MB of disk space.
-After completing make, it takes up roughly 20 MB, though the actual
+The complete perl5 source tree takes up about 20 MB of disk space.
+After completing make, it takes up roughly 30 MB, though the actual
total is likely to be quite system-dependent. The installation
-directories need something on the order of 15 MB, though again that
+directories need something on the order of 20 MB, though again that
value is system-dependent.
=head1 Start with a Fresh Distribution
After it runs, Configure will perform variable substitution on all the
*.SH files and offer to run make depend.
+=head2 Altering config.sh variables for C compiler switches etc.
+
+For most users, all of the Configure defaults are fine. Configure
+also has several convenient options which are all described below.
+However, if Configure doesn't have an option to do what you want,
+you can change Configure variables 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"
+
+For more help on Configure switches, run:
+
+ sh Configure -h
+
=head2 Common Configure options
Configure supports a number of useful options. Run B<Configure -h> to
=item Directories for the perl distribution
-By default, Configure will use the following directories for 5.6.
+By default, Configure will use the following directories for 5.6.0.
$version is the full perl version number, including subversion, e.g.
-5.6 or 5.6.1, and $archname is a string like sun4-sunos,
+5.6.0 or 5.6.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.
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. $apiversion
-is the perl version number (without subversion), e.g. 5.6.
+be used for installing those add-on modules and scripts.
Configure variable Default value
$siteprefix $prefix
$sitebin $siteprefix/bin
$sitescriptdir $siteprefix/bin
- $sitelib $siteprefix/lib/perl5/site_perl/
- $sitearch $siteprefix/lib/perl5/site_perl/$apiversion/$archname
+ $sitelib $siteprefix/lib/perl5/site_perl/$version
+ $sitearch $siteprefix/lib/perl5/site_perl/$version/$archname
$siteman1dir $siteprefix/man/man1
$siteman3dir $siteprefix/man/man3
$sitehtml1dir (none)
$sitehtml3dir (none)
By default, ExtUtils::MakeMaker will install architecture-independent
-modules into $sitelib/$apiversion and architecture-dependent modules
-into $sitearch.
+modules into $sitelib and architecture-dependent modules into $sitearch.
=item Directories for vendor-supplied add-on files
(The next ones are set only if vendorprefix is set.)
$vendorbin $vendorprefix/bin
$vendorscriptdir $vendorprefix/bin
- $vendorlib $vendorprefix/lib/perl5/vendor_perl/
- $vendorarch $vendorprefix/lib/perl5/vendor_perl/$apiversion/$archname
+ $vendorlib $vendorprefix/lib/perl5/vendor_perl/$version
+ $vendorarch $vendorprefix/lib/perl5/vendor_perl/$version/$archname
$vendorman1dir $vendorprefix/man/man1
$vendorman3dir $vendorprefix/man/man3
$vendorhtml1dir (none)
$sitebin /usr/local/bin
$sitescriptdir /usr/local/bin
- $sitelib /usr/local/lib/perl5/site_perl/
- $sitearch /usr/local/lib/perl5/site_perl/$apiversion/$archname
+ $sitelib /usr/local/lib/perl5/site_perl/$version
+ $sitearch /usr/local/lib/perl5/site_perl/$version/$archname
$siteman1dir /usr/local/man/man1
$siteman3dir /usr/local/man/man3
$vendorbin /usr/bin
$vendorscriptdir /usr/bin
- $vendorlib /usr/lib/perl5/vendor_perl/
- $vendorarch /usr/lib/perl5/vendor_perl/$apiversion/$archname
+ $vendorlib /usr/lib/perl5/vendor_perl/$version
+ $vendorarch /usr/lib/perl5/vendor_perl/$version/$archname
$vendorman1dir /usr/man/man1
$vendorman3dir /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. Note too how the vendor-supplied
-directories track $apiversion, rather than $version, to ease upgrading
-between maintenance subversions. See L<"Coexistence with earlier
-versions of perl5"> below for more details.
+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
You can continue to use the old default from the command line with
- sh Configure -Dman3dir=/usr/local/lib/perl5/5.6/man/man3
+ sh Configure -Dman3dir=/usr/local/lib/perl5/5.6.0/man/man3
Some users also prefer to use a .3pm suffix. You can do that with
suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib.
Thus, for example, if you Configure with
--Dprefix=/opt/perl, then the default library directories for 5.6 are
+-Dprefix=/opt/perl, then the default library directories for 5.6.0 are
Configure variable Default value
- $privlib /opt/perl/lib/5.6
- $archlib /opt/perl/lib/5.6/$archname
- $sitelib /opt/perl/lib/site_perl/5.6
- $sitearch /opt/perl/lib/site_perl/5.6/$archname
+ $privlib /opt/perl/lib/5.6.0
+ $archlib /opt/perl/lib/5.6.0/$archname
+ $sitelib /opt/perl/lib/site_perl/5.6.0
+ $sitearch /opt/perl/lib/site_perl/5.6.0/$archname
=head2 Changing the installation directory
to contain any valid shell commands. It will be run just after the
platform-specific hints files.
-Note: Since the directory hierarchy for 5.6 contains a number of
+Note: Since the directory hierarchy for 5.6.0 contains a number of
new vendor* and site* entries, your Policy.sh file will probably not
set them to your desired values. I encourage you to run Configure
interactively to be sure it puts things where you want them.
The default is to compile without thread support.
+As of v5.5.64, perl has two different internal threads implementations.
+The 5.005 version (5005threads) and an interpreter-based implementation
+(ithreads) with one interpreter per thread. By default, Configure selects
+ithreads if -Dusethreads is specified. However, you can select the old
+5005threads behavior instead by either
+
+ sh Configure -Dusethreads -Duse5005threads
+
+or by
+ sh Configure -Dusethreads -Uuseithreads
+
+Eventually (by perl v5.6.0) this internal confusion ought to disappear,
+and these options may disappear as well.
+
=head2 Selecting File IO mechanisms
Previous versions of perl used the standard IO mechanisms as defined in
To build a shared libperl, the environment variable controlling shared
library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
NeXTSTEP/OPENSTEP/Rhapsody, LIBRARY_PATH for BeOS, SHLIB_PATH for
-HP-UX, LIBPATH for AIX, PATH for cygwin) must be set up to include
+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.
If you are using a shared libperl, see the warnings about multiple
versions of perl under L<Building a shared libperl.so Perl library>.
-=head2 Other Compiler Flags
-
-For most users, all of the Configure defaults are fine. However, you
-can change a number of factors in the way perl is built by adding
-appropriate -D directives to your ccflags variable in config.sh.
-
-You should also run Configure interactively to verify that a hint file
-doesn't inadvertently override your ccflags setting. (Hints files
-shouldn't do that, but some might.)
-
=head2 Extensions
By default, Configure will offer to build every extension which appears
built by default, but you can skip it by setting the Configure variable
useopcode=false either in a hint file for from the command line.
-You can learn more about each of these extensions by consulting the
+If you unpack any additional extensions in the ext/ directory before
+running Configure, then Configure will offer to build those additional
+extensions as well. Most users probably shouldn't have to do this --
+it is usually easier to build additional extensions later after perl
+has been installed. However, if you wish to have those additional
+extensions statically linked into the perl binary, then this offers a
+convenient way to do that in one step. (It is not necessary, however;
+you can build and install extensions just fine even if you don't have
+dynamic loading. See lib/ExtUtils/MakeMaker.pm for more details.)
+
+You can learn more about each of the supplied extensions by consulting the
documentation in the individual .pm modules, located under the
ext/ subdirectory.
=item No sh
-If you don't have sh, you'll have to copy the sample file Porting/config_H
-to config.h and edit the config.h to reflect your system's peculiarities.
+If you don't have sh, you'll have to copy the sample file
+Porting/config.sh to config.sh and edit your config.sh to reflect your
+system's peculiarities. See Porting/pumpkin.pod for more information.
You'll probably also have to extensively modify the extension building
mechanism.
Specific information for the OS/2, Plan9, VMS and Win32 ports is in the
corresponding README files and subdirectories. Additional information,
including a glossary of all those config.sh variables, is in the Porting
-subdirectory. Especially Porting/Glossary should come in handy.
+subdirectory. Especially Porting/Glossary should come in handy.
Ports for other systems may also be available. You should check out
http://www.perl.com/CPAN/ports for current information on ports to
=item CRIPPLED_CC
-If you still can't compile successfully, try adding a -DCRIPPLED_CC
-flag. (Just because you get no errors doesn't mean it compiled right!)
-This simplifies some complicated expressions for compilers that get
-indigestion easily.
+If you still can't compile successfully, try:
+
+ sh Configure -Accflags=-DCRIPPLED_CC
+
+This flag simplifies some complicated expressions for compilers that get
+indigestion easily. (Just because you get no errors doesn't mean it
+compiled right!)
=item Missing functions
/usr/local/lib/perl5/site_perl/5.005/$archname
/usr/local/lib/perl5/site_perl/5.005
-Now, suppose you install version 5.6. The directories searched by
-version 5.6 will be
+Beginning with 5.6.0 the version number in the site libraries are
+fully versioned. Now, suppose you install version 5.6.0. The directories
+searched by version 5.6.0 will be
- /usr/local/lib/perl5/5.6/$archname
- /usr/local/lib/perl5/5.6
- /usr/local/lib/perl5/site_perl/5.6/$archname
- /usr/local/lib/perl5/site_perl/5.6
+ /usr/local/lib/perl5/5.6.0/$archname
+ /usr/local/lib/perl5/5.6.0
+ /usr/local/lib/perl5/site_perl/5.6.0/$archname
+ /usr/local/lib/perl5/site_perl/5.6.0
/usr/local/lib/perl5/site_perl/5.005/$archname
/usr/local/lib/perl5/site_perl/5.005
+ /usr/local/lib/perl5/site_perl/
-Notice the last two entries -- Perl understands the default structure
+Notice the last three entries -- Perl understands the default structure
of the $sitelib directories and will look back in older, compatible
directories. This way, modules installed under 5.005_03 will continue
-to be usable by 5.005_03 but will also accessible to 5.6. Further,
+to be usable by 5.005_03 but will also accessible to 5.6.0. Further,
suppose that you upgrade a module to one which requires features
-present only in 5.6. That new module will get installed into
-/usr/local/lib/perl5/site_perl/5.6 and will be available to 5.6,
+present only in 5.6.0. That new module will get installed into
+/usr/local/lib/perl5/site_perl/5.6.0 and will be available to 5.6.0,
but will not interfere with the 5.005_03 version.
-Also, by default, 5.6 will look in
-
- /usr/local/lib/perl5/site_perl/
-
-for 5.004-era pure perl modules.
+The last entry, /usr/local/lib/perl5/site_perl/, is there so that
+5.6.0 will look for 5.004-era pure perl modules.
-Lastly, suppose you now install version 5.6.1. The directories
-searched by 5.6.1 will be
+Lastly, suppose you now install version 5.6.1, which we'll assume is
+binary compatible with 5.6.0 and 5.005. The directories searched
+by 5.6.1 (if you don't change the Configure defaults) will be:
/usr/local/lib/perl5/5.6.1/$archname
/usr/local/lib/perl5/5.6.1
- /usr/local/lib/perl5/site_perl/5.6/$archname
- /usr/local/lib/perl5/site_perl/5.6
+ /usr/local/lib/perl5/site_perl/5.6.1/$archname
+ /usr/local/lib/perl5/site_perl/5.6.1
+
+ /usr/local/lib/perl5/site_perl/5.6.0/$archname
+ /usr/local/lib/perl5/site_perl/5.6.0
/usr/local/lib/perl5/site_perl/5.005/$archname
/usr/local/lib/perl5/site_perl/5.005
/usr/local/lib/perl5/site_perl/
-When you install an add-on extension, it gets installed into $sitelib (or
-$sitearch if it is architecture-specific). This directory deliberately
-does NOT include the sub-version number (01) so that both 5.6 and
-5.6.1 can use the extension.
-
-However, if you do run into problems, and you want to continue to use the
-old version of perl along with your extension, move those extension files
-to the appropriate version directory, such as $privlib (or $archlib).
-(The extension's .packlist file lists the files installed with that
-extension. For the Tk extension, for example, the list of files installed
-is in $sitearch/auto/Tk/.packlist.) Then use your newer version of perl
-to rebuild and re-install the extension into $sitelib. This way, Perl
-5.6 will find your files in the 5.6 directory, and newer versions
-of perl will find your newer extension in the $sitelib directory.
-(This is also why perl searches the site-specific libraries last.)
-
-Alternatively, if you are willing to reinstall all your modules
-every time you upgrade perl, then you can include the subversion
-number in $sitearch and $sitelib when you run Configure.
+Assuming the users in your site are still actively using perl 5.6.0 and
+5.005 after you installed 5.6.1, you can continue to install add-on
+extensions using any of perl 5.6.1, 5.6.0, or 5.005. The installations
+of these different versions remain distinct, but remember that the newer
+versions of perl are automatically set up to search the site libraries of
+the older ones. This means that installing a new extension with 5.005
+will make it visible to all three versions. Later, if you install the
+same extension using, say, perl 5.6.1, it will override the 5.005-installed
+version, but only for perl 5.6.1.
+
+This way, you can choose to share compatible extensions, but also upgrade
+to a newer version of an extension that may be incompatible with earlier
+versions, without breaking the earlier versions' installations.
=head2 Maintaining completely separate versions
Many users prefer to keep all versions of perl in completely
separate directories. This guarantees that an update to one version
-won't interfere with another version. One convenient way to do this
-is by using a separate prefix for each version, such as
+won't interfere with another version. (The defaults guarantee this for
+libraries after 5.6.0, but not for executables. TODO?) One convenient
+way to do this is by using a separate prefix for each version, such as
sh Configure -Dprefix=/opt/perl5.004
subversions may not have all the compatibility wrinkles ironed out
yet.
-=head2 Upgrading from 5.005 to 5.6
-
-Extensions built and installed with versions of perl prior to 5.005_50
-will need to be recompiled to be used with 5.005_50 and later. You will,
-however, be able to continue using 5.005 even after you install 5.6.
-The 5.005 binary will still be able to find the modules built under
-5.005; the 5.6 binary will look in the new $sitearch and $sitelib
-directories, and will not find them. See also your installed copy
-of the perllocal.pod file for a (possibly incomplete) list of locally
-installed modules. Note that you want perllocal.pod not perllocale.pod
-for installed module information.
+=head2 Upgrading from 5.005 to 5.6.0
+
+Most extensions built and installed with versions of perl
+prior to 5.005_50 will not need to be recompiled to be used with
+5.6.0. If you find you do need to rebuild an extension with 5.6.0,
+you may safely do so without disturbing the 5.005 installation.
+(See L<"Coexistence with earlier versions of perl5"> above.)
+
+See your installed copy of the perllocal.pod file for a (possibly
+incomplete) list of locally installed modules. Note that you want
+perllocal.pod not perllocale.pod for installed module information.
=head1 Coexistence with perl4
https://perl5.git.perl.org / perl5.git / blobdiff