This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: [ID 20010514.022] Makemaker a bit too prefix-happy
[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
b88cc0eb
JH
27B<NOTE>: starting from the release 5.6.0 Perl will use a version
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
77provide additional or different instructions for building Perl.
78
203c3eec
AD
79If there is a hint file for your system (in the hints/ directory) you
80should also read that hint file for specific information for your
694a7e45
AD
81system. (Unixware users should use the svr4.sh hint file.) If
82there is a README file for your platform, then you should read
83that too. Additional information is in the Porting/ directory.
203c3eec 84
c42e3e15
GS
85=head1 WARNING: This version requires an extra step to build old extensions.
86
875.005_53 and later releases do not export unadorned
88global symbols anymore. This means you may need to build older
89extensions that have not been updated for the new naming convention
90with:
91
92 perl Makefile.PL POLLUTE=1
d56c5707 93
c42e3e15
GS
94Alternatively, you can enable CPP symbol pollution wholesale by
95building perl itself with:
96
97 sh Configure -Accflags=-DPERL_POLLUTE
98
99pod/perldelta.pod contains more details about this.
100
1b1c1ae2
GS
101=head1 WARNING: This version may not be binary compatible with Perl 5.005.
102
103Using the default Configure options for building perl should get you
104a perl that will be binary compatible with the 5.005 release.
693762b4 105
1b1c1ae2
GS
106However, if you run Configure with any custom options, such as
107-Dusethreads, -Dusemultiplicity, -Dusemymalloc, -Ubincompat5005 etc.,
108the resulting perl will not be binary compatible. Under these
109circumstances, if you have dynamically loaded extensions that were
110built under perl 5.005, you will need to rebuild and reinstall all
111those extensions to use them with 5.6.
112
113Pure perl modules without XS or C code should continue to work fine
114without reinstallation. See the discussions below on
115L<"Coexistence with earlier versions of perl5"> and
116L<"Upgrading from 5.005 to 5.6"> for more details.
693762b4
AD
117
118The standard extensions supplied with Perl will be handled automatically.
119
1b1c1ae2 120On a related issue, old modules may possibly be affected by the
693762b4 121changes in the Perl language in the current release. Please see
e02fdbd2 122pod/perldelta.pod (and pod/perl500Xdelta.pod) for a description of
c42e3e15 123what's changed. See your installed copy of the perllocal.pod
d6baa268
JH
124file for a (possibly incomplete) list of locally installed modules.
125Also see CPAN::autobundle for one way to make a "bundle" of your
126currently installed modules.
693762b4 127
5effff0b
GS
128=head1 WARNING: This version requires a compiler that supports ANSI C.
129
16dc217a
GS
130Most C compilers are now ANSI-compliant. However, a few current
131computers are delivered with an older C compiler expressly for
132rebuilding the system kernel, or for some other historical reason.
133Alternatively, you may have an old machine which was shipped before
134ANSI compliance became widespread. Such compilers are not suitable
135for building Perl.
136
137If you find that your default C compiler is not ANSI-capable, but you
138know that an ANSI-capable compiler is installed on your system, you
139can tell F<Configure> to use the correct compiler by means of the
140C<-Dcc=> command-line option -- see L<"gcc">.
141
142If do not have an ANSI-capable compiler there are several avenues open
143to you:
144
145=over 4
146
147=item *
148
149You may try obtaining GCC, available from GNU mirrors worldwide,
150listed at <URL:http://www.gnu.org/order/ftp.html>. If, rather than
151building gcc from source code, you locate a binary version configured
152for your platform, be sure that it is compiled for the version of the
153operating system that you are using.
154
155=item *
156
157You may purchase a commercial ANSI C compiler from your system
158supplier or elsewhere. (Or your organization may already have
159licensed such software -- ask your colleagues to find out how to
160access it.) If there is a README file for your system in the Perl
161distribution (for example, F<README.hpux>), it may contain advice on
162suitable compilers.
163
164=item *
165
d6baa268 166Another alternative may be to use a tool like ansi2knr to convert the
5effff0b
GS
167sources back to K&R style, but there is no guarantee this route will get
168you anywhere, since the prototypes are not the only ANSI features used
d6baa268
JH
169in the Perl sources. ansi2knr is usually found as part of the freely
170available Ghostscript distribution. Another similar tool is
171unprotoize, distributed with GCC. Since unprotoize requires GCC to
5effff0b
GS
172run, you may have to run it on a platform where GCC is available, and move
173the sources back to the platform without GCC.
174
175If you succeed in automatically converting the sources to a K&R compatible
7f2de2d2 176form, be sure to email perlbug@perl.org to let us know the steps you
5effff0b
GS
177followed. This will enable us to officially support this option.
178
16dc217a
GS
179=back
180
df41b452
GS
181Although Perl can be compiled using a C++ compiler, the Configure script
182does not work with some C++ compilers.
183
aa689395 184=head1 Space Requirements
eed2e782 185
416d06d2
AD
186The complete perl5 source tree takes up about 35 MB of disk space.
187After completing make, it takes up roughly 50 MB, though the actual
d6baa268 188total is likely to be quite system-dependent. The installation
416d06d2 189directories need something on the order of 30 MB, though again that
1ec51d55 190value is system-dependent.
8e07c86e 191
aa689395 192=head1 Start with a Fresh Distribution
8e07c86e 193
edb1cbcb
PP
194If you have built perl before, you should clean out the build directory
195with the command
196
dc45a647
MB
197 make distclean
198
199or
200
edb1cbcb 201 make realclean
c3edaffb 202
dc45a647
MB
203The only difference between the two is that make distclean also removes
204your old config.sh and Policy.sh files.
205
206The results of a Configure run are stored in the config.sh and Policy.sh
207files. If you are upgrading from a previous version of perl, or if you
208change systems or compilers or make other significant changes, or if
209you are experiencing difficulties building perl, you should probably
d6baa268 210not re-use your old config.sh. Simply remove it
8e07c86e 211
d6baa268 212 rm -f config.sh
4633a7c4 213
e57fd563
PP
214If you wish to use your old config.sh, be especially attentive to the
215version and architecture-specific questions and answers. For example,
216the default directory for architecture-dependent library modules
217includes the version name. By default, Configure will reuse your old
218name (e.g. /opt/perl/lib/i86pc-solaris/5.003) even if you're running
219Configure for a different version, e.g. 5.004. Yes, Configure should
220probably check and correct for this, but it doesn't, presently.
221Similarly, if you used a shared libperl.so (see below) with version
222numbers, you will probably want to adjust them as well.
223
d6baa268
JH
224Also, be careful to check your architecture name. For example, some
225Linux distributions use i386, while others may use i486. If you build
226it yourself, Configure uses the output of the arch command, which
227might be i586 or i686 instead. If you pick up a precompiled binary, or
228compile extensions on different systems, they might not all agree on
229the architecture name.
e57fd563
PP
230
231In short, if you wish to use your old config.sh, I recommend running
232Configure interactively rather than blindly accepting the defaults.
8e07c86e 233
d6baa268
JH
234If your reason to reuse your old config.sh is to save your particular
235installation choices, then you can probably achieve the same effect by
236using the Policy.sh file. See the section on L<"Site-wide Policy
237settings"> below. If you wish to start with a fresh distribution, you
238also need to remove any old Policy.sh files you may have with
239
240 rm -f Policy.sh
dc45a647 241
aa689395 242=head1 Run Configure
8e07c86e
AD
243
244Configure will figure out various things about your system. Some
245things Configure will figure out for itself, other things it will ask
d6baa268
JH
246you about. To accept the default, just press RETURN. The default is
247almost always okay. It is normal for some things to be "NOT found",
248since Configure often searches for many different ways of performing
249the same function.
250
251At any Configure prompt, you can type &-d and Configure will use the
252defaults from then on.
8e07c86e
AD
253
254After it runs, Configure will perform variable substitution on all the
1ec51d55 255*.SH files and offer to run make depend.
8e07c86e 256
1b1c1ae2
GS
257=head2 Altering config.sh variables for C compiler switches etc.
258
259For most users, all of the Configure defaults are fine. Configure
260also has several convenient options which are all described below.
261However, if Configure doesn't have an option to do what you want,
262you can change Configure variables after the platform hints have been
263run, by using Configure's -A switch. For example, here's how to add
264a couple of extra flags to C compiler invocations:
265
266 sh Configure -Accflags="-DPERL_Y2KWARN -DPERL_POLLUTE_MALLOC"
267
268For more help on Configure switches, run:
269
270 sh Configure -h
271
844fc9f4
JH
272=head2 Building Perl outside of the source directory
273
274Sometimes it is desirable to build Perl in a directory different from
275where the sources are, for example if you want to keep your sources
276read-only, or if you want to share the sources between different binary
277architectures.
278
279Starting from Perl 5.6.1 you can do this (if your file system supports
280symbolic links) by
281
282 mkdir /tmp/perl/build/directory
283 cd /tmp/perl/build/directory
284 sh /path/to/perl/source/Configure -Dmksymlinks ...
285
286This will create in /tmp/perl/build/directory a tree of symbolic links
287pointing to files in /path/to/perl/source. The original files are left
288unaffected. After Configure has finished you can just say
289
290 make all test
291
292and Perl will be built and tested, all in /tmp/perl/build/directory.
293
d6baa268
JH
294=head2 Common Configure options
295
fb73857a
PP
296Configure supports a number of useful options. Run B<Configure -h> to
297get a listing. See the Porting/Glossary file for a complete list of
298Configure variables you can set and their definitions.
299
d6baa268
JH
300=over 4
301
302=item gcc
303
304To compile with gcc you should run
8e07c86e
AD
305
306 sh Configure -Dcc=gcc
307
308This is the preferred way to specify gcc (or another alternative
309compiler) so that the hints files can set appropriate defaults.
310
d6baa268 311=item Installation prefix
4633a7c4 312
8e07c86e 313By default, for most systems, perl will be installed in
8d74ce1c
AD
314/usr/local/{bin, lib, man}. (See L<"Installation Directories">
315and L<"Coexistence with earlier versions of perl5"> below for
316further details.)
317
318You can specify a different 'prefix' for the default installation
319directory, when Configure prompts you or by using the Configure command
320line option -Dprefix='/some/directory', e.g.
8e07c86e 321
25f94b33 322 sh Configure -Dprefix=/opt/perl
4633a7c4 323
d6baa268
JH
324If your prefix contains the string "perl", then the suggested
325directory structure is simplified. For example, if you use
326prefix=/opt/perl, then Configure will suggest /opt/perl/lib instead of
327/opt/perl/lib/perl5/. Again, see L<"Installation Directories"> below
328for more details.
8e07c86e 329
8d74ce1c
AD
330NOTE: You must not specify an installation directory that is the same
331as or below your perl source directory. If you do, installperl will
332attempt infinite recursion.
84902520 333
d6baa268
JH
334=item /usr/bin/perl
335
336It may seem obvious, but Perl is useful only when users can easily
337find it. It's often a good idea to have both /usr/bin/perl and
dd64f1c3 338/usr/local/bin/perl be symlinks to the actual binary. Be especially
d6baa268
JH
339careful, however, not to overwrite a version of perl supplied by your
340vendor unless you are sure you know what you are doing.
341
342By default, Configure will arrange for /usr/bin/perl to be linked to
343the current version of perl. You can turn off that behavior by running
344
345 Configure -Uinstallusrbinperl
346
347or by answering 'no' to the appropriate Configure prompt.
348
349In any case, system administrators are strongly encouraged to
dd64f1c3 350put (symlinks to) perl and its accompanying utilities, such as perldoc,
4682965a
MB
351into a directory typically found along a user's PATH, or in another
352obvious and convenient place.
353
d6baa268 354=item Overriding an old config.sh
04d420f9 355
d6baa268
JH
356If you want to use your old config.sh but override some of the items
357with command line options, you need to use B<Configure -O>.
358
359=back
8e07c86e 360
203c3eec
AD
361If you are willing to accept all the defaults, and you want terse
362output, you can run
363
364 sh Configure -des
365
b88cc0eb
JH
366Note: for development releases (odd subreleases, like 5.7, as opposed
367to maintenance releases which have even subreleases, like 5.6)
368if you want to use Configure -d, you will also need to supply -Dusedevel
369to Configure, because the default answer to the question "do you really
370want to Configure a development version?" is "no". The -Dusedevel
371skips that sanity check.
372
373For example for my Solaris system, I usually use
203c3eec
AD
374
375 sh Configure -Dprefix=/opt/perl -Doptimize='-xpentium -xO4' -des
376
46bb10fb
CS
377=head2 GNU-style configure
378
1ec51d55 379If you prefer the GNU-style configure command line interface, you can
dc45a647 380use the supplied configure.gnu command, e.g.
46bb10fb 381
693762b4 382 CC=gcc ./configure.gnu
46bb10fb 383
dc45a647 384The configure.gnu script emulates a few of the more common configure
46bb10fb
CS
385options. Try
386
693762b4 387 ./configure.gnu --help
46bb10fb
CS
388
389for a listing.
390
d6baa268 391Cross compiling and compiling in a different directory are not supported.
46bb10fb 392
dc45a647 393(The file is called configure.gnu to avoid problems on systems
693762b4 394that would not distinguish the files "Configure" and "configure".)
46bb10fb 395
aa689395 396=head2 Installation Directories
4633a7c4
LW
397
398The installation directories can all be changed by answering the
399appropriate questions in Configure. For convenience, all the
400installation questions are near the beginning of Configure.
d6baa268
JH
401Further, there are a number of additions to the installation
402directories since 5.005, so reusing your old config.sh may not
403be sufficient to put everything where you want it.
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 464
49cb0e56
GS
465NOTE: As of 5.6.0, ExtUtils::MakeMaker will use $sitelib and $sitearch,
466but will not use the other site-specific directories. Volunteers to
467fix this are needed.
468
d6baa268
JH
469=item Directories for vendor-supplied add-on files
470
471Lastly, if you are building a binary distribution of perl for
472distribution, Configure can optionally set up the following directories
473for you to use to distribute add-on modules.
474
475 Configure variable Default value
476 $vendorprefix (none)
477 (The next ones are set only if vendorprefix is set.)
478 $vendorbin $vendorprefix/bin
49c10eea 479 $vendorscript $vendorprefix/bin
273cf8d1
GS
480 $vendorlib $vendorprefix/lib/perl5/vendor_perl/$version
481 $vendorarch $vendorprefix/lib/perl5/vendor_perl/$version/$archname
49c10eea
JH
482 $vendorman1 $vendorprefix/man/man1
483 $vendorman3 $vendorprefix/man/man3
484 $vendorhtml1 (none)
485 $vendorhtml3 (none)
d6baa268
JH
486
487These are normally empty, but may be set as needed. For example,
488a vendor might choose the following settings:
489
490 $prefix /usr/bin
491 $siteprefix /usr/local/bin
492 $vendorprefix /usr/bin
493
494This would have the effect of setting the following:
495
496 $bin /usr/bin
497 $scriptdir /usr/bin
498 $privlib /usr/lib/perl5/$version
499 $archlib /usr/lib/perl5/$version/$archname
500 $man1dir /usr/man/man1
501 $man3dir /usr/man/man3
502
503 $sitebin /usr/local/bin
49c10eea 504 $sitescript /usr/local/bin
273cf8d1
GS
505 $sitelib /usr/local/lib/perl5/site_perl/$version
506 $sitearch /usr/local/lib/perl5/site_perl/$version/$archname
49c10eea
JH
507 $siteman1 /usr/local/man/man1
508 $siteman3 /usr/local/man/man3
d6baa268 509
49c10eea
JH
510 $vendorbin /usr/bin
511 $vendorscript /usr/bin
273cf8d1
GS
512 $vendorlib /usr/lib/perl5/vendor_perl/$version
513 $vendorarch /usr/lib/perl5/vendor_perl/$version/$archname
49c10eea
JH
514 $vendorman1 /usr/man/man1
515 $vendorman3 /usr/man/man3
d6baa268
JH
516
517Note how in this example, the vendor-supplied directories are in the
518/usr hierarchy, while the directories reserved for the end-user are in
273cf8d1
GS
519the /usr/local hierarchy.
520
49cb0e56
GS
521NOTE: As of 5.6.0, ExtUtils::MakeMaker does not use these directories.
522Volunteers to fix this are needed.
523
273cf8d1
GS
524The entire installed library hierarchy is installed in locations with
525version numbers, keeping the installations of different versions distinct.
526However, later installations of Perl can still be configured to search the
527installed libraries corresponding to compatible earlier versions.
528See L<"Coexistence with earlier versions of perl5"> below for more details
529on how Perl can be made to search older version directories.
d6baa268
JH
530
531Of course you may use these directories however you see fit. For
532example, you may wish to use $siteprefix for site-specific files that
533are stored locally on your own disk and use $vendorprefix for
534site-specific files that are stored elsewhere on your organization's
535network. One way to do that would be something like
536
537 sh Configure -Dsiteprefix=/usr/local -Dvendorprefix=/usr/share/perl
538
539=item otherlibdirs
540
541As a final catch-all, Configure also offers an $otherlibdirs
542variable. This variable contains a colon-separated list of additional
3b777bb4
GS
543directories to add to @INC. By default, it will be empty.
544Perl will search these directories (including architecture and
545version-specific subdirectories) for add-on modules and extensions.
d6baa268 546
a61357a9
JA
547=item APPLLIB_EXP
548
549There is one other way of adding paths to @INC at perl build time, and
550that is by setting the APPLLIB_EXP C pre-processor token to a colon-
551separated list of directories, like this
552
553 sh Configure -Accflags='-DAPPLLIB_EXP=\"/usr/libperl\"'
554
555The directories defined by APPLLIB_EXP get added to @INC I<first>,
556ahead of any others, and so provide a way to override the standard perl
557modules should you, for example, want to distribute fixes without
558touching the perl distribution proper. And, like otherlib dirs,
559version and architecture specific subdirectories are also searched, if
560present, at run time. Of course, you can still search other @INC
561directories ahead of those in APPLLIB_EXP by using any of the standard
562run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc.
563
d6baa268 564=item Man Pages
1ec51d55 565
d6baa268
JH
566In versions 5.005_57 and earlier, the default was to store module man
567pages in a version-specific directory, such as
568/usr/local/lib/perl5/$version/man/man3. The default for 5.005_58 and
569after is /usr/local/man/man3 so that most users can find the man pages
570without resetting MANPATH.
4633a7c4 571
d6baa268 572You can continue to use the old default from the command line with
4633a7c4 573
0a08c020 574 sh Configure -Dman3dir=/usr/local/lib/perl5/5.6.0/man/man3
8d74ce1c 575
d6baa268
JH
576Some users also prefer to use a .3pm suffix. You can do that with
577
578 sh Configure -Dman3ext=3pm
579
580Again, these are just the defaults, and can be changed as you run
581Configure.
582
583=item HTML pages
584
585As of perl5.005_57, the standard perl installation does not do
586anything with HTML documentation, but that may change in the future.
587Further, some add-on modules may wish to install HTML documents. The
588html Configure variables listed above are provided if you wish to
589specify where such documents should be placed. The default is "none",
590but will likely eventually change to something useful based on user
591feedback.
8d74ce1c 592
d6baa268 593=back
8d74ce1c 594
3a6175e1
AD
595Some users prefer to append a "/share" to $privlib and $sitelib
596to emphasize that those directories can be shared among different
597architectures.
4633a7c4 598
8d74ce1c
AD
599Note that these are just the defaults. You can actually structure the
600directories any way you like. They don't even have to be on the same
601filesystem.
602
603Further details about the installation directories, maintenance and
604development subversions, and about supporting multiple versions are
605discussed in L<"Coexistence with earlier versions of perl5"> below.
606
607If you specify a prefix that contains the string "perl", then the
d6baa268
JH
608library directory structure is slightly simplified. Instead of
609suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib.
8d74ce1c 610
d6baa268 611Thus, for example, if you Configure with
0a08c020 612-Dprefix=/opt/perl, then the default library directories for 5.6.0 are
3a6175e1 613
d6baa268 614 Configure variable Default value
0a08c020
GS
615 $privlib /opt/perl/lib/5.6.0
616 $archlib /opt/perl/lib/5.6.0/$archname
617 $sitelib /opt/perl/lib/site_perl/5.6.0
618 $sitearch /opt/perl/lib/site_perl/5.6.0/$archname
4633a7c4 619
aa689395
PP
620=head2 Changing the installation directory
621
622Configure distinguishes between the directory in which perl (and its
623associated files) should be installed and the directory in which it
624will eventually reside. For most sites, these two are the same; for
625sites that use AFS, this distinction is handled automatically.
1ec51d55 626However, sites that use software such as depot to manage software
d6baa268
JH
627packages, or users building binary packages for distribution may also
628wish to install perl into a different directory and use that
629management software to move perl to its final destination. This
630section describes how to do that.
aa689395 631
0dcb58f4 632Suppose you want to install perl under the /tmp/perl5 directory. You
d6baa268
JH
633could edit config.sh and change all the install* variables to point to
634/tmp/perl5 instead of /usr/local, or you could simply use the
635following command line:
636
637 sh Configure -Dinstallprefix=/tmp/perl5
638
639(replace /tmp/perl5 by a directory of your choice).
aa689395 640
693762b4 641Beware, though, that if you go to try to install new add-on
d6baa268 642modules, they too will get installed in under '/tmp/perl5' if you
693762b4
AD
643follow this example. The next section shows one way of dealing with
644that problem.
645
aa689395
PP
646=head2 Creating an installable tar archive
647
648If you need to install perl on many identical systems, it is
649convenient to compile it once and create an archive that can be
d6c1b5d3
AD
650installed on multiple systems. Suppose, for example, that you want to
651create an archive that can be installed in /opt/perl.
652Here's one way to do that:
aa689395 653
d6baa268 654 # Set up to install perl into a different directory,
aa689395 655 # e.g. /tmp/perl5 (see previous part).
d6baa268 656 sh Configure -Dinstallprefix=/tmp/perl5 -Dprefix=/opt/perl -des
aa689395
PP
657 make
658 make test
d6c1b5d3 659 make install # This will install everything into /tmp/perl5.
aa689395 660 cd /tmp/perl5
d6c1b5d3 661 # Edit $archlib/Config.pm and $archlib/.packlist to change all the
fb73857a 662 # install* variables back to reflect where everything will
d6c1b5d3
AD
663 # really be installed. (That is, change /tmp/perl5 to /opt/perl
664 # everywhere in those files.)
665 # Check the scripts in $scriptdir to make sure they have the correct
bfb7748a 666 # #!/wherever/perl line.
aa689395
PP
667 tar cvf ../perl5-archive.tar .
668 # Then, on each machine where you want to install perl,
d6c1b5d3 669 cd /opt/perl # Or wherever you specified as $prefix
aa689395
PP
670 tar xvf perl5-archive.tar
671
dc45a647 672=head2 Site-wide Policy settings
693762b4
AD
673
674After Configure runs, it stores a number of common site-wide "policy"
675answers (such as installation directories and the local perl contact
676person) in the Policy.sh file. If you want to build perl on another
677system using the same policy defaults, simply copy the Policy.sh file
678to the new system and Configure will use it along with the appropriate
679hint file for your system.
680
dc45a647
MB
681Alternatively, if you wish to change some or all of those policy
682answers, you should
683
684 rm -f Policy.sh
685
686to ensure that Configure doesn't re-use them.
687
688Further information is in the Policy_sh.SH file itself.
689
8d74ce1c
AD
690If the generated Policy.sh file is unsuitable, you may freely edit it
691to contain any valid shell commands. It will be run just after the
692platform-specific hints files.
693
c42e3e15 694Note: Since the directory hierarchy for 5.6.0 contains a number of
d6baa268
JH
695new vendor* and site* entries, your Policy.sh file will probably not
696set them to your desired values. I encourage you to run Configure
697interactively to be sure it puts things where you want them.
698
aa689395
PP
699=head2 Configure-time Options
700
701There are several different ways to Configure and build perl for your
702system. For most users, the defaults are sensible and will work.
703Some users, however, may wish to further customize perl. Here are
704some of the main things you can change.
705
693762b4 706=head2 Threads
aa689395 707
d6baa268
JH
708On some platforms, perl5.005 and later can be compiled with
709experimental support for threads. To enable this, read the file
710README.threads, and then try:
f7542a9d 711
693762b4 712 sh Configure -Dusethreads
aa689395 713
693762b4
AD
714Currently, you need to specify -Dusethreads on the Configure command
715line so that the hint files can make appropriate adjustments.
716
717The default is to compile without thread support.
3fe9a6f1 718
aaacdc8b
GS
719As of v5.5.64, perl has two different internal threads implementations.
720The 5.005 version (5005threads) and an interpreter-based implementation
721(ithreads) with one interpreter per thread. By default, Configure selects
722ithreads if -Dusethreads is specified. However, you can select the old
7235005threads behavior instead by either
724
725 sh Configure -Dusethreads -Duse5005threads
726
727or by
728 sh Configure -Dusethreads -Uuseithreads
729
730Eventually (by perl v5.6.0) this internal confusion ought to disappear,
731and these options may disappear as well.
732
766b63c4
JH
733=head2 Large file support.
734
735Since Perl 5.6.0 Perl has supported large files (files larger than
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,
740seek(), stat(), and -s them. It is bad if you are interfacing Perl
741using some extension, also the components you are connecting to must
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
46bb10fb
CS
798=head2 Selecting File IO mechanisms
799
800Previous versions of perl used the standard IO mechanisms as defined in
1ec51d55 801stdio.h. Versions 5.003_02 and later of perl allow alternate IO
46bb10fb
CS
802mechanisms via a "PerlIO" abstraction, but the stdio mechanism is still
803the default and is the only supported mechanism.
804
805This PerlIO abstraction can be enabled either on the Configure command
806line with
807
808 sh Configure -Duseperlio
809
810or interactively at the appropriate Configure prompt.
811
812If you choose to use the PerlIO abstraction layer, there are two
813(experimental) possibilities for the underlying IO calls. These have been
814tested to some extent on some platforms, but are not guaranteed to work
815everywhere.
816
817=over 4
818
819=item 1.
820
1ec51d55 821AT&T's "sfio". This has superior performance to stdio.h in many
aa689395 822cases, and is extensible by the use of "discipline" modules. Sfio
46bb10fb
CS
823currently only builds on a subset of the UNIX platforms perl supports.
824Because the data structures are completely different from stdio, perl
825extension modules or external libraries may not work. This
826configuration exists to allow these issues to be worked on.
827
828This option requires the 'sfio' package to have been built and installed.
1b9c9cf5 829The latest sfio is available from http://www.research.att.com/sw/tools/sfio/
46bb10fb
CS
830
831You select this option by
832
833 sh Configure -Duseperlio -Dusesfio
834
835If you have already selected -Duseperlio, and if Configure detects
836that you have sfio, then sfio will be the default suggested by
837Configure.
838
d6baa268
JH
839Note: On some systems, sfio's iffe configuration script fails to
840detect that you have an atexit function (or equivalent). Apparently,
841this is a problem at least for some versions of Linux and SunOS 4.
842Configure should detect this problem and warn you about problems with
843_exit vs. exit. If you have this problem, the fix is to go back to
844your sfio sources and correct iffe's guess about atexit.
33e6ee5f 845
46bb10fb
CS
846=item 2.
847
848Normal stdio IO, but with all IO going through calls to the PerlIO
849abstraction layer. This configuration can be used to check that perl and
850extension modules have been correctly converted to use the PerlIO
851abstraction.
852
853This configuration should work on all platforms (but might not).
854
aa689395 855You select this option via:
46bb10fb
CS
856
857 sh Configure -Duseperlio -Uusesfio
858
859If you have already selected -Duseperlio, and if Configure does not
860detect sfio, then this will be the default suggested by Configure.
861
862=back
863
1b9c9cf5
DH
864=head2 SOCKS
865
866Perl can be configured to be 'socksified', that is, to use the SOCKS
867TCP/IP proxy protocol library. SOCKS is used to give applications
868access to transport layer network proxies. Perl supports only SOCKS
869Version 5. You can find more about SOCKS from http://www.socks.nec.com/
870
d6baa268
JH
871=head2 Dynamic Loading
872
873By default, Configure will compile perl to use dynamic loading if
874your system supports it. If you want to force perl to be compiled
875statically, you can either choose this when Configure prompts you or
876you can use the Configure command line option -Uusedl.
877
aa689395 878=head2 Building a shared libperl.so Perl library
c3edaffb
PP
879
880Currently, for most systems, the main perl executable is built by
881linking the "perl library" libperl.a with perlmain.o, your static
882extensions (usually just DynaLoader.a) and various extra libraries,
883such as -lm.
884
9d67150a
PP
885On some systems that support dynamic loading, it may be possible to
886replace libperl.a with a shared libperl.so. If you anticipate building
c3edaffb
PP
887several different perl binaries (e.g. by embedding libperl into
888different programs, or by using the optional compiler extension), then
9d67150a 889you might wish to build a shared libperl.so so that all your binaries
c3edaffb
PP
890can share the same library.
891
892The disadvantages are that there may be a significant performance
9d67150a 893penalty associated with the shared libperl.so, and that the overall
aa689395 894mechanism is still rather fragile with respect to different versions
c3edaffb
PP
895and upgrades.
896
897In terms of performance, on my test system (Solaris 2.5_x86) the perl
9d67150a 898test suite took roughly 15% longer to run with the shared libperl.so.
c3edaffb
PP
899Your system and typical applications may well give quite different
900results.
901
902The default name for the shared library is typically something like
a6006777 903libperl.so.3.2 (for Perl 5.003_02) or libperl.so.302 or simply
9d67150a 904libperl.so. Configure tries to guess a sensible naming convention
c3edaffb
PP
905based on your C library name. Since the library gets installed in a
906version-specific architecture-dependent directory, the exact name
907isn't very important anyway, as long as your linker is happy.
908
909For some systems (mostly SVR4), building a shared libperl is required
910for dynamic loading to work, and hence is already the default.
911
912You can elect to build a shared libperl by
913
914 sh Configure -Duseshrplib
915
2bf2710f
GS
916To build a shared libperl, the environment variable controlling shared
917library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
78be1e1a
JH
918NeXTSTEP/OPENSTEP/Darwin, LIBRARY_PATH for BeOS, LD_LIBRARY_PATH/SHLIB_PATH
919for HP-UX, LIBPATH for AIX, PATH for Cygwin) must be set up to include
2bf2710f 920the Perl build directory because that's where the shared libperl will
d6baa268 921be created. Configure arranges makefile to have the correct shared
2bf2710f
GS
922library search settings.
923
924However, there are some special cases where manually setting the
925shared library path might be required. For example, if you want to run
926something like the following with the newly-built but not-yet-installed
927./perl:
928
929 cd t; ./perl misc/failing_test.t
930or
931 ./perl -Ilib ~/my_mission_critical_test
932
933then you need to set up the shared library path explicitly.
934You can do this with
c3edaffb
PP
935
936 LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
937
938for Bourne-style shells, or
939
940 setenv LD_LIBRARY_PATH `pwd`
941
2bf2710f 942for Csh-style shells. (This procedure may also be needed if for some
d6baa268 943unexpected reason Configure fails to set up makefile correctly.)
2bf2710f
GS
944
945You can often recognize failures to build/use a shared libperl from error
946messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
947for example:
94818126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
c3edaffb 949
9d67150a
PP
950There is also an potential problem with the shared perl library if you
951want to have more than one "flavor" of the same version of perl (e.g.
952with and without -DDEBUGGING). For example, suppose you build and
a6006777
PP
953install a standard Perl 5.004 with a shared library. Then, suppose you
954try to build Perl 5.004 with -DDEBUGGING enabled, but everything else
9d67150a
PP
955the same, including all the installation directories. How can you
956ensure that your newly built perl will link with your newly built
7f678428 957libperl.so.4 rather with the installed libperl.so.4? The answer is
9d67150a 958that you might not be able to. The installation directory is encoded
56c6f531
JH
959in the perl binary with the LD_RUN_PATH environment variable (or
960equivalent ld command-line option). On Solaris, you can override that
7beaa944 961with LD_LIBRARY_PATH; on Linux you can't. On Digital Unix, you can
0dcb58f4 962override LD_LIBRARY_PATH by setting the _RLD_ROOT environment variable
7beaa944 963to point to the perl build directory.
9d67150a
PP
964
965The only reliable answer is that you should specify a different
966directory for the architecture-dependent library for your -DDEBUGGING
fb73857a 967version of perl. You can do this by changing all the *archlib*
d6baa268 968variables in config.sh to point to your new architecture-dependent library.
9d67150a 969
55479bb6
AD
970=head2 Malloc Issues
971
d6baa268
JH
972Perl relies heavily on malloc(3) to grow data structures as needed,
973so perl's performance can be noticeably affected by the performance of
974the malloc function on your system. The perl source is shipped with a
975version of malloc that has been optimized for the typical requests from
976perl, so there's a chance that it may be both faster and use less memory
977than your system malloc.
55479bb6 978
d6baa268
JH
979However, if your system already has an excellent malloc, or if you are
980experiencing difficulties with extensions that use third-party libraries
981that call malloc, then you should probably use your system's malloc.
982(Or, you might wish to explore the malloc flags discussed below.)
c3edaffb 983
aa689395
PP
984=over 4
985
d6baa268 986=item Using the system malloc
2ae324a7 987
d6baa268 988To build without perl's malloc, you can use the Configure command
aa689395 989
d6baa268 990 sh Configure -Uusemymalloc
aa689395 991
d6baa268 992or you can answer 'n' at the appropriate interactive Configure prompt.
aa689395 993
86058a2d
GS
994=item -DPERL_POLLUTE_MALLOC
995
b2a6d19e
GS
996NOTE: This flag is enabled automatically on some platforms if you
997asked for binary compatibility with version 5.005, or if you just
998run Configure to accept all the defaults on those platforms. You
999can refuse the automatic binary compatibility flags wholesale by
1000running:
1001
1002 sh Configure -Ubincompat5005
1003
1004or by answering 'n' at the appropriate prompt.
1005
d6baa268 1006Perl's malloc family of functions are called Perl_malloc(),
b2a6d19e
GS
1007Perl_realloc(), Perl_calloc() and Perl_mfree(). When this flag is
1008not enabled, the names do not clash with the system versions of
1009these functions.
d6baa268 1010
b2a6d19e 1011If enabled, Perl's malloc family of functions will have the same
d6baa268
JH
1012names as the system versions. This may be sometimes required when you
1013have libraries that like to free() data that may have been allocated
1014by Perl_malloc() and vice versa.
86058a2d 1015
d6baa268
JH
1016Note that enabling this option may sometimes lead to duplicate symbols
1017from the linker for malloc et al. In such cases, the system probably
1018does not allow its malloc functions to be fully replaced with custom
1019versions.
86058a2d 1020
aa689395
PP
1021=back
1022
3bf462b8
CS
1023=head2 Building a debugging perl
1024
1025You can run perl scripts under the perl debugger at any time with
3fe9a6f1 1026B<perl -d your_script>. If, however, you want to debug perl itself,
3bf462b8
CS
1027you probably want to do
1028
1029 sh Configure -Doptimize='-g'
1030
203c3eec
AD
1031This will do two independent things: First, it will force compilation
1032to use cc -g so that you can use your system's debugger on the
1033executable. (Note: Your system may actually require something like
d6baa268
JH
1034cc -g2. Check your man pages for cc(1) and also any hint file for
1035your system.) Second, it will add -DDEBUGGING to your ccflags
1036variable in config.sh so that you can use B<perl -D> to access perl's
1037internal state. (Note: Configure will only add -DDEBUGGING by default
1038if you are not reusing your old config.sh. If you want to reuse your
1039old config.sh, then you can just edit it and change the optimize and
1040ccflags variables by hand and then propagate your changes as shown in
1041L<"Propagating your changes to config.sh"> below.)
203c3eec
AD
1042
1043You can actually specify -g and -DDEBUGGING independently, but usually
1044it's convenient to have both.
3bf462b8
CS
1045
1046If you are using a shared libperl, see the warnings about multiple
1047versions of perl under L<Building a shared libperl.so Perl library>.
1048
8d74ce1c
AD
1049=head2 Extensions
1050
1051By default, Configure will offer to build every extension which appears
1052to be supported. For example, Configure will offer to build GDBM_File
1053only if it is able to find the gdbm library. (See examples below.)
1054B, DynaLoader, Fcntl, IO, and attrs are always built by default.
1055Configure does not contain code to test for POSIX compliance, so POSIX
1056is always built by default as well. If you wish to skip POSIX, you can
1057set the Configure variable useposix=false either in a hint file or from
1058the Configure command line. Similarly, the Opcode extension is always
1059built by default, but you can skip it by setting the Configure variable
1060useopcode=false either in a hint file for from the command line.
1061
c42e3e15
GS
1062If you unpack any additional extensions in the ext/ directory before
1063running Configure, then Configure will offer to build those additional
1064extensions as well. Most users probably shouldn't have to do this --
1065it is usually easier to build additional extensions later after perl
1066has been installed. However, if you wish to have those additional
1067extensions statically linked into the perl binary, then this offers a
1068convenient way to do that in one step. (It is not necessary, however;
1069you can build and install extensions just fine even if you don't have
1070dynamic loading. See lib/ExtUtils/MakeMaker.pm for more details.)
1071
1072You can learn more about each of the supplied extensions by consulting the
8d74ce1c
AD
1073documentation in the individual .pm modules, located under the
1074ext/ subdirectory.
1075
1076Even if you do not have dynamic loading, you must still build the
1077DynaLoader extension; you should just build the stub dl_none.xs
1078version. (Configure will suggest this as the default.)
1079
1080In summary, here are the Configure command-line variables you can set
1081to turn off each extension:
1082
1083 B (Always included by default)
1084 DB_File i_db
1085 DynaLoader (Must always be included as a static extension)
1086 Fcntl (Always included by default)
1087 GDBM_File i_gdbm
1088 IO (Always included by default)
1089 NDBM_File i_ndbm
1090 ODBM_File i_dbm
1091 POSIX useposix
1092 SDBM_File (Always included by default)
1093 Opcode useopcode
1094 Socket d_socket
a2dab6bc 1095 Threads use5005threads
8d74ce1c
AD
1096 attrs (Always included by default)
1097
1098Thus to skip the NDBM_File extension, you can use
1099
1100 sh Configure -Ui_ndbm
1101
1102Again, this is taken care of automatically if you don't have the ndbm
1103library.
1104
1105Of course, you may always run Configure interactively and select only
1106the extensions you want.
1107
1108Note: The DB_File module will only work with version 1.x of Berkeley
1109DB or newer releases of version 2. Configure will automatically detect
1110this for you and refuse to try to build DB_File with earlier
1111releases of version 2.
1112
1113If you re-use your old config.sh but change your system (e.g. by
1114adding libgdbm) Configure will still offer your old choices of extensions
1115for the default answer, but it will also point out the discrepancy to
1116you.
1117
1118Finally, if you have dynamic loading (most modern Unix systems do)
1119remember that these extensions do not increase the size of your perl
1120executable, nor do they impact start-up time, so you probably might as
1121well build all the ones that will work on your system.
1122
1123=head2 Including locally-installed libraries
1124
1125Perl5 comes with interfaces to number of database extensions, including
1126dbm, ndbm, gdbm, and Berkeley db. For each extension, if
1127Configure can find the appropriate header files and libraries, it will
1128automatically include that extension. The gdbm and db libraries
1129are not included with perl. See the library documentation for
1130how to obtain the libraries.
1131
d6baa268
JH
1132If your database header (.h) files are not in a directory normally
1133searched by your C compiler, then you will need to include the
1134appropriate -I/your/directory option when prompted by Configure. If
1135your database library (.a) files are not in a directory normally
1136searched by your C compiler and linker, then you will need to include
1137the appropriate -L/your/directory option when prompted by Configure.
1138See the examples below.
8d74ce1c
AD
1139
1140=head2 Examples
1141
1142=over 4
1143
1144=item gdbm in /usr/local
1145
1146Suppose you have gdbm and want Configure to find it and build the
d6baa268 1147GDBM_File extension. This example assumes you have gdbm.h
8d74ce1c
AD
1148installed in /usr/local/include/gdbm.h and libgdbm.a installed in
1149/usr/local/lib/libgdbm.a. Configure should figure all the
1150necessary steps out automatically.
1151
1152Specifically, when Configure prompts you for flags for
1153your C compiler, you should include -I/usr/local/include.
1154
1155When Configure prompts you for linker flags, you should include
1156-L/usr/local/lib.
1157
1158If you are using dynamic loading, then when Configure prompts you for
1159linker flags for dynamic loading, you should again include
1160-L/usr/local/lib.
1161
d6baa268
JH
1162Again, this should all happen automatically. This should also work if
1163you have gdbm installed in any of (/usr/local, /opt/local, /usr/gnu,
1164/opt/gnu, /usr/GNU, or /opt/GNU).
8d74ce1c
AD
1165
1166=item gdbm in /usr/you
1167
1168Suppose you have gdbm installed in some place other than /usr/local/,
1169but you still want Configure to find it. To be specific, assume you
1170have /usr/you/include/gdbm.h and /usr/you/lib/libgdbm.a. You
1171still have to add -I/usr/you/include to cc flags, but you have to take
1172an extra step to help Configure find libgdbm.a. Specifically, when
1173Configure prompts you for library directories, you have to add
1174/usr/you/lib to the list.
1175
1176It is possible to specify this from the command line too (all on one
1177line):
1178
d6baa268 1179 sh Configure -de \
8d74ce1c
AD
1180 -Dlocincpth="/usr/you/include" \
1181 -Dloclibpth="/usr/you/lib"
1182
1183locincpth is a space-separated list of include directories to search.
1184Configure will automatically add the appropriate -I directives.
1185
1186loclibpth is a space-separated list of library directories to search.
1187Configure will automatically add the appropriate -L directives. If
1188you have some libraries under /usr/local/ and others under
1189/usr/you, then you have to include both, namely
1190
d6baa268 1191 sh Configure -de \
8d74ce1c
AD
1192 -Dlocincpth="/usr/you/include /usr/local/include" \
1193 -Dloclibpth="/usr/you/lib /usr/local/lib"
1194
1195=back
1196
bb636fa4
JH
1197=head2 Building DB, NDBM, and ODBM interfaces with Berkeley DB 3
1198
1199Perl interface for DB3 is part of Berkeley DB, but if you want to
1200compile standard Perl DB/ODBM/NDBM interfaces, you must follow
1201following instructions.
1202
1203Berkeley DB3 from Sleepycat Software is by default installed without
1204DB1 compatibility code (needed for DB_File interface) and without
1205links to compatibility files. So if you want to use packages written
1206for DB/ODBM/NDBM interfaces, you need to configure DB3 with
1207--enable-compat185 (and optionally with --enable-dump185) and create
1208additional references (suppose you are installing DB3 with
1209--prefix=/usr):
1210
1211 ln -s libdb-3.so /usr/lib/libdbm.so
1212 ln -s libdb-3.so /usr/lib/libndbm.so
1213 echo '#define DB_DBM_HSEARCH 1' >dbm.h
1214 echo '#include <db.h>' >>dbm.h
1215 install -m 0644 dbm.h /usr/include/dbm.h
1216 install -m 0644 dbm.h /usr/include/ndbm.h
1217
1218Optionally, if you have compiled with --enable-compat185 (not needed
1219for ODBM/NDBM):
1220
1221 ln -s libdb-3.so /usr/lib/libdb1.so
1222 ln -s libdb-3.so /usr/lib/libdb.so
1223
1224ODBM emulation seems not to be perfect, but is quite usable,
1225using DB 3.1.17:
1226
1227 lib/odbm.............FAILED at test 9
1228 Failed 1/64 tests, 98.44% okay
1229
8e07c86e
AD
1230=head2 What if it doesn't work?
1231
8d74ce1c
AD
1232If you run into problems, try some of the following ideas.
1233If none of them help, then see L<"Reporting Problems"> below.
1234
8e07c86e
AD
1235=over 4
1236
25f94b33
AD
1237=item Running Configure Interactively
1238
1239If Configure runs into trouble, remember that you can always run
1240Configure interactively so that you can check (and correct) its
1241guesses.
1242
1243All the installation questions have been moved to the top, so you don't
aa689395 1244have to wait for them. Once you've handled them (and your C compiler and
1ec51d55 1245flags) you can type &-d at the next Configure prompt and Configure
25f94b33
AD
1246will use the defaults from then on.
1247
1248If you find yourself trying obscure command line incantations and
1249config.over tricks, I recommend you run Configure interactively
1250instead. You'll probably save yourself time in the long run.
1251
aa689395 1252=item Hint files
8e07c86e
AD
1253
1254The perl distribution includes a number of system-specific hints files
1255in the hints/ directory. If one of them matches your system, Configure
1256will offer to use that hint file.
1257
1258Several of the hint files contain additional important information.
f5b3b617
AD
1259If you have any problems, it is a good idea to read the relevant hint file
1260for further information. See hints/solaris_2.sh for an extensive example.
1261More information about writing good hints is in the hints/README.hints
1262file.
8e07c86e 1263
edb1cbcb
PP
1264=item *** WHOA THERE!!! ***
1265
1266Occasionally, Configure makes a wrong guess. For example, on SunOS
12674.1.3, Configure incorrectly concludes that tzname[] is in the
1268standard C library. The hint file is set up to correct for this. You
1269will see a message:
1270
1271 *** WHOA THERE!!! ***
1272 The recommended value for $d_tzname on this machine was "undef"!
1273 Keep the recommended value? [y]
1274
1275You should always keep the recommended value unless, after reading the
1276relevant section of the hint file, you are sure you want to try
1277overriding it.
1278
1279If you are re-using an old config.sh, the word "previous" will be
1280used instead of "recommended". Again, you will almost always want
1281to keep the previous value, unless you have changed something on your
1282system.
1283
1284For example, suppose you have added libgdbm.a to your system
1285and you decide to reconfigure perl to use GDBM_File. When you run
1286Configure again, you will need to add -lgdbm to the list of libraries.
bfb7748a
AD
1287Now, Configure will find your gdbm include file and library and will
1288issue a message:
edb1cbcb
PP
1289
1290 *** WHOA THERE!!! ***
1291 The previous value for $i_gdbm on this machine was "undef"!
1292 Keep the previous value? [y]
1293
1ec51d55 1294In this case, you do not want to keep the previous value, so you
c3edaffb 1295should answer 'n'. (You'll also have to manually add GDBM_File to
edb1cbcb
PP
1296the list of dynamic extensions to build.)
1297
8e07c86e
AD
1298=item Changing Compilers
1299
1300If you change compilers or make other significant changes, you should
1ec51d55 1301probably not re-use your old config.sh. Simply remove it or
8e07c86e
AD
1302rename it, e.g. mv config.sh config.sh.old. Then rerun Configure
1303with the options you want to use.
1304
1ec51d55
CS
1305This is a common source of problems. If you change from cc to
1306gcc, you should almost always remove your old config.sh.
8e07c86e 1307
c3edaffb 1308=item Propagating your changes to config.sh
8e07c86e 1309
1ec51d55
CS
1310If you make any changes to config.sh, you should propagate
1311them to all the .SH files by running
1312
1313 sh Configure -S
1314
1315You will then have to rebuild by running
9d67150a
PP
1316
1317 make depend
1318 make
8e07c86e
AD
1319
1320=item config.over
1321
1322You can also supply a shell script config.over to over-ride Configure's
1323guesses. It will get loaded up at the very end, just before config.sh
1324is created. You have to be careful with this, however, as Configure
d6baa268 1325does no checking that your changes make sense.
8e07c86e
AD
1326
1327=item config.h
1328
1ec51d55
CS
1329Many of the system dependencies are contained in config.h.
1330Configure builds config.h by running the config_h.SH script.
1331The values for the variables are taken from config.sh.
8e07c86e 1332
1ec51d55
CS
1333If there are any problems, you can edit config.h directly. Beware,
1334though, that the next time you run Configure, your changes will be
8e07c86e
AD
1335lost.
1336
1337=item cflags
1338
1339If you have any additional changes to make to the C compiler command
1ec51d55
CS
1340line, they can be made in cflags.SH. For instance, to turn off the
1341optimizer on toke.c, find the line in the switch structure for
1342toke.c and put the command optimize='-g' before the ;; . You
1343can also edit cflags directly, but beware that your changes will be
1344lost the next time you run Configure.
8e07c86e 1345
f5b3b617
AD
1346To explore various ways of changing ccflags from within a hint file,
1347see the file hints/README.hints.
1348
1349To change the C flags for all the files, edit config.sh and change either
1350$ccflags or $optimize, and then re-run
1ec51d55
CS
1351
1352 sh Configure -S
1353 make depend
8e07c86e 1354
aa689395 1355=item No sh
8e07c86e 1356
c42e3e15
GS
1357If you don't have sh, you'll have to copy the sample file
1358Porting/config.sh to config.sh and edit your config.sh to reflect your
1359system's peculiarities. See Porting/pumpkin.pod for more information.
8e07c86e
AD
1360You'll probably also have to extensively modify the extension building
1361mechanism.
1362
d6baa268
JH
1363=item Environment variable clashes
1364
1365Configure uses a CONFIG variable that is reported to cause trouble on
1366ReliantUnix 5.44. If your system sets this variable, you can try
1367unsetting it before you run Configure. Configure should eventually
1368be fixed to avoid polluting the namespace of the environment.
1369
1370=item Digital UNIX/Tru64 UNIX and BIN_SH
1371
1372In Digital UNIX/Tru64 UNIX, Configure might abort with
1373
1374Build a threading Perl? [n]
1375Configure[2437]: Syntax error at line 1 : `config.sh' is not expected.
1376
1377This indicates that Configure is being run with a broken Korn shell
1378(even though you think you are using a Bourne shell by using
1379"sh Configure" or "./Configure"). The Korn shell bug has been reported
1380to Compaq as of February 1999 but in the meanwhile, the reason ksh is
1381being used is that you have the environment variable BIN_SH set to
1382'xpg4'. This causes /bin/sh to delegate its duties to /bin/posix/sh
1383(a ksh). Unset the environment variable and rerun Configure.
1384
1385=item HP-UX 11, pthreads, and libgdbm
1386
1387If you are running Configure with -Dusethreads in HP-UX 11, be warned
1388that POSIX threads and libgdbm (the GNU dbm library) compiled before
1389HP-UX 11 do not mix. This will cause a basic test run by Configure to
1390fail
1391
1392Pthread internal error: message: __libc_reinit() failed, file: ../pthreads/pthread.c, line: 1096
1393Return Pointer is 0xc082bf33
1394sh: 5345 Quit(coredump)
1395
1396and Configure will give up. The cure is to recompile and install
1397libgdbm under HP-UX 11.
1398
c3edaffb
PP
1399=item Porting information
1400
2ae324a7 1401Specific information for the OS/2, Plan9, VMS and Win32 ports is in the
1ec51d55
CS
1402corresponding README files and subdirectories. Additional information,
1403including a glossary of all those config.sh variables, is in the Porting
c42e3e15 1404subdirectory. Especially Porting/Glossary should come in handy.
c3edaffb 1405
7f678428 1406Ports for other systems may also be available. You should check out
1ec51d55 1407http://www.perl.com/CPAN/ports for current information on ports to
7f678428
PP
1408various other operating systems.
1409
491517e0
JA
1410If you plan to port Perl to a new architecture study carefully the
1411section titled "Philosophical Issues in Patching and Porting Perl"
1412in the file Porting/pumpkin.pod and the file Porting/patching.pod.
1413Study also how other non-UNIX ports have solved problems.
1414
8e07c86e
AD
1415=back
1416
1417=head1 make depend
1418
bfb7748a
AD
1419This will look for all the includes. The output is stored in makefile.
1420The only difference between Makefile and makefile is the dependencies at
1421the bottom of makefile. If you have to make any changes, you should edit
1422makefile, not Makefile since the Unix make command reads makefile first.
1423(On non-Unix systems, the output may be stored in a different file.
1424Check the value of $firstmakefile in your config.sh if in doubt.)
8e07c86e
AD
1425
1426Configure will offer to do this step for you, so it isn't listed
1427explicitly above.
1428
1429=head1 make
1430
1431This will attempt to make perl in the current directory.
1432
8d74ce1c
AD
1433=head2 What if it doesn't work?
1434
8e07c86e 1435If you can't compile successfully, try some of the following ideas.
7f678428 1436If none of them help, and careful reading of the error message and
8d74ce1c
AD
1437the relevant manual pages on your system doesn't help,
1438then see L<"Reporting Problems"> below.
8e07c86e
AD
1439
1440=over 4
1441
1ec51d55 1442=item hints
8e07c86e
AD
1443
1444If you used a hint file, try reading the comments in the hint file
1445for further tips and information.
1446
1ec51d55 1447=item extensions
8e07c86e 1448
1ec51d55 1449If you can successfully build miniperl, but the process crashes
c3edaffb
PP
1450during the building of extensions, you should run
1451
3a6175e1 1452 make minitest
c3edaffb
PP
1453
1454to test your version of miniperl.
1455
e57fd563
PP
1456=item locale
1457
bfb7748a
AD
1458If you have any locale-related environment variables set, try unsetting
1459them. I have some reports that some versions of IRIX hang while
1460running B<./miniperl configpm> with locales other than the C locale.
1461See the discussion under L<"make test"> below about locales and the
1462whole L<"Locale problems"> section in the file pod/perllocale.pod.
3e6e419a
JH
1463The latter is especially useful if you see something like this
1464
1465 perl: warning: Setting locale failed.
1466 perl: warning: Please check that your locale settings:
1467 LC_ALL = "En_US",
1468 LANG = (unset)
1469 are supported and installed on your system.
1470 perl: warning: Falling back to the standard locale ("C").
1471
1472at Perl startup.
e57fd563 1473
7f678428 1474=item varargs
c3edaffb
PP
1475
1476If you get varargs problems with gcc, be sure that gcc is installed
bfb7748a
AD
1477correctly and that you are not passing -I/usr/include to gcc. When using
1478gcc, you should probably have i_stdarg='define' and i_varargs='undef'
1479in config.sh. The problem is usually solved by running fixincludes
1480correctly. If you do change config.sh, don't forget to propagate
1481your changes (see L<"Propagating your changes to config.sh"> below).
7f678428 1482See also the L<"vsprintf"> item below.
c3edaffb 1483
bfb7748a 1484=item util.c
c3edaffb
PP
1485
1486If you get error messages such as the following (the exact line
bfb7748a 1487numbers and function name may vary in different versions of perl):
c3edaffb 1488
bfb7748a
AD
1489 util.c: In function `Perl_form':
1490 util.c:1107: number of arguments doesn't match prototype
1491 proto.h:125: prototype declaration
c3edaffb
PP
1492
1493it might well be a symptom of the gcc "varargs problem". See the
7f678428 1494previous L<"varargs"> item.
c3edaffb 1495
1ec51d55 1496=item LD_LIBRARY_PATH
c3edaffb
PP
1497
1498If you run into dynamic loading problems, check your setting of
aa689395
PP
1499the LD_LIBRARY_PATH environment variable. If you're creating a static
1500Perl library (libperl.a rather than libperl.so) it should build
c3edaffb
PP
1501fine with LD_LIBRARY_PATH unset, though that may depend on details
1502of your local set-up.
1503
aa689395 1504=item nm extraction
c3edaffb
PP
1505
1506If Configure seems to be having trouble finding library functions,
1507try not using nm extraction. You can do this from the command line
1508with
1509
1510 sh Configure -Uusenm
1511
1512or by answering the nm extraction question interactively.
1ec51d55 1513If you have previously run Configure, you should not reuse your old
c3edaffb
PP
1514config.sh.
1515
bfb7748a
AD
1516=item umask not found
1517
1518If the build processes encounters errors relating to umask(), the problem
1519is probably that Configure couldn't find your umask() system call.
1520Check your config.sh. You should have d_umask='define'. If you don't,
1521this is probably the L<"nm extraction"> problem discussed above. Also,
1522try reading the hints file for your system for further information.
1523
7f678428 1524=item vsprintf
c3edaffb
PP
1525
1526If you run into problems with vsprintf in compiling util.c, the
1527problem is probably that Configure failed to detect your system's
1528version of vsprintf(). Check whether your system has vprintf().
1529(Virtually all modern Unix systems do.) Then, check the variable
1530d_vprintf in config.sh. If your system has vprintf, it should be:
1531
1532 d_vprintf='define'
1533
1534If Configure guessed wrong, it is likely that Configure guessed wrong
bfb7748a
AD
1535on a number of other common functions too. This is probably
1536the L<"nm extraction"> problem discussed above.
c3edaffb 1537
3fe9a6f1
PP
1538=item do_aspawn
1539
1540If you run into problems relating to do_aspawn or do_spawn, the
1541problem is probably that Configure failed to detect your system's
bfb7748a
AD
1542fork() function. Follow the procedure in the previous item
1543on L<"nm extraction">.
3fe9a6f1 1544
84902520
TB
1545=item __inet_* errors
1546
1547If you receive unresolved symbol errors during Perl build and/or test
1548referring to __inet_* symbols, check to see whether BIND 8.1 is
1549installed. It installs a /usr/local/include/arpa/inet.h that refers to
1550these symbols. Versions of BIND later than 8.1 do not install inet.h
1551in that location and avoid the errors. You should probably update to a
1552newer version of BIND. If you can't, you can either link with the
1553updated resolver library provided with BIND 8.1 or rename
1554/usr/local/bin/arpa/inet.h during the Perl build and test process to
1555avoid the problem.
1556
d6baa268
JH
1557=item #error "No DATAMODEL_NATIVE specified"
1558
1559This is a common error when trying to build perl on Solaris 2.6 with a
1560gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files
1561changed, so you need to update your gcc installation. You can either
1562rerun the fixincludes script from gcc or take the opportunity to
1563update your gcc installation.
1564
aa689395 1565=item Optimizer
c3edaffb 1566
9d67150a 1567If you can't compile successfully, try turning off your compiler's
aa689395 1568optimizer. Edit config.sh and change the line
9d67150a
PP
1569
1570 optimize='-O'
1571
bfb7748a 1572to
9d67150a
PP
1573
1574 optimize=' '
1575
1576then propagate your changes with B<sh Configure -S> and rebuild
1577with B<make depend; make>.
1578
1ec51d55 1579=item CRIPPLED_CC
9d67150a 1580
1b1c1ae2
GS
1581If you still can't compile successfully, try:
1582
1583 sh Configure -Accflags=-DCRIPPLED_CC
1584
1585This flag simplifies some complicated expressions for compilers that get
1586indigestion easily. (Just because you get no errors doesn't mean it
1587compiled right!)
9d67150a
PP
1588
1589=item Missing functions
1590
1591If you have missing routines, you probably need to add some library or
1592other, or you need to undefine some feature that Configure thought was
1593there but is defective or incomplete. Look through config.h for
bfb7748a
AD
1594likely suspects. If Configure guessed wrong on a number of functions,
1595you might have the L<"nm extraction"> problem discussed above.
8e07c86e 1596
1ec51d55 1597=item toke.c
8e07c86e 1598
1ec51d55
CS
1599Some compilers will not compile or optimize the larger files (such as
1600toke.c) without some extra switches to use larger jump offsets or
1601allocate larger internal tables. You can customize the switches for
1602each file in cflags. It's okay to insert rules for specific files into
1603makefile since a default rule only takes effect in the absence of a
8e07c86e
AD
1604specific rule.
1605
7f678428 1606=item Missing dbmclose
8e07c86e 1607
c3edaffb
PP
1608SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
1609that includes libdbm.nfs (which includes dbmclose()) may be available.
8e07c86e 1610
f3d9a6ba 1611=item Note (probably harmless): No library found for -lsomething
7f678428
PP
1612
1613If you see such a message during the building of an extension, but
1614the extension passes its tests anyway (see L<"make test"> below),
1615then don't worry about the warning message. The extension
1616Makefile.PL goes looking for various libraries needed on various
aa689395 1617systems; few systems will need all the possible libraries listed.
7f678428
PP
1618For example, a system may have -lcposix or -lposix, but it's
1619unlikely to have both, so most users will see warnings for the one
f3d9a6ba
CS
1620they don't have. The phrase 'probably harmless' is intended to
1621reassure you that nothing unusual is happening, and the build
1622process is continuing.
7f678428
PP
1623
1624On the other hand, if you are building GDBM_File and you get the
1625message
1626
f3d9a6ba 1627 Note (probably harmless): No library found for -lgdbm
7f678428
PP
1628
1629then it's likely you're going to run into trouble somewhere along
1630the line, since it's hard to see how you can use the GDBM_File
1631extension without the -lgdbm library.
1632
1633It is true that, in principle, Configure could have figured all of
1634this out, but Configure and the extension building process are not
1635quite that tightly coordinated.
1636
aa689395
PP
1637=item sh: ar: not found
1638
1639This is a message from your shell telling you that the command 'ar'
1640was not found. You need to check your PATH environment variable to
1641make sure that it includes the directory with the 'ar' command. This
1ec51d55 1642is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
aa689395
PP
1643directory.
1644
1645=item db-recno failure on tests 51, 53 and 55
1646
1647Old versions of the DB library (including the DB library which comes
1648with FreeBSD 2.1) had broken handling of recno databases with modified
1649bval settings. Upgrade your DB library or OS.
1650
6087ac44
JH
1651=item Bad arg length for semctl, is XX, should be ZZZ
1652
1653If you get this error message from the lib/ipc_sysv test, your System
1654V IPC may be broken. The XX typically is 20, and that is what ZZZ
1655also should be. Consider upgrading your OS, or reconfiguring your OS
1656to include the System V semaphores.
1657
220f3621
GS
1658=item lib/ipc_sysv........semget: No space left on device
1659
1660Either your account or the whole system has run out of semaphores. Or
1661both. Either list the semaphores with "ipcs" and remove the unneeded
1662ones (which ones these are depends on your system and applications)
1663with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
1664system.
1665
d6baa268
JH
1666=item GNU binutils
1667
1668If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
1669tools you may be in for some trouble. For example creating archives
1670with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
1671may lead into linking problems. Either recompile your GNU binutils
1672under your current operating system release, or modify your PATH not
1673to include the GNU utils before running Configure, or specify the
1674vendor-supplied utilities explicitly to Configure, for example by
1675Configure -Dar=/bin/ar.
1676
16dc217a
GS
1677=item THIS PACKAGE SEEMS TO BE INCOMPLETE
1678
1679The F<Configure> program has not been able to find all the files which
1680make up the complete Perl distribution. You may have a damaged source
1681archive file (in which case you may also have seen messages such as
1682C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on
1683archive file>), or you may have obtained a structurally-sound but
1684incomplete archive. In either case, try downloading again from the
1685official site named at the start of this document. If you do find
1686that any site is carrying a corrupted or incomplete source code
1687archive, please report it to the site's maintainer.
1688
16dc217a
GS
1689=item invalid token: ##
1690
1691You are using a non-ANSI-compliant C compiler. See L<WARNING: This
1692version requires a compiler that supports ANSI C>.
1693
1ec51d55 1694=item Miscellaneous
8e07c86e
AD
1695
1696Some additional things that have been reported for either perl4 or perl5:
1697
1698Genix may need to use libc rather than libc_s, or #undef VARARGS.
1699
1700NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
1701
1ec51d55 1702UTS may need one or more of -DCRIPPLED_CC, -K or -g, and undef LSTAT.
8e07c86e 1703
220f3621
GS
1704FreeBSD can fail the lib/ipc_sysv.t test if SysV IPC has not been
1705configured to the kernel. Perl tries to detect this, though, and
1706you will get a message telling what to do.
6087ac44 1707
8e07c86e
AD
1708If you get syntax errors on '(', try -DCRIPPLED_CC.
1709
1710Machines with half-implemented dbm routines will need to #undef I_ODBM
1711
d6baa268
JH
1712HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
1713Patch Bundle" has been reported to break the io/fs test #18 which
1714tests whether utime() can change timestamps. The Y2K patch seems to
1715break utime() so that over NFS the timestamps do not get changed
1716(on local filesystems utime() still works).
1717
8e07c86e
AD
1718=back
1719
1720=head1 make test
1721
d6baa268
JH
1722This will run the regression tests on the perl you just made. If
1723'make test' doesn't say "All tests successful" then something went
1724wrong. See the file t/README in the t subdirectory.
84902520 1725
84902520 1726Note that you can't run the tests in background if this disables
fb73857a
PP
1727opening of /dev/tty. You can use 'make test-notty' in that case but
1728a few tty tests will be skipped.
c3edaffb 1729
c4f23d77
AD
1730=head2 What if make test doesn't work?
1731
1ec51d55
CS
1732If make test bombs out, just cd to the t directory and run ./TEST
1733by hand to see if it makes any difference. If individual tests
c3edaffb 1734bomb, you can run them by hand, e.g.,
8e07c86e
AD
1735
1736 ./perl op/groups.t
1737
aa689395 1738Another way to get more detailed information about failed tests and
1ec51d55 1739individual subtests is to cd to the t directory and run
aa689395
PP
1740
1741 ./perl harness
1742
fb73857a 1743(this assumes that most basic tests succeed, since harness uses
aa689395
PP
1744complicated constructs).
1745
fb73857a 1746You should also read the individual tests to see if there are any helpful
c3edaffb
PP
1747comments that apply to your system.
1748
c4f23d77
AD
1749=over 4
1750
1751=item locale
1752
1ec51d55 1753Note: One possible reason for errors is that some external programs
c07a80fd 1754may be broken due to the combination of your environment and the way
3fe9a6f1 1755B<make test> exercises them. For example, this may happen if you have
1ec51d55
CS
1756one or more of these environment variables set: LC_ALL LC_CTYPE
1757LC_COLLATE LANG. In some versions of UNIX, the non-English locales
e57fd563
PP
1758are known to cause programs to exhibit mysterious errors.
1759
1760If you have any of the above environment variables set, please try
aa689395
PP
1761
1762 setenv LC_ALL C
1763
1764(for C shell) or
1765
1766 LC_ALL=C;export LC_ALL
1767
1ec51d55
CS
1768for Bourne or Korn shell) from the command line and then retry
1769make test. If the tests then succeed, you may have a broken program that
aa689395 1770is confusing the testing. Please run the troublesome test by hand as
e57fd563 1771shown above and see whether you can locate the program. Look for
1ec51d55
CS
1772things like: exec, `backquoted command`, system, open("|...") or
1773open("...|"). All these mean that Perl is trying to run some
e57fd563 1774external program.
eed2e782 1775
c4f23d77
AD
1776=item Out of memory
1777
1778On some systems, particularly those with smaller amounts of RAM, some
1779of the tests in t/op/pat.t may fail with an "Out of memory" message.
7970f296
GS
1780For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
1781test 85 will fail if run under either t/TEST or t/harness.
c4f23d77
AD
1782
1783Try stopping other jobs on the system and then running the test by itself:
1784
1785 cd t; ./perl op/pat.t
1786
1787to see if you have any better luck. If your perl still fails this
1788test, it does not necessarily mean you have a broken perl. This test
1789tries to exercise the regular expression subsystem quite thoroughly,
1790and may well be far more demanding than your normal usage.
1791
781948c1
JH
1792=item Test failures from lib/ftmp-security saying "system possibly insecure"
1793
1794Firstly, test failures from the ftmp-security are not necessarily
1795serious or indicative of a real security threat. That being said,
1796they bear investigating.
1797
1798The tests may fail for the following reasons. Note that each of the
1799tests is run both in the building directory and the temporary
1800directory, as returned by File::Spec->tmpdir().
1801
1802(1) If the directory the tests are being run is owned by somebody else
1803than the user running the tests, or root (uid 0). This failure can
1804happen if the Perl source code distribution is unpacked in a way that
1805the user ids in the distribution package are used as-is. Some tar
1806programs do this.
1807
1808(2) If the directory the test are being run in is writable by group
1809or by other (remember: with UNIX/POSIX semantics, write access to
1810a directory means the right to add/remove files in that directory),
1811and there is no sticky bit set in the directory. 'Sticky bit' is
1812a feature used in some UNIXes to give extra protection to files: if
1813the bit is on a directory, no one but the owner (or the root) can remove
1814that file even if the permissions of the directory would allow file
1815removal by others. This failure can happen if the permissions in the
1816directory simply are a bit too liberal for the tests' liking. This
1817may or may not be a real problem: it depends on the permissions policy
1818used on this particular directory/project/system/site. This failure
1819can also happen if the system either doesn't support the sticky bit
1820(this is the case with many non-UNIX platforms: in principle the
1821File::Temp should know about these platforms and skip the tests), or
1822if the system supports the sticky bit but for some reason or reasons
1823it is not being used. This is for example the case with HP-UX: as of
1824HP-UX release 11.00, the sticky bit is very much supported, but HP-UX
1825doesn't use it on its /tmp directory as shipped. Also as with the
1826permissions, some local policy might dictate that the stickiness is
1827not used.
1828
b2b23189
JH
1829(3) If the system supports the POSIX 'chown giveaway' feature and if
1830any of the parent directories of the temporary file back to the root
1831directory are 'unsafe', using the definitions given above in (1) and
1832(2).
781948c1
JH
1833
1834See the documentation for the File::Temp module for more information
1835about the various security aspects.
1836
c4f23d77
AD
1837=back
1838
8e07c86e
AD
1839=head1 make install
1840
1841This will put perl into the public directory you specified to
1ec51d55 1842Configure; by default this is /usr/local/bin. It will also try
8e07c86e 1843to put the man pages in a reasonable place. It will not nroff the man
aa689395 1844pages, however. You may need to be root to run B<make install>. If you
8e07c86e
AD
1845are not root, you must own the directories in question and you should
1846ignore any messages about chown not working.
1847
dd64f1c3
AD
1848=head2 Installing perl under different names
1849
1850If you want to install perl under a name other than "perl" (for example,
1851when installing perl with special features enabled, such as debugging),
1852indicate the alternate name on the "make install" line, such as:
1853
1854 make install PERLNAME=myperl
1855
beb13193
RS
1856You can separately change the base used for versioned names (like
1857"perl5.005") by setting PERLNAME_VERBASE, like
1858
1859 make install PERLNAME=perl5 PERLNAME_VERBASE=perl
1860
1861This can be useful if you have to install perl as "perl5" (due to an
1862ancient version in /usr/bin supplied by your vendor, eg). Without this
1863the versioned binary would be called "perl55.005".
1864
dd64f1c3
AD
1865=head2 Installed files
1866
8e07c86e
AD
1867If you want to see exactly what will happen without installing
1868anything, you can run
4633a7c4 1869
8e07c86e
AD
1870 ./perl installperl -n
1871 ./perl installman -n
1872
1ec51d55 1873make install will install the following:
8e07c86e 1874
d56c5707
JH
1875 binaries
1876
8e07c86e
AD
1877 perl,
1878 perl5.nnn where nnn is the current release number. This
1879 will be a link to perl.
1880 suidperl,
1881 sperl5.nnn If you requested setuid emulation.
1882 a2p awk-to-perl translator
d56c5707
JH
1883
1884 scripts
1885
8e07c86e
AD
1886 cppstdin This is used by perl -P, if your cc -E can't
1887 read from stdin.
1888 c2ph, pstruct Scripts for handling C structures in header files.
1889 s2p sed-to-perl translator
1890 find2perl find-to-perl translator
aa689395 1891 h2ph Extract constants and simple macros from C headers
8e07c86e 1892 h2xs Converts C .h header files to Perl extensions.
24b3df7f 1893 perlbug Tool to report bugs in Perl.
8e07c86e 1894 perldoc Tool to read perl's pod documentation.
aa689395 1895 pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules
8e07c86e 1896 pod2html, Converters from perl's pod documentation format
aa689395 1897 pod2latex, to other useful formats.
d56c5707
JH
1898 pod2man,
1899 pod2text,
1900 pod2checker,
1901 pod2select,
1902 pod2usage
aa689395 1903 splain Describe Perl warnings and errors
95667ae4 1904 dprofpp Perl code profile post-processor
8e07c86e 1905
d56c5707
JH
1906 library files
1907
1908 in $privlib and $archlib specified to
8e07c86e 1909 Configure, usually under /usr/local/lib/perl5/.
d56c5707
JH
1910
1911 documentation
1912
d6baa268
JH
1913 man pages in $man1dir, usually /usr/local/man/man1.
1914 module man
1915 pages in $man3dir, usually /usr/local/man/man3.
8e07c86e
AD
1916 pod/*.pod in $privlib/pod/.
1917
d6baa268
JH
1918Installperl will also create the directories listed above
1919in L<"Installation Directories">.
4633a7c4 1920
d56c5707 1921Perl's *.h header files and the libperl library are also installed
d6baa268 1922under $archlib so that any user may later build new modules, run the
56c6f531
JH
1923optional Perl compiler, or embed the perl interpreter into another
1924program even if the Perl source is no longer available.
8e07c86e 1925
d56c5707
JH
1926Sometimes you only want to install the version-specific parts of the perl
1927installation. For example, you may wish to install a newer version of
1928perl alongside an already installed production version of perl without
1929disabling installation of new modules for the production version.
1930To only install the version-specific parts of the perl installation, run
1931
1932 Configure -Dversiononly
1933
1934or answer 'y' to the appropriate Configure prompt. Alternatively,
1935you can just manually run
1936
1937 ./perl installperl -v
1938
1939and skip installman altogether.
1940See also L<"Maintaining completely separate versions"> for another
1941approach.
1942
aa689395 1943=head1 Coexistence with earlier versions of perl5
4633a7c4 1944
693762b4
AD
1945In general, you can usually safely upgrade from one version of Perl (e.g.
19465.004_04) to another similar version (e.g. 5.004_05) without re-compiling
1947all of your add-on extensions. You can also safely leave the old version
1948around in case the new version causes you problems for some reason.
1949For example, if you want to be sure that your script continues to run
dc45a647 1950with 5.004_04, simply replace the '#!/usr/local/bin/perl' line at the
693762b4
AD
1951top of the script with the particular version you want to run, e.g.
1952#!/usr/local/bin/perl5.00404.
1953
693762b4
AD
1954Most extensions will probably not need to be recompiled to use
1955with a newer version of perl. Here is how it is supposed to work.
1956(These examples assume you accept all the Configure defaults.)
1957
d6baa268
JH
1958Suppose you already have version 5.005_03 installed. The directories
1959searched by 5.005_03 are
1960
1961 /usr/local/lib/perl5/5.00503/$archname
1962 /usr/local/lib/perl5/5.00503
1963 /usr/local/lib/perl5/site_perl/5.005/$archname
1964 /usr/local/lib/perl5/site_perl/5.005
1965
0a08c020
GS
1966Beginning with 5.6.0 the version number in the site libraries are
1967fully versioned. Now, suppose you install version 5.6.0. The directories
1968searched by version 5.6.0 will be
d6baa268 1969
0a08c020
GS
1970 /usr/local/lib/perl5/5.6.0/$archname
1971 /usr/local/lib/perl5/5.6.0
1972 /usr/local/lib/perl5/site_perl/5.6.0/$archname
1973 /usr/local/lib/perl5/site_perl/5.6.0
d6baa268
JH
1974
1975 /usr/local/lib/perl5/site_perl/5.005/$archname
1976 /usr/local/lib/perl5/site_perl/5.005
c42e3e15 1977 /usr/local/lib/perl5/site_perl/
bfb7748a 1978
c42e3e15 1979Notice the last three entries -- Perl understands the default structure
d6baa268
JH
1980of the $sitelib directories and will look back in older, compatible
1981directories. This way, modules installed under 5.005_03 will continue
0a08c020 1982to be usable by 5.005_03 but will also accessible to 5.6.0. Further,
d6baa268 1983suppose that you upgrade a module to one which requires features
0a08c020
GS
1984present only in 5.6.0. That new module will get installed into
1985/usr/local/lib/perl5/site_perl/5.6.0 and will be available to 5.6.0,
d6baa268 1986but will not interfere with the 5.005_03 version.
bfb7748a 1987
c42e3e15
GS
1988The last entry, /usr/local/lib/perl5/site_perl/, is there so that
19895.6.0 will look for 5.004-era pure perl modules.
d6baa268 1990
0a08c020
GS
1991Lastly, suppose you now install version 5.6.1, which we'll assume is
1992binary compatible with 5.6.0 and 5.005. The directories searched
1993by 5.6.1 (if you don't change the Configure defaults) will be:
d6baa268 1994
265f5c4a
GS
1995 /usr/local/lib/perl5/5.6.1/$archname
1996 /usr/local/lib/perl5/5.6.1
0a08c020
GS
1997 /usr/local/lib/perl5/site_perl/5.6.1/$archname
1998 /usr/local/lib/perl5/site_perl/5.6.1
1999
2000 /usr/local/lib/perl5/site_perl/5.6.0/$archname
2001 /usr/local/lib/perl5/site_perl/5.6.0
d6baa268
JH
2002
2003 /usr/local/lib/perl5/site_perl/5.005/$archname
2004 /usr/local/lib/perl5/site_perl/5.005
2005 /usr/local/lib/perl5/site_perl/
bfb7748a 2006
0a08c020
GS
2007Assuming the users in your site are still actively using perl 5.6.0 and
20085.005 after you installed 5.6.1, you can continue to install add-on
2009extensions using any of perl 5.6.1, 5.6.0, or 5.005. The installations
2010of these different versions remain distinct, but remember that the newer
2011versions of perl are automatically set up to search the site libraries of
2012the older ones. This means that installing a new extension with 5.005
2013will make it visible to all three versions. Later, if you install the
2014same extension using, say, perl 5.6.1, it will override the 5.005-installed
2015version, but only for perl 5.6.1.
2016
2017This way, you can choose to share compatible extensions, but also upgrade
2018to a newer version of an extension that may be incompatible with earlier
2019versions, without breaking the earlier versions' installations.
693762b4
AD
2020
2021=head2 Maintaining completely separate versions
4633a7c4 2022
1ec51d55 2023Many users prefer to keep all versions of perl in completely
d6baa268 2024separate directories. This guarantees that an update to one version
0a08c020
GS
2025won't interfere with another version. (The defaults guarantee this for
2026libraries after 5.6.0, but not for executables. TODO?) One convenient
2027way to do this is by using a separate prefix for each version, such as
d52d4e46 2028
46bb10fb 2029 sh Configure -Dprefix=/opt/perl5.004
d52d4e46 2030
46bb10fb 2031and adding /opt/perl5.004/bin to the shell PATH variable. Such users
d52d4e46
PP
2032may also wish to add a symbolic link /usr/local/bin/perl so that
2033scripts can still start with #!/usr/local/bin/perl.
2034
693762b4
AD
2035Others might share a common directory for maintenance sub-versions
2036(e.g. 5.004 for all 5.004_0x versions), but change directory with
2037each major version.
2038
6877a1cf
AD
2039If you are installing a development subversion, you probably ought to
2040seriously consider using a separate directory, since development
2041subversions may not have all the compatibility wrinkles ironed out
2042yet.
2043
0a08c020 2044=head2 Upgrading from 5.005 to 5.6.0
693762b4 2045
c42e3e15
GS
2046Most extensions built and installed with versions of perl
2047prior to 5.005_50 will not need to be recompiled to be used with
20485.6.0. If you find you do need to rebuild an extension with 5.6.0,
2049you may safely do so without disturbing the 5.005 installation.
2050(See L<"Coexistence with earlier versions of perl5"> above.)
2051
2052See your installed copy of the perllocal.pod file for a (possibly
2053incomplete) list of locally installed modules. Note that you want
2054perllocal.pod not perllocale.pod for installed module information.
693762b4 2055
8e07c86e
AD
2056=head1 Coexistence with perl4
2057
2058You can safely install perl5 even if you want to keep perl4 around.
2059
1ec51d55
CS
2060By default, the perl5 libraries go into /usr/local/lib/perl5/, so
2061they don't override the perl4 libraries in /usr/local/lib/perl/.
8e07c86e
AD
2062
2063In your /usr/local/bin directory, you should have a binary named
1ec51d55 2064perl4.036. That will not be touched by the perl5 installation
8e07c86e
AD
2065process. Most perl4 scripts should run just fine under perl5.
2066However, if you have any scripts that require perl4, you can replace
d6baa268
JH
2067the #! line at the top of them by #!/usr/local/bin/perl4.036 (or
2068whatever the appropriate pathname is). See pod/perltrap.pod for
2069possible problems running perl4 scripts under perl5.
8e07c86e 2070
aa689395
PP
2071=head1 cd /usr/include; h2ph *.h sys/*.h
2072
d6baa268
JH
2073Some perl scripts need to be able to obtain information from the
2074system header files. This command will convert the most commonly used
1ec51d55 2075header files in /usr/include into files that can be easily interpreted
d6baa268
JH
2076by perl. These files will be placed in the architecture-dependent
2077library ($archlib) directory you specified to Configure.
aa689395 2078
d6baa268
JH
2079Note: Due to differences in the C and perl languages, the conversion
2080of the header files is not perfect. You will probably have to
2081hand-edit some of the converted files to get them to parse correctly.
2082For example, h2ph breaks spectacularly on type casting and certain
2083structures.
aa689395 2084
fb73857a 2085=head1 installhtml --help
aa689395 2086
3e3baf6d
TB
2087Some sites may wish to make perl documentation available in HTML
2088format. The installhtml utility can be used to convert pod
fb73857a 2089documentation into linked HTML files and install them.
aa689395 2090
d6baa268
JH
2091Currently, the supplied ./installhtml script does not make use of the
2092html Configure variables. This should be fixed in a future release.
2093
fb73857a 2094The following command-line is an example of one used to convert
3e3baf6d 2095perl documentation:
aa689395 2096
3e3baf6d
TB
2097 ./installhtml \
2098 --podroot=. \
2099 --podpath=lib:ext:pod:vms \
2100 --recurse \
2101 --htmldir=/perl/nmanual \
2102 --htmlroot=/perl/nmanual \
2103 --splithead=pod/perlipc \
2104 --splititem=pod/perlfunc \
2105 --libpods=perlfunc:perlguts:perlvar:perlrun:perlop \
2106 --verbose
2107
2108See the documentation in installhtml for more details. It can take
2109many minutes to execute a large installation and you should expect to
2110see warnings like "no title", "unexpected directive" and "cannot
2111resolve" as the files are processed. We are aware of these problems
2112(and would welcome patches for them).
aa689395 2113
fb73857a
PP
2114You may find it helpful to run installhtml twice. That should reduce
2115the number of "cannot resolve" warnings.
2116
aa689395
PP
2117=head1 cd pod && make tex && (process the latex files)
2118
2119Some sites may also wish to make the documentation in the pod/ directory
2120available in TeX format. Type
2121
2122 (cd pod && make tex && <process the latex files>)
2123
2124=head1 Reporting Problems
2125
bfb7748a
AD
2126If you have difficulty building perl, and none of the advice in this file
2127helps, and careful reading of the error message and the relevant manual
2128pages on your system doesn't help either, then you should send a message
7f2de2d2 2129to either the comp.lang.perl.misc newsgroup or to perlbug@perl.org with
bfb7748a 2130an accurate description of your problem.
aa689395 2131
bfb7748a
AD
2132Please include the output of the ./myconfig shell script that comes with
2133the distribution. Alternatively, you can use the perlbug program that
2134comes with the perl distribution, but you need to have perl compiled
2135before you can use it. (If you have not installed it yet, you need to
f5b3b617 2136run C<./perl -Ilib utils/perlbug> instead of a plain C<perlbug>.)
aa689395 2137
694a7e45
AD
2138Please try to make your message brief but clear. Trim out unnecessary
2139information. Do not include large files (such as config.sh or a complete
2140Configure or make log) unless absolutely necessary. Do not include a
2141complete transcript of your build session. Just include the failing
d6baa268 2142commands, the relevant error messages, and whatever preceding commands
694a7e45
AD
2143are necessary to give the appropriate context. Plain text should
2144usually be sufficient--fancy attachments or encodings may actually
2145reduce the number of people who read your message. Your message
2146will get relayed to over 400 subscribers around the world so please
2147try to keep it brief but clear.
aa689395 2148
8e07c86e
AD
2149=head1 DOCUMENTATION
2150
bfb7748a
AD
2151Read the manual entries before running perl. The main documentation
2152is in the pod/ subdirectory and should have been installed during the
8e07c86e 2153build process. Type B<man perl> to get started. Alternatively, you
bfb7748a
AD
2154can type B<perldoc perl> to use the supplied perldoc script. This is
2155sometimes useful for finding things in the library modules.
8e07c86e 2156
1ec51d55 2157Under UNIX, you can produce a documentation book in postscript form,
bfb7748a
AD
2158along with its table of contents, by going to the pod/ subdirectory and
2159running (either):
34a2a22e
RM
2160
2161 ./roffitall -groff # If you have GNU groff installed
aa689395 2162 ./roffitall -psroff # If you have psroff
34a2a22e
RM
2163
2164This will leave you with two postscript files ready to be printed.
aa689395
PP
2165(You may need to fix the roffitall command to use your local troff
2166set-up.)
34a2a22e 2167
bfb7748a
AD
2168Note that you must have performed the installation already before running
2169the above, since the script collects the installed files to generate
2170the documentation.
34a2a22e 2171
8e07c86e
AD
2172=head1 AUTHOR
2173
bfb7748a
AD
2174Original author: Andy Dougherty doughera@lafayette.edu , borrowing very
2175heavily from the original README by Larry Wall, with lots of helpful
2176feedback and additions from the perl5-porters@perl.org folks.
fb73857a 2177
f5b3b617
AD
2178If you have problems, corrections, or questions, please see
2179L<"Reporting Problems"> above.
2180
2181=head1 REDISTRIBUTION
2182
2183This document is part of the Perl package and may be distributed under
d6baa268 2184the same terms as perl itself, with the following additional request:
f5b3b617 2185If you are distributing a modified version of perl (perhaps as part of
d6baa268
JH
2186a larger package) please B<do> modify these installation instructions
2187and the contact information to match your distribution.
8e07c86e 2188
a5f75d66 2189=head1 LAST MODIFIED
24b3df7f 2190
d6baa268 2191$Id: INSTALL,v 1.58 1999/07/23 14:43:00 doughera Exp $