This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Note latest stable in INSTALL:
[perl5.git] / INSTALL
CommitLineData
f1300be0
YST
1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
4
8e07c86e
AD
5=head1 NAME
6
cb8c159f 7INSTALL - Build and Installation guide for perl 5.
8e07c86e
AD
8
9=head1 SYNOPSIS
10
7df75831 11First, make sure you have an up-to-date version of Perl. If you
ce80d64e
AD
12didn't get your Perl source from CPAN, check the latest version at
13http://www.cpan.org/src/. Perl uses a version scheme where even-numbered
08854360 14subreleases (like 5.8.x and 5.10.x) are stable maintenance releases and
ce80d64e
AD
15odd-numbered subreleases (like 5.7.x and 5.9.x) are unstable
16development releases. Development releases should not be used in
17production environments. Fixes and new features are first carefully
18tested in development releases and only if they prove themselves to be
19worthy will they be migrated to the maintenance releases.
3ce0d271 20
7df75831 21The basic steps to build and install perl 5 on a Unix system with all
dd3196cd 22the defaults are to run, from a freshly unpacked source tree:
8e07c86e 23
491517e0 24 sh Configure -de
8e07c86e
AD
25 make
26 make test
27 make install
36477c24 28
8e07c86e
AD
29Each of these is explained in further detail below.
30
cc65bb49
AD
31The above commands will install Perl to /usr/local (or some other
32platform-specific directory -- see the appropriate file in hints/.)
7df75831 33If that's not okay with you, you can run Configure interactively, by
ff52061e
RGS
34just typing "sh Configure" (without the -de args). You can also specify
35any prefix location by adding "-Dprefix='/some/dir'" to Configure's args.
36To explicitly name the perl binary, use the command
37"make install PERLNAME=myperl".
491517e0 38
668cbedd 39Building perl from source requires an ANSI compliant C compiler.
51eec7ec
MB
40A minimum of C89 is required. Some features available in C99 will
41be probed for and used when found. The perl build process does not
42rely on anything more than C89.
43
ff52061e 44These options, and many more, are explained in further detail below.
7f678428 45
e0ddbfb2
RS
46If you're building perl from a git repository, you should also consult
47the documentation in pod/perlgit.pod for information on that special
48circumstance.
49
8d74ce1c 50If you have problems, corrections, or questions, please see
ff52061e 51L<"Reporting Problems"> below.
8d74ce1c 52
7beaa944 53For information on what's new in this release, see the
37ee6528 54pod/perldelta.pod file. For more information about how to find more
9519d2ec 55specific detail about changes, see the Changes file.
c3edaffb 56
1ec51d55 57=head1 DESCRIPTION
edb1cbcb 58
c3edaffb 59This document is written in pod format as an easy way to indicate its
60structure. The pod format is described in pod/perlpod.pod, but you can
1ec51d55
CS
61read it as is with any pager or editor. Headings and items are marked
62by lines beginning with '='. The other mark-up used is
63
64 B<text> embolden text, used for switches, programs or commands
65 C<code> literal code
66 L<name> A link (cross reference) to name
ce80d64e 67 F<file> A filename
1ec51d55 68
c42e3e15 69Although most of the defaults are probably fine for most users,
ce80d64e 70you should probably at least skim through this document before
1ec51d55 71proceeding.
c3edaffb 72
ce80d64e
AD
73In addition to this file, check if there is a README file specific to
74your operating system, since it may provide additional or different
75instructions for building Perl. If there is a hint file for your
dd3196cd
RGS
76system (in the hints/ directory) you might also want to read it
77for even more information.
c42e3e15 78
ce80d64e
AD
79For additional information about porting Perl, see the section on
80L<"Porting information"> below, and look at the files in the Porting/
81directory.
d56c5707 82
ce80d64e 83=head1 PRELIMINARIES
c42e3e15 84
ce80d64e 85=head2 Changes and Incompatibilities
c42e3e15 86
37ee6528 87Please see pod/perldelta.pod for a description of the changes and
ce80d64e
AD
88potential incompatibilities introduced with this release. A few of
89the most important issues are listed below, but you should refer
37ee6528 90to pod/perldelta.pod for more detailed information.
c42e3e15 91
ab97e755
MB
92B<WARNING:> This version is not binary compatible with earlier versions
93of Perl. If you have built extensions (i.e. modules that include C code)
64fa5b0b
DM
94using an earlier version of Perl, you will need to rebuild and reinstall
95those extensions.
1b1c1ae2
GS
96
97Pure perl modules without XS or C code should continue to work fine
dd3196cd 98without reinstallation. See the discussion below on
7df75831 99L<"Coexistence with earlier versions of perl 5"> for more details.
693762b4
AD
100
101The standard extensions supplied with Perl will be handled automatically.
102
ce80d64e
AD
103On a related issue, old modules may possibly be affected by the changes
104in the Perl language in the current release. Please see
37ee6528 105pod/perldelta.pod for a description of what's changed. See your
ce80d64e 106installed copy of the perllocal.pod file for a (possibly incomplete)
c75cfcf0
FC
107list of locally installed modules. Also see the L<CPAN> module's
108C<autobundle> function for one way to make a "bundle" of your currently
109installed modules.
16dc217a 110
aa689395 111=head1 Run Configure
8e07c86e
AD
112
113Configure will figure out various things about your system. Some
114things Configure will figure out for itself, other things it will ask
d6baa268
JH
115you about. To accept the default, just press RETURN. The default is
116almost always okay. It is normal for some things to be "NOT found",
117since Configure often searches for many different ways of performing
118the same function.
119
ce80d64e 120At any Configure prompt, you can type &-d and Configure will use the
d6baa268 121defaults from then on.
8e07c86e
AD
122
123After it runs, Configure will perform variable substitution on all the
1ec51d55 124*.SH files and offer to run make depend.
8e07c86e 125
dd3196cd
RGS
126The results of a Configure run are stored in the config.sh and Policy.sh
127files.
128
ce80d64e 129=head2 Common Configure options
844fc9f4 130
ce80d64e 131Configure supports a number of useful options. Run
844fc9f4 132
ce80d64e 133 Configure -h
d6baa268 134
ce80d64e 135to get a listing. See the Porting/Glossary file for a complete list of
fb73857a 136Configure variables you can set and their definitions.
137
d6baa268
JH
138=over 4
139
08854360 140=item C compiler
d6baa268 141
08854360
RGS
142To compile with gcc, if it's not the default compiler on your
143system, you should run
8e07c86e
AD
144
145 sh Configure -Dcc=gcc
146
08854360 147This is the preferred way to specify gcc (or any another alternative
8e07c86e
AD
148compiler) so that the hints files can set appropriate defaults.
149
d6baa268 150=item Installation prefix
4633a7c4 151
8e07c86e 152By default, for most systems, perl will be installed in
8d74ce1c 153/usr/local/{bin, lib, man}. (See L<"Installation Directories">
7df75831 154and L<"Coexistence with earlier versions of perl 5"> below for
8d74ce1c
AD
155further details.)
156
157You can specify a different 'prefix' for the default installation
ce80d64e 158directory when Configure prompts you, or by using the Configure command
8d74ce1c 159line option -Dprefix='/some/directory', e.g.
8e07c86e 160
25f94b33 161 sh Configure -Dprefix=/opt/perl
4633a7c4 162
d6baa268
JH
163If your prefix contains the string "perl", then the suggested
164directory structure is simplified. For example, if you use
165prefix=/opt/perl, then Configure will suggest /opt/perl/lib instead of
166/opt/perl/lib/perl5/. Again, see L<"Installation Directories"> below
bc70e9ec
JH
167for more details. Do not include a trailing slash, (i.e. /opt/perl/)
168or you may experience odd test failures.
8e07c86e 169
8d74ce1c
AD
170NOTE: You must not specify an installation directory that is the same
171as or below your perl source directory. If you do, installperl will
172attempt infinite recursion.
84902520 173
d6baa268
JH
174=item /usr/bin/perl
175
176It may seem obvious, but Perl is useful only when users can easily
177find it. It's often a good idea to have both /usr/bin/perl and
dd64f1c3 178/usr/local/bin/perl be symlinks to the actual binary. Be especially
d6baa268 179careful, however, not to overwrite a version of perl supplied by your
b66c6cec
AD
180vendor unless you are sure you know what you are doing. If you insist
181on replacing your vendor's perl, useful information on how it was
182configured may be found with
183
184 perl -V:config_args
185
186(Check the output carefully, however, since this doesn't preserve
ce80d64e
AD
187spaces in arguments to Configure. For that, you have to look carefully
188at config_arg1, config_arg2, etc.)
d6baa268 189
ce80d64e
AD
190By default, Configure will not try to link /usr/bin/perl to the current
191version of perl. You can turn on that behavior by running
d6baa268 192
7d56c962 193 Configure -Dinstallusrbinperl
d6baa268 194
7d56c962 195or by answering 'yes' to the appropriate Configure prompt.
d6baa268 196
ce80d64e
AD
197In any case, system administrators are strongly encouraged to put
198(symlinks to) perl and its accompanying utilities, such as perldoc,
4682965a
MB
199into a directory typically found along a user's PATH, or in another
200obvious and convenient place.
201
71c4561b 202=item Building a development release
04d420f9 203
ce80d64e
AD
204For development releases (odd subreleases, like 5.9.x) if you want to
205use Configure -d, you will also need to supply -Dusedevel to Configure,
206because the default answer to the question "do you really want to
207Configure a development version?" is "no". The -Dusedevel skips that
208sanity check.
d6baa268
JH
209
210=back
8e07c86e 211
203c3eec
AD
212If you are willing to accept all the defaults, and you want terse
213output, you can run
214
215 sh Configure -des
216
dd3196cd 217=head2 Altering Configure variables for C compiler switches etc.
46bb10fb 218
ce80d64e
AD
219For most users, most of the Configure defaults are fine, or can easily
220be set on the Configure command line. However, if Configure doesn't
221have an option to do what you want, you can change Configure variables
222after the platform hints have been run by using Configure's -A switch.
223For example, here's how to add a couple of extra flags to C compiler
224invocations:
46bb10fb 225
08854360 226 sh Configure -Accflags="-DPERL_EXTERNAL_GLOB -DNO_HASH_SEED"
46bb10fb 227
5247441a 228To clarify, those ccflags values are not Configure options; if passed to
dd3196cd
RGS
229Configure directly, they won't do anything useful (they will define a
230variable in config.sh, but without taking any action based upon it).
231But when passed to the compiler, those flags will activate #ifdefd code.
5247441a 232
ce80d64e 233For more help on Configure switches, run
46bb10fb 234
ce80d64e 235 sh Configure -h
46bb10fb 236
ce80d64e 237=head2 Major Configure-time Build Options
46bb10fb 238
ce80d64e
AD
239There are several different ways to Configure and build perl for your
240system. For most users, the defaults are sensible and will work.
241Some users, however, may wish to further customize perl. Here are
242some of the main things you can change.
46bb10fb 243
ce80d64e 244=head3 Threads
cc65bb49 245
ce80d64e
AD
246On some platforms, perl can be compiled with support for threads. To
247enable this, run
4633a7c4 248
ce80d64e 249 sh Configure -Dusethreads
4633a7c4 250
ce80d64e 251The default is to compile without thread support.
cc65bb49 252
ab97e755
MB
253Perl used to have two different internal threads implementations. The
254current model (available internally since 5.6, and as a user-level module
255since 5.8) is called interpreter-based implementation (ithreads), with
256one interpreter per thread, and explicit sharing of data. The (deprecated)
2575.005 version (5005threads) was removed for release 5.10.
d6baa268 258
ce80d64e 259The 'threads' module is for use with the ithreads implementation. The
ab97e755
MB
260'Thread' module emulates the old 5005threads interface on top of the
261current ithreads model.
d6baa268 262
ce80d64e
AD
263When using threads, perl uses a dynamically-sized buffer for some of
264the thread-safe library calls, such as those in the getpw*() family.
265This buffer starts small, but it will keep growing until the result
266fits. To get a fixed upper limit, you should compile Perl with
267PERL_REENTRANT_MAXSIZE defined to be the number of bytes you want. One
268way to do this is to run Configure with
08854360 269C<-Accflags=-DPERL_REENTRANT_MAXSIZE=65536>.
d6baa268 270
08854360 271=head3 Large file support
b367e8b0 272
ce80d64e
AD
273Since Perl 5.6.0, Perl has supported large files (files larger than
2742 gigabytes), and in many common platforms like Linux or Solaris this
275support is on by default.
d6baa268 276
ce80d64e 277This is both good and bad. It is good in that you can use large files,
ab97e755
MB
278seek(), stat(), and -s them. It is bad in that if you are interfacing
279Perl using some extension, the components you are connecting to must also
ce80d64e
AD
280be large file aware: if Perl thinks files can be large but the other
281parts of the software puzzle do not understand the concept, bad things
08854360 282will happen.
d6baa268 283
ce80d64e
AD
284There's also one known limitation with the current large files
285implementation: unless you also have 64-bit integers (see the next
286section), you cannot use the printf/sprintf non-decimal integer formats
287like C<%x> to print filesizes. You can use C<%d>, though.
d6baa268 288
71c4561b
RGS
289If you want to compile perl without large file support, use
290
291 sh Configure -Uuselargefiles
292
08854360 293=head3 64 bit support
d6baa268 294
08854360
RGS
295If your platform does not run natively at 64 bits, but can simulate
296them with compiler flags and/or C<long long> or C<int64_t>,
ce80d64e 297you can build a perl that uses 64 bits.
d6baa268 298
ce80d64e
AD
299There are actually two modes of 64-bitness: the first one is achieved
300using Configure -Duse64bitint and the second one using Configure
301-Duse64bitall. The difference is that the first one is minimal and
302the second one maximal. The first works in more places than the second.
d6baa268 303
ce80d64e
AD
304The C<use64bitint> option does only as much as is required to get
30564-bit integers into Perl (this may mean, for example, using "long
306longs") while your memory may still be limited to 2 gigabytes (because
307your pointers could still be 32-bit). Note that the name C<64bitint>
308does not imply that your C compiler will be using 64-bit C<int>s (it
309might, but it doesn't have to). The C<use64bitint> simply means that
310you will be able to have 64 bit-wide scalar values.
d6baa268 311
ce80d64e
AD
312The C<use64bitall> option goes all the way by attempting to switch
313integers (if it can), longs (and pointers) to being 64-bit. This may
314create an even more binary incompatible Perl than -Duse64bitint: the
315resulting executable may not run at all in a 32-bit box, or you may
316have to reboot/reconfigure/rebuild your operating system to be 64-bit
317aware.
d6baa268 318
08854360 319Natively 64-bit systems need neither -Duse64bitint nor -Duse64bitall.
0e78eb44
MB
320On these systems, it might be the default compilation mode, and there
321is currently no guarantee that passing no use64bitall option to the
322Configure process will build a 32bit perl. Implementing -Duse32bit*
1ed7425e 323options is planned for a future release of perl.
d6baa268 324
ce80d64e 325=head3 Long doubles
d6baa268 326
ce80d64e
AD
327In some systems you may be able to use long doubles to enhance the
328range and precision of your double precision floating point numbers
329(that is, Perl's numbers). Use Configure -Duselongdouble to enable
330this support (if it is available).
d6baa268 331
aacf4ea2
JH
332Note that the exact format and range of long doubles varies:
333the most common is the x86 80-bit (64 bits of mantissa) format,
334but there are others, with different mantissa and exponent ranges.
335
ce80d64e 336=head3 "more bits"
b367e8b0 337
ce80d64e
AD
338You can "Configure -Dusemorebits" to turn on both the 64-bit support
339and the long double support.
b367e8b0 340
257c99f5
JH
341=head3 quadmath
342
b7ce25dd 343One option for more precision is that gcc 4.6 and later have a library
257c99f5
JH
344called quadmath, which implements the IEEE 754 quadruple precision
345(128-bit, 113 bits of mantissa) floating point numbers. The library
346works at least on x86 and ia64 platforms. It may be part of your gcc
347installation, or you may need to install it separately.
348
79f6e7a5
JH
349With "Configure -Dusequadmath" you can try enabling its use, but note
350the compiler dependency, you may need to also add "-Dcc=...".
84e6cb05 351At C level the type is called C<__float128> (note, not "long double"),
b7ce25dd 352but Perl source knows it as NV. (This is not "long doubles".)
257c99f5 353
ce80d64e 354=head3 Algorithmic Complexity Attacks on Hashes
504f80c1 355
e6b54db6
YO
356Perl 5.18 reworked the measures used to secure its hash function
357from algorithmic complexity attacks. By default it will build with
358all of these measures enabled along with support for controlling and
359disabling them via environment variables.
360
361You can override various aspects of this feature by defining various
362symbols during configure. An example might be:
363
364 Configure -Accflags=-DPERL_HASH_FUNC_SIPHASH
365
366B<Unless stated otherwise these options are considered experimental or
367insecure and are not recommended for production use.>
368
369Perl 5.18 includes support for multiple hash functions, and changed
370the default (to ONE_AT_A_TIME_HARD), you can choose a different
371algorithm by defining one of the following symbols. Note that as of
372Perl 5.18 we can only recommend use of the default or SIPHASH. All
373the others are known to have security issues and are for research
374purposes only.
375
376 PERL_HASH_FUNC_SIPHASH
377 PERL_HASH_FUNC_SDBM
378 PERL_HASH_FUNC_DJB2
379 PERL_HASH_FUNC_SUPERFAST
380 PERL_HASH_FUNC_MURMUR3
381 PERL_HASH_FUNC_ONE_AT_A_TIME
382 PERL_HASH_FUNC_ONE_AT_A_TIME_HARD
383 PERL_HASH_FUNC_ONE_AT_A_TIME_OLD
384
385Perl 5.18 randomizes the order returned by keys(), values(), and each(),
386and allows controlling this behavior by using of the PERL_PERTURB_KEYS
387option. You can disable this option entirely with the define:
388
389 PERL_PERTURB_KEYS_DISABLED
390
391You can disable the environment variable checks and specify the type of
392key traversal randomization to be used by defining one of these:
393
394 PERL_PERTURB_KEYS_RANDOM
395 PERL_PERTURB_KEYS_DETERMINISTIC
396
397In Perl 5.18 the seed used for the hash function is randomly selected
eb717850 398at process start which can be overridden by specifying a seed by setting
e6b54db6
YO
399the PERL_HASH_SEED environment variable.
400
401You can change this behavior by building perl with the
402
403 USE_HASH_SEED_EXPLICIT
404
405define, in which case one has to explicitly set the PERL_HASH_SEED
406environment variable to enable the security feature or by adding
407
408 NO_HASH_SEED
409
410to the compilation flags to completely disable the randomisation feature.
411Note these modes are poorly tested, insecure and not recommended.
504f80c1 412
3debabd9 413B<Perl has never guaranteed any ordering of the hash keys>, and the
86358043
NC
414ordering has already changed several times during the lifetime of Perl
4155. Also, the ordering of hash keys has always been, and continues to
08854360 416be, affected by the insertion order. Note that because of this
86358043 417randomisation for example the Data::Dumper results will be different
08854360 418between different runs of Perl, since Data::Dumper by default dumps
86358043
NC
419hashes "unordered". The use of the Data::Dumper C<Sortkeys> option is
420recommended.
504f80c1 421
ab97e755
MB
422See L<perlrun/PERL_HASH_SEED> and L<perlrun/PERL_PERTURB_KEYS> for
423details on the environment variables, and L<perlsec/Algorithmic
424Complexity Attacks> for further security details.
e6b54db6 425
ce80d64e 426=head3 SOCKS
1b9c9cf5
DH
427
428Perl can be configured to be 'socksified', that is, to use the SOCKS
429TCP/IP proxy protocol library. SOCKS is used to give applications
430access to transport layer network proxies. Perl supports only SOCKS
71c4561b
RGS
431Version 5. The corresponding Configure option is -Dusesocks.
432You can find more about SOCKS from wikipedia at
433L<http://en.wikipedia.org/wiki/SOCKS>.
1b9c9cf5 434
ce80d64e 435=head3 Dynamic Loading
d6baa268 436
71c4561b
RGS
437By default, Configure will compile perl to use dynamic loading.
438If you want to force perl to be compiled completely
d6baa268
JH
439statically, you can either choose this when Configure prompts you or
440you can use the Configure command line option -Uusedl.
7df75831
RGS
441With this option, you won't be able to use any new extension
442(XS) module without recompiling perl itself.
d6baa268 443
ce80d64e 444=head3 Building a shared Perl library
c3edaffb 445
446Currently, for most systems, the main perl executable is built by
447linking the "perl library" libperl.a with perlmain.o, your static
8ba4bff0 448extensions, and various extra libraries, such as -lm.
c3edaffb 449
08854360 450On systems that support dynamic loading, it may be possible to
9d67150a 451replace libperl.a with a shared libperl.so. If you anticipate building
c3edaffb 452several different perl binaries (e.g. by embedding libperl into
453different programs, or by using the optional compiler extension), then
9d67150a 454you might wish to build a shared libperl.so so that all your binaries
c3edaffb 455can share the same library.
456
457The disadvantages are that there may be a significant performance
9d67150a 458penalty associated with the shared libperl.so, and that the overall
aa689395 459mechanism is still rather fragile with respect to different versions
c3edaffb 460and upgrades.
461
462In terms of performance, on my test system (Solaris 2.5_x86) the perl
9d67150a 463test suite took roughly 15% longer to run with the shared libperl.so.
c3edaffb 464Your system and typical applications may well give quite different
465results.
466
467The default name for the shared library is typically something like
08854360 468libperl.so.5.8.8 (for Perl 5.8.8), or libperl.so.588, or simply
9d67150a 469libperl.so. Configure tries to guess a sensible naming convention
c3edaffb 470based on your C library name. Since the library gets installed in a
471version-specific architecture-dependent directory, the exact name
472isn't very important anyway, as long as your linker is happy.
473
c3edaffb 474You can elect to build a shared libperl by
475
ce80d64e
AD
476 sh Configure -Duseshrplib
477
478To build a shared libperl, the environment variable controlling shared
479library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
f05550c0 480Darwin, LD_LIBRARY_PATH/SHLIB_PATH
ce80d64e
AD
481for HP-UX, LIBPATH for AIX, PATH for Cygwin) must be set up to include
482the Perl build directory because that's where the shared libperl will
483be created. Configure arranges makefile to have the correct shared
484library search settings. You can find the name of the environment
485variable Perl thinks works in your your system by
486
487 grep ldlibpthname config.sh
488
489However, there are some special cases where manually setting the
490shared library path might be required. For example, if you want to run
491something like the following with the newly-built but not-yet-installed
492./perl:
493
04bd6448 494 ./perl -MTestInit t/misc/failing_test.t
08854360 495
ce80d64e 496or
08854360 497
ce80d64e
AD
498 ./perl -Ilib ~/my_mission_critical_test
499
500then you need to set up the shared library path explicitly.
501You can do this with
502
503 LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
504
505for Bourne-style shells, or
506
507 setenv LD_LIBRARY_PATH `pwd`
508
509for Csh-style shells. (This procedure may also be needed if for some
510unexpected reason Configure fails to set up makefile correctly.) (And
511again, it may be something other than LD_LIBRARY_PATH for you, see above.)
512
513You can often recognize failures to build/use a shared libperl from error
514messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
515for example:
08854360
RGS
516
517 18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
ce80d64e
AD
518
519There is also an potential problem with the shared perl library if you
520want to have more than one "flavor" of the same version of perl (e.g.
521with and without -DDEBUGGING). For example, suppose you build and
08854360
RGS
522install a standard Perl 5.10.0 with a shared library. Then, suppose you
523try to build Perl 5.10.0 with -DDEBUGGING enabled, but everything else
ce80d64e
AD
524the same, including all the installation directories. How can you
525ensure that your newly built perl will link with your newly built
526libperl.so.8 rather with the installed libperl.so.8? The answer is
527that you might not be able to. The installation directory is encoded
528in the perl binary with the LD_RUN_PATH environment variable (or
529equivalent ld command-line option). On Solaris, you can override that
530with LD_LIBRARY_PATH; on Linux, you can only override at runtime via
531LD_PRELOAD, specifying the exact filename you wish to be used; and on
532Digital Unix, you can override LD_LIBRARY_PATH by setting the
533_RLD_ROOT environment variable to point to the perl build directory.
534
535In other words, it is generally not a good idea to try to build a perl
536with a shared library if $archlib/CORE/$libperl already exists from a
537previous build.
538
539A good workaround is to specify a different directory for the
540architecture-dependent library for your -DDEBUGGING version of perl.
541You can do this by changing all the *archlib* variables in config.sh to
542point to your new architecture-dependent library.
543
575e1338
NC
544=head3 Environment access
545
ab97e755
MB
546Perl often needs to write to the program's environment, such as when
547C<%ENV> is assigned to. Many implementations of the C library function
548C<putenv()> leak memory, so where possible perl will manipulate the
549environment directly to avoid these leaks. The default is now to perform
550direct manipulation whenever perl is running as a stand alone interpreter,
551and to call the safe but potentially leaky C<putenv()> function when the
552perl interpreter is embedded in another application. You can force perl
553to always use C<putenv()> by compiling with
554C<-Accflags="-DPERL_USE_SAFE_PUTENV">, see section L</"Altering Configure
555variables for C compiler switches etc.">. You can force an embedded perl
556to use direct manipulation by setting C<PL_use_safe_putenv = 0;> after
557the C<perl_construct()> call.
575e1338 558
ce80d64e
AD
559=head2 Installation Directories
560
561The installation directories can all be changed by answering the
be8498a1
RGS
562appropriate questions in Configure. For convenience, all the installation
563questions are near the beginning of Configure. Do not include trailing
564slashes on directory names. At any point during the Configure process,
565you can answer a question with &-d and Configure will use the defaults
566from then on. Alternatively, you can
ce80d64e
AD
567
568 grep '^install' config.sh
569
570after Configure has run to verify the installation paths.
571
572The defaults are intended to be reasonable and sensible for most
573people building from sources. Those who build and distribute binary
574distributions or who export perl to a range of systems will probably
575need to alter them. If you are content to just accept the defaults,
576you can safely skip the next section.
577
578The directories set up by Configure fall into three broad categories.
579
580=over 4
581
582=item Directories for the perl distribution
583
1e2ea6fa 584By default, Configure will use the following directories for 5.25.2.
ce80d64e 585$version is the full perl version number, including subversion, e.g.
8891dd8d 5865.12.3, and $archname is a string like sun4-sunos,
ce80d64e
AD
587determined by Configure. The full definitions of all Configure
588variables are in the file Porting/Glossary.
589
590 Configure variable Default value
591 $prefixexp /usr/local
592 $binexp $prefixexp/bin
593 $scriptdirexp $prefixexp/bin
594 $privlibexp $prefixexp/lib/perl5/$version
595 $archlibexp $prefixexp/lib/perl5/$version/$archname
596 $man1direxp $prefixexp/man/man1
597 $man3direxp $prefixexp/man/man3
598 $html1direxp (none)
599 $html3direxp (none)
600
ab97e755
MB
601$prefixexp is generated from $prefix, with ~ expansion done to convert
602home directories into absolute paths. Similarly for the other variables
603listed. As file system calls do not do this, you should always reference
604the ...exp variables, to support users who build perl in their home
605directory.
ce80d64e
AD
606
607Actually, Configure recognizes the SVR3-style
608/usr/local/man/l_man/man1 directories, if present, and uses those
609instead. Also, if $prefix contains the string "perl", the library
610directories are simplified as described below. For simplicity, only
611the common style is shown here.
612
613=item Directories for site-specific add-on files
614
615After perl is installed, you may later wish to add modules (e.g. from
616CPAN) or scripts. Configure will set up the following directories to
617be used for installing those add-on modules and scripts.
618
979b4168
KW
619 Configure Default
620 variable value
621 $siteprefixexp $prefixexp
622 $sitebinexp $siteprefixexp/bin
623 $sitescriptexp $siteprefixexp/bin
624 $sitelibexp $siteprefixexp/lib/perl5/site_perl/$version
625 $sitearchexp
626 $siteprefixexp/lib/perl5/site_perl/$version/$archname
627 $siteman1direxp $siteprefixexp/man/man1
628 $siteman3direxp $siteprefixexp/man/man3
629 $sitehtml1direxp (none)
630 $sitehtml3direxp (none)
ce80d64e
AD
631
632By default, ExtUtils::MakeMaker will install architecture-independent
633modules into $sitelib and architecture-dependent modules into $sitearch.
634
635=item Directories for vendor-supplied add-on files
636
637Lastly, if you are building a binary distribution of perl for
638distribution, Configure can optionally set up the following directories
639for you to use to distribute add-on modules.
640
979b4168
KW
641 Configure Default
642 variable value
643 $vendorprefixexp (none)
644
645 (The next ones are set only if vendorprefix is set.)
646
647 $vendorbinexp $vendorprefixexp/bin
648 $vendorscriptexp $vendorprefixexp/bin
649 $vendorlibexp $vendorprefixexp/lib/perl5/vendor_perl/$version
650 $vendorarchexp
651 $vendorprefixexp/lib/perl5/vendor_perl/$version/$archname
652 $vendorman1direxp $vendorprefixexp/man/man1
653 $vendorman3direxp $vendorprefixexp/man/man3
654 $vendorhtml1direxp (none)
655 $vendorhtml3direxp (none)
ce80d64e
AD
656
657These are normally empty, but may be set as needed. For example,
658a vendor might choose the following settings:
659
979b4168
KW
660 $prefix /usr
661 $siteprefix /usr/local
662 $vendorprefix /usr
ce80d64e
AD
663
664This would have the effect of setting the following:
665
979b4168
KW
666 $binexp /usr/bin
667 $scriptdirexp /usr/bin
668 $privlibexp /usr/lib/perl5/$version
669 $archlibexp /usr/lib/perl5/$version/$archname
670 $man1direxp /usr/man/man1
671 $man3direxp /usr/man/man3
672
673 $sitebinexp /usr/local/bin
674 $sitescriptexp /usr/local/bin
675 $sitelibexp /usr/local/lib/perl5/site_perl/$version
676 $sitearchexp /usr/local/lib/perl5/site_perl/$version/$archname
677 $siteman1direxp /usr/local/man/man1
678 $siteman3direxp /usr/local/man/man3
679
680 $vendorbinexp /usr/bin
681 $vendorscriptexp /usr/bin
682 $vendorlibexp /usr/lib/perl5/vendor_perl/$version
683 $vendorarchexp /usr/lib/perl5/vendor_perl/$version/$archname
684 $vendorman1direxp /usr/man/man1
685 $vendorman3direxp /usr/man/man3
ce80d64e
AD
686
687Note how in this example, the vendor-supplied directories are in the
668cbedd 688/usr hierarchy, while the directories reserved for the end user are in
ce80d64e
AD
689the /usr/local hierarchy.
690
691The entire installed library hierarchy is installed in locations with
692version numbers, keeping the installations of different versions distinct.
ab97e755
MB
693However, later installations of Perl can still be configured to search
694the installed libraries corresponding to compatible earlier versions.
695See L<"Coexistence with earlier versions of perl 5"> below for more
696details on how Perl can be made to search older version directories.
ce80d64e
AD
697
698Of course you may use these directories however you see fit. For
699example, you may wish to use $siteprefix for site-specific files that
700are stored locally on your own disk and use $vendorprefix for
701site-specific files that are stored elsewhere on your organization's
702network. One way to do that would be something like
703
979b4168 704 sh Configure -Dsiteprefix=/usr/local -Dvendorprefix=/usr/share/perl
ce80d64e
AD
705
706=item otherlibdirs
707
708As a final catch-all, Configure also offers an $otherlibdirs
709variable. This variable contains a colon-separated list of additional
710directories to add to @INC. By default, it will be empty.
711Perl will search these directories (including architecture and
712version-specific subdirectories) for add-on modules and extensions.
713
714For example, if you have a bundle of perl libraries from a previous
715installation, perhaps in a strange place:
716
717 Configure -Dotherlibdirs=/usr/lib/perl5/site_perl/5.8.1
718
719=item APPLLIB_EXP
720
721There is one other way of adding paths to @INC at perl build time, and
722that is by setting the APPLLIB_EXP C pre-processor token to a colon-
723separated list of directories, like this
724
725 sh Configure -Accflags='-DAPPLLIB_EXP=\"/usr/libperl\"'
726
727The directories defined by APPLLIB_EXP get added to @INC I<first>,
728ahead of any others, and so provide a way to override the standard perl
729modules should you, for example, want to distribute fixes without
730touching the perl distribution proper. And, like otherlib dirs,
731version and architecture specific subdirectories are also searched, if
732present, at run time. Of course, you can still search other @INC
733directories ahead of those in APPLLIB_EXP by using any of the standard
734run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc.
735
785aa5e3 736=item usesitecustomize
20ef40cf
GA
737
738Run-time customization of @INC can be enabled with:
739
36de116d 740 sh Configure -Dusesitecustomize
20ef40cf 741
785aa5e3
RGS
742which will define USE_SITECUSTOMIZE and $Config{usesitecustomize}.
743When enabled, this makes perl run F<$sitelibexp/sitecustomize.pl> before
20ef40cf
GA
744anything else. This script can then be set up to add additional
745entries to @INC.
746
ce80d64e
AD
747=item Man Pages
748
be8498a1
RGS
749By default, man pages will be installed in $man1dir and $man3dir, which
750are normally /usr/local/man/man1 and /usr/local/man/man3. If you
751want to use a .3pm suffix for perl man pages, you can do that with
ce80d64e
AD
752
753 sh Configure -Dman3ext=3pm
754
ce80d64e
AD
755=item HTML pages
756
757Currently, the standard perl installation does not do anything with
758HTML documentation, but that may change in the future. Further, some
759add-on modules may wish to install HTML documents. The html Configure
760variables listed above are provided if you wish to specify where such
761documents should be placed. The default is "none", but will likely
762eventually change to something useful based on user feedback.
763
764=back
765
766Some users prefer to append a "/share" to $privlib and $sitelib
767to emphasize that those directories can be shared among different
768architectures.
769
770Note that these are just the defaults. You can actually structure the
771directories any way you like. They don't even have to be on the same
772filesystem.
c3edaffb 773
ce80d64e
AD
774Further details about the installation directories, maintenance and
775development subversions, and about supporting multiple versions are
7df75831 776discussed in L<"Coexistence with earlier versions of perl 5"> below.
10c7e831 777
ce80d64e
AD
778If you specify a prefix that contains the string "perl", then the
779library directory structure is slightly simplified. Instead of
780suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib.
2bf2710f 781
ce80d64e
AD
782Thus, for example, if you Configure with
783-Dprefix=/opt/perl, then the default library directories for 5.9.0 are
2bf2710f 784
ce80d64e
AD
785 Configure variable Default value
786 $privlib /opt/perl/lib/5.9.0
787 $archlib /opt/perl/lib/5.9.0/$archname
788 $sitelib /opt/perl/lib/site_perl/5.9.0
789 $sitearch /opt/perl/lib/site_perl/5.9.0/$archname
2bf2710f 790
ce80d64e 791=head2 Changing the installation directory
c3edaffb 792
ce80d64e 793Configure distinguishes between the directory in which perl (and its
7df75831 794associated files) should be installed, and the directory in which it
ce80d64e
AD
795will eventually reside. For most sites, these two are the same; for
796sites that use AFS, this distinction is handled automatically.
7df75831
RGS
797However, sites that use package management software such as rpm or
798dpkg, or users building binary packages for distribution may also
799wish to install perl into a different directory before moving perl
800to its final destination. There are two ways to do that:
801
802=over 4
803
804=item installprefix
c3edaffb 805
be8498a1
RGS
806To install perl under the /tmp/perl5 directory, use the following
807command line:
c3edaffb 808
7df75831 809 sh Configure -Dinstallprefix=/tmp/perl5
c3edaffb 810
ce80d64e 811(replace /tmp/perl5 by a directory of your choice).
2bf2710f 812
ce80d64e
AD
813Beware, though, that if you go to try to install new add-on
814modules, they too will get installed in under '/tmp/perl5' if you
7df75831
RGS
815follow this example. That's why it's usually better to use DESTDIR,
816as shown in the next section.
c3edaffb 817
7df75831 818=item DESTDIR
9d67150a 819
ce80d64e
AD
820If you need to install perl on many identical systems, it is convenient
821to compile it once and create an archive that can be installed on
822multiple systems. Suppose, for example, that you want to create an
823archive that can be installed in /opt/perl. One way to do that is by
824using the DESTDIR variable during C<make install>. The DESTDIR is
825automatically prepended to all the installation paths. Thus you
826simply do:
830717a7 827
ce80d64e
AD
828 sh Configure -Dprefix=/opt/perl -des
829 make
830 make test
831 make install DESTDIR=/tmp/perl5
832 cd /tmp/perl5/opt/perl
833 tar cvf /tmp/perl5-archive.tar .
9d67150a 834
7df75831
RGS
835=back
836
32878f30
NP
837=head2 Relocatable @INC
838
839To create a relocatable perl tree, use the following command line:
840
841 sh Configure -Duserelocatableinc
842
843Then the paths in @INC (and everything else in %Config) can be
844optionally located via the path of the perl executable.
845
846That means that, if the string ".../" is found at the start of any
847path, it's substituted with the directory of $^X. So, the relocation
848can be configured on a per-directory basis, although the default with
849"-Duserelocatableinc" is that everything is relocated. The initial
850install is done to the original configured prefix.
851
79f7885c
RGS
852This option is not compatible with the building of a shared libperl
853("-Duseshrplib"), because in that case perl is linked with an hard-coded
854rpath that points at the libperl.so, that cannot be relocated.
855
ce80d64e 856=head2 Site-wide Policy settings
55479bb6 857
ce80d64e 858After Configure runs, it stores a number of common site-wide "policy"
7df75831
RGS
859answers (such as installation directories) in the Policy.sh file.
860If you want to build perl on another system using the same policy
861defaults, simply copy the Policy.sh file to the new system's perl build
862directory, and Configure will use it. This will work even if Policy.sh was
a0a8d9d3 863generated for another version of Perl, or on a system with a
da1b4322 864different architecture and/or operating system. However, in such cases,
a0a8d9d3
DD
865you should review the contents of the file before using it: for
866example, your new target may not keep its man pages in the same place
867as the system on which the file was generated.
55479bb6 868
ce80d64e
AD
869Alternatively, if you wish to change some or all of those policy
870answers, you should
c3edaffb 871
ce80d64e 872 rm -f Policy.sh
aa689395 873
ce80d64e 874to ensure that Configure doesn't re-use them.
2ae324a7 875
ce80d64e 876Further information is in the Policy_sh.SH file itself.
aa689395 877
ce80d64e
AD
878If the generated Policy.sh file is unsuitable, you may freely edit it
879to contain any valid shell commands. It will be run just after the
880platform-specific hints files.
aa689395 881
ce80d64e 882=head2 Disabling older versions of Perl
aa689395 883
ce80d64e 884Configure will search for binary compatible versions of previously
7df75831
RGS
885installed perl binaries in the tree that is specified as target tree,
886and these will be used as locations to search for modules by the perl
887being built. The list of perl versions found will be put in the Configure
888variable inc_version_list.
86058a2d 889
ab97e755
MB
890To disable this use of older perl modules, even completely valid pure
891perl modules, you can specify to not include the paths found:
b2a6d19e 892
ce80d64e 893 sh Configure -Dinc_version_list=none ...
d6baa268 894
ab97e755
MB
895If you do want to use modules from some previous perl versions, the
896variable must contain a space separated list of directories under the
897site_perl directory, and has to include architecture-dependent
898directories separately, eg.
274ca399 899
4683a5d7 900 sh Configure -Dinc_version_list="5.16.0/x86_64-linux 5.16.0" ...
274ca399 901
ce80d64e 902When using the newer perl, you can add these paths again in the
668cbedd 903PERL5LIB environment variable or with perl's -I runtime option.
86058a2d 904
ce80d64e 905=head2 Building Perl outside of the source directory
86058a2d 906
ce80d64e
AD
907Sometimes it is desirable to build Perl in a directory different from
908where the sources are, for example if you want to keep your sources
909read-only, or if you want to share the sources between different binary
910architectures. You can do this (if your file system supports symbolic
911links) by
06c896bb 912
ce80d64e
AD
913 mkdir /tmp/perl/build/directory
914 cd /tmp/perl/build/directory
915 sh /path/to/perl/source/Configure -Dmksymlinks ...
06c896bb 916
ce80d64e
AD
917This will create in /tmp/perl/build/directory a tree of symbolic links
918pointing to files in /path/to/perl/source. The original files are left
919unaffected. After Configure has finished you can just say
06c896bb 920
ce80d64e 921 make
7df75831
RGS
922 make test
923 make install
06c896bb 924
ce80d64e 925as usual, and Perl will be built in /tmp/perl/build/directory.
aa689395 926
3bf462b8
CS
927=head2 Building a debugging perl
928
929You can run perl scripts under the perl debugger at any time with
3fe9a6f1 930B<perl -d your_script>. If, however, you want to debug perl itself,
eaf812ae
MB
931you probably want to have support for perl internal debugging code
932(activated by adding -DDEBUGGING to ccflags), and/or support for the
7df75831
RGS
933system debugger by adding -g to the optimisation flags. For that,
934use the parameter:
eaf812ae 935
08854360
RGS
936 sh Configure -DDEBUGGING
937
938or
939
eaf812ae
MB
940 sh Configure -DDEBUGGING=<mode>
941
942For a more eye appealing call, -DEBUGGING is defined to be an alias
943for -DDEBUGGING. For both, the -U calls are also supported, in order
944to be able to overrule the hints or Policy.sh settings.
945
7df75831 946Here are the DEBUGGING modes:
3bf462b8 947
7df75831 948=over 4
3bf462b8 949
eaf812ae
MB
950=item -DDEBUGGING
951
952=item -DEBUGGING
953
954=item -DEBUGGING=both
955
7df75831
RGS
956Sets both -DDEBUGGING in the ccflags, and adds -g to optimize.
957
958You can actually specify -g and -DDEBUGGING independently (see below),
959but usually it's convenient to have both.
eaf812ae
MB
960
961=item -DEBUGGING=-g
962
7df75831
RGS
963=item -Doptimize=-g
964
eaf812ae
MB
965Adds -g to optimize, but does not set -DDEBUGGING.
966
7df75831
RGS
967(Note: Your system may actually require something like cc -g2.
968Check your man pages for cc(1) and also any hint file for your system.)
969
eaf812ae
MB
970=item -DEBUGGING=none
971
7df75831
RGS
972=item -UDEBUGGING
973
eaf812ae
MB
974Removes -g from optimize, and -DDEBUGGING from ccflags.
975
976=back
977
3bf462b8 978If you are using a shared libperl, see the warnings about multiple
a522f097 979versions of perl under L<Building a shared Perl library>.
3bf462b8 980
def5f8a5
DM
981Note that a perl built with -DDEBUGGING will be much bigger and will run
982much, much more slowly than a standard perl.
1db12997
DM
983
984=head2 DTrace support
985
979b4168 986On platforms where DTrace is available, it may be enabled by
ab97e755
MB
987using the -Dusedtrace option to Configure. DTrace probes are available
988for subroutine entry (sub-entry) and subroutine exit (sub-exit). Here's a
1db12997
DM
989simple D script that uses them:
990
991 perl$target:::sub-entry, perl$target:::sub-return {
992 printf("%s %s (%s:%d)\n", probename == "sub-entry" ? "->" : "<-",
993 copyinstr(arg0), copyinstr(arg1), arg2);
994 }
995
996
8d74ce1c
AD
997=head2 Extensions
998
80c1f5de
AD
999Perl ships with a number of standard extensions. These are contained
1000in the ext/ subdirectory.
1001
8d74ce1c
AD
1002By default, Configure will offer to build every extension which appears
1003to be supported. For example, Configure will offer to build GDBM_File
7df75831 1004only if it is able to find the gdbm library.
ce80d64e
AD
1005
1006To disable certain extensions so that they are not built, use the
1007-Dnoextensions=... and -Donlyextensions=... options. They both accept
47bd56ab
DM
1008a space-separated list of extensions, such as C<IPC/SysV>. The extensions
1009listed in
ce80d64e
AD
1010C<noextensions> are removed from the list of extensions to build, while
1011the C<onlyextensions> is rather more severe and builds only the listed
1012extensions. The latter should be used with extreme caution since
1013certain extensions are used by many other extensions and modules:
1014examples of such modules include Fcntl and IO. The order of processing
1015these options is first C<only> (if present), then C<no> (if present).
8d74ce1c
AD
1016
1017Of course, you may always run Configure interactively and select only
1018the extensions you want.
1019
7df75831
RGS
1020If you unpack any additional extensions in the ext/ directory before
1021running Configure, then Configure will offer to build those additional
1022extensions as well. Most users probably shouldn't have to do this --
1023it is usually easier to build additional extensions later after perl
1024has been installed. However, if you wish to have those additional
1025extensions statically linked into the perl binary, then this offers a
1026convenient way to do that in one step. (It is not necessary, however;
1027you can build and install extensions just fine even if you don't have
1028dynamic loading. See lib/ExtUtils/MakeMaker.pm for more details.)
1029Another way of specifying extra modules is described in
1030L<"Adding extra modules to the build"> below.
8d74ce1c 1031
dd3196cd 1032If you re-use an old config.sh but change your system (e.g. by
8d74ce1c
AD
1033adding libgdbm) Configure will still offer your old choices of extensions
1034for the default answer, but it will also point out the discrepancy to
1035you.
1036
8d74ce1c
AD
1037=head2 Including locally-installed libraries
1038
7df75831
RGS
1039Perl comes with interfaces to number of libraries, including threads,
1040dbm, ndbm, gdbm, and Berkeley db. For the *db* extension, if
8d74ce1c 1041Configure can find the appropriate header files and libraries, it will
7df75831 1042automatically include that extension. The threading extension needs
27021420 1043to be specified explicitly (see L</Threads>).
7df75831
RGS
1044
1045Those libraries are not distributed with perl. If your header (.h) files
1046for those libraries are not in a directory normally searched by your C
1047compiler, then you will need to include the appropriate -I/your/directory
1048option when prompted by Configure. If your libraries are not in a
1049directory normally searched by your C compiler and linker, then you will
1050need to include the appropriate -L/your/directory option when prompted
1051by Configure. See the examples below.
8d74ce1c 1052
ce80d64e 1053=head3 Examples
8d74ce1c
AD
1054
1055=over 4
1056
1057=item gdbm in /usr/local
1058
1059Suppose you have gdbm and want Configure to find it and build the
d6baa268 1060GDBM_File extension. This example assumes you have gdbm.h
8d74ce1c
AD
1061installed in /usr/local/include/gdbm.h and libgdbm.a installed in
1062/usr/local/lib/libgdbm.a. Configure should figure all the
1063necessary steps out automatically.
1064
1065Specifically, when Configure prompts you for flags for
7df75831
RGS
1066your C compiler, you should include -I/usr/local/include, if it's
1067not here yet. Similarly, when Configure prompts you for linker flags,
1068you should include -L/usr/local/lib.
8d74ce1c
AD
1069
1070If you are using dynamic loading, then when Configure prompts you for
1071linker flags for dynamic loading, you should again include
1072-L/usr/local/lib.
1073
d6baa268
JH
1074Again, this should all happen automatically. This should also work if
1075you have gdbm installed in any of (/usr/local, /opt/local, /usr/gnu,
1076/opt/gnu, /usr/GNU, or /opt/GNU).
8d74ce1c 1077
e8b9ce60
AD
1078=item BerkeleyDB in /usr/local/BerkeleyDB
1079
668cbedd 1080The version of BerkeleyDB distributed by Oracle installs in a
e8b9ce60
AD
1081version-specific directory by default, typically something like
1082/usr/local/BerkeleyDB.4.7. To have Configure find that, you need to add
ab97e755
MB
1083-I/usr/local/BerkeleyDB.4.7/include to cc flags, as in the previous
1084example, and you will also have to take extra steps to help Configure
1085find -ldb. Specifically, when Configure prompts you for library
1086directories, add /usr/local/BerkeleyDB.4.7/lib to the list. Also, you
1087will need to add appropriate linker flags to tell the runtime linker
1088where to find the BerkeleyDB shared libraries.
e8b9ce60
AD
1089
1090It is possible to specify this from the command line (all on one
8d74ce1c
AD
1091line):
1092
979b4168
KW
1093 sh Configure -de \
1094 -Dlocincpth='/usr/local/BerkeleyDB.4.7/include \
1095 /usr/local/include' \
1096 -Dloclibpth='/usr/local/BerkeleyDB.4.7/lib /usr/local/lib' \
1097 -Aldflags='-R/usr/local/BerkeleyDB.4.7/lib'
8d74ce1c
AD
1098
1099locincpth is a space-separated list of include directories to search.
1100Configure will automatically add the appropriate -I directives.
1101
1102loclibpth is a space-separated list of library directories to search.
e8b9ce60 1103Configure will automatically add the appropriate -L directives.
8d74ce1c 1104
e8b9ce60
AD
1105The addition to ldflags is so that the dynamic linker knows where to find
1106the BerkeleyDB libraries. For Linux and Solaris, the -R option does that.
1107Other systems may use different flags. Use the appropriate flag for your
1108system.
8d74ce1c
AD
1109
1110=back
1111
b76ca5cc
BF
1112=head2 Specifying a logical root directory
1113
1114If you are cross-compiling, or are using a compiler which has it's own
1115headers and libraries in a nonstandard location, and your compiler
ab97e755
MB
1116understands the C<--sysroot> option, you can use the C<-Dsysroot> option
1117to specify the logical root directory under which all libraries and
1118headers are searched for. This patch adjusts Configure to search under
1119$sysroot, instead of /.
1120
b76ca5cc
BF
1121--sysroot is added to ccflags and friends so that make in
1122ExtUtils::MakeMaker, and other extensions, will use it.
1123
ce80d64e
AD
1124=head2 Overriding an old config.sh
1125
dd3196cd
RGS
1126If you want to use an old config.sh produced by a previous run of
1127Configure, but override some of the items with command line options, you
1128need to use B<Configure -O>.
ce80d64e
AD
1129
1130=head2 GNU-style configure
1131
1132If you prefer the GNU-style configure command line interface, you can
1133use the supplied configure.gnu command, e.g.
1134
1135 CC=gcc ./configure.gnu
1136
1137The configure.gnu script emulates a few of the more common configure
1138options. Try
1139
1140 ./configure.gnu --help
1141
1142for a listing.
1143
1144(The file is called configure.gnu to avoid problems on systems
1145that would not distinguish the files "Configure" and "configure".)
1146
ce80d64e
AD
1147=head2 Malloc Issues
1148
1149Perl relies heavily on malloc(3) to grow data structures as needed,
1150so perl's performance can be noticeably affected by the performance of
1151the malloc function on your system. The perl source is shipped with a
1152version of malloc that has been optimized for the typical requests from
1153perl, so there's a chance that it may be both faster and use less memory
1154than your system malloc.
1155
1156However, if your system already has an excellent malloc, or if you are
1157experiencing difficulties with extensions that use third-party libraries
1158that call malloc, then you should probably use your system's malloc.
1159(Or, you might wish to explore the malloc flags discussed below.)
1160
1161=over 4
1162
1163=item Using the system malloc
1164
1165To build without perl's malloc, you can use the Configure command
1166
1167 sh Configure -Uusemymalloc
1168
1169or you can answer 'n' at the appropriate interactive Configure prompt.
1170
73d6d1b0
RGS
1171Note that Perl's malloc isn't always used by default; that actually
1172depends on your system. For example, on Linux and FreeBSD (and many more
1173systems), Configure chooses to use the system's malloc by default.
1174See the appropriate file in the F<hints/> directory to see how the
1175default is set.
1176
ce80d64e
AD
1177=item -DPERL_POLLUTE_MALLOC
1178
1179NOTE: This flag is enabled automatically on some platforms if you just
7df75831 1180run Configure to accept all the defaults.
ce80d64e
AD
1181
1182Perl's malloc family of functions are normally called Perl_malloc(),
1183Perl_realloc(), Perl_calloc() and Perl_mfree().
1184These names do not clash with the system versions of these functions.
1185
1186If this flag is enabled, however, Perl's malloc family of functions
1187will have the same names as the system versions. This may be required
1188sometimes if you have libraries that like to free() data that may have
1189been allocated by Perl_malloc() and vice versa.
1190
1191Note that enabling this option may sometimes lead to duplicate symbols
1192from the linker for malloc et al. In such cases, the system probably
1193does not allow its malloc functions to be fully replaced with custom
1194versions.
1195
1196=item -DPERL_DEBUGGING_MSTATS
1197
1198This flag enables debugging mstats, which is required to use the
1199Devel::Peek::mstat() function. You cannot enable this unless you are
1200using Perl's malloc, so a typical Configure command would be
1201
7df75831 1202 sh Configure -Accflags=-DPERL_DEBUGGING_MSTATS -Dusemymalloc
ce80d64e
AD
1203
1204to enable this option.
1205
1206=back
1207
8e07c86e
AD
1208=head2 What if it doesn't work?
1209
8d74ce1c 1210If you run into problems, try some of the following ideas.
ff52061e 1211If none of them help, then see L<"Reporting Problems"> below.
8d74ce1c 1212
8e07c86e
AD
1213=over 4
1214
25f94b33
AD
1215=item Running Configure Interactively
1216
1217If Configure runs into trouble, remember that you can always run
1218Configure interactively so that you can check (and correct) its
1219guesses.
1220
1221All the installation questions have been moved to the top, so you don't
aa689395 1222have to wait for them. Once you've handled them (and your C compiler and
1ec51d55 1223flags) you can type &-d at the next Configure prompt and Configure
25f94b33
AD
1224will use the defaults from then on.
1225
1226If you find yourself trying obscure command line incantations and
1227config.over tricks, I recommend you run Configure interactively
1228instead. You'll probably save yourself time in the long run.
1229
aa689395 1230=item Hint files
8e07c86e 1231
a0a8d9d3
DD
1232Hint files tell Configure about a number of things:
1233
1234=over 4
1235
1236=item o
1237
1238The peculiarities or conventions of particular platforms -- non-standard
1239library locations and names, default installation locations for binaries,
1240and so on.
1241
1242=item o
1243
1244The deficiencies of the platform -- for example, library functions that,
1245although present, are too badly broken to be usable; or limits on
1246resources that are generously available on most platforms.
1247
1248=item o
1249
ab97e755
MB
1250How best to optimize for the platform, both in terms of binary size
1251and/or speed, and for Perl feature support. Because of wide variations in
1252the implementation of shared libraries and of threading, for example,
1253Configure often needs hints in order to be able to use these features.
a0a8d9d3
DD
1254
1255=back
1256
1257The perl distribution includes many system-specific hints files
1258in the hints/ directory. If one of them matches your system, Configure
1259will offer to use that hint file. Unless you have a very good reason
1260not to, you should accept its offer.
8e07c86e
AD
1261
1262Several of the hint files contain additional important information.
ab97e755
MB
1263If you have any problems, it is a good idea to read the relevant hint
1264file for further information. See hints/solaris_2.sh for an extensive
1265example. More information about writing good hints is in the
1266hints/README.hints file, which also explains hint files known as
1267callback-units.
a0a8d9d3
DD
1268
1269Note that any hint file is read before any Policy file, meaning that
1270Policy overrides hints -- see L</Site-wide Policy settings>.
8e07c86e 1271
73d6d1b0 1272=item WHOA THERE!!!
edb1cbcb 1273
ab97e755
MB
1274If you are re-using an old config.sh, it's possible that Configure
1275detects different values from the ones specified in this file. You will
1276almost always want to keep the previous value, unless you have changed
1277something on your system.
edb1cbcb 1278
1279For example, suppose you have added libgdbm.a to your system
1280and you decide to reconfigure perl to use GDBM_File. When you run
1281Configure again, you will need to add -lgdbm to the list of libraries.
bfb7748a
AD
1282Now, Configure will find your gdbm include file and library and will
1283issue a message:
edb1cbcb 1284
1285 *** WHOA THERE!!! ***
1286 The previous value for $i_gdbm on this machine was "undef"!
1287 Keep the previous value? [y]
1288
1ec51d55 1289In this case, you do not want to keep the previous value, so you
c3edaffb 1290should answer 'n'. (You'll also have to manually add GDBM_File to
edb1cbcb 1291the list of dynamic extensions to build.)
1292
8e07c86e
AD
1293=item Changing Compilers
1294
1295If you change compilers or make other significant changes, you should
1ec51d55 1296probably not re-use your old config.sh. Simply remove it or
dd3196cd 1297rename it, then rerun Configure with the options you want to use.
8e07c86e 1298
c3edaffb 1299=item Propagating your changes to config.sh
8e07c86e 1300
1ec51d55
CS
1301If you make any changes to config.sh, you should propagate
1302them to all the .SH files by running
1303
1304 sh Configure -S
1305
1306You will then have to rebuild by running
9d67150a 1307
1308 make depend
1309 make
8e07c86e 1310
48370efc
JH
1311=item config.over and config.arch
1312
668cbedd 1313You can also supply a shell script config.over to override
48370efc
JH
1314Configure's guesses. It will get loaded up at the very end, just
1315before config.sh is created. You have to be careful with this,
1316however, as Configure does no checking that your changes make sense.
1317This file is usually good for site-specific customizations.
1318
1319There is also another file that, if it exists, is loaded before the
1320config.over, called config.arch. This file is intended to be per
1321architecture, not per site, and usually it's the architecture-specific
1322hints file that creates the config.arch.
8e07c86e
AD
1323
1324=item config.h
1325
1ec51d55
CS
1326Many of the system dependencies are contained in config.h.
1327Configure builds config.h by running the config_h.SH script.
1328The values for the variables are taken from config.sh.
8e07c86e 1329
1ec51d55
CS
1330If there are any problems, you can edit config.h directly. Beware,
1331though, that the next time you run Configure, your changes will be
8e07c86e
AD
1332lost.
1333
1334=item cflags
1335
1336If you have any additional changes to make to the C compiler command
1ec51d55 1337line, they can be made in cflags.SH. For instance, to turn off the
5729ffdd
NC
1338optimizer on toke.c, find the switch structure marked 'or customize here',
1339and add a line for toke.c ahead of the catch-all *) so that it now reads:
1340
1341 : or customize here
1342
1343 case "$file" in
1344 toke) optimize='-g' ;;
1345 *) ;;
1346
ab97e755
MB
1347You should not edit the generated file cflags directly, as your changes
1348will be lost the next time you run Configure, or if you edit config.sh.
8e07c86e 1349
f5b3b617
AD
1350To explore various ways of changing ccflags from within a hint file,
1351see the file hints/README.hints.
1352
1353To change the C flags for all the files, edit config.sh and change either
1354$ccflags or $optimize, and then re-run
1ec51d55
CS
1355
1356 sh Configure -S
1357 make depend
8e07c86e 1358
aa689395 1359=item No sh
8e07c86e 1360
c42e3e15
GS
1361If you don't have sh, you'll have to copy the sample file
1362Porting/config.sh to config.sh and edit your config.sh to reflect your
1363system's peculiarities. See Porting/pumpkin.pod for more information.
8e07c86e
AD
1364You'll probably also have to extensively modify the extension building
1365mechanism.
1366
c3edaffb 1367=item Porting information
1368
e6f03d26 1369Specific information for the OS/2, Plan 9, VMS and Win32 ports is in the
1ec51d55
CS
1370corresponding README files and subdirectories. Additional information,
1371including a glossary of all those config.sh variables, is in the Porting
ce80d64e 1372subdirectory. Porting/Glossary should especially come in handy.
c3edaffb 1373
7f678428 1374Ports for other systems may also be available. You should check out
468f45d5 1375http://www.cpan.org/ports for current information on ports to
7f678428 1376various other operating systems.
1377
ce80d64e 1378If you plan to port Perl to a new architecture, study carefully the
491517e0 1379section titled "Philosophical Issues in Patching and Porting Perl"
c222ef46 1380in the file Porting/pumpkin.pod and the file pod/perlgit.pod.
491517e0
JA
1381Study also how other non-UNIX ports have solved problems.
1382
8e07c86e
AD
1383=back
1384
ce80d64e 1385=head2 Adding extra modules to the build
fadf0ef5
JH
1386
1387You can specify extra modules or module bundles to be fetched from the
1388CPAN and installed as part of the Perl build. Either use the -Dextras=...
1389command line parameter to Configure, for example like this:
1390
d3df0cfd 1391 Configure -Dextras="Bundle::LWP DBI"
fadf0ef5
JH
1392
1393or answer first 'y' to the question 'Install any extra modules?' and
d3df0cfd 1394then answer "Bundle::LWP DBI" to the 'Extras?' question.
ab97e755
MB
1395The module or the bundle names are as for the CPAN module 'install'
1396command. This will only work if those modules are to be built as dynamic
a522f097
AD
1397extensions. If you wish to include those extra modules as static
1398extensions, see L<"Extensions"> above.
fadf0ef5
JH
1399
1400Notice that because the CPAN module will be used to fetch the extra
1401modules, you will need access to the CPAN, either via the Internet,
1402or via a local copy such as a CD-ROM or a local CPAN mirror. If you
1403do not, using the extra modules option will die horribly.
1404
1405Also notice that you yourself are responsible for satisfying any extra
ab97e755
MB
1406dependencies such as external headers or libraries BEFORE trying the
1407build. For example: you will need to have the Foo database specific
fadf0ef5
JH
1408headers and libraries installed for the DBD::Foo module. The Configure
1409process or the Perl build process will not help you with these.
1410
ce80d64e 1411=head2 suidperl
03739d21 1412
172dd959
JV
1413suidperl was an optional component of earlier releases of perl. It is no
1414longer available. Instead, use a tool specifically designed to handle
1415changes in privileges, such as B<sudo>.
03739d21 1416
8e07c86e
AD
1417=head1 make depend
1418
bfb7748a
AD
1419This will look for all the includes. The output is stored in makefile.
1420The only difference between Makefile and makefile is the dependencies at
1421the bottom of makefile. If you have to make any changes, you should edit
ce80d64e 1422makefile, not Makefile, since the Unix make command reads makefile first.
bfb7748a
AD
1423(On non-Unix systems, the output may be stored in a different file.
1424Check the value of $firstmakefile in your config.sh if in doubt.)
8e07c86e
AD
1425
1426Configure will offer to do this step for you, so it isn't listed
1427explicitly above.
1428
1429=head1 make
1430
1431This will attempt to make perl in the current directory.
1432
8d410bc4
YST
1433=head2 Expected errors
1434
f5b5f377 1435These error reports are normal, and can be ignored:
8d410bc4
YST
1436
1437 ...
1438 make: [extra.pods] Error 1 (ignored)
1439 ...
1440 make: [extras.make] Error 1 (ignored)
1441
8d74ce1c
AD
1442=head2 What if it doesn't work?
1443
8e07c86e 1444If you can't compile successfully, try some of the following ideas.
7f678428 1445If none of them help, and careful reading of the error message and
8d74ce1c 1446the relevant manual pages on your system doesn't help,
ff52061e 1447then see L<"Reporting Problems"> below.
8e07c86e
AD
1448
1449=over 4
1450
1ec51d55 1451=item hints
8e07c86e
AD
1452
1453If you used a hint file, try reading the comments in the hint file
1454for further tips and information.
1455
1ec51d55 1456=item extensions
8e07c86e 1457
1ec51d55 1458If you can successfully build miniperl, but the process crashes
ce80d64e 1459during the building of extensions, run
c3edaffb 1460
3a6175e1 1461 make minitest
c3edaffb 1462
1463to test your version of miniperl.
1464
e57fd563 1465=item locale
1466
bfb7748a
AD
1467If you have any locale-related environment variables set, try unsetting
1468them. I have some reports that some versions of IRIX hang while
1469running B<./miniperl configpm> with locales other than the C locale.
1470See the discussion under L<"make test"> below about locales and the
ab97e755
MB
1471whole L<perllocale/"LOCALE PROBLEMS"> section in the file
1472pod/perllocale.pod. The latter is especially useful if you see something
1473like this
3e6e419a
JH
1474
1475 perl: warning: Setting locale failed.
1476 perl: warning: Please check that your locale settings:
1477 LC_ALL = "En_US",
1478 LANG = (unset)
1479 are supported and installed on your system.
1480 perl: warning: Falling back to the standard locale ("C").
1481
1482at Perl startup.
e57fd563 1483
06aa495b
DM
1484=item other environment variables
1485
1486Configure does not check for environment variables that can sometimes
1487have a major influence on how perl is built or tested. For example,
1488OBJECT_MODE on AIX determines the way the compiler and linker deal with
1489their objects, but this is a variable that only influences build-time
1490behaviour, and should not affect the perl scripts that are eventually
1491executed by the perl binary. Other variables, like PERL_UNICODE,
adbb55c0 1492PERL5LIB, and PERL5OPT will influence the behaviour of the test suite.
06aa495b
DM
1493So if you are getting strange test failures, you may want to try
1494retesting with the various PERL variables unset.
1495
7f678428 1496=item varargs
c3edaffb 1497
1498If you get varargs problems with gcc, be sure that gcc is installed
bfb7748a
AD
1499correctly and that you are not passing -I/usr/include to gcc. When using
1500gcc, you should probably have i_stdarg='define' and i_varargs='undef'
ce80d64e 1501in config.sh. The problem is usually solved by installing gcc
bfb7748a
AD
1502correctly. If you do change config.sh, don't forget to propagate
1503your changes (see L<"Propagating your changes to config.sh"> below).
7f678428 1504See also the L<"vsprintf"> item below.
c3edaffb 1505
bfb7748a 1506=item util.c
c3edaffb 1507
1508If you get error messages such as the following (the exact line
bfb7748a 1509numbers and function name may vary in different versions of perl):
c3edaffb 1510
19f4563d 1511 util.c: In function 'Perl_form':
bfb7748a
AD
1512 util.c:1107: number of arguments doesn't match prototype
1513 proto.h:125: prototype declaration
c3edaffb 1514
1515it might well be a symptom of the gcc "varargs problem". See the
7f678428 1516previous L<"varargs"> item.
c3edaffb 1517
1ec51d55 1518=item LD_LIBRARY_PATH
c3edaffb 1519
1520If you run into dynamic loading problems, check your setting of
aa689395 1521the LD_LIBRARY_PATH environment variable. If you're creating a static
1522Perl library (libperl.a rather than libperl.so) it should build
c3edaffb 1523fine with LD_LIBRARY_PATH unset, though that may depend on details
668cbedd 1524of your local setup.
c3edaffb 1525
aa689395 1526=item nm extraction
c3edaffb 1527
1528If Configure seems to be having trouble finding library functions,
1529try not using nm extraction. You can do this from the command line
1530with
1531
1532 sh Configure -Uusenm
1533
1534or by answering the nm extraction question interactively.
1ec51d55 1535If you have previously run Configure, you should not reuse your old
c3edaffb 1536config.sh.
1537
bfb7748a
AD
1538=item umask not found
1539
1540If the build processes encounters errors relating to umask(), the problem
1541is probably that Configure couldn't find your umask() system call.
1542Check your config.sh. You should have d_umask='define'. If you don't,
1543this is probably the L<"nm extraction"> problem discussed above. Also,
1544try reading the hints file for your system for further information.
1545
7f678428 1546=item vsprintf
c3edaffb 1547
1548If you run into problems with vsprintf in compiling util.c, the
1549problem is probably that Configure failed to detect your system's
1550version of vsprintf(). Check whether your system has vprintf().
1551(Virtually all modern Unix systems do.) Then, check the variable
1552d_vprintf in config.sh. If your system has vprintf, it should be:
1553
1554 d_vprintf='define'
1555
1556If Configure guessed wrong, it is likely that Configure guessed wrong
bfb7748a
AD
1557on a number of other common functions too. This is probably
1558the L<"nm extraction"> problem discussed above.
c3edaffb 1559
3fe9a6f1 1560=item do_aspawn
1561
1562If you run into problems relating to do_aspawn or do_spawn, the
1563problem is probably that Configure failed to detect your system's
bfb7748a
AD
1564fork() function. Follow the procedure in the previous item
1565on L<"nm extraction">.
3fe9a6f1 1566
84902520
TB
1567=item __inet_* errors
1568
1569If you receive unresolved symbol errors during Perl build and/or test
1570referring to __inet_* symbols, check to see whether BIND 8.1 is
1571installed. It installs a /usr/local/include/arpa/inet.h that refers to
1572these symbols. Versions of BIND later than 8.1 do not install inet.h
1573in that location and avoid the errors. You should probably update to a
6d240721 1574newer version of BIND (and remove the files the old one left behind).
ab97e755
MB
1575If you can't, you can either link with the updated resolver library
1576provided with BIND 8.1 or rename /usr/local/bin/arpa/inet.h during the
1577Perl build and test process to avoid the problem.
6d240721 1578
73d6d1b0 1579=item .*_r() prototype NOT found
6d240721
JH
1580
1581On a related note, if you see a bunch of complaints like the above about
ab97e755
MB
1582reentrant functions -- specifically networking-related ones -- being
1583present but without prototypes available, check to see if BIND 8.1 (or
1584possibly other BIND 8 versions) is (or has been) installed. They install
1585header files such as netdb.h into places such as /usr/local/include (or
1586into another directory as specified at build/install time), at least
1587optionally. Remove them or put them in someplace that isn't in the C
1588preprocessor's header file include search path (determined by -I options
1589plus defaults, normally /usr/include).
84902520 1590
d6baa268
JH
1591=item #error "No DATAMODEL_NATIVE specified"
1592
1593This is a common error when trying to build perl on Solaris 2.6 with a
1594gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files
1595changed, so you need to update your gcc installation. You can either
1596rerun the fixincludes script from gcc or take the opportunity to
1597update your gcc installation.
1598
aa689395 1599=item Optimizer
c3edaffb 1600
9d67150a 1601If you can't compile successfully, try turning off your compiler's
aa689395 1602optimizer. Edit config.sh and change the line
9d67150a 1603
1604 optimize='-O'
1605
bfb7748a 1606to
9d67150a 1607
1608 optimize=' '
1609
1610then propagate your changes with B<sh Configure -S> and rebuild
1611with B<make depend; make>.
1612
4bbc1586 1613=item Missing functions and Undefined symbols
9d67150a 1614
4bbc1586
AD
1615If the build of miniperl fails with a long list of missing functions or
1616undefined symbols, check the libs variable in the config.sh file. It
1617should look something like
1618
1619 libs='-lsocket -lnsl -ldl -lm -lc'
1620
1621The exact libraries will vary from system to system, but you typically
1622need to include at least the math library -lm. Normally, Configure
1623will suggest the correct defaults. If the libs variable is empty, you
1624need to start all over again. Run
1625
1626 make distclean
1627
1628and start from the very beginning. This time, unless you are sure of
1629what you are doing, accept the default list of libraries suggested by
1630Configure.
1631
0ff780f4
MB
1632If the libs variable is missing -lm, there is a chance that libm.so.1
1633is available, but the required (symbolic) link to libm.so is missing.
1634(same could be the case for other libraries like libcrypt.so). You
1635should check your installation for packages that create that link, and
1636if no package is installed that supplies that link or you cannot install
1637them, make the symbolic link yourself e.g.:
1638
c7121961
FC
1639 $ rpm -qf /usr/lib64/libm.so
1640 glibc-devel-2.15-22.17.1.x86_64
1641 $ ls -lgo /usr/lib64/libm.so
1642 lrwxrwxrwx 1 16 Jan 7 2013 /usr/lib64/libm.so -> /lib64/libm.so.6
0ff780f4 1643
c7121961 1644 or
0ff780f4 1645
c7121961 1646 $ sudo ln -s /lib64/libm.so.6 /lib64/libm.so
0ff780f4 1647
4bbc1586
AD
1648If the libs variable looks correct, you might have the
1649L<"nm extraction"> problem discussed above.
1650
668cbedd 1651If you still have missing routines or undefined symbols, you probably
0ff780f4
MB
1652need to add some library or other, make a symbolic link like described
1653above, or you need to undefine some feature that Configure thought was
1654there but is defective or incomplete. If you used a hint file, see if
1655it has any relevant advice. You can also look through through config.h
1656for likely suspects.
8e07c86e 1657
1ec51d55 1658=item toke.c
8e07c86e 1659
1ec51d55
CS
1660Some compilers will not compile or optimize the larger files (such as
1661toke.c) without some extra switches to use larger jump offsets or
1662allocate larger internal tables. You can customize the switches for
ab97e755
MB
1663each file in cflags.SH. It's okay to insert rules for specific files
1664into makefile since a default rule only takes effect in the absence of a
8e07c86e
AD
1665specific rule.
1666
7f678428 1667=item Missing dbmclose
8e07c86e 1668
c3edaffb 1669SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
1670that includes libdbm.nfs (which includes dbmclose()) may be available.
8e07c86e 1671
1bb125e2
MB
1672=item error: too few arguments to function 'dbmclose'
1673
1674Building ODBM_File on some (Open)SUSE distributions might run into this
1675error, as the header file is broken. There are two ways to deal with this
1676
1677 1. Disable the use of ODBM_FILE
1678
1679 Configure ... -Dnoextensions=ODBM_File
1680
1681 2. Fix the header file, somewhat like this:
1682
1683 --- a/usr/include/dbm.h 2010-03-24 08:54:59.000000000 +0100
1684 +++ b/usr/include/dbm.h 2010-03-24 08:55:15.000000000 +0100
1685 @@ -59,4 +59,4 @@ extern datum firstkey __P((void));
1686
1687 extern datum nextkey __P((datum key));
1688
1689 -extern int dbmclose __P((DBM *));
1690 +extern int dbmclose __P((void));
1691
44666fef 1692=item Warning (mostly harmless): No library found for -lsomething
7f678428 1693
1694If you see such a message during the building of an extension, but
1695the extension passes its tests anyway (see L<"make test"> below),
1696then don't worry about the warning message. The extension
1697Makefile.PL goes looking for various libraries needed on various
aa689395 1698systems; few systems will need all the possible libraries listed.
74b7c41f 1699Most users will see warnings for the ones they don't have. The
44666fef 1700phrase 'mostly harmless' is intended to reassure you that nothing
74b7c41f 1701unusual is happening, and the build process is continuing.
7f678428 1702
1703On the other hand, if you are building GDBM_File and you get the
1704message
1705
44666fef 1706 Warning (mostly harmless): No library found for -lgdbm
7f678428 1707
1708then it's likely you're going to run into trouble somewhere along
1709the line, since it's hard to see how you can use the GDBM_File
1710extension without the -lgdbm library.
1711
1712It is true that, in principle, Configure could have figured all of
1713this out, but Configure and the extension building process are not
1714quite that tightly coordinated.
1715
aa689395 1716=item sh: ar: not found
1717
1718This is a message from your shell telling you that the command 'ar'
1719was not found. You need to check your PATH environment variable to
1720make sure that it includes the directory with the 'ar' command. This
1ec51d55 1721is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
aa689395 1722directory.
1723
1724=item db-recno failure on tests 51, 53 and 55
1725
1726Old versions of the DB library (including the DB library which comes
1727with FreeBSD 2.1) had broken handling of recno databases with modified
1728bval settings. Upgrade your DB library or OS.
1729
6087ac44
JH
1730=item Bad arg length for semctl, is XX, should be ZZZ
1731
c935ba53 1732If you get this error message from the F<cpan/IPC-SysV/t/sem.t> test, your
ab97e755 1733System V IPC may be broken. The XX typically is 20, and that is what ZZZ
6087ac44
JH
1734also should be. Consider upgrading your OS, or reconfiguring your OS
1735to include the System V semaphores.
1736
c935ba53 1737=item cpan/IPC-SysV/t/sem........semget: No space left on device
220f3621
GS
1738
1739Either your account or the whole system has run out of semaphores. Or
1740both. Either list the semaphores with "ipcs" and remove the unneeded
1741ones (which ones these are depends on your system and applications)
1742with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
1743system.
1744
d6baa268
JH
1745=item GNU binutils
1746
1747If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
1748tools you may be in for some trouble. For example creating archives
1749with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
1750may lead into linking problems. Either recompile your GNU binutils
1751under your current operating system release, or modify your PATH not
1752to include the GNU utils before running Configure, or specify the
1753vendor-supplied utilities explicitly to Configure, for example by
1754Configure -Dar=/bin/ar.
1755
16dc217a
GS
1756=item THIS PACKAGE SEEMS TO BE INCOMPLETE
1757
1758The F<Configure> program has not been able to find all the files which
1759make up the complete Perl distribution. You may have a damaged source
1760archive file (in which case you may also have seen messages such as
1761C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on
1762archive file>), or you may have obtained a structurally-sound but
1763incomplete archive. In either case, try downloading again from the
1764official site named at the start of this document. If you do find
1765that any site is carrying a corrupted or incomplete source code
1766archive, please report it to the site's maintainer.
1767
16dc217a
GS
1768=item invalid token: ##
1769
ce80d64e
AD
1770You are using a non-ANSI-compliant C compiler. To compile Perl, you
1771need to use a compiler that supports ANSI C. If there is a README
1772file for your system, it may have further details on your compiler
1773options.
16dc217a 1774
1ec51d55 1775=item Miscellaneous
8e07c86e 1776
7df75831 1777Some additional things that have been reported:
8e07c86e
AD
1778
1779Genix may need to use libc rather than libc_s, or #undef VARARGS.
1780
1781NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
1782
668cbedd 1783UTS may need one or more of -K or -g, and #undef LSTAT.
8e07c86e 1784
c935ba53 1785FreeBSD can fail the F<cpan/IPC-SysV/t/sem.t> test if SysV IPC has not been
5cda700b 1786configured in the kernel. Perl tries to detect this, though, and
ce80d64e 1787you will get a message telling you what to do.
6087ac44 1788
6c8d78fb
HS
1789Building Perl on a system that has also BIND (headers and libraries)
1790installed may run into troubles because BIND installs its own netdb.h
1791and socket.h, which may not agree with the operating system's ideas of
1792the same files. Similarly, including -lbind may conflict with libc's
1793view of the world. You may have to tweak -Dlocincpth and -Dloclibpth
1794to avoid the BIND.
1795
8e07c86e
AD
1796=back
1797
58a21a9b
JH
1798=head2 Cross-compilation
1799
e7a3c61b 1800Perl can be cross-compiled. It is just not trivial, cross-compilation
30bba555 1801rarely is. Perl is routinely cross-compiled for several platforms: as of
f36edc68 1802January 2014, these include Android, Blackberry 10, PocketPC aka
30bba555
BF
1803WinCE, ARM Linux, and Solaris. Previous versions of
1804Perl also provided support for Open Zaurus, Symbian, and
1805the IBM OS/400, but it's unknown if those ports are still functional.
ab97e755
MB
1806These platforms are known as the B<target> platforms, while the systems
1807where the compilation takes place are the B<host> platforms.
e7a3c61b
JH
1808
1809What makes the situation difficult is that first of all,
1810cross-compilation environments vary significantly in how they are set
1811up and used, and secondly because the primary way of configuring Perl
1812(using the rather large Unix-tool-dependent Configure script) is not
1813awfully well suited for cross-compilation. However, starting from
30bba555
BF
1814version 5.18.0, the Configure script also knows two ways of supporting
1815cross-compilation, so please keep reading.
e7a3c61b
JH
1816
1817See the following files for more information about compiling Perl for
1818the particular platforms:
1819
1820=over 4
1821
1822=item WinCE/PocketPC
1823
30bba555 1824L<README.ce or perlce|perlce>
e7a3c61b 1825
30bba555 1826=item Android
e7a3c61b 1827
ab97e755
MB
1828L<"Cross-compilation" in README.android or
1829perlandroid|perlandroid/Cross-compilation>
e7a3c61b 1830
30bba555 1831=item Blackberry
e7a3c61b 1832
30bba555 1833L<"Cross-compilation" in README.qnx or perlqnx|perlqnx/Cross-compilation>
e7a3c61b 1834
30bba555 1835=item Solaris
e7a3c61b 1836
ab97e755
MB
1837L<"CROSS-COMPILATION" in README.solaris or
1838perlsolaris|perlsolaris/CROSS-COMPILATION>
30bba555
BF
1839
1840=item Linux
1841
1842This document; See below.
e7a3c61b
JH
1843
1844=back
1845
1846Packaging and transferring either the core Perl modules or CPAN
1847modules to the target platform is also left up to the each
1848cross-compilation environment. Often the cross-compilation target
1849platforms are somewhat limited in diskspace: see the section
1850L<Minimizing the Perl installation> to learn more of the minimal set
1851of files required for a functional Perl installation.
1852
1853For some cross-compilation environments the Configure option
1854C<-Dinstallprefix=...> might be handy, see L<Changing the installation
1855directory>.
1856
30bba555 1857About the cross-compilation support of Configure: There's two forms.
ab97e755
MB
1858The more common one requires some way of transferring and running
1859executables in the target system, such as an ssh connection; this is the
1860C<./Configure -Dusecrosscompile -Dtargethost=...> route. The second
1861method doesn't need access to the target system, but requires you to
1862provide a config.sh, and and a canned Makefile; the rest of this section
1863describes the former.
e7a3c61b 1864
30bba555 1865This cross-compilation setup of Configure has successfully been used in
ab97e755
MB
1866a wide variety of setups, such as a 64-bit OS X host for an Android ARM
1867target, or an amd64 Linux host targeting x86 Solaris, or even Windows.
e7a3c61b
JH
1868
1869To run Configure in cross-compilation mode the basic switch that
30bba555 1870has to be used is C<-Dusecrosscompile>:
58a21a9b
JH
1871
1872 sh ./Configure -des -Dusecrosscompile -D...
1873
1874This will make the cpp symbol USE_CROSS_COMPILE and the %Config
30bba555 1875symbol C<usecrosscompile> available.
58a21a9b
JH
1876
1877During the Configure and build, certain helper scripts will be created
1878into the Cross/ subdirectory. The scripts are used to execute a
1879cross-compiled executable, and to transfer files to and from the
1880target host. The execution scripts are named F<run-*> and the
1881transfer scripts F<to-*> and F<from-*>. The part after the dash is
1882the method to use for remote execution and transfer: by default the
1883methods are B<ssh> and B<scp>, thus making the scripts F<run-ssh>,
1884F<to-scp>, and F<from-scp>.
1885
1886To configure the scripts for a target host and a directory (in which
1887the execution will happen and which is to and from where the transfer
1888happens), supply Configure with
1889
1890 -Dtargethost=so.me.ho.st -Dtargetdir=/tar/get/dir
1891
1892The targethost is what e.g. ssh will use as the hostname, the targetdir
93bc48fa
JH
1893must exist (the scripts won't create it), the targetdir defaults to /tmp.
1894You can also specify a username to use for ssh/rsh logins
58a21a9b
JH
1895
1896 -Dtargetuser=luser
1897
30bba555 1898but in case you don't, "root" will be used. Similarly, you can specify
ab97e755
MB
1899a non-standard (i.e. not 22) port for the connection, if applicable,
1900through
30bba555
BF
1901
1902 -Dtargetport=2222
58a21a9b 1903
30bba555
BF
1904If the name of C<cc> has the usual GNU C semantics for cross
1905compilers, that is, CPU-OS-gcc, the target architecture (C<targetarch>),
1906plus names of the C<ar>, C<nm>, and C<ranlib> will also be automatically
1907chosen to be CPU-OS-ar and so on.
1908(The C<ld> requires more thought and will be chosen later by Configure
1909as appropriate). This will also aid in guessing the proper
1910operating system name for the target, which has other repercussions, like
ab97e755
MB
1911better defaults and possibly critical fixes for the platform. If
1912Configure isn't guessing the OS name properly, you may need to either add
1913a hint file redirecting Configure's guess, or modify Configure to make
1914the correct choice.
30bba555
BF
1915
1916If your compiler doesn't follow that convention, you will also need to
1917specify which target environment to use, as well as C<ar> and friends:
58a21a9b
JH
1918
1919 -Dtargetarch=arm-linux
30bba555
BF
1920 -Dcc=mycrossgcc
1921 -Dar=...
1922
1923Additionally, a cross-compilation toolchain will usually install it's own
ab97e755 1924logical system root somewhere -- that is, it'll create a directory
a95b3d6a
KW
1925somewhere which includes subdirectories like C<'include'> or C<'lib'>. For
1926example, you may end up with F</skiff/local/arm-linux>, where
1927F</skiff/local/arm-linux/bin> holds the binaries for cross-compilation,
1928F</skiff/local/arm-linux/include> has the headers, and
1929F</skiff/local/arm-linux/lib> has the library files.
30bba555
BF
1930If this is the case, and you are using a compiler that understands
1931C<--sysroot>, like gcc or clang, you'll want to specify the
1932C<-Dsysroot> option for Configure:
1933
1934 -Dsysroot=/skiff/local/arm-linux
1935
1936However, if your don't have a suitable directory to pass to C<-Dsysroot>,
1937you will also need to specify which target environment to use:
1938
58a21a9b
JH
1939 -Dusrinc=/skiff/local/arm-linux/include
1940 -Dincpth=/skiff/local/arm-linux/include
1941 -Dlibpth=/skiff/local/arm-linux/lib
1942
58a21a9b
JH
1943In addition to the default execution/transfer methods you can also
1944choose B<rsh> for execution, and B<rcp> or B<cp> for transfer,
1945for example:
1946
1947 -Dtargetrun=rsh -Dtargetto=rcp -Dtargetfrom=cp
1948
1949Putting it all together:
1950
1951 sh ./Configure -des -Dusecrosscompile \
93bc48fa 1952 -Dtargethost=so.me.ho.st \
30bba555 1953 -Dtargetdir=/tar/get/dir \
58a21a9b
JH
1954 -Dtargetuser=root \
1955 -Dtargetarch=arm-linux \
1956 -Dcc=arm-linux-gcc \
30bba555 1957 -Dsysroot=/skiff/local/arm-linux \
58a21a9b
JH
1958 -D...
1959
e7a3c61b 1960or if you are happy with the defaults:
93bc48fa
JH
1961
1962 sh ./Configure -des -Dusecrosscompile \
1963 -Dtargethost=so.me.ho.st \
1964 -Dcc=arm-linux-gcc \
1965 -D...
1966
e7a3c61b
JH
1967Another example where the cross-compiler has been installed under
1968F</usr/local/arm/2.95.5>:
1969
1970 sh ./Configure -des -Dusecrosscompile \
1971 -Dtargethost=so.me.ho.st \
1972 -Dcc=/usr/local/arm/2.95.5/bin/arm-linux-gcc \
30bba555
BF
1973 -Dsysroot=/usr/local/arm/2.95.5
1974
1975There is also a C<targetenv> option for Configure which can be used
1976to modify the environment of the target just before testing begins
1977during 'make test'. For example, if the target system has a nonstandard
1978/tmp location, you could do this:
1979
1980 -Dtargetenv="export TMPDIR=/other/tmp;"
1981
ab97e755
MB
1982If you are planning on cross-compiling to several platforms, or some
1983other thing that would involve running Configure several times, there are
1984two options that can be used to speed things up considerably.
30bba555
BF
1985As a bit of background, when you
1986call Configure with C<-Dusecrosscompile>, it begins by actually partially
1987building a miniperl on the host machine, as well as the generate_uudmap
1988binary, and we end up using that during the build.
ab97e755
MB
1989So instead of building that new perl every single time, you can build it
1990just once in a separate directory, and then pass the resulting binaries
1991to Configure like this:
30bba555
BF
1992
1993 -Dhostperl=/path/to/second/build/dir/miniperl
1994 -Dhostgenerate=/path/to/second/build/dir/generate_uudmap
1995
1996Much less commonly, if you are cross-compiling from an ASCII host to an
1997EBCDIC target, or vise versa, you'll have to pass C<-Uhostgenerate> to
1998Configure, to signify that you want to build a generate_uudmap binary
1999that, during make, will be run on the target system.
e7a3c61b 2000
8e07c86e
AD
2001=head1 make test
2002
d6baa268
JH
2003This will run the regression tests on the perl you just made. If
2004'make test' doesn't say "All tests successful" then something went
36bded94 2005wrong.
84902520 2006
84902520 2007Note that you can't run the tests in background if this disables
fb73857a 2008opening of /dev/tty. You can use 'make test-notty' in that case but
2009a few tty tests will be skipped.
c3edaffb 2010
c4f23d77
AD
2011=head2 What if make test doesn't work?
2012
1ec51d55 2013If make test bombs out, just cd to the t directory and run ./TEST
36bded94 2014by hand to see if it makes any difference.
8e07c86e 2015
36bded94
AD
2016One way to get more detailed information about failed tests and
2017individual subtests is to run the harness from the t directory:
aa689395 2018
785aa5e3 2019 cd t ; ./perl harness <list of tests>
aa689395 2020
fb73857a 2021(this assumes that most basic tests succeed, since harness uses
785aa5e3
RGS
2022complicated constructs). If no list of tests is provided, harness
2023will run all tests.
10c7e831 2024
36bded94
AD
2025If individual tests fail, you can often run them by hand (from the main
2026perl directory), e.g.,
2027
2028 ./perl -MTestInit t/op/groups.t
2029
fb73857a 2030You should also read the individual tests to see if there are any helpful
10c7e831
JH
2031comments that apply to your system. You may also need to setup your
2032shared library path if you get errors like:
2033
2034 /sbin/loader: Fatal Error: cannot map libperl.so
2035
36bded94
AD
2036The file t/README in the t subdirectory contains more information about
2037running and modifying tests.
2038
10c7e831 2039See L</"Building a shared Perl library"> earlier in this document.
c3edaffb 2040
c4f23d77
AD
2041=over 4
2042
2043=item locale
2044
1ec51d55 2045Note: One possible reason for errors is that some external programs
c07a80fd 2046may be broken due to the combination of your environment and the way
785aa5e3 2047'make test' exercises them. For example, this may happen if you have
1ec51d55
CS
2048one or more of these environment variables set: LC_ALL LC_CTYPE
2049LC_COLLATE LANG. In some versions of UNIX, the non-English locales
e57fd563 2050are known to cause programs to exhibit mysterious errors.
2051
2052If you have any of the above environment variables set, please try
aa689395 2053
2054 setenv LC_ALL C
2055
2056(for C shell) or
2057
2058 LC_ALL=C;export LC_ALL
2059
1ec51d55
CS
2060for Bourne or Korn shell) from the command line and then retry
2061make test. If the tests then succeed, you may have a broken program that
aa689395 2062is confusing the testing. Please run the troublesome test by hand as
e57fd563 2063shown above and see whether you can locate the program. Look for
1ec51d55
CS
2064things like: exec, `backquoted command`, system, open("|...") or
2065open("...|"). All these mean that Perl is trying to run some
e57fd563 2066external program.
eed2e782 2067
0740bb5b
AD
2068=item Timing problems
2069
c29923ff
JH
2070Several tests in the test suite check timing functions, such as
2071sleep(), and see if they return in a reasonable amount of time.
9341413f
JH
2072If your system is quite busy and doesn't respond quickly enough,
2073these tests might fail. If possible, try running the tests again
2074with the system under a lighter load. These timing-sensitive
2075and load-sensitive tests include F<t/op/alarm.t>,
d0b0e707
TH
2076F<dist/Time-HiRes/t/alarm.t>, F<dist/Time-HiRes/t/clock.t>,
2077F<dist/Time-HiRes/t/itimer.t>, F<dist/Time-HiRes/t/usleep.t>,
1543af16 2078F<dist/threads-shared/t/waithires.t>,
c935ba53 2079F<dist/threads-shared/t/stress.t>, F<lib/Benchmark.t>,
9341413f 2080F<lib/Memoize/t/expmod_t.t>, and F<lib/Memoize/t/speed.t>.
0740bb5b 2081
f89caa8d
RGS
2082You might also experience some failures in F<t/op/stat.t> if you build
2083perl on an NFS filesystem, if the remote clock and the system clock are
2084different.
2085
c4f23d77
AD
2086=item Out of memory
2087
2088On some systems, particularly those with smaller amounts of RAM, some
2089of the tests in t/op/pat.t may fail with an "Out of memory" message.
7970f296
GS
2090For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
2091test 85 will fail if run under either t/TEST or t/harness.
c4f23d77
AD
2092
2093Try stopping other jobs on the system and then running the test by itself:
2094
04bd6448 2095 ./perl -MTestInit t/op/pat.t
c4f23d77
AD
2096
2097to see if you have any better luck. If your perl still fails this
2098test, it does not necessarily mean you have a broken perl. This test
2099tries to exercise the regular expression subsystem quite thoroughly,
2100and may well be far more demanding than your normal usage.
2101
a55bb48b
AD
2102=item libgcc_s.so.1: cannot open shared object file
2103
2104This message has been reported on gcc-3.2.3 and earlier installed with
2105a non-standard prefix. Setting the LD_LIBRARY_PATH environment variable
2106(or equivalent) to include gcc's lib/ directory with the libgcc_s.so.1
2107shared library should fix the problem.
2108
4f76e5ba
AD
2109=item Failures from lib/File/Temp/t/security saying "system possibly insecure"
2110
2111First, such warnings are not necessarily serious or indicative of a
2112real security threat. That being said, they bear investigating.
2113
2114Note that each of the tests is run twice. The first time is in the
2115directory returned by File::Spec->tmpdir() (often /tmp on Unix
2116systems), and the second time in the directory from which the test was
2117run (usually the 't' directory, if the test was run as part of 'make
2118test').
2119
2120The tests may fail for the following reasons:
2121
2122(1) If the directory the tests are being run in is owned by somebody
2123other than the user running the tests, or by root (uid 0).
2124
2125This failure can happen if the Perl source code distribution is
668cbedd 2126unpacked in such a way that the user IDs in the distribution package
4f76e5ba
AD
2127are used as-is. Some tar programs do this.
2128
2129(2) If the directory the tests are being run in is writable by group or
2130by others, and there is no sticky bit set for the directory. (With
2131UNIX/POSIX semantics, write access to a directory means the right to
2132add or remove files in that directory. The 'sticky bit' is a feature
2133used in some UNIXes to give extra protection to files: if the bit is
2134set for a directory, no one but the owner (or root) can remove that
2135file even if the permissions would otherwise allow file removal by
2136others.)
2137
2138This failure may or may not be a real problem: it depends on the
2139permissions policy used on this particular system. This failure can
2140also happen if the system either doesn't support the sticky bit (this
2141is the case with many non-UNIX platforms: in principle File::Temp
2142should know about these platforms and skip the tests), or if the system
2143supports the sticky bit but for some reason or reasons it is not being
2144used. This is, for example, the case with HP-UX: as of HP-UX release
214511.00, the sticky bit is very much supported, but HP-UX doesn't use it
2146on its /tmp directory as shipped. Also, as with the permissions, some
2147local policy might dictate that the stickiness is not used.
781948c1 2148
b2b23189
JH
2149(3) If the system supports the POSIX 'chown giveaway' feature and if
2150any of the parent directories of the temporary file back to the root
2151directory are 'unsafe', using the definitions given above in (1) and
4f76e5ba
AD
2152(2). For Unix systems, this is usually not an issue if you are
2153building on a local disk. See the documentation for the File::Temp
2154module for more information about 'chown giveaway'.
781948c1
JH
2155
2156See the documentation for the File::Temp module for more information
4f76e5ba 2157about the various security aspects of temporary files.
781948c1 2158
c4f23d77
AD
2159=back
2160
5ee651a9 2161The core distribution can now run its regression tests in parallel on
ab97e755
MB
2162Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS>
2163in your environment to the number of tests to run in parallel, and run
5ee651a9
NC
2164C<make test_harness>. On a Bourne-like shell, this can be done as
2165
2166 TEST_JOBS=3 make test_harness # Run 3 tests in parallel
2167
ab97e755
MB
2168An environment variable is used, rather than parallel make itself,
2169because L<TAP::Harness> needs to be able to schedule individual
2170non-conflicting test scripts itself, and there is no standard interface
2171to C<make> utilities to interact with their job schedulers.
5ee651a9 2172
8e07c86e
AD
2173=head1 make install
2174
2175This will put perl into the public directory you specified to
ab97e755
MB
2176Configure; by default this is /usr/local/bin. It will also try to put
2177the man pages in a reasonable place. It will not nroff the man pages,
2178however. You may need to be root to run B<make install>. If you are not
2179root, you must still have permission to install into the directories
ce80d64e
AD
2180in question and you should ignore any messages about chown not working.
2181
19f4563d 2182If "make install" just says "'install' is up to date" or something
ce80d64e
AD
2183similar, you may be on a case-insensitive filesystems such as Mac's HFS+,
2184and you should say "make install-all". (This confusion is brought to you
2185by the Perl distribution having a file called INSTALL.)
8e07c86e 2186
dd64f1c3
AD
2187=head2 Installing perl under different names
2188
2189If you want to install perl under a name other than "perl" (for example,
2190when installing perl with special features enabled, such as debugging),
2191indicate the alternate name on the "make install" line, such as:
2192
2193 make install PERLNAME=myperl
2194
beb13193 2195You can separately change the base used for versioned names (like
be8498a1 2196"perl5.8.9") by setting PERLNAME_VERBASE, like
beb13193
RS
2197
2198 make install PERLNAME=perl5 PERLNAME_VERBASE=perl
2199
ab97e755
MB
2200This can be useful if you have to install perl as "perl5" (e.g. to avoid
2201conflicts with an ancient version in /usr/bin supplied by your vendor).
be8498a1 2202Without this the versioned binary would be called "perl55.8.8".
beb13193 2203
ce80d64e
AD
2204=head2 Installing perl under a different directory
2205
2206You can install perl under a different destination directory by using
2207the DESTDIR variable during C<make install>, with a command like
2208
2209 make install DESTDIR=/tmp/perl5
2210
2211DESTDIR is automatically prepended to all the installation paths. See
7df75831 2212the example in L<"DESTDIR"> above.
ce80d64e 2213
dd64f1c3
AD
2214=head2 Installed files
2215
8e07c86e
AD
2216If you want to see exactly what will happen without installing
2217anything, you can run
4633a7c4 2218
8e07c86e
AD
2219 ./perl installperl -n
2220 ./perl installman -n
2221
1ec51d55 2222make install will install the following:
8e07c86e 2223
d56c5707
JH
2224 binaries
2225
8e07c86e 2226 perl,
be8498a1 2227 perl5.n.n where 5.n.n is the current release number. This
8e07c86e 2228 will be a link to perl.
d56c5707
JH
2229
2230 scripts
2231
979b4168
KW
2232 cppstdin This is used by the deprecated switch perl -P,
2233 if your cc -E can't read from stdin.
2234 c2ph, pstruct Scripts for handling C structures in header
2235 files.
979b4168
KW
2236 corelist Shows versions of modules that come with
2237 different
668cbedd
KW
2238 versions of perl.
2239 cpan The CPAN shell.
668cbedd 2240 enc2xs Encoding module generator.
979b4168
KW
2241 h2ph Extract constants and simple macros from C
2242 headers.
8e07c86e 2243 h2xs Converts C .h header files to Perl extensions.
73d6d1b0
RGS
2244 instmodsh A shell to examine installed modules.
2245 libnetcfg Configure libnet.
24b3df7f 2246 perlbug Tool to report bugs in Perl.
8e07c86e 2247 perldoc Tool to read perl's pod documentation.
668cbedd 2248 perlivp Perl Installation Verification Procedure.
73d6d1b0 2249 piconv A Perl implementation of the encoding conversion
668cbedd
KW
2250 utility iconv.
2251 pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules.
8e07c86e 2252 pod2html, Converters from perl's pod documentation format
d56c5707
JH
2253 pod2man,
2254 pod2text,
d56c5707 2255 pod2usage
668cbedd
KW
2256 podchecker POD syntax checker.
2257 podselect Prints sections of POD documentation.
2258 prove A command-line tool for running tests.
2259 psed A Perl implementation of sed.
2260 ptar A Perl implementation of tar.
2261 ptardiff A diff for tar archives.
2262 ptargrep A grep for tar archives.
668cbedd
KW
2263 shasum A tool to print or check SHA checksums.
2264 splain Describe Perl warnings and errors.
2265 xsubpp Compiler to convert Perl XS code into C code.
979b4168 2266 zipdetails display the internal structure of zip files
8e07c86e 2267
d56c5707
JH
2268 library files
2269
2270 in $privlib and $archlib specified to
8e07c86e 2271 Configure, usually under /usr/local/lib/perl5/.
d56c5707
JH
2272
2273 documentation
2274
d6baa268
JH
2275 man pages in $man1dir, usually /usr/local/man/man1.
2276 module man
2277 pages in $man3dir, usually /usr/local/man/man3.
8e07c86e
AD
2278 pod/*.pod in $privlib/pod/.
2279
33cceb07 2280installperl will also create the directories listed above
d6baa268 2281in L<"Installation Directories">.
4633a7c4 2282
d56c5707 2283Perl's *.h header files and the libperl library are also installed
d6baa268 2284under $archlib so that any user may later build new modules, run the
56c6f531
JH
2285optional Perl compiler, or embed the perl interpreter into another
2286program even if the Perl source is no longer available.
8e07c86e 2287
33cceb07
RGS
2288=head2 Installing only version-specific parts
2289
d56c5707
JH
2290Sometimes you only want to install the version-specific parts of the perl
2291installation. For example, you may wish to install a newer version of
33cceb07 2292perl alongside an already installed production version without
d56c5707
JH
2293disabling installation of new modules for the production version.
2294To only install the version-specific parts of the perl installation, run
2295
2296 Configure -Dversiononly
2297
2298or answer 'y' to the appropriate Configure prompt. Alternatively,
2299you can just manually run
2300
2301 ./perl installperl -v
2302
2303and skip installman altogether.
33cceb07 2304
d56c5707
JH
2305See also L<"Maintaining completely separate versions"> for another
2306approach.
2307
f4ce0e6d
RGS
2308=head1 cd /usr/include; h2ph *.h sys/*.h
2309
2310Some perl scripts need to be able to obtain information from the
2311system header files. This command will convert the most commonly used
2312header files in /usr/include into files that can be easily interpreted
2313by perl. These files will be placed in the architecture-dependent
2314library ($archlib) directory you specified to Configure.
2315
668cbedd 2316Note: Due to differences in the C and perl languages, the conversion
f4ce0e6d
RGS
2317of the header files is not perfect. You will probably have to
2318hand-edit some of the converted files to get them to parse correctly.
2319For example, h2ph breaks spectacularly on type casting and certain
2320structures.
2321
2322=head1 installhtml --help
2323
2324Some sites may wish to make perl documentation available in HTML
2325format. The installhtml utility can be used to convert pod
2326documentation into linked HTML files and install them.
2327
2328Currently, the supplied ./installhtml script does not make use of the
2329html Configure variables. This should be fixed in a future release.
2330
2331The following command-line is an example of one used to convert
2332perl documentation:
2333
2334 ./installhtml \
2335 --podroot=. \
2336 --podpath=lib:ext:pod:vms \
2337 --recurse \
2338 --htmldir=/perl/nmanual \
2339 --htmlroot=/perl/nmanual \
2340 --splithead=pod/perlipc \
2341 --splititem=pod/perlfunc \
f4ce0e6d
RGS
2342 --verbose
2343
2344See the documentation in installhtml for more details. It can take
2345many minutes to execute a large installation and you should expect to
2346see warnings like "no title", "unexpected directive" and "cannot
2347resolve" as the files are processed. We are aware of these problems
2348(and would welcome patches for them).
2349
2350You may find it helpful to run installhtml twice. That should reduce
2351the number of "cannot resolve" warnings.
2352
2353=head1 cd pod && make tex && (process the latex files)
2354
2355Some sites may also wish to make the documentation in the pod/ directory
2356available in TeX format. Type
2357
2358 (cd pod && make tex && <process the latex files>)
2359
2360=head1 Starting all over again
2361
668cbedd 2362If you wish to rebuild perl from the same build directory, you should
f4ce0e6d
RGS
2363clean it out with the command
2364
2365 make distclean
2366
2367or
2368
2369 make realclean
2370
2371The only difference between the two is that make distclean also removes
dd8235d9
TC
2372your old config.sh and Policy.sh files. (A plain 'make clean' is now
2373eqivalent to 'make realclean'.)
f4ce0e6d
RGS
2374
2375If you are upgrading from a previous version of perl, or if you
2376change systems or compilers or make other significant changes, or if
668cbedd 2377you are experiencing difficulties building perl, you should not reuse
f4ce0e6d
RGS
2378your old config.sh.
2379
2380If your reason to reuse your old config.sh is to save your particular
2381installation choices, then you can probably achieve the same effect by
2382using the Policy.sh file. See the section on L<"Site-wide Policy
2383settings"> above.
2384
ff52061e
RGS
2385=head1 Reporting Problems
2386
2387Wherever possible please use the perlbug tool supplied with this Perl
2388to report problems, as it automatically includes summary configuration
2389information about your perl, which may help us track down problems far
2390more quickly. But first you should read the advice in this file,
2391carefully re-read the error message and check the relevant manual pages
2392on your system, as these may help you find an immediate solution. If
2393you are not sure whether what you are seeing is a bug, you can send a
2394message describing the problem to the comp.lang.perl.misc newsgroup to
2395get advice.
2396
2397The perlbug tool is installed along with perl, so after you have
2398completed C<make install> it should be possible to run it with plain
2399C<perlbug>. If the install fails, or you want to report problems with
2400C<make test> without installing perl, then you can use C<make nok> to
2401run perlbug to report the problem, or run it by hand from this source
2402directory with C<./perl -Ilib utils/perlbug>
2403
2404If the build fails too early to run perlbug uninstalled, then please
2405B<run> the C<./myconfig> shell script, and mail its output along with
2406an accurate description of your problem to perlbug@perl.org
2407
2408If Configure itself fails, and does not generate a config.sh file
2409(needed to run C<./myconfig>), then please mail perlbug@perl.org the
2410description of how Configure fails along with details of your system
668cbedd 2411-- for example the output from running C<uname -a>
ff52061e
RGS
2412
2413Please try to make your message brief but clear. Brief, clear bug
2414reports tend to get answered more quickly. Please don't worry if your
668cbedd 2415written English is not great -- what matters is how well you describe
ff52061e
RGS
2416the important technical details of the problem you have encountered,
2417not whether your grammar and spelling is flawless.
2418
2419Trim out unnecessary information. Do not include large files (such as
2420config.sh or a complete Configure or make log) unless absolutely
2421necessary. Do not include a complete transcript of your build
2422session. Just include the failing commands, the relevant error
2423messages, and whatever preceding commands are necessary to give the
668cbedd 2424appropriate context. Plain text should usually be sufficient -- fancy
ff52061e
RGS
2425attachments or encodings may actually reduce the number of people who
2426read your message. Your message will get relayed to over 400
2427subscribers around the world so please try to keep it brief but clear.
2428
87c118b9
DM
2429If the bug you are reporting has security implications which make it
2430inappropriate to send to a publicly archived mailing list, then see
2431L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
2432for details of how to report the issue.
5acb7768 2433
ff52061e
RGS
2434If you are unsure what makes a good bug report please read "How to
2435report Bugs Effectively" by Simon Tatham:
2436http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
2437
7df75831 2438=head1 Coexistence with earlier versions of perl 5
4633a7c4 2439
1e2ea6fa 2440Perl 5.25.2 is not binary compatible with earlier versions of Perl.
cc65bb49 2441In other words, you will have to recompile your XS modules.
14eee2f1 2442
ab97e755
MB
2443In general, you can usually safely upgrade from one version of Perl
2444(e.g. 5.X.Y) to another similar minor version (e.g. 5.X.(Y+1))) without
33cceb07 2445re-compiling all of your extensions. You can also safely leave the old
ab97e755
MB
2446version around in case the new version causes you problems for some
2447reason.
693762b4 2448
be8498a1
RGS
2449Usually, most extensions will probably not need to be recompiled to be
2450used with a newer version of Perl. Here is how it is supposed to work.
ce80d64e 2451(These examples assume you accept all the Configure defaults.)
693762b4 2452
33cceb07
RGS
2453Suppose you already have version 5.8.7 installed. The directories
2454searched by 5.8.7 are typically like:
d6baa268 2455
33cceb07
RGS
2456 /usr/local/lib/perl5/5.8.7/$archname
2457 /usr/local/lib/perl5/5.8.7
2458 /usr/local/lib/perl5/site_perl/5.8.7/$archname
2459 /usr/local/lib/perl5/site_perl/5.8.7
d6baa268 2460
33cceb07
RGS
2461Now, suppose you install version 5.8.8. The directories
2462searched by version 5.8.8 will be:
d6baa268 2463
33cceb07
RGS
2464 /usr/local/lib/perl5/5.8.8/$archname
2465 /usr/local/lib/perl5/5.8.8
2466 /usr/local/lib/perl5/site_perl/5.8.8/$archname
2467 /usr/local/lib/perl5/site_perl/5.8.8
d6baa268 2468
33cceb07
RGS
2469 /usr/local/lib/perl5/site_perl/5.8.7/$archname
2470 /usr/local/lib/perl5/site_perl/5.8.7
c42e3e15 2471 /usr/local/lib/perl5/site_perl/
bfb7748a 2472
c42e3e15 2473Notice the last three entries -- Perl understands the default structure
d6baa268 2474of the $sitelib directories and will look back in older, compatible
33cceb07
RGS
2475directories. This way, modules installed under 5.8.7 will continue
2476to be usable by 5.8.7 but will also accessible to 5.8.8. Further,
d6baa268 2477suppose that you upgrade a module to one which requires features
33cceb07
RGS
2478present only in 5.8.8. That new module will get installed into
2479/usr/local/lib/perl5/site_perl/5.8.8 and will be available to 5.8.8,
2480but will not interfere with the 5.8.7 version.
bfb7748a 2481
c42e3e15 2482The last entry, /usr/local/lib/perl5/site_perl/, is there so that
fe23a901 24835.6.0 and above will look for 5.004-era pure perl modules.
d6baa268 2484
33cceb07
RGS
2485Lastly, suppose you now install 5.10.0, which is not binary compatible
2486with 5.8.x. The directories searched by 5.10.0 (if you don't change the
fe23a901
RF
2487Configure defaults) will be:
2488
33cceb07
RGS
2489 /usr/local/lib/perl5/5.10.0/$archname
2490 /usr/local/lib/perl5/5.10.0
2491 /usr/local/lib/perl5/site_perl/5.10.0/$archname
2492 /usr/local/lib/perl5/site_perl/5.10.0
d6baa268 2493
33cceb07 2494 /usr/local/lib/perl5/site_perl/5.8.8
d6baa268 2495
33cceb07 2496 /usr/local/lib/perl5/site_perl/5.8.7
fe23a901 2497
d6baa268 2498 /usr/local/lib/perl5/site_perl/
bfb7748a 2499
cc65bb49
AD
2500Note that the earlier $archname entries are now gone, but pure perl
2501modules from earlier versions will still be found.
2502
0a08c020
GS
2503This way, you can choose to share compatible extensions, but also upgrade
2504to a newer version of an extension that may be incompatible with earlier
2505versions, without breaking the earlier versions' installations.
693762b4
AD
2506
2507=head2 Maintaining completely separate versions
4633a7c4 2508
1ec51d55 2509Many users prefer to keep all versions of perl in completely
d6baa268 2510separate directories. This guarantees that an update to one version
0a08c020
GS
2511won't interfere with another version. (The defaults guarantee this for
2512libraries after 5.6.0, but not for executables. TODO?) One convenient
2513way to do this is by using a separate prefix for each version, such as
d52d4e46 2514
1e2ea6fa 2515 sh Configure -Dprefix=/opt/perl5.25.2
d52d4e46 2516
1e2ea6fa 2517and adding /opt/perl5.25.2/bin to the shell PATH variable. Such users
d52d4e46 2518may also wish to add a symbolic link /usr/local/bin/perl so that
2519scripts can still start with #!/usr/local/bin/perl.
2520
693762b4 2521Others might share a common directory for maintenance sub-versions
33cceb07 2522(e.g. 5.10 for all 5.10.x versions), but change directory with
693762b4
AD
2523each major version.
2524
6877a1cf
AD
2525If you are installing a development subversion, you probably ought to
2526seriously consider using a separate directory, since development
2527subversions may not have all the compatibility wrinkles ironed out
2528yet.
2529
5ad99925 2530=head2 Upgrading from v5.25.0 or earlier
693762b4 2531
1e2ea6fa 2532B<Perl 5.25.2 may not be binary compatible with Perl v5.22 or
4683a5d7 2533earlier Perl releases.> Perl modules having binary parts
e655887d 2534(meaning that a C compiler is used) will have to be recompiled to be
1e2ea6fa
S
2535used with 5.25.2. If you find you do need to rebuild an extension with
25365.25.2, you may safely do so without disturbing the older
7df75831 2537installations. (See L<"Coexistence with earlier versions of perl 5">
e655887d 2538above.)
c42e3e15
GS
2539
2540See your installed copy of the perllocal.pod file for a (possibly
2541incomplete) list of locally installed modules. Note that you want
cc65bb49 2542perllocal.pod, not perllocale.pod, for installed module information.
693762b4 2543
8ebf57cf
JH
2544=head1 Minimizing the Perl installation
2545
2546The following section is meant for people worrying about squeezing the
2547Perl installation into minimal systems (for example when installing
2548operating systems, or in really small filesystems).
2549
c8214fdf 2550Leaving out as many extensions as possible is an obvious way:
5cda700b
AD
2551Encode, with its big conversion tables, consumes a lot of
2552space. On the other hand, you cannot throw away everything. The
2553Fcntl module is pretty essential. If you need to do network
c8214fdf
JH
2554programming, you'll appreciate the Socket module, and so forth: it all
2555depends on what do you need to do.
2556
8ebf57cf
JH
2557In the following we offer two different slimmed down installation
2558recipes. They are informative, not normative: the choice of files
2559depends on what you need.
2560
2561Firstly, the bare minimum to run this script
2562
2563 use strict;
2564 use warnings;
2565 foreach my $f (</*>) {
2566 print("$f\n");
2567 }
2568
1e2ea6fa 2569in Linux with perl-5.25.2 is as follows (under $Config{prefix}):
8ebf57cf
JH
2570
2571 ./bin/perl
1e2ea6fa
S
2572 ./lib/perl5/5.25.2/strict.pm
2573 ./lib/perl5/5.25.2/warnings.pm
2574 ./lib/perl5/5.25.2/i686-linux/File/Glob.pm
2575 ./lib/perl5/5.25.2/feature.pm
2576 ./lib/perl5/5.25.2/XSLoader.pm
2577 ./lib/perl5/5.25.2/i686-linux/auto/File/Glob/Glob.so
8ebf57cf 2578
ab97e755
MB
2579Secondly, for perl-5.10.1, the Debian perl-base package contains 591
2580files, (of which 510 are for lib/unicore) totaling about 3.5MB in its
2581i386 version. Omitting the lib/unicore/* files for brevity, the
2582remaining files are:
8ebf57cf 2583
bfe08c74 2584 /usr/bin/perl
00930d57
AD
2585 /usr/bin/perl5.10.1
2586 /usr/lib/perl/5.10.1/Config.pm
2587 /usr/lib/perl/5.10.1/Config_git.pl
2588 /usr/lib/perl/5.10.1/Config_heavy.pl
2589 /usr/lib/perl/5.10.1/Cwd.pm
2590 /usr/lib/perl/5.10.1/DynaLoader.pm
2591 /usr/lib/perl/5.10.1/Errno.pm
2592 /usr/lib/perl/5.10.1/Fcntl.pm
2593 /usr/lib/perl/5.10.1/File/Glob.pm
2594 /usr/lib/perl/5.10.1/Hash/Util.pm
2595 /usr/lib/perl/5.10.1/IO.pm
2596 /usr/lib/perl/5.10.1/IO/File.pm
2597 /usr/lib/perl/5.10.1/IO/Handle.pm
2598 /usr/lib/perl/5.10.1/IO/Pipe.pm
2599 /usr/lib/perl/5.10.1/IO/Seekable.pm
2600 /usr/lib/perl/5.10.1/IO/Select.pm
2601 /usr/lib/perl/5.10.1/IO/Socket.pm
2602 /usr/lib/perl/5.10.1/IO/Socket/INET.pm
2603 /usr/lib/perl/5.10.1/IO/Socket/UNIX.pm
2604 /usr/lib/perl/5.10.1/List/Util.pm
2605 /usr/lib/perl/5.10.1/POSIX.pm
2606 /usr/lib/perl/5.10.1/Scalar/Util.pm
2607 /usr/lib/perl/5.10.1/Socket.pm
2608 /usr/lib/perl/5.10.1/XSLoader.pm
2609 /usr/lib/perl/5.10.1/auto/Cwd/Cwd.so
2610 /usr/lib/perl/5.10.1/auto/DynaLoader/autosplit.ix
2611 /usr/lib/perl/5.10.1/auto/DynaLoader/dl_expandspec.al
2612 /usr/lib/perl/5.10.1/auto/DynaLoader/dl_find_symbol_anywhere.al
2613 /usr/lib/perl/5.10.1/auto/DynaLoader/dl_findfile.al
2614 /usr/lib/perl/5.10.1/auto/Fcntl/Fcntl.so
2615 /usr/lib/perl/5.10.1/auto/File/Glob/Glob.so
2616 /usr/lib/perl/5.10.1/auto/Hash/Util/Util.so
2617 /usr/lib/perl/5.10.1/auto/IO/IO.so
2618 /usr/lib/perl/5.10.1/auto/List/Util/Util.so
2619 /usr/lib/perl/5.10.1/auto/POSIX/POSIX.so
2620 /usr/lib/perl/5.10.1/auto/POSIX/autosplit.ix
2621 /usr/lib/perl/5.10.1/auto/POSIX/load_imports.al
2622 /usr/lib/perl/5.10.1/auto/Socket/Socket.so
2623 /usr/lib/perl/5.10.1/lib.pm
2624 /usr/lib/perl/5.10.1/re.pm
8ebf57cf 2625 /usr/share/doc/perl/AUTHORS.gz
bfe08c74 2626 /usr/share/doc/perl/Documentation
00930d57 2627 /usr/share/doc/perl/README.Debian
8ebf57cf 2628 /usr/share/doc/perl/changelog.Debian.gz
bfe08c74 2629 /usr/share/doc/perl/copyright
00930d57 2630 /usr/share/lintian/overrides/perl-base
8ebf57cf 2631 /usr/share/man/man1/perl.1.gz
00930d57
AD
2632 /usr/share/man/man1/perl5.10.1.1.gz
2633 /usr/share/perl/5.10.1/AutoLoader.pm
2634 /usr/share/perl/5.10.1/Carp.pm
2635 /usr/share/perl/5.10.1/Carp/Heavy.pm
2636 /usr/share/perl/5.10.1/Exporter.pm
2637 /usr/share/perl/5.10.1/Exporter/Heavy.pm
2638 /usr/share/perl/5.10.1/File/Spec.pm
2639 /usr/share/perl/5.10.1/File/Spec/Unix.pm
2640 /usr/share/perl/5.10.1/FileHandle.pm
2641 /usr/share/perl/5.10.1/Getopt/Long.pm
2642 /usr/share/perl/5.10.1/IPC/Open2.pm
2643 /usr/share/perl/5.10.1/IPC/Open3.pm
2644 /usr/share/perl/5.10.1/SelectSaver.pm
2645 /usr/share/perl/5.10.1/Symbol.pm
2646 /usr/share/perl/5.10.1/Text/ParseWords.pm
2647 /usr/share/perl/5.10.1/Text/Tabs.pm
2648 /usr/share/perl/5.10.1/Text/Wrap.pm
2649 /usr/share/perl/5.10.1/Tie/Hash.pm
2650 /usr/share/perl/5.10.1/attributes.pm
2651 /usr/share/perl/5.10.1/base.pm
2652 /usr/share/perl/5.10.1/bytes.pm
2653 /usr/share/perl/5.10.1/bytes_heavy.pl
2654 /usr/share/perl/5.10.1/constant.pm
2655 /usr/share/perl/5.10.1/fields.pm
2656 /usr/share/perl/5.10.1/integer.pm
2657 /usr/share/perl/5.10.1/locale.pm
2658 /usr/share/perl/5.10.1/overload.pm
2659 /usr/share/perl/5.10.1/strict.pm
2660 /usr/share/perl/5.10.1/unicore/*
2661 /usr/share/perl/5.10.1/utf8.pm
2662 /usr/share/perl/5.10.1/utf8_heavy.pl
2663 /usr/share/perl/5.10.1/vars.pm
2664 /usr/share/perl/5.10.1/warnings.pm
2665 /usr/share/perl/5.10.1/warnings/register.pm
8ebf57cf 2666
e7a3c61b
JH
2667A nice trick to find out the minimal set of Perl library files you will
2668need to run a Perl program is
2669
a0a8d9d3 2670 perl -e 'do "prog.pl"; END { print "$_\n" for sort keys %INC }'
e7a3c61b
JH
2671
2672(this will not find libraries required in runtime, unfortunately, but
2673it's a minimal set) and if you want to find out all the files you can
2674use something like the below
2675
979b4168
KW
2676 strace perl -le 'do "x.pl"' 2>&1 \
2677 | perl -nle '/^open\(\"(.+?)"/ && print $1'
e7a3c61b
JH
2678
2679(The 'strace' is Linux-specific, other similar utilities include 'truss'
2680and 'ktrace'.)
2681
c19ccd8c
RGS
2682=head2 C<-DNO_MATHOMS>
2683
2684If you configure perl with C<-Accflags=-DNO_MATHOMS>, the functions from
2685F<mathoms.c> will not be compiled in. Those functions are no longer used
2686by perl itself; for source compatibility reasons, though, they weren't
2687completely removed.
2688
8e07c86e
AD
2689=head1 DOCUMENTATION
2690
bfb7748a
AD
2691Read the manual entries before running perl. The main documentation
2692is in the pod/ subdirectory and should have been installed during the
8e07c86e 2693build process. Type B<man perl> to get started. Alternatively, you
bfb7748a
AD
2694can type B<perldoc perl> to use the supplied perldoc script. This is
2695sometimes useful for finding things in the library modules.
8e07c86e
AD
2696
2697=head1 AUTHOR
2698
bfb7748a
AD
2699Original author: Andy Dougherty doughera@lafayette.edu , borrowing very
2700heavily from the original README by Larry Wall, with lots of helpful
2701feedback and additions from the perl5-porters@perl.org folks.
fb73857a 2702
f5b3b617
AD
2703If you have problems, corrections, or questions, please see
2704L<"Reporting Problems"> above.
2705
2706=head1 REDISTRIBUTION
2707
2708This document is part of the Perl package and may be distributed under
d6baa268 2709the same terms as perl itself, with the following additional request:
f5b3b617 2710If you are distributing a modified version of perl (perhaps as part of
d6baa268
JH
2711a larger package) please B<do> modify these installation instructions
2712and the contact information to match your distribution.