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