X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=INSTALL;h=f087b77fc8d55263ab8fc7bb904bca60c5311214;hb=502fc48ee3e3c29dc3d569f8e543d48ceb7a4de6;hp=45064a6db2904650b67192f74a1d5e08fc893923;hpb=345c69e9b0e03d9315f568046674ffa653e13358;p=p5sagit%2Fp5-mst-13.2.git diff --git a/INSTALL b/INSTALL index 45064a6..f087b77 100644 --- a/INSTALL +++ b/INSTALL @@ -24,7 +24,7 @@ with all the defaults are: Each of these is explained in further detail below. -B: starting from the release 5.6.0 Perl will use a version +B: starting from the release 5.6.0, Perl will use a version scheme where even-numbered subreleases (like 5.6) are stable maintenance releases and odd-numbered subreleases (like 5.7) are unstable development releases. Development releases should not be @@ -88,8 +88,8 @@ 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 +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 @@ -101,17 +101,12 @@ building perl itself with: pod/perldelta.pod contains more details about this. -=head1 WARNING: This version may not be binary compatible with Perl 5.005. +=head1 WARNING: This version is not binary compatible with releases of +Perl prior to 5.8.0. -Using the default Configure options for building perl should get you -a perl that will be binary compatible with the 5.005 release. - -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. +If you have built extensions (ie 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 @@ -186,10 +181,10 @@ does not work with some C++ compilers. =head1 Space Requirements -The complete perl5 source tree takes up about 40 MB of disk space. -After completing make, it takes up roughly 60 MB, though the actual +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 35 MB, though again that +directories need something on the order of 45 MB, though again that value is system-dependent. =head1 Start with a Fresh Distribution @@ -328,7 +323,8 @@ If your prefix contains the string "perl", then the suggested directory structure is simplified. For example, if you use prefix=/opt/perl, then Configure will suggest /opt/perl/lib instead of /opt/perl/lib/perl5/. Again, see L<"Installation Directories"> below -for more details. +for more details. Do not include a trailing slash, (i.e. /opt/perl/) +or you may experience odd test failures. NOTE: You must not specify an installation directory that is the same as or below your perl source directory. If you do, installperl will @@ -403,7 +399,8 @@ appropriate questions in Configure. For convenience, all the installation questions are near the beginning of Configure. Further, there are a number of additions to the installation directories since 5.005, so reusing your old config.sh may not -be sufficient to put everything where you want it. +be sufficient to put everything where you want it. 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 @@ -719,19 +716,23 @@ line so that the hint files can make appropriate adjustments. 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 +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. - sh Configure -Dusethreads -Duse5005threads +The 5.005 version (5005threads) is considered obsolete, buggy, and +unmaintained. -or by - sh Configure -Dusethreads -Uuseithreads +By default, Configure selects ithreads if -Dusethreads is specified. -Eventually (by perl v5.6.0) this internal confusion ought to disappear, -and these options may disappear as well. +However, you can select the old 5005threads behavior + + sh Configure -Dusethreads -Duse5005threads + +If you decide to use ithreads, the 'threads' module allows their use, +and the 'Thread' module offers an interface to both 5005threads and +ithreads (whichever has been configured). =head2 Large file support. @@ -800,33 +801,36 @@ and the long double support. =head2 Selecting File IO mechanisms -Previous versions of perl used the standard IO mechanisms as defined in -stdio.h. Versions 5.003_02 and later of perl allow alternate IO -mechanisms via a "PerlIO" abstraction, but the stdio mechanism is still -the default and is the only supported mechanism. - -This PerlIO abstraction can be enabled either on the Configure command -line with +Executive summary: in Perl 5.8, you should use the default "PerlIO" +as the IO mechanism unless you have a good reason not to. - sh Configure -Duseperlio +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. -or interactively at the appropriate Configure prompt. +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. -If you choose to use the PerlIO abstraction layer, there are two -(experimental) possibilities for the underlying IO calls. These have been -tested to some extent on some platforms, but are not guaranteed to work -everywhere. +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 -=over 4 + sh Configure -Uuseperlio -=item 1. +or interactively at the appropriate Configure prompt. -AT&T's "sfio". This has superior performance to stdio.h in many -cases, and is extensible by the use of "discipline" modules. Sfio -currently only builds on a subset of the UNIX platforms perl supports. -Because the data structures are completely different from stdio, perl -extension modules or external libraries may not work. This -configuration exists to allow these issues to be worked on. +With the PerlIO abstraction layer, there is another possibility for +the underlying IO calls, AT&T's "sfio". This has superior performance +to stdio.h in many cases, and is extensible by the use of "discipline" +modules ("Native" PerlIO has them too). Sfio currently only builds on +a subset of the UNIX platforms perl supports. Because the data +structures are completely different from stdio, perl extension modules +or external libraries may not work. This configuration exists to +allow these issues to be worked on. This option requires the 'sfio' package to have been built and installed. The latest sfio is available from http://www.research.att.com/sw/tools/sfio/ @@ -846,24 +850,6 @@ Configure should detect this problem and warn you about problems with _exit vs. exit. If you have this problem, the fix is to go back to your sfio sources and correct iffe's guess about atexit. -=item 2. - -Normal stdio IO, but with all IO going through calls to the PerlIO -abstraction layer. This configuration can be used to check that perl and -extension modules have been correctly converted to use the PerlIO -abstraction. - -This configuration should work on all platforms (but might not). - -You select this option via: - - sh Configure -Duseperlio -Uusesfio - -If you have already selected -Duseperlio, and if Configure does not -detect sfio, then this will be the default suggested by Configure. - -=back - =head2 SOCKS Perl can be configured to be 'socksified', that is, to use the SOCKS @@ -1000,15 +986,8 @@ or you can answer 'n' at the appropriate interactive Configure prompt. =item -DPERL_POLLUTE_MALLOC -NOTE: This flag is enabled automatically on some platforms if you -asked for binary compatibility with version 5.005, or if you just -run Configure to accept all the defaults on those platforms. You -can refuse the automatic binary compatibility flags wholesale by -running: - - sh Configure -Ubincompat5005 - -or by answering 'n' at the appropriate prompt. +NOTE: This flag is enabled automatically on some platforms if you just +run Configure to accept all the defaults on those platforms. Perl's malloc family of functions are called Perl_malloc(), Perl_realloc(), Perl_calloc() and Perl_mfree(). When this flag is @@ -1628,16 +1607,6 @@ to then propagate your changes with B and rebuild with B. -=item CRIPPLED_CC - -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 If you have missing routines, you probably need to add some library or @@ -1751,14 +1720,12 @@ Genix may need to use libc rather than libc_s, or #undef VARARGS. NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR. -UTS may need one or more of -DCRIPPLED_CC, -K or -g, and undef LSTAT. +UTS may need one or more of -K or -g, and undef LSTAT. FreeBSD can fail the lib/ipc_sysv.t test if SysV IPC has not been configured to the kernel. Perl tries to detect this, though, and you will get a message telling what to do. -If you get syntax errors on '(', try -DCRIPPLED_CC. - Machines with half-implemented dbm routines will need to #undef I_ODBM HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000 @@ -1946,10 +1913,12 @@ external program. Several tests in the test suite check timing functions, such as sleep(), and see if they return in a reasonable amount of time. -If your system is quite busy and doesn't return quickly enough, -these tests might fail. If possible, try running the tests again with -the system under a lighter load. These tests include F, -F, and F. +If your system is quite busy and doesn't respond quickly enough, +these tests might fail. If possible, try running the tests again +with the system under a lighter load. These timing-sensitive +and load-sensitive tests include F, +F, F, +F, and F. =item Out of memory @@ -2120,6 +2089,9 @@ approach. =head1 Coexistence with earlier versions of perl5 +Perl 5.8 is not binary compatible with earlier versions of Perl. +In other words, you have to recompile your XS modules. + In general, you can usually safely upgrade from one version of Perl (e.g. 5.004_04) to another similar version (e.g. 5.004_05) without re-compiling all of your add-on extensions. You can also safely leave the old version @@ -2305,6 +2277,13 @@ The following section is meant for people worrying about squeezing the Perl installation into minimal systems (for example when installing operating systems, or in really small filesystems). +Leaving out as many extensions as possible is an obvious way: +especially the Encode with its big conversion tables consumes a lot of +space. On the other hand, you cannot throw away everything, especially +the Fcntl module is pretty essential. If you need to do network +programming, you'll appreciate the Socket module, and so forth: it all +depends on what do you need to do. + In the following we offer two different slimmed down installation recipes. They are informative, not normative: the choice of files depends on what you need.