# 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
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. To compile with gcc, for example, you can run
+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
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
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
(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
+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 location may change in a
-future release of perl.)
+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
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
make test
make install
cd /tmp/perl5
+ # Edit lib/<archname>/<version>/Config.pm to change all the
+ # install* variables back to reflect where everything will
+ # really be installed.
tar cvf ../perl5-archive.tar .
# Then, on each machine where you want to install perl,
cd /usr/local # Or wherever you specified as $prefix
=head2 Binary Compatibility With Earlier Versions of Perl 5
-If you have dynamically loaded extensions that you built under
-perl 5.003 and that you wish to continue to use with perl 5.004, then you
-need to ensure that 5.004 remains binary compatible with 5.003.
-
-Starting with Perl 5.003, all functions in the Perl C source code have
-been protected by default by the prefix Perl_ (or perl_) so that you
-may link with third-party libraries without fear of namespace
-collisions. This change broke compatibility with version 5.002, so
-installing 5.003 or 5.004 over 5.002 or earlier will force you to
-re-build and install all of your dynamically loadable extensions.
-(The standard extensions supplied with Perl are handled
+For Perl 5.004 it was possible to be binary compatible with 5.003.
+Starting from Perl 5.005 this is no more possible because 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 and the so-called 'bincompat3' mode (the default mode)
+and that you wish to continue to use with perl 5.005, you may need to
+reinstall the extensions.
+
+Background: starting with Perl 5.003, all functions in the Perl C
+source code have been protected by default by the prefix Perl_ (or
+perl_) so that you may link with third-party libraries without fear of
+namespace collisions. This change broke compatibility with version
+5.002, so installing 5.003 or 5.004 over 5.002 or earlier will force
+you to re-build and install all of your dynamically loadable
+extensions. (The standard extensions supplied with Perl are handled
automatically). You can turn off this namespace protection by adding
-DNO_EMBED to your ccflags variable in config.sh.
-Perl 5.003's namespace protection was incomplete, but this has
-been fixed in 5.004. However, some sites may need to maintain
-complete binary compatibility with Perl 5.003. If you are building
-Perl for such a site, then when Configure asks if you want binary
-compatibility, answer "y".
-
-On the other hand, if you are embedding perl into another application
-and want the maximum namespace protection, then you probably ought to
-answer "n" when Configure asks if you want binary compatibility.
-
-The default answer of "y" to maintain binary compatibility is probably
-appropriate for almost everyone.
-
-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 for
-a description of what's changed.
+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.
=head2 Selecting File IO mechanisms
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
-version of perl. You can do this with by changing all the *archlib*
+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.
=over 4
-=item -DDEBUGGING_MSTATS
-
-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
+=item -DPERL_EMERGENCY_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.
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.
+
+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.
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
./perl harness
-(this assumes that most tests succeed, since harness uses
+(this assumes that most basic tests succeed, since harness uses
complicated constructs).
-You can also read the individual tests to see if there are any helpful
+You should also read the individual tests to see if there are any helpful
comments that apply to your system.
Note: One possible reason for errors is that some external programs
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)
+=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:
-Some sites may wish to make the documentation in the pod/ directory
-available in HTML format. Type
+ ./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
- cd pod && make html && mv *.html <www home dir>
+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).
-where F<www home dir> is wherever your site keeps HTML files.
+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)
=head1 AUTHOR
-Andy Dougherty doughera@lafcol.lafayette.edu , borrowing very heavily
-from the original README by Larry Wall, and also with lots of helpful
-feedback from the perl5-porters@perl.org folks.
+Original author: Andy Dougherty doughera@lafcol.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 or questions, please see L<"Reporting Problems">
+above.
=head1 LAST MODIFIED
-$Id: INSTALL,v 1.13 1997/04/03 18:29:14 doughera Released $
+$Id: INSTALL,v 1.28 1997/10/10 16:50:59 doughera Released $
projects / p5sagit/p5-mst-13.2.git / blobdiff