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.
+provide additional or different instructions for building Perl. There
+are also README files for several flavors of Unix systems, such as
+Solaris, HP-UX, and AIX; if you have one of those systems, you should
+also read the README file specific to that system.
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
=head1 Space Requirements
-The complete perl5 source tree takes up about 35 MB of disk space.
-After completing make, it takes up roughly 50 MB, though the actual
+The complete perl5 source tree takes up about 40 MB of disk space.
+After completing make, it takes up roughly 60 MB, though the actual
total is likely to be quite system-dependent. The installation
-directories need something on the order of 30 MB, though again that
+directories need something on the order of 35 MB, though again that
value is system-dependent.
=head1 Start with a Fresh Distribution
=head2 Extensions
+Perl ships with a number of standard extensions. These are contained
+in the ext/ subdirectory.
+
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.
+the Configure command line.
If you unpack any additional extensions in the ext/ directory before
running Configure, then Configure will offer to build those additional
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:
+to turn off various extensions. All others are included by default.
- B (Always included by default)
DB_File i_db
DynaLoader (Must always be included as a static extension)
- Fcntl (Always included by default)
GDBM_File i_gdbm
- IO (Always included by default)
NDBM_File i_ndbm
ODBM_File i_dbm
POSIX useposix
- SDBM_File (Always included by default)
Opcode useopcode
Socket d_socket
Threads use5005threads
- attrs (Always included by default)
Thus to skip the NDBM_File extension, you can use
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)
+Finally, if you have dynamic loading (most modern 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.
make depend
make
-=item config.over
+=item config.over and config.arch
+
+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.
+This file is usually good for site-specific customizations.
-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.
+There is also another file that, if it exists, is loaded before the
+config.over, called config.arch. This file is intended to be per
+architecture, not per site, and usually it's the architecture-specific
+hints file that creates the config.arch.
=item config.h
subdirectory. Especially Porting/Glossary should come in handy.
Ports for other systems may also be available. You should check out
-http://www.perl.com/CPAN/ports for current information on ports to
+http://www.cpan.org/ports for current information on ports to
various other operating systems.
If you plan to port Perl to a new architecture study carefully the
=back
+=head1 Adding extra modules to the build
+
+You can specify extra modules or module bundles to be fetched from the
+CPAN and installed as part of the Perl build. Either use the -Dextras=...
+command line parameter to Configure, for example like this:
+
+ Configure -Dextras="Compress::Zlib Bundle::LWP DBI"
+
+or answer first 'y' to the question 'Install any extra modules?' and
+then answer "Compress::Zlib Bundle::LWP DBI" to the 'Extras?' question.
+The module or the bundle names are as for the CPAN module 'install' command.
+
+Notice that because the CPAN module will be used to fetch the extra
+modules, you will need access to the CPAN, either via the Internet,
+or via a local copy such as a CD-ROM or a local CPAN mirror. If you
+do not, using the extra modules option will die horribly.
+
+Also notice that you yourself are responsible for satisfying any extra
+dependencies such as external headers or libraries BEFORE trying the build.
+For example: you will need to have the zlib.h header and the libz
+library installed for the Compress::Zlib, or the Foo database specific
+headers and libraries installed for the DBD::Foo module. The Configure
+process or the Perl build process will not help you with these.
+
+=head1 suidperl
+
+suidperl is an optional component, which is built or installed by default.
+From perlfaq1:
+
+ On some systems, setuid and setgid scripts (scripts written
+ in the C shell, Bourne shell, or Perl, for example, with the
+ set user or group ID permissions enabled) are insecure due to
+ a race condition in the kernel. For those systems, Perl versions
+ 5 and 4 attempt to work around this vulnerability with an optional
+ component, a special program named suidperl, also known as sperl.
+ This program attempts to emulate the set-user-ID and set-group-ID
+ features of the kernel.
+
+Because of the buggy history of suidperl, and the difficulty
+of properly security auditing as large and complex piece of
+software as Perl, we cannot recommend using suidperl and the feature
+should be considered deprecated.
+Instead use for example 'sudo': http://www.courtesan.com/sudo/
+
=head1 make depend
This will look for all the includes. The output is stored in makefile.
=back
+=head2 Cross-compilation
+
+Starting from Perl 5.8 Perl has the beginnings of cross-compilation
+support. What is known to work is running Configure in a
+cross-compilation environment and building the miniperl executable.
+What is known not to work is building the perl executable because
+that would require building extensions: Dynaloader statically and
+File::Glob dynamically, for extensions one needs MakeMaker and
+MakeMaker is not yet cross-compilation aware, and neither is
+the main Makefile.
+
+Since the functionality is so lacking, it must be considered
+highly experimental. It is so experimental that it is not even
+mentioned during an interactive Configure session, a direct command
+line invocation (detailed shortly) is required to access the
+functionality.
+
+ NOTE: Perl is routinely built using cross-compilation
+ in the EPOC environment but the solutions from there
+ can't directly be used elsewhere.
+
+The one environment where cross-compilation has successfully been used
+as of this writing is the Compaq iPAQ running ARM Linux. The build
+host was Intel Linux, the networking setup was PPP + SSH. The exact
+setup details are beyond the scope of this document, see
+http://www.handhelds.org/ for more information.
+
+To run Configure in cross-compilation mode the basic switch is
+C<-Dusecrosscompile>.
+
+ sh ./Configure -des -Dusecrosscompile -D...
+
+This will make the cpp symbol USE_CROSS_COMPILE and the %Config
+symbol C<usecrosscompile> available.
+
+During the Configure and build, certain helper scripts will be created
+into the Cross/ subdirectory. The scripts are used to execute a
+cross-compiled executable, and to transfer files to and from the
+target host. The execution scripts are named F<run-*> and the
+transfer scripts F<to-*> and F<from-*>. The part after the dash is
+the method to use for remote execution and transfer: by default the
+methods are B<ssh> and B<scp>, thus making the scripts F<run-ssh>,
+F<to-scp>, and F<from-scp>.
+
+To configure the scripts for a target host and a directory (in which
+the execution will happen and which is to and from where the transfer
+happens), supply Configure with
+
+ -Dtargethost=so.me.ho.st -Dtargetdir=/tar/get/dir
+
+The targethost is what e.g. ssh will use as the hostname, the targetdir
+must exist (the scripts won't create it), the targetdir defaults to /tmp.
+You can also specify a username to use for ssh/rsh logins
+
+ -Dtargetuser=luser
+
+but in case you don't, "root" will be used.
+
+Because this is a cross-compilation effort, you will also need to specify
+which target environment and which compilation environment to use.
+This includes the compiler, the header files, and the libraries.
+In the below we use the usual settings for the iPAQ cross-compilation
+environment:
+
+ -Dtargetarch=arm-linux
+ -Dcc=arm-linux-gcc
+ -Dusrinc=/skiff/local/arm-linux/include
+ -Dincpth=/skiff/local/arm-linux/include
+ -Dlibpth=/skiff/local/arm-linux/lib
+
+If the name of the C<cc> has the usual GNU C semantics for cross
+compilers, that is, CPU-OS-gcc, the names of the C<ar>, C<nm>, and
+C<ranlib> will also be automatically chosen to be CPU-OS-ar and so on.
+(The C<ld> requires more thought and will be chosen later by Configure
+as appropriate.) Also, in this case the incpth, libpth, and usrinc
+will be guessed by Configure (unless explicitly set to something else,
+in which case Configure's guesses with be appended).
+
+In addition to the default execution/transfer methods you can also
+choose B<rsh> for execution, and B<rcp> or B<cp> for transfer,
+for example:
+
+ -Dtargetrun=rsh -Dtargetto=rcp -Dtargetfrom=cp
+
+Putting it all together:
+
+ sh ./Configure -des -Dusecrosscompile \
+ -Dtargethost=so.me.ho.st \
+ -Dtargetdir=/tar/get/dir \
+ -Dtargetuser=root \
+ -Dtargetarch=arm-linux \
+ -Dcc=arm-linux-gcc \
+ -Dusrinc=/skiff/local/arm-linux/include \
+ -Dincpth=/skiff/local/arm-linux/include \
+ -Dlibpth=/skiff/local/arm-linux/lib \
+ -D...
+
+or if you are happy with the defaults
+
+ sh ./Configure -des -Dusecrosscompile \
+ -Dtargethost=so.me.ho.st \
+ -Dcc=arm-linux-gcc \
+ -D...
+
=head1 make test
This will run the regression tests on the perl you just made. If
(cd pod && make tex && <process the latex files>)
+=head1 Minimizing the Perl installation
+
+The following section is meant for people worrying about squeezing the
+Perl installation into minimal systems (for example when installing
+operating systems, or in really small filesystems).
+
+In the following we offer two different slimmed down installation
+recipes. They are informative, not normative: the choice of files
+depends on what you need.
+
+Firstly, the bare minimum to run this script
+
+ use strict;
+ use warnings;
+ foreach my $f (</*>) {
+ print("$f\n");
+ }
+
+in Solaris is as follows (under $Config{prefix}):
+
+ ./bin/perl
+ ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/autosplit.ix
+ ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_expandspec.al
+ ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_find_symbol_anywhere.al
+ ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_findfile.al
+ ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/Glob.so
+ ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/autosplit.ix
+ ./lib/perl5/5.6.1/sun4-solaris-64int/Config.pm
+ ./lib/perl5/5.6.1/sun4-solaris-64int/XSLoader.pm
+ ./lib/perl5/5.6.1/sun4-solaris-64int/DynaLoader.pm
+ ./lib/perl5/5.6.1/sun4-solaris-64int/CORE/libperl.so
+ ./lib/perl5/5.6.1/strict.pm
+ ./lib/perl5/5.6.1/warnings.pm
+ ./lib/perl5/5.6.1/Carp.pm
+ ./lib/perl5/5.6.1/Exporter.pm
+ ./lib/perl5/5.6.1/File/Glob.pm
+ ./lib/perl5/5.6.1/AutoLoader.pm
+ ./lib/perl5/5.6.1/vars.pm
+ ./lib/perl5/5.6.1/warnings/register.pm
+ ./lib/perl5/5.6.1/Carp/Heavy.pm
+ ./lib/perl5/5.6.1/Exporter/Heavy.pm
+
+Secondly, Debian perl-base package contains the following files,
+size about 1.2MB in its i386 version:
+
+ /usr/share/doc/perl/Documentation
+ /usr/share/doc/perl/README.Debian
+ /usr/share/doc/perl/copyright
+ /usr/share/doc/perl/AUTHORS.gz
+ /usr/share/doc/perl/changelog.Debian.gz
+ /usr/share/man/man1/perl.1.gz
+ /usr/share/perl/5.6.1/AutoLoader.pm
+ /usr/share/perl/5.6.1/Carp.pm
+ /usr/share/perl/5.6.1/Carp/Heavy.pm
+ /usr/share/perl/5.6.1/Cwd.pm
+ /usr/share/perl/5.6.1/Exporter.pm
+ /usr/share/perl/5.6.1/Exporter/Heavy.pm
+ /usr/share/perl/5.6.1/File/Spec.pm
+ /usr/share/perl/5.6.1/File/Spec/Unix.pm
+ /usr/share/perl/5.6.1/FileHandle.pm
+ /usr/share/perl/5.6.1/Getopt/Long.pm
+ /usr/share/perl/5.6.1/IO/Socket/INET.pm
+ /usr/share/perl/5.6.1/IO/Socket/UNIX.pm
+ /usr/share/perl/5.6.1/IPC/Open2.pm
+ /usr/share/perl/5.6.1/IPC/Open3.pm
+ /usr/share/perl/5.6.1/SelectSaver.pm
+ /usr/share/perl/5.6.1/Symbol.pm
+ /usr/share/perl/5.6.1/Text/Tabs.pm
+ /usr/share/perl/5.6.1/Text/Wrap.pm
+ /usr/share/perl/5.6.1/attributes.pm
+ /usr/share/perl/5.6.1/auto/Getopt/Long/GetOptions.al
+ /usr/share/perl/5.6.1/auto/Getopt/Long/FindOption.al
+ /usr/share/perl/5.6.1/auto/Getopt/Long/Configure.al
+ /usr/share/perl/5.6.1/auto/Getopt/Long/config.al
+ /usr/share/perl/5.6.1/auto/Getopt/Long/Croak.al
+ /usr/share/perl/5.6.1/auto/Getopt/Long/autosplit.ix
+ /usr/share/perl/5.6.1/base.pm
+ /usr/share/perl/5.6.1/constant.pm
+ /usr/share/perl/5.6.1/fields.pm
+ /usr/share/perl/5.6.1/integer.pm
+ /usr/share/perl/5.6.1/lib.pm
+ /usr/share/perl/5.6.1/locale.pm
+ /usr/share/perl/5.6.1/overload.pm
+ /usr/share/perl/5.6.1/strict.pm
+ /usr/share/perl/5.6.1/vars.pm
+ /usr/share/perl/5.6.1/warnings.pm
+ /usr/share/perl/5.6.1/warnings/register.pm
+ /usr/bin/perl
+ /usr/lib/perl/5.6.1/Config.pm
+ /usr/lib/perl/5.6.1/Data/Dumper.pm
+ /usr/lib/perl/5.6.1/DynaLoader.pm
+ /usr/lib/perl/5.6.1/Errno.pm
+ /usr/lib/perl/5.6.1/Fcntl.pm
+ /usr/lib/perl/5.6.1/File/Glob.pm
+ /usr/lib/perl/5.6.1/IO.pm
+ /usr/lib/perl/5.6.1/IO/File.pm
+ /usr/lib/perl/5.6.1/IO/Handle.pm
+ /usr/lib/perl/5.6.1/IO/Pipe.pm
+ /usr/lib/perl/5.6.1/IO/Seekable.pm
+ /usr/lib/perl/5.6.1/IO/Select.pm
+ /usr/lib/perl/5.6.1/IO/Socket.pm
+ /usr/lib/perl/5.6.1/POSIX.pm
+ /usr/lib/perl/5.6.1/Socket.pm
+ /usr/lib/perl/5.6.1/XSLoader.pm
+ /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.so
+ /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.bs
+ /usr/lib/perl/5.6.1/auto/DynaLoader/dl_findfile.al
+ /usr/lib/perl/5.6.1/auto/DynaLoader/dl_expandspec.al
+ /usr/lib/perl/5.6.1/auto/DynaLoader/dl_find_symbol_anywhere.al
+ /usr/lib/perl/5.6.1/auto/DynaLoader/autosplit.ix
+ /usr/lib/perl/5.6.1/auto/DynaLoader/DynaLoader.a
+ /usr/lib/perl/5.6.1/auto/DynaLoader/extralibs.ld
+ /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.so
+ /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.bs
+ /usr/lib/perl/5.6.1/auto/File/Glob/Glob.bs
+ /usr/lib/perl/5.6.1/auto/File/Glob/Glob.so
+ /usr/lib/perl/5.6.1/auto/File/Glob/autosplit.ix
+ /usr/lib/perl/5.6.1/auto/IO/IO.so
+ /usr/lib/perl/5.6.1/auto/IO/IO.bs
+ /usr/lib/perl/5.6.1/auto/POSIX/POSIX.bs
+ /usr/lib/perl/5.6.1/auto/POSIX/POSIX.so
+ /usr/lib/perl/5.6.1/auto/POSIX/autosplit.ix
+ /usr/lib/perl/5.6.1/auto/POSIX/load_imports.al
+ /usr/lib/perl/5.6.1/auto/Socket/Socket.so
+ /usr/lib/perl/5.6.1/auto/Socket/Socket.bs
+
=head1 Reporting Problems
If you have difficulty building perl, and none of the advice in this file
If you are distributing a modified version of perl (perhaps as part of
a larger package) please B<do> modify these installation instructions
and the contact information to match your distribution.
-
-=head1 LAST MODIFIED
-
-$Id: INSTALL,v 1.58 1999/07/23 14:43:00 doughera Exp $