diff options
Diffstat (limited to 'contrib/perl5/INSTALL')
| -rw-r--r-- | contrib/perl5/INSTALL | 1599 |
1 files changed, 1599 insertions, 0 deletions
diff --git a/contrib/perl5/INSTALL b/contrib/perl5/INSTALL new file mode 100644 index 0000000..a892e7d --- /dev/null +++ b/contrib/perl5/INSTALL @@ -0,0 +1,1599 @@ +=head1 NAME + +Install - Build and Installation guide for perl5. + +=head1 SYNOPSIS + +The basic steps to build and install perl5 on a Unix system are: + + rm -f config.sh Policy.sh + sh Configure + 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. + +For information on non-Unix systems, see the section on +L<"Porting information"> 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 + +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.) + +=head1 WARNING: This version is not binary compatible with Perl 5.004. + +Starting with Perl 5.004_50 there were many deep and far-reaching changes +to the language internals. If you have dynamically loaded extensions +that you built under perl 5.003 or 5.004, you can continue to use them +with 5.004, but you will need to rebuild and reinstall those extensions +to use them 5.005. See the discussions below on +L<"Coexistence with earlier versions of perl5"> and +L<"Upgrading from 5.004 to 5.005"> for more details. + +The standard extensions supplied with Perl will be handled automatically. + +In a related issue, old extensions may possibly be affected by the +changes in the Perl language in the current release. Please see +pod/perldelta.pod for a description of what's changed. + +=head1 Space Requirements + +The complete perl5 source tree takes up about 10 MB of disk space. The +complete tree after completing make takes roughly 20 MB, though the +actual total is likely to be quite system-dependent. The installation +directories need something on the order of 10 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 or rename it, e.g. + + mv config.sh config.sh.old + +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. Some Linux systems +(such as Debian) use i386, while others may use i486, i586, or i686. +If you pick up a precompiled binary, it might not use the same 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 new Policy.sh file. See the section on +L<"Site-wide Policy settings"> below. + +=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. 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. + +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. + +To compile with gcc, for example, 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. + +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>. + +By default, for most systems, perl will be installed in +/usr/local/{bin, lib, man}. 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 directories +are simplified. For example, if you use prefix=/opt/perl, +then Configure will suggest /opt/perl/lib instead of +/opt/perl/lib/perl5/. + +NOTE: You must not specify an installation directory that is below +your perl source directory. If you do, installperl will attempt +infinite recursion. + +It may seem obvious to say, 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, of overwriting a version of perl supplied by your +vendor. 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. + +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. + +If you are willing to accept all the defaults, and you want terse +output, you can run + + sh Configure -des + +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 is not supported. + +(The file is called configure.gnu to avoid problems on systems +that would not distinguish the files "Configure" and "configure".) + +=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. + +You can learn more about each of these 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 usethreads + 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 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. + +Note: 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 examples 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. If you want to accept the +defaults for all the questions and have Configure print out only terse +messages, then you can just run + + sh Configure -des + +and Configure should include the GDBM_File extension automatically. + +This should actually 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 -des \ + -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 -des \ + -Dlocincpth="/usr/you/include /usr/local/include" \ + -Dloclibpth="/usr/you/lib /usr/local/lib" + +=back + +=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. + +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. + +By default, Configure will use the following directories for library files +for 5.005 (archname is a string like sun4-sunos, determined by Configure). + + Configure variable Default value + $archlib /usr/local/lib/perl5/5.005/archname + $privlib /usr/local/lib/perl5/5.005 + $sitearch /usr/local/lib/perl5/site_perl/5.005/archname + $sitelib /usr/local/lib/perl5/site_perl/5.005 + +Some users prefer to append a "/share" to $privlib and $sitelib +to emphasize that those directories can be shared among different +architectures. + +By default, Configure will use the following directories for manual pages: + + Configure variable Default value + $man1dir /usr/local/man/man1 + $man3dir /usr/local/lib/perl5/man/man3 + +(Actually, Configure recognizes the SVR3-style +/usr/local/man/l_man/man1 directories, if present, and uses those +instead.) + +The module man pages are stuck in that strange spot so that +they don't collide with other man pages stored in /usr/local/man/man3, +and so that Perl's man pages don't hide system man pages. On some +systems, B<man less> would end up calling up Perl's less.pm module man +page, rather than the less program. (This default location will likely +change to /usr/local/man/man3 in a future release of perl.) + +Note: Many users prefer to store the module man pages in +/usr/local/man/man3. You can do this from the command line with + + sh Configure -Dman3dir=/usr/local/man/man3 + +Some users also prefer to use a .3pm suffix. You can do that with + + sh Configure -Dman3ext=3pm + +If you specify a prefix that contains the string "perl", then the +directory structure is simplified. For example, if you Configure with +-Dprefix=/opt/perl, then the defaults for 5.005 are + + Configure variable Default value + $archlib /opt/perl/lib/5.005/archname + $privlib /opt/perl/lib/5.005 + $sitearch /opt/perl/lib/site_perl/5.005/archname + $sitelib /opt/perl/lib/site_perl/5.005 + + $man1dir /opt/perl/man/man1 + $man3dir /opt/perl/man/man3 + +The perl executable will search the libraries in the order given +above. + +The directories under site_perl are empty, but are intended to be used +for installing local or site-wide extensions. Perl will automatically +look in these directories. + +In order to support using things like #!/usr/local/bin/perl5.005 after +a later version is released, architecture-dependent libraries are +stored in a version-specific directory, such as +/usr/local/lib/perl5/archname/5.005/. + +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. + +Again, these are just the defaults, and can be changed as you run +Configure. + +=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 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 this. Someday, Configure may support +an option -Dinstallprefix=/foo to simplify this. + +Suppose you want to install perl under the /tmp/perl5 directory. You +can edit config.sh and change all the install* variables to point to +/tmp/perl5 instead of /usr/local/wherever. Or, you can automate this +process by placing the following lines in a file config.over before you +run Configure (replace /tmp/perl5 by a directory of your choice): + + installprefix=/tmp/perl5 + test -d $installprefix || mkdir $installprefix + test -d $installprefix/bin || mkdir $installprefix/bin + installarchlib=`echo $installarchlib | sed "s!$prefix!$installprefix!"` + installbin=`echo $installbin | sed "s!$prefix!$installprefix!"` + installman1dir=`echo $installman1dir | sed "s!$prefix!$installprefix!"` + installman3dir=`echo $installman3dir | sed "s!$prefix!$installprefix!"` + installprivlib=`echo $installprivlib | sed "s!$prefix!$installprefix!"` + installscript=`echo $installscript | sed "s!$prefix!$installprefix!"` + installsitelib=`echo $installsitelib | sed "s!$prefix!$installprefix!"` + installsitearch=`echo $installsitearch | sed "s!$prefix!$installprefix!"` + +Then, you can Configure and install in the usual way: + + sh Configure -des + make + make test + make install + +Beware, though, that if you go to try to install new add-on +extensions, 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. Here's one way to do that: + + # Set up config.over to install perl into a different directory, + # e.g. /tmp/perl5 (see previous part). + sh Configure -des + make + make test + make install + cd /tmp/perl5 + # Edit $archlib/Config.pm to change all the + # install* variables back to reflect where everything will + # really be installed. + # Edit any of the scripts in $scriptdir to have the correct + # #!/wherever/perl line. + tar cvf ../perl5-archive.tar . + # Then, on each machine where you want to install perl, + cd /usr/local # 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. + +=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 can be compiled to use 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. + +=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. +A (fairly old) version of sfio is in CPAN. + +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. + +You can test if you have this problem by trying the following shell +script. (You may have to add some extra cflags and libraries. A +portable version of this may eventually make its way into Configure.) + + #!/bin/sh + cat > try.c <<'EOCP' + #include <stdio.h> + main() { printf("42\n"); } + EOCP + cc -o try try.c -lsfio + val=`./try` + if test X$val = X42; then + echo "Your sfio looks ok" + else + echo "Your sfio has the exit problem." + fi + +If you have this problem, the fix is to go back to your sfio sources +and correct iffe's guess about atexit. + +There also might be a more recent release of Sfio that fixes your +problem. + +=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 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 actually build perl, you must add the current working directory to your +LD_LIBRARY_PATH environment variable before running make. 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. You *MUST* do this before running make. +Folks running NeXT OPENSTEP must substitute DYLD_LIBRARY_PATH for +LD_LIBRARY_PATH above. + +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, namely archlib, archlib_exp, and +installarchlib, 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 is very fast but +somewhat wasteful of space. On the other hand, your system's malloc +function may be a bit slower but also a bit more frugal. However, +as of 5.004_68, perl's malloc has been optimized for the typical +requests from perl, so there's a chance that it may be both faster and +use less memory. + +For many uses, speed is probably the most important consideration, so +the default behavior (for most systems) is to use the malloc supplied +with perl. However, if you will be running very large applications +(e.g. Tk or PDL) or 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 might wish to use +your system's malloc. (Or, you might wish to explore the malloc flags +discussed below.) + +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. + +=head2 Malloc Performance Flags + +If you are using Perl's malloc, you may add one or more of the following +items to your ccflags config.sh variable to change its behavior. You can +find out more about these and other flags by reading the commentary near +the top of the malloc.c source. The defaults should be fine for +nearly everyone. + +=over 4 + +=item -DNO_FANCY_MALLOC + +Undefined by default. Defining it returns malloc to the version used +in Perl 5.004. + +=item -DPLAIN_MALLOC + +Undefined by default. Defining it in addition to NO_FANCY_MALLOC returns +malloc to the version used in Perl version 5.000. + +=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 Other Compiler Flags + +For most users, all of the Configure defaults are fine. However, +you can change a number of factors in the way perl is built +by adding appropriate -D directives to your ccflags variable in +config.sh. + +For example, you can replace the rand() and srand() functions in the +perl source by any other random number generator by a trick such as the +following (this should all be on one line): + + sh Configure -Dccflags='-Dmy_rand=random -Dmy_srand=srandom' \ + -Drandbits=31 + +or you can use the drand48 family of functions with + + sh Configure -Dccflags='-Dmy_rand=lrand48 -Dmy_srand=srand48' \ + -Drandbits=31 + +or by adding the -D flags to your ccflags at the appropriate Configure +prompt. (Read pp.c to see how this works.) + +You should also run Configure interactively to verify that a hint file +doesn't inadvertently override your ccflags setting. (Hints files +shouldn't do that, but some might.) + +=head2 What if it doesn't work? + +=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. See the section on +L<"Changing the installation directory"> for an example. + +=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_H +to config.h and edit the config.h to reflect your system's peculiarities. +You'll probably also have to extensively modify the extension building +mechanism. + +=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. + +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. + +=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. + +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, you can +send a message to either the comp.lang.perl.misc newsgroup or to +perlbug@perl.com with an accurate description of your problem. +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 malloc duplicates + +If you get duplicates upon linking for malloc et al, add -DEMBEDMYMALLOC +to your ccflags variable in config.sh. + +=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 Solaris and SunOS dynamic loading + +If you have problems with dynamic loading using gcc on SunOS or +Solaris, and you are using GNU as and GNU ld, you may need to add +-B/bin/ (for SunOS) or -B/usr/ccs/bin/ (for Solaris) to your +$ccflags, $ldflags, and $lddlflags so that the system's versions of as +and ld are used. Note that the trailing '/' is required. +Alternatively, you can use the GCC_EXEC_PREFIX +environment variable to ensure that Sun's as and ld are used. Consult +your gcc documentation for further information on the -B option and +the GCC_EXEC_PREFIX variable. + +One convenient way to ensure you are not using GNU as and ld is to +invoke Configure with + + sh Configure -Dcc='gcc -B/usr/ccs/bin/' + +for Solaris systems. For a SunOS system, you must use -B/bin/ +instead. + +Alternatively, recent versions of GNU ld reportedly work if you +include C<-Wl,-export-dynamic> in the ccdlflags variable in +config.sh. + +=item ld.so.1: ./perl: fatal: relocation error: + +If you get this message on SunOS or Solaris, and you're using gcc, +it's probably the GNU as or GNU ld problem in the previous item +L<"Solaris and SunOS dynamic loading">. + +=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 dlopen: stub interception failed + +The primary cause of the 'dlopen: stub interception failed' message is +that the LD_LIBRARY_PATH environment variable includes a directory +which is a symlink to /usr/lib (such as /lib). + +The reason this causes a problem is quite subtle. The file libdl.so.1.0 +actually *only* contains functions which generate 'stub interception +failed' errors! The runtime linker intercepts links to +"/usr/lib/libdl.so.1.0" and links in internal implementation of those +functions instead. [Thanks to Tim Bunce for this explanation.] + +=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 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 adding a -DCRIPPLED_CC +flag. (Just because you get no errors doesn't mean it compiled right!) +This simplifies some complicated expressions for compilers that get +indigestion easily. + +=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 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 + +=back + +=head1 make test + +This will run the regression tests on the perl you just made (you +should run plain 'make' before 'make test' otherwise you won't have a +complete build). 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. +Specifically, in perl5.004_64, tests 74 and 78 have been reported to +fail on some systems. On my SparcStation IPC with 8 MB of RAM, test 78 +will fail if the system is running any other significant tasks at the +same time. + +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. + +=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 + +=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: + + 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 + 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, and + pod2text + splain Describe Perl warnings and errors + + library files in $privlib and $archlib specified to + Configure, usually under /usr/local/lib/perl5/. + man pages in the location specified to Configure, usually + something like /usr/local/man/man1. + module in the location specified to Configure, usually + man pages under /usr/local/lib/perl5/man/man3. + pod/*.pod in $privlib/pod/. + +Installperl will also create the library directories $siteperl and +$sitearch listed in config.sh. Usually, these are something like + + /usr/local/lib/perl5/site_perl/5.005 + /usr/local/lib/perl5/site_perl/5.005/archname + +where archname is something like sun4-sunos. These directories +will be used for installing extensions. + +Perl's *.h header files and the libperl.a library are also installed +under $archlib so that any user may later build new extensions, run the +optional Perl compiler, or embed the perl interpreter into another +program even if the Perl source is no longer available. + +=head1 Coexistence with earlier versions of perl5 + +WARNING: The upgrade from 5.004_0x to 5.005 is going to be a bit +tricky. See L<"Upgrading from 5.004 to 5.005"> below. + +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.) + +The directories searched by version 5.005 will be + + Configure variable Default value + $archlib /usr/local/lib/perl5/5.005/archname + $privlib /usr/local/lib/perl5/5.005 + $sitearch /usr/local/lib/perl5/site_perl/5.005/archname + $sitelib /usr/local/lib/perl5/site_perl/5.005 + +while the directories searched by version 5.005_01 will be + + $archlib /usr/local/lib/perl5/5.00501/archname + $privlib /usr/local/lib/perl5/5.00501 + $sitearch /usr/local/lib/perl5/site_perl/5.005/archname + $sitelib /usr/local/lib/perl5/site_perl/5.005 + +When you install an add-on extension, it gets installed into $sitelib (or +$sitearch if it is architecture-specific). This directory deliberately +does NOT include the sub-version number (01) so that both 5.005 and +5.005_01 can use the extension. Only when a perl version changes to +break backwards compatibility will the default suggestions for the +$sitearch and $sitelib version numbers be increased. + +However, if you do run into problems, and you want to continue to use the +old version of perl along with your extension, move those extension files +to the appropriate version directory, such as $privlib (or $archlib). +(The extension's .packlist file lists the files installed with that +extension. For the Tk extension, for example, the list of files installed +is in $sitearch/auto/Tk/.packlist.) Then use your newer version of perl +to rebuild and re-install the extension into $sitelib. This way, Perl +5.005 will find your files in the 5.005 directory, and newer versions +of perl will find your newer extension in the $sitelib directory. +(This is also why perl searches the site-specific libraries last.) + +Alternatively, if you are willing to reinstall all your extensions +every time you upgrade perl, then you can include the subversion +number in $sitearch and $sitelib when you run Configure. + +=head2 Maintaining completely separate versions + +Many users prefer to keep all versions of perl in completely +separate directories. 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.004 to 5.005 + +Extensions built and installed with versions of perl prior to 5.004_50 +will need to be recompiled to be used with 5.004_50 and later. You will, +however, be able to continue using 5.004 even after you install 5.005. +The 5.004 binary will still be able to find the extensions built under +5.004; the 5.005 binary will look in the new $sitearch and $sitelib +directories, and will not find them. + +=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. + +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.com 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>.) + +You might also find helpful information in the Porting directory of the +perl distribution. + +=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. + +If you are distributing a modified version of perl (perhaps as part of +a larger package) please do modify these installation instructions and +the contact information to match your distribution. + +=head1 LAST MODIFIED + +$Id: INSTALL,v 1.42 1998/07/15 18:04:44 doughera Released $ |
