X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=INSTALL;h=95c214538677fb786f59ab86b0e40808535837af;hb=1ff5bc37303d3f603211be08e5e01dac62fcfa6c;hp=08e7dd8bb78c48c3f62403bd44c7032f906e0db8;hpb=6c8d78fb324d7709ee76d3711608bab5f83d721f;p=p5sagit%2Fp5-mst-13.2.git
diff --git a/INSTALL b/INSTALL
index 08e7dd8..95c2145 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,62 +1,49 @@
+If you read this file _as_is_, just ignore the funny characters you see.
+It is written in the POD format (see pod/perlpod.pod) which is specially
+designed to be readable as is.
+
=head1 NAME
-Install - Build and Installation guide for perl5.
+Install - Build and Installation guide for perl 5.
=head1 SYNOPSIS
-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
-.
+First, make sure you have an up-to-date version of Perl. If you
+didn't get your Perl source from CPAN, check the latest version at
+http://www.cpan.org/src/. Perl uses a version scheme where even-numbered
+subreleases (like 5.8.x and 5.10.x) are stable maintenance releases and
+odd-numbered subreleases (like 5.7.x and 5.9.x) are unstable
+development releases. Development releases should not be used in
+production environments. Fixes and new features are first carefully
+tested in development releases and only if they prove themselves to be
+worthy will they be migrated to the maintenance releases.
-The basic steps to build and install perl5 on a Unix system
-with all the defaults are:
+The basic steps to build and install perl 5 on a Unix system with all
+the defaults are to run, from a freshly unpacked source tree:
- rm -f config.sh Policy.sh
sh Configure -de
make
make test
make install
- # You may also wish to add these:
- (cd /usr/include && h2ph *.h sys/*.h)
- (installhtml --help)
- (cd pod && make tex && )
-
Each of these is explained in further detail below.
-B: starting from the release 5.6.0, Perl uses a version
-scheme where even-numbered subreleases (like 5.6 and 5.8) are stable
-maintenance releases and odd-numbered subreleases (like 5.7) are
-unstable development releases. Development releases should not be
-used in production environments. Fixes and new features are first
-carefully tested in development releases and only if they prove
-themselves to be worthy will they be migrated to the maintenance
-releases.
-
The above commands will install Perl to /usr/local (or some other
platform-specific directory -- see the appropriate file in hints/.)
-If that's not okay with you, use
-
- rm -f config.sh Policy.sh
- sh Configure
- make
- make test
- make install
-
-For information on non-Unix systems, see the section on L<"Porting
-information"> below.
+If that's not okay with you, you can run Configure interactively, by
+just typing "sh Configure" (without the -de args). You can also specify
+any prefix location by adding "-Dprefix='/some/dir'" to Configure's args.
+To explicitly name the perl binary, use the command
+"make install PERLNAME=myperl".
-If "make install" just says "`install' is up to date" or something
-similar, you may be on a case-insensitive filesystems such as Mac's HFS+,
-and you should say "make install-all". (This confusion is brought to you
-by the Perl distribution having a file called INSTALL.)
+These options, and many more, are explained in further detail below.
If you have problems, corrections, or questions, please see
L<"Reporting Problems"> below.
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.
+pod/perl5110delta.pod file. For more information about how to find more
+specific detail about changes, see the Changes file.
=head1 DESCRIPTION
@@ -68,159 +55,48 @@ by lines beginning with '='. The other mark-up used is
B embolden text, used for switches, programs or commands
C literal code
L A link (cross reference) to name
+ F A filename
Although most of the defaults are probably fine for most users,
-you should probably at least skim through this entire document before
+you should probably at least skim through this document before
proceeding.
-If you're building Perl on a non-Unix system, you should also read
-the README file specific to your operating system, since this may
-provide additional or different instructions for building Perl. There
-are also README files for several flavors of Unix systems, such as
-Solaris, HP-UX, and AIX; if you have one of those systems, you should
-also read the README file specific to that system.
-
-If there is a hint file for your system (in the hints/ directory) you
-should also read that hint file for specific information for your
-system. (Unixware users should use the svr4.sh hint file.)
-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 rather old
-extensions that have not been updated for the current naming convention
-with:
-
- perl Makefile.PL POLLUTE=1
+In addition to this file, check if there is a README file specific to
+your operating system, since it may provide additional or different
+instructions for building Perl. If there is a hint file for your
+system (in the hints/ directory) you might also want to read it
+for even more information.
-Alternatively, you can enable CPP symbol pollution wholesale by
-building perl itself with:
+For additional information about porting Perl, see the section on
+L<"Porting information"> below, and look at the files in the Porting/
+directory.
- sh Configure -Accflags=-DPERL_POLLUTE
+=head1 PRELIMINARIES
-pod/perl56delta.pod contains more details about this.
+=head2 Changes and Incompatibilities
-=head1 WARNING: This version is not binary compatible with releases of
-Perl prior to 5.8.0.
+Please see pod/perl5110delta.pod for a description of the changes and
+potential incompatibilities introduced with this release. A few of
+the most important issues are listed below, but you should refer
+to pod/perl5110delta.pod for more detailed information.
+B This version is not binary compatible with prior releases of Perl.
If you have built extensions (i.e. modules that include C code)
using an earlier version of Perl, you will need to rebuild and reinstall
those extensions.
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 or 5.6 to 5.8.0"> for more details.
+without reinstallation. See the discussion below on
+L<"Coexistence with earlier versions of perl 5"> for more details.
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 the earlier pod/perl5Xdelta.pod) for a description of
-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 WARNING: This version requires a compiler that supports ANSI C.
-
-Most C compilers are now ANSI-compliant. However, a few current
-computers are delivered with an older C compiler expressly for
-rebuilding the system kernel, or for some other historical reason.
-Alternatively, you may have an old machine which was shipped before
-ANSI compliance became widespread. Such compilers are not suitable
-for building Perl.
-
-If you find that your default C compiler is not ANSI-capable, but you
-know that an ANSI-capable compiler is installed on your system, you
-can tell F to use the correct compiler by means of the
-C<-Dcc=> command-line option -- see L<"gcc">.
-
-If do not have an ANSI-capable compiler there are a couple of avenues
-open to you:
-
-=over 4
-
-=item *
-
-You may try obtaining GCC, available from GNU mirrors worldwide,
-listed at . If, rather than
-building gcc from source code, you locate a binary version configured
-for your platform, be sure that it is compiled for the version of the
-operating system that you are using.
-
-=item *
-
-You may purchase a commercial ANSI C compiler from your system
-supplier or elsewhere. (Or your organization may already have
-licensed such software -- ask your colleagues to find out how to
-access it.) If there is a README file for your system in the Perl
-distribution (for example, F), it may contain advice on
-suitable compilers.
-
-=back
-
-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 50 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.
-
-=head1 Start with a Fresh Distribution
-
-If you have built perl before, you should clean out the build directory
-with the command
-
- make distclean
-
-or
-
- make realclean
-
-The only difference between the two is that make distclean also removes
-your old config.sh and Policy.sh files.
-
-The results of a Configure run are stored in the config.sh and Policy.sh
-files. If you are upgrading from a previous version of perl, or if you
-change systems or compilers or make other significant changes, or if
-you are experiencing difficulties building perl, you should probably
-not re-use your old config.sh. Simply remove it
-
- rm -f config.sh
-
-If you wish to use your old config.sh, be especially attentive to the
-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.
-
-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.
-
-In short, if you wish to use your old config.sh, I recommend running
-Configure interactively rather than blindly accepting the defaults.
-
-If your reason to reuse your old config.sh is to save your particular
-installation choices, then you can probably achieve the same effect by
-using the Policy.sh file. See the section on L<"Site-wide Policy
-settings"> below. If you wish to start with a fresh distribution, you
-also need to remove any old Policy.sh files you may have with
-
- rm -f Policy.sh
+On a related issue, old modules may possibly be affected by the changes
+in the Perl language in the current release. Please see
+pod/perl5110delta.pod for a description of 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 Run Configure
@@ -231,73 +107,45 @@ almost always okay. It is normal for some things to be "NOT found",
since Configure often searches for many different ways of performing
the same function.
-At any Configure prompt, you can type &-d and Configure will use the
+At any Configure prompt, you can type &-d and Configure will use the
defaults from then on.
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 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 Building Perl outside of the source directory
-
-Sometimes it is desirable to build Perl in a directory different from
-where the sources are, for example if you want to keep your sources
-read-only, or if you want to share the sources between different binary
-architectures. You can do this (if your file system supports symbolic
-links) by
-
- mkdir /tmp/perl/build/directory
- cd /tmp/perl/build/directory
- sh /path/to/perl/source/Configure -Dmksymlinks ...
-
-This will create in /tmp/perl/build/directory a tree of symbolic links
-pointing to files in /path/to/perl/source. The original files are left
-unaffected. After Configure has finished you can just say
+The results of a Configure run are stored in the config.sh and Policy.sh
+files.
- make all test
+=head2 Common Configure options
-and Perl will be built and tested, all in /tmp/perl/build/directory.
+Configure supports a number of useful options. Run
-=head2 Common Configure options
+ Configure -h
-Configure supports a number of useful options. Run B to
-get a listing. See the Porting/Glossary file for a complete list of
+to get a listing. See the Porting/Glossary file for a complete list of
Configure variables you can set and their definitions.
=over 4
-=item gcc
+=item C compiler
-To compile with gcc you should run
+To compile with gcc, if it's not the default compiler on your
+system, you should run
sh Configure -Dcc=gcc
-This is the preferred way to specify gcc (or another alternative
+This is the preferred way to specify gcc (or any another alternative
compiler) so that the hints files can set appropriate defaults.
=item Installation prefix
By default, for most systems, perl will be installed in
/usr/local/{bin, lib, man}. (See L<"Installation Directories">
-and L<"Coexistence with earlier versions of perl5"> below for
+and L<"Coexistence with earlier versions of perl 5"> below for
further details.)
You can specify a different 'prefix' for the default installation
-directory, when Configure prompts you or by using the Configure command
+directory when Configure prompts you, or by using the Configure command
line option -Dprefix='/some/directory', e.g.
sh Configure -Dprefix=/opt/perl
@@ -319,24 +167,35 @@ It may seem obvious, but Perl is useful only when users can easily
find it. It's often a good idea to have both /usr/bin/perl and
/usr/local/bin/perl be symlinks to the actual binary. Be especially
careful, however, not to overwrite a version of perl supplied by your
-vendor unless you are sure you know what you are doing.
+vendor unless you are sure you know what you are doing. If you insist
+on replacing your vendor's perl, useful information on how it was
+configured may be found with
+
+ perl -V:config_args
-By default, Configure will arrange for /usr/bin/perl to be linked to
-the current version of perl. You can turn off that behavior by running
+(Check the output carefully, however, since this doesn't preserve
+spaces in arguments to Configure. For that, you have to look carefully
+at config_arg1, config_arg2, etc.)
- Configure -Uinstallusrbinperl
+By default, Configure will not try to link /usr/bin/perl to the current
+version of perl. You can turn on that behavior by running
-or by answering 'no' to the appropriate Configure prompt.
+ Configure -Dinstallusrbinperl
-In any case, system administrators are strongly encouraged to
-put (symlinks to) perl and its accompanying utilities, such as perldoc,
+or by answering 'yes' to the appropriate Configure prompt.
+
+In any case, system administrators are strongly encouraged to put
+(symlinks to) perl and its accompanying utilities, such as perldoc,
into a directory typically found along a user's PATH, or in another
obvious and convenient place.
-=item Overriding an old config.sh
+=item Building a development release
-If you want to use your old config.sh but override some of the items
-with command line options, you need to use B.
+For development releases (odd subreleases, like 5.9.x) if you want to
+use Configure -d, you will also need to supply -Dusedevel to Configure,
+because the default answer to the question "do you really want to
+Configure a development version?" is "no". The -Dusedevel skips that
+sanity check.
=back
@@ -345,47 +204,309 @@ output, you can run
sh Configure -des
-Note: for development releases (odd subreleases, like 5.9, as opposed
-to maintenance releases which have even subreleases, like 5.6 and 5.8)
-if you want to use Configure -d, you will also need to supply -Dusedevel
-to Configure, because the default answer to the question "do you really
-want to Configure a development version?" is "no". The -Dusedevel
-skips that sanity check.
+=head2 Altering Configure variables for C compiler switches etc.
-For example for my Solaris system, I usually use
+For most users, most of the Configure defaults are fine, or can easily
+be set on the Configure command line. 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 -Dprefix=/opt/perl -Doptimize='-xpentium -xO4' -des
+ sh Configure -Accflags="-DPERL_EXTERNAL_GLOB -DNO_HASH_SEED"
-=head2 GNU-style configure
+To clarify, those ccflags values are not Configure options; if passed to
+Configure directly, they won't do anything useful (they will define a
+variable in config.sh, but without taking any action based upon it).
+But when passed to the compiler, those flags will activate #ifdefd code.
-If you prefer the GNU-style configure command line interface, you can
-use the supplied configure.gnu command, e.g.
+For more help on Configure switches, run
- CC=gcc ./configure.gnu
+ sh Configure -h
-The configure.gnu script emulates a few of the more common configure
-options. Try
+=head2 Major Configure-time Build Options
- ./configure.gnu --help
+There are several different ways to Configure and build perl for your
+system. For most users, the defaults are sensible and will work.
+Some users, however, may wish to further customize perl. Here are
+some of the main things you can change.
-for a listing.
+=head3 Threads
-(The file is called configure.gnu to avoid problems on systems
-that would not distinguish the files "Configure" and "configure".)
+On some platforms, perl can be compiled with support for threads. To
+enable this, run
+
+ sh Configure -Dusethreads
+
+The default is to compile without thread support.
+
+Perl used to have two different internal threads implementations. The current
+model (available internally since 5.6, and as a user-level module since 5.8) is
+called interpreter-based implementation (ithreads), with one interpreter per
+thread, and explicit sharing of data. The (deprecated) 5.005 version
+(5005threads) has been removed for release 5.10.
+
+The 'threads' module is for use with the ithreads implementation. The
+'Thread' module emulates the old 5005threads interface on top of the current
+ithreads model.
+
+When using threads, perl uses a dynamically-sized buffer for some of
+the thread-safe library calls, such as those in the getpw*() family.
+This buffer starts small, but it will keep growing until the result
+fits. To get a fixed upper limit, you should compile Perl with
+PERL_REENTRANT_MAXSIZE defined to be the number of bytes you want. One
+way to do this is to run Configure with
+C<-Accflags=-DPERL_REENTRANT_MAXSIZE=65536>.
+
+=head3 Large file support
+
+Since Perl 5.6.0, Perl has supported large files (files larger than
+2 gigabytes), and in many common platforms like Linux or Solaris this
+support is on by default.
+
+This is both good and bad. It is good in that you can use large files,
+seek(), stat(), and -s them. It is bad in that if you are interfacing Perl
+using some extension, the components you are connecting to must also
+be large file aware: if Perl thinks files can be large but the other
+parts of the software puzzle do not understand the concept, bad things
+will happen.
+
+There's also one known limitation with the current large files
+implementation: unless you also have 64-bit integers (see the next
+section), you cannot use the printf/sprintf non-decimal integer formats
+like C<%x> to print filesizes. You can use C<%d>, though.
+
+If you want to compile perl without large file support, use
+
+ sh Configure -Uuselargefiles
+
+=head3 64 bit support
+
+If your platform does not run natively at 64 bits, but can simulate
+them with compiler flags and/or C or C,
+you can build a perl that uses 64 bits.
+
+There are actually two modes of 64-bitness: the first one is achieved
+using Configure -Duse64bitint and the second one using Configure
+-Duse64bitall. The difference is that the first one is minimal and
+the second one maximal. The first works in more places than the second.
+
+The C option does only as much as is required to get
+64-bit integers into Perl (this may mean, for example, using "long
+longs") while your memory may still be limited to 2 gigabytes (because
+your pointers could still be 32-bit). Note that the name C<64bitint>
+does not imply that your C compiler will be using 64-bit Cs (it
+might, but it doesn't have to). The C simply means that
+you will be able to have 64 bit-wide scalar values.
+
+The C option goes all the way by attempting to switch
+integers (if it can), longs (and pointers) to being 64-bit. This may
+create an even more binary incompatible Perl than -Duse64bitint: the
+resulting executable may not run at all in a 32-bit box, or you may
+have to reboot/reconfigure/rebuild your operating system to be 64-bit
+aware.
+
+Natively 64-bit systems need neither -Duse64bitint nor -Duse64bitall.
+On these systems, it might be the default compilation mode, and there
+is currently no guarantee that passing no use64bitall option to the
+Configure process will build a 32bit perl. Implementing -Duse32bit*
+options is planned for perl 5.12.
+
+=head3 Long doubles
+
+In some systems you may be able to use long doubles to enhance the
+range and precision of your double precision floating point numbers
+(that is, Perl's numbers). Use Configure -Duselongdouble to enable
+this support (if it is available).
+
+=head3 "more bits"
+
+You can "Configure -Dusemorebits" to turn on both the 64-bit support
+and the long double support.
-See L below for information on cross-compiling.
+=head3 Algorithmic Complexity Attacks on Hashes
+
+In Perls 5.8.0 and earlier it was easy to create degenerate hashes.
+Processing such hashes would consume large amounts of CPU time,
+enabling a "Denial of Service" attack against Perl. Such hashes may be
+a problem for example for mod_perl sites, sites with Perl CGI scripts
+and web services, that process data originating from external sources.
+
+In Perl 5.8.1 a security feature was introduced to make it harder to
+create such degenerate hashes. A visible side effect of this was that
+the keys(), values(), and each() functions may return the hash elements
+in different order between different runs of Perl even with the same
+data. It also had unintended binary incompatibility issues with
+certain modules compiled against Perl 5.8.0.
+
+In Perl 5.8.2 an improved scheme was introduced. Hashes will return
+elements in the same order as Perl 5.8.0 by default. On a hash by hash
+basis, if pathological data is detected during a hash key insertion,
+then that hash will switch to an alternative random hash seed. As
+adding keys can always dramatically change returned hash element order,
+existing programs will not be affected by this, unless they
+specifically test for pre-recorded hash return order for contrived
+data. (eg the list of keys generated by C