X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/0a08c020238096f33826419fc8f499789a1b40a2..200f06d0560bb35c44d4f11900efe1b9030aadea:/INSTALL
diff --git a/INSTALL b/INSTALL
index 7ac14ca..552c870 100644
--- a/INSTALL
+++ b/INSTALL
@@ -8,7 +8,8 @@ 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
.
-The basic steps to build and install perl5 on a Unix system are:
+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
@@ -42,20 +43,6 @@ For information on what's new in this release, see the
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 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 DESCRIPTION
This document is written in pod format as an easy way to indicate its
@@ -67,7 +54,8 @@ by lines beginning with '='. The other mark-up used is
C literal code
L 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
@@ -80,6 +68,22 @@ system. (Unixware users should use the svr4.sh hint file.) If
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 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
@@ -102,7 +106,7 @@ The standard extensions supplied with Perl will be handled automatically.
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.
@@ -124,12 +128,15 @@ If you succeed in automatically converting the sources to a K&R compatible
form, be sure to email perlbug@perl.com to let us know the steps you
followed. This will enable us to officially support this option.
+Although Perl can be compiled using a C++ compiler, the Configure script
+does not work with some C++ compilers.
+
=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
@@ -333,7 +340,7 @@ The directories set up by Configure fall into three broad categories.
=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.0 or 5.6.1, and $archname is a string like sun4-sunos,
determined by Configure. The full definitions of all Configure
@@ -360,23 +367,26 @@ the common style is shown here.
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. $version
-is the perl version number, e.g. 5.6.0.
+be used for installing those add-on modules and scripts.
Configure variable Default value
$siteprefix $prefix
$sitebin $siteprefix/bin
- $sitescriptdir $siteprefix/bin
+ $sitescript $siteprefix/bin
$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)
+ $siteman1 $siteprefix/man/man1
+ $siteman3 $siteprefix/man/man3
+ $sitehtml1 (none)
+ $sitehtml3 (none)
By default, ExtUtils::MakeMaker will install architecture-independent
modules into $sitelib and architecture-dependent modules into $sitearch.
+NOTE: As of 5.6.0, ExtUtils::MakeMaker will use $sitelib and $sitearch,
+but will not use the other site-specific directories. Volunteers to
+fix this are needed.
+
=item Directories for vendor-supplied add-on files
Lastly, if you are building a binary distribution of perl for
@@ -387,13 +397,13 @@ for you to use to distribute add-on modules.
$vendorprefix (none)
(The next ones are set only if vendorprefix is set.)
$vendorbin $vendorprefix/bin
- $vendorscriptdir $vendorprefix/bin
+ $vendorscript $vendorprefix/bin
$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)
- $vendorhtml3dir (none)
+ $vendorman1 $vendorprefix/man/man1
+ $vendorman3 $vendorprefix/man/man3
+ $vendorhtml1 (none)
+ $vendorhtml3 (none)
These are normally empty, but may be set as needed. For example,
a vendor might choose the following settings:
@@ -412,23 +422,26 @@ This would have the effect of setting the following:
$man3dir /usr/man/man3
$sitebin /usr/local/bin
- $sitescriptdir /usr/local/bin
+ $sitescript /usr/local/bin
$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
+ $siteman1 /usr/local/man/man1
+ $siteman3 /usr/local/man/man3
- $vendorbin /usr/bin
- $vendorscriptdir /usr/bin
+ $vendorbin /usr/bin
+ $vendorscript /usr/bin
$vendorlib /usr/lib/perl5/vendor_perl/$version
$vendorarch /usr/lib/perl5/vendor_perl/$version/$archname
- $vendorman1dir /usr/man/man1
- $vendorman3dir /usr/man/man3
+ $vendorman1 /usr/man/man1
+ $vendorman3 /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: As of 5.6.0, ExtUtils::MakeMaker does not use these directories.
+Volunteers to fix this are needed.
+
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
@@ -582,7 +595,7 @@ If the generated Policy.sh file is unsuitable, you may freely edit it
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.
@@ -737,7 +750,7 @@ You can elect to build a shared libperl by
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
+NeXTSTEP/OPENSTEP/Darwin, LIBRARY_PATH for BeOS, 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
@@ -881,7 +894,17 @@ the Configure command line. Similarly, the Opcode extension is always
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.
@@ -904,7 +927,7 @@ to turn off each extension:
SDBM_File (Always included by default)
Opcode useopcode
Socket d_socket
- Threads usethreads
+ Threads use5005threads
attrs (Always included by default)
Thus to skip the NDBM_File extension, you can use
@@ -1133,8 +1156,9 @@ $ccflags or $optimize, and then re-run
=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.
@@ -1179,7 +1203,7 @@ libgdbm under HP-UX 11.
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
@@ -1580,10 +1604,8 @@ external program.
On some systems, particularly those with smaller amounts of RAM, some
of the tests in t/op/pat.t may fail with an "Out of memory" message.
-Specifically, in perl5.004_64, tests 74 and 78 have been reported to
-fail on some systems. On my SparcStation IPC with 8 MB of RAM, test 78
-will fail if the system is running any other significant tasks at the
-same time.
+For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
+test 85 will fail if run under either t/TEST or t/harness.
Try stopping other jobs on the system and then running the test by itself:
@@ -1704,8 +1726,9 @@ searched by version 5.6.0 will be
/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.0. Further,
@@ -1714,11 +1737,8 @@ 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.0 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, which we'll assume is
binary compatible with 5.6.0 and 5.005. The directories searched
@@ -1775,15 +1795,15 @@ yet.
=head2 Upgrading from 5.005 to 5.6.0
-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.0 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.
+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