=head1 SYNOPSIS
+ ****************************
+ *** NEEDS WORK FOR 5.004 ***
+ ****************************
+
The basic steps to build and install perl5 on a Unix system are:
rm -f config.sh
make
make test
make install
+ # possibly add these:
+ (cd /usr/include && h2ph *.h sys/*.h)
+ cd pod; make html && mv *.html <www home dir> && cd ..
+ cd pod; make tex && <process the latex files> && cd ..
+
Each of these is explained in further detail below.
mv config.sh config.sh.old
-Then run Configure.
+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
+call themselves i486, while others use i586. 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.
=head1 Run Configure.
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
-/usr/local/lib/perl5/.
+/opt/perl/lib/perl5/.
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 by
-using the Configure command line option -Uusedl.
+statically, you can either choose this when Configure prompts you or
+you can use the Configure command line option -Uusedl.
+
+=head2 GNU-style configure
+
+If you prefer the GNU-style B<configure> command line interface, you can
+use the supplied B<configure> command, e.g.
+
+ CC=gcc ./configure
+
+The B<configure> script emulates several of the more common configure
+options. Try
+
+ ./configure --help
+
+for a listing.
+
+Cross compiling is currently not supported.
+
+For systems that do not distinguish the files "Configure" and
+"configure", Perl includes a copy of B<configure> named
+B<configure.gnu>.
+
+=head2 Binary Compatibility With Earlier Versions of Perl 5
+
+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
+collisons. This change broke compatability 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, which has been
+rectified in Perl 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 B<Configure> asks if you want binary
+compatibility, answer "y".
=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.)
-DynaLoader, Fcntl and FileHandle 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
+DynaLoader, Fcntl, and IO 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.
+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:
DB_File i_db
- DynaLoader (Must always be included)
+ DynaLoader (Must always be included as a static extension)
Fcntl (Always included by default)
- FileHandle (Always included by default)
GDBM_File i_gdbm
IO (Always included by default)
NDBM_File i_ndbm
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 GNU-style configure
-
-If you prefer the GNU-style B<configure> command line interface, you can
-use the supplied B<configure> command, e.g.
-
- CC=gcc ./configure
-
-The B<configure> script emulates several of the more common configure
-options. Try
-
- ./configure --help
-
-for a listing.
-
-Cross compiling is currently not supported.
-
=head2 Including locally-installed libraries
Perl5 comes with interfaces to number of database extensions, including
library files (archname is a string like sun4-sunos, determined
by Configure)
- /usr/local/lib/perl5/archname/5.002
+ /usr/local/lib/perl5/archname/5.004
/usr/local/lib/perl5/
/usr/local/lib/perl5/site_perl/archname
/usr/local/lib/perl5/site_perl
directory structure is simplified. For example, if you Configure
with -Dprefix=/opt/perl, then the defaults are
- /opt/perl/lib/archname/5.002
+ /opt/perl/lib/archname/5.004
/opt/perl/lib
/opt/perl/lib/site_perl/archname
/opt/perl/lib/site_perl
will automatically look in these directories. Previously, most sites
just put their local extensions in with the standard distribution.
-In order to support using things like #!/usr/local/bin/perl5.002 after
+In order to support using things like #!/usr/local/bin/perl5.004 after
a later version is released, architecture-dependent libraries are
stored in a version-specific directory, such as
-/usr/local/lib/perl5/archname/5.002/. In 5.000 and 5.001, these files
-were just stored in /usr/local/lib/perl5/archname/. If you will not be
-using 5.001 binaries, you can delete the standard extensions from the
-/usr/local/lib/perl5/archname/ directory. Locally-added extensions can
-be moved to the site_perl and site_perl/archname directories.
+/usr/local/lib/perl5/archname/5.004/. In Perl 5.000 and 5.001, these
+files were just stored in /usr/local/lib/perl5/archname/. If you will
+not be using 5.001 binaries, you can delete the standard extensions from
+the /usr/local/lib/perl5/archname/ directory. Locally-added extensions
+can be moved to the site_perl and site_perl/archname directories.
Again, these are just the defaults, and can be changed as you run
Configure.
+=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 "disipline" 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, and work is in progress to make
+it more easily buildable by adding Configure support.
+
+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.
+
+=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 Changing the installation directory
Configure distinguishes between the directory in which perl (and its
make test
make install
-=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
- 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 Building a shared libperl.so Perl library.
Currently, for most systems, the main perl executable is built by
results.
The default name for the shared library is typically something like
-libperl.so.3.2 (for perl5.003_02) or libperl.so.302 or simply
+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
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 perl5.004 with a shared library. Then, suppose you
-try to build perl5.004 with -DDEBUGGING enabled, but everything else
+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. On
-Solaris, you can override that with LD_LIBRARY_PATH; on Linux you
-can't.
+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.
The only reliable answer is that you should specify a different
directory for the architecture-dependent library for your -DDEBUGGING
variables in config.sh, namely archlib, archlib_exp, and
installarchlib, to point to your new architecture-dependent library.
-=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 "disipline" 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, and work is in progress to make
-it more easily buildable by adding Configure support.
-
-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.
-
-=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 currently does not).
-
-You select this option via :
-
- sh Configure -Duseperlio -Uusesfio
+=head2 Creating an installable tar archive
-If you have already selected -Duseperlio, and if Configure does not
-detect sfio, then this will be the default suggested by Configure.
+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:
-=back
+ # 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
+ 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 What if it doesn't work?
=item Propagating your changes to config.sh
-If you later make any changes to F<config.sh>, you should propagate
+If you make any changes to F<config.sh>, you should propagate
them to all the .SH files by running B<sh Configure -S>. You will
then have to rebuild by running
subdirectory.
Ports for other systems may also be available. You should check out
-L<"http:/www.perl.com/CPAN/ports"> for current information on ports to
+L<"http://www.perl.com/CPAN/ports"> for current information on ports to
various other operating systems.
=back
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.
+
=item *
If you get duplicates upon linking for malloc et al, say -DHIDEMYMALLOC.
=item *
-If you can't compile successfully, try adding a C<-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.
+If you still can't compile successfully, try adding a C<-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
Machines with half-implemented dbm routines will need to #undef I_ODBM
+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.
=back
may be broken due to the combination of your environment and the way
C<make test> exercises them. For example, this may happen if you have
one or more of these environment variables set: C<LC_ALL LC_CTYPE
-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 C<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 C<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:
-C<exec, `backquoted command`, system, open("|...")> or C<open("...|")>.
-All these mean that Perl is trying to run some external program.
-
-=head1 INSTALLING PERL5
+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
+C<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 C<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: C<exec, `backquoted command`, system, open("|...")> or
+C<open("...|")>. All these mean that Perl is trying to run some
+external program.
=head1 make install
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 even if the Perl source is no longer available.
-
-The libperl.a library is only needed for building new
-extensions and linking them statically into a new perl executable.
-If you will not be doing that, then you may safely delete
-$archlib/libperl.a after perl is installed.
-
-make install may also offer to install perl in a "standard" location.
+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.
Most of the documentation in the pod/ directory is also available
in HTML and LaTeX format. Type
=head1 Coexistence with earlier versions of perl5.
You can safely install the current version of perl5 and still run scripts
-under the old binaries for versions 5.002 and later ONLY. Instead of
+under the old binaries for versions 5.003 and later ONLY. Instead of
starting your script with #!/usr/local/bin/perl, just start it with
-#!/usr/local/bin/perl5.001 (or whatever version you want to run.)
-If you want to retain a version of perl5 prior to perl5.002, you'll
+#!/usr/local/bin/perl5.003 (or whatever version you want to run.)
+If you want to retain a version of Perl 5 prior to 5.003, you'll
need to install the current version in a separate directory tree,
since some of the architecture-independent library files have changed
in incompatible ways.
The architecture-dependent files are stored in a version-specific
-directory (such as F</usr/local/lib/perl5/sun4-sunos/5.002>) so that
-they are still accessible. I<Note:> perl5.000 and perl5.001 did not
+directory (such as F</usr/local/lib/perl5/sun4-sunos/5.004>) so that
+they are still accessible. I<Note:> Perl 5.000 and 5.001 did not
put their architecture-dependent libraries in a version-specific
directory. They are simply in F</usr/local/lib/perl5/$archname>. If
you will not be using 5.000 or 5.001, you may safely remove those
version of perl. If you do run into problems, and you want to continue
to use the old version of perl along with your extension, simply move
those extension files to the appropriate version directory, such as
-F</usr/local/lib/perl/archname/5.002>. Then perl5.002 will find your
-files in the 5.002 directory, and newer versions of perl will find your
+F</usr/local/lib/perl/archname/5.004>. Then Perl 5.004 will find your
+files in the 5.004 directory, and newer versions of perl will find your
newer extension in the site_perl directory.
Some users may 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.002
+ sh Configure -Dprefix=/opt/perl5.004
-and adding /opt/perl5.002/bin to the shell PATH variable. Such users
+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.
-B<NOTE>: Starting with 5.002_01, all functions in the perl C source
-code are protected by default by the prefix Perl_ (or perl_) so that
-you may link with third-party libraries without fear of namespace
-collisons. This breaks compatability with the initially released
-version of 5.002, so once you install 5.002_01 (or higher) you will
-need 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. This is a one-time
-change. In the future, we certainly hope that most extensions won't
-need to be recompiled for use with a newer version of perl.
-
=head1 Coexistence with perl4
You can safely install perl5 even if you want to keep perl4 around.
can type B<perldoc perl> to use the supplied B<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 I<Table of Contents> by going to the pod/ subdirectory
+and running (either):
+
+ ./roffitall -groff # If you have GNU groff installed
+ ./roffitall -psroff # Otherwise
+
+This will leave you with two postscript files ready to be printed.
+
+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
Andy Dougherty <doughera@lafcol.lafayette.edu>, borrowing I<very> heavily
=head1 LAST MODIFIED
-6 September 1996
-
-> > Warning (will try anyway): No library found for -lucb
-> Don't worry about these. It tried anyway and succeeded. If you can think
-> of a better way to word the message, please feel free to suggest one.
-
-I figured that Configure should be able to figure out that there are no
--lucb/-lposix/-lcposix libraries so that ExtUtils::Liblist won't have
-to check for them. Okay, I'll stop worrying. :)
-
-Thank you!
-Dan
+8 February 1997
https://perl5.git.perl.org / perl5.git / blobdiff