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