This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate change #11051 from macperl; O_RDONLY is not zero
[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
03739d21
JH
1415=head1 suidperl
1416
c80c8d62 1417suidperl is an optional component, which is built or installed by default.
03739d21
JH
1418From perlfaq1:
1419
1420 On some systems, setuid and setgid scripts (scripts written
1421 in the C shell, Bourne shell, or Perl, for example, with the
1422 set user or group ID permissions enabled) are insecure due to
1423 a race condition in the kernel. For those systems, Perl versions
1424 5 and 4 attempt to work around this vulnerability with an optional
1425 component, a special program named suidperl, also known as sperl.
1426 This program attempts to emulate the set-user-ID and set-group-ID
1427 features of the kernel.
1428
1429Because of the buggy history of suidperl, and the difficulty
1430of properly security auditing as large and complex piece of
1431software as Perl, we cannot recommend using suidperl and the feature
1432should be considered deprecated.
1433Instead use for example 'sudo': http://www.courtesan.com/sudo/
1434
8e07c86e
AD
1435=head1 make depend
1436
bfb7748a
AD
1437This will look for all the includes. The output is stored in makefile.
1438The only difference between Makefile and makefile is the dependencies at
1439the bottom of makefile. If you have to make any changes, you should edit
1440makefile, not Makefile since the Unix make command reads makefile first.
1441(On non-Unix systems, the output may be stored in a different file.
1442Check the value of $firstmakefile in your config.sh if in doubt.)
8e07c86e
AD
1443
1444Configure will offer to do this step for you, so it isn't listed
1445explicitly above.
1446
1447=head1 make
1448
1449This will attempt to make perl in the current directory.
1450
8d74ce1c
AD
1451=head2 What if it doesn't work?
1452
8e07c86e 1453If you can't compile successfully, try some of the following ideas.
7f678428 1454If none of them help, and careful reading of the error message and
8d74ce1c
AD
1455the relevant manual pages on your system doesn't help,
1456then see L<"Reporting Problems"> below.
8e07c86e
AD
1457
1458=over 4
1459
1ec51d55 1460=item hints
8e07c86e
AD
1461
1462If you used a hint file, try reading the comments in the hint file
1463for further tips and information.
1464
1ec51d55 1465=item extensions
8e07c86e 1466
1ec51d55 1467If you can successfully build miniperl, but the process crashes
c3edaffb
PP
1468during the building of extensions, you should run
1469
3a6175e1 1470 make minitest
c3edaffb
PP
1471
1472to test your version of miniperl.
1473
e57fd563
PP
1474=item locale
1475
bfb7748a
AD
1476If you have any locale-related environment variables set, try unsetting
1477them. I have some reports that some versions of IRIX hang while
1478running B<./miniperl configpm> with locales other than the C locale.
1479See the discussion under L<"make test"> below about locales and the
1480whole L<"Locale problems"> section in the file pod/perllocale.pod.
3e6e419a
JH
1481The latter is especially useful if you see something like this
1482
1483 perl: warning: Setting locale failed.
1484 perl: warning: Please check that your locale settings:
1485 LC_ALL = "En_US",
1486 LANG = (unset)
1487 are supported and installed on your system.
1488 perl: warning: Falling back to the standard locale ("C").
1489
1490at Perl startup.
e57fd563 1491
7f678428 1492=item varargs
c3edaffb
PP
1493
1494If you get varargs problems with gcc, be sure that gcc is installed
bfb7748a
AD
1495correctly and that you are not passing -I/usr/include to gcc. When using
1496gcc, you should probably have i_stdarg='define' and i_varargs='undef'
1497in config.sh. The problem is usually solved by running fixincludes
1498correctly. If you do change config.sh, don't forget to propagate
1499your changes (see L<"Propagating your changes to config.sh"> below).
7f678428 1500See also the L<"vsprintf"> item below.
c3edaffb 1501
bfb7748a 1502=item util.c
c3edaffb
PP
1503
1504If you get error messages such as the following (the exact line
bfb7748a 1505numbers and function name may vary in different versions of perl):
c3edaffb 1506
bfb7748a
AD
1507 util.c: In function `Perl_form':
1508 util.c:1107: number of arguments doesn't match prototype
1509 proto.h:125: prototype declaration
c3edaffb
PP
1510
1511it might well be a symptom of the gcc "varargs problem". See the
7f678428 1512previous L<"varargs"> item.
c3edaffb 1513
1ec51d55 1514=item LD_LIBRARY_PATH
c3edaffb
PP
1515
1516If you run into dynamic loading problems, check your setting of
aa689395
PP
1517the LD_LIBRARY_PATH environment variable. If you're creating a static
1518Perl library (libperl.a rather than libperl.so) it should build
c3edaffb
PP
1519fine with LD_LIBRARY_PATH unset, though that may depend on details
1520of your local set-up.
1521
aa689395 1522=item nm extraction
c3edaffb
PP
1523
1524If Configure seems to be having trouble finding library functions,
1525try not using nm extraction. You can do this from the command line
1526with
1527
1528 sh Configure -Uusenm
1529
1530or by answering the nm extraction question interactively.
1ec51d55 1531If you have previously run Configure, you should not reuse your old
c3edaffb
PP
1532config.sh.
1533
bfb7748a
AD
1534=item umask not found
1535
1536If the build processes encounters errors relating to umask(), the problem
1537is probably that Configure couldn't find your umask() system call.
1538Check your config.sh. You should have d_umask='define'. If you don't,
1539this is probably the L<"nm extraction"> problem discussed above. Also,
1540try reading the hints file for your system for further information.
1541
7f678428 1542=item vsprintf
c3edaffb
PP
1543
1544If you run into problems with vsprintf in compiling util.c, the
1545problem is probably that Configure failed to detect your system's
1546version of vsprintf(). Check whether your system has vprintf().
1547(Virtually all modern Unix systems do.) Then, check the variable
1548d_vprintf in config.sh. If your system has vprintf, it should be:
1549
1550 d_vprintf='define'
1551
1552If Configure guessed wrong, it is likely that Configure guessed wrong
bfb7748a
AD
1553on a number of other common functions too. This is probably
1554the L<"nm extraction"> problem discussed above.
c3edaffb 1555
3fe9a6f1
PP
1556=item do_aspawn
1557
1558If you run into problems relating to do_aspawn or do_spawn, the
1559problem is probably that Configure failed to detect your system's
bfb7748a
AD
1560fork() function. Follow the procedure in the previous item
1561on L<"nm extraction">.
3fe9a6f1 1562
84902520
TB
1563=item __inet_* errors
1564
1565If you receive unresolved symbol errors during Perl build and/or test
1566referring to __inet_* symbols, check to see whether BIND 8.1 is
1567installed. It installs a /usr/local/include/arpa/inet.h that refers to
1568these symbols. Versions of BIND later than 8.1 do not install inet.h
1569in that location and avoid the errors. You should probably update to a
1570newer version of BIND. If you can't, you can either link with the
1571updated resolver library provided with BIND 8.1 or rename
1572/usr/local/bin/arpa/inet.h during the Perl build and test process to
1573avoid the problem.
1574
d6baa268
JH
1575=item #error "No DATAMODEL_NATIVE specified"
1576
1577This is a common error when trying to build perl on Solaris 2.6 with a
1578gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files
1579changed, so you need to update your gcc installation. You can either
1580rerun the fixincludes script from gcc or take the opportunity to
1581update your gcc installation.
1582
aa689395 1583=item Optimizer
c3edaffb 1584
9d67150a 1585If you can't compile successfully, try turning off your compiler's
aa689395 1586optimizer. Edit config.sh and change the line
9d67150a
PP
1587
1588 optimize='-O'
1589
bfb7748a 1590to
9d67150a
PP
1591
1592 optimize=' '
1593
1594then propagate your changes with B<sh Configure -S> and rebuild
1595with B<make depend; make>.
1596
1ec51d55 1597=item CRIPPLED_CC
9d67150a 1598
1b1c1ae2
GS
1599If you still can't compile successfully, try:
1600
1601 sh Configure -Accflags=-DCRIPPLED_CC
1602
1603This flag simplifies some complicated expressions for compilers that get
1604indigestion easily. (Just because you get no errors doesn't mean it
1605compiled right!)
9d67150a
PP
1606
1607=item Missing functions
1608
1609If you have missing routines, you probably need to add some library or
1610other, or you need to undefine some feature that Configure thought was
1611there but is defective or incomplete. Look through config.h for
bfb7748a
AD
1612likely suspects. If Configure guessed wrong on a number of functions,
1613you might have the L<"nm extraction"> problem discussed above.
8e07c86e 1614
1ec51d55 1615=item toke.c
8e07c86e 1616
1ec51d55
CS
1617Some compilers will not compile or optimize the larger files (such as
1618toke.c) without some extra switches to use larger jump offsets or
1619allocate larger internal tables. You can customize the switches for
1620each file in cflags. It's okay to insert rules for specific files into
1621makefile since a default rule only takes effect in the absence of a
8e07c86e
AD
1622specific rule.
1623
7f678428 1624=item Missing dbmclose
8e07c86e 1625
c3edaffb
PP
1626SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
1627that includes libdbm.nfs (which includes dbmclose()) may be available.
8e07c86e 1628
f3d9a6ba 1629=item Note (probably harmless): No library found for -lsomething
7f678428
PP
1630
1631If you see such a message during the building of an extension, but
1632the extension passes its tests anyway (see L<"make test"> below),
1633then don't worry about the warning message. The extension
1634Makefile.PL goes looking for various libraries needed on various
aa689395 1635systems; few systems will need all the possible libraries listed.
7f678428
PP
1636For example, a system may have -lcposix or -lposix, but it's
1637unlikely to have both, so most users will see warnings for the one
f3d9a6ba
CS
1638they don't have. The phrase 'probably harmless' is intended to
1639reassure you that nothing unusual is happening, and the build
1640process is continuing.
7f678428
PP
1641
1642On the other hand, if you are building GDBM_File and you get the
1643message
1644
f3d9a6ba 1645 Note (probably harmless): No library found for -lgdbm
7f678428
PP
1646
1647then it's likely you're going to run into trouble somewhere along
1648the line, since it's hard to see how you can use the GDBM_File
1649extension without the -lgdbm library.
1650
1651It is true that, in principle, Configure could have figured all of
1652this out, but Configure and the extension building process are not
1653quite that tightly coordinated.
1654
aa689395
PP
1655=item sh: ar: not found
1656
1657This is a message from your shell telling you that the command 'ar'
1658was not found. You need to check your PATH environment variable to
1659make sure that it includes the directory with the 'ar' command. This
1ec51d55 1660is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
aa689395
PP
1661directory.
1662
1663=item db-recno failure on tests 51, 53 and 55
1664
1665Old versions of the DB library (including the DB library which comes
1666with FreeBSD 2.1) had broken handling of recno databases with modified
1667bval settings. Upgrade your DB library or OS.
1668
6087ac44
JH
1669=item Bad arg length for semctl, is XX, should be ZZZ
1670
1671If you get this error message from the lib/ipc_sysv test, your System
1672V IPC may be broken. The XX typically is 20, and that is what ZZZ
1673also should be. Consider upgrading your OS, or reconfiguring your OS
1674to include the System V semaphores.
1675
220f3621
GS
1676=item lib/ipc_sysv........semget: No space left on device
1677
1678Either your account or the whole system has run out of semaphores. Or
1679both. Either list the semaphores with "ipcs" and remove the unneeded
1680ones (which ones these are depends on your system and applications)
1681with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
1682system.
1683
d6baa268
JH
1684=item GNU binutils
1685
1686If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
1687tools you may be in for some trouble. For example creating archives
1688with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
1689may lead into linking problems. Either recompile your GNU binutils
1690under your current operating system release, or modify your PATH not
1691to include the GNU utils before running Configure, or specify the
1692vendor-supplied utilities explicitly to Configure, for example by
1693Configure -Dar=/bin/ar.
1694
16dc217a
GS
1695=item THIS PACKAGE SEEMS TO BE INCOMPLETE
1696
1697The F<Configure> program has not been able to find all the files which
1698make up the complete Perl distribution. You may have a damaged source
1699archive file (in which case you may also have seen messages such as
1700C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on
1701archive file>), or you may have obtained a structurally-sound but
1702incomplete archive. In either case, try downloading again from the
1703official site named at the start of this document. If you do find
1704that any site is carrying a corrupted or incomplete source code
1705archive, please report it to the site's maintainer.
1706
16dc217a
GS
1707=item invalid token: ##
1708
1709You are using a non-ANSI-compliant C compiler. See L<WARNING: This
1710version requires a compiler that supports ANSI C>.
1711
1ec51d55 1712=item Miscellaneous
8e07c86e
AD
1713
1714Some additional things that have been reported for either perl4 or perl5:
1715
1716Genix may need to use libc rather than libc_s, or #undef VARARGS.
1717
1718NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
1719
1ec51d55 1720UTS may need one or more of -DCRIPPLED_CC, -K or -g, and undef LSTAT.
8e07c86e 1721
220f3621
GS
1722FreeBSD can fail the lib/ipc_sysv.t test if SysV IPC has not been
1723configured to the kernel. Perl tries to detect this, though, and
1724you will get a message telling what to do.
6087ac44 1725
8e07c86e
AD
1726If you get syntax errors on '(', try -DCRIPPLED_CC.
1727
1728Machines with half-implemented dbm routines will need to #undef I_ODBM
1729
d6baa268
JH
1730HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
1731Patch Bundle" has been reported to break the io/fs test #18 which
1732tests whether utime() can change timestamps. The Y2K patch seems to
1733break utime() so that over NFS the timestamps do not get changed
1734(on local filesystems utime() still works).
1735
8e07c86e
AD
1736=back
1737
58a21a9b
JH
1738=head2 Cross-compilation
1739
1740Starting from Perl 5.8 Perl has the beginnings of cross-compilation
1741support. What is known to work is running Configure in a
1742cross-compilation environment and building the miniperl executable.
65090350 1743What is known not to work is building the perl executable because
58a21a9b
JH
1744that would require building extensions: Dynaloader statically and
1745File::Glob dynamically, for extensions one needs MakeMaker and
1746MakeMaker is not yet cross-compilation aware, and neither is
1747the main Makefile.
1748
93bc48fa
JH
1749Since the functionality is so lacking, it must be considered
1750highly experimental. It is so experimental that it is not even
c80c8d62 1751mentioned during an interactive Configure session, a direct command
93bc48fa
JH
1752line invocation (detailed shortly) is required to access the
1753functionality.
1754
58a21a9b
JH
1755 NOTE: Perl is routinely built using cross-compilation
1756 in the EPOC environment but the solutions from there
93bc48fa 1757 can't directly be used elsewhere.
58a21a9b
JH
1758
1759The one environment where cross-compilation has successfully been used
1760as of this writing is the Compaq iPAQ running ARM Linux. The build
93bc48fa
JH
1761host was Intel Linux, the networking setup was PPP + SSH. The exact
1762setup details are beyond the scope of this document, see
58a21a9b
JH
1763http://www.handhelds.org/ for more information.
1764
1765To run Configure in cross-compilation mode the basic switch is
1766C<-Dusecrosscompile>.
1767
1768 sh ./Configure -des -Dusecrosscompile -D...
1769
1770This will make the cpp symbol USE_CROSS_COMPILE and the %Config
1771symbol C<usecrosscompile> available.
1772
1773During the Configure and build, certain helper scripts will be created
1774into the Cross/ subdirectory. The scripts are used to execute a
1775cross-compiled executable, and to transfer files to and from the
1776target host. The execution scripts are named F<run-*> and the
1777transfer scripts F<to-*> and F<from-*>. The part after the dash is
1778the method to use for remote execution and transfer: by default the
1779methods are B<ssh> and B<scp>, thus making the scripts F<run-ssh>,
1780F<to-scp>, and F<from-scp>.
1781
1782To configure the scripts for a target host and a directory (in which
1783the execution will happen and which is to and from where the transfer
1784happens), supply Configure with
1785
1786 -Dtargethost=so.me.ho.st -Dtargetdir=/tar/get/dir
1787
1788The targethost is what e.g. ssh will use as the hostname, the targetdir
93bc48fa
JH
1789must exist (the scripts won't create it), the targetdir defaults to /tmp.
1790You can also specify a username to use for ssh/rsh logins
58a21a9b
JH
1791
1792 -Dtargetuser=luser
1793
1794but in case you don't, "root" will be used.
1795
93bc48fa
JH
1796Because this is a cross-compilation effort, you will also need to specify
1797which target environment and which compilation environment to use.
1798This includes the compiler, the header files, and the libraries.
1799In the below we use the usual settings for the iPAQ cross-compilation
1800environment:
58a21a9b
JH
1801
1802 -Dtargetarch=arm-linux
1803 -Dcc=arm-linux-gcc
1804 -Dusrinc=/skiff/local/arm-linux/include
1805 -Dincpth=/skiff/local/arm-linux/include
1806 -Dlibpth=/skiff/local/arm-linux/lib
1807
1808If the name of the C<cc> has the usual GNU C semantics for cross
1809compilers, that is, CPU-OS-gcc, the names of the C<ar>, C<nm>, and
1810C<ranlib> will also be automatically chosen to be CPU-OS-ar and so on.
93bc48fa
JH
1811(The C<ld> requires more thought and will be chosen later by Configure
1812as appropriate.) Also, in this case the incpth, libpth, and usrinc
1813will be guessed by Configure (unless explicitly set to something else,
1814in which case Configure's guesses with be appended).
58a21a9b
JH
1815
1816In addition to the default execution/transfer methods you can also
1817choose B<rsh> for execution, and B<rcp> or B<cp> for transfer,
1818for example:
1819
1820 -Dtargetrun=rsh -Dtargetto=rcp -Dtargetfrom=cp
1821
1822Putting it all together:
1823
1824 sh ./Configure -des -Dusecrosscompile \
93bc48fa
JH
1825 -Dtargethost=so.me.ho.st \
1826 -Dtargetdir=/tar/get/dir \
58a21a9b
JH
1827 -Dtargetuser=root \
1828 -Dtargetarch=arm-linux \
1829 -Dcc=arm-linux-gcc \
1830 -Dusrinc=/skiff/local/arm-linux/include \
1831 -Dincpth=/skiff/local/arm-linux/include \
1832 -Dlibpth=/skiff/local/arm-linux/lib \
1833 -D...
1834
93bc48fa
JH
1835or if you are happy with the defaults
1836
1837 sh ./Configure -des -Dusecrosscompile \
1838 -Dtargethost=so.me.ho.st \
1839 -Dcc=arm-linux-gcc \
1840 -D...
1841
8e07c86e
AD
1842=head1 make test
1843
d6baa268
JH
1844This will run the regression tests on the perl you just made. If
1845'make test' doesn't say "All tests successful" then something went
1846wrong. See the file t/README in the t subdirectory.
84902520 1847
84902520 1848Note that you can't run the tests in background if this disables
fb73857a
PP
1849opening of /dev/tty. You can use 'make test-notty' in that case but
1850a few tty tests will be skipped.
c3edaffb 1851
c4f23d77
AD
1852=head2 What if make test doesn't work?
1853
1ec51d55
CS
1854If make test bombs out, just cd to the t directory and run ./TEST
1855by hand to see if it makes any difference. If individual tests
c3edaffb 1856bomb, you can run them by hand, e.g.,
8e07c86e
AD
1857
1858 ./perl op/groups.t
1859
aa689395 1860Another way to get more detailed information about failed tests and
1ec51d55 1861individual subtests is to cd to the t directory and run
aa689395
PP
1862
1863 ./perl harness
1864
fb73857a 1865(this assumes that most basic tests succeed, since harness uses
aa689395
PP
1866complicated constructs).
1867
fb73857a 1868You should also read the individual tests to see if there are any helpful
c3edaffb
PP
1869comments that apply to your system.
1870
c4f23d77
AD
1871=over 4
1872
1873=item locale
1874
1ec51d55 1875Note: One possible reason for errors is that some external programs
c07a80fd 1876may be broken due to the combination of your environment and the way
3fe9a6f1 1877B<make test> exercises them. For example, this may happen if you have
1ec51d55
CS
1878one or more of these environment variables set: LC_ALL LC_CTYPE
1879LC_COLLATE LANG. In some versions of UNIX, the non-English locales
e57fd563
PP
1880are known to cause programs to exhibit mysterious errors.
1881
1882If you have any of the above environment variables set, please try
aa689395
PP
1883
1884 setenv LC_ALL C
1885
1886(for C shell) or
1887
1888 LC_ALL=C;export LC_ALL
1889
1ec51d55
CS
1890for Bourne or Korn shell) from the command line and then retry
1891make test. If the tests then succeed, you may have a broken program that
aa689395 1892is confusing the testing. Please run the troublesome test by hand as
e57fd563 1893shown above and see whether you can locate the program. Look for
1ec51d55
CS
1894things like: exec, `backquoted command`, system, open("|...") or
1895open("...|"). All these mean that Perl is trying to run some
e57fd563 1896external program.
eed2e782 1897
c4f23d77
AD
1898=item Out of memory
1899
1900On some systems, particularly those with smaller amounts of RAM, some
1901of the tests in t/op/pat.t may fail with an "Out of memory" message.
7970f296
GS
1902For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
1903test 85 will fail if run under either t/TEST or t/harness.
c4f23d77
AD
1904
1905Try stopping other jobs on the system and then running the test by itself:
1906
1907 cd t; ./perl op/pat.t
1908
1909to see if you have any better luck. If your perl still fails this
1910test, it does not necessarily mean you have a broken perl. This test
1911tries to exercise the regular expression subsystem quite thoroughly,
1912and may well be far more demanding than your normal usage.
1913
781948c1
JH
1914=item Test failures from lib/ftmp-security saying "system possibly insecure"
1915
1916Firstly, test failures from the ftmp-security are not necessarily
1917serious or indicative of a real security threat. That being said,
1918they bear investigating.
1919
1920The tests may fail for the following reasons. Note that each of the
1921tests is run both in the building directory and the temporary
1922directory, as returned by File::Spec->tmpdir().
1923
1924(1) If the directory the tests are being run is owned by somebody else
1925than the user running the tests, or root (uid 0). This failure can
1926happen if the Perl source code distribution is unpacked in a way that
1927the user ids in the distribution package are used as-is. Some tar
1928programs do this.
1929
1930(2) If the directory the test are being run in is writable by group
1931or by other (remember: with UNIX/POSIX semantics, write access to
1932a directory means the right to add/remove files in that directory),
1933and there is no sticky bit set in the directory. 'Sticky bit' is
1934a feature used in some UNIXes to give extra protection to files: if
1935the bit is on a directory, no one but the owner (or the root) can remove
1936that file even if the permissions of the directory would allow file
1937removal by others. This failure can happen if the permissions in the
1938directory simply are a bit too liberal for the tests' liking. This
1939may or may not be a real problem: it depends on the permissions policy
1940used on this particular directory/project/system/site. This failure
1941can also happen if the system either doesn't support the sticky bit
1942(this is the case with many non-UNIX platforms: in principle the
1943File::Temp should know about these platforms and skip the tests), or
1944if the system supports the sticky bit but for some reason or reasons
1945it is not being used. This is for example the case with HP-UX: as of
1946HP-UX release 11.00, the sticky bit is very much supported, but HP-UX
1947doesn't use it on its /tmp directory as shipped. Also as with the
1948permissions, some local policy might dictate that the stickiness is
1949not used.
1950
b2b23189
JH
1951(3) If the system supports the POSIX 'chown giveaway' feature and if
1952any of the parent directories of the temporary file back to the root
1953directory are 'unsafe', using the definitions given above in (1) and
1954(2).
781948c1
JH
1955
1956See the documentation for the File::Temp module for more information
1957about the various security aspects.
1958
c4f23d77
AD
1959=back
1960
8e07c86e
AD
1961=head1 make install
1962
1963This will put perl into the public directory you specified to
1ec51d55 1964Configure; by default this is /usr/local/bin. It will also try
8e07c86e 1965to put the man pages in a reasonable place. It will not nroff the man
aa689395 1966pages, however. You may need to be root to run B<make install>. If you
8e07c86e
AD
1967are not root, you must own the directories in question and you should
1968ignore any messages about chown not working.
1969
dd64f1c3
AD
1970=head2 Installing perl under different names
1971
1972If you want to install perl under a name other than "perl" (for example,
1973when installing perl with special features enabled, such as debugging),
1974indicate the alternate name on the "make install" line, such as:
1975
1976 make install PERLNAME=myperl
1977
beb13193
RS
1978You can separately change the base used for versioned names (like
1979"perl5.005") by setting PERLNAME_VERBASE, like
1980
1981 make install PERLNAME=perl5 PERLNAME_VERBASE=perl
1982
1983This can be useful if you have to install perl as "perl5" (due to an
1984ancient version in /usr/bin supplied by your vendor, eg). Without this
1985the versioned binary would be called "perl55.005".
1986
dd64f1c3
AD
1987=head2 Installed files
1988
8e07c86e
AD
1989If you want to see exactly what will happen without installing
1990anything, you can run
4633a7c4 1991
8e07c86e
AD
1992 ./perl installperl -n
1993 ./perl installman -n
1994
1ec51d55 1995make install will install the following:
8e07c86e 1996
d56c5707
JH
1997 binaries
1998
8e07c86e
AD
1999 perl,
2000 perl5.nnn where nnn is the current release number. This
2001 will be a link to perl.
2002 suidperl,
2003 sperl5.nnn If you requested setuid emulation.
2004 a2p awk-to-perl translator
d56c5707
JH
2005
2006 scripts
2007
8e07c86e
AD
2008 cppstdin This is used by perl -P, if your cc -E can't
2009 read from stdin.
2010 c2ph, pstruct Scripts for handling C structures in header files.
2011 s2p sed-to-perl translator
2012 find2perl find-to-perl translator
aa689395 2013 h2ph Extract constants and simple macros from C headers
8e07c86e 2014 h2xs Converts C .h header files to Perl extensions.
24b3df7f 2015 perlbug Tool to report bugs in Perl.
8e07c86e 2016 perldoc Tool to read perl's pod documentation.
aa689395 2017 pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules
8e07c86e 2018 pod2html, Converters from perl's pod documentation format
aa689395 2019 pod2latex, to other useful formats.
d56c5707
JH
2020 pod2man,
2021 pod2text,
2022 pod2checker,
2023 pod2select,
2024 pod2usage
aa689395 2025 splain Describe Perl warnings and errors
95667ae4 2026 dprofpp Perl code profile post-processor
8e07c86e 2027
d56c5707
JH
2028 library files
2029
2030 in $privlib and $archlib specified to
8e07c86e 2031 Configure, usually under /usr/local/lib/perl5/.
d56c5707
JH
2032
2033 documentation
2034
d6baa268
JH
2035 man pages in $man1dir, usually /usr/local/man/man1.
2036 module man
2037 pages in $man3dir, usually /usr/local/man/man3.
8e07c86e
AD
2038 pod/*.pod in $privlib/pod/.
2039
d6baa268
JH
2040Installperl will also create the directories listed above
2041in L<"Installation Directories">.
4633a7c4 2042
d56c5707 2043Perl's *.h header files and the libperl library are also installed
d6baa268 2044under $archlib so that any user may later build new modules, run the
56c6f531
JH
2045optional Perl compiler, or embed the perl interpreter into another
2046program even if the Perl source is no longer available.
8e07c86e 2047
d56c5707
JH
2048Sometimes you only want to install the version-specific parts of the perl
2049installation. For example, you may wish to install a newer version of
2050perl alongside an already installed production version of perl without
2051disabling installation of new modules for the production version.
2052To only install the version-specific parts of the perl installation, run
2053
2054 Configure -Dversiononly
2055
2056or answer 'y' to the appropriate Configure prompt. Alternatively,
2057you can just manually run
2058
2059 ./perl installperl -v
2060
2061and skip installman altogether.
2062See also L<"Maintaining completely separate versions"> for another
2063approach.
2064
aa689395 2065=head1 Coexistence with earlier versions of perl5
4633a7c4 2066
693762b4
AD
2067In general, you can usually safely upgrade from one version of Perl (e.g.
20685.004_04) to another similar version (e.g. 5.004_05) without re-compiling
2069all of your add-on extensions. You can also safely leave the old version
2070around in case the new version causes you problems for some reason.
2071For example, if you want to be sure that your script continues to run
dc45a647 2072with 5.004_04, simply replace the '#!/usr/local/bin/perl' line at the
693762b4
AD
2073top of the script with the particular version you want to run, e.g.
2074#!/usr/local/bin/perl5.00404.
2075
693762b4
AD
2076Most extensions will probably not need to be recompiled to use
2077with a newer version of perl. Here is how it is supposed to work.
2078(These examples assume you accept all the Configure defaults.)
2079
d6baa268
JH
2080Suppose you already have version 5.005_03 installed. The directories
2081searched by 5.005_03 are
2082
2083 /usr/local/lib/perl5/5.00503/$archname
2084 /usr/local/lib/perl5/5.00503
2085 /usr/local/lib/perl5/site_perl/5.005/$archname
2086 /usr/local/lib/perl5/site_perl/5.005
2087
0a08c020
GS
2088Beginning with 5.6.0 the version number in the site libraries are
2089fully versioned. Now, suppose you install version 5.6.0. The directories
2090searched by version 5.6.0 will be
d6baa268 2091
0a08c020
GS
2092 /usr/local/lib/perl5/5.6.0/$archname
2093 /usr/local/lib/perl5/5.6.0
2094 /usr/local/lib/perl5/site_perl/5.6.0/$archname
2095 /usr/local/lib/perl5/site_perl/5.6.0
d6baa268
JH
2096
2097 /usr/local/lib/perl5/site_perl/5.005/$archname
2098 /usr/local/lib/perl5/site_perl/5.005
c42e3e15 2099 /usr/local/lib/perl5/site_perl/
bfb7748a 2100
c42e3e15 2101Notice the last three entries -- Perl understands the default structure
d6baa268
JH
2102of the $sitelib directories and will look back in older, compatible
2103directories. This way, modules installed under 5.005_03 will continue
0a08c020 2104to be usable by 5.005_03 but will also accessible to 5.6.0. Further,
d6baa268 2105suppose that you upgrade a module to one which requires features
0a08c020
GS
2106present only in 5.6.0. That new module will get installed into
2107/usr/local/lib/perl5/site_perl/5.6.0 and will be available to 5.6.0,
d6baa268 2108but will not interfere with the 5.005_03 version.
bfb7748a 2109
c42e3e15
GS
2110The last entry, /usr/local/lib/perl5/site_perl/, is there so that
21115.6.0 will look for 5.004-era pure perl modules.
d6baa268 2112
0a08c020
GS
2113Lastly, suppose you now install version 5.6.1, which we'll assume is
2114binary compatible with 5.6.0 and 5.005. The directories searched
2115by 5.6.1 (if you don't change the Configure defaults) will be:
d6baa268 2116
265f5c4a
GS
2117 /usr/local/lib/perl5/5.6.1/$archname
2118 /usr/local/lib/perl5/5.6.1
0a08c020
GS
2119 /usr/local/lib/perl5/site_perl/5.6.1/$archname
2120 /usr/local/lib/perl5/site_perl/5.6.1
2121
2122 /usr/local/lib/perl5/site_perl/5.6.0/$archname
2123 /usr/local/lib/perl5/site_perl/5.6.0
d6baa268
JH
2124
2125 /usr/local/lib/perl5/site_perl/5.005/$archname
2126 /usr/local/lib/perl5/site_perl/5.005
2127 /usr/local/lib/perl5/site_perl/
bfb7748a 2128
0a08c020
GS
2129Assuming the users in your site are still actively using perl 5.6.0 and
21305.005 after you installed 5.6.1, you can continue to install add-on
2131extensions using any of perl 5.6.1, 5.6.0, or 5.005. The installations
2132of these different versions remain distinct, but remember that the newer
2133versions of perl are automatically set up to search the site libraries of
2134the older ones. This means that installing a new extension with 5.005
2135will make it visible to all three versions. Later, if you install the
2136same extension using, say, perl 5.6.1, it will override the 5.005-installed
2137version, but only for perl 5.6.1.
2138
2139This way, you can choose to share compatible extensions, but also upgrade
2140to a newer version of an extension that may be incompatible with earlier
2141versions, without breaking the earlier versions' installations.
693762b4
AD
2142
2143=head2 Maintaining completely separate versions
4633a7c4 2144
1ec51d55 2145Many users prefer to keep all versions of perl in completely
d6baa268 2146separate directories. This guarantees that an update to one version
0a08c020
GS
2147won't interfere with another version. (The defaults guarantee this for
2148libraries after 5.6.0, but not for executables. TODO?) One convenient
2149way to do this is by using a separate prefix for each version, such as
d52d4e46 2150
46bb10fb 2151 sh Configure -Dprefix=/opt/perl5.004
d52d4e46 2152
46bb10fb 2153and adding /opt/perl5.004/bin to the shell PATH variable. Such users
d52d4e46
PP
2154may also wish to add a symbolic link /usr/local/bin/perl so that
2155scripts can still start with #!/usr/local/bin/perl.
2156
693762b4
AD
2157Others might share a common directory for maintenance sub-versions
2158(e.g. 5.004 for all 5.004_0x versions), but change directory with
2159each major version.
2160
6877a1cf
AD
2161If you are installing a development subversion, you probably ought to
2162seriously consider using a separate directory, since development
2163subversions may not have all the compatibility wrinkles ironed out
2164yet.
2165
0a08c020 2166=head2 Upgrading from 5.005 to 5.6.0
693762b4 2167
c42e3e15
GS
2168Most extensions built and installed with versions of perl
2169prior to 5.005_50 will not need to be recompiled to be used with
21705.6.0. If you find you do need to rebuild an extension with 5.6.0,
2171you may safely do so without disturbing the 5.005 installation.
2172(See L<"Coexistence with earlier versions of perl5"> above.)
2173
2174See your installed copy of the perllocal.pod file for a (possibly
2175incomplete) list of locally installed modules. Note that you want
2176perllocal.pod not perllocale.pod for installed module information.
693762b4 2177
8e07c86e
AD
2178=head1 Coexistence with perl4
2179
2180You can safely install perl5 even if you want to keep perl4 around.
2181
1ec51d55
CS
2182By default, the perl5 libraries go into /usr/local/lib/perl5/, so
2183they don't override the perl4 libraries in /usr/local/lib/perl/.
8e07c86e
AD
2184
2185In your /usr/local/bin directory, you should have a binary named
1ec51d55 2186perl4.036. That will not be touched by the perl5 installation
8e07c86e
AD
2187process. Most perl4 scripts should run just fine under perl5.
2188However, if you have any scripts that require perl4, you can replace
d6baa268
JH
2189the #! line at the top of them by #!/usr/local/bin/perl4.036 (or
2190whatever the appropriate pathname is). See pod/perltrap.pod for
2191possible problems running perl4 scripts under perl5.
8e07c86e 2192
aa689395
PP
2193=head1 cd /usr/include; h2ph *.h sys/*.h
2194
d6baa268
JH
2195Some perl scripts need to be able to obtain information from the
2196system header files. This command will convert the most commonly used
1ec51d55 2197header files in /usr/include into files that can be easily interpreted
d6baa268
JH
2198by perl. These files will be placed in the architecture-dependent
2199library ($archlib) directory you specified to Configure.
aa689395 2200
d6baa268
JH
2201Note: Due to differences in the C and perl languages, the conversion
2202of the header files is not perfect. You will probably have to
2203hand-edit some of the converted files to get them to parse correctly.
2204For example, h2ph breaks spectacularly on type casting and certain
2205structures.
aa689395 2206
fb73857a 2207=head1 installhtml --help
aa689395 2208
3e3baf6d
TB
2209Some sites may wish to make perl documentation available in HTML
2210format. The installhtml utility can be used to convert pod
fb73857a 2211documentation into linked HTML files and install them.
aa689395 2212
d6baa268
JH
2213Currently, the supplied ./installhtml script does not make use of the
2214html Configure variables. This should be fixed in a future release.
2215
fb73857a 2216The following command-line is an example of one used to convert
3e3baf6d 2217perl documentation:
aa689395 2218
3e3baf6d
TB
2219 ./installhtml \
2220 --podroot=. \
2221 --podpath=lib:ext:pod:vms \
2222 --recurse \
2223 --htmldir=/perl/nmanual \
2224 --htmlroot=/perl/nmanual \
2225 --splithead=pod/perlipc \
2226 --splititem=pod/perlfunc \
2227 --libpods=perlfunc:perlguts:perlvar:perlrun:perlop \
2228 --verbose
2229
2230See the documentation in installhtml for more details. It can take
2231many minutes to execute a large installation and you should expect to
2232see warnings like "no title", "unexpected directive" and "cannot
2233resolve" as the files are processed. We are aware of these problems
2234(and would welcome patches for them).
aa689395 2235
fb73857a
PP
2236You may find it helpful to run installhtml twice. That should reduce
2237the number of "cannot resolve" warnings.
2238
aa689395
PP
2239=head1 cd pod && make tex && (process the latex files)
2240
2241Some sites may also wish to make the documentation in the pod/ directory
2242available in TeX format. Type
2243
2244 (cd pod && make tex && <process the latex files>)
2245
2246=head1 Reporting Problems
2247
bfb7748a
AD
2248If you have difficulty building perl, and none of the advice in this file
2249helps, and careful reading of the error message and the relevant manual
2250pages on your system doesn't help either, then you should send a message
7f2de2d2 2251to either the comp.lang.perl.misc newsgroup or to perlbug@perl.org with
bfb7748a 2252an accurate description of your problem.
aa689395 2253
bfb7748a
AD
2254Please include the output of the ./myconfig shell script that comes with
2255the distribution. Alternatively, you can use the perlbug program that
2256comes with the perl distribution, but you need to have perl compiled
2257before you can use it. (If you have not installed it yet, you need to
f5b3b617 2258run C<./perl -Ilib utils/perlbug> instead of a plain C<perlbug>.)
aa689395 2259
694a7e45
AD
2260Please try to make your message brief but clear. Trim out unnecessary
2261information. Do not include large files (such as config.sh or a complete
2262Configure or make log) unless absolutely necessary. Do not include a
2263complete transcript of your build session. Just include the failing
d6baa268 2264commands, the relevant error messages, and whatever preceding commands
694a7e45
AD
2265are necessary to give the appropriate context. Plain text should
2266usually be sufficient--fancy attachments or encodings may actually
2267reduce the number of people who read your message. Your message
2268will get relayed to over 400 subscribers around the world so please
2269try to keep it brief but clear.
aa689395 2270
8e07c86e
AD
2271=head1 DOCUMENTATION
2272
bfb7748a
AD
2273Read the manual entries before running perl. The main documentation
2274is in the pod/ subdirectory and should have been installed during the
8e07c86e 2275build process. Type B<man perl> to get started. Alternatively, you
bfb7748a
AD
2276can type B<perldoc perl> to use the supplied perldoc script. This is
2277sometimes useful for finding things in the library modules.
8e07c86e 2278
1ec51d55 2279Under UNIX, you can produce a documentation book in postscript form,
bfb7748a
AD
2280along with its table of contents, by going to the pod/ subdirectory and
2281running (either):
34a2a22e
RM
2282
2283 ./roffitall -groff # If you have GNU groff installed
aa689395 2284 ./roffitall -psroff # If you have psroff
34a2a22e
RM
2285
2286This will leave you with two postscript files ready to be printed.
aa689395
PP
2287(You may need to fix the roffitall command to use your local troff
2288set-up.)
34a2a22e 2289
bfb7748a
AD
2290Note that you must have performed the installation already before running
2291the above, since the script collects the installed files to generate
2292the documentation.
34a2a22e 2293
8e07c86e
AD
2294=head1 AUTHOR
2295
bfb7748a
AD
2296Original author: Andy Dougherty doughera@lafayette.edu , borrowing very
2297heavily from the original README by Larry Wall, with lots of helpful
2298feedback and additions from the perl5-porters@perl.org folks.
fb73857a 2299
f5b3b617
AD
2300If you have problems, corrections, or questions, please see
2301L<"Reporting Problems"> above.
2302
2303=head1 REDISTRIBUTION
2304
2305This document is part of the Perl package and may be distributed under
d6baa268 2306the same terms as perl itself, with the following additional request:
f5b3b617 2307If you are distributing a modified version of perl (perhaps as part of
d6baa268
JH
2308a larger package) please B<do> modify these installation instructions
2309and the contact information to match your distribution.