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