X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=INSTALL;h=e77b18991d9dce9380033c367a5aaa32d4ffe973;hb=67a86ef3f5ab1f509f5775da82cbf43e437569ac;hp=6fb66653c3a36995cf433a3ceffff0013ae92642;hpb=f9faeafccd43fe415773256f1becd34b66408086;p=p5sagit%2Fp5-mst-13.2.git diff --git a/INSTALL b/INSTALL index 6fb6665..e77b189 100644 --- a/INSTALL +++ b/INSTALL @@ -59,7 +59,7 @@ http://www.chiark.greenend.org.uk/~sgtatham/bugs.html 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.6.x and 5.8.x) are stable maintenance releases and +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 @@ -90,7 +90,7 @@ If that's not okay with you, can run Configure interactively and use # You may also wish to add these: (cd /usr/include && h2ph *.h sys/*.h) (installhtml --help) - (cd pod && make tex && ) + (cd pod && make tex && ) or you can use some of the Configure options described below. @@ -98,7 +98,7 @@ If you have problems, corrections, or questions, please see L<"Reporting Problems"> above. For information on what's new in this release, see the -pod/perldelta.pod file. For more detailed information about specific +pod/perl5100delta.pod file. For more detailed information about specific changes, see the Changes file. =head1 DESCRIPTION @@ -132,13 +132,12 @@ directory. =head2 Changes and Incompatibilities -Please see pod/perldelta.pod for a description of the changes and +Please see pod/perl5100delta.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/perldelta.pod for more detailed information. +to pod/perl5100delta.pod for more detailed information. -=head3 WARNING: This version is not binary compatible with releases of -Perl prior to 5.9.0. +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 @@ -153,20 +152,11 @@ 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 for a description of what's changed. See your +pod/perl5100delta.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. -=head2 Space Requirements - -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. - =head1 Start with a Fresh Distribution If you have built perl before, you should clean out the build directory @@ -194,17 +184,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. @@ -243,13 +231,14 @@ 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 @@ -332,7 +321,7 @@ 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_EXTERNAL_GLOB -DPERL_POLLUTE_MALLOC" + sh Configure -Accflags="-DPERL_EXTERNAL_GLOB -DNO_HASH_SEED" 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 @@ -362,21 +351,15 @@ line so that the hint files can make appropriate adjustments. The default is to compile without thread support. -Perl has 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 5.005 -version (5005threads) is considered obsolete, buggy, and unmaintained. - -By default, Configure selects ithreads if -Dusethreads is specified. - -However, if you insist, you can select the unsupported old 5005threads behavior - - sh Configure -Dusethreads -Duse5005threads +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 offers an interface to either 5005threads or ithreads -(whichever has been configured). +'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. @@ -384,9 +367,9 @@ 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> +C<-Accflags=-DPERL_REENTRANT_MAXSIZE=65536>. -=head3 Large file support. +=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 @@ -397,18 +380,17 @@ 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. One popular extension suffering from this ailment is the -Apache extension mod_perl. +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. -=head3 64 bit support. +=head3 64 bit support -If your platform does not have run natively at 64 bits, but can -simulate them with compiler flags and/or C or C, +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 @@ -431,13 +413,7 @@ 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 like Alpha and Cray need neither -Duse64bitint -nor -Duse64bitall. - - NOTE: 64-bit support is still experimental on most platforms. - Existing support only covers the LP64 data model. In particular, the - LLP64 data model is not yet supported. 64-bit libraries and system - APIs on many platforms have not stabilized--your mileage may vary. +Natively 64-bit systems need neither -Duse64bitint nor -Duse64bitall. =head3 Long doubles @@ -451,30 +427,6 @@ this support (if it is available). You can "Configure -Dusemorebits" to turn on both the 64-bit support and the long double support. -=head3 Selecting File IO mechanisms - -Executive summary: as of Perl 5.8, you should use the default "PerlIO" -as the IO mechanism unless you have a good reason not to. - -In more detail: previous versions of perl used the standard IO -mechanisms as defined in stdio.h. Versions 5.003_02 and later of perl -introduced alternate IO mechanisms via a "PerlIO" abstraction, but up -until and including Perl 5.6, the stdio mechanism was still the default -and the only supported mechanism. - -Starting from Perl 5.8, the default mechanism is to use the PerlIO -abstraction, because it allows better control of I/O mechanisms, -instead of having to work with (often, work around) vendors' I/O -implementations. - -This PerlIO abstraction can be (but again, unless you know what you -are doing, should not be) disabled either on the Configure command -line with - - sh Configure -Uuseperlio - -or interactively at the appropriate Configure prompt. - =head3 Algorithmic Complexity Attacks on Hashes In Perls 5.8.0 and earlier it was easy to create degenerate hashes. @@ -513,10 +465,9 @@ the compilation flags to completely disable the randomisation feature. B, and the ordering has already changed several times during the lifetime of Perl 5. Also, the ordering of hash keys has always been, and continues to -be, affected by the insertion order. It is likely that Perl 5.10 and -Perl 6 will randomise all hashes. Note that because of this +be, affected by the insertion order. Note that because of this randomisation for example the Data::Dumper results will be different -between different runs of Perl since Data::Dumper by default dumps +between different runs of Perl, since Data::Dumper by default dumps hashes "unordered". The use of the Data::Dumper C option is recommended. @@ -538,10 +489,9 @@ 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 +On 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 @@ -559,15 +509,12 @@ 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.5.8.8 (for Perl 5.8.8), or libperl.so.588, 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 @@ -588,8 +535,10 @@ 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 + cd t; ./perl -MTestInit misc/failing_test.t + or + ./perl -Ilib ~/my_mission_critical_test then you need to set up the shared library path explicitly. @@ -608,13 +557,14 @@ 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 + + 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 +install a standard Perl 5.10.0 with a shared library. Then, suppose you +try to build Perl 5.10.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 @@ -651,14 +601,11 @@ C 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 @@ -676,9 +623,9 @@ 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.9.0. +By default, Configure will use the following directories for 5.10.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, +5.10.0 or 5.9.5, and $archname is a string like sun4-sunos, determined by Configure. The full definitions of all Configure variables are in the file Porting/Glossary. @@ -836,23 +783,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 @@ -901,10 +837,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 @@ -1002,6 +936,10 @@ 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 + +or + sh Configure -DDEBUGGING= For a more eye appealing call, -DEBUGGING is defined to be an alias @@ -1031,8 +969,6 @@ 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 @@ -1366,23 +1302,10 @@ Policy overrides hints -- see L. =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: - - *** WHOA THERE!!! *** - The recommended value for $d_tzname on this machine was "undef"! - Keep the recommended value? [y] - -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. - -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 @@ -1522,10 +1445,10 @@ You can specify extra modules or module bundles to be fetched from the CPAN and installed as part of the Perl build. Either use the -Dextras=... command line parameter to Configure, for example like this: - Configure -Dextras="Compress::Zlib Bundle::LWP DBI" + Configure -Dextras="Bundle::LWP DBI" or answer first 'y' to the question 'Install any extra modules?' and -then answer "Compress::Zlib Bundle::LWP DBI" to the 'Extras?' question. +then answer "Bundle::LWP DBI" to the 'Extras?' question. The module or the bundle names are as for the CPAN module 'install' command. This will only work if those modules are to be built as dynamic extensions. If you wish to include those extra modules as static @@ -1538,8 +1461,7 @@ do not, using the extra modules option will die horribly. Also notice that you yourself are responsible for satisfying any extra dependencies such as external headers or libraries BEFORE trying the build. -For example: you will need to have the zlib.h header and the libz -library installed for the Compress::Zlib, or the Foo database specific +For example: you will need to have the Foo database specific headers and libraries installed for the DBD::Foo module. The Configure process or the Perl build process will not help you with these. @@ -1561,8 +1483,9 @@ Because of the buggy history of suidperl, and the difficulty of properly security auditing as large and complex piece of software as Perl, we cannot recommend using suidperl and the feature should be considered deprecated. + Instead, use a tool specifically designed to handle changes in -privileges, such as B, http://www.courtesan.com/sudo/ . +privileges, such as B. =head1 make depend @@ -1618,7 +1541,7 @@ If you have any locale-related environment variables set, try unsetting them. I have some reports that some versions of IRIX hang while running B<./miniperl configpm> with locales other than the C locale. See the discussion under L<"make test"> below about locales and the -whole L<"Locale problems"> section in the file pod/perllocale.pod. +whole L section in the file pod/perllocale.pod. The latter is especially useful if you see something like this perl: warning: Setting locale failed. @@ -2231,13 +2154,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 @@ -2249,7 +2172,6 @@ the DESTDIR variable during C, 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 @@ -2263,10 +2185,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 @@ -2330,7 +2252,7 @@ approach. =head1 Coexistence with earlier versions of perl5 -Perl 5.9 is not binary compatible with earlier versions of Perl. +Perl 5.10 is not binary compatible with earlier versions of Perl. In other words, you will have to recompile your XS modules. In general, you can usually safely upgrade from one version of Perl (e.g. @@ -2342,8 +2264,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 @@ -2450,21 +2372,6 @@ 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 - -You can safely install perl5 even if you want to keep perl4 around. - -By default, the perl5 libraries go into /usr/local/lib/perl5/, so -they don't override the perl4 libraries in /usr/local/lib/perl/. - -In your /usr/local/bin directory, you should have a binary named -perl4.036. That will not be touched by the perl5 installation -process. Most perl4 scripts should run just fine under perl5. -However, if you have any scripts that require perl4, you can replace -the #! line at the top of them by #!/usr/local/bin/perl4.036 (or -whatever the appropriate pathname is). See L for -possible problems running perl4 scripts under perl5. - =head1 cd /usr/include; h2ph *.h sys/*.h Some perl scripts need to be able to obtain information from the