Remove Encode::Tcl::Extended, suggested by
[p5sagit/p5-mst-13.2.git] / INSTALL
CommitLineData
8e07c86e 1=head1 NAME
2
3Install - Build and Installation guide for perl5.
4
5=head1 SYNOPSIS
6
3ce0d271 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 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 16 make
17 make test
18 make install
36477c24 19
aa689395 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 24
25Each of these is explained in further detail below.
26
b88cc0eb 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 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 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 53If you have problems, corrections, or questions, please see
54L<"Reporting Problems"> below.
55
7beaa944 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 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 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 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 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 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 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 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 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 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 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 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 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 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 131=head1 WARNING: This version requires a compiler that supports ANSI C.
132
16dc217a 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 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 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 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 180followed. This will enable us to officially support this option.
181
16dc217a 182=back
183
df41b452 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
976c6ee4 189The complete perl5 source tree takes up about 40 MB of disk space.
190After completing make, it takes up roughly 60 MB, though the actual
d6baa268 191total is likely to be quite system-dependent. The installation
976c6ee4 192directories need something on the order of 35 MB, though again that
1ec51d55 193value is system-dependent.
8e07c86e 194
aa689395 195=head1 Start with a Fresh Distribution
8e07c86e 196
edb1cbcb 197If you have built perl before, you should clean out the build directory
198with the command
199
dc45a647 200 make distclean
201
202or
203
edb1cbcb 204 make realclean
c3edaffb 205
dc45a647 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 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 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 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 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 246
247Configure will figure out various things about your system. Some
248things Configure will figure out for itself, other things it will ask
d6baa268 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 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 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 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 297=head2 Common Configure options
298
fb73857a 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 303=over 4
304
305=item gcc
306
307To compile with gcc you should run
8e07c86e 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 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 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 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 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 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 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 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 364If you are willing to accept all the defaults, and you want terse
365output, you can run
366
367 sh Configure -des
368
b88cc0eb 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 377
378 sh Configure -Dprefix=/opt/perl -Doptimize='-xpentium -xO4' -des
379
46bb10fb 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 388options. Try
389
693762b4 390 ./configure.gnu --help
46bb10fb 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 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 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 408I highly recommend running Configure interactively to be sure it puts
409everything where you want it. At any point during the Configure
d6baa268 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 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 453
454 Configure variable Default value
455 $siteprefix $prefix
456 $sitebin $siteprefix/bin
49c10eea 457 $sitescript $siteprefix/bin
273cf8d1 458 $sitelib $siteprefix/lib/perl5/site_perl/$version
459 $sitearch $siteprefix/lib/perl5/site_perl/$version/$archname
49c10eea 460 $siteman1 $siteprefix/man/man1
461 $siteman3 $siteprefix/man/man3
462 $sitehtml1 (none)
463 $sitehtml3 (none)
d6baa268 464
465By default, ExtUtils::MakeMaker will install architecture-independent
273cf8d1 466modules into $sitelib and architecture-dependent modules into $sitearch.
d6baa268 467
49cb0e56 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 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 483 $vendorlib $vendorprefix/lib/perl5/vendor_perl/$version
484 $vendorarch $vendorprefix/lib/perl5/vendor_perl/$version/$archname
49c10eea 485 $vendorman1 $vendorprefix/man/man1
486 $vendorman3 $vendorprefix/man/man3
487 $vendorhtml1 (none)
488 $vendorhtml3 (none)
d6baa268 489
490These are normally empty, but may be set as needed. For example,
491a vendor might choose the following settings:
492
345c69e9 493 $prefix /usr
494 $siteprefix /usr/local
495 $vendorprefix /usr
d6baa268 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 508 $sitelib /usr/local/lib/perl5/site_perl/$version
509 $sitearch /usr/local/lib/perl5/site_perl/$version/$archname
49c10eea 510 $siteman1 /usr/local/man/man1
511 $siteman3 /usr/local/man/man3
d6baa268 512
49c10eea 513 $vendorbin /usr/bin
514 $vendorscript /usr/bin
273cf8d1 515 $vendorlib /usr/lib/perl5/vendor_perl/$version
516 $vendorarch /usr/lib/perl5/vendor_perl/$version/$archname
49c10eea 517 $vendorman1 /usr/man/man1
518 $vendorman3 /usr/man/man3
d6baa268 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 522the /usr/local hierarchy.
523
49cb0e56 524NOTE: As of 5.6.0, ExtUtils::MakeMaker does not use these directories.
525Volunteers to fix this are needed.
526
273cf8d1 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 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 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 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 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 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 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 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 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 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 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 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 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 646follow this example. The next section shows one way of dealing with
647that problem.
648
aa689395 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 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 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 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 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 673 tar xvf perl5-archive.tar
674
dc45a647 675=head2 Site-wide Policy settings
693762b4 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 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 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 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 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 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 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 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 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 755=head2 64 bit support.
756
766b63c4 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 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 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 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 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 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 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 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 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 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 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
10c7e831 881=head2 Building a shared Perl library
c3edaffb 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 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 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 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 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 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 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 919To build a shared libperl, the environment variable controlling shared
920library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
78be1e1a 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
10c7e831 925library search settings. You can find the name of the environment
926variable Perl thinks works in your your system by
927
928 grep ldlibpthname config.sh
2bf2710f 929
930However, there are some special cases where manually setting the
931shared library path might be required. For example, if you want to run
932something like the following with the newly-built but not-yet-installed
933./perl:
934
935 cd t; ./perl misc/failing_test.t
936or
937 ./perl -Ilib ~/my_mission_critical_test
938
939then you need to set up the shared library path explicitly.
940You can do this with
c3edaffb 941
942 LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
943
944for Bourne-style shells, or
945
946 setenv LD_LIBRARY_PATH `pwd`
947
2bf2710f 948for Csh-style shells. (This procedure may also be needed if for some
10c7e831 949unexpected reason Configure fails to set up makefile correctly.) (And
950again, it may be something else than LD_LIBRARY_PATH for you, see above.)
2bf2710f 951
952You can often recognize failures to build/use a shared libperl from error
953messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
954for example:
95518126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
c3edaffb 956
9d67150a 957There is also an potential problem with the shared perl library if you
958want to have more than one "flavor" of the same version of perl (e.g.
959with and without -DDEBUGGING). For example, suppose you build and
a6006777 960install a standard Perl 5.004 with a shared library. Then, suppose you
961try to build Perl 5.004 with -DDEBUGGING enabled, but everything else
9d67150a 962the same, including all the installation directories. How can you
963ensure that your newly built perl will link with your newly built
7f678428 964libperl.so.4 rather with the installed libperl.so.4? The answer is
9d67150a 965that you might not be able to. The installation directory is encoded
56c6f531 966in the perl binary with the LD_RUN_PATH environment variable (or
967equivalent ld command-line option). On Solaris, you can override that
7beaa944 968with LD_LIBRARY_PATH; on Linux you can't. On Digital Unix, you can
0dcb58f4 969override LD_LIBRARY_PATH by setting the _RLD_ROOT environment variable
7beaa944 970to point to the perl build directory.
9d67150a 971
972The only reliable answer is that you should specify a different
973directory for the architecture-dependent library for your -DDEBUGGING
fb73857a 974version of perl. You can do this by changing all the *archlib*
d6baa268 975variables in config.sh to point to your new architecture-dependent library.
9d67150a 976
55479bb6 977=head2 Malloc Issues
978
d6baa268 979Perl relies heavily on malloc(3) to grow data structures as needed,
980so perl's performance can be noticeably affected by the performance of
981the malloc function on your system. The perl source is shipped with a
982version of malloc that has been optimized for the typical requests from
983perl, so there's a chance that it may be both faster and use less memory
984than your system malloc.
55479bb6 985
d6baa268 986However, if your system already has an excellent malloc, or if you are
987experiencing difficulties with extensions that use third-party libraries
988that call malloc, then you should probably use your system's malloc.
989(Or, you might wish to explore the malloc flags discussed below.)
c3edaffb 990
aa689395 991=over 4
992
d6baa268 993=item Using the system malloc
2ae324a7 994
d6baa268 995To build without perl's malloc, you can use the Configure command
aa689395 996
d6baa268 997 sh Configure -Uusemymalloc
aa689395 998
d6baa268 999or you can answer 'n' at the appropriate interactive Configure prompt.
aa689395 1000
86058a2d 1001=item -DPERL_POLLUTE_MALLOC
1002
b2a6d19e 1003NOTE: This flag is enabled automatically on some platforms if you
1004asked for binary compatibility with version 5.005, or if you just
1005run Configure to accept all the defaults on those platforms. You
1006can refuse the automatic binary compatibility flags wholesale by
1007running:
1008
1009 sh Configure -Ubincompat5005
1010
1011or by answering 'n' at the appropriate prompt.
1012
d6baa268 1013Perl's malloc family of functions are called Perl_malloc(),
b2a6d19e 1014Perl_realloc(), Perl_calloc() and Perl_mfree(). When this flag is
1015not enabled, the names do not clash with the system versions of
1016these functions.
d6baa268 1017
b2a6d19e 1018If enabled, Perl's malloc family of functions will have the same
d6baa268 1019names as the system versions. This may be sometimes required when you
1020have libraries that like to free() data that may have been allocated
1021by Perl_malloc() and vice versa.
86058a2d 1022
d6baa268 1023Note that enabling this option may sometimes lead to duplicate symbols
1024from the linker for malloc et al. In such cases, the system probably
1025does not allow its malloc functions to be fully replaced with custom
1026versions.
86058a2d 1027
aa689395 1028=back
1029
3bf462b8 1030=head2 Building a debugging perl
1031
1032You can run perl scripts under the perl debugger at any time with
3fe9a6f1 1033B<perl -d your_script>. If, however, you want to debug perl itself,
3bf462b8 1034you probably want to do
1035
1036 sh Configure -Doptimize='-g'
1037
203c3eec 1038This will do two independent things: First, it will force compilation
1039to use cc -g so that you can use your system's debugger on the
1040executable. (Note: Your system may actually require something like
d6baa268 1041cc -g2. Check your man pages for cc(1) and also any hint file for
1042your system.) Second, it will add -DDEBUGGING to your ccflags
1043variable in config.sh so that you can use B<perl -D> to access perl's
1044internal state. (Note: Configure will only add -DDEBUGGING by default
1045if you are not reusing your old config.sh. If you want to reuse your
1046old config.sh, then you can just edit it and change the optimize and
1047ccflags variables by hand and then propagate your changes as shown in
1048L<"Propagating your changes to config.sh"> below.)
203c3eec 1049
1050You can actually specify -g and -DDEBUGGING independently, but usually
1051it's convenient to have both.
3bf462b8 1052
1053If you are using a shared libperl, see the warnings about multiple
1054versions of perl under L<Building a shared libperl.so Perl library>.
1055
8d74ce1c 1056=head2 Extensions
1057
80c1f5de 1058Perl ships with a number of standard extensions. These are contained
1059in the ext/ subdirectory.
1060
8d74ce1c 1061By default, Configure will offer to build every extension which appears
1062to be supported. For example, Configure will offer to build GDBM_File
1063only if it is able to find the gdbm library. (See examples below.)
8d74ce1c 1064Configure does not contain code to test for POSIX compliance, so POSIX
1065is always built by default as well. If you wish to skip POSIX, you can
1066set the Configure variable useposix=false either in a hint file or from
80c1f5de 1067the Configure command line.
8d74ce1c 1068
c42e3e15 1069If you unpack any additional extensions in the ext/ directory before
1070running Configure, then Configure will offer to build those additional
1071extensions as well. Most users probably shouldn't have to do this --
1072it is usually easier to build additional extensions later after perl
1073has been installed. However, if you wish to have those additional
1074extensions statically linked into the perl binary, then this offers a
1075convenient way to do that in one step. (It is not necessary, however;
1076you can build and install extensions just fine even if you don't have
1077dynamic loading. See lib/ExtUtils/MakeMaker.pm for more details.)
1078
1079You can learn more about each of the supplied extensions by consulting the
8d74ce1c 1080documentation in the individual .pm modules, located under the
1081ext/ subdirectory.
1082
1083Even if you do not have dynamic loading, you must still build the
1084DynaLoader extension; you should just build the stub dl_none.xs
1085version. (Configure will suggest this as the default.)
1086
1087In summary, here are the Configure command-line variables you can set
80c1f5de 1088to turn off various extensions. All others are included by default.
8d74ce1c 1089
8d74ce1c 1090 DB_File i_db
1091 DynaLoader (Must always be included as a static extension)
8d74ce1c 1092 GDBM_File i_gdbm
8d74ce1c 1093 NDBM_File i_ndbm
1094 ODBM_File i_dbm
1095 POSIX useposix
8d74ce1c 1096 Opcode useopcode
1097 Socket d_socket
a2dab6bc 1098 Threads use5005threads
8d74ce1c 1099
1100Thus to skip the NDBM_File extension, you can use
1101
1102 sh Configure -Ui_ndbm
1103
1104Again, this is taken care of automatically if you don't have the ndbm
1105library.
1106
1107Of course, you may always run Configure interactively and select only
1108the extensions you want.
1109
1110Note: The DB_File module will only work with version 1.x of Berkeley
1111DB or newer releases of version 2. Configure will automatically detect
1112this for you and refuse to try to build DB_File with earlier
1113releases of version 2.
1114
1115If you re-use your old config.sh but change your system (e.g. by
1116adding libgdbm) Configure will still offer your old choices of extensions
1117for the default answer, but it will also point out the discrepancy to
1118you.
1119
80c1f5de 1120Finally, if you have dynamic loading (most modern systems do)
8d74ce1c 1121remember that these extensions do not increase the size of your perl
1122executable, nor do they impact start-up time, so you probably might as
1123well build all the ones that will work on your system.
1124
1125=head2 Including locally-installed libraries
1126
1127Perl5 comes with interfaces to number of database extensions, including
1128dbm, ndbm, gdbm, and Berkeley db. For each extension, if
1129Configure can find the appropriate header files and libraries, it will
1130automatically include that extension. The gdbm and db libraries
1131are not included with perl. See the library documentation for
1132how to obtain the libraries.
1133
d6baa268 1134If your database header (.h) files are not in a directory normally
1135searched by your C compiler, then you will need to include the
1136appropriate -I/your/directory option when prompted by Configure. If
1137your database library (.a) files are not in a directory normally
1138searched by your C compiler and linker, then you will need to include
1139the appropriate -L/your/directory option when prompted by Configure.
1140See the examples below.
8d74ce1c 1141
1142=head2 Examples
1143
1144=over 4
1145
1146=item gdbm in /usr/local
1147
1148Suppose you have gdbm and want Configure to find it and build the
d6baa268 1149GDBM_File extension. This example assumes you have gdbm.h
8d74ce1c 1150installed in /usr/local/include/gdbm.h and libgdbm.a installed in
1151/usr/local/lib/libgdbm.a. Configure should figure all the
1152necessary steps out automatically.
1153
1154Specifically, when Configure prompts you for flags for
1155your C compiler, you should include -I/usr/local/include.
1156
1157When Configure prompts you for linker flags, you should include
1158-L/usr/local/lib.
1159
1160If you are using dynamic loading, then when Configure prompts you for
1161linker flags for dynamic loading, you should again include
1162-L/usr/local/lib.
1163
d6baa268 1164Again, this should all happen automatically. This should also work if
1165you have gdbm installed in any of (/usr/local, /opt/local, /usr/gnu,
1166/opt/gnu, /usr/GNU, or /opt/GNU).
8d74ce1c 1167
1168=item gdbm in /usr/you
1169
1170Suppose you have gdbm installed in some place other than /usr/local/,
1171but you still want Configure to find it. To be specific, assume you
1172have /usr/you/include/gdbm.h and /usr/you/lib/libgdbm.a. You
1173still have to add -I/usr/you/include to cc flags, but you have to take
1174an extra step to help Configure find libgdbm.a. Specifically, when
1175Configure prompts you for library directories, you have to add
1176/usr/you/lib to the list.
1177
1178It is possible to specify this from the command line too (all on one
1179line):
1180
d6baa268 1181 sh Configure -de \
8d74ce1c 1182 -Dlocincpth="/usr/you/include" \
1183 -Dloclibpth="/usr/you/lib"
1184
1185locincpth is a space-separated list of include directories to search.
1186Configure will automatically add the appropriate -I directives.
1187
1188loclibpth is a space-separated list of library directories to search.
1189Configure will automatically add the appropriate -L directives. If
1190you have some libraries under /usr/local/ and others under
1191/usr/you, then you have to include both, namely
1192
d6baa268 1193 sh Configure -de \
8d74ce1c 1194 -Dlocincpth="/usr/you/include /usr/local/include" \
1195 -Dloclibpth="/usr/you/lib /usr/local/lib"
1196
1197=back
1198
bb636fa4 1199=head2 Building DB, NDBM, and ODBM interfaces with Berkeley DB 3
1200
1201Perl interface for DB3 is part of Berkeley DB, but if you want to
1202compile standard Perl DB/ODBM/NDBM interfaces, you must follow
1203following instructions.
1204
1205Berkeley DB3 from Sleepycat Software is by default installed without
1206DB1 compatibility code (needed for DB_File interface) and without
1207links to compatibility files. So if you want to use packages written
1208for DB/ODBM/NDBM interfaces, you need to configure DB3 with
1209--enable-compat185 (and optionally with --enable-dump185) and create
1210additional references (suppose you are installing DB3 with
1211--prefix=/usr):
1212
1213 ln -s libdb-3.so /usr/lib/libdbm.so
1214 ln -s libdb-3.so /usr/lib/libndbm.so
1215 echo '#define DB_DBM_HSEARCH 1' >dbm.h
1216 echo '#include <db.h>' >>dbm.h
1217 install -m 0644 dbm.h /usr/include/dbm.h
1218 install -m 0644 dbm.h /usr/include/ndbm.h
1219
1220Optionally, if you have compiled with --enable-compat185 (not needed
1221for ODBM/NDBM):
1222
1223 ln -s libdb-3.so /usr/lib/libdb1.so
1224 ln -s libdb-3.so /usr/lib/libdb.so
1225
1226ODBM emulation seems not to be perfect, but is quite usable,
1227using DB 3.1.17:
1228
1229 lib/odbm.............FAILED at test 9
1230 Failed 1/64 tests, 98.44% okay
1231
8e07c86e 1232=head2 What if it doesn't work?
1233
8d74ce1c 1234If you run into problems, try some of the following ideas.
1235If none of them help, then see L<"Reporting Problems"> below.
1236
8e07c86e 1237=over 4
1238
25f94b33 1239=item Running Configure Interactively
1240
1241If Configure runs into trouble, remember that you can always run
1242Configure interactively so that you can check (and correct) its
1243guesses.
1244
1245All the installation questions have been moved to the top, so you don't
aa689395 1246have to wait for them. Once you've handled them (and your C compiler and
1ec51d55 1247flags) you can type &-d at the next Configure prompt and Configure
25f94b33 1248will use the defaults from then on.
1249
1250If you find yourself trying obscure command line incantations and
1251config.over tricks, I recommend you run Configure interactively
1252instead. You'll probably save yourself time in the long run.
1253
aa689395 1254=item Hint files
8e07c86e 1255
1256The perl distribution includes a number of system-specific hints files
1257in the hints/ directory. If one of them matches your system, Configure
1258will offer to use that hint file.
1259
1260Several of the hint files contain additional important information.
f5b3b617 1261If you have any problems, it is a good idea to read the relevant hint file
1262for further information. See hints/solaris_2.sh for an extensive example.
1263More information about writing good hints is in the hints/README.hints
1264file.
8e07c86e 1265
edb1cbcb 1266=item *** WHOA THERE!!! ***
1267
1268Occasionally, Configure makes a wrong guess. For example, on SunOS
12694.1.3, Configure incorrectly concludes that tzname[] is in the
1270standard C library. The hint file is set up to correct for this. You
1271will see a message:
1272
1273 *** WHOA THERE!!! ***
1274 The recommended value for $d_tzname on this machine was "undef"!
1275 Keep the recommended value? [y]
1276
1277You should always keep the recommended value unless, after reading the
1278relevant section of the hint file, you are sure you want to try
1279overriding it.
1280
1281If you are re-using an old config.sh, the word "previous" will be
1282used instead of "recommended". Again, you will almost always want
1283to keep the previous value, unless you have changed something on your
1284system.
1285
1286For example, suppose you have added libgdbm.a to your system
1287and you decide to reconfigure perl to use GDBM_File. When you run
1288Configure again, you will need to add -lgdbm to the list of libraries.
bfb7748a 1289Now, Configure will find your gdbm include file and library and will
1290issue a message:
edb1cbcb 1291
1292 *** WHOA THERE!!! ***
1293 The previous value for $i_gdbm on this machine was "undef"!
1294 Keep the previous value? [y]
1295
1ec51d55 1296In this case, you do not want to keep the previous value, so you
c3edaffb 1297should answer 'n'. (You'll also have to manually add GDBM_File to
edb1cbcb 1298the list of dynamic extensions to build.)
1299
8e07c86e 1300=item Changing Compilers
1301
1302If you change compilers or make other significant changes, you should
1ec51d55 1303probably not re-use your old config.sh. Simply remove it or
8e07c86e 1304rename it, e.g. mv config.sh config.sh.old. Then rerun Configure
1305with the options you want to use.
1306
1ec51d55 1307This is a common source of problems. If you change from cc to
1308gcc, you should almost always remove your old config.sh.
8e07c86e 1309
c3edaffb 1310=item Propagating your changes to config.sh
8e07c86e 1311
1ec51d55 1312If you make any changes to config.sh, you should propagate
1313them to all the .SH files by running
1314
1315 sh Configure -S
1316
1317You will then have to rebuild by running
9d67150a 1318
1319 make depend
1320 make
8e07c86e 1321
48370efc 1322=item config.over and config.arch
1323
1324You can also supply a shell script config.over to over-ride
1325Configure's guesses. It will get loaded up at the very end, just
1326before config.sh is created. You have to be careful with this,
1327however, as Configure does no checking that your changes make sense.
1328This file is usually good for site-specific customizations.
1329
1330There is also another file that, if it exists, is loaded before the
1331config.over, called config.arch. This file is intended to be per
1332architecture, not per site, and usually it's the architecture-specific
1333hints file that creates the config.arch.
8e07c86e 1334
1335=item config.h
1336
1ec51d55 1337Many of the system dependencies are contained in config.h.
1338Configure builds config.h by running the config_h.SH script.
1339The values for the variables are taken from config.sh.
8e07c86e 1340
1ec51d55 1341If there are any problems, you can edit config.h directly. Beware,
1342though, that the next time you run Configure, your changes will be
8e07c86e 1343lost.
1344
1345=item cflags
1346
1347If you have any additional changes to make to the C compiler command
1ec51d55 1348line, they can be made in cflags.SH. For instance, to turn off the
1349optimizer on toke.c, find the line in the switch structure for
1350toke.c and put the command optimize='-g' before the ;; . You
1351can also edit cflags directly, but beware that your changes will be
1352lost the next time you run Configure.
8e07c86e 1353
f5b3b617 1354To explore various ways of changing ccflags from within a hint file,
1355see the file hints/README.hints.
1356
1357To change the C flags for all the files, edit config.sh and change either
1358$ccflags or $optimize, and then re-run
1ec51d55 1359
1360 sh Configure -S
1361 make depend
8e07c86e 1362
aa689395 1363=item No sh
8e07c86e 1364
c42e3e15 1365If you don't have sh, you'll have to copy the sample file
1366Porting/config.sh to config.sh and edit your config.sh to reflect your
1367system's peculiarities. See Porting/pumpkin.pod for more information.
8e07c86e 1368You'll probably also have to extensively modify the extension building
1369mechanism.
1370
d6baa268 1371=item Environment variable clashes
1372
1373Configure uses a CONFIG variable that is reported to cause trouble on
1374ReliantUnix 5.44. If your system sets this variable, you can try
1375unsetting it before you run Configure. Configure should eventually
1376be fixed to avoid polluting the namespace of the environment.
1377
1378=item Digital UNIX/Tru64 UNIX and BIN_SH
1379
1380In Digital UNIX/Tru64 UNIX, Configure might abort with
1381
1382Build a threading Perl? [n]
1383Configure[2437]: Syntax error at line 1 : `config.sh' is not expected.
1384
1385This indicates that Configure is being run with a broken Korn shell
1386(even though you think you are using a Bourne shell by using
1387"sh Configure" or "./Configure"). The Korn shell bug has been reported
1388to Compaq as of February 1999 but in the meanwhile, the reason ksh is
1389being used is that you have the environment variable BIN_SH set to
1390'xpg4'. This causes /bin/sh to delegate its duties to /bin/posix/sh
1391(a ksh). Unset the environment variable and rerun Configure.
1392
1393=item HP-UX 11, pthreads, and libgdbm
1394
1395If you are running Configure with -Dusethreads in HP-UX 11, be warned
1396that POSIX threads and libgdbm (the GNU dbm library) compiled before
1397HP-UX 11 do not mix. This will cause a basic test run by Configure to
1398fail
1399
1400Pthread internal error: message: __libc_reinit() failed, file: ../pthreads/pthread.c, line: 1096
1401Return Pointer is 0xc082bf33
1402sh: 5345 Quit(coredump)
1403
1404and Configure will give up. The cure is to recompile and install
1405libgdbm under HP-UX 11.
1406
c3edaffb 1407=item Porting information
1408
2ae324a7 1409Specific information for the OS/2, Plan9, VMS and Win32 ports is in the
1ec51d55 1410corresponding README files and subdirectories. Additional information,
1411including a glossary of all those config.sh variables, is in the Porting
c42e3e15 1412subdirectory. Especially Porting/Glossary should come in handy.
c3edaffb 1413
7f678428 1414Ports for other systems may also be available. You should check out
468f45d5 1415http://www.cpan.org/ports for current information on ports to
7f678428 1416various other operating systems.
1417
491517e0 1418If you plan to port Perl to a new architecture study carefully the
1419section titled "Philosophical Issues in Patching and Porting Perl"
1420in the file Porting/pumpkin.pod and the file Porting/patching.pod.
1421Study also how other non-UNIX ports have solved problems.
1422
8e07c86e 1423=back
1424
fadf0ef5 1425=head1 Adding extra modules to the build
1426
1427You can specify extra modules or module bundles to be fetched from the
1428CPAN and installed as part of the Perl build. Either use the -Dextras=...
1429command line parameter to Configure, for example like this:
1430
1431 Configure -Dextras="Compress::Zlib Bundle::LWP DBI"
1432
1433or answer first 'y' to the question 'Install any extra modules?' and
1434then answer "Compress::Zlib Bundle::LWP DBI" to the 'Extras?' question.
1435The module or the bundle names are as for the CPAN module 'install' command.
1436
1437Notice that because the CPAN module will be used to fetch the extra
1438modules, you will need access to the CPAN, either via the Internet,
1439or via a local copy such as a CD-ROM or a local CPAN mirror. If you
1440do not, using the extra modules option will die horribly.
1441
1442Also notice that you yourself are responsible for satisfying any extra
1443dependencies such as external headers or libraries BEFORE trying the build.
1444For example: you will need to have the zlib.h header and the libz
1445library installed for the Compress::Zlib, or the Foo database specific
1446headers and libraries installed for the DBD::Foo module. The Configure
1447process or the Perl build process will not help you with these.
1448
03739d21 1449=head1 suidperl
1450
c80c8d62 1451suidperl is an optional component, which is built or installed by default.
03739d21 1452From perlfaq1:
1453
1454 On some systems, setuid and setgid scripts (scripts written
1455 in the C shell, Bourne shell, or Perl, for example, with the
1456 set user or group ID permissions enabled) are insecure due to
1457 a race condition in the kernel. For those systems, Perl versions
1458 5 and 4 attempt to work around this vulnerability with an optional
1459 component, a special program named suidperl, also known as sperl.
1460 This program attempts to emulate the set-user-ID and set-group-ID
1461 features of the kernel.
1462
1463Because of the buggy history of suidperl, and the difficulty
1464of properly security auditing as large and complex piece of
1465software as Perl, we cannot recommend using suidperl and the feature
1466should be considered deprecated.
1467Instead use for example 'sudo': http://www.courtesan.com/sudo/
1468
8e07c86e 1469=head1 make depend
1470
bfb7748a 1471This will look for all the includes. The output is stored in makefile.
1472The only difference between Makefile and makefile is the dependencies at
1473the bottom of makefile. If you have to make any changes, you should edit
1474makefile, not Makefile since the Unix make command reads makefile first.
1475(On non-Unix systems, the output may be stored in a different file.
1476Check the value of $firstmakefile in your config.sh if in doubt.)
8e07c86e 1477
1478Configure will offer to do this step for you, so it isn't listed
1479explicitly above.
1480
1481=head1 make
1482
1483This will attempt to make perl in the current directory.
1484
8d74ce1c 1485=head2 What if it doesn't work?
1486
8e07c86e 1487If you can't compile successfully, try some of the following ideas.
7f678428 1488If none of them help, and careful reading of the error message and
8d74ce1c 1489the relevant manual pages on your system doesn't help,
1490then see L<"Reporting Problems"> below.
8e07c86e 1491
1492=over 4
1493
1ec51d55 1494=item hints
8e07c86e 1495
1496If you used a hint file, try reading the comments in the hint file
1497for further tips and information.
1498
1ec51d55 1499=item extensions
8e07c86e 1500
1ec51d55 1501If you can successfully build miniperl, but the process crashes
c3edaffb 1502during the building of extensions, you should run
1503
3a6175e1 1504 make minitest
c3edaffb 1505
1506to test your version of miniperl.
1507
e57fd563 1508=item locale
1509
bfb7748a 1510If you have any locale-related environment variables set, try unsetting
1511them. I have some reports that some versions of IRIX hang while
1512running B<./miniperl configpm> with locales other than the C locale.
1513See the discussion under L<"make test"> below about locales and the
1514whole L<"Locale problems"> section in the file pod/perllocale.pod.
3e6e419a 1515The latter is especially useful if you see something like this
1516
1517 perl: warning: Setting locale failed.
1518 perl: warning: Please check that your locale settings:
1519 LC_ALL = "En_US",
1520 LANG = (unset)
1521 are supported and installed on your system.
1522 perl: warning: Falling back to the standard locale ("C").
1523
1524at Perl startup.
e57fd563 1525
7f678428 1526=item varargs
c3edaffb 1527
1528If you get varargs problems with gcc, be sure that gcc is installed
bfb7748a 1529correctly and that you are not passing -I/usr/include to gcc. When using
1530gcc, you should probably have i_stdarg='define' and i_varargs='undef'
1531in config.sh. The problem is usually solved by running fixincludes
1532correctly. If you do change config.sh, don't forget to propagate
1533your changes (see L<"Propagating your changes to config.sh"> below).
7f678428 1534See also the L<"vsprintf"> item below.
c3edaffb 1535
bfb7748a 1536=item util.c
c3edaffb 1537
1538If you get error messages such as the following (the exact line
bfb7748a 1539numbers and function name may vary in different versions of perl):
c3edaffb 1540
bfb7748a 1541 util.c: In function `Perl_form':
1542 util.c:1107: number of arguments doesn't match prototype
1543 proto.h:125: prototype declaration
c3edaffb 1544
1545it might well be a symptom of the gcc "varargs problem". See the
7f678428 1546previous L<"varargs"> item.
c3edaffb 1547
1ec51d55 1548=item LD_LIBRARY_PATH
c3edaffb 1549
1550If you run into dynamic loading problems, check your setting of
aa689395 1551the LD_LIBRARY_PATH environment variable. If you're creating a static
1552Perl library (libperl.a rather than libperl.so) it should build
c3edaffb 1553fine with LD_LIBRARY_PATH unset, though that may depend on details
1554of your local set-up.
1555
aa689395 1556=item nm extraction
c3edaffb 1557
1558If Configure seems to be having trouble finding library functions,
1559try not using nm extraction. You can do this from the command line
1560with
1561
1562 sh Configure -Uusenm
1563
1564or by answering the nm extraction question interactively.
1ec51d55 1565If you have previously run Configure, you should not reuse your old
c3edaffb 1566config.sh.
1567
bfb7748a 1568=item umask not found
1569
1570If the build processes encounters errors relating to umask(), the problem
1571is probably that Configure couldn't find your umask() system call.
1572Check your config.sh. You should have d_umask='define'. If you don't,
1573this is probably the L<"nm extraction"> problem discussed above. Also,
1574try reading the hints file for your system for further information.
1575
7f678428 1576=item vsprintf
c3edaffb 1577
1578If you run into problems with vsprintf in compiling util.c, the
1579problem is probably that Configure failed to detect your system's
1580version of vsprintf(). Check whether your system has vprintf().
1581(Virtually all modern Unix systems do.) Then, check the variable
1582d_vprintf in config.sh. If your system has vprintf, it should be:
1583
1584 d_vprintf='define'
1585
1586If Configure guessed wrong, it is likely that Configure guessed wrong
bfb7748a 1587on a number of other common functions too. This is probably
1588the L<"nm extraction"> problem discussed above.
c3edaffb 1589
3fe9a6f1 1590=item do_aspawn
1591
1592If you run into problems relating to do_aspawn or do_spawn, the
1593problem is probably that Configure failed to detect your system's
bfb7748a 1594fork() function. Follow the procedure in the previous item
1595on L<"nm extraction">.
3fe9a6f1 1596
84902520 1597=item __inet_* errors
1598
1599If you receive unresolved symbol errors during Perl build and/or test
1600referring to __inet_* symbols, check to see whether BIND 8.1 is
1601installed. It installs a /usr/local/include/arpa/inet.h that refers to
1602these symbols. Versions of BIND later than 8.1 do not install inet.h
1603in that location and avoid the errors. You should probably update to a
1604newer version of BIND. If you can't, you can either link with the
1605updated resolver library provided with BIND 8.1 or rename
1606/usr/local/bin/arpa/inet.h during the Perl build and test process to
1607avoid the problem.
1608
d6baa268 1609=item #error "No DATAMODEL_NATIVE specified"
1610
1611This is a common error when trying to build perl on Solaris 2.6 with a
1612gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files
1613changed, so you need to update your gcc installation. You can either
1614rerun the fixincludes script from gcc or take the opportunity to
1615update your gcc installation.
1616
aa689395 1617=item Optimizer
c3edaffb 1618
9d67150a 1619If you can't compile successfully, try turning off your compiler's
aa689395 1620optimizer. Edit config.sh and change the line
9d67150a 1621
1622 optimize='-O'
1623
bfb7748a 1624to
9d67150a 1625
1626 optimize=' '
1627
1628then propagate your changes with B<sh Configure -S> and rebuild
1629with B<make depend; make>.
1630
1ec51d55 1631=item CRIPPLED_CC
9d67150a 1632
1b1c1ae2 1633If you still can't compile successfully, try:
1634
1635 sh Configure -Accflags=-DCRIPPLED_CC
1636
1637This flag simplifies some complicated expressions for compilers that get
1638indigestion easily. (Just because you get no errors doesn't mean it
1639compiled right!)
9d67150a 1640
1641=item Missing functions
1642
1643If you have missing routines, you probably need to add some library or
1644other, or you need to undefine some feature that Configure thought was
1645there but is defective or incomplete. Look through config.h for
bfb7748a 1646likely suspects. If Configure guessed wrong on a number of functions,
1647you might have the L<"nm extraction"> problem discussed above.
8e07c86e 1648
1ec51d55 1649=item toke.c
8e07c86e 1650
1ec51d55 1651Some compilers will not compile or optimize the larger files (such as
1652toke.c) without some extra switches to use larger jump offsets or
1653allocate larger internal tables. You can customize the switches for
1654each file in cflags. It's okay to insert rules for specific files into
1655makefile since a default rule only takes effect in the absence of a
8e07c86e 1656specific rule.
1657
7f678428 1658=item Missing dbmclose
8e07c86e 1659
c3edaffb 1660SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
1661that includes libdbm.nfs (which includes dbmclose()) may be available.
8e07c86e 1662
f3d9a6ba 1663=item Note (probably harmless): No library found for -lsomething
7f678428 1664
1665If you see such a message during the building of an extension, but
1666the extension passes its tests anyway (see L<"make test"> below),
1667then don't worry about the warning message. The extension
1668Makefile.PL goes looking for various libraries needed on various
aa689395 1669systems; few systems will need all the possible libraries listed.
7f678428 1670For example, a system may have -lcposix or -lposix, but it's
1671unlikely to have both, so most users will see warnings for the one
f3d9a6ba 1672they don't have. The phrase 'probably harmless' is intended to
1673reassure you that nothing unusual is happening, and the build
1674process is continuing.
7f678428 1675
1676On the other hand, if you are building GDBM_File and you get the
1677message
1678
f3d9a6ba 1679 Note (probably harmless): No library found for -lgdbm
7f678428 1680
1681then it's likely you're going to run into trouble somewhere along
1682the line, since it's hard to see how you can use the GDBM_File
1683extension without the -lgdbm library.
1684
1685It is true that, in principle, Configure could have figured all of
1686this out, but Configure and the extension building process are not
1687quite that tightly coordinated.
1688
aa689395 1689=item sh: ar: not found
1690
1691This is a message from your shell telling you that the command 'ar'
1692was not found. You need to check your PATH environment variable to
1693make sure that it includes the directory with the 'ar' command. This
1ec51d55 1694is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
aa689395 1695directory.
1696
1697=item db-recno failure on tests 51, 53 and 55
1698
1699Old versions of the DB library (including the DB library which comes
1700with FreeBSD 2.1) had broken handling of recno databases with modified
1701bval settings. Upgrade your DB library or OS.
1702
6087ac44 1703=item Bad arg length for semctl, is XX, should be ZZZ
1704
1705If you get this error message from the lib/ipc_sysv test, your System
1706V IPC may be broken. The XX typically is 20, and that is what ZZZ
1707also should be. Consider upgrading your OS, or reconfiguring your OS
1708to include the System V semaphores.
1709
220f3621 1710=item lib/ipc_sysv........semget: No space left on device
1711
1712Either your account or the whole system has run out of semaphores. Or
1713both. Either list the semaphores with "ipcs" and remove the unneeded
1714ones (which ones these are depends on your system and applications)
1715with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
1716system.
1717
d6baa268 1718=item GNU binutils
1719
1720If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
1721tools you may be in for some trouble. For example creating archives
1722with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
1723may lead into linking problems. Either recompile your GNU binutils
1724under your current operating system release, or modify your PATH not
1725to include the GNU utils before running Configure, or specify the
1726vendor-supplied utilities explicitly to Configure, for example by
1727Configure -Dar=/bin/ar.
1728
16dc217a 1729=item THIS PACKAGE SEEMS TO BE INCOMPLETE
1730
1731The F<Configure> program has not been able to find all the files which
1732make up the complete Perl distribution. You may have a damaged source
1733archive file (in which case you may also have seen messages such as
1734C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on
1735archive file>), or you may have obtained a structurally-sound but
1736incomplete archive. In either case, try downloading again from the
1737official site named at the start of this document. If you do find
1738that any site is carrying a corrupted or incomplete source code
1739archive, please report it to the site's maintainer.
1740
16dc217a 1741=item invalid token: ##
1742
1743You are using a non-ANSI-compliant C compiler. See L<WARNING: This
1744version requires a compiler that supports ANSI C>.
1745
1ec51d55 1746=item Miscellaneous
8e07c86e 1747
1748Some additional things that have been reported for either perl4 or perl5:
1749
1750Genix may need to use libc rather than libc_s, or #undef VARARGS.
1751
1752NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
1753
1ec51d55 1754UTS may need one or more of -DCRIPPLED_CC, -K or -g, and undef LSTAT.
8e07c86e 1755
220f3621 1756FreeBSD can fail the lib/ipc_sysv.t test if SysV IPC has not been
1757configured to the kernel. Perl tries to detect this, though, and
1758you will get a message telling what to do.
6087ac44 1759
8e07c86e 1760If you get syntax errors on '(', try -DCRIPPLED_CC.
1761
1762Machines with half-implemented dbm routines will need to #undef I_ODBM
1763
d6baa268 1764HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
1765Patch Bundle" has been reported to break the io/fs test #18 which
1766tests whether utime() can change timestamps. The Y2K patch seems to
1767break utime() so that over NFS the timestamps do not get changed
1768(on local filesystems utime() still works).
1769
8e07c86e 1770=back
1771
58a21a9b 1772=head2 Cross-compilation
1773
1774Starting from Perl 5.8 Perl has the beginnings of cross-compilation
1775support. What is known to work is running Configure in a
1776cross-compilation environment and building the miniperl executable.
65090350 1777What is known not to work is building the perl executable because
58a21a9b 1778that would require building extensions: Dynaloader statically and
1779File::Glob dynamically, for extensions one needs MakeMaker and
1780MakeMaker is not yet cross-compilation aware, and neither is
1781the main Makefile.
1782
93bc48fa 1783Since the functionality is so lacking, it must be considered
1784highly experimental. It is so experimental that it is not even
c80c8d62 1785mentioned during an interactive Configure session, a direct command
93bc48fa 1786line invocation (detailed shortly) is required to access the
1787functionality.
1788
58a21a9b 1789 NOTE: Perl is routinely built using cross-compilation
1790 in the EPOC environment but the solutions from there
93bc48fa 1791 can't directly be used elsewhere.
58a21a9b 1792
1793The one environment where cross-compilation has successfully been used
1794as of this writing is the Compaq iPAQ running ARM Linux. The build
93bc48fa 1795host was Intel Linux, the networking setup was PPP + SSH. The exact
1796setup details are beyond the scope of this document, see
58a21a9b 1797http://www.handhelds.org/ for more information.
1798
1799To run Configure in cross-compilation mode the basic switch is
1800C<-Dusecrosscompile>.
1801
1802 sh ./Configure -des -Dusecrosscompile -D...
1803
1804This will make the cpp symbol USE_CROSS_COMPILE and the %Config
1805symbol C<usecrosscompile> available.
1806
1807During the Configure and build, certain helper scripts will be created
1808into the Cross/ subdirectory. The scripts are used to execute a
1809cross-compiled executable, and to transfer files to and from the
1810target host. The execution scripts are named F<run-*> and the
1811transfer scripts F<to-*> and F<from-*>. The part after the dash is
1812the method to use for remote execution and transfer: by default the
1813methods are B<ssh> and B<scp>, thus making the scripts F<run-ssh>,
1814F<to-scp>, and F<from-scp>.
1815
1816To configure the scripts for a target host and a directory (in which
1817the execution will happen and which is to and from where the transfer
1818happens), supply Configure with
1819
1820 -Dtargethost=so.me.ho.st -Dtargetdir=/tar/get/dir
1821
1822The targethost is what e.g. ssh will use as the hostname, the targetdir
93bc48fa 1823must exist (the scripts won't create it), the targetdir defaults to /tmp.
1824You can also specify a username to use for ssh/rsh logins
58a21a9b 1825
1826 -Dtargetuser=luser
1827
1828but in case you don't, "root" will be used.
1829
93bc48fa 1830Because this is a cross-compilation effort, you will also need to specify
1831which target environment and which compilation environment to use.
1832This includes the compiler, the header files, and the libraries.
1833In the below we use the usual settings for the iPAQ cross-compilation
1834environment:
58a21a9b 1835
1836 -Dtargetarch=arm-linux
1837 -Dcc=arm-linux-gcc
1838 -Dusrinc=/skiff/local/arm-linux/include
1839 -Dincpth=/skiff/local/arm-linux/include
1840 -Dlibpth=/skiff/local/arm-linux/lib
1841
1842If the name of the C<cc> has the usual GNU C semantics for cross
1843compilers, that is, CPU-OS-gcc, the names of the C<ar>, C<nm>, and
1844C<ranlib> will also be automatically chosen to be CPU-OS-ar and so on.
93bc48fa 1845(The C<ld> requires more thought and will be chosen later by Configure
1846as appropriate.) Also, in this case the incpth, libpth, and usrinc
1847will be guessed by Configure (unless explicitly set to something else,
1848in which case Configure's guesses with be appended).
58a21a9b 1849
1850In addition to the default execution/transfer methods you can also
1851choose B<rsh> for execution, and B<rcp> or B<cp> for transfer,
1852for example:
1853
1854 -Dtargetrun=rsh -Dtargetto=rcp -Dtargetfrom=cp
1855
1856Putting it all together:
1857
1858 sh ./Configure -des -Dusecrosscompile \
93bc48fa 1859 -Dtargethost=so.me.ho.st \
1860 -Dtargetdir=/tar/get/dir \
58a21a9b 1861 -Dtargetuser=root \
1862 -Dtargetarch=arm-linux \
1863 -Dcc=arm-linux-gcc \
1864 -Dusrinc=/skiff/local/arm-linux/include \
1865 -Dincpth=/skiff/local/arm-linux/include \
1866 -Dlibpth=/skiff/local/arm-linux/lib \
1867 -D...
1868
93bc48fa 1869or if you are happy with the defaults
1870
1871 sh ./Configure -des -Dusecrosscompile \
1872 -Dtargethost=so.me.ho.st \
1873 -Dcc=arm-linux-gcc \
1874 -D...
1875
8e07c86e 1876=head1 make test
1877
d6baa268 1878This will run the regression tests on the perl you just made. If
1879'make test' doesn't say "All tests successful" then something went
1880wrong. See the file t/README in the t subdirectory.
84902520 1881
84902520 1882Note that you can't run the tests in background if this disables
fb73857a 1883opening of /dev/tty. You can use 'make test-notty' in that case but
1884a few tty tests will be skipped.
c3edaffb 1885
c4f23d77 1886=head2 What if make test doesn't work?
1887
1ec51d55 1888If make test bombs out, just cd to the t directory and run ./TEST
1889by hand to see if it makes any difference. If individual tests
c3edaffb 1890bomb, you can run them by hand, e.g.,
8e07c86e 1891
1892 ./perl op/groups.t
1893
aa689395 1894Another way to get more detailed information about failed tests and
1ec51d55 1895individual subtests is to cd to the t directory and run
aa689395 1896
1897 ./perl harness
1898
fb73857a 1899(this assumes that most basic tests succeed, since harness uses
10c7e831 1900complicated constructs). For extension and library tests you
1901need a little bit more: you need to setup your environment variable
1902PERL_CORE to a true value (like "1"), and you need to supply the
1903right Perl library path:
1904
1905 setenv PERL_CORE 1
1906 ./perl -I../lib ../ext/Socket/Socket.t
1907 ./perl -I../lib ../lib/less.t
aa689395 1908
10c7e831 1909(For csh-like shells on UNIX, adjust appropriately for other platforms.)
fb73857a 1910You should also read the individual tests to see if there are any helpful
10c7e831 1911comments that apply to your system. You may also need to setup your
1912shared library path if you get errors like:
1913
1914 /sbin/loader: Fatal Error: cannot map libperl.so
1915
1916See L</"Building a shared Perl library"> earlier in this document.
c3edaffb 1917
c4f23d77 1918=over 4
1919
1920=item locale
1921
1ec51d55 1922Note: One possible reason for errors is that some external programs
c07a80fd 1923may be broken due to the combination of your environment and the way
3fe9a6f1 1924B<make test> exercises them. For example, this may happen if you have
1ec51d55 1925one or more of these environment variables set: LC_ALL LC_CTYPE
1926LC_COLLATE LANG. In some versions of UNIX, the non-English locales
e57fd563 1927are known to cause programs to exhibit mysterious errors.
1928
1929If you have any of the above environment variables set, please try
aa689395 1930
1931 setenv LC_ALL C
1932
1933(for C shell) or
1934
1935 LC_ALL=C;export LC_ALL
1936
1ec51d55 1937for Bourne or Korn shell) from the command line and then retry
1938make test. If the tests then succeed, you may have a broken program that
aa689395 1939is confusing the testing. Please run the troublesome test by hand as
e57fd563 1940shown above and see whether you can locate the program. Look for
1ec51d55 1941things like: exec, `backquoted command`, system, open("|...") or
1942open("...|"). All these mean that Perl is trying to run some
e57fd563 1943external program.
eed2e782 1944
0740bb5b 1945=item Timing problems
1946
c29923ff 1947Several tests in the test suite check timing functions, such as
1948sleep(), and see if they return in a reasonable amount of time.
1949If your system is quite busy and doesn't return quickly enough,
1950these tests might fail. If possible, try running the tests again with
1951the system under a lighter load. These tests include F<t/op/alarm.t>,
1952F<ext/Time/HiRes/HiRes.t>, and F<lib/Benchmark.t>.
0740bb5b 1953
c4f23d77 1954=item Out of memory
1955
1956On some systems, particularly those with smaller amounts of RAM, some
1957of the tests in t/op/pat.t may fail with an "Out of memory" message.
7970f296 1958For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
1959test 85 will fail if run under either t/TEST or t/harness.
c4f23d77 1960
1961Try stopping other jobs on the system and then running the test by itself:
1962
1963 cd t; ./perl op/pat.t
1964
1965to see if you have any better luck. If your perl still fails this
1966test, it does not necessarily mean you have a broken perl. This test
1967tries to exercise the regular expression subsystem quite thoroughly,
1968and may well be far more demanding than your normal usage.
1969
781948c1 1970=item Test failures from lib/ftmp-security saying "system possibly insecure"
1971
1972Firstly, test failures from the ftmp-security are not necessarily
1973serious or indicative of a real security threat. That being said,
1974they bear investigating.
1975
1976The tests may fail for the following reasons. Note that each of the
1977tests is run both in the building directory and the temporary
1978directory, as returned by File::Spec->tmpdir().
1979
1980(1) If the directory the tests are being run is owned by somebody else
1981than the user running the tests, or root (uid 0). This failure can
1982happen if the Perl source code distribution is unpacked in a way that
1983the user ids in the distribution package are used as-is. Some tar
1984programs do this.
1985
1986(2) If the directory the test are being run in is writable by group
1987or by other (remember: with UNIX/POSIX semantics, write access to
1988a directory means the right to add/remove files in that directory),
1989and there is no sticky bit set in the directory. 'Sticky bit' is
1990a feature used in some UNIXes to give extra protection to files: if
1991the bit is on a directory, no one but the owner (or the root) can remove
1992that file even if the permissions of the directory would allow file
1993removal by others. This failure can happen if the permissions in the
1994directory simply are a bit too liberal for the tests' liking. This
1995may or may not be a real problem: it depends on the permissions policy
1996used on this particular directory/project/system/site. This failure
1997can also happen if the system either doesn't support the sticky bit
1998(this is the case with many non-UNIX platforms: in principle the
1999File::Temp should know about these platforms and skip the tests), or
2000if the system supports the sticky bit but for some reason or reasons
2001it is not being used. This is for example the case with HP-UX: as of
2002HP-UX release 11.00, the sticky bit is very much supported, but HP-UX
2003doesn't use it on its /tmp directory as shipped. Also as with the
2004permissions, some local policy might dictate that the stickiness is
2005not used.
2006
b2b23189 2007(3) If the system supports the POSIX 'chown giveaway' feature and if
2008any of the parent directories of the temporary file back to the root
2009directory are 'unsafe', using the definitions given above in (1) and
2010(2).
781948c1 2011
2012See the documentation for the File::Temp module for more information
2013about the various security aspects.
2014
c4f23d77 2015=back
2016
8e07c86e 2017=head1 make install
2018
2019This will put perl into the public directory you specified to
1ec51d55 2020Configure; by default this is /usr/local/bin. It will also try
8e07c86e 2021to put the man pages in a reasonable place. It will not nroff the man
aa689395 2022pages, however. You may need to be root to run B<make install>. If you
8e07c86e 2023are not root, you must own the directories in question and you should
2024ignore any messages about chown not working.
2025
dd64f1c3 2026=head2 Installing perl under different names
2027
2028If you want to install perl under a name other than "perl" (for example,
2029when installing perl with special features enabled, such as debugging),
2030indicate the alternate name on the "make install" line, such as:
2031
2032 make install PERLNAME=myperl
2033
beb13193 2034You can separately change the base used for versioned names (like
2035"perl5.005") by setting PERLNAME_VERBASE, like
2036
2037 make install PERLNAME=perl5 PERLNAME_VERBASE=perl
2038
2039This can be useful if you have to install perl as "perl5" (due to an
2040ancient version in /usr/bin supplied by your vendor, eg). Without this
2041the versioned binary would be called "perl55.005".
2042
dd64f1c3 2043=head2 Installed files
2044
8e07c86e 2045If you want to see exactly what will happen without installing
2046anything, you can run
4633a7c4 2047
8e07c86e 2048 ./perl installperl -n
2049 ./perl installman -n
2050
1ec51d55 2051make install will install the following:
8e07c86e 2052
d56c5707 2053 binaries
2054
8e07c86e 2055 perl,
2056 perl5.nnn where nnn is the current release number. This
2057 will be a link to perl.
2058 suidperl,
2059 sperl5.nnn If you requested setuid emulation.
2060 a2p awk-to-perl translator
d56c5707 2061
2062 scripts
2063
8e07c86e 2064 cppstdin This is used by perl -P, if your cc -E can't
2065 read from stdin.
2066 c2ph, pstruct Scripts for handling C structures in header files.
2067 s2p sed-to-perl translator
2068 find2perl find-to-perl translator
aa689395 2069 h2ph Extract constants and simple macros from C headers
8e07c86e 2070 h2xs Converts C .h header files to Perl extensions.
24b3df7f 2071 perlbug Tool to report bugs in Perl.
8e07c86e 2072 perldoc Tool to read perl's pod documentation.
aa689395 2073 pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules
8e07c86e 2074 pod2html, Converters from perl's pod documentation format
aa689395 2075 pod2latex, to other useful formats.
d56c5707 2076 pod2man,
2077 pod2text,
2078 pod2checker,
2079 pod2select,
2080 pod2usage
aa689395 2081 splain Describe Perl warnings and errors
95667ae4 2082 dprofpp Perl code profile post-processor
8e07c86e 2083
d56c5707 2084 library files
2085
2086 in $privlib and $archlib specified to
8e07c86e 2087 Configure, usually under /usr/local/lib/perl5/.
d56c5707 2088
2089 documentation
2090
d6baa268 2091 man pages in $man1dir, usually /usr/local/man/man1.
2092 module man
2093 pages in $man3dir, usually /usr/local/man/man3.
8e07c86e 2094 pod/*.pod in $privlib/pod/.
2095
d6baa268 2096Installperl will also create the directories listed above
2097in L<"Installation Directories">.
4633a7c4 2098
d56c5707 2099Perl's *.h header files and the libperl library are also installed
d6baa268 2100under $archlib so that any user may later build new modules, run the
56c6f531 2101optional Perl compiler, or embed the perl interpreter into another
2102program even if the Perl source is no longer available.
8e07c86e 2103
d56c5707 2104Sometimes you only want to install the version-specific parts of the perl
2105installation. For example, you may wish to install a newer version of
2106perl alongside an already installed production version of perl without
2107disabling installation of new modules for the production version.
2108To only install the version-specific parts of the perl installation, run
2109
2110 Configure -Dversiononly
2111
2112or answer 'y' to the appropriate Configure prompt. Alternatively,
2113you can just manually run
2114
2115 ./perl installperl -v
2116
2117and skip installman altogether.
2118See also L<"Maintaining completely separate versions"> for another
2119approach.
2120
aa689395 2121=head1 Coexistence with earlier versions of perl5
4633a7c4 2122
693762b4 2123In general, you can usually safely upgrade from one version of Perl (e.g.
21245.004_04) to another similar version (e.g. 5.004_05) without re-compiling
2125all of your add-on extensions. You can also safely leave the old version
2126around in case the new version causes you problems for some reason.
2127For example, if you want to be sure that your script continues to run
dc45a647 2128with 5.004_04, simply replace the '#!/usr/local/bin/perl' line at the
693762b4 2129top of the script with the particular version you want to run, e.g.
2130#!/usr/local/bin/perl5.00404.
2131
693762b4 2132Most extensions will probably not need to be recompiled to use
2133with a newer version of perl. Here is how it is supposed to work.
2134(These examples assume you accept all the Configure defaults.)
2135
d6baa268 2136Suppose you already have version 5.005_03 installed. The directories
2137searched by 5.005_03 are
2138
2139 /usr/local/lib/perl5/5.00503/$archname
2140 /usr/local/lib/perl5/5.00503
2141 /usr/local/lib/perl5/site_perl/5.005/$archname
2142 /usr/local/lib/perl5/site_perl/5.005
2143
0a08c020 2144Beginning with 5.6.0 the version number in the site libraries are
2145fully versioned. Now, suppose you install version 5.6.0. The directories
2146searched by version 5.6.0 will be
d6baa268 2147
0a08c020 2148 /usr/local/lib/perl5/5.6.0/$archname
2149 /usr/local/lib/perl5/5.6.0
2150 /usr/local/lib/perl5/site_perl/5.6.0/$archname
2151 /usr/local/lib/perl5/site_perl/5.6.0
d6baa268 2152
2153 /usr/local/lib/perl5/site_perl/5.005/$archname
2154 /usr/local/lib/perl5/site_perl/5.005
c42e3e15 2155 /usr/local/lib/perl5/site_perl/
bfb7748a 2156
c42e3e15 2157Notice the last three entries -- Perl understands the default structure
d6baa268 2158of the $sitelib directories and will look back in older, compatible
2159directories. This way, modules installed under 5.005_03 will continue
0a08c020 2160to be usable by 5.005_03 but will also accessible to 5.6.0. Further,
d6baa268 2161suppose that you upgrade a module to one which requires features
0a08c020 2162present only in 5.6.0. That new module will get installed into
2163/usr/local/lib/perl5/site_perl/5.6.0 and will be available to 5.6.0,
d6baa268 2164but will not interfere with the 5.005_03 version.
bfb7748a 2165
c42e3e15 2166The last entry, /usr/local/lib/perl5/site_perl/, is there so that
21675.6.0 will look for 5.004-era pure perl modules.
d6baa268 2168
0a08c020 2169Lastly, suppose you now install version 5.6.1, which we'll assume is
2170binary compatible with 5.6.0 and 5.005. The directories searched
2171by 5.6.1 (if you don't change the Configure defaults) will be:
d6baa268 2172
265f5c4a 2173 /usr/local/lib/perl5/5.6.1/$archname
2174 /usr/local/lib/perl5/5.6.1
0a08c020 2175 /usr/local/lib/perl5/site_perl/5.6.1/$archname
2176 /usr/local/lib/perl5/site_perl/5.6.1
2177
2178 /usr/local/lib/perl5/site_perl/5.6.0/$archname
2179 /usr/local/lib/perl5/site_perl/5.6.0
d6baa268 2180
2181 /usr/local/lib/perl5/site_perl/5.005/$archname
2182 /usr/local/lib/perl5/site_perl/5.005
2183 /usr/local/lib/perl5/site_perl/
bfb7748a 2184
0a08c020 2185Assuming the users in your site are still actively using perl 5.6.0 and
21865.005 after you installed 5.6.1, you can continue to install add-on
2187extensions using any of perl 5.6.1, 5.6.0, or 5.005. The installations
2188of these different versions remain distinct, but remember that the newer
2189versions of perl are automatically set up to search the site libraries of
2190the older ones. This means that installing a new extension with 5.005
2191will make it visible to all three versions. Later, if you install the
2192same extension using, say, perl 5.6.1, it will override the 5.005-installed
2193version, but only for perl 5.6.1.
2194
2195This way, you can choose to share compatible extensions, but also upgrade
2196to a newer version of an extension that may be incompatible with earlier
2197versions, without breaking the earlier versions' installations.
693762b4 2198
2199=head2 Maintaining completely separate versions
4633a7c4 2200
1ec51d55 2201Many users prefer to keep all versions of perl in completely
d6baa268 2202separate directories. This guarantees that an update to one version
0a08c020 2203won't interfere with another version. (The defaults guarantee this for
2204libraries after 5.6.0, but not for executables. TODO?) One convenient
2205way to do this is by using a separate prefix for each version, such as
d52d4e46 2206
46bb10fb 2207 sh Configure -Dprefix=/opt/perl5.004
d52d4e46 2208
46bb10fb 2209and adding /opt/perl5.004/bin to the shell PATH variable. Such users
d52d4e46 2210may also wish to add a symbolic link /usr/local/bin/perl so that
2211scripts can still start with #!/usr/local/bin/perl.
2212
693762b4 2213Others might share a common directory for maintenance sub-versions
2214(e.g. 5.004 for all 5.004_0x versions), but change directory with
2215each major version.
2216
6877a1cf 2217If you are installing a development subversion, you probably ought to
2218seriously consider using a separate directory, since development
2219subversions may not have all the compatibility wrinkles ironed out
2220yet.
2221
0a08c020 2222=head2 Upgrading from 5.005 to 5.6.0
693762b4 2223
c42e3e15 2224Most extensions built and installed with versions of perl
2225prior to 5.005_50 will not need to be recompiled to be used with
22265.6.0. If you find you do need to rebuild an extension with 5.6.0,
2227you may safely do so without disturbing the 5.005 installation.
2228(See L<"Coexistence with earlier versions of perl5"> above.)
2229
2230See your installed copy of the perllocal.pod file for a (possibly
2231incomplete) list of locally installed modules. Note that you want
2232perllocal.pod not perllocale.pod for installed module information.
693762b4 2233
8e07c86e 2234=head1 Coexistence with perl4
2235
2236You can safely install perl5 even if you want to keep perl4 around.
2237
1ec51d55 2238By default, the perl5 libraries go into /usr/local/lib/perl5/, so
2239they don't override the perl4 libraries in /usr/local/lib/perl/.
8e07c86e 2240
2241In your /usr/local/bin directory, you should have a binary named
1ec51d55 2242perl4.036. That will not be touched by the perl5 installation
8e07c86e 2243process. Most perl4 scripts should run just fine under perl5.
2244However, if you have any scripts that require perl4, you can replace
d6baa268 2245the #! line at the top of them by #!/usr/local/bin/perl4.036 (or
2246whatever the appropriate pathname is). See pod/perltrap.pod for
2247possible problems running perl4 scripts under perl5.
8e07c86e 2248
aa689395 2249=head1 cd /usr/include; h2ph *.h sys/*.h
2250
d6baa268 2251Some perl scripts need to be able to obtain information from the
2252system header files. This command will convert the most commonly used
1ec51d55 2253header files in /usr/include into files that can be easily interpreted
d6baa268 2254by perl. These files will be placed in the architecture-dependent
2255library ($archlib) directory you specified to Configure.
aa689395 2256
d6baa268 2257Note: Due to differences in the C and perl languages, the conversion
2258of the header files is not perfect. You will probably have to
2259hand-edit some of the converted files to get them to parse correctly.
2260For example, h2ph breaks spectacularly on type casting and certain
2261structures.
aa689395 2262
fb73857a 2263=head1 installhtml --help
aa689395 2264
3e3baf6d 2265Some sites may wish to make perl documentation available in HTML
2266format. The installhtml utility can be used to convert pod
fb73857a 2267documentation into linked HTML files and install them.
aa689395 2268
d6baa268 2269Currently, the supplied ./installhtml script does not make use of the
2270html Configure variables. This should be fixed in a future release.
2271
fb73857a 2272The following command-line is an example of one used to convert
3e3baf6d 2273perl documentation:
aa689395 2274
3e3baf6d 2275 ./installhtml \
2276 --podroot=. \
2277 --podpath=lib:ext:pod:vms \
2278 --recurse \
2279 --htmldir=/perl/nmanual \
2280 --htmlroot=/perl/nmanual \
2281 --splithead=pod/perlipc \
2282 --splititem=pod/perlfunc \
2283 --libpods=perlfunc:perlguts:perlvar:perlrun:perlop \
2284 --verbose
2285
2286See the documentation in installhtml for more details. It can take
2287many minutes to execute a large installation and you should expect to
2288see warnings like "no title", "unexpected directive" and "cannot
2289resolve" as the files are processed. We are aware of these problems
2290(and would welcome patches for them).
aa689395 2291
fb73857a 2292You may find it helpful to run installhtml twice. That should reduce
2293the number of "cannot resolve" warnings.
2294
aa689395 2295=head1 cd pod && make tex && (process the latex files)
2296
2297Some sites may also wish to make the documentation in the pod/ directory
2298available in TeX format. Type
2299
2300 (cd pod && make tex && <process the latex files>)
2301
8ebf57cf 2302=head1 Minimizing the Perl installation
2303
2304The following section is meant for people worrying about squeezing the
2305Perl installation into minimal systems (for example when installing
2306operating systems, or in really small filesystems).
2307
2308In the following we offer two different slimmed down installation
2309recipes. They are informative, not normative: the choice of files
2310depends on what you need.
2311
2312Firstly, the bare minimum to run this script
2313
2314 use strict;
2315 use warnings;
2316 foreach my $f (</*>) {
2317 print("$f\n");
2318 }
2319
2320in Solaris is as follows (under $Config{prefix}):
2321
2322 ./bin/perl
2323 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/autosplit.ix
2324 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_expandspec.al
2325 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_find_symbol_anywhere.al
2326 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_findfile.al
2327 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/Glob.so
2328 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/autosplit.ix
2329 ./lib/perl5/5.6.1/sun4-solaris-64int/Config.pm
2330 ./lib/perl5/5.6.1/sun4-solaris-64int/XSLoader.pm
2331 ./lib/perl5/5.6.1/sun4-solaris-64int/DynaLoader.pm
2332 ./lib/perl5/5.6.1/sun4-solaris-64int/CORE/libperl.so
2333 ./lib/perl5/5.6.1/strict.pm
2334 ./lib/perl5/5.6.1/warnings.pm
2335 ./lib/perl5/5.6.1/Carp.pm
2336 ./lib/perl5/5.6.1/Exporter.pm
2337 ./lib/perl5/5.6.1/File/Glob.pm
2338 ./lib/perl5/5.6.1/AutoLoader.pm
2339 ./lib/perl5/5.6.1/vars.pm
2340 ./lib/perl5/5.6.1/warnings/register.pm
2341 ./lib/perl5/5.6.1/Carp/Heavy.pm
2342 ./lib/perl5/5.6.1/Exporter/Heavy.pm
2343
2344Secondly, Debian perl-base package contains the following files,
2345size about 1.2MB in its i386 version:
2346
2347 /usr/share/doc/perl/Documentation
2348 /usr/share/doc/perl/README.Debian
2349 /usr/share/doc/perl/copyright
2350 /usr/share/doc/perl/AUTHORS.gz
2351 /usr/share/doc/perl/changelog.Debian.gz
2352 /usr/share/man/man1/perl.1.gz
2353 /usr/share/perl/5.6.1/AutoLoader.pm
2354 /usr/share/perl/5.6.1/Carp.pm
2355 /usr/share/perl/5.6.1/Carp/Heavy.pm
2356 /usr/share/perl/5.6.1/Cwd.pm
2357 /usr/share/perl/5.6.1/Exporter.pm
2358 /usr/share/perl/5.6.1/Exporter/Heavy.pm
2359 /usr/share/perl/5.6.1/File/Spec.pm
2360 /usr/share/perl/5.6.1/File/Spec/Unix.pm
2361 /usr/share/perl/5.6.1/FileHandle.pm
2362 /usr/share/perl/5.6.1/Getopt/Long.pm
2363 /usr/share/perl/5.6.1/IO/Socket/INET.pm
2364 /usr/share/perl/5.6.1/IO/Socket/UNIX.pm
2365 /usr/share/perl/5.6.1/IPC/Open2.pm
2366 /usr/share/perl/5.6.1/IPC/Open3.pm
2367 /usr/share/perl/5.6.1/SelectSaver.pm
2368 /usr/share/perl/5.6.1/Symbol.pm
2369 /usr/share/perl/5.6.1/Text/Tabs.pm
2370 /usr/share/perl/5.6.1/Text/Wrap.pm
2371 /usr/share/perl/5.6.1/attributes.pm
2372 /usr/share/perl/5.6.1/auto/Getopt/Long/GetOptions.al
2373 /usr/share/perl/5.6.1/auto/Getopt/Long/FindOption.al
2374 /usr/share/perl/5.6.1/auto/Getopt/Long/Configure.al
2375 /usr/share/perl/5.6.1/auto/Getopt/Long/config.al
2376 /usr/share/perl/5.6.1/auto/Getopt/Long/Croak.al
2377 /usr/share/perl/5.6.1/auto/Getopt/Long/autosplit.ix
2378 /usr/share/perl/5.6.1/base.pm
2379 /usr/share/perl/5.6.1/constant.pm
2380 /usr/share/perl/5.6.1/fields.pm
2381 /usr/share/perl/5.6.1/integer.pm
2382 /usr/share/perl/5.6.1/lib.pm
2383 /usr/share/perl/5.6.1/locale.pm
2384 /usr/share/perl/5.6.1/overload.pm
2385 /usr/share/perl/5.6.1/strict.pm
2386 /usr/share/perl/5.6.1/vars.pm
2387 /usr/share/perl/5.6.1/warnings.pm
2388 /usr/share/perl/5.6.1/warnings/register.pm
2389 /usr/bin/perl
2390 /usr/lib/perl/5.6.1/Config.pm
2391 /usr/lib/perl/5.6.1/Data/Dumper.pm
2392 /usr/lib/perl/5.6.1/DynaLoader.pm
2393 /usr/lib/perl/5.6.1/Errno.pm
2394 /usr/lib/perl/5.6.1/Fcntl.pm
2395 /usr/lib/perl/5.6.1/File/Glob.pm
2396 /usr/lib/perl/5.6.1/IO.pm
2397 /usr/lib/perl/5.6.1/IO/File.pm
2398 /usr/lib/perl/5.6.1/IO/Handle.pm
2399 /usr/lib/perl/5.6.1/IO/Pipe.pm
2400 /usr/lib/perl/5.6.1/IO/Seekable.pm
2401 /usr/lib/perl/5.6.1/IO/Select.pm
2402 /usr/lib/perl/5.6.1/IO/Socket.pm
2403 /usr/lib/perl/5.6.1/POSIX.pm
2404 /usr/lib/perl/5.6.1/Socket.pm
2405 /usr/lib/perl/5.6.1/XSLoader.pm
2406 /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.so
2407 /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.bs
2408 /usr/lib/perl/5.6.1/auto/DynaLoader/dl_findfile.al
2409 /usr/lib/perl/5.6.1/auto/DynaLoader/dl_expandspec.al
2410 /usr/lib/perl/5.6.1/auto/DynaLoader/dl_find_symbol_anywhere.al
2411 /usr/lib/perl/5.6.1/auto/DynaLoader/autosplit.ix
2412 /usr/lib/perl/5.6.1/auto/DynaLoader/DynaLoader.a
2413 /usr/lib/perl/5.6.1/auto/DynaLoader/extralibs.ld
2414 /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.so
2415 /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.bs
2416 /usr/lib/perl/5.6.1/auto/File/Glob/Glob.bs
2417 /usr/lib/perl/5.6.1/auto/File/Glob/Glob.so
2418 /usr/lib/perl/5.6.1/auto/File/Glob/autosplit.ix
2419 /usr/lib/perl/5.6.1/auto/IO/IO.so
2420 /usr/lib/perl/5.6.1/auto/IO/IO.bs
2421 /usr/lib/perl/5.6.1/auto/POSIX/POSIX.bs
2422 /usr/lib/perl/5.6.1/auto/POSIX/POSIX.so
2423 /usr/lib/perl/5.6.1/auto/POSIX/autosplit.ix
2424 /usr/lib/perl/5.6.1/auto/POSIX/load_imports.al
2425 /usr/lib/perl/5.6.1/auto/Socket/Socket.so
2426 /usr/lib/perl/5.6.1/auto/Socket/Socket.bs
2427
aa689395 2428=head1 Reporting Problems
2429
bfb7748a 2430If you have difficulty building perl, and none of the advice in this file
2431helps, and careful reading of the error message and the relevant manual
2432pages on your system doesn't help either, then you should send a message
7f2de2d2 2433to either the comp.lang.perl.misc newsgroup or to perlbug@perl.org with
bfb7748a 2434an accurate description of your problem.
aa689395 2435
bfb7748a 2436Please include the output of the ./myconfig shell script that comes with
2437the distribution. Alternatively, you can use the perlbug program that
2438comes with the perl distribution, but you need to have perl compiled
2439before you can use it. (If you have not installed it yet, you need to
f5b3b617 2440run C<./perl -Ilib utils/perlbug> instead of a plain C<perlbug>.)
aa689395 2441
694a7e45 2442Please try to make your message brief but clear. Trim out unnecessary
2443information. Do not include large files (such as config.sh or a complete
2444Configure or make log) unless absolutely necessary. Do not include a
2445complete transcript of your build session. Just include the failing
d6baa268 2446commands, the relevant error messages, and whatever preceding commands
694a7e45 2447are necessary to give the appropriate context. Plain text should
2448usually be sufficient--fancy attachments or encodings may actually
2449reduce the number of people who read your message. Your message
2450will get relayed to over 400 subscribers around the world so please
2451try to keep it brief but clear.
aa689395 2452
8e07c86e 2453=head1 DOCUMENTATION
2454
bfb7748a 2455Read the manual entries before running perl. The main documentation
2456is in the pod/ subdirectory and should have been installed during the
8e07c86e 2457build process. Type B<man perl> to get started. Alternatively, you
bfb7748a 2458can type B<perldoc perl> to use the supplied perldoc script. This is
2459sometimes useful for finding things in the library modules.
8e07c86e 2460
1ec51d55 2461Under UNIX, you can produce a documentation book in postscript form,
bfb7748a 2462along with its table of contents, by going to the pod/ subdirectory and
2463running (either):
34a2a22e 2464
2465 ./roffitall -groff # If you have GNU groff installed
aa689395 2466 ./roffitall -psroff # If you have psroff
34a2a22e 2467
2468This will leave you with two postscript files ready to be printed.
aa689395 2469(You may need to fix the roffitall command to use your local troff
2470set-up.)
34a2a22e 2471
bfb7748a 2472Note that you must have performed the installation already before running
2473the above, since the script collects the installed files to generate
2474the documentation.
34a2a22e 2475
8e07c86e 2476=head1 AUTHOR
2477
bfb7748a 2478Original author: Andy Dougherty doughera@lafayette.edu , borrowing very
2479heavily from the original README by Larry Wall, with lots of helpful
2480feedback and additions from the perl5-porters@perl.org folks.
fb73857a 2481
f5b3b617 2482If you have problems, corrections, or questions, please see
2483L<"Reporting Problems"> above.
2484
2485=head1 REDISTRIBUTION
2486
2487This document is part of the Perl package and may be distributed under
d6baa268 2488the same terms as perl itself, with the following additional request:
f5b3b617 2489If you are distributing a modified version of perl (perhaps as part of
d6baa268 2490a larger package) please B<do> modify these installation instructions
2491and the contact information to match your distribution.