This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: OK: 5.8.1 RC5 on SuSE 8.2 32bit AMD (gcc 3.3 prerelease)
[perl5.git] / INSTALL
CommitLineData
8e07c86e
AD
1=head1 NAME
2
3Install - Build and Installation guide for perl5.
4
5=head1 SYNOPSIS
6
3ce0d271
GS
7First, make sure you are installing an up-to-date version of Perl. If
8you didn't get your Perl source from CPAN, check the latest version at
16dc217a 9<URL:http://www.cpan.org/src/>.
3ce0d271 10
c42e3e15
GS
11The basic steps to build and install perl5 on a Unix system
12with all the defaults are:
8e07c86e 13
dc45a647 14 rm -f config.sh Policy.sh
491517e0 15 sh Configure -de
8e07c86e
AD
16 make
17 make test
18 make install
36477c24 19
aa689395
PP
20 # You may also wish to add these:
21 (cd /usr/include && h2ph *.h sys/*.h)
3e3baf6d 22 (installhtml --help)
aa689395 23 (cd pod && make tex && <process the latex files>)
8e07c86e
AD
24
25Each of these is explained in further detail below.
26
cc65bb49 27B<NOTE>: starting from the release 5.6.0, Perl uses a version
fe23a901 28scheme where even-numbered subreleases (like 5.6 and 5.8) are stable
b88cc0eb
JH
29maintenance releases and odd-numbered subreleases (like 5.7) are
30unstable development releases. Development releases should not be
31used in production environments. Fixes and new features are first
32carefully tested in development releases and only if they prove
33themselves to be worthy will they be migrated to the maintenance
34releases.
35
cc65bb49
AD
36The above commands will install Perl to /usr/local (or some other
37platform-specific directory -- see the appropriate file in hints/.)
38If that's not okay with you, use
491517e0
JA
39
40 rm -f config.sh Policy.sh
41 sh Configure
42 make
43 make test
44 make install
45
adbebc0b
JH
46For information on non-Unix systems, see the section on L<"Porting
47information"> below.
48
49If "make install" just says "`install' is up to date" or something
cc65bb49
AD
50similar, you may be on a case-insensitive filesystems such as Mac's HFS+,
51and you should say "make install-all". (This confusion is brought to you
adbebc0b 52by the Perl distribution having a file called INSTALL.)
7f678428 53
8d74ce1c
AD
54If you have problems, corrections, or questions, please see
55L<"Reporting Problems"> below.
56
7beaa944
AD
57For information on what's new in this release, see the
58pod/perldelta.pod file. For more detailed information about specific
59changes, see the Changes file.
c3edaffb 60
1ec51d55 61=head1 DESCRIPTION
edb1cbcb 62
c3edaffb
PP
63This document is written in pod format as an easy way to indicate its
64structure. The pod format is described in pod/perlpod.pod, but you can
1ec51d55
CS
65read it as is with any pager or editor. Headings and items are marked
66by lines beginning with '='. The other mark-up used is
67
68 B<text> embolden text, used for switches, programs or commands
69 C<code> literal code
70 L<name> A link (cross reference) to name
71
c42e3e15
GS
72Although most of the defaults are probably fine for most users,
73you should probably at least skim through this entire document before
1ec51d55 74proceeding.
c3edaffb 75
eed2e782
PP
76If you're building Perl on a non-Unix system, you should also read
77the README file specific to your operating system, since this may
c35d5681
PN
78provide additional or different instructions for building Perl. There
79are also README files for several flavors of Unix systems, such as
80Solaris, HP-UX, and AIX; if you have one of those systems, you should
81also read the README file specific to that system.
eed2e782 82
203c3eec
AD
83If there is a hint file for your system (in the hints/ directory) you
84should also read that hint file for specific information for your
2ab493b8 85system. (Unixware users should use the svr4.sh or the svr5.sh hint file.)
cc65bb49 86Additional information is in the Porting/ directory.
203c3eec 87
c42e3e15
GS
88=head1 WARNING: This version requires an extra step to build old extensions.
89
905.005_53 and later releases do not export unadorned
64fa5b0b
DM
91global symbols anymore. This means you may need to build rather old
92extensions that have not been updated for the current naming convention
c42e3e15
GS
93with:
94
95 perl Makefile.PL POLLUTE=1
d56c5707 96
c42e3e15
GS
97Alternatively, you can enable CPP symbol pollution wholesale by
98building perl itself with:
99
100 sh Configure -Accflags=-DPERL_POLLUTE
101
5cda700b 102pod/perl56delta.pod contains more details about this.
c42e3e15 103
64fa5b0b
DM
104=head1 WARNING: This version is not binary compatible with releases of
105Perl prior to 5.8.0.
1b1c1ae2 106
cc65bb49 107If you have built extensions (i.e. modules that include C code)
64fa5b0b
DM
108using an earlier version of Perl, you will need to rebuild and reinstall
109those extensions.
1b1c1ae2
GS
110
111Pure perl modules without XS or C code should continue to work fine
112without reinstallation. See the discussions below on
113L<"Coexistence with earlier versions of perl5"> and
fe23a901 114L<"Upgrading from 5.005 or 5.6 to 5.8.0"> for more details.
693762b4
AD
115
116The standard extensions supplied with Perl will be handled automatically.
117
1b1c1ae2 118On a related issue, old modules may possibly be affected by the
693762b4 119changes in the Perl language in the current release. Please see
5cda700b 120pod/perldelta.pod (and the earlier pod/perl5Xdelta.pod) for a description of
c42e3e15 121what's changed. See your installed copy of the perllocal.pod
d6baa268
JH
122file for a (possibly incomplete) list of locally installed modules.
123Also see CPAN::autobundle for one way to make a "bundle" of your
124currently installed modules.
693762b4 125
5effff0b
GS
126=head1 WARNING: This version requires a compiler that supports ANSI C.
127
16dc217a
GS
128Most C compilers are now ANSI-compliant. However, a few current
129computers are delivered with an older C compiler expressly for
130rebuilding the system kernel, or for some other historical reason.
131Alternatively, you may have an old machine which was shipped before
132ANSI compliance became widespread. Such compilers are not suitable
133for building Perl.
134
135If you find that your default C compiler is not ANSI-capable, but you
136know that an ANSI-capable compiler is installed on your system, you
137can tell F<Configure> to use the correct compiler by means of the
138C<-Dcc=> command-line option -- see L<"gcc">.
139
cc65bb49
AD
140If do not have an ANSI-capable compiler there are a couple of avenues
141open to you:
16dc217a
GS
142
143=over 4
144
145=item *
146
147You may try obtaining GCC, available from GNU mirrors worldwide,
148listed at <URL:http://www.gnu.org/order/ftp.html>. If, rather than
149building gcc from source code, you locate a binary version configured
150for your platform, be sure that it is compiled for the version of the
151operating system that you are using.
152
153=item *
154
155You may purchase a commercial ANSI C compiler from your system
156supplier or elsewhere. (Or your organization may already have
157licensed such software -- ask your colleagues to find out how to
158access it.) If there is a README file for your system in the Perl
159distribution (for example, F<README.hpux>), it may contain advice on
160suitable compilers.
161
16dc217a
GS
162=back
163
df41b452
GS
164Although Perl can be compiled using a C++ compiler, the Configure script
165does not work with some C++ compilers.
166
aa689395 167=head1 Space Requirements
eed2e782 168
8756f06c
JH
169The complete perl5 source tree takes up about 50 MB of disk space.
170After completing make, it takes up roughly 100 MB, though the actual
d6baa268 171total is likely to be quite system-dependent. The installation
8756f06c 172directories need something on the order of 45 MB, though again that
1ec51d55 173value is system-dependent.
8e07c86e 174
aa689395 175=head1 Start with a Fresh Distribution
8e07c86e 176
edb1cbcb
PP
177If you have built perl before, you should clean out the build directory
178with the command
179
dc45a647
MB
180 make distclean
181
182or
183
edb1cbcb 184 make realclean
c3edaffb 185
dc45a647
MB
186The only difference between the two is that make distclean also removes
187your old config.sh and Policy.sh files.
188
189The results of a Configure run are stored in the config.sh and Policy.sh
190files. If you are upgrading from a previous version of perl, or if you
191change systems or compilers or make other significant changes, or if
192you are experiencing difficulties building perl, you should probably
d6baa268 193not re-use your old config.sh. Simply remove it
8e07c86e 194
d6baa268 195 rm -f config.sh
4633a7c4 196
e57fd563
PP
197If you wish to use your old config.sh, be especially attentive to the
198version and architecture-specific questions and answers. For example,
199the default directory for architecture-dependent library modules
200includes the version name. By default, Configure will reuse your old
201name (e.g. /opt/perl/lib/i86pc-solaris/5.003) even if you're running
202Configure for a different version, e.g. 5.004. Yes, Configure should
5cda700b 203probably check and correct for this, but it doesn't.
e57fd563
PP
204Similarly, if you used a shared libperl.so (see below) with version
205numbers, you will probably want to adjust them as well.
206
d6baa268
JH
207Also, be careful to check your architecture name. For example, some
208Linux distributions use i386, while others may use i486. If you build
209it yourself, Configure uses the output of the arch command, which
210might be i586 or i686 instead. If you pick up a precompiled binary, or
211compile extensions on different systems, they might not all agree on
212the architecture name.
e57fd563
PP
213
214In short, if you wish to use your old config.sh, I recommend running
215Configure interactively rather than blindly accepting the defaults.
8e07c86e 216
d6baa268
JH
217If your reason to reuse your old config.sh is to save your particular
218installation choices, then you can probably achieve the same effect by
219using the Policy.sh file. See the section on L<"Site-wide Policy
220settings"> below. If you wish to start with a fresh distribution, you
221also need to remove any old Policy.sh files you may have with
222
223 rm -f Policy.sh
dc45a647 224
aa689395 225=head1 Run Configure
8e07c86e
AD
226
227Configure will figure out various things about your system. Some
228things Configure will figure out for itself, other things it will ask
d6baa268
JH
229you about. To accept the default, just press RETURN. The default is
230almost always okay. It is normal for some things to be "NOT found",
231since Configure often searches for many different ways of performing
232the same function.
233
234At any Configure prompt, you can type &-d and Configure will use the
235defaults from then on.
8e07c86e
AD
236
237After it runs, Configure will perform variable substitution on all the
1ec51d55 238*.SH files and offer to run make depend.
8e07c86e 239
1b1c1ae2
GS
240=head2 Altering config.sh variables for C compiler switches etc.
241
242For most users, all of the Configure defaults are fine. Configure
cc65bb49 243also has several convenient options which are described below.
1b1c1ae2
GS
244However, if Configure doesn't have an option to do what you want,
245you can change Configure variables after the platform hints have been
246run, by using Configure's -A switch. For example, here's how to add
247a couple of extra flags to C compiler invocations:
248
249 sh Configure -Accflags="-DPERL_Y2KWARN -DPERL_POLLUTE_MALLOC"
250
251For more help on Configure switches, run:
252
253 sh Configure -h
254
844fc9f4
JH
255=head2 Building Perl outside of the source directory
256
257Sometimes it is desirable to build Perl in a directory different from
258where the sources are, for example if you want to keep your sources
259read-only, or if you want to share the sources between different binary
cc65bb49
AD
260architectures. You can do this (if your file system supports symbolic
261links) by
5cda700b 262
844fc9f4
JH
263 mkdir /tmp/perl/build/directory
264 cd /tmp/perl/build/directory
265 sh /path/to/perl/source/Configure -Dmksymlinks ...
266
267This will create in /tmp/perl/build/directory a tree of symbolic links
268pointing to files in /path/to/perl/source. The original files are left
269unaffected. After Configure has finished you can just say
270
271 make all test
272
273and Perl will be built and tested, all in /tmp/perl/build/directory.
274
d6baa268
JH
275=head2 Common Configure options
276
fb73857a
PP
277Configure supports a number of useful options. Run B<Configure -h> to
278get a listing. See the Porting/Glossary file for a complete list of
279Configure variables you can set and their definitions.
280
d6baa268
JH
281=over 4
282
283=item gcc
284
285To compile with gcc you should run
8e07c86e
AD
286
287 sh Configure -Dcc=gcc
288
289This is the preferred way to specify gcc (or another alternative
290compiler) so that the hints files can set appropriate defaults.
291
d6baa268 292=item Installation prefix
4633a7c4 293
8e07c86e 294By default, for most systems, perl will be installed in
8d74ce1c
AD
295/usr/local/{bin, lib, man}. (See L<"Installation Directories">
296and L<"Coexistence with earlier versions of perl5"> below for
297further details.)
298
299You can specify a different 'prefix' for the default installation
300directory, when Configure prompts you or by using the Configure command
301line option -Dprefix='/some/directory', e.g.
8e07c86e 302
25f94b33 303 sh Configure -Dprefix=/opt/perl
4633a7c4 304
d6baa268
JH
305If your prefix contains the string "perl", then the suggested
306directory structure is simplified. For example, if you use
307prefix=/opt/perl, then Configure will suggest /opt/perl/lib instead of
308/opt/perl/lib/perl5/. Again, see L<"Installation Directories"> below
bc70e9ec
JH
309for more details. Do not include a trailing slash, (i.e. /opt/perl/)
310or you may experience odd test failures.
8e07c86e 311
8d74ce1c
AD
312NOTE: You must not specify an installation directory that is the same
313as or below your perl source directory. If you do, installperl will
314attempt infinite recursion.
84902520 315
d6baa268
JH
316=item /usr/bin/perl
317
318It may seem obvious, but Perl is useful only when users can easily
319find it. It's often a good idea to have both /usr/bin/perl and
dd64f1c3 320/usr/local/bin/perl be symlinks to the actual binary. Be especially
d6baa268 321careful, however, not to overwrite a version of perl supplied by your
b66c6cec
AD
322vendor unless you are sure you know what you are doing. If you insist
323on replacing your vendor's perl, useful information on how it was
324configured may be found with
325
326 perl -V:config_args
327
328(Check the output carefully, however, since this doesn't preserve
329spaces in arguments to Configure. For that, you have to look
330carefully at config_arg1, config_arg2, etc.)
d6baa268 331
7d56c962
RGS
332By default, Configure will not try to link /usr/bin/perl to
333the current version of perl. You can turn on that behavior by running
d6baa268 334
7d56c962 335 Configure -Dinstallusrbinperl
d6baa268 336
7d56c962
RGS
337or by answering 'yes' to the appropriate Configure prompt.
338(Note that before perl 5.8.1, the default behavior was to create
339or overwrite /usr/bin/perl even if it already existed.)
d6baa268
JH
340
341In any case, system administrators are strongly encouraged to
dd64f1c3 342put (symlinks to) perl and its accompanying utilities, such as perldoc,
4682965a
MB
343into a directory typically found along a user's PATH, or in another
344obvious and convenient place.
345
d6baa268 346=item Overriding an old config.sh
04d420f9 347
d6baa268
JH
348If you want to use your old config.sh but override some of the items
349with command line options, you need to use B<Configure -O>.
350
351=back
8e07c86e 352
203c3eec
AD
353If you are willing to accept all the defaults, and you want terse
354output, you can run
355
356 sh Configure -des
357
cc65bb49 358Note: for development releases (odd subreleases, like 5.9, as opposed
fe23a901 359to maintenance releases which have even subreleases, like 5.6 and 5.8)
b88cc0eb
JH
360if you want to use Configure -d, you will also need to supply -Dusedevel
361to Configure, because the default answer to the question "do you really
362want to Configure a development version?" is "no". The -Dusedevel
363skips that sanity check.
364
365For example for my Solaris system, I usually use
203c3eec
AD
366
367 sh Configure -Dprefix=/opt/perl -Doptimize='-xpentium -xO4' -des
368
46bb10fb
CS
369=head2 GNU-style configure
370
1ec51d55 371If you prefer the GNU-style configure command line interface, you can
dc45a647 372use the supplied configure.gnu command, e.g.
46bb10fb 373
693762b4 374 CC=gcc ./configure.gnu
46bb10fb 375
dc45a647 376The configure.gnu script emulates a few of the more common configure
46bb10fb
CS
377options. Try
378
693762b4 379 ./configure.gnu --help
46bb10fb
CS
380
381for a listing.
382
dc45a647 383(The file is called configure.gnu to avoid problems on systems
693762b4 384that would not distinguish the files "Configure" and "configure".)
46bb10fb 385
cc65bb49
AD
386See L<Cross-compilation> below for information on cross-compiling.
387
aa689395 388=head2 Installation Directories
4633a7c4
LW
389
390The installation directories can all be changed by answering the
391appropriate questions in Configure. For convenience, all the
392installation questions are near the beginning of Configure.
cc65bb49 393Do not include trailing slashes on directory names.
4633a7c4 394
7beaa944
AD
395I highly recommend running Configure interactively to be sure it puts
396everything where you want it. At any point during the Configure
d6baa268 397process, you can answer a question with &-d and Configure will use
cc65bb49
AD
398the defaults from then on. Alternatively, you can
399
400 grep '^install' config.sh
401
402after Configure has run to verify the installation paths.
d6baa268
JH
403
404The defaults are intended to be reasonable and sensible for most
405people building from sources. Those who build and distribute binary
406distributions or who export perl to a range of systems will probably
407need to alter them. If you are content to just accept the defaults,
408you can safely skip the next section.
409
410The directories set up by Configure fall into three broad categories.
411
412=over 4
413
414=item Directories for the perl distribution
415
fe23a901 416By default, Configure will use the following directories for 5.8.0.
d6baa268 417$version is the full perl version number, including subversion, e.g.
fe23a901 4185.8.0 or 5.8.1, and $archname is a string like sun4-sunos,
d6baa268
JH
419determined by Configure. The full definitions of all Configure
420variables are in the file Porting/Glossary.
421
422 Configure variable Default value
423 $prefix /usr/local
424 $bin $prefix/bin
425 $scriptdir $prefix/bin
426 $privlib $prefix/lib/perl5/$version
427 $archlib $prefix/lib/perl5/$version/$archname
428 $man1dir $prefix/man/man1
429 $man3dir $prefix/man/man3
430 $html1dir (none)
431 $html3dir (none)
432
433Actually, Configure recognizes the SVR3-style
434/usr/local/man/l_man/man1 directories, if present, and uses those
435instead. Also, if $prefix contains the string "perl", the library
436directories are simplified as described below. For simplicity, only
437the common style is shown here.
438
439=item Directories for site-specific add-on files
440
441After perl is installed, you may later wish to add modules (e.g. from
442CPAN) or scripts. Configure will set up the following directories to
c42e3e15 443be used for installing those add-on modules and scripts.
d6baa268
JH
444
445 Configure variable Default value
446 $siteprefix $prefix
447 $sitebin $siteprefix/bin
49c10eea 448 $sitescript $siteprefix/bin
273cf8d1
GS
449 $sitelib $siteprefix/lib/perl5/site_perl/$version
450 $sitearch $siteprefix/lib/perl5/site_perl/$version/$archname
66e2fe92
JH
451 $siteman1dir $siteprefix/man/man1
452 $siteman3dir $siteprefix/man/man3
453 $sitehtml1dir (none)
454 $sitehtml3dir (none)
d6baa268
JH
455
456By default, ExtUtils::MakeMaker will install architecture-independent
273cf8d1 457modules into $sitelib and architecture-dependent modules into $sitearch.
d6baa268
JH
458
459=item Directories for vendor-supplied add-on files
460
461Lastly, if you are building a binary distribution of perl for
462distribution, Configure can optionally set up the following directories
463for you to use to distribute add-on modules.
464
465 Configure variable Default value
466 $vendorprefix (none)
467 (The next ones are set only if vendorprefix is set.)
468 $vendorbin $vendorprefix/bin
49c10eea 469 $vendorscript $vendorprefix/bin
273cf8d1
GS
470 $vendorlib $vendorprefix/lib/perl5/vendor_perl/$version
471 $vendorarch $vendorprefix/lib/perl5/vendor_perl/$version/$archname
66e2fe92
JH
472 $vendorman1dir $vendorprefix/man/man1
473 $vendorman3dir $vendorprefix/man/man3
474 $vendorhtml1dir (none)
475 $vendorhtml3dir (none)
d6baa268
JH
476
477These are normally empty, but may be set as needed. For example,
478a vendor might choose the following settings:
479
345c69e9
A
480 $prefix /usr
481 $siteprefix /usr/local
482 $vendorprefix /usr
d6baa268
JH
483
484This would have the effect of setting the following:
485
486 $bin /usr/bin
487 $scriptdir /usr/bin
488 $privlib /usr/lib/perl5/$version
489 $archlib /usr/lib/perl5/$version/$archname
490 $man1dir /usr/man/man1
491 $man3dir /usr/man/man3
492
493 $sitebin /usr/local/bin
49c10eea 494 $sitescript /usr/local/bin
273cf8d1
GS
495 $sitelib /usr/local/lib/perl5/site_perl/$version
496 $sitearch /usr/local/lib/perl5/site_perl/$version/$archname
66e2fe92
JH
497 $siteman1dir /usr/local/man/man1
498 $siteman3dir /usr/local/man/man3
d6baa268 499
49c10eea
JH
500 $vendorbin /usr/bin
501 $vendorscript /usr/bin
273cf8d1
GS
502 $vendorlib /usr/lib/perl5/vendor_perl/$version
503 $vendorarch /usr/lib/perl5/vendor_perl/$version/$archname
66e2fe92
JH
504 $vendorman1dir /usr/man/man1
505 $vendorman3dir /usr/man/man3
d6baa268
JH
506
507Note how in this example, the vendor-supplied directories are in the
508/usr hierarchy, while the directories reserved for the end-user are in
273cf8d1
GS
509the /usr/local hierarchy.
510
511The entire installed library hierarchy is installed in locations with
512version numbers, keeping the installations of different versions distinct.
513However, later installations of Perl can still be configured to search the
514installed libraries corresponding to compatible earlier versions.
515See L<"Coexistence with earlier versions of perl5"> below for more details
516on how Perl can be made to search older version directories.
d6baa268
JH
517
518Of course you may use these directories however you see fit. For
519example, you may wish to use $siteprefix for site-specific files that
520are stored locally on your own disk and use $vendorprefix for
521site-specific files that are stored elsewhere on your organization's
522network. One way to do that would be something like
523
524 sh Configure -Dsiteprefix=/usr/local -Dvendorprefix=/usr/share/perl
525
526=item otherlibdirs
527
528As a final catch-all, Configure also offers an $otherlibdirs
529variable. This variable contains a colon-separated list of additional
3b777bb4
GS
530directories to add to @INC. By default, it will be empty.
531Perl will search these directories (including architecture and
532version-specific subdirectories) for add-on modules and extensions.
d6baa268 533
fe23a901
RF
534For example, if you have a bundle of perl libraries from a previous
535installation, perhaps in a strange place:
536
537 Configure -Dotherlibdirs=/usr/lib/perl5/site_perl/5.6.1
538
a61357a9
JA
539=item APPLLIB_EXP
540
541There is one other way of adding paths to @INC at perl build time, and
542that is by setting the APPLLIB_EXP C pre-processor token to a colon-
543separated list of directories, like this
544
545 sh Configure -Accflags='-DAPPLLIB_EXP=\"/usr/libperl\"'
546
547The directories defined by APPLLIB_EXP get added to @INC I<first>,
548ahead of any others, and so provide a way to override the standard perl
549modules should you, for example, want to distribute fixes without
550touching the perl distribution proper. And, like otherlib dirs,
551version and architecture specific subdirectories are also searched, if
552present, at run time. Of course, you can still search other @INC
553directories ahead of those in APPLLIB_EXP by using any of the standard
554run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc.
555
d6baa268 556=item Man Pages
1ec51d55 557
d6baa268
JH
558In versions 5.005_57 and earlier, the default was to store module man
559pages in a version-specific directory, such as
560/usr/local/lib/perl5/$version/man/man3. The default for 5.005_58 and
561after is /usr/local/man/man3 so that most users can find the man pages
562without resetting MANPATH.
4633a7c4 563
d6baa268 564You can continue to use the old default from the command line with
4633a7c4 565
fe23a901 566 sh Configure -Dman3dir=/usr/local/lib/perl5/5.8.0/man/man3
8d74ce1c 567
d6baa268
JH
568Some users also prefer to use a .3pm suffix. You can do that with
569
570 sh Configure -Dman3ext=3pm
571
572Again, these are just the defaults, and can be changed as you run
573Configure.
574
575=item HTML pages
576
cc65bb49
AD
577Currently, the standard perl installation does not do anything with
578HTML documentation, but that may change in the future. Further, some
579add-on modules may wish to install HTML documents. The html Configure
580variables listed above are provided if you wish to specify where such
581documents should be placed. The default is "none", but will likely
582eventually change to something useful based on user feedback.
8d74ce1c 583
d6baa268 584=back
8d74ce1c 585
3a6175e1
AD
586Some users prefer to append a "/share" to $privlib and $sitelib
587to emphasize that those directories can be shared among different
588architectures.
4633a7c4 589
8d74ce1c
AD
590Note that these are just the defaults. You can actually structure the
591directories any way you like. They don't even have to be on the same
592filesystem.
593
594Further details about the installation directories, maintenance and
595development subversions, and about supporting multiple versions are
596discussed in L<"Coexistence with earlier versions of perl5"> below.
597
598If you specify a prefix that contains the string "perl", then the
d6baa268
JH
599library directory structure is slightly simplified. Instead of
600suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib.
8d74ce1c 601
d6baa268 602Thus, for example, if you Configure with
fe23a901 603-Dprefix=/opt/perl, then the default library directories for 5.8.0 are
3a6175e1 604
d6baa268 605 Configure variable Default value
fe23a901
RF
606 $privlib /opt/perl/lib/5.8.0
607 $archlib /opt/perl/lib/5.8.0/$archname
608 $sitelib /opt/perl/lib/site_perl/5.8.0
609 $sitearch /opt/perl/lib/site_perl/5.8.0/$archname
4633a7c4 610
aa689395
PP
611=head2 Changing the installation directory
612
613Configure distinguishes between the directory in which perl (and its
614associated files) should be installed and the directory in which it
615will eventually reside. For most sites, these two are the same; for
616sites that use AFS, this distinction is handled automatically.
1ec51d55 617However, sites that use software such as depot to manage software
d6baa268
JH
618packages, or users building binary packages for distribution may also
619wish to install perl into a different directory and use that
620management software to move perl to its final destination. This
621section describes how to do that.
aa689395 622
0dcb58f4 623Suppose you want to install perl under the /tmp/perl5 directory. You
d6baa268
JH
624could edit config.sh and change all the install* variables to point to
625/tmp/perl5 instead of /usr/local, or you could simply use the
626following command line:
627
628 sh Configure -Dinstallprefix=/tmp/perl5
629
630(replace /tmp/perl5 by a directory of your choice).
aa689395 631
693762b4 632Beware, though, that if you go to try to install new add-on
d6baa268 633modules, they too will get installed in under '/tmp/perl5' if you
693762b4
AD
634follow this example. The next section shows one way of dealing with
635that problem.
636
aa689395
PP
637=head2 Creating an installable tar archive
638
639If you need to install perl on many identical systems, it is
640convenient to compile it once and create an archive that can be
d6c1b5d3
AD
641installed on multiple systems. Suppose, for example, that you want to
642create an archive that can be installed in /opt/perl.
643Here's one way to do that:
aa689395 644
d6baa268 645 # Set up to install perl into a different directory,
aa689395 646 # e.g. /tmp/perl5 (see previous part).
d6baa268 647 sh Configure -Dinstallprefix=/tmp/perl5 -Dprefix=/opt/perl -des
aa689395
PP
648 make
649 make test
d6c1b5d3 650 make install # This will install everything into /tmp/perl5.
aa689395 651 cd /tmp/perl5
d6c1b5d3 652 # Edit $archlib/Config.pm and $archlib/.packlist to change all the
fb73857a 653 # install* variables back to reflect where everything will
d6c1b5d3
AD
654 # really be installed. (That is, change /tmp/perl5 to /opt/perl
655 # everywhere in those files.)
656 # Check the scripts in $scriptdir to make sure they have the correct
bfb7748a 657 # #!/wherever/perl line.
aa689395
PP
658 tar cvf ../perl5-archive.tar .
659 # Then, on each machine where you want to install perl,
d6c1b5d3 660 cd /opt/perl # Or wherever you specified as $prefix
aa689395
PP
661 tar xvf perl5-archive.tar
662
5c8863fa
JH
663Alternatively, the DESTDIR variable is honored during C<make install>.
664The DESTDIR is automatically prepended to all the installation paths
665(and there is no need to edit anything). With DESTDIR, the above
666example can we written as:
5a9231b0
MS
667
668 sh Configure -Dprefix=/opt/perl -des
669 make
670 make test
671 make install DESTDIR=/tmp/perl5
672 cd /tmp/perl5/opt/perl
673 tar cvf /tmp/perl5-archive.tar .
674
dc45a647 675=head2 Site-wide Policy settings
693762b4
AD
676
677After Configure runs, it stores a number of common site-wide "policy"
678answers (such as installation directories and the local perl contact
679person) in the Policy.sh file. If you want to build perl on another
680system using the same policy defaults, simply copy the Policy.sh file
681to the new system and Configure will use it along with the appropriate
682hint file for your system.
683
dc45a647
MB
684Alternatively, if you wish to change some or all of those policy
685answers, you should
686
687 rm -f Policy.sh
688
689to ensure that Configure doesn't re-use them.
690
691Further information is in the Policy_sh.SH file itself.
692
8d74ce1c
AD
693If the generated Policy.sh file is unsuitable, you may freely edit it
694to contain any valid shell commands. It will be run just after the
695platform-specific hints files.
696
aa689395
PP
697=head2 Configure-time Options
698
699There are several different ways to Configure and build perl for your
700system. For most users, the defaults are sensible and will work.
701Some users, however, may wish to further customize perl. Here are
702some of the main things you can change.
703
693762b4 704=head2 Threads
aa689395 705
cc65bb49
AD
706On some platforms, perl can be compiled with
707support for threads. To enable this, run
f7542a9d 708
693762b4 709 sh Configure -Dusethreads
aa689395 710
693762b4
AD
711Currently, you need to specify -Dusethreads on the Configure command
712line so that the hint files can make appropriate adjustments.
713
714The default is to compile without thread support.
3fe9a6f1 715
6d5328bc
JH
716Perl has two different internal threads implementations. The current
717model (available internally since 5.6, and as a user-level module
718since 5.8) is called interpreter-based implementation (ithreads),
719with one interpreter per thread, and explicit sharing of data.
aaacdc8b 720
6d5328bc
JH
721The 5.005 version (5005threads) is considered obsolete, buggy, and
722unmaintained.
723
724By default, Configure selects ithreads if -Dusethreads is specified.
aaacdc8b 725
cc65bb49 726(You need to also use the PerlIO layer, explained later, if you decide
b29b105d
JH
727to use ithreads, to guarantee the good interworking of threads and I/O.)
728
cc65bb49 729However, if you wish, you can select the unsupported old 5005threads behavior
aaacdc8b 730
6d5328bc
JH
731 sh Configure -Dusethreads -Duse5005threads
732
733If you decide to use ithreads, the 'threads' module allows their use,
734and the 'Thread' module offers an interface to both 5005threads and
735ithreads (whichever has been configured).
aaacdc8b 736
af685957
JH
737When building threaded for certain library calls like the getgr*() and
738the getpw*() there is a dynamically sized result buffer: the buffer
739starts small but Perl will keep growing the buffer until the result fits.
740To get a fixed upper limit you will have to recompile Perl with
741PERL_REENTRANT_MAXSIZE defined to be the number of bytes you want.
742One way to do this is to run Configure with
743C<-Accflags=-DPERL_REENTRANT_MAXSIZE=65536>
744
766b63c4
JH
745=head2 Large file support.
746
5cda700b 747Since Perl 5.6.0, Perl has supported large files (files larger than
766b63c4
JH
7482 gigabytes), and in many common platforms like Linux or Solaris this
749support is on by default.
750
751This is both good and bad. It is good in that you can use large files,
5cda700b
AD
752seek(), stat(), and -s them. It is bad in that if you are interfacing Perl
753using some extension, the components you are connecting to must also
766b63c4
JH
754be large file aware: if Perl thinks files can be large but the other
755parts of the software puzzle do not understand the concept, bad things
756will happen. One popular extension suffering from this ailment is the
757Apache extension mod_perl.
758
759There's also one known limitation with the current large files
760implementation: unless you also have 64-bit integers (see the next
761section), you cannot use the printf/sprintf non-decimal integer
762formats like C<%x> to print filesizes. You can use C<%d>, though.
763
9d5a2765
A
764=head2 64 bit support.
765
766b63c4
JH
766If your platform does not have 64 bits natively, but can simulate them
767with compiler flags and/or C<long long> or C<int64_t>, you can build a
768perl that uses 64 bits.
9d5a2765
A
769
770There are actually two modes of 64-bitness: the first one is achieved
771using Configure -Duse64bitint and the second one using Configure
772-Duse64bitall. The difference is that the first one is minimal and
773the second one maximal. The first works in more places than the second.
774
775The C<use64bitint> does only as much as is required to get 64-bit
776integers into Perl (this may mean, for example, using "long longs")
777while your memory may still be limited to 2 gigabytes (because your
778pointers could still be 32-bit). Note that the name C<64bitint> does
779not imply that your C compiler will be using 64-bit C<int>s (it might,
780but it doesn't have to): the C<use64bitint> means that you will be
781able to have 64 bits wide scalar values.
782
783The C<use64bitall> goes all the way by attempting to switch also
784integers (if it can), longs (and pointers) to being 64-bit. This may
785create an even more binary incompatible Perl than -Duse64bitint: the
786resulting executable may not run at all in a 32-bit box, or you may
787have to reboot/reconfigure/rebuild your operating system to be 64-bit
788aware.
789
790Natively 64-bit systems like Alpha and Cray need neither -Duse64bitint
791nor -Duse64bitall.
792
793 NOTE: 64-bit support is still experimental on most platforms.
794 Existing support only covers the LP64 data model. In particular, the
795 LLP64 data model is not yet supported. 64-bit libraries and system
796 APIs on many platforms have not stabilized--your mileage may vary.
797
798=head2 Long doubles
799
800In some systems you may be able to use long doubles to enhance the
801range and precision of your double precision floating point numbers
802(that is, Perl's numbers). Use Configure -Duselongdouble to enable
803this support (if it is available).
804
805=head2 "more bits"
806
807You can "Configure -Dusemorebits" to turn on both the 64-bit support
808and the long double support.
809
46bb10fb
CS
810=head2 Selecting File IO mechanisms
811
365d6a78 812Executive summary: in Perl 5.8, you should use the default "PerlIO"
dd2bab0f
JH
813as the IO mechanism unless you have a good reason not to.
814
815In more detail: previous versions of perl used the standard IO
816mechanisms as defined in stdio.h. Versions 5.003_02 and later of perl
365d6a78
PN
817introduced alternate IO mechanisms via a "PerlIO" abstraction, but up
818until and including Perl 5.6, the stdio mechanism was still the default
819and the only supported mechanism.
46bb10fb 820
365d6a78 821Starting from Perl 5.8, the default mechanism is to use the PerlIO
6d5328bc
JH
822abstraction, because it allows better control of I/O mechanisms,
823instead of having to work with (often, work around) vendors' I/O
824implementations.
46bb10fb 825
365d6a78
PN
826This PerlIO abstraction can be (but again, unless you know what you
827are doing, should not be) disabled either on the Configure command
828line with
46bb10fb 829
6d5328bc 830 sh Configure -Uuseperlio
46bb10fb 831
6d5328bc 832or interactively at the appropriate Configure prompt.
46bb10fb 833
6d5328bc
JH
834With the PerlIO abstraction layer, there is another possibility for
835the underlying IO calls, AT&T's "sfio". This has superior performance
836to stdio.h in many cases, and is extensible by the use of "discipline"
837modules ("Native" PerlIO has them too). Sfio currently only builds on
838a subset of the UNIX platforms perl supports. Because the data
839structures are completely different from stdio, perl extension modules
840or external libraries may not work. This configuration exists to
841allow these issues to be worked on.
46bb10fb
CS
842
843This option requires the 'sfio' package to have been built and installed.
1b9c9cf5 844The latest sfio is available from http://www.research.att.com/sw/tools/sfio/
46bb10fb
CS
845
846You select this option by
847
848 sh Configure -Duseperlio -Dusesfio
849
850If you have already selected -Duseperlio, and if Configure detects
851that you have sfio, then sfio will be the default suggested by
852Configure.
853
d6baa268
JH
854Note: On some systems, sfio's iffe configuration script fails to
855detect that you have an atexit function (or equivalent). Apparently,
856this is a problem at least for some versions of Linux and SunOS 4.
857Configure should detect this problem and warn you about problems with
858_exit vs. exit. If you have this problem, the fix is to go back to
859your sfio sources and correct iffe's guess about atexit.
33e6ee5f 860
504f80c1
JH
861=head2 Algorithmic Complexity Attacks on Hashes
862
863In Perls 5.8.0 and earlier it was easy to create degenerate hashes.
864Processing such hashes would consume large amounts of CPU time,
3debabd9 865enabling a "Denial of Service" attack against Perl. Such hashes may be
504f80c1
JH
866a problem for example for mod_perl sites, sites with Perl CGI scripts
867and web services, that process data originating from external sources.
868
869In Perl 5.8.1 a security feature was introduced to make it harder
870to create such degenerate hashes.
871
e267033d
JH
872Because of this feature the keys(), values(), and each() functions may
873return the hash elements in different order between different runs of
874Perl even with the same data. One can still revert to the old
4546b9e6 875repeatable order by setting the environment variable PERL_HASH_SEED,
e267033d
JH
876see L<perlrun/PERL_HASH_SEED>. Another option is to add
877-DUSE_HASH_SEED_EXPLICIT to the compilation flags (for example by
878using C<Configure -Accflags=-DUSE_HAS_SEED_EXPLICIT>), in which case
879one has to explicitly set the PERL_HASH_SEED environment variable to
880enable the security feature, or by adding -DNO_HASH_SEED to the compilation
881flags to completely disable the randomisation feature.
504f80c1 882
3debabd9 883B<Perl has never guaranteed any ordering of the hash keys>, and the
504f80c1 884ordering has already changed several times during the lifetime of
3debabd9
TB
885Perl 5. Also, the ordering of hash keys has always been, and
886continues to be, affected by the insertion order.
504f80c1
JH
887
888Note that because of this randomisation for example the Data::Dumper
889results will be different between different runs of Perl since
890Data::Dumper by default dumps hashes "unordered". The use of the
3debabd9 891Data::Dumper C<Sortkeys> option is recommended.
504f80c1 892
1b9c9cf5
DH
893=head2 SOCKS
894
895Perl can be configured to be 'socksified', that is, to use the SOCKS
896TCP/IP proxy protocol library. SOCKS is used to give applications
897access to transport layer network proxies. Perl supports only SOCKS
898Version 5. You can find more about SOCKS from http://www.socks.nec.com/
899
d6baa268
JH
900=head2 Dynamic Loading
901
902By default, Configure will compile perl to use dynamic loading if
903your system supports it. If you want to force perl to be compiled
904statically, you can either choose this when Configure prompts you or
905you can use the Configure command line option -Uusedl.
906
10c7e831 907=head2 Building a shared Perl library
c3edaffb
PP
908
909Currently, for most systems, the main perl executable is built by
910linking the "perl library" libperl.a with perlmain.o, your static
911extensions (usually just DynaLoader.a) and various extra libraries,
912such as -lm.
913
9d67150a
PP
914On some systems that support dynamic loading, it may be possible to
915replace libperl.a with a shared libperl.so. If you anticipate building
c3edaffb
PP
916several different perl binaries (e.g. by embedding libperl into
917different programs, or by using the optional compiler extension), then
9d67150a 918you might wish to build a shared libperl.so so that all your binaries
c3edaffb
PP
919can share the same library.
920
921The disadvantages are that there may be a significant performance
9d67150a 922penalty associated with the shared libperl.so, and that the overall
aa689395 923mechanism is still rather fragile with respect to different versions
c3edaffb
PP
924and upgrades.
925
926In terms of performance, on my test system (Solaris 2.5_x86) the perl
9d67150a 927test suite took roughly 15% longer to run with the shared libperl.so.
c3edaffb
PP
928Your system and typical applications may well give quite different
929results.
930
931The default name for the shared library is typically something like
a6006777 932libperl.so.3.2 (for Perl 5.003_02) or libperl.so.302 or simply
9d67150a 933libperl.so. Configure tries to guess a sensible naming convention
c3edaffb
PP
934based on your C library name. Since the library gets installed in a
935version-specific architecture-dependent directory, the exact name
936isn't very important anyway, as long as your linker is happy.
937
938For some systems (mostly SVR4), building a shared libperl is required
939for dynamic loading to work, and hence is already the default.
940
941You can elect to build a shared libperl by
942
943 sh Configure -Duseshrplib
944
2bf2710f
GS
945To build a shared libperl, the environment variable controlling shared
946library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
78be1e1a
JH
947NeXTSTEP/OPENSTEP/Darwin, LIBRARY_PATH for BeOS, LD_LIBRARY_PATH/SHLIB_PATH
948for HP-UX, LIBPATH for AIX, PATH for Cygwin) must be set up to include
2bf2710f 949the Perl build directory because that's where the shared libperl will
d6baa268 950be created. Configure arranges makefile to have the correct shared
10c7e831
JH
951library search settings. You can find the name of the environment
952variable Perl thinks works in your your system by
953
954 grep ldlibpthname config.sh
2bf2710f
GS
955
956However, there are some special cases where manually setting the
957shared library path might be required. For example, if you want to run
958something like the following with the newly-built but not-yet-installed
959./perl:
960
961 cd t; ./perl misc/failing_test.t
962or
963 ./perl -Ilib ~/my_mission_critical_test
964
965then you need to set up the shared library path explicitly.
966You can do this with
c3edaffb
PP
967
968 LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
969
970for Bourne-style shells, or
971
972 setenv LD_LIBRARY_PATH `pwd`
973
2bf2710f 974for Csh-style shells. (This procedure may also be needed if for some
10c7e831 975unexpected reason Configure fails to set up makefile correctly.) (And
5cda700b 976again, it may be something other than LD_LIBRARY_PATH for you, see above.)
2bf2710f
GS
977
978You can often recognize failures to build/use a shared libperl from error
979messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
980for example:
98118126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
c3edaffb 982
9d67150a
PP
983There is also an potential problem with the shared perl library if you
984want to have more than one "flavor" of the same version of perl (e.g.
985with and without -DDEBUGGING). For example, suppose you build and
cc65bb49
AD
986install a standard Perl 5.8.0 with a shared library. Then, suppose you
987try to build Perl 5.8.0 with -DDEBUGGING enabled, but everything else
9d67150a
PP
988the same, including all the installation directories. How can you
989ensure that your newly built perl will link with your newly built
cc65bb49 990libperl.so.8 rather with the installed libperl.so.8? The answer is
9d67150a 991that you might not be able to. The installation directory is encoded
56c6f531
JH
992in the perl binary with the LD_RUN_PATH environment variable (or
993equivalent ld command-line option). On Solaris, you can override that
1ff4263c
CT
994with LD_LIBRARY_PATH; on Linux, you can only override at runtime via
995LD_PRELOAD, specifying the exact filename you wish to be used; and on
996Digital Unix, you can override LD_LIBRARY_PATH by setting the
997_RLD_ROOT environment variable to point to the perl build directory.
9d67150a 998
830717a7
AD
999In other words, it is generally not a good idea to try to build a perl
1000with a shared library if $archlib/CORE/$libperl already exists from a
1001previous build.
1002
1003A good workaround is to specify a different directory for the
1004architecture-dependent library for your -DDEBUGGING version of perl.
1005You can do this by changing all the *archlib* variables in config.sh to
1006point to your new architecture-dependent library.
9d67150a 1007
55479bb6
AD
1008=head2 Malloc Issues
1009
d6baa268
JH
1010Perl relies heavily on malloc(3) to grow data structures as needed,
1011so perl's performance can be noticeably affected by the performance of
1012the malloc function on your system. The perl source is shipped with a
1013version of malloc that has been optimized for the typical requests from
1014perl, so there's a chance that it may be both faster and use less memory
1015than your system malloc.
55479bb6 1016
d6baa268
JH
1017However, if your system already has an excellent malloc, or if you are
1018experiencing difficulties with extensions that use third-party libraries
1019that call malloc, then you should probably use your system's malloc.
1020(Or, you might wish to explore the malloc flags discussed below.)
c3edaffb 1021
aa689395
PP
1022=over 4
1023
d6baa268 1024=item Using the system malloc
2ae324a7 1025
d6baa268 1026To build without perl's malloc, you can use the Configure command
aa689395 1027
d6baa268 1028 sh Configure -Uusemymalloc
aa689395 1029
d6baa268 1030or you can answer 'n' at the appropriate interactive Configure prompt.
aa689395 1031
86058a2d
GS
1032=item -DPERL_POLLUTE_MALLOC
1033
d953f698
JH
1034NOTE: This flag is enabled automatically on some platforms if you just
1035run Configure to accept all the defaults on those platforms.
b2a6d19e 1036
5cda700b
AD
1037Perl's malloc family of functions are normally called Perl_malloc(),
1038Perl_realloc(), Perl_calloc() and Perl_mfree().
1039These names do not clash with the system versions of these functions.
d6baa268 1040
5cda700b
AD
1041If this flag is enabled, however, Perl's malloc family of functions
1042will have the same names as the system versions. This may be required
1043sometimes if you have libraries that like to free() data that may have
1044been allocated by Perl_malloc() and vice versa.
86058a2d 1045
d6baa268
JH
1046Note that enabling this option may sometimes lead to duplicate symbols
1047from the linker for malloc et al. In such cases, the system probably
1048does not allow its malloc functions to be fully replaced with custom
1049versions.
86058a2d 1050
06c896bb
SH
1051=item -DPERL_DEBUGGING_MSTATS
1052
1053This flag enables debugging mstats, which is required to use the
1054Devel::Peek::mstat() function. You cannot enable this unless you are
1055using Perl's malloc, so a typical Configure command would be
1056
8267c262 1057 sh Configure -Accflags=-DPERL_DEBUGGING_MSTATS -Dusemymalloc='y'
06c896bb
SH
1058
1059to enable this option.
1060
aa689395
PP
1061=back
1062
3bf462b8
CS
1063=head2 Building a debugging perl
1064
1065You can run perl scripts under the perl debugger at any time with
3fe9a6f1 1066B<perl -d your_script>. If, however, you want to debug perl itself,
3bf462b8
CS
1067you probably want to do
1068
1069 sh Configure -Doptimize='-g'
1070
203c3eec
AD
1071This will do two independent things: First, it will force compilation
1072to use cc -g so that you can use your system's debugger on the
1073executable. (Note: Your system may actually require something like
d6baa268
JH
1074cc -g2. Check your man pages for cc(1) and also any hint file for
1075your system.) Second, it will add -DDEBUGGING to your ccflags
1076variable in config.sh so that you can use B<perl -D> to access perl's
1077internal state. (Note: Configure will only add -DDEBUGGING by default
1078if you are not reusing your old config.sh. If you want to reuse your
1079old config.sh, then you can just edit it and change the optimize and
1080ccflags variables by hand and then propagate your changes as shown in
1081L<"Propagating your changes to config.sh"> below.)
203c3eec
AD
1082
1083You can actually specify -g and -DDEBUGGING independently, but usually
1084it's convenient to have both.
3bf462b8
CS
1085
1086If you are using a shared libperl, see the warnings about multiple
1087versions of perl under L<Building a shared libperl.so Perl library>.
1088
8d74ce1c
AD
1089=head2 Extensions
1090
80c1f5de
AD
1091Perl ships with a number of standard extensions. These are contained
1092in the ext/ subdirectory.
1093
8d74ce1c
AD
1094By default, Configure will offer to build every extension which appears
1095to be supported. For example, Configure will offer to build GDBM_File
1096only if it is able to find the gdbm library. (See examples below.)
8d74ce1c
AD
1097Configure does not contain code to test for POSIX compliance, so POSIX
1098is always built by default as well. If you wish to skip POSIX, you can
1099set the Configure variable useposix=false either in a hint file or from
80c1f5de 1100the Configure command line.
8d74ce1c 1101
c42e3e15
GS
1102If you unpack any additional extensions in the ext/ directory before
1103running Configure, then Configure will offer to build those additional
1104extensions as well. Most users probably shouldn't have to do this --
1105it is usually easier to build additional extensions later after perl
1106has been installed. However, if you wish to have those additional
1107extensions statically linked into the perl binary, then this offers a
1108convenient way to do that in one step. (It is not necessary, however;
1109you can build and install extensions just fine even if you don't have
1110dynamic loading. See lib/ExtUtils/MakeMaker.pm for more details.)
1111
1112You can learn more about each of the supplied extensions by consulting the
8d74ce1c
AD
1113documentation in the individual .pm modules, located under the
1114ext/ subdirectory.
1115
1116Even if you do not have dynamic loading, you must still build the
1117DynaLoader extension; you should just build the stub dl_none.xs
1118version. (Configure will suggest this as the default.)
1119
7a8675bc
JH
1120To disable certain extensions so that they are not built, use
1121the -Dnoextensions=... and -Donlyextensions=... options. They both
1122accept a space-separated list of extensions. The extensions listed
1123in C<noextensions> are removed from the list of extensions to build,
1124while the C<onlyextensions> is rather more severe and builds only
1125the listed extensions. The latter should be used with extreme caution
1126since certain extensions are used by many other extensions and modules:
1127such modules include Fcntl and IO. The order of processing these
1128options is first C<only> (if present), then C<no> (if present).
1129
1130Another, older way to turn off various extensions (which is still good
1131to know if you have to work with older Perl) exists. Here are the
1132Configure command-line variables you can set to turn off various
1133extensions. All others are included by default.
8d74ce1c 1134
8d74ce1c
AD
1135 DB_File i_db
1136 DynaLoader (Must always be included as a static extension)
8d74ce1c 1137 GDBM_File i_gdbm
8d74ce1c
AD
1138 NDBM_File i_ndbm
1139 ODBM_File i_dbm
1140 POSIX useposix
8d74ce1c
AD
1141 Opcode useopcode
1142 Socket d_socket
a2dab6bc 1143 Threads use5005threads
8d74ce1c
AD
1144
1145Thus to skip the NDBM_File extension, you can use
1146
1147 sh Configure -Ui_ndbm
1148
1149Again, this is taken care of automatically if you don't have the ndbm
1150library.
1151
1152Of course, you may always run Configure interactively and select only
1153the extensions you want.
1154
1155Note: The DB_File module will only work with version 1.x of Berkeley
1156DB or newer releases of version 2. Configure will automatically detect
1157this for you and refuse to try to build DB_File with earlier
1158releases of version 2.
1159
1160If you re-use your old config.sh but change your system (e.g. by
1161adding libgdbm) Configure will still offer your old choices of extensions
1162for the default answer, but it will also point out the discrepancy to
1163you.
1164
80c1f5de 1165Finally, if you have dynamic loading (most modern systems do)
8d74ce1c
AD
1166remember that these extensions do not increase the size of your perl
1167executable, nor do they impact start-up time, so you probably might as
1168well build all the ones that will work on your system.
1169
1170=head2 Including locally-installed libraries
1171
1172Perl5 comes with interfaces to number of database extensions, including
1173dbm, ndbm, gdbm, and Berkeley db. For each extension, if
1174Configure can find the appropriate header files and libraries, it will
1175automatically include that extension. The gdbm and db libraries
1176are not included with perl. See the library documentation for
1177how to obtain the libraries.
1178
d6baa268
JH
1179If your database header (.h) files are not in a directory normally
1180searched by your C compiler, then you will need to include the
1181appropriate -I/your/directory option when prompted by Configure. If
1182your database library (.a) files are not in a directory normally
1183searched by your C compiler and linker, then you will need to include
1184the appropriate -L/your/directory option when prompted by Configure.
1185See the examples below.
8d74ce1c
AD
1186
1187=head2 Examples
1188
1189=over 4
1190
1191=item gdbm in /usr/local
1192
1193Suppose you have gdbm and want Configure to find it and build the
d6baa268 1194GDBM_File extension. This example assumes you have gdbm.h
8d74ce1c
AD
1195installed in /usr/local/include/gdbm.h and libgdbm.a installed in
1196/usr/local/lib/libgdbm.a. Configure should figure all the
1197necessary steps out automatically.
1198
1199Specifically, when Configure prompts you for flags for
1200your C compiler, you should include -I/usr/local/include.
1201
1202When Configure prompts you for linker flags, you should include
1203-L/usr/local/lib.
1204
1205If you are using dynamic loading, then when Configure prompts you for
1206linker flags for dynamic loading, you should again include
1207-L/usr/local/lib.
1208
d6baa268
JH
1209Again, this should all happen automatically. This should also work if
1210you have gdbm installed in any of (/usr/local, /opt/local, /usr/gnu,
1211/opt/gnu, /usr/GNU, or /opt/GNU).
8d74ce1c
AD
1212
1213=item gdbm in /usr/you
1214
1215Suppose you have gdbm installed in some place other than /usr/local/,
1216but you still want Configure to find it. To be specific, assume you
1217have /usr/you/include/gdbm.h and /usr/you/lib/libgdbm.a. You
1218still have to add -I/usr/you/include to cc flags, but you have to take
1219an extra step to help Configure find libgdbm.a. Specifically, when
1220Configure prompts you for library directories, you have to add
1221/usr/you/lib to the list.
1222
1223It is possible to specify this from the command line too (all on one
1224line):
1225
d6baa268 1226 sh Configure -de \
8d74ce1c
AD
1227 -Dlocincpth="/usr/you/include" \
1228 -Dloclibpth="/usr/you/lib"
1229
1230locincpth is a space-separated list of include directories to search.
1231Configure will automatically add the appropriate -I directives.
1232
1233loclibpth is a space-separated list of library directories to search.
1234Configure will automatically add the appropriate -L directives. If
1235you have some libraries under /usr/local/ and others under
1236/usr/you, then you have to include both, namely
1237
d6baa268 1238 sh Configure -de \
8d74ce1c
AD
1239 -Dlocincpth="/usr/you/include /usr/local/include" \
1240 -Dloclibpth="/usr/you/lib /usr/local/lib"
1241
1242=back
1243
bb636fa4
JH
1244=head2 Building DB, NDBM, and ODBM interfaces with Berkeley DB 3
1245
1246Perl interface for DB3 is part of Berkeley DB, but if you want to
1247compile standard Perl DB/ODBM/NDBM interfaces, you must follow
1248following instructions.
1249
1250Berkeley DB3 from Sleepycat Software is by default installed without
1251DB1 compatibility code (needed for DB_File interface) and without
1252links to compatibility files. So if you want to use packages written
1253for DB/ODBM/NDBM interfaces, you need to configure DB3 with
1254--enable-compat185 (and optionally with --enable-dump185) and create
1255additional references (suppose you are installing DB3 with
1256--prefix=/usr):
1257
1258 ln -s libdb-3.so /usr/lib/libdbm.so
1259 ln -s libdb-3.so /usr/lib/libndbm.so
1260 echo '#define DB_DBM_HSEARCH 1' >dbm.h
1261 echo '#include <db.h>' >>dbm.h
1262 install -m 0644 dbm.h /usr/include/dbm.h
1263 install -m 0644 dbm.h /usr/include/ndbm.h
1264
1265Optionally, if you have compiled with --enable-compat185 (not needed
1266for ODBM/NDBM):
1267
1268 ln -s libdb-3.so /usr/lib/libdb1.so
1269 ln -s libdb-3.so /usr/lib/libdb.so
1270
1271ODBM emulation seems not to be perfect, but is quite usable,
1272using DB 3.1.17:
1273
1274 lib/odbm.............FAILED at test 9
1275 Failed 1/64 tests, 98.44% okay
1276
8e07c86e
AD
1277=head2 What if it doesn't work?
1278
8d74ce1c
AD
1279If you run into problems, try some of the following ideas.
1280If none of them help, then see L<"Reporting Problems"> below.
1281
8e07c86e
AD
1282=over 4
1283
25f94b33
AD
1284=item Running Configure Interactively
1285
1286If Configure runs into trouble, remember that you can always run
1287Configure interactively so that you can check (and correct) its
1288guesses.
1289
1290All the installation questions have been moved to the top, so you don't
aa689395 1291have to wait for them. Once you've handled them (and your C compiler and
1ec51d55 1292flags) you can type &-d at the next Configure prompt and Configure
25f94b33
AD
1293will use the defaults from then on.
1294
1295If you find yourself trying obscure command line incantations and
1296config.over tricks, I recommend you run Configure interactively
1297instead. You'll probably save yourself time in the long run.
1298
aa689395 1299=item Hint files
8e07c86e
AD
1300
1301The perl distribution includes a number of system-specific hints files
1302in the hints/ directory. If one of them matches your system, Configure
1303will offer to use that hint file.
1304
1305Several of the hint files contain additional important information.
f5b3b617
AD
1306If you have any problems, it is a good idea to read the relevant hint file
1307for further information. See hints/solaris_2.sh for an extensive example.
1308More information about writing good hints is in the hints/README.hints
1309file.
8e07c86e 1310
edb1cbcb
PP
1311=item *** WHOA THERE!!! ***
1312
1313Occasionally, Configure makes a wrong guess. For example, on SunOS
13144.1.3, Configure incorrectly concludes that tzname[] is in the
1315standard C library. The hint file is set up to correct for this. You
1316will see a message:
1317
1318 *** WHOA THERE!!! ***
1319 The recommended value for $d_tzname on this machine was "undef"!
1320 Keep the recommended value? [y]
1321
1322You should always keep the recommended value unless, after reading the
1323relevant section of the hint file, you are sure you want to try
1324overriding it.
1325
1326If you are re-using an old config.sh, the word "previous" will be
1327used instead of "recommended". Again, you will almost always want
1328to keep the previous value, unless you have changed something on your
1329system.
1330
1331For example, suppose you have added libgdbm.a to your system
1332and you decide to reconfigure perl to use GDBM_File. When you run
1333Configure again, you will need to add -lgdbm to the list of libraries.
bfb7748a
AD
1334Now, Configure will find your gdbm include file and library and will
1335issue a message:
edb1cbcb
PP
1336
1337 *** WHOA THERE!!! ***
1338 The previous value for $i_gdbm on this machine was "undef"!
1339 Keep the previous value? [y]
1340
1ec51d55 1341In this case, you do not want to keep the previous value, so you
c3edaffb 1342should answer 'n'. (You'll also have to manually add GDBM_File to
edb1cbcb
PP
1343the list of dynamic extensions to build.)
1344
8e07c86e
AD
1345=item Changing Compilers
1346
1347If you change compilers or make other significant changes, you should
1ec51d55 1348probably not re-use your old config.sh. Simply remove it or
8e07c86e
AD
1349rename it, e.g. mv config.sh config.sh.old. Then rerun Configure
1350with the options you want to use.
1351
1ec51d55
CS
1352This is a common source of problems. If you change from cc to
1353gcc, you should almost always remove your old config.sh.
8e07c86e 1354
c3edaffb 1355=item Propagating your changes to config.sh
8e07c86e 1356
1ec51d55
CS
1357If you make any changes to config.sh, you should propagate
1358them to all the .SH files by running
1359
1360 sh Configure -S
1361
1362You will then have to rebuild by running
9d67150a
PP
1363
1364 make depend
1365 make
8e07c86e 1366
48370efc
JH
1367=item config.over and config.arch
1368
1369You can also supply a shell script config.over to over-ride
1370Configure's guesses. It will get loaded up at the very end, just
1371before config.sh is created. You have to be careful with this,
1372however, as Configure does no checking that your changes make sense.
1373This file is usually good for site-specific customizations.
1374
1375There is also another file that, if it exists, is loaded before the
1376config.over, called config.arch. This file is intended to be per
1377architecture, not per site, and usually it's the architecture-specific
1378hints file that creates the config.arch.
8e07c86e
AD
1379
1380=item config.h
1381
1ec51d55
CS
1382Many of the system dependencies are contained in config.h.
1383Configure builds config.h by running the config_h.SH script.
1384The values for the variables are taken from config.sh.
8e07c86e 1385
1ec51d55
CS
1386If there are any problems, you can edit config.h directly. Beware,
1387though, that the next time you run Configure, your changes will be
8e07c86e
AD
1388lost.
1389
1390=item cflags
1391
1392If you have any additional changes to make to the C compiler command
1ec51d55
CS
1393line, they can be made in cflags.SH. For instance, to turn off the
1394optimizer on toke.c, find the line in the switch structure for
1395toke.c and put the command optimize='-g' before the ;; . You
1396can also edit cflags directly, but beware that your changes will be
1397lost the next time you run Configure.
8e07c86e 1398
f5b3b617
AD
1399To explore various ways of changing ccflags from within a hint file,
1400see the file hints/README.hints.
1401
1402To change the C flags for all the files, edit config.sh and change either
1403$ccflags or $optimize, and then re-run
1ec51d55
CS
1404
1405 sh Configure -S
1406 make depend
8e07c86e 1407
aa689395 1408=item No sh
8e07c86e 1409
c42e3e15
GS
1410If you don't have sh, you'll have to copy the sample file
1411Porting/config.sh to config.sh and edit your config.sh to reflect your
1412system's peculiarities. See Porting/pumpkin.pod for more information.
8e07c86e
AD
1413You'll probably also have to extensively modify the extension building
1414mechanism.
1415
d6baa268
JH
1416=item Digital UNIX/Tru64 UNIX and BIN_SH
1417
1418In Digital UNIX/Tru64 UNIX, Configure might abort with
1419
1420Build a threading Perl? [n]
1421Configure[2437]: Syntax error at line 1 : `config.sh' is not expected.
1422
1423This indicates that Configure is being run with a broken Korn shell
1424(even though you think you are using a Bourne shell by using
1425"sh Configure" or "./Configure"). The Korn shell bug has been reported
1426to Compaq as of February 1999 but in the meanwhile, the reason ksh is
1427being used is that you have the environment variable BIN_SH set to
1428'xpg4'. This causes /bin/sh to delegate its duties to /bin/posix/sh
1429(a ksh). Unset the environment variable and rerun Configure.
1430
1431=item HP-UX 11, pthreads, and libgdbm
1432
1433If you are running Configure with -Dusethreads in HP-UX 11, be warned
1434that POSIX threads and libgdbm (the GNU dbm library) compiled before
1435HP-UX 11 do not mix. This will cause a basic test run by Configure to
1436fail
1437
1438Pthread internal error: message: __libc_reinit() failed, file: ../pthreads/pthread.c, line: 1096
1439Return Pointer is 0xc082bf33
1440sh: 5345 Quit(coredump)
1441
1442and Configure will give up. The cure is to recompile and install
1443libgdbm under HP-UX 11.
1444
c3edaffb
PP
1445=item Porting information
1446
e6f03d26 1447Specific information for the OS/2, Plan 9, VMS and Win32 ports is in the
1ec51d55
CS
1448corresponding README files and subdirectories. Additional information,
1449including a glossary of all those config.sh variables, is in the Porting
c42e3e15 1450subdirectory. Especially Porting/Glossary should come in handy.
c3edaffb 1451
7f678428 1452Ports for other systems may also be available. You should check out
468f45d5 1453http://www.cpan.org/ports for current information on ports to
7f678428
PP
1454various other operating systems.
1455
491517e0
JA
1456If you plan to port Perl to a new architecture study carefully the
1457section titled "Philosophical Issues in Patching and Porting Perl"
1458in the file Porting/pumpkin.pod and the file Porting/patching.pod.
1459Study also how other non-UNIX ports have solved problems.
1460
8e07c86e
AD
1461=back
1462
fadf0ef5
JH
1463=head1 Adding extra modules to the build
1464
1465You can specify extra modules or module bundles to be fetched from the
1466CPAN and installed as part of the Perl build. Either use the -Dextras=...
1467command line parameter to Configure, for example like this:
1468
1469 Configure -Dextras="Compress::Zlib Bundle::LWP DBI"
1470
1471or answer first 'y' to the question 'Install any extra modules?' and
1472then answer "Compress::Zlib Bundle::LWP DBI" to the 'Extras?' question.
1473The module or the bundle names are as for the CPAN module 'install' command.
1474
1475Notice that because the CPAN module will be used to fetch the extra
1476modules, you will need access to the CPAN, either via the Internet,
1477or via a local copy such as a CD-ROM or a local CPAN mirror. If you
1478do not, using the extra modules option will die horribly.
1479
1480Also notice that you yourself are responsible for satisfying any extra
1481dependencies such as external headers or libraries BEFORE trying the build.
1482For example: you will need to have the zlib.h header and the libz
1483library installed for the Compress::Zlib, or the Foo database specific
1484headers and libraries installed for the DBD::Foo module. The Configure
1485process or the Perl build process will not help you with these.
1486
03739d21
JH
1487=head1 suidperl
1488
c80c8d62 1489suidperl is an optional component, which is built or installed by default.
03739d21
JH
1490From perlfaq1:
1491
1492 On some systems, setuid and setgid scripts (scripts written
1493 in the C shell, Bourne shell, or Perl, for example, with the
1494 set user or group ID permissions enabled) are insecure due to
1495 a race condition in the kernel. For those systems, Perl versions
1496 5 and 4 attempt to work around this vulnerability with an optional
1497 component, a special program named suidperl, also known as sperl.
1498 This program attempts to emulate the set-user-ID and set-group-ID
1499 features of the kernel.
1500
1501Because of the buggy history of suidperl, and the difficulty
1502of properly security auditing as large and complex piece of
1503software as Perl, we cannot recommend using suidperl and the feature
1504should be considered deprecated.
1505Instead use for example 'sudo': http://www.courtesan.com/sudo/
1506
8e07c86e
AD
1507=head1 make depend
1508
bfb7748a
AD
1509This will look for all the includes. The output is stored in makefile.
1510The only difference between Makefile and makefile is the dependencies at
1511the bottom of makefile. If you have to make any changes, you should edit
1512makefile, not Makefile since the Unix make command reads makefile first.
1513(On non-Unix systems, the output may be stored in a different file.
1514Check the value of $firstmakefile in your config.sh if in doubt.)
8e07c86e
AD
1515
1516Configure will offer to do this step for you, so it isn't listed
1517explicitly above.
1518
1519=head1 make
1520
1521This will attempt to make perl in the current directory.
1522
8d410bc4
YST
1523=head2 Expected errors
1524
1525These errors are normal, and can be ignored:
1526
1527 ...
1528 make: [extra.pods] Error 1 (ignored)
1529 ...
1530 make: [extras.make] Error 1 (ignored)
1531
8d74ce1c
AD
1532=head2 What if it doesn't work?
1533
8e07c86e 1534If you can't compile successfully, try some of the following ideas.
7f678428 1535If none of them help, and careful reading of the error message and
8d74ce1c
AD
1536the relevant manual pages on your system doesn't help,
1537then see L<"Reporting Problems"> below.
8e07c86e
AD
1538
1539=over 4
1540
1ec51d55 1541=item hints
8e07c86e
AD
1542
1543If you used a hint file, try reading the comments in the hint file
1544for further tips and information.
1545
1ec51d55 1546=item extensions
8e07c86e 1547
1ec51d55 1548If you can successfully build miniperl, but the process crashes
c3edaffb
PP
1549during the building of extensions, you should run
1550
3a6175e1 1551 make minitest
c3edaffb
PP
1552
1553to test your version of miniperl.
1554
e57fd563
PP
1555=item locale
1556
bfb7748a
AD
1557If you have any locale-related environment variables set, try unsetting
1558them. I have some reports that some versions of IRIX hang while
1559running B<./miniperl configpm> with locales other than the C locale.
1560See the discussion under L<"make test"> below about locales and the
1561whole L<"Locale problems"> section in the file pod/perllocale.pod.
3e6e419a
JH
1562The latter is especially useful if you see something like this
1563
1564 perl: warning: Setting locale failed.
1565 perl: warning: Please check that your locale settings:
1566 LC_ALL = "En_US",
1567 LANG = (unset)
1568 are supported and installed on your system.
1569 perl: warning: Falling back to the standard locale ("C").
1570
1571at Perl startup.
e57fd563 1572
7f678428 1573=item varargs
c3edaffb
PP
1574
1575If you get varargs problems with gcc, be sure that gcc is installed
bfb7748a
AD
1576correctly and that you are not passing -I/usr/include to gcc. When using
1577gcc, you should probably have i_stdarg='define' and i_varargs='undef'
1578in config.sh. The problem is usually solved by running fixincludes
1579correctly. If you do change config.sh, don't forget to propagate
1580your changes (see L<"Propagating your changes to config.sh"> below).
7f678428 1581See also the L<"vsprintf"> item below.
c3edaffb 1582
bfb7748a 1583=item util.c
c3edaffb
PP
1584
1585If you get error messages such as the following (the exact line
bfb7748a 1586numbers and function name may vary in different versions of perl):
c3edaffb 1587
bfb7748a
AD
1588 util.c: In function `Perl_form':
1589 util.c:1107: number of arguments doesn't match prototype
1590 proto.h:125: prototype declaration
c3edaffb
PP
1591
1592it might well be a symptom of the gcc "varargs problem". See the
7f678428 1593previous L<"varargs"> item.
c3edaffb 1594
1ec51d55 1595=item LD_LIBRARY_PATH
c3edaffb
PP
1596
1597If you run into dynamic loading problems, check your setting of
aa689395
PP
1598the LD_LIBRARY_PATH environment variable. If you're creating a static
1599Perl library (libperl.a rather than libperl.so) it should build
c3edaffb
PP
1600fine with LD_LIBRARY_PATH unset, though that may depend on details
1601of your local set-up.
1602
aa689395 1603=item nm extraction
c3edaffb
PP
1604
1605If Configure seems to be having trouble finding library functions,
1606try not using nm extraction. You can do this from the command line
1607with
1608
1609 sh Configure -Uusenm
1610
1611or by answering the nm extraction question interactively.
1ec51d55 1612If you have previously run Configure, you should not reuse your old
c3edaffb
PP
1613config.sh.
1614
bfb7748a
AD
1615=item umask not found
1616
1617If the build processes encounters errors relating to umask(), the problem
1618is probably that Configure couldn't find your umask() system call.
1619Check your config.sh. You should have d_umask='define'. If you don't,
1620this is probably the L<"nm extraction"> problem discussed above. Also,
1621try reading the hints file for your system for further information.
1622
7f678428 1623=item vsprintf
c3edaffb
PP
1624
1625If you run into problems with vsprintf in compiling util.c, the
1626problem is probably that Configure failed to detect your system's
1627version of vsprintf(). Check whether your system has vprintf().
1628(Virtually all modern Unix systems do.) Then, check the variable
1629d_vprintf in config.sh. If your system has vprintf, it should be:
1630
1631 d_vprintf='define'
1632
1633If Configure guessed wrong, it is likely that Configure guessed wrong
bfb7748a
AD
1634on a number of other common functions too. This is probably
1635the L<"nm extraction"> problem discussed above.
c3edaffb 1636
3fe9a6f1
PP
1637=item do_aspawn
1638
1639If you run into problems relating to do_aspawn or do_spawn, the
1640problem is probably that Configure failed to detect your system's
bfb7748a
AD
1641fork() function. Follow the procedure in the previous item
1642on L<"nm extraction">.
3fe9a6f1 1643
84902520
TB
1644=item __inet_* errors
1645
1646If you receive unresolved symbol errors during Perl build and/or test
1647referring to __inet_* symbols, check to see whether BIND 8.1 is
1648installed. It installs a /usr/local/include/arpa/inet.h that refers to
1649these symbols. Versions of BIND later than 8.1 do not install inet.h
1650in that location and avoid the errors. You should probably update to a
6d240721
JH
1651newer version of BIND (and remove the files the old one left behind).
1652If you can't, you can either link with the updated resolver library provided
1653with BIND 8.1 or rename /usr/local/bin/arpa/inet.h during the Perl build and
1654test process to avoid the problem.
1655
1656=item *_r() prototype NOT found
1657
1658On a related note, if you see a bunch of complaints like the above about
1659reentrant functions - specifically networking-related ones - being present
1660but without prototypes available, check to see if BIND 8.1 (or possibly
1661other BIND 8 versions) is (or has been) installed. They install
1662header files such as netdb.h into places such as /usr/local/include (or into
1663another directory as specified at build/install time), at least optionally.
1664Remove them or put them in someplace that isn't in the C preprocessor's
1665header file include search path (determined by -I options plus defaults,
1666normally /usr/include).
84902520 1667
d6baa268
JH
1668=item #error "No DATAMODEL_NATIVE specified"
1669
1670This is a common error when trying to build perl on Solaris 2.6 with a
1671gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files
1672changed, so you need to update your gcc installation. You can either
1673rerun the fixincludes script from gcc or take the opportunity to
1674update your gcc installation.
1675
aa689395 1676=item Optimizer
c3edaffb 1677
9d67150a 1678If you can't compile successfully, try turning off your compiler's
aa689395 1679optimizer. Edit config.sh and change the line
9d67150a
PP
1680
1681 optimize='-O'
1682
bfb7748a 1683to
9d67150a
PP
1684
1685 optimize=' '
1686
1687then propagate your changes with B<sh Configure -S> and rebuild
1688with B<make depend; make>.
1689
9d67150a
PP
1690=item Missing functions
1691
1692If you have missing routines, you probably need to add some library or
1693other, or you need to undefine some feature that Configure thought was
1694there but is defective or incomplete. Look through config.h for
bfb7748a
AD
1695likely suspects. If Configure guessed wrong on a number of functions,
1696you might have the L<"nm extraction"> problem discussed above.
8e07c86e 1697
1ec51d55 1698=item toke.c
8e07c86e 1699
1ec51d55
CS
1700Some compilers will not compile or optimize the larger files (such as
1701toke.c) without some extra switches to use larger jump offsets or
1702allocate larger internal tables. You can customize the switches for
1703each file in cflags. It's okay to insert rules for specific files into
1704makefile since a default rule only takes effect in the absence of a
8e07c86e
AD
1705specific rule.
1706
7f678428 1707=item Missing dbmclose
8e07c86e 1708
c3edaffb
PP
1709SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
1710that includes libdbm.nfs (which includes dbmclose()) may be available.
8e07c86e 1711
f3d9a6ba 1712=item Note (probably harmless): No library found for -lsomething
7f678428
PP
1713
1714If you see such a message during the building of an extension, but
1715the extension passes its tests anyway (see L<"make test"> below),
1716then don't worry about the warning message. The extension
1717Makefile.PL goes looking for various libraries needed on various
aa689395 1718systems; few systems will need all the possible libraries listed.
7f678428
PP
1719For example, a system may have -lcposix or -lposix, but it's
1720unlikely to have both, so most users will see warnings for the one
f3d9a6ba
CS
1721they don't have. The phrase 'probably harmless' is intended to
1722reassure you that nothing unusual is happening, and the build
1723process is continuing.
7f678428
PP
1724
1725On the other hand, if you are building GDBM_File and you get the
1726message
1727
f3d9a6ba 1728 Note (probably harmless): No library found for -lgdbm
7f678428
PP
1729
1730then it's likely you're going to run into trouble somewhere along
1731the line, since it's hard to see how you can use the GDBM_File
1732extension without the -lgdbm library.
1733
1734It is true that, in principle, Configure could have figured all of
1735this out, but Configure and the extension building process are not
1736quite that tightly coordinated.
1737
aa689395
PP
1738=item sh: ar: not found
1739
1740This is a message from your shell telling you that the command 'ar'
1741was not found. You need to check your PATH environment variable to
1742make sure that it includes the directory with the 'ar' command. This
1ec51d55 1743is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
aa689395
PP
1744directory.
1745
1746=item db-recno failure on tests 51, 53 and 55
1747
1748Old versions of the DB library (including the DB library which comes
1749with FreeBSD 2.1) had broken handling of recno databases with modified
1750bval settings. Upgrade your DB library or OS.
1751
6087ac44
JH
1752=item Bad arg length for semctl, is XX, should be ZZZ
1753
11906ba0 1754If you get this error message from the ext/IPC/SysV/t/sem test, your System
6087ac44
JH
1755V IPC may be broken. The XX typically is 20, and that is what ZZZ
1756also should be. Consider upgrading your OS, or reconfiguring your OS
1757to include the System V semaphores.
1758
11906ba0 1759=item ext/IPC/SysV/t/sem........semget: No space left on device
220f3621
GS
1760
1761Either your account or the whole system has run out of semaphores. Or
1762both. Either list the semaphores with "ipcs" and remove the unneeded
1763ones (which ones these are depends on your system and applications)
1764with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
1765system.
1766
d6baa268
JH
1767=item GNU binutils
1768
1769If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
1770tools you may be in for some trouble. For example creating archives
1771with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
1772may lead into linking problems. Either recompile your GNU binutils
1773under your current operating system release, or modify your PATH not
1774to include the GNU utils before running Configure, or specify the
1775vendor-supplied utilities explicitly to Configure, for example by
1776Configure -Dar=/bin/ar.
1777
16dc217a
GS
1778=item THIS PACKAGE SEEMS TO BE INCOMPLETE
1779
1780The F<Configure> program has not been able to find all the files which
1781make up the complete Perl distribution. You may have a damaged source
1782archive file (in which case you may also have seen messages such as
1783C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on
1784archive file>), or you may have obtained a structurally-sound but
1785incomplete archive. In either case, try downloading again from the
1786official site named at the start of this document. If you do find
1787that any site is carrying a corrupted or incomplete source code
1788archive, please report it to the site's maintainer.
1789
16dc217a
GS
1790=item invalid token: ##
1791
1792You are using a non-ANSI-compliant C compiler. See L<WARNING: This
1793version requires a compiler that supports ANSI C>.
1794
1ec51d55 1795=item Miscellaneous
8e07c86e
AD
1796
1797Some additional things that have been reported for either perl4 or perl5:
1798
1799Genix may need to use libc rather than libc_s, or #undef VARARGS.
1800
1801NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
1802
9ede5bc8 1803UTS may need one or more of -K or -g, and undef LSTAT.
8e07c86e 1804
11906ba0 1805FreeBSD can fail the ext/IPC/SysV/t/sem.t test if SysV IPC has not been
5cda700b 1806configured in the kernel. Perl tries to detect this, though, and
220f3621 1807you will get a message telling what to do.
6087ac44 1808
d6baa268
JH
1809HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
1810Patch Bundle" has been reported to break the io/fs test #18 which
1811tests whether utime() can change timestamps. The Y2K patch seems to
1812break utime() so that over NFS the timestamps do not get changed
1813(on local filesystems utime() still works).
1814
6c8d78fb
HS
1815Building Perl on a system that has also BIND (headers and libraries)
1816installed may run into troubles because BIND installs its own netdb.h
1817and socket.h, which may not agree with the operating system's ideas of
1818the same files. Similarly, including -lbind may conflict with libc's
1819view of the world. You may have to tweak -Dlocincpth and -Dloclibpth
1820to avoid the BIND.
1821
8e07c86e
AD
1822=back
1823
58a21a9b
JH
1824=head2 Cross-compilation
1825
1826Starting from Perl 5.8 Perl has the beginnings of cross-compilation
1827support. What is known to work is running Configure in a
1828cross-compilation environment and building the miniperl executable.
65090350 1829What is known not to work is building the perl executable because
58a21a9b
JH
1830that would require building extensions: Dynaloader statically and
1831File::Glob dynamically, for extensions one needs MakeMaker and
1832MakeMaker is not yet cross-compilation aware, and neither is
1833the main Makefile.
1834
93bc48fa
JH
1835Since the functionality is so lacking, it must be considered
1836highly experimental. It is so experimental that it is not even
c80c8d62 1837mentioned during an interactive Configure session, a direct command
93bc48fa
JH
1838line invocation (detailed shortly) is required to access the
1839functionality.
1840
58a21a9b 1841 NOTE: Perl is routinely built using cross-compilation
6a809565
JH
1842 in the EPOC environment, in the WinCE, and in the OpenZaurus
1843 project, but all those use something slightly different setup
1844 than what described here. For the WinCE setup, read the
1845 wince/README.compile. For the OpenZaurus setup, read the
1846 Cross/README.
1847
1848The one environment where this cross-compilation setup has
1849successfully been used as of this writing is the Compaq iPAQ running
1850ARM Linux. The build host was Intel Linux, the networking setup was
1851PPP + SSH. The exact setup details are beyond the scope of this
1852document, see http://www.handhelds.org/ for more information.
58a21a9b
JH
1853
1854To run Configure in cross-compilation mode the basic switch is
1855C<-Dusecrosscompile>.
1856
1857 sh ./Configure -des -Dusecrosscompile -D...
1858
1859This will make the cpp symbol USE_CROSS_COMPILE and the %Config
1860symbol C<usecrosscompile> available.
1861
1862During the Configure and build, certain helper scripts will be created
1863into the Cross/ subdirectory. The scripts are used to execute a
1864cross-compiled executable, and to transfer files to and from the
1865target host. The execution scripts are named F<run-*> and the
1866transfer scripts F<to-*> and F<from-*>. The part after the dash is
1867the method to use for remote execution and transfer: by default the
1868methods are B<ssh> and B<scp>, thus making the scripts F<run-ssh>,
1869F<to-scp>, and F<from-scp>.
1870
1871To configure the scripts for a target host and a directory (in which
1872the execution will happen and which is to and from where the transfer
1873happens), supply Configure with
1874
1875 -Dtargethost=so.me.ho.st -Dtargetdir=/tar/get/dir
1876
1877The targethost is what e.g. ssh will use as the hostname, the targetdir
93bc48fa
JH
1878must exist (the scripts won't create it), the targetdir defaults to /tmp.
1879You can also specify a username to use for ssh/rsh logins
58a21a9b
JH
1880
1881 -Dtargetuser=luser
1882
1883but in case you don't, "root" will be used.
1884
93bc48fa
JH
1885Because this is a cross-compilation effort, you will also need to specify
1886which target environment and which compilation environment to use.
1887This includes the compiler, the header files, and the libraries.
1888In the below we use the usual settings for the iPAQ cross-compilation
1889environment:
58a21a9b
JH
1890
1891 -Dtargetarch=arm-linux
1892 -Dcc=arm-linux-gcc
1893 -Dusrinc=/skiff/local/arm-linux/include
1894 -Dincpth=/skiff/local/arm-linux/include
1895 -Dlibpth=/skiff/local/arm-linux/lib
1896
1897If the name of the C<cc> has the usual GNU C semantics for cross
1898compilers, that is, CPU-OS-gcc, the names of the C<ar>, C<nm>, and
1899C<ranlib> will also be automatically chosen to be CPU-OS-ar and so on.
93bc48fa
JH
1900(The C<ld> requires more thought and will be chosen later by Configure
1901as appropriate.) Also, in this case the incpth, libpth, and usrinc
1902will be guessed by Configure (unless explicitly set to something else,
1903in which case Configure's guesses with be appended).
58a21a9b
JH
1904
1905In addition to the default execution/transfer methods you can also
1906choose B<rsh> for execution, and B<rcp> or B<cp> for transfer,
1907for example:
1908
1909 -Dtargetrun=rsh -Dtargetto=rcp -Dtargetfrom=cp
1910
1911Putting it all together:
1912
1913 sh ./Configure -des -Dusecrosscompile \
93bc48fa
JH
1914 -Dtargethost=so.me.ho.st \
1915 -Dtargetdir=/tar/get/dir \
58a21a9b
JH
1916 -Dtargetuser=root \
1917 -Dtargetarch=arm-linux \
1918 -Dcc=arm-linux-gcc \
1919 -Dusrinc=/skiff/local/arm-linux/include \
1920 -Dincpth=/skiff/local/arm-linux/include \
1921 -Dlibpth=/skiff/local/arm-linux/lib \
1922 -D...
1923
93bc48fa
JH
1924or if you are happy with the defaults
1925
1926 sh ./Configure -des -Dusecrosscompile \
1927 -Dtargethost=so.me.ho.st \
1928 -Dcc=arm-linux-gcc \
1929 -D...
1930
8e07c86e
AD
1931=head1 make test
1932
d6baa268
JH
1933This will run the regression tests on the perl you just made. If
1934'make test' doesn't say "All tests successful" then something went
1935wrong. See the file t/README in the t subdirectory.
84902520 1936
84902520 1937Note that you can't run the tests in background if this disables
fb73857a
PP
1938opening of /dev/tty. You can use 'make test-notty' in that case but
1939a few tty tests will be skipped.
c3edaffb 1940
c4f23d77
AD
1941=head2 What if make test doesn't work?
1942
1ec51d55
CS
1943If make test bombs out, just cd to the t directory and run ./TEST
1944by hand to see if it makes any difference. If individual tests
c3edaffb 1945bomb, you can run them by hand, e.g.,
8e07c86e
AD
1946
1947 ./perl op/groups.t
1948
aa689395 1949Another way to get more detailed information about failed tests and
1ec51d55 1950individual subtests is to cd to the t directory and run
aa689395
PP
1951
1952 ./perl harness
1953
fb73857a 1954(this assumes that most basic tests succeed, since harness uses
10c7e831
JH
1955complicated constructs). For extension and library tests you
1956need a little bit more: you need to setup your environment variable
1957PERL_CORE to a true value (like "1"), and you need to supply the
1958right Perl library path:
1959
1960 setenv PERL_CORE 1
1961 ./perl -I../lib ../ext/Socket/Socket.t
1962 ./perl -I../lib ../lib/less.t
aa689395 1963
5cda700b 1964(For csh-like shells on UNIX; adjust appropriately for other platforms.)
fb73857a 1965You should also read the individual tests to see if there are any helpful
10c7e831
JH
1966comments that apply to your system. You may also need to setup your
1967shared library path if you get errors like:
1968
1969 /sbin/loader: Fatal Error: cannot map libperl.so
1970
1971See L</"Building a shared Perl library"> earlier in this document.
c3edaffb 1972
c4f23d77
AD
1973=over 4
1974
1975=item locale
1976
1ec51d55 1977Note: One possible reason for errors is that some external programs
c07a80fd 1978may be broken due to the combination of your environment and the way
3fe9a6f1 1979B<make test> exercises them. For example, this may happen if you have
1ec51d55
CS
1980one or more of these environment variables set: LC_ALL LC_CTYPE
1981LC_COLLATE LANG. In some versions of UNIX, the non-English locales
e57fd563
PP
1982are known to cause programs to exhibit mysterious errors.
1983
1984If you have any of the above environment variables set, please try
aa689395
PP
1985
1986 setenv LC_ALL C
1987
1988(for C shell) or
1989
1990 LC_ALL=C;export LC_ALL
1991
1ec51d55
CS
1992for Bourne or Korn shell) from the command line and then retry
1993make test. If the tests then succeed, you may have a broken program that
aa689395 1994is confusing the testing. Please run the troublesome test by hand as
e57fd563 1995shown above and see whether you can locate the program. Look for
1ec51d55
CS
1996things like: exec, `backquoted command`, system, open("|...") or
1997open("...|"). All these mean that Perl is trying to run some
e57fd563 1998external program.
eed2e782 1999
0740bb5b
AD
2000=item Timing problems
2001
c29923ff
JH
2002Several tests in the test suite check timing functions, such as
2003sleep(), and see if they return in a reasonable amount of time.
9341413f
JH
2004If your system is quite busy and doesn't respond quickly enough,
2005these tests might fail. If possible, try running the tests again
2006with the system under a lighter load. These timing-sensitive
2007and load-sensitive tests include F<t/op/alarm.t>,
2008F<ext/Time/HiRes/HiRes.t>, F<lib/Benchmark.t>,
2009F<lib/Memoize/t/expmod_t.t>, and F<lib/Memoize/t/speed.t>.
0740bb5b 2010
c4f23d77
AD
2011=item Out of memory
2012
2013On some systems, particularly those with smaller amounts of RAM, some
2014of the tests in t/op/pat.t may fail with an "Out of memory" message.
7970f296
GS
2015For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
2016test 85 will fail if run under either t/TEST or t/harness.
c4f23d77
AD
2017
2018Try stopping other jobs on the system and then running the test by itself:
2019
2020 cd t; ./perl op/pat.t
2021
2022to see if you have any better luck. If your perl still fails this
2023test, it does not necessarily mean you have a broken perl. This test
2024tries to exercise the regular expression subsystem quite thoroughly,
2025and may well be far more demanding than your normal usage.
2026
4f76e5ba
AD
2027=item Failures from lib/File/Temp/t/security saying "system possibly insecure"
2028
2029First, such warnings are not necessarily serious or indicative of a
2030real security threat. That being said, they bear investigating.
2031
2032Note that each of the tests is run twice. The first time is in the
2033directory returned by File::Spec->tmpdir() (often /tmp on Unix
2034systems), and the second time in the directory from which the test was
2035run (usually the 't' directory, if the test was run as part of 'make
2036test').
2037
2038The tests may fail for the following reasons:
2039
2040(1) If the directory the tests are being run in is owned by somebody
2041other than the user running the tests, or by root (uid 0).
2042
2043This failure can happen if the Perl source code distribution is
2044unpacked in such a way that the user ids in the distribution package
2045are used as-is. Some tar programs do this.
2046
2047(2) If the directory the tests are being run in is writable by group or
2048by others, and there is no sticky bit set for the directory. (With
2049UNIX/POSIX semantics, write access to a directory means the right to
2050add or remove files in that directory. The 'sticky bit' is a feature
2051used in some UNIXes to give extra protection to files: if the bit is
2052set for a directory, no one but the owner (or root) can remove that
2053file even if the permissions would otherwise allow file removal by
2054others.)
2055
2056This failure may or may not be a real problem: it depends on the
2057permissions policy used on this particular system. This failure can
2058also happen if the system either doesn't support the sticky bit (this
2059is the case with many non-UNIX platforms: in principle File::Temp
2060should know about these platforms and skip the tests), or if the system
2061supports the sticky bit but for some reason or reasons it is not being
2062used. This is, for example, the case with HP-UX: as of HP-UX release
206311.00, the sticky bit is very much supported, but HP-UX doesn't use it
2064on its /tmp directory as shipped. Also, as with the permissions, some
2065local policy might dictate that the stickiness is not used.
781948c1 2066
b2b23189
JH
2067(3) If the system supports the POSIX 'chown giveaway' feature and if
2068any of the parent directories of the temporary file back to the root
2069directory are 'unsafe', using the definitions given above in (1) and
4f76e5ba
AD
2070(2). For Unix systems, this is usually not an issue if you are
2071building on a local disk. See the documentation for the File::Temp
2072module for more information about 'chown giveaway'.
781948c1
JH
2073
2074See the documentation for the File::Temp module for more information
4f76e5ba 2075about the various security aspects of temporary files.
781948c1 2076
c4f23d77
AD
2077=back
2078
8e07c86e
AD
2079=head1 make install
2080
2081This will put perl into the public directory you specified to
1ec51d55 2082Configure; by default this is /usr/local/bin. It will also try
8e07c86e 2083to put the man pages in a reasonable place. It will not nroff the man
aa689395 2084pages, however. You may need to be root to run B<make install>. If you
8e07c86e
AD
2085are not root, you must own the directories in question and you should
2086ignore any messages about chown not working.
2087
dd64f1c3
AD
2088=head2 Installing perl under different names
2089
2090If you want to install perl under a name other than "perl" (for example,
2091when installing perl with special features enabled, such as debugging),
2092indicate the alternate name on the "make install" line, such as:
2093
2094 make install PERLNAME=myperl
2095
beb13193
RS
2096You can separately change the base used for versioned names (like
2097"perl5.005") by setting PERLNAME_VERBASE, like
2098
2099 make install PERLNAME=perl5 PERLNAME_VERBASE=perl
2100
5cda700b
AD
2101This can be useful if you have to install perl as "perl5" (e.g. to
2102avoid conflicts with an ancient version in /usr/bin supplied by your vendor).
2103Without this the versioned binary would be called "perl55.005".
beb13193 2104
dd64f1c3
AD
2105=head2 Installed files
2106
8e07c86e
AD
2107If you want to see exactly what will happen without installing
2108anything, you can run
4633a7c4 2109
8e07c86e
AD
2110 ./perl installperl -n
2111 ./perl installman -n
2112
1ec51d55 2113make install will install the following:
8e07c86e 2114
d56c5707
JH
2115 binaries
2116
8e07c86e
AD
2117 perl,
2118 perl5.nnn where nnn is the current release number. This
2119 will be a link to perl.
2120 suidperl,
2121 sperl5.nnn If you requested setuid emulation.
2122 a2p awk-to-perl translator
d56c5707
JH
2123
2124 scripts
2125
8e07c86e
AD
2126 cppstdin This is used by perl -P, if your cc -E can't
2127 read from stdin.
2128 c2ph, pstruct Scripts for handling C structures in header files.
2129 s2p sed-to-perl translator
2130 find2perl find-to-perl translator
aa689395 2131 h2ph Extract constants and simple macros from C headers
8e07c86e 2132 h2xs Converts C .h header files to Perl extensions.
24b3df7f 2133 perlbug Tool to report bugs in Perl.
8e07c86e 2134 perldoc Tool to read perl's pod documentation.
aa689395 2135 pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules
8e07c86e 2136 pod2html, Converters from perl's pod documentation format
aa689395 2137 pod2latex, to other useful formats.
d56c5707
JH
2138 pod2man,
2139 pod2text,
2140 pod2checker,
2141 pod2select,
2142 pod2usage
aa689395 2143 splain Describe Perl warnings and errors
95667ae4 2144 dprofpp Perl code profile post-processor
8e07c86e 2145
d56c5707
JH
2146 library files
2147
2148 in $privlib and $archlib specified to
8e07c86e 2149 Configure, usually under /usr/local/lib/perl5/.
d56c5707
JH
2150
2151 documentation
2152
d6baa268
JH
2153 man pages in $man1dir, usually /usr/local/man/man1.
2154 module man
2155 pages in $man3dir, usually /usr/local/man/man3.
8e07c86e
AD
2156 pod/*.pod in $privlib/pod/.
2157
d6baa268
JH
2158Installperl will also create the directories listed above
2159in L<"Installation Directories">.
4633a7c4 2160
d56c5707 2161Perl's *.h header files and the libperl library are also installed
d6baa268 2162under $archlib so that any user may later build new modules, run the
56c6f531
JH
2163optional Perl compiler, or embed the perl interpreter into another
2164program even if the Perl source is no longer available.
8e07c86e 2165
d56c5707
JH
2166Sometimes you only want to install the version-specific parts of the perl
2167installation. For example, you may wish to install a newer version of
2168perl alongside an already installed production version of perl without
2169disabling installation of new modules for the production version.
2170To only install the version-specific parts of the perl installation, run
2171
2172 Configure -Dversiononly
2173
2174or answer 'y' to the appropriate Configure prompt. Alternatively,
2175you can just manually run
2176
2177 ./perl installperl -v
2178
2179and skip installman altogether.
2180See also L<"Maintaining completely separate versions"> for another
2181approach.
2182
aa689395 2183=head1 Coexistence with earlier versions of perl5
4633a7c4 2184
14eee2f1 2185Perl 5.8 is not binary compatible with earlier versions of Perl.
cc65bb49 2186In other words, you will have to recompile your XS modules.
14eee2f1 2187
693762b4
AD
2188In general, you can usually safely upgrade from one version of Perl (e.g.
21895.004_04) to another similar version (e.g. 5.004_05) without re-compiling
2190all of your add-on extensions. You can also safely leave the old version
2191around in case the new version causes you problems for some reason.
2192For example, if you want to be sure that your script continues to run
dc45a647 2193with 5.004_04, simply replace the '#!/usr/local/bin/perl' line at the
693762b4
AD
2194top of the script with the particular version you want to run, e.g.
2195#!/usr/local/bin/perl5.00404.
2196
e655887d
CB
2197Usually, most extensions will probably not need to be recompiled to
2198use with a newer version of Perl (the Perl 5.6 to Perl 5.8 transition
2199being an exception). Here is how it is supposed to work. (These
2200examples assume you accept all the Configure defaults.)
693762b4 2201
d6baa268
JH
2202Suppose you already have version 5.005_03 installed. The directories
2203searched by 5.005_03 are
2204
2205 /usr/local/lib/perl5/5.00503/$archname
2206 /usr/local/lib/perl5/5.00503
2207 /usr/local/lib/perl5/site_perl/5.005/$archname
2208 /usr/local/lib/perl5/site_perl/5.005
2209
0a08c020
GS
2210Beginning with 5.6.0 the version number in the site libraries are
2211fully versioned. Now, suppose you install version 5.6.0. The directories
2212searched by version 5.6.0 will be
d6baa268 2213
0a08c020
GS
2214 /usr/local/lib/perl5/5.6.0/$archname
2215 /usr/local/lib/perl5/5.6.0
2216 /usr/local/lib/perl5/site_perl/5.6.0/$archname
2217 /usr/local/lib/perl5/site_perl/5.6.0
d6baa268
JH
2218
2219 /usr/local/lib/perl5/site_perl/5.005/$archname
2220 /usr/local/lib/perl5/site_perl/5.005
c42e3e15 2221 /usr/local/lib/perl5/site_perl/
bfb7748a 2222
c42e3e15 2223Notice the last three entries -- Perl understands the default structure
d6baa268
JH
2224of the $sitelib directories and will look back in older, compatible
2225directories. This way, modules installed under 5.005_03 will continue
0a08c020 2226to be usable by 5.005_03 but will also accessible to 5.6.0. Further,
d6baa268 2227suppose that you upgrade a module to one which requires features
0a08c020
GS
2228present only in 5.6.0. That new module will get installed into
2229/usr/local/lib/perl5/site_perl/5.6.0 and will be available to 5.6.0,
d6baa268 2230but will not interfere with the 5.005_03 version.
bfb7748a 2231
c42e3e15 2232The last entry, /usr/local/lib/perl5/site_perl/, is there so that
fe23a901 22335.6.0 and above will look for 5.004-era pure perl modules.
d6baa268 2234
cc65bb49
AD
2235Lastly, suppose you now install 5.8.0, which is not binary compatible
2236with 5.6.0. The directories searched by 5.8.0 (if you don't change the
fe23a901
RF
2237Configure defaults) will be:
2238
2239 /usr/local/lib/perl5/5.8.0/$archname
2240 /usr/local/lib/perl5/5.8.0
2241 /usr/local/lib/perl5/site_perl/5.8.0/$archname
2242 /usr/local/lib/perl5/site_perl/5.8.0
d6baa268 2243
0a08c020 2244 /usr/local/lib/perl5/site_perl/5.6.0
d6baa268 2245
d6baa268 2246 /usr/local/lib/perl5/site_perl/5.005
fe23a901 2247
d6baa268 2248 /usr/local/lib/perl5/site_perl/
bfb7748a 2249
cc65bb49
AD
2250Note that the earlier $archname entries are now gone, but pure perl
2251modules from earlier versions will still be found.
2252
0a08c020 2253Assuming the users in your site are still actively using perl 5.6.0 and
fe23a901 22545.005 after you installed 5.8.0, you can continue to install add-on
cc65bb49
AD
2255extensions using any of perl 5.8.0, 5.6.0, or 5.005. The installations
2256of these different versions remain distinct, but remember that the
2257newer versions of perl are automatically set up to search the
2258compatible site libraries of the older ones. This means that
2259installing a new XS extension with 5.005 will make it visible to both
22605.005 and 5.6.0, but not to 5.8.0. Installing a pure perl module with
22615.005 will make it visible to all three versions. Later, if you
2262install the same extension using, say, perl 5.8.0, it will override the
22635.005-installed version, but only for perl 5.8.0.
0a08c020
GS
2264
2265This way, you can choose to share compatible extensions, but also upgrade
2266to a newer version of an extension that may be incompatible with earlier
2267versions, without breaking the earlier versions' installations.
693762b4
AD
2268
2269=head2 Maintaining completely separate versions
4633a7c4 2270
1ec51d55 2271Many users prefer to keep all versions of perl in completely
d6baa268 2272separate directories. This guarantees that an update to one version
0a08c020
GS
2273won't interfere with another version. (The defaults guarantee this for
2274libraries after 5.6.0, but not for executables. TODO?) One convenient
2275way to do this is by using a separate prefix for each version, such as
d52d4e46 2276
46bb10fb 2277 sh Configure -Dprefix=/opt/perl5.004
d52d4e46 2278
46bb10fb 2279and adding /opt/perl5.004/bin to the shell PATH variable. Such users
d52d4e46
PP
2280may also wish to add a symbolic link /usr/local/bin/perl so that
2281scripts can still start with #!/usr/local/bin/perl.
2282
693762b4 2283Others might share a common directory for maintenance sub-versions
cc65bb49 2284(e.g. 5.8 for all 5.8.x versions), but change directory with
693762b4
AD
2285each major version.
2286
6877a1cf
AD
2287If you are installing a development subversion, you probably ought to
2288seriously consider using a separate directory, since development
2289subversions may not have all the compatibility wrinkles ironed out
2290yet.
2291
e655887d 2292=head2 Upgrading from 5.005 or 5.6 to 5.8.0
693762b4 2293
e655887d
CB
2294B<Perl 5.8.0 is binary incompatible with Perl 5.6.1, 5.6.0, 5.005,
2295and any earlier Perl release.> Perl modules having binary parts
2296(meaning that a C compiler is used) will have to be recompiled to be
2297used with 5.8.0. If you find you do need to rebuild an extension with
22985.8.0, you may safely do so without disturbing the 5.005 or 5.6.0
2299installations. (See L<"Coexistence with earlier versions of perl5">
2300above.)
c42e3e15
GS
2301
2302See your installed copy of the perllocal.pod file for a (possibly
2303incomplete) list of locally installed modules. Note that you want
cc65bb49 2304perllocal.pod, not perllocale.pod, for installed module information.
693762b4 2305
8e07c86e
AD
2306=head1 Coexistence with perl4
2307
2308You can safely install perl5 even if you want to keep perl4 around.
2309
1ec51d55
CS
2310By default, the perl5 libraries go into /usr/local/lib/perl5/, so
2311they don't override the perl4 libraries in /usr/local/lib/perl/.
8e07c86e
AD
2312
2313In your /usr/local/bin directory, you should have a binary named
1ec51d55 2314perl4.036. That will not be touched by the perl5 installation
8e07c86e
AD
2315process. Most perl4 scripts should run just fine under perl5.
2316However, if you have any scripts that require perl4, you can replace
d6baa268
JH
2317the #! line at the top of them by #!/usr/local/bin/perl4.036 (or
2318whatever the appropriate pathname is). See pod/perltrap.pod for
2319possible problems running perl4 scripts under perl5.
8e07c86e 2320
aa689395
PP
2321=head1 cd /usr/include; h2ph *.h sys/*.h
2322
d6baa268
JH
2323Some perl scripts need to be able to obtain information from the
2324system header files. This command will convert the most commonly used
1ec51d55 2325header files in /usr/include into files that can be easily interpreted
d6baa268
JH
2326by perl. These files will be placed in the architecture-dependent
2327library ($archlib) directory you specified to Configure.
aa689395 2328
d6baa268
JH
2329Note: Due to differences in the C and perl languages, the conversion
2330of the header files is not perfect. You will probably have to
2331hand-edit some of the converted files to get them to parse correctly.
2332For example, h2ph breaks spectacularly on type casting and certain
2333structures.
aa689395 2334
fb73857a 2335=head1 installhtml --help
aa689395 2336
3e3baf6d
TB
2337Some sites may wish to make perl documentation available in HTML
2338format. The installhtml utility can be used to convert pod
fb73857a 2339documentation into linked HTML files and install them.
aa689395 2340
d6baa268
JH
2341Currently, the supplied ./installhtml script does not make use of the
2342html Configure variables. This should be fixed in a future release.
2343
fb73857a 2344The following command-line is an example of one used to convert
3e3baf6d 2345perl documentation:
aa689395 2346
3e3baf6d
TB
2347 ./installhtml \
2348 --podroot=. \
2349 --podpath=lib:ext:pod:vms \
2350 --recurse \
2351 --htmldir=/perl/nmanual \
2352 --htmlroot=/perl/nmanual \
2353 --splithead=pod/perlipc \
2354 --splititem=pod/perlfunc \
2355 --libpods=perlfunc:perlguts:perlvar:perlrun:perlop \
2356 --verbose
2357
2358See the documentation in installhtml for more details. It can take
2359many minutes to execute a large installation and you should expect to
2360see warnings like "no title", "unexpected directive" and "cannot
2361resolve" as the files are processed. We are aware of these problems
2362(and would welcome patches for them).
aa689395 2363
fb73857a
PP
2364You may find it helpful to run installhtml twice. That should reduce
2365the number of "cannot resolve" warnings.
2366
aa689395
PP
2367=head1 cd pod && make tex && (process the latex files)
2368
2369Some sites may also wish to make the documentation in the pod/ directory
2370available in TeX format. Type
2371
2372 (cd pod && make tex && <process the latex files>)
2373
8ebf57cf
JH
2374=head1 Minimizing the Perl installation
2375
2376The following section is meant for people worrying about squeezing the
2377Perl installation into minimal systems (for example when installing
2378operating systems, or in really small filesystems).
2379
c8214fdf 2380Leaving out as many extensions as possible is an obvious way:
5cda700b
AD
2381Encode, with its big conversion tables, consumes a lot of
2382space. On the other hand, you cannot throw away everything. The
2383Fcntl module is pretty essential. If you need to do network
c8214fdf
JH
2384programming, you'll appreciate the Socket module, and so forth: it all
2385depends on what do you need to do.
2386
8ebf57cf
JH
2387In the following we offer two different slimmed down installation
2388recipes. They are informative, not normative: the choice of files
2389depends on what you need.
2390
2391Firstly, the bare minimum to run this script
2392
2393 use strict;
2394 use warnings;
2395 foreach my $f (</*>) {
2396 print("$f\n");
2397 }
2398
2399in Solaris is as follows (under $Config{prefix}):
2400
2401 ./bin/perl
2402 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/autosplit.ix
2403 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_expandspec.al
2404 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_find_symbol_anywhere.al
2405 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_findfile.al
2406 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/Glob.so
2407 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/autosplit.ix
2408 ./lib/perl5/5.6.1/sun4-solaris-64int/Config.pm
2409 ./lib/perl5/5.6.1/sun4-solaris-64int/XSLoader.pm
2410 ./lib/perl5/5.6.1/sun4-solaris-64int/DynaLoader.pm
2411 ./lib/perl5/5.6.1/sun4-solaris-64int/CORE/libperl.so
2412 ./lib/perl5/5.6.1/strict.pm
2413 ./lib/perl5/5.6.1/warnings.pm
2414 ./lib/perl5/5.6.1/Carp.pm
2415 ./lib/perl5/5.6.1/Exporter.pm
2416 ./lib/perl5/5.6.1/File/Glob.pm
2417 ./lib/perl5/5.6.1/AutoLoader.pm
2418 ./lib/perl5/5.6.1/vars.pm
2419 ./lib/perl5/5.6.1/warnings/register.pm
2420 ./lib/perl5/5.6.1/Carp/Heavy.pm
2421 ./lib/perl5/5.6.1/Exporter/Heavy.pm
2422
2423Secondly, Debian perl-base package contains the following files,
2424size about 1.2MB in its i386 version:
2425
2426 /usr/share/doc/perl/Documentation
2427 /usr/share/doc/perl/README.Debian
2428 /usr/share/doc/perl/copyright
2429 /usr/share/doc/perl/AUTHORS.gz
2430 /usr/share/doc/perl/changelog.Debian.gz
2431 /usr/share/man/man1/perl.1.gz
2432 /usr/share/perl/5.6.1/AutoLoader.pm
2433 /usr/share/perl/5.6.1/Carp.pm
2434 /usr/share/perl/5.6.1/Carp/Heavy.pm
2435 /usr/share/perl/5.6.1/Cwd.pm
2436 /usr/share/perl/5.6.1/Exporter.pm
2437 /usr/share/perl/5.6.1/Exporter/Heavy.pm
2438 /usr/share/perl/5.6.1/File/Spec.pm
2439 /usr/share/perl/5.6.1/File/Spec/Unix.pm
2440 /usr/share/perl/5.6.1/FileHandle.pm
2441 /usr/share/perl/5.6.1/Getopt/Long.pm
2442 /usr/share/perl/5.6.1/IO/Socket/INET.pm
2443 /usr/share/perl/5.6.1/IO/Socket/UNIX.pm
2444 /usr/share/perl/5.6.1/IPC/Open2.pm
2445 /usr/share/perl/5.6.1/IPC/Open3.pm
2446 /usr/share/perl/5.6.1/SelectSaver.pm
2447 /usr/share/perl/5.6.1/Symbol.pm
2448 /usr/share/perl/5.6.1/Text/Tabs.pm
2449 /usr/share/perl/5.6.1/Text/Wrap.pm
2450 /usr/share/perl/5.6.1/attributes.pm
2451 /usr/share/perl/5.6.1/auto/Getopt/Long/GetOptions.al
2452 /usr/share/perl/5.6.1/auto/Getopt/Long/FindOption.al
2453 /usr/share/perl/5.6.1/auto/Getopt/Long/Configure.al
2454 /usr/share/perl/5.6.1/auto/Getopt/Long/config.al
2455 /usr/share/perl/5.6.1/auto/Getopt/Long/Croak.al
2456 /usr/share/perl/5.6.1/auto/Getopt/Long/autosplit.ix
2457 /usr/share/perl/5.6.1/base.pm
2458 /usr/share/perl/5.6.1/constant.pm
2459 /usr/share/perl/5.6.1/fields.pm
2460 /usr/share/perl/5.6.1/integer.pm
2461 /usr/share/perl/5.6.1/lib.pm
2462 /usr/share/perl/5.6.1/locale.pm
2463 /usr/share/perl/5.6.1/overload.pm
2464 /usr/share/perl/5.6.1/strict.pm
2465 /usr/share/perl/5.6.1/vars.pm
2466 /usr/share/perl/5.6.1/warnings.pm
2467 /usr/share/perl/5.6.1/warnings/register.pm
2468 /usr/bin/perl
2469 /usr/lib/perl/5.6.1/Config.pm
2470 /usr/lib/perl/5.6.1/Data/Dumper.pm
2471 /usr/lib/perl/5.6.1/DynaLoader.pm
2472 /usr/lib/perl/5.6.1/Errno.pm
2473 /usr/lib/perl/5.6.1/Fcntl.pm
2474 /usr/lib/perl/5.6.1/File/Glob.pm
2475 /usr/lib/perl/5.6.1/IO.pm
2476 /usr/lib/perl/5.6.1/IO/File.pm
2477 /usr/lib/perl/5.6.1/IO/Handle.pm
2478 /usr/lib/perl/5.6.1/IO/Pipe.pm
2479 /usr/lib/perl/5.6.1/IO/Seekable.pm
2480 /usr/lib/perl/5.6.1/IO/Select.pm
2481 /usr/lib/perl/5.6.1/IO/Socket.pm
2482 /usr/lib/perl/5.6.1/POSIX.pm
2483 /usr/lib/perl/5.6.1/Socket.pm
2484 /usr/lib/perl/5.6.1/XSLoader.pm
2485 /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.so
2486 /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.bs
2487 /usr/lib/perl/5.6.1/auto/DynaLoader/dl_findfile.al
2488 /usr/lib/perl/5.6.1/auto/DynaLoader/dl_expandspec.al
2489 /usr/lib/perl/5.6.1/auto/DynaLoader/dl_find_symbol_anywhere.al
2490 /usr/lib/perl/5.6.1/auto/DynaLoader/autosplit.ix
2491 /usr/lib/perl/5.6.1/auto/DynaLoader/DynaLoader.a
2492 /usr/lib/perl/5.6.1/auto/DynaLoader/extralibs.ld
2493 /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.so
2494 /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.bs
2495 /usr/lib/perl/5.6.1/auto/File/Glob/Glob.bs
2496 /usr/lib/perl/5.6.1/auto/File/Glob/Glob.so
2497 /usr/lib/perl/5.6.1/auto/File/Glob/autosplit.ix
2498 /usr/lib/perl/5.6.1/auto/IO/IO.so
2499 /usr/lib/perl/5.6.1/auto/IO/IO.bs
2500 /usr/lib/perl/5.6.1/auto/POSIX/POSIX.bs
2501 /usr/lib/perl/5.6.1/auto/POSIX/POSIX.so
2502 /usr/lib/perl/5.6.1/auto/POSIX/autosplit.ix
2503 /usr/lib/perl/5.6.1/auto/POSIX/load_imports.al
2504 /usr/lib/perl/5.6.1/auto/Socket/Socket.so
2505 /usr/lib/perl/5.6.1/auto/Socket/Socket.bs
2506
aa689395
PP
2507=head1 Reporting Problems
2508
bfb7748a
AD
2509If you have difficulty building perl, and none of the advice in this file
2510helps, and careful reading of the error message and the relevant manual
2511pages on your system doesn't help either, then you should send a message
7f2de2d2 2512to either the comp.lang.perl.misc newsgroup or to perlbug@perl.org with
bfb7748a 2513an accurate description of your problem.
aa689395 2514
bfb7748a
AD
2515Please include the output of the ./myconfig shell script that comes with
2516the distribution. Alternatively, you can use the perlbug program that
2517comes with the perl distribution, but you need to have perl compiled
2518before you can use it. (If you have not installed it yet, you need to
f5b3b617 2519run C<./perl -Ilib utils/perlbug> instead of a plain C<perlbug>.)
aa689395 2520
694a7e45
AD
2521Please try to make your message brief but clear. Trim out unnecessary
2522information. Do not include large files (such as config.sh or a complete
2523Configure or make log) unless absolutely necessary. Do not include a
2524complete transcript of your build session. Just include the failing
d6baa268 2525commands, the relevant error messages, and whatever preceding commands
694a7e45
AD
2526are necessary to give the appropriate context. Plain text should
2527usually be sufficient--fancy attachments or encodings may actually
2528reduce the number of people who read your message. Your message
2529will get relayed to over 400 subscribers around the world so please
2530try to keep it brief but clear.
aa689395 2531
8e07c86e
AD
2532=head1 DOCUMENTATION
2533
bfb7748a
AD
2534Read the manual entries before running perl. The main documentation
2535is in the pod/ subdirectory and should have been installed during the
8e07c86e 2536build process. Type B<man perl> to get started. Alternatively, you
bfb7748a
AD
2537can type B<perldoc perl> to use the supplied perldoc script. This is
2538sometimes useful for finding things in the library modules.
8e07c86e 2539
1ec51d55 2540Under UNIX, you can produce a documentation book in postscript form,
bfb7748a
AD
2541along with its table of contents, by going to the pod/ subdirectory and
2542running (either):
34a2a22e
RM
2543
2544 ./roffitall -groff # If you have GNU groff installed
aa689395 2545 ./roffitall -psroff # If you have psroff
34a2a22e
RM
2546
2547This will leave you with two postscript files ready to be printed.
aa689395
PP
2548(You may need to fix the roffitall command to use your local troff
2549set-up.)
34a2a22e 2550
bfb7748a
AD
2551Note that you must have performed the installation already before running
2552the above, since the script collects the installed files to generate
2553the documentation.
34a2a22e 2554
8e07c86e
AD
2555=head1 AUTHOR
2556
bfb7748a
AD
2557Original author: Andy Dougherty doughera@lafayette.edu , borrowing very
2558heavily from the original README by Larry Wall, with lots of helpful
2559feedback and additions from the perl5-porters@perl.org folks.
fb73857a 2560
f5b3b617
AD
2561If you have problems, corrections, or questions, please see
2562L<"Reporting Problems"> above.
2563
2564=head1 REDISTRIBUTION
2565
2566This document is part of the Perl package and may be distributed under
d6baa268 2567the same terms as perl itself, with the following additional request:
f5b3b617 2568If you are distributing a modified version of perl (perhaps as part of
d6baa268
JH
2569a larger package) please B<do> modify these installation instructions
2570and the contact information to match your distribution.