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