diff options
Diffstat (limited to 'contrib/perl5/INSTALL')
| -rw-r--r-- | contrib/perl5/INSTALL | 2167 |
1 files changed, 0 insertions, 2167 deletions
diff --git a/contrib/perl5/INSTALL b/contrib/perl5/INSTALL deleted file mode 100644 index dbf6cb5..0000000 --- a/contrib/perl5/INSTALL +++ /dev/null @@ -1,2167 +0,0 @@ -=head1 NAME - -Install - Build and Installation guide for perl5. - -=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 -<URL:http://www.cpan.org/src/>. - -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 - 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 && <process the latex files>) - -Each of these is explained in further detail below. - -B<NOTE>: 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 -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 /opt, depending -on the platform. 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 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. - -=head1 DESCRIPTION - -This document is written in pod format as an easy way to indicate its -structure. The pod format is described in pod/perlpod.pod, but you can -read it as is with any pager or editor. Headings and items are marked -by lines beginning with '='. The other mark-up used is - - B<text> embolden text, used for switches, programs or commands - C<code> literal code - L<name> A link (cross reference) to name - -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 -the README file specific to your operating system, since this may -provide additional or different instructions for building Perl. - -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.) 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 -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. - -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 to 5.6"> 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 pod/perl500Xdelta.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<Configure> 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 several avenues open -to you: - -=over 4 - -=item * - -You may try obtaining GCC, available from GNU mirrors worldwide, -listed at <URL:http://www.gnu.org/order/ftp.html>. 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<README.hpux>), it may contain advice on -suitable compilers. - -=item * - -Another alternative may be to use a tool like ansi2knr to convert the -sources back to K&R style, but there is no guarantee this route will get -you anywhere, since the prototypes are not the only ANSI features used -in the Perl sources. ansi2knr is usually found as part of the freely -available Ghostscript distribution. Another similar tool is -unprotoize, distributed with GCC. Since unprotoize requires GCC to -run, you may have to run it on a platform where GCC is available, and move -the sources back to the platform without GCC. - -If you succeed in automatically converting the sources to a K&R compatible -form, be sure to email perlbug@perl.org to let us know the steps you -followed. This will enable us to officially support this option. - -=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 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 20 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, presently. -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 - -=head1 Run Configure - -Configure will figure out various things about your system. Some -things Configure will figure out for itself, other things it will ask -you about. To accept the default, just press RETURN. The default is -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 -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 all 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. - -Starting from Perl 5.6.1 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 - - make all test - -and Perl will be built and tested, all in /tmp/perl/build/directory. - -=head2 Common Configure options - -Configure supports a number of useful options. Run B<Configure -h> 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 - -To compile with gcc you should run - - sh Configure -Dcc=gcc - -This is the preferred way to specify gcc (or 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 -further details.) - -You can specify a different 'prefix' for the default installation -directory, when Configure prompts you or by using the Configure command -line option -Dprefix='/some/directory', e.g. - - sh Configure -Dprefix=/opt/perl - -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. - -NOTE: You must not specify an installation directory that is the same -as or below your perl source directory. If you do, installperl will -attempt infinite recursion. - -=item /usr/bin/perl - -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. - -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 - - Configure -Uinstallusrbinperl - -or by answering 'no' 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 - -If you want to use your old config.sh but override some of the items -with command line options, you need to use B<Configure -O>. - -=back - -If you are willing to accept all the defaults, and you want terse -output, you can run - - sh Configure -des - -Note: for development releases (odd subreleases, like 5.7, as opposed -to maintenance releases which have even subreleases, like 5.6) -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. - -For example for my Solaris system, I usually use - - sh Configure -Dprefix=/opt/perl -Doptimize='-xpentium -xO4' -des - -=head2 GNU-style configure - -If you prefer the GNU-style configure command line interface, you can -use the supplied configure.gnu command, e.g. - - CC=gcc ./configure.gnu - -The configure.gnu script emulates a few of the more common configure -options. Try - - ./configure.gnu --help - -for a listing. - -Cross compiling and compiling in a different directory are not supported. - -(The file is called configure.gnu to avoid problems on systems -that would not distinguish the files "Configure" and "configure".) - -=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. -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. - -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. - -The defaults are intended to be reasonable and sensible for most -people building from sources. Those who build and distribute binary -distributions or who export perl to a range of systems will probably -need to alter them. If you are content to just accept the defaults, -you can safely skip the next section. - -The directories set up by Configure fall into three broad categories. - -=over 4 - -=item Directories for the perl distribution - -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 -variables are in the file Porting/Glossary. - - Configure variable Default value - $prefix /usr/local - $bin $prefix/bin - $scriptdir $prefix/bin - $privlib $prefix/lib/perl5/$version - $archlib $prefix/lib/perl5/$version/$archname - $man1dir $prefix/man/man1 - $man3dir $prefix/man/man3 - $html1dir (none) - $html3dir (none) - -Actually, Configure recognizes the SVR3-style -/usr/local/man/l_man/man1 directories, if present, and uses those -instead. Also, if $prefix contains the string "perl", the library -directories are simplified as described below. For simplicity, only -the common style is shown here. - -=item Directories for site-specific add-on files - -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. - - Configure variable Default value - $siteprefix $prefix - $sitebin $siteprefix/bin - $sitescript $siteprefix/bin - $sitelib $siteprefix/lib/perl5/site_perl/$version - $sitearch $siteprefix/lib/perl5/site_perl/$version/$archname - $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 -distribution, Configure can optionally set up the following directories -for you to use to distribute add-on modules. - - Configure variable Default value - $vendorprefix (none) - (The next ones are set only if vendorprefix is set.) - $vendorbin $vendorprefix/bin - $vendorscript $vendorprefix/bin - $vendorlib $vendorprefix/lib/perl5/vendor_perl/$version - $vendorarch $vendorprefix/lib/perl5/vendor_perl/$version/$archname - $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: - - $prefix /usr/bin - $siteprefix /usr/local/bin - $vendorprefix /usr/bin - -This would have the effect of setting the following: - - $bin /usr/bin - $scriptdir /usr/bin - $privlib /usr/lib/perl5/$version - $archlib /usr/lib/perl5/$version/$archname - $man1dir /usr/man/man1 - $man3dir /usr/man/man3 - - $sitebin /usr/local/bin - $sitescript /usr/local/bin - $sitelib /usr/local/lib/perl5/site_perl/$version - $sitearch /usr/local/lib/perl5/site_perl/$version/$archname - $siteman1 /usr/local/man/man1 - $siteman3 /usr/local/man/man3 - - $vendorbin /usr/bin - $vendorscript /usr/bin - $vendorlib /usr/lib/perl5/vendor_perl/$version - $vendorarch /usr/lib/perl5/vendor_perl/$version/$archname - $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 -installed libraries corresponding to compatible earlier versions. -See L<"Coexistence with earlier versions of perl5"> below for more details -on how Perl can be made to search older version directories. - -Of course you may use these directories however you see fit. For -example, you may wish to use $siteprefix for site-specific files that -are stored locally on your own disk and use $vendorprefix for -site-specific files that are stored elsewhere on your organization's -network. One way to do that would be something like - - sh Configure -Dsiteprefix=/usr/local -Dvendorprefix=/usr/share/perl - -=item otherlibdirs - -As a final catch-all, Configure also offers an $otherlibdirs -variable. This variable contains a colon-separated list of additional -directories to add to @INC. By default, it will be empty. -Perl will search these directories (including architecture and -version-specific subdirectories) for add-on modules and extensions. - -=item APPLLIB_EXP - -There is one other way of adding paths to @INC at perl build time, and -that is by setting the APPLLIB_EXP C pre-processor token to a colon- -separated list of directories, like this - - sh Configure -Accflags='-DAPPLLIB_EXP=\"/usr/libperl\"' - -The directories defined by APPLLIB_EXP get added to @INC I<first>, -ahead of any others, and so provide a way to override the standard perl -modules should you, for example, want to distribute fixes without -touching the perl distribution proper. And, like otherlib dirs, -version and architecture specific subdirectories are also searched, if -present, at run time. Of course, you can still search other @INC -directories ahead of those in APPLLIB_EXP by using any of the standard -run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc. - -=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.6.0/man/man3 - -Some users also prefer to use a .3pm suffix. 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 - -As of perl5.005_57, the standard perl installation does not do -anything with HTML documentation, but that may change in the future. -Further, some add-on modules may wish to install HTML documents. The -html Configure variables listed above are provided if you wish to -specify where such documents should be placed. The default is "none", -but will likely eventually change to something useful based on user -feedback. - -=back - -Some users prefer to append a "/share" to $privlib and $sitelib -to emphasize that those directories can be shared among different -architectures. - -Note that these are just the defaults. You can actually structure the -directories any way you like. They don't even have to be on the same -filesystem. - -Further details about the installation directories, maintenance and -development subversions, and about supporting multiple versions are -discussed in L<"Coexistence with earlier versions of perl5"> below. - -If you specify a prefix that contains the string "perl", then the -library directory structure is slightly simplified. Instead of -suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib. - -Thus, for example, if you Configure with --Dprefix=/opt/perl, then the default library directories for 5.6.0 are - - Configure variable Default value - $privlib /opt/perl/lib/5.6.0 - $archlib /opt/perl/lib/5.6.0/$archname - $sitelib /opt/perl/lib/site_perl/5.6.0 - $sitearch /opt/perl/lib/site_perl/5.6.0/$archname - -=head2 Changing the installation directory - -Configure distinguishes between the directory in which perl (and its -associated files) should be installed and the directory in which it -will eventually reside. For most sites, these two are the same; for -sites that use AFS, this distinction is handled automatically. -However, sites that use software such as depot to manage software -packages, or users building binary packages for distribution may also -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: - - sh Configure -Dinstallprefix=/tmp/perl5 - -(replace /tmp/perl5 by a directory of your choice). - -Beware, though, that if you go to try to install new add-on -modules, they too will get installed in under '/tmp/perl5' if you -follow this example. The next section shows one way of dealing with -that problem. - -=head2 Creating an installable tar archive - -If you need to install perl on many identical systems, it is -convenient to compile it once and create an archive that can be -installed on multiple systems. Suppose, for example, that you want to -create an archive that can be installed in /opt/perl. -Here's one way to do that: - - # Set up to install perl into a different directory, - # e.g. /tmp/perl5 (see previous part). - sh Configure -Dinstallprefix=/tmp/perl5 -Dprefix=/opt/perl -des - make - make test - make install # This will install everything into /tmp/perl5. - cd /tmp/perl5 - # Edit $archlib/Config.pm and $archlib/.packlist to change all the - # install* variables back to reflect where everything will - # really be installed. (That is, change /tmp/perl5 to /opt/perl - # everywhere in those files.) - # Check the scripts in $scriptdir to make sure they have the correct - # #!/wherever/perl line. - tar cvf ../perl5-archive.tar . - # Then, on each machine where you want to install perl, - cd /opt/perl # Or wherever you specified as $prefix - tar xvf perl5-archive.tar - -=head2 Site-wide Policy settings - -After Configure runs, it stores a number of common site-wide "policy" -answers (such as installation directories and the local perl contact -person) in the Policy.sh file. If you want to build perl on another -system using the same policy defaults, simply copy the Policy.sh file -to the new system and Configure will use it along with the appropriate -hint file for your system. - -Alternatively, if you wish to change some or all of those policy -answers, you should - - rm -f Policy.sh - -to ensure that Configure doesn't re-use them. - -Further information is in the Policy_sh.SH file itself. - -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.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. - -=head2 Configure-time Options - -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. - -=head2 Threads - -On some platforms, perl5.005 and later can be compiled with -experimental support for threads. To enable this, read the file -README.threads, and then try: - - sh Configure -Dusethreads - -Currently, you need to specify -Dusethreads on the Configure command -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 - - sh Configure -Dusethreads -Duse5005threads - -or by - sh Configure -Dusethreads -Uuseithreads - -Eventually (by perl v5.6.0) this internal confusion ought to disappear, -and these options may disappear as well. - -=head2 64 bit support. - -If your platform does not have 64 bits natively, but can simulate them with -compiler flags and/or C<long long> or C<int64_t>, 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<use64bitint> 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 C<int>s (it might, -but it doesn't have to): the C<use64bitint> means that you will be -able to have 64 bits wide scalar values. - -The C<use64bitall> goes all the way by attempting to switch also -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 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. - -=head2 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). - -=head2 "more bits" - -You can "Configure -Dusemorebits" to turn on both the 64-bit support -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 - - sh Configure -Duseperlio - -or interactively at the appropriate Configure prompt. - -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. - -=over 4 - -=item 1. - -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. - -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/ - -You select this option by - - sh Configure -Duseperlio -Dusesfio - -If you have already selected -Duseperlio, and if Configure detects -that you have sfio, then sfio will be the default suggested by -Configure. - -Note: On some systems, sfio's iffe configuration script fails to -detect that you have an atexit function (or equivalent). Apparently, -this is a problem at least for some versions of Linux and SunOS 4. -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 -TCP/IP proxy protocol library. SOCKS is used to give applications -access to transport layer network proxies. Perl supports only SOCKS -Version 5. You can find more about SOCKS from http://www.socks.nec.com/ - -=head2 Dynamic Loading - -By default, Configure will compile perl to use dynamic loading if -your system supports it. If you want to force perl to be compiled -statically, you can either choose this when Configure prompts you or -you can use the Configure command line option -Uusedl. - -=head2 Building a shared libperl.so Perl library - -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. - -On some 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 -you might wish to build a shared libperl.so so that all your binaries -can share the same library. - -The disadvantages are that there may be a significant performance -penalty associated with the shared libperl.so, and that the overall -mechanism is still rather fragile with respect to different versions -and upgrades. - -In terms of performance, on my test system (Solaris 2.5_x86) the perl -test suite took roughly 15% longer to run with the shared libperl.so. -Your system and typical applications may well give quite different -results. - -The default name for the shared library is typically something like -libperl.so.3.2 (for Perl 5.003_02) or libperl.so.302 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 - -To build a shared libperl, the environment variable controlling shared -library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_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 -library search settings. - -However, there are some special cases where manually setting the -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 -or - ./perl -Ilib ~/my_mission_critical_test - -then you need to set up the shared library path explicitly. -You can do this with - - LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH - -for Bourne-style shells, or - - setenv LD_LIBRARY_PATH `pwd` - -for Csh-style shells. (This procedure may also be needed if for some -unexpected reason Configure fails to set up makefile correctly.) - -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 - -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.004 with a shared library. Then, suppose you -try to build Perl 5.004 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.4 rather with the installed libperl.so.4? The answer is -that you might not be able to. The installation directory is encoded -in the perl binary with the LD_RUN_PATH environment variable (or -equivalent ld command-line option). On Solaris, you can override that -with LD_LIBRARY_PATH; on Linux you can't. On Digital Unix, you can -override LD_LIBRARY_PATH by setting the _RLD_ROOT environment variable -to point to the perl build directory. - -The only reliable answer is that you should specify a different -directory for the architecture-dependent library for your -DDEBUGGING -version of perl. You can do this by changing all the *archlib* -variables in config.sh to point to your new architecture-dependent library. - -=head2 Malloc Issues - -Perl relies heavily on malloc(3) to grow data structures as needed, -so perl's performance can be noticeably affected by the performance of -the malloc function on your system. The perl source is shipped with a -version of malloc that has been optimized for the typical requests from -perl, so there's a chance that it may be both faster and use less memory -than your system malloc. - -However, if your system already has an excellent malloc, or if you are -experiencing difficulties with extensions that use third-party libraries -that call malloc, then you should probably use your system's malloc. -(Or, you might wish to explore the malloc flags discussed below.) - -=over 4 - -=item Using the system malloc - -To build without perl's malloc, you can use the Configure command - - sh Configure -Uusemymalloc - -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. - -Perl's malloc family of functions are called Perl_malloc(), -Perl_realloc(), Perl_calloc() and Perl_mfree(). When this flag is -not enabled, the names do not clash with the system versions of -these functions. - -If enabled, Perl's malloc family of functions will have the same -names as the system versions. This may be sometimes required when you -have libraries that like to free() data that may have been allocated -by Perl_malloc() and vice versa. - -Note that enabling this option may sometimes lead to duplicate symbols -from the linker for malloc et al. In such cases, the system probably -does not allow its malloc functions to be fully replaced with custom -versions. - -=back - -=head2 Building a debugging perl - -You can run perl scripts under the perl debugger at any time with -B<perl -d your_script>. If, however, you want to debug perl itself, -you probably want to do - - sh Configure -Doptimize='-g' - -This will do two independent things: First, it will force compilation -to use cc -g so that you can use your system's debugger on the -executable. (Note: Your system may actually require something like -cc -g2. Check your man pages for cc(1) and also any hint file for -your system.) Second, it will add -DDEBUGGING to your ccflags -variable in config.sh so that you can use B<perl -D> to access perl's -internal state. (Note: Configure will only add -DDEBUGGING by default -if you are not reusing your old config.sh. If you want to reuse your -old config.sh, then you can just edit it and change the optimize and -ccflags variables by hand and then propagate your changes as shown in -L<"Propagating your changes to config.sh"> below.) - -You can actually specify -g and -DDEBUGGING independently, but usually -it's convenient to have both. - -If you are using a shared libperl, see the warnings about multiple -versions of perl under L<Building a shared libperl.so Perl library>. - -=head2 Extensions - -By default, Configure will offer to build every extension which appears -to be supported. For example, Configure will offer to build GDBM_File -only if it is able to find the gdbm library. (See examples below.) -B, DynaLoader, Fcntl, IO, and attrs are always built by default. -Configure does not contain code to test for POSIX compliance, so POSIX -is always built by default as well. If you wish to skip POSIX, you can -set the Configure variable useposix=false either in a hint file or from -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. - -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. - -Even if you do not have dynamic loading, you must still build the -DynaLoader extension; you should just build the stub dl_none.xs -version. (Configure will suggest this as the default.) - -In summary, here are the Configure command-line variables you can set -to turn off each extension: - - B (Always included by default) - DB_File i_db - DynaLoader (Must always be included as a static extension) - Fcntl (Always included by default) - GDBM_File i_gdbm - IO (Always included by default) - NDBM_File i_ndbm - ODBM_File i_dbm - POSIX useposix - SDBM_File (Always included by default) - Opcode useopcode - Socket d_socket - Threads use5005threads - attrs (Always included by default) - -Thus to skip the NDBM_File extension, you can use - - sh Configure -Ui_ndbm - -Again, this is taken care of automatically if you don't have the ndbm -library. - -Of course, you may always run Configure interactively and select only -the extensions you want. - -Note: The DB_File module will only work with version 1.x of Berkeley -DB or newer releases of version 2. Configure will automatically detect -this for you and refuse to try to build DB_File with earlier -releases of version 2. - -If you re-use your old config.sh but change your system (e.g. by -adding libgdbm) Configure will still offer your old choices of extensions -for the default answer, but it will also point out the discrepancy to -you. - -Finally, if you have dynamic loading (most modern Unix systems do) -remember that these extensions do not increase the size of your perl -executable, nor do they impact start-up time, so you probably might as -well build all the ones that will work on your system. - -=head2 Including locally-installed libraries - -Perl5 comes with interfaces to number of database extensions, including -dbm, ndbm, gdbm, and Berkeley db. For each extension, if -Configure can find the appropriate header files and libraries, it will -automatically include that extension. The gdbm and db libraries -are not included with perl. See the library documentation for -how to obtain the libraries. - -If your database header (.h) files are not in a directory normally -searched by your C compiler, then you will need to include the -appropriate -I/your/directory option when prompted by Configure. If -your database library (.a) files are not in a directory normally -searched by your C compiler and linker, then you will need to include -the appropriate -L/your/directory option when prompted by Configure. -See the examples below. - -=head2 Examples - -=over 4 - -=item gdbm in /usr/local - -Suppose you have gdbm and want Configure to find it and build the -GDBM_File extension. This example assumes you have gdbm.h -installed in /usr/local/include/gdbm.h and libgdbm.a installed in -/usr/local/lib/libgdbm.a. Configure should figure all the -necessary steps out automatically. - -Specifically, when Configure prompts you for flags for -your C compiler, you should include -I/usr/local/include. - -When Configure prompts you for linker flags, you should include --L/usr/local/lib. - -If you are using dynamic loading, then when Configure prompts you for -linker flags for dynamic loading, you should again include --L/usr/local/lib. - -Again, this should all happen automatically. This should also work if -you have gdbm installed in any of (/usr/local, /opt/local, /usr/gnu, -/opt/gnu, /usr/GNU, or /opt/GNU). - -=item gdbm in /usr/you - -Suppose you have gdbm installed in some place other than /usr/local/, -but you still want Configure to find it. To be specific, assume you -have /usr/you/include/gdbm.h and /usr/you/lib/libgdbm.a. You -still have to add -I/usr/you/include to cc flags, but you have to take -an extra step to help Configure find libgdbm.a. Specifically, when -Configure prompts you for library directories, you have to add -/usr/you/lib to the list. - -It is possible to specify this from the command line too (all on one -line): - - sh Configure -de \ - -Dlocincpth="/usr/you/include" \ - -Dloclibpth="/usr/you/lib" - -locincpth is a space-separated list of include directories to search. -Configure will automatically add the appropriate -I directives. - -loclibpth is a space-separated list of library directories to search. -Configure will automatically add the appropriate -L directives. If -you have some libraries under /usr/local/ and others under -/usr/you, then you have to include both, namely - - sh Configure -de \ - -Dlocincpth="/usr/you/include /usr/local/include" \ - -Dloclibpth="/usr/you/lib /usr/local/lib" - -=back - -=head2 Building DB, NDBM, and ODBM interfaces with Berkeley DB 3 - -Perl interface for DB3 is part of Berkeley DB, but if you want to -compile standard Perl DB/ODBM/NDBM interfaces, you must follow -following instructions. - -Berkeley DB3 from Sleepycat Software is by default installed without -DB1 compatibility code (needed for DB_File interface) and without -links to compatibility files. So if you want to use packages written -for DB/ODBM/NDBM interfaces, you need to configure DB3 with ---enable-compat185 (and optionally with --enable-dump185) and create -additional references (suppose you are installing DB3 with ---prefix=/usr): - - ln -s libdb-3.so /usr/lib/libdbm.so - ln -s libdb-3.so /usr/lib/libndbm.so - echo '#define DB_DBM_HSEARCH 1' >dbm.h - echo '#include <db.h>' >>dbm.h - install -m 0644 dbm.h /usr/include/dbm.h - install -m 0644 dbm.h /usr/include/ndbm.h - -Optionally, if you have compiled with --enable-compat185 (not needed -for ODBM/NDBM): - - ln -s libdb-3.so /usr/lib/libdb1.so - ln -s libdb-3.so /usr/lib/libdb.so - -ODBM emulation seems not to be perfect, but is quite usable, -using DB 3.1.17: - - lib/odbm.............FAILED at test 9 - Failed 1/64 tests, 98.44% okay - -=head2 What if it doesn't work? - -If you run into problems, try some of the following ideas. -If none of them help, then see L<"Reporting Problems"> below. - -=over 4 - -=item Running Configure Interactively - -If Configure runs into trouble, remember that you can always run -Configure interactively so that you can check (and correct) its -guesses. - -All the installation questions have been moved to the top, so you don't -have to wait for them. Once you've handled them (and your C compiler and -flags) you can type &-d at the next Configure prompt and Configure -will use the defaults from then on. - -If you find yourself trying obscure command line incantations and -config.over tricks, I recommend you run Configure interactively -instead. You'll probably save yourself time in the long run. - -=item Hint files - -The perl distribution includes a number of system-specific hints files -in the hints/ directory. If one of them matches your system, Configure -will offer to use that hint file. - -Several of the hint files contain additional important information. -If you have any problems, it is a good idea to read the relevant hint file -for further information. See hints/solaris_2.sh for an extensive example. -More information about writing good hints is in the hints/README.hints -file. - -=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. - -For example, suppose you have added libgdbm.a to your system -and you decide to reconfigure perl to use GDBM_File. When you run -Configure again, you will need to add -lgdbm to the list of libraries. -Now, Configure will find your gdbm include file and library and will -issue a message: - - *** WHOA THERE!!! *** - The previous value for $i_gdbm on this machine was "undef"! - Keep the previous value? [y] - -In this case, you do not want to keep the previous value, so you -should answer 'n'. (You'll also have to manually add GDBM_File to -the list of dynamic extensions to build.) - -=item Changing Compilers - -If you change compilers or make other significant changes, you should -probably not re-use your old config.sh. Simply remove it or -rename it, e.g. mv config.sh config.sh.old. Then rerun Configure -with the options you want to use. - -This is a common source of problems. If you change from cc to -gcc, you should almost always remove your old config.sh. - -=item Propagating your changes to config.sh - -If you make any changes to config.sh, you should propagate -them to all the .SH files by running - - sh Configure -S - -You will then have to rebuild by running - - make depend - make - -=item config.over - -You can also supply a shell script config.over to over-ride Configure's -guesses. It will get loaded up at the very end, just before config.sh -is created. You have to be careful with this, however, as Configure -does no checking that your changes make sense. - -=item config.h - -Many of the system dependencies are contained in config.h. -Configure builds config.h by running the config_h.SH script. -The values for the variables are taken from config.sh. - -If there are any problems, you can edit config.h directly. Beware, -though, that the next time you run Configure, your changes will be -lost. - -=item cflags - -If you have any additional changes to make to the C compiler command -line, they can be made in cflags.SH. For instance, to turn off the -optimizer on toke.c, find the line in the switch structure for -toke.c and put the command optimize='-g' before the ;; . You -can also edit cflags directly, but beware that your changes will be -lost the next time you run Configure. - -To explore various ways of changing ccflags from within a hint file, -see the file hints/README.hints. - -To change the C flags for all the files, edit config.sh and change either -$ccflags or $optimize, and then re-run - - sh Configure -S - make depend - -=item No sh - -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. - -=item Environment variable clashes - -Configure uses a CONFIG variable that is reported to cause trouble on -ReliantUnix 5.44. If your system sets this variable, you can try -unsetting it before you run Configure. Configure should eventually -be fixed to avoid polluting the namespace of the environment. - -=item Digital UNIX/Tru64 UNIX and BIN_SH - -In Digital UNIX/Tru64 UNIX, Configure might abort with - -Build a threading Perl? [n] -Configure[2437]: Syntax error at line 1 : `config.sh' is not expected. - -This indicates that Configure is being run with a broken Korn shell -(even though you think you are using a Bourne shell by using -"sh Configure" or "./Configure"). The Korn shell bug has been reported -to Compaq as of February 1999 but in the meanwhile, the reason ksh is -being used is that you have the environment variable BIN_SH set to -'xpg4'. This causes /bin/sh to delegate its duties to /bin/posix/sh -(a ksh). Unset the environment variable and rerun Configure. - -=item HP-UX 11, pthreads, and libgdbm - -If you are running Configure with -Dusethreads in HP-UX 11, be warned -that POSIX threads and libgdbm (the GNU dbm library) compiled before -HP-UX 11 do not mix. This will cause a basic test run by Configure to -fail - -Pthread internal error: message: __libc_reinit() failed, file: ../pthreads/pthread.c, line: 1096 -Return Pointer is 0xc082bf33 -sh: 5345 Quit(coredump) - -and Configure will give up. The cure is to recompile and install -libgdbm under HP-UX 11. - -=item Porting information - -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. - -Ports for other systems may also be available. You should check out -http://www.perl.com/CPAN/ports for current information on ports to -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. -Study also how other non-UNIX ports have solved problems. - -=back - -=head1 make depend - -This will look for all the includes. The output is stored in makefile. -The only difference between Makefile and makefile is the dependencies at -the bottom of makefile. If you have to make any changes, you should edit -makefile, not Makefile since the Unix make command reads makefile first. -(On non-Unix systems, the output may be stored in a different file. -Check the value of $firstmakefile in your config.sh if in doubt.) - -Configure will offer to do this step for you, so it isn't listed -explicitly above. - -=head1 make - -This will attempt to make perl in the current directory. - -=head2 What if it doesn't work? - -If you can't compile successfully, try some of the following ideas. -If none of them help, and careful reading of the error message and -the relevant manual pages on your system doesn't help, -then see L<"Reporting Problems"> below. - -=over 4 - -=item hints - -If you used a hint file, try reading the comments in the hint file -for further tips and information. - -=item extensions - -If you can successfully build miniperl, but the process crashes -during the building of extensions, you should run - - make minitest - -to test your version of miniperl. - -=item locale - -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. -The latter is especially useful if you see something like this - - perl: warning: Setting locale failed. - perl: warning: Please check that your locale settings: - LC_ALL = "En_US", - LANG = (unset) - are supported and installed on your system. - perl: warning: Falling back to the standard locale ("C"). - -at Perl startup. - -=item varargs - -If you get varargs problems with gcc, be sure that gcc is installed -correctly and that you are not passing -I/usr/include to gcc. When using -gcc, you should probably have i_stdarg='define' and i_varargs='undef' -in config.sh. The problem is usually solved by running fixincludes -correctly. If you do change config.sh, don't forget to propagate -your changes (see L<"Propagating your changes to config.sh"> below). -See also the L<"vsprintf"> item below. - -=item util.c - -If you get error messages such as the following (the exact line -numbers and function name may vary in different versions of perl): - - util.c: In function `Perl_form': - util.c:1107: number of arguments doesn't match prototype - proto.h:125: prototype declaration - -it might well be a symptom of the gcc "varargs problem". See the -previous L<"varargs"> item. - -=item LD_LIBRARY_PATH - -If you run into dynamic loading problems, check your setting of -the LD_LIBRARY_PATH environment variable. If you're creating a static -Perl library (libperl.a rather than libperl.so) it should build -fine with LD_LIBRARY_PATH unset, though that may depend on details -of your local set-up. - -=item nm extraction - -If Configure seems to be having trouble finding library functions, -try not using nm extraction. You can do this from the command line -with - - sh Configure -Uusenm - -or by answering the nm extraction question interactively. -If you have previously run Configure, you should not reuse your old -config.sh. - -=item umask not found - -If the build processes encounters errors relating to umask(), the problem -is probably that Configure couldn't find your umask() system call. -Check your config.sh. You should have d_umask='define'. If you don't, -this is probably the L<"nm extraction"> problem discussed above. Also, -try reading the hints file for your system for further information. - -=item vsprintf - -If you run into problems with vsprintf in compiling util.c, the -problem is probably that Configure failed to detect your system's -version of vsprintf(). Check whether your system has vprintf(). -(Virtually all modern Unix systems do.) Then, check the variable -d_vprintf in config.sh. If your system has vprintf, it should be: - - d_vprintf='define' - -If Configure guessed wrong, it is likely that Configure guessed wrong -on a number of other common functions too. This is probably -the L<"nm extraction"> problem discussed above. - -=item do_aspawn - -If you run into problems relating to do_aspawn or do_spawn, the -problem is probably that Configure failed to detect your system's -fork() function. Follow the procedure in the previous item -on L<"nm extraction">. - -=item __inet_* errors - -If you receive unresolved symbol errors during Perl build and/or test -referring to __inet_* symbols, check to see whether BIND 8.1 is -installed. It installs a /usr/local/include/arpa/inet.h that refers to -these symbols. Versions of BIND later than 8.1 do not install inet.h -in that location and avoid the errors. You should probably update to a -newer version of BIND. If you can't, you can either link with the -updated resolver library provided with BIND 8.1 or rename -/usr/local/bin/arpa/inet.h during the Perl build and test process to -avoid the problem. - -=item #error "No DATAMODEL_NATIVE specified" - -This is a common error when trying to build perl on Solaris 2.6 with a -gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files -changed, so you need to update your gcc installation. You can either -rerun the fixincludes script from gcc or take the opportunity to -update your gcc installation. - -=item Optimizer - -If you can't compile successfully, try turning off your compiler's -optimizer. Edit config.sh and change the line - - optimize='-O' - -to - - optimize=' ' - -then propagate your changes with B<sh Configure -S> and rebuild -with B<make depend; make>. - -=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 -other, or you need to undefine some feature that Configure thought was -there but is defective or incomplete. Look through config.h for -likely suspects. If Configure guessed wrong on a number of functions, -you might have the L<"nm extraction"> problem discussed above. - -=item toke.c - -Some compilers will not compile or optimize the larger files (such as -toke.c) without some extra switches to use larger jump offsets or -allocate larger internal tables. You can customize the switches for -each file in cflags. It's okay to insert rules for specific files into -makefile since a default rule only takes effect in the absence of a -specific rule. - -=item Missing dbmclose - -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 Note (probably harmless): No library found for -lsomething - -If you see such a message during the building of an extension, but -the extension passes its tests anyway (see L<"make test"> below), -then don't worry about the warning message. The extension -Makefile.PL goes looking for various libraries needed on various -systems; few systems will need all the possible libraries listed. -For example, a system may have -lcposix or -lposix, but it's -unlikely to have both, so most users will see warnings for the one -they don't have. The phrase 'probably harmless' is intended to -reassure you that nothing unusual is happening, and the build -process is continuing. - -On the other hand, if you are building GDBM_File and you get the -message - - Note (probably harmless): No library found for -lgdbm - -then it's likely you're going to run into trouble somewhere along -the line, since it's hard to see how you can use the GDBM_File -extension without the -lgdbm library. - -It is true that, in principle, Configure could have figured all of -this out, but Configure and the extension building process are not -quite that tightly coordinated. - -=item sh: ar: not found - -This is a message from your shell telling you that the command 'ar' -was not found. You need to check your PATH environment variable to -make sure that it includes the directory with the 'ar' command. This -is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin -directory. - -=item db-recno failure on tests 51, 53 and 55 - -Old versions of the DB library (including the DB library which comes -with FreeBSD 2.1) had broken handling of recno databases with modified -bval settings. Upgrade your DB library or OS. - -=item Bad arg length for semctl, is XX, should be ZZZ - -If you get this error message from the lib/ipc_sysv test, your System -V IPC may be broken. The XX typically is 20, and that is what ZZZ -also should be. Consider upgrading your OS, or reconfiguring your OS -to include the System V semaphores. - -=item lib/ipc_sysv........semget: No space left on device - -Either your account or the whole system has run out of semaphores. Or -both. Either list the semaphores with "ipcs" and remove the unneeded -ones (which ones these are depends on your system and applications) -with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your -system. - -=item GNU binutils - -If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied -tools you may be in for some trouble. For example creating archives -with an old GNU 'ar' and then using a new current vendor-supplied 'ld' -may lead into linking problems. Either recompile your GNU binutils -under your current operating system release, or modify your PATH not -to include the GNU utils before running Configure, or specify the -vendor-supplied utilities explicitly to Configure, for example by -Configure -Dar=/bin/ar. - -=item THIS PACKAGE SEEMS TO BE INCOMPLETE - -The F<Configure> program has not been able to find all the files which -make up the complete Perl distribution. You may have a damaged source -archive file (in which case you may also have seen messages such as -C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on -archive file>), or you may have obtained a structurally-sound but -incomplete archive. In either case, try downloading again from the -official site named at the start of this document. If you do find -that any site is carrying a corrupted or incomplete source code -archive, please report it to the site's maintainer. - -=item invalid token: ## - -You are using a non-ANSI-compliant C compiler. See L<WARNING: This -version requires a compiler that supports ANSI C>. - -=item Miscellaneous - -Some additional things that have been reported for either perl4 or perl5: - -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. - -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 -Patch Bundle" has been reported to break the io/fs test #18 which -tests whether utime() can change timestamps. The Y2K patch seems to -break utime() so that over NFS the timestamps do not get changed -(on local filesystems utime() still works). - -=back - -=head1 make test - -This will run the regression tests on the perl you just made. If -'make test' doesn't say "All tests successful" then something went -wrong. See the file t/README in the t subdirectory. - -Note that you can't run the tests in background if this disables -opening of /dev/tty. You can use 'make test-notty' in that case but -a few tty tests will be skipped. - -=head2 What if make test doesn't work? - -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., - - ./perl 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 - - ./perl harness - -(this assumes that most basic tests succeed, since harness uses -complicated constructs). - -You should also read the individual tests to see if there are any helpful -comments that apply to your system. - -=over 4 - -=item locale - -Note: One possible reason for errors is that some external programs -may be broken due to the combination of your environment and the way -B<make test> exercises them. For example, this may happen if you have -one or more of these environment variables set: LC_ALL LC_CTYPE -LC_COLLATE LANG. In some versions of UNIX, the non-English locales -are known to cause programs to exhibit mysterious errors. - -If you have any of the above environment variables set, please try - - setenv LC_ALL C - -(for C shell) or - - LC_ALL=C;export LC_ALL - -for Bourne or Korn shell) from the command line and then retry -make test. If the tests then succeed, you may have a broken program that -is confusing the testing. Please run the troublesome test by hand as -shown above and see whether you can locate the program. Look for -things like: exec, `backquoted command`, system, open("|...") or -open("...|"). All these mean that Perl is trying to run some -external program. - -=item Out of memory - -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. -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: - - cd t; ./perl op/pat.t - -to see if you have any better luck. If your perl still fails this -test, it does not necessarily mean you have a broken perl. This test -tries to exercise the regular expression subsystem quite thoroughly, -and may well be far more demanding than your normal usage. - -=item Test failures from lib/ftmp-security saying "system possibly insecure" - -Firstly, test failures from the ftmp-security are not necessarily -serious or indicative of a real security threat. That being said, -they bear investigating. - -The tests may fail for the following reasons. Note that each of the -tests is run both in the building directory and the temporary -directory, as returned by File::Spec->tmpdir(). - -(1) If the directory the tests are being run is owned by somebody else -than the user running the tests, or root (uid 0). This failure can -happen if the Perl source code distribution is unpacked in a way that -the user ids in the distribution package are used as-is. Some tar -programs do this. - -(2) If the directory the test are being run in is writable by group -or by other (remember: with UNIX/POSIX semantics, write access to -a directory means the right to add/remove files in that directory), -and there is no sticky bit set in the directory. 'Sticky bit' is -a feature used in some UNIXes to give extra protection to files: if -the bit is on a directory, no one but the owner (or the root) can remove -that file even if the permissions of the directory would allow file -removal by others. This failure can happen if the permissions in the -directory simply are a bit too liberal for the tests' liking. This -may or may not be a real problem: it depends on the permissions policy -used on this particular directory/project/system/site. This failure -can also happen if the system either doesn't support the sticky bit -(this is the case with many non-UNIX platforms: in principle the -File::Temp should know about these platforms and skip the tests), or -if the system supports the sticky bit but for some reason or reasons -it is not being used. This is for example the case with HP-UX: as of -HP-UX release 11.00, the sticky bit is very much supported, but HP-UX -doesn't use it on its /tmp directory as shipped. Also as with the -permissions, some local policy might dictate that the stickiness is -not used. - -(3) If the system supports the POSIX 'chown giveaway' feature and if -any of the parent directories of the temporary file back to the root -directory are 'unsafe', using the definitions given above in (1) and -(2). - -See the documentation for the File::Temp module for more information -about the various security aspects. - -=back - -=head1 make install - -This will put perl into the public directory you specified to -Configure; by default this is /usr/local/bin. It will also try -to put the man pages in a reasonable place. It will not nroff the man -pages, however. You may need to be root to run B<make install>. If you -are not root, you must own the directories in question and you should -ignore any messages about chown not working. - -=head2 Installing perl under different names - -If you want to install perl under a name other than "perl" (for example, -when installing perl with special features enabled, such as debugging), -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 - - make install PERLNAME=perl5 PERLNAME_VERBASE=perl - -This can be useful if you have to install perl as "perl5" (due to an -ancient version in /usr/bin supplied by your vendor, eg). Without this -the versioned binary would be called "perl55.005". - -=head2 Installed files - -If you want to see exactly what will happen without installing -anything, you can run - - ./perl installperl -n - ./perl installman -n - -make install will install the following: - - binaries - - perl, - perl5.nnn where nnn is the current release number. This - will be a link to perl. - suidperl, - sperl5.nnn If you requested setuid emulation. - a2p awk-to-perl translator - - scripts - - cppstdin This is used by perl -P, if your cc -E can't - read from stdin. - c2ph, pstruct Scripts for handling C structures in header files. - s2p sed-to-perl translator - find2perl find-to-perl translator - h2ph Extract constants and simple macros from C headers - h2xs Converts C .h header files to Perl extensions. - perlbug Tool to report bugs in Perl. - perldoc Tool to read perl's pod documentation. - pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules - pod2html, Converters from perl's pod documentation format - pod2latex, to other useful formats. - pod2man, - pod2text, - pod2checker, - pod2select, - pod2usage - splain Describe Perl warnings and errors - dprofpp Perl code profile post-processor - - library files - - in $privlib and $archlib specified to - Configure, usually under /usr/local/lib/perl5/. - - documentation - - man pages in $man1dir, usually /usr/local/man/man1. - module man - pages in $man3dir, usually /usr/local/man/man3. - pod/*.pod in $privlib/pod/. - -Installperl will also create the directories listed above -in L<"Installation Directories">. - -Perl's *.h header files and the libperl library are also installed -under $archlib so that any user may later build new modules, run the -optional Perl compiler, or embed the perl interpreter into another -program even if the Perl source is no longer available. - -Sometimes you only want to install the version-specific parts of the perl -installation. For example, you may wish to install a newer version of -perl alongside an already installed production version of perl without -disabling installation of new modules for the production version. -To only install the version-specific parts of the perl installation, run - - Configure -Dversiononly - -or answer 'y' to the appropriate Configure prompt. Alternatively, -you can just manually run - - ./perl installperl -v - -and skip installman altogether. -See also L<"Maintaining completely separate versions"> for another -approach. - -=head1 Coexistence with earlier versions of perl5 - -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 -around in case the new version causes you problems for some reason. -For example, if you want to be sure that your script continues to run -with 5.004_04, 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.00404. - -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. -(These examples assume you accept all the Configure defaults.) - -Suppose you already have version 5.005_03 installed. The directories -searched by 5.005_03 are - - /usr/local/lib/perl5/5.00503/$archname - /usr/local/lib/perl5/5.00503 - /usr/local/lib/perl5/site_perl/5.005/$archname - /usr/local/lib/perl5/site_perl/5.005 - -Beginning with 5.6.0 the version number in the site libraries are -fully versioned. Now, suppose you install version 5.6.0. The directories -searched by version 5.6.0 will be - - /usr/local/lib/perl5/5.6.0/$archname - /usr/local/lib/perl5/5.6.0 - /usr/local/lib/perl5/site_perl/5.6.0/$archname - /usr/local/lib/perl5/site_perl/5.6.0 - - /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 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, -suppose that you upgrade a module to one which requires features -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. - -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 -by 5.6.1 (if you don't change the Configure defaults) will be: - - /usr/local/lib/perl5/5.6.1/$archname - /usr/local/lib/perl5/5.6.1 - /usr/local/lib/perl5/site_perl/5.6.1/$archname - /usr/local/lib/perl5/site_perl/5.6.1 - - /usr/local/lib/perl5/site_perl/5.6.0/$archname - /usr/local/lib/perl5/site_perl/5.6.0 - - /usr/local/lib/perl5/site_perl/5.005/$archname - /usr/local/lib/perl5/site_perl/5.005 - /usr/local/lib/perl5/site_perl/ - -Assuming the users in your site are still actively using perl 5.6.0 and -5.005 after you installed 5.6.1, you can continue to install add-on -extensions using any of perl 5.6.1, 5.6.0, or 5.005. The installations -of these different versions remain distinct, but remember that the newer -versions of perl are automatically set up to search the site libraries of -the older ones. This means that installing a new extension with 5.005 -will make it visible to all three versions. Later, if you install the -same extension using, say, perl 5.6.1, it will override the 5.005-installed -version, but only for perl 5.6.1. - -This way, you can choose to share compatible extensions, but also upgrade -to a newer version of an extension that may be incompatible with earlier -versions, without breaking the earlier versions' installations. - -=head2 Maintaining completely separate versions - -Many users prefer to keep all versions of perl in completely -separate directories. This guarantees that an update to one version -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.004 - -and adding /opt/perl5.004/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. - -Others might share a common directory for maintenance sub-versions -(e.g. 5.004 for all 5.004_0x versions), but change directory with -each major version. - -If you are installing a development subversion, you probably ought to -seriously consider using a separate directory, since development -subversions may not have all the compatibility wrinkles ironed out -yet. - -=head2 Upgrading from 5.005 to 5.6.0 - -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 - -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 pod/perltrap.pod 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 -system header files. This command will convert the most commonly used -header files in /usr/include into files that can be easily interpreted -by perl. These files will be placed in the architecture-dependent -library ($archlib) directory you specified to Configure. - -Note: Due to differences in the C and perl languages, the conversion -of the header files is not perfect. You will probably have to -hand-edit some of the converted files to get them to parse correctly. -For example, h2ph breaks spectacularly on type casting and certain -structures. - -=head1 installhtml --help - -Some sites may wish to make perl documentation available in HTML -format. The installhtml utility can be used to convert pod -documentation into linked HTML files and install them. - -Currently, the supplied ./installhtml script does not make use of the -html Configure variables. This should be fixed in a future release. - -The following command-line is an example of one used to convert -perl documentation: - - ./installhtml \ - --podroot=. \ - --podpath=lib:ext:pod:vms \ - --recurse \ - --htmldir=/perl/nmanual \ - --htmlroot=/perl/nmanual \ - --splithead=pod/perlipc \ - --splititem=pod/perlfunc \ - --libpods=perlfunc:perlguts:perlvar:perlrun:perlop \ - --verbose - -See the documentation in installhtml for more details. It can take -many minutes to execute a large installation and you should expect to -see warnings like "no title", "unexpected directive" and "cannot -resolve" as the files are processed. We are aware of these problems -(and would welcome patches for them). - -You may find it helpful to run installhtml twice. That should reduce -the number of "cannot resolve" warnings. - -=head1 cd pod && make tex && (process the latex files) - -Some sites may also wish to make the documentation in the pod/ directory -available in TeX format. Type - - (cd pod && make tex && <process the latex files>) - -=head1 Reporting Problems - -If you have difficulty building perl, and none of the advice in this file -helps, and careful reading of the error message and the relevant manual -pages on your system doesn't help either, then you should send a message -to either the comp.lang.perl.misc newsgroup or to perlbug@perl.org with -an accurate description of your problem. - -Please include the output of the ./myconfig shell script that comes with -the distribution. Alternatively, you can use the perlbug program that -comes with the perl distribution, but you need to have perl compiled -before you can use it. (If you have not installed it yet, you need to -run C<./perl -Ilib utils/perlbug> instead of a plain C<perlbug>.) - -Please try to make your message brief but clear. Trim out unnecessary -information. Do not include large files (such as config.sh or a complete -Configure or make log) unless absolutely necessary. Do not include a -complete transcript of your build session. Just include the failing -commands, the relevant error messages, and whatever preceding commands -are necessary to give the appropriate context. Plain text should -usually be sufficient--fancy attachments or encodings may actually -reduce the number of people who read your message. Your message -will get relayed to over 400 subscribers around the world so please -try to keep it brief but clear. - -=head1 DOCUMENTATION - -Read the manual entries before running perl. The main documentation -is in the pod/ subdirectory and should have been installed during the -build process. Type B<man perl> to get started. Alternatively, you -can type B<perldoc perl> to use the supplied perldoc script. This is -sometimes useful for finding things in the library modules. - -Under UNIX, you can produce a documentation book in postscript form, -along with its table of contents, by going to the pod/ subdirectory and -running (either): - - ./roffitall -groff # If you have GNU groff installed - ./roffitall -psroff # If you have psroff - -This will leave you with two postscript files ready to be printed. -(You may need to fix the roffitall command to use your local troff -set-up.) - -Note that you must have performed the installation already before running -the above, since the script collects the installed files to generate -the documentation. - -=head1 AUTHOR - -Original author: Andy Dougherty doughera@lafayette.edu , borrowing very -heavily from the original README by Larry Wall, with lots of helpful -feedback and additions from the perl5-porters@perl.org folks. - -If you have problems, corrections, or questions, please see -L<"Reporting Problems"> above. - -=head1 REDISTRIBUTION - -This document is part of the Perl package and may be distributed under -the same terms as perl itself, with the following additional request: -If you are distributing a modified version of perl (perhaps as part of -a larger package) please B<do> modify these installation instructions -and the contact information to match your distribution. - -=head1 LAST MODIFIED - -$Id: INSTALL,v 1.58 1999/07/23 14:43:00 doughera Exp $ |
