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