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