# You may also wish to add these:
(cd /usr/include && h2ph *.h sys/*.h)
- (cd pod && make html && mv *.html <www home dir>)
+ (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 L<"Porting information"> 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.
+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
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 Space Requirements
The complete perl5 source tree takes up about 7 MB of disk space. The
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 ok.
+is almost always ok. 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.
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>.
-If you are willing to accept all the defaults, and you want terse
-output, you can run
-
- sh Configure -des
-
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
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.
+
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
appropriate questions in Configure. For convenience, all the
installation questions are near the beginning of Configure.
-It is highly recommend that you 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
-C<&-d> and Configure will use the defaults from then on.
+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 uses the following directories for
library files (archname is a string like sun4-sunos, determined
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. You could
-also set them all from the Configure command line. 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):
+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
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.
+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
=over 4
-=item -DDEBUGGING_MSTATS
+=item -DPERL_EMERGENCY_SBRK
-If DEBUGGING_MSTATS is defined, you can extract malloc
-statistics from the Perl interpreter. The overhead this imposes is not
-large (perl just twiddles integers at malloc/free/sbrk time). When you
-run perl with the environment variable PERL_DEBUG_MSTATS set to
-either 1 or 2, the interpreter will dump statistics to stderr at exit
-time and (with a value of 2) after compilation. If you install the
-Devel::Peek module you can get the statistics whenever you like by
-invoking its mstat() function.
-
-=item -DEMERGENCY_SBRK
-
-If EMERGENCY_SBRK is defined, running out of memory need not be a
+If PERL_EMERGENCY_SBRK is defined, running out of memory need not be a
fatal error: a memory pool can allocated by assigning to the special
variable $^M. See perlvar(1) for more details.
sh Configure -Doptimize='-g'
-This will do two things: First, it will force compilation to use
-cc -g so that you can use your system's debugger on the executable.
-Second, it will add a -DDEBUGGING to your ccflags variable in
+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 you 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, however, that Configure will only add -DDEBUGGING by
+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.
+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>.
sh Configure -Dccflags='-Drand=random -Dsrand=srandom'
-or by adding -Drand=random and -Dsrandom=srandom to your ccflags
-at the appropriate Configure prompt. (You may also have to adjust
-Configure's guess for 'randbits' as well.)
+or by adding -Drand=random and -Dsrand=srandom to your ccflags
+at the appropriate Configure prompt. (Note: Although this worked for
+me, it might not work for you if your system's header files give
+different prototypes for rand() and random() or srand() and srandom().)
+
+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?
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. Alternatively, you can use the GCC_EXEC_PREFIX
+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,
fork() function. Follow the procedure in the previous items
on L<"vsprintf"> and 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
=head1 make test
-This will run the regression tests on the perl you just made. If it
-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.
+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.
+
+If you want to run make test in the background you should
+Note that you can't run the tests in background if this disables
+opening of /dev/tty.
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
may also wish to add a symbolic link /usr/local/bin/perl so that
scripts can still start with #!/usr/local/bin/perl.
+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.
+
=head1 Coexistence with perl4
You can safely install perl5 even if you want to keep perl4 around.
correctly. For example, h2ph breaks spectacularly on type casting and
certain structures.
-=head1 cd pod && make html && mv *.html (www home dir)
+=head 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 install them.
-Some sites may wish to make the documentation in the pod/ directory
-available in HTML format. Type
+The following command-line is an example of the one we use to convert
+perl documentation:
- cd pod && make html && mv *.html <www home dir>
+ ./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
-where F<www home dir> is wherever your site keeps HTML files.
+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).
=head1 cd pod && make tex && (process the latex files)
=head1 LAST MODIFIED
-$Id: INSTALL,v 1.11 1997/03/26 19:08:06 doughera Released $
+$Id: INSTALL,v 1.22 1997/08/01 15:39:14 doughera Released $
projects / p5sagit/p5-mst-13.2.git / blobdiff