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