X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/e8b9ce6006d3ecb2b02af04e4406ccb4294e728c..eda9cac17f1c742273b62b039f512bc88ffb37a1:/INSTALL diff --git a/INSTALL b/INSTALL index 147acd2..33faa6b 100644 --- a/INSTALL +++ b/INSTALL @@ -36,13 +36,18 @@ 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". +Building perl from source requires an ANSI compliant C-Compiler. +A minimum of C89 is required. Some features available in C99 will +be probed for and used when found. The perl build process does not +rely on anything more than C89. + 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/perl5110delta.pod file. For more information about how to find more +pod/perldelta.pod file. For more information about how to find more specific detail about changes, see the Changes file. =head1 DESCRIPTION @@ -75,10 +80,10 @@ directory. =head2 Changes and Incompatibilities -Please see pod/perl5110delta.pod for a description of the changes and +Please see pod/perldelta.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. +to pod/perldelta.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) @@ -93,7 +98,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/perl5110delta.pod for a description of what's changed. See your +pod/perldelta.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. @@ -244,7 +249,7 @@ 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. +(5005threads) was 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 @@ -310,7 +315,7 @@ 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. +options is planned for a future release of perl. =head3 Long doubles @@ -495,9 +500,10 @@ to avoid these leaks. The default is now to perform direct manipulation whenever perl is running as a stand alone interpreter, and to call the safe but potentially leaky C function when the perl interpreter is embedded in another application. You can force perl to always use C -by compiling with -DPERL_USE_SAFE_PUTENV. You can force an embedded perl to -use direct manipulation by setting C after the -C call. +by compiling with C<-Accflags="-DPERL_USE_SAFE_PUTENV">, see section +L. +You can force an embedded perl to use direct manipulation by setting +C after the C call. =head2 Installation Directories @@ -524,9 +530,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.10.0. +By default, Configure will use the following directories for 5.13.9. $version is the full perl version number, including subversion, e.g. -5.10.0 or 5.9.5, and $archname is a string like sun4-sunos, +5.13.9 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. @@ -772,6 +778,25 @@ simply do: =back +=head2 Relocatable @INC + +To create a relocatable perl tree, use the following command line: + + sh Configure -Duserelocatableinc + +Then the paths in @INC (and everything else in %Config) can be +optionally located via the path of the perl executable. + +That means that, if the string ".../" is found at the start of any +path, it's substituted with the directory of $^X. So, the relocation +can be configured on a per-directory basis, although the default with +"-Duserelocatableinc" is that everything is relocated. The initial +install is done to the original configured prefix. + +This option is not compatible with the building of a shared libperl +("-Duseshrplib"), because in that case perl is linked with an hard-coded +rpath that points at the libperl.so, that cannot be relocated. + =head2 Site-wide Policy settings After Configure runs, it stores a number of common site-wide "policy" @@ -811,6 +836,13 @@ modules, you can specify to not include the paths found: sh Configure -Dinc_version_list=none ... +If you do want to use modules from some previous perl versions, the variable +must contain a space separated list of directories under the site_perl +directory, and has to include architecture-dependent directories separately, +eg. + + sh Configure -Dinc_version_list="5.12.0/x86_64-linux 5.12.0" ... + When using the newer perl, you can add these paths again in the $PERL5LIB environment variable or with perl's -I runtime option. @@ -890,6 +922,22 @@ Removes -g from optimize, and -DDEBUGGING from ccflags. If you are using a shared libperl, see the warnings about multiple versions of perl under L. +Note that a perl built with -DDEBUGGING will be bigger and will run more +slowly than a standard perl. + +=head2 DTrace support + +On platforms where DTrace is available, it may be enabled by +using the -Dusedtrace option to Configure. DTrace probes are available for +subroutine entry (sub-entry) and subroutine exit (sub-exit). Here's a +simple D script that uses them: + + perl$target:::sub-entry, perl$target:::sub-return { + printf("%s %s (%s:%d)\n", probename == "sub-entry" ? "->" : "<-", + copyinstr(arg0), copyinstr(arg1), arg2); + } + + =head2 Extensions Perl ships with a number of standard extensions. These are contained @@ -901,7 +949,8 @@ only if it is able to find the gdbm library. To disable certain extensions so that they are not built, use the -Dnoextensions=... and -Donlyextensions=... options. They both accept -a space-separated list of extensions. The extensions listed in +a space-separated list of extensions, such as C. The extensions +listed in C are removed from the list of extensions to build, while the C is rather more severe and builds only the listed extensions. The latter should be used with extreme caution since @@ -935,7 +984,7 @@ Perl comes with interfaces to number of libraries, including threads, dbm, ndbm, gdbm, and Berkeley db. For the *db* extension, if Configure can find the appropriate header files and libraries, it will automatically include that extension. The threading extension needs -to be specified explicitely (see L). +to be specified explicitly (see L). Those libraries are not distributed with perl. If your header (.h) files for those libraries are not in a directory normally searched by your C @@ -1251,7 +1300,7 @@ various other operating systems. If you plan to port Perl to a new architecture, study carefully the section titled "Philosophical Issues in Patching and Porting Perl" -in the file Porting/pumpkin.pod and the file Porting/patching.pod. +in the file Porting/pumpkin.pod and the file pod/perlrepository.pod. Study also how other non-UNIX ports have solved problems. =back @@ -1284,25 +1333,9 @@ process or the Perl build process will not help you with these. =head2 suidperl -suidperl is an optional component, which is normally neither built -nor installed by default. From perlfaq1: - - On some systems, setuid and setgid scripts (scripts written - in the C shell, Bourne shell, or Perl, for example, with the - set user or group ID permissions enabled) are insecure due to - a race condition in the kernel. For those systems, Perl versions - 5 and 4 attempt to work around this vulnerability with an optional - component, a special program named suidperl, also known as sperl. - This program attempts to emulate the set-user-ID and set-group-ID - features of the kernel. - -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. +suidperl was an optional component of earlier releases of perl. It is no +longer available. Instead, use a tool specifically designed to handle +changes in privileges, such as B. =head1 make depend @@ -1370,6 +1403,18 @@ The latter is especially useful if you see something like this at Perl startup. +=item other environment variables + +Configure does not check for environment variables that can sometimes +have a major influence on how perl is built or tested. For example, +OBJECT_MODE on AIX determines the way the compiler and linker deal with +their objects, but this is a variable that only influences build-time +behaviour, and should not affect the perl scripts that are eventually +executed by the perl binary. Other variables, like PERL_UNICODE, +PERL5LIB, and PERL5OPT will influence the behaviour of the test suite. +So if you are getting strange test failures, you may want to try +retesting with the various PERL variables unset. + =item varargs If you get varargs problems with gcc, be sure that gcc is installed @@ -1529,6 +1574,26 @@ specific rule. SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4 that includes libdbm.nfs (which includes dbmclose()) may be available. +=item error: too few arguments to function 'dbmclose' + +Building ODBM_File on some (Open)SUSE distributions might run into this +error, as the header file is broken. There are two ways to deal with this + + 1. Disable the use of ODBM_FILE + + Configure ... -Dnoextensions=ODBM_File + + 2. Fix the header file, somewhat like this: + + --- a/usr/include/dbm.h 2010-03-24 08:54:59.000000000 +0100 + +++ b/usr/include/dbm.h 2010-03-24 08:55:15.000000000 +0100 + @@ -59,4 +59,4 @@ extern datum firstkey __P((void)); + + extern datum nextkey __P((datum key)); + + -extern int dbmclose __P((DBM *)); + +extern int dbmclose __P((void)); + =item Note (probably harmless): No library found for -lsomething If you see such a message during the building of an extension, but @@ -1808,7 +1873,7 @@ If make test bombs out, just cd to the t directory and run ./TEST by hand to see if it makes any difference. If individual tests bomb, you can run them by hand, e.g., - cd t ; ./perl -MTestInit op/groups.t + ./perl -MTestInit t/op/groups.t Another way to get more detailed information about failed tests and individual subtests is to cd to the t directory and run @@ -1945,6 +2010,18 @@ about the various security aspects of temporary files. =back +The core distribution can now run its regression tests in parallel on +Unix-like platforms. Instead of running C, set C in +your environment to the number of tests to run in parallel, and run +C. On a Bourne-like shell, this can be done as + + TEST_JOBS=3 make test_harness # Run 3 tests in parallel + +An environment variable is used, rather than parallel make itself, because +L needs to be able to schedule individual non-conflicting test +scripts itself, and there is no standard interface to C utilities to +interact with their job schedulers. + =head1 make install This will put perl into the public directory you specified to @@ -2041,6 +2118,7 @@ make install will install the following: psed A Perl implementation of sed ptar A Perl implementation of tar ptardiff A diff for tar archives + ptargrep A grep for tar archives s2p sed-to-perl translator shasum A tool to print or check SHA checksums splain Describe Perl warnings and errors @@ -2222,7 +2300,7 @@ http://www.chiark.greenend.org.uk/~sgtatham/bugs.html =head1 Coexistence with earlier versions of perl 5 -Perl 5.10 is not binary compatible with earlier versions of Perl. +Perl 5.12 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. @@ -2296,9 +2374,9 @@ 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.10.0 + sh Configure -Dprefix=/opt/perl5.13.9 -and adding /opt/perl5.10.0/bin to the shell PATH variable. Such users +and adding /opt/perl5.13.9/bin to the shell PATH variable. Such users may also wish to add a symbolic link /usr/local/bin/perl so that scripts can still start with #!/usr/local/bin/perl. @@ -2311,13 +2389,13 @@ seriously consider using a separate directory, since development subversions may not have all the compatibility wrinkles ironed out yet. -=head2 Upgrading from 5.8.x or earlier +=head2 Upgrading from 5.13.8 or earlier -B Perl modules having binary parts (meaning that a C compiler is used) will have to be recompiled to be -used with 5.10.0. If you find you do need to rebuild an extension with -5.10.0, you may safely do so without disturbing the older +used with 5.13.9. If you find you do need to rebuild an extension with +5.13.9, you may safely do so without disturbing the older installations. (See L<"Coexistence with earlier versions of perl 5"> above.)