1 If you read this file _as_is_, just ignore the funny characters you see.
2 It is written in the POD format (see F<pod/perlpod.pod>) which is specially
3 designed to be readable as is.
7 INSTALL - Build and Installation guide for perl 5.
11 First, make sure you have an up-to-date version of Perl. If you
12 didn't get your Perl source from CPAN, check the latest version at
13 L<https://www.cpan.org/src/>. Perl uses a version scheme where even-numbered
14 subreleases (like 5.8.x and 5.10.x) are stable maintenance releases and
15 odd-numbered subreleases (like 5.7.x and 5.9.x) are unstable
16 development releases. Development releases should not be used in
17 production environments. Fixes and new features are first carefully
18 tested in development releases and only if they prove themselves to be
19 worthy will they be migrated to the maintenance releases.
21 The basic steps to build and install perl 5 on a Unix system with all
22 the defaults are to run, from a freshly unpacked source tree:
29 Each of these is explained in further detail below.
31 The above commands will install Perl to F</usr/local> (or some other
32 platform-specific directory -- see the appropriate file in F<hints/>.)
33 If that's not okay with you, you can run Configure interactively, by
34 just typing "sh Configure" (without the -de args). You can also specify
35 any prefix location by adding C<"-Dprefix='/some/dir'"> to Configure's args.
36 To explicitly name the perl binary, use the command
37 "make install PERLNAME=myperl".
39 Building perl from source requires an ANSI compliant C compiler.
40 C89 with a minimal subset of C99 features is required. Some other
41 features available in C99 will be probed for and used when found.
43 These options, and many more, are explained in further detail below.
45 If you're building perl from a git repository, you should also consult
46 the documentation in F<pod/perlgit.pod> for information on that special
49 If you have problems, corrections, or questions, please see
50 L<"Reporting Problems"> below.
52 For information on what's new in this release, see the
53 F<pod/perldelta.pod> file. For more information about how to find more
54 specific detail about changes, see the Changes file.
58 This document is written in pod format as an easy way to indicate its
59 structure. The pod format is described in F<pod/perlpod.pod>, but you can
60 read it as is with any pager or editor. Headings and items are marked
61 by lines beginning with '='. The other mark-up used is
63 B<text> embolden text, used for switches, programs or commands
65 L<name> A link (cross reference) to name
68 Although most of the defaults are probably fine for most users,
69 you should probably at least skim through this document before
72 In addition to this file, check if there is a README file specific to
73 your operating system, since it may provide additional or different
74 instructions for building Perl. If there is a hint file for your
75 system (in the F<hints/> directory) you might also want to read it
76 for even more information.
78 For additional information about porting Perl, see the section on
79 L<"Porting information"> below, and look at the files in the F<Porting/>
84 =head2 Changes and Incompatibilities
86 Please see F<pod/perldelta.pod> for a description of the changes and
87 potential incompatibilities introduced with this release. A few of
88 the most important issues are listed below, but you should refer
89 to F<pod/perldelta.pod> for more detailed information.
91 =head3 Compatibility with earlier versions
93 B<WARNING:> This version is not binary compatible with earlier versions
94 of Perl. If you have built extensions (i.e. modules that include C code)
95 using an earlier version of Perl, you will need to rebuild and reinstall
98 Pure perl modules without XS or C code should continue to work fine
99 without reinstallation. See the discussion below on
100 L<"Coexistence with earlier versions of perl 5"> for more details.
102 The standard extensions supplied with Perl will be handled automatically.
104 On a related issue, old modules may possibly be affected by the changes
105 in the Perl language in the current release. Please see
106 F<pod/perldelta.pod> for a description of what's changed. See your
107 installed copy of the perllocal.pod file for a (possibly incomplete)
108 list of locally installed modules. Also see the L<CPAN> module's
109 C<autobundle> function for one way to make a "bundle" of your currently
114 With 5.36 we changed our C compiler baseline requirement from "ANSI C89" to
115 "C89 plus some specific C99 features". We have been using C99 features
116 optionally for some time - we now additionally B<rely> on a few in the core C
117 code and installed headers, which we know work on all supported compilers on
118 all platforms we target. Because earlier versions of Perl still compile with
119 strictly ANSI C89 compilers and there are still a few installations in the
120 wild which use these very old compilers, XS code that targets earlier versions
121 of Perl must not B<rely> on C99 features - that includes XS code in this
122 distribution that is dual life on CPAN. To test that XS code can build on
123 such compilers, some authors configure their perl builds with compiler flags
124 to warn or raise errors on C99 specific features, most often for mixed
125 declarations and code. This obviously will not work if you attempt it for
126 this release - it will not build. However, XS authors should be aware that
133 If you change the C compiler flags in your F<Makefile.PL> or similar to add
134 such warnings or errors, you must now only do it for 5.35.4 or earlier.
138 Do not rely on now being able to use C99 features in your XS code, even for
139 platforms with C99 compilers - some installations of earlier versions of perl
140 are deliberately configured to enforce C89 standards so that locally authored
141 extension code conforms to them. If you choose to require C99 for your code,
142 that's fine, but do so knowing that if you distribute it, some installations
143 of perl are configured to fault C99.
149 Configure will figure out various things about your system. Some
150 things Configure will figure out for itself, other things it will ask
151 you about. To accept the default, just press RETURN. The default is
152 almost always okay. It is normal for some things to be "NOT found",
153 since Configure often searches for many different ways of performing
156 At any Configure prompt, you can type &-d and Configure will use the
157 defaults from then on.
159 After it runs, Configure will perform variable substitution on all the
160 *.SH files and offer to run make depend.
162 The results of a Configure run are stored in the config.sh and Policy.sh
165 =head2 Common Configure options
167 Configure supports a number of useful options. Run
173 Many Configure switches are expressed as C<key=value> pairs, for example:
177 Sometimes the value to be supplied for a switch is a string which contains
178 spaces. In that case, the value needs to be quoted so as to delimit that
179 "shell word" from any following switch. Example:
181 sh ./Configure -des \
182 -Doptimize="-O2 -pipe -fstack-protector -fno-strict-aliasing" \
185 Once Configure has run, you will be able to access configuration data via
186 entries in the file F<config.sh>.
188 config_arg0='./Configure'
189 config_args='-des -Doptimize=-O2 -pipe -fstack-protector -fno-strict-aliasing -Dusedevel'
192 config_arg2='-Doptimize=-O2 -pipe -fstack-protector -fno-strict-aliasing'
193 config_arg3='-Dusedevel'
195 See the F<Porting/Glossary> file for a complete list of
196 Configure variables you can set and their definitions.
202 To compile with gcc, if it's not the default compiler on your
203 system, you should run
205 sh Configure -Dcc=gcc
207 This is the preferred way to specify gcc (or any another alternative
208 compiler) so that the hints files can set appropriate defaults.
210 =item Installation prefix
212 By default, for most systems, perl will be installed in
213 F</usr/local/>{F<bin>, F<lib>, F<man>}. (See L<"Installation Directories">
214 and L<"Coexistence with earlier versions of perl 5"> below for
217 You can specify a different 'prefix' for the default installation
218 directory when Configure prompts you, or by using the Configure command
219 line option C<-Dprefix='/some/directory'>, e.g.
221 sh Configure -Dprefix=/opt/perl
223 If your prefix contains the string "perl", then the suggested
224 directory structure is simplified. For example, if you use
225 C<prefix=/opt/perl>, then Configure will suggest F</opt/perl/lib> instead of
226 F</opt/perl/lib/perl5/>. Again, see L<"Installation Directories"> below
227 for more details. Do not include a trailing slash, (i.e. F</opt/perl/>)
228 or you may experience odd test failures.
230 NOTE: You must not specify an installation directory that is the same
231 as or below your perl source directory. If you do, installperl will
232 attempt infinite recursion.
234 =item F</usr/bin/perl>
236 It may seem obvious, but Perl is useful only when users can easily
237 find it. It's often a good idea to have both F</usr/bin/perl> and
238 F</usr/local/bin/perl> be symlinks to the actual binary. Be especially
239 careful, however, not to overwrite a version of perl supplied by your
240 vendor unless you are sure you know what you are doing. If you insist
241 on replacing your vendor's perl, useful information on how it was
242 configured may be found with
246 (Check the output carefully, however, since this doesn't preserve
247 spaces in arguments to Configure. For that, you have to look carefully
248 at config_arg1, config_arg2, etc.)
250 By default, Configure will not try to link F</usr/bin/perl> to the current
251 version of perl. You can turn on that behavior by running
253 Configure -Dinstallusrbinperl
255 or by answering 'yes' to the appropriate Configure prompt.
257 In any case, system administrators are strongly encouraged to put
258 (symlinks to) perl and its accompanying utilities, such as perldoc,
259 into a directory typically found along a user's PATH, or in another
260 obvious and convenient place.
262 =item Building a development release
264 For development releases (odd subreleases, like 5.9.x) if you want to
265 use Configure -d, you will also need to supply -Dusedevel to Configure,
266 because the default answer to the question "do you really want to
267 Configure a development version?" is "no". The -Dusedevel skips that
272 If you are willing to accept all the defaults, and you want terse
277 =head2 Altering Configure variables for C compiler switches etc.
279 For most users, most of the Configure defaults are fine, or can easily
280 be set on the Configure command line. However, if Configure doesn't
281 have an option to do what you want, you can change Configure variables
282 after the platform hints have been run by using Configure's -A switch.
283 For example, here's how to add a couple of extra flags to C compiler
286 sh Configure -Accflags="-DPERL_EXTERNAL_GLOB -DNO_HASH_SEED"
288 To clarify, those ccflags values are not Configure options; if passed to
289 Configure directly, they won't do anything useful (they will define a
290 variable in config.sh, but without taking any action based upon it).
291 But when passed to the compiler, those flags will activate #ifdefd code.
293 For more help on Configure switches, run
297 =head2 Major Configure-time Build Options
299 There are several different ways to Configure and build perl for your
300 system. For most users, the defaults are sensible and will work.
301 Some users, however, may wish to further customize perl. Here are
302 some of the main things you can change.
306 On some platforms, perl can be compiled with support for threads. To
309 sh Configure -Dusethreads
311 The default is to compile without thread support.
313 Perl used to have two different internal threads implementations. The
314 current model (available internally since 5.6, and as a user-level module
315 since 5.8) is called interpreter-based implementation (ithreads), with
316 one interpreter per thread, and explicit sharing of data. The (deprecated)
317 5.005 version (5005threads) was removed for release 5.10.
319 The 'threads' module is for use with the ithreads implementation. The
320 'Thread' module emulates the old 5005threads interface on top of the
321 current ithreads model.
323 When using threads, perl uses a dynamically-sized buffer for some of
324 the thread-safe library calls, such as those in the getpw*() family.
325 This buffer starts small, but it will keep growing until the result
326 fits. To get a fixed upper limit, you should compile Perl with
327 PERL_REENTRANT_MAXSIZE defined to be the number of bytes you want. One
328 way to do this is to run Configure with
329 C<-Accflags=-DPERL_REENTRANT_MAXSIZE=65536>.
331 =head3 Large file support
333 Since Perl 5.6.0, Perl has supported large files (files larger than
334 2 gigabytes), and in many common platforms like Linux or Solaris this
335 support is on by default.
337 This is both good and bad. It is good in that you can use large files,
338 seek(), stat(), and -s them. It is bad in that if you are interfacing
339 Perl using some extension, the components you are connecting to must also
340 be large file aware: if Perl thinks files can be large but the other
341 parts of the software puzzle do not understand the concept, bad things
344 There's also one known limitation with the current large files
345 implementation: unless you also have 64-bit integers (see the next
346 section), you cannot use the printf/sprintf non-decimal integer formats
347 like C<%x> to print filesizes. You can use C<%d>, though.
349 If you want to compile perl without large file support, use
351 sh Configure -Uuselargefiles
353 =head3 64 bit support
355 If your platform does not run natively at 64 bits, but can simulate
356 them with compiler flags and/or C<long long> or C<int64_t>,
357 you can build a perl that uses 64 bits.
359 There are actually two modes of 64-bitness: the first one is achieved
360 using Configure -Duse64bitint and the second one using Configure
361 -Duse64bitall. The difference is that the first one is minimal and
362 the second one maximal. The first works in more places than the second.
364 The C<use64bitint> option does only as much as is required to get
365 64-bit integers into Perl (this may mean, for example, using "long
366 longs") while your memory may still be limited to 2 gigabytes (because
367 your pointers could still be 32-bit). Note that the name C<64bitint>
368 does not imply that your C compiler will be using 64-bit C<int>s (it
369 might, but it doesn't have to). The C<use64bitint> simply means that
370 you will be able to have 64 bit-wide scalar values.
372 The C<use64bitall> option goes all the way by attempting to switch
373 integers (if it can), longs (and pointers) to being 64-bit. This may
374 create an even more binary incompatible Perl than -Duse64bitint: the
375 resulting executable may not run at all in a 32-bit box, or you may
376 have to reboot/reconfigure/rebuild your operating system to be 64-bit
379 Natively 64-bit systems need neither -Duse64bitint nor -Duse64bitall.
380 On these systems, it might be the default compilation mode, and there
381 is currently no guarantee that passing no use64bitall option to the
382 Configure process will build a 32bit perl. Implementing -Duse32bit*
383 options is planned for a future release of perl.
387 In some systems you may be able to use long doubles to enhance the
388 range and precision of your double precision floating point numbers
389 (that is, Perl's numbers). Use Configure -Duselongdouble to enable
390 this support (if it is available).
392 Note that the exact format and range of long doubles varies:
393 the most common is the x86 80-bit (64 bits of mantissa) format,
394 but there are others, with different mantissa and exponent ranges.
398 You can "Configure -Dusemorebits" to turn on both the 64-bit support
399 and the long double support.
403 One option for more precision is that gcc 4.6 and later have a library
404 called quadmath, which implements the IEEE 754 quadruple precision
405 (128-bit, 113 bits of mantissa) floating point numbers. The library
406 works at least on x86 and ia64 platforms. It may be part of your gcc
407 installation, or you may need to install it separately.
409 With "Configure -Dusequadmath" you can try enabling its use, but note
410 the compiler dependency, you may need to also add "-Dcc=...".
411 At C level the type is called C<__float128> (note, not "long double"),
412 but Perl source knows it as NV. (This is not "long doubles".)
414 =head3 Algorithmic Complexity Attacks on Hashes
416 Perl 5.18 reworked the measures used to secure its hash function
417 from algorithmic complexity attacks. By default it will build with
418 all of these measures enabled along with support for controlling and
419 disabling them via environment variables.
421 You can override various aspects of this feature by defining various
422 symbols during configure. An example might be:
424 sh Configure -Accflags=-DPERL_HASH_FUNC_SIPHASH
426 B<Unless stated otherwise these options are considered experimental or
427 insecure and are not recommended for production use.>
429 Since Perl 5.18 we have included support for multiple hash functions,
430 although from time to time we change which functions we support,
431 and which function is default (currently SBOX+SIPHASH13 on 64 bit builds
432 and SBOX+ZAPHOD32 for 32 bit builds). You can choose a different
433 algorithm by defining one of the following symbols during configure.
434 Note that there are security implications regarding which hash function you choose
435 to use. The functions are listed roughly by how secure they are believed
436 to be, with the one believed to be most secure at release time being PERL_HASH_FUNC_SIPHASH.
438 PERL_HASH_FUNC_SIPHASH
439 PERL_HASH_FUNC_SIPHASH13
440 PERL_HASH_FUNC_ZAPHOD32
442 In addition, these, (or custom hash functions), may be "fronted" by the
443 SBOX32 hash function for keys under a chosen size. This hash function is
444 special in that it has proven theoretical security properties, and is very
445 fast to hash, but which by nature is restricted to a maximum key length,
446 and which has rather expensive setup costs (relatively speaking), both in
447 terms of performance and more importantly in terms of memory. SBOX32
448 requires 1k of storage per character it can hash, and it must populate that
449 storage with 256 32-bit random values as well. In practice the RNG we use
450 for seeding the SBOX32 storage is very efficient, and populating the table
451 required for hashing even fairly long keys is negligible as we only do it
452 during startup. By default we build with SBOX32 enabled, but you can change
455 PERL_HASH_USE_SBOX32_ALSO
457 to zero in configure. By default Perl will use SBOX32 to hash strings 24 bytes
458 or shorter, you can change this length by setting
462 to the desired length, with the maximum length being 256.
464 As of Perl 5.18 the order returned by keys(), values(), and each() is
465 non-deterministic and distinct per hash, and the insert order for
466 colliding keys is randomized as well, and perl allows for controlling this
467 by the PERL_PERTURB_KEYS environment setting. You can disable this behavior
468 entirely with the define
470 PERL_PERTURB_KEYS_DISABLED
472 You can disable the environment variable checks and compile time specify
473 the type of key traversal randomization to be used by defining one of these:
475 PERL_PERTURB_KEYS_RANDOM
476 PERL_PERTURB_KEYS_DETERMINISTIC
478 Since Perl 5.18 the seed used for the hash function is randomly selected
479 at process start, which can be overridden by specifying a seed by setting
480 the PERL_HASH_SEED environment variable.
482 You can change this behavior so that your perl is built with a hard coded
487 Note that if you do this you should modify the code in hv_func.h to specify
488 your own key. In the future this define may be renamed and replaced with one
489 that requires you to specify the key to use.
491 B<NOTE WELL: Perl has never guaranteed any ordering of the hash keys>, and the
492 ordering has already changed several times during the lifetime of Perl
493 5. Also, the ordering of hash keys has always been, and continues to
494 be, affected by the insertion order regardless of whether you build with
495 or without the randomization features. Note that because of this
496 and especially with randomization that the key order of a hash is *undefined*
497 and that things like Data::Dumper, for example, may produce different output
498 between different runs of Perl, since Data::Dumper serializes the key in the
499 native order for the hash. The use of the Data::Dumper C<Sortkeys> option is
500 recommended if you are comparing dumps between different invocations of perl.
502 See L<perlrun/PERL_HASH_SEED> and L<perlrun/PERL_PERTURB_KEYS> for
503 details on the environment variables, and L<perlsec/Algorithmic
504 Complexity Attacks> for further security details.
506 The C<PERL_HASH_SEED> and PERL_PERTURB_KEYS> environment variables can
507 be disabled by building configuring perl with
508 C<-Accflags=-DNO_PERL_HASH_ENV>.
510 The C<PERL_HASH_SEED_DEBUG> environment variable can be disabled by
511 configuring perl with C<-Accflags=-DNO_PERL_HASH_SEED_DEBUG>.
515 Perl can be configured to be 'socksified', that is, to use the SOCKS
516 TCP/IP proxy protocol library. SOCKS is used to give applications
517 access to transport layer network proxies. Perl supports only SOCKS
518 Version 5. The corresponding Configure option is -Dusesocks.
519 You can find more about SOCKS from wikipedia at
520 L<https://en.wikipedia.org/wiki/SOCKS>.
522 =head3 Dynamic Loading
524 By default, Configure will compile perl to use dynamic loading.
525 If you want to force perl to be compiled completely
526 statically, you can either choose this when Configure prompts you or
527 you can use the Configure command line option -Uusedl.
528 With this option, you won't be able to use any new extension
529 (XS) module without recompiling perl itself.
531 =head3 Building a shared Perl library
533 Currently, for most systems, the main perl executable is built by
534 linking the "perl library" libperl.a with perlmain.o, your static
535 extensions, and various extra libraries, such as -lm.
537 On systems that support dynamic loading, it may be possible to
538 replace libperl.a with a shared libperl.so. If you anticipate building
539 several different perl binaries (e.g. by embedding libperl into
540 different programs, or by using the optional compiler extension), then
541 you might wish to build a shared libperl.so so that all your binaries
542 can share the same library.
544 The disadvantages are that there may be a significant performance
545 penalty associated with the shared libperl.so, and that the overall
546 mechanism is still rather fragile with respect to different versions
549 In terms of performance, on my test system (Solaris 2.5_x86) the perl
550 test suite took roughly 15% longer to run with the shared libperl.so.
551 Your system and typical applications may well give quite different
554 The default name for the shared library is typically something like
555 libperl.so.5.8.8 (for Perl 5.8.8), or libperl.so.588, or simply
556 libperl.so. Configure tries to guess a sensible naming convention
557 based on your C library name. Since the library gets installed in a
558 version-specific architecture-dependent directory, the exact name
559 isn't very important anyway, as long as your linker is happy.
561 You can elect to build a shared libperl by
563 sh Configure -Duseshrplib
565 To build a shared libperl, the environment variable controlling shared
566 library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
567 Darwin, LD_LIBRARY_PATH/SHLIB_PATH
568 for HP-UX, LIBPATH for AIX and z/OS, PATH for Cygwin) must be set up to include
569 the Perl build directory because that's where the shared libperl will
570 be created. Configure arranges makefile to have the correct shared
571 library search settings. You can find the name of the environment
572 variable Perl thinks works in your your system by
574 grep ldlibpthname config.sh
576 However, there are some special cases where manually setting the
577 shared library path might be required. For example, if you want to run
578 something like the following with the newly-built but not-yet-installed
581 ./perl -I. -MTestInit t/misc/failing_test.t
585 ./perl -Ilib ~/my_mission_critical_test
587 then you need to set up the shared library path explicitly.
590 LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
592 for Bourne-style shells, or
594 setenv LD_LIBRARY_PATH `pwd`
596 for Csh-style shells. (This procedure may also be needed if for some
597 unexpected reason Configure fails to set up makefile correctly.) (And
598 again, it may be something other than LD_LIBRARY_PATH for you, see above.)
600 You can often recognize failures to build/use a shared libperl from error
601 messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
604 18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
606 There is also an potential problem with the shared perl library if you
607 want to have more than one "flavor" of the same version of perl (e.g.
608 with and without -DDEBUGGING). For example, suppose you build and
609 install a standard Perl 5.10.0 with a shared library. Then, suppose you
610 try to build Perl 5.10.0 with -DDEBUGGING enabled, but everything else
611 the same, including all the installation directories. How can you
612 ensure that your newly built perl will link with your newly built
613 libperl.so.8 rather with the installed libperl.so.8? The answer is
614 that you might not be able to. The installation directory is encoded
615 in the perl binary with the LD_RUN_PATH environment variable (or
616 equivalent ld command-line option). On Solaris, you can override that
617 with LD_LIBRARY_PATH; on Linux, you can only override at runtime via
618 LD_PRELOAD, specifying the exact filename you wish to be used; and on
619 Digital Unix, you can override LD_LIBRARY_PATH by setting the
620 _RLD_ROOT environment variable to point to the perl build directory.
622 In other words, it is generally not a good idea to try to build a perl
623 with a shared library if $archlib/CORE/$libperl already exists from a
626 A good workaround is to specify a different directory for the
627 architecture-dependent library for your -DDEBUGGING version of perl.
628 You can do this by changing all the *archlib* variables in config.sh to
629 point to your new architecture-dependent library.
631 =head3 Environment access
633 Perl often needs to write to the program's environment, such as when
634 C<%ENV> is assigned to. Many implementations of the C library function
635 C<putenv()> leak memory, so where possible perl will manipulate the
636 environment directly to avoid these leaks. The default is now to perform
637 direct manipulation whenever perl is running as a stand alone interpreter,
638 and to call the safe but potentially leaky C<putenv()> function when the
639 perl interpreter is embedded in another application. You can force perl
640 to always use C<putenv()> by compiling with
641 C<-Accflags="-DPERL_USE_SAFE_PUTENV">, see section L</"Altering Configure
642 variables for C compiler switches etc.">. You can force an embedded perl
643 to use direct manipulation by setting C<PL_use_safe_putenv = 0;> after
644 the C<perl_construct()> call.
648 Before File::Glob entered core in 5.6.0 globbing was implemented by shelling
649 out. If the environmental variable PERL_EXTERNAL_GLOB is defined and if the
650 F<csh> shell is available, perl will still do this the old way.
652 =head2 Installation Directories
654 The installation directories can all be changed by answering the
655 appropriate questions in Configure. For convenience, all the installation
656 questions are near the beginning of Configure. Do not include trailing
657 slashes on directory names. At any point during the Configure process,
658 you can answer a question with &-d and Configure will use the defaults
659 from then on. Alternatively, you can
661 grep '^install' config.sh
663 after Configure has run to verify the installation paths.
665 The defaults are intended to be reasonable and sensible for most
666 people building from sources. Those who build and distribute binary
667 distributions or who export perl to a range of systems will probably
668 need to alter them. If you are content to just accept the defaults,
669 you can safely skip the next section.
671 The directories set up by Configure fall into three broad categories.
675 =item Directories for the perl distribution
677 By default, Configure will use the following directories for 5.35.8.
678 $version is the full perl version number, including subversion, e.g.
679 5.12.3, and $archname is a string like sun4-sunos,
680 determined by Configure. The full definitions of all Configure
681 variables are in the file Porting/Glossary.
683 Configure variable Default value
684 $prefixexp /usr/local
685 $binexp $prefixexp/bin
686 $scriptdirexp $prefixexp/bin
687 $privlibexp $prefixexp/lib/perl5/$version
688 $archlibexp $prefixexp/lib/perl5/$version/$archname
689 $man1direxp $prefixexp/man/man1
690 $man3direxp $prefixexp/man/man3
694 $prefixexp is generated from $prefix, with ~ expansion done to convert
695 home directories into absolute paths. Similarly for the other variables
696 listed. As file system calls do not do this, you should always reference
697 the ...exp variables, to support users who build perl in their home
700 Actually, Configure recognizes the SVR3-style
701 /usr/local/man/l_man/man1 directories, if present, and uses those
702 instead. Also, if $prefix contains the string "perl", the library
703 directories are simplified as described below. For simplicity, only
704 the common style is shown here.
706 =item Directories for site-specific add-on files
708 After perl is installed, you may later wish to add modules (e.g. from
709 CPAN) or scripts. Configure will set up the following directories to
710 be used for installing those add-on modules and scripts.
714 $siteprefixexp $prefixexp
715 $sitebinexp $siteprefixexp/bin
716 $sitescriptexp $siteprefixexp/bin
717 $sitelibexp $siteprefixexp/lib/perl5/site_perl/$version
719 $siteprefixexp/lib/perl5/site_perl/$version/$archname
720 $siteman1direxp $siteprefixexp/man/man1
721 $siteman3direxp $siteprefixexp/man/man3
722 $sitehtml1direxp (none)
723 $sitehtml3direxp (none)
725 By default, ExtUtils::MakeMaker will install architecture-independent
726 modules into $sitelib and architecture-dependent modules into $sitearch.
728 =item Directories for vendor-supplied add-on files
730 Lastly, if you are building a binary distribution of perl for
731 distribution, Configure can optionally set up the following directories
732 for you to use to distribute add-on modules.
736 $vendorprefixexp (none)
738 (The next ones are set only if vendorprefix is set.)
740 $vendorbinexp $vendorprefixexp/bin
741 $vendorscriptexp $vendorprefixexp/bin
742 $vendorlibexp $vendorprefixexp/lib/perl5/vendor_perl/$version
744 $vendorprefixexp/lib/perl5/vendor_perl/$version/$archname
745 $vendorman1direxp $vendorprefixexp/man/man1
746 $vendorman3direxp $vendorprefixexp/man/man3
747 $vendorhtml1direxp (none)
748 $vendorhtml3direxp (none)
750 These are normally empty, but may be set as needed. For example,
751 a vendor might choose the following settings:
754 $siteprefix /usr/local
757 This would have the effect of setting the following:
760 $scriptdirexp /usr/bin
761 $privlibexp /usr/lib/perl5/$version
762 $archlibexp /usr/lib/perl5/$version/$archname
763 $man1direxp /usr/man/man1
764 $man3direxp /usr/man/man3
766 $sitebinexp /usr/local/bin
767 $sitescriptexp /usr/local/bin
768 $sitelibexp /usr/local/lib/perl5/site_perl/$version
769 $sitearchexp /usr/local/lib/perl5/site_perl/$version/$archname
770 $siteman1direxp /usr/local/man/man1
771 $siteman3direxp /usr/local/man/man3
773 $vendorbinexp /usr/bin
774 $vendorscriptexp /usr/bin
775 $vendorlibexp /usr/lib/perl5/vendor_perl/$version
776 $vendorarchexp /usr/lib/perl5/vendor_perl/$version/$archname
777 $vendorman1direxp /usr/man/man1
778 $vendorman3direxp /usr/man/man3
780 Note how in this example, the vendor-supplied directories are in the
781 /usr hierarchy, while the directories reserved for the end user are in
782 the /usr/local hierarchy.
784 The entire installed library hierarchy is installed in locations with
785 version numbers, keeping the installations of different versions distinct.
786 However, later installations of Perl can still be configured to search
787 the installed libraries corresponding to compatible earlier versions.
788 See L<"Coexistence with earlier versions of perl 5"> below for more
789 details on how Perl can be made to search older version directories.
791 Of course you may use these directories however you see fit. For
792 example, you may wish to use $siteprefix for site-specific files that
793 are stored locally on your own disk and use $vendorprefix for
794 site-specific files that are stored elsewhere on your organization's
795 network. One way to do that would be something like
797 sh Configure -Dsiteprefix=/usr/local -Dvendorprefix=/usr/share/perl
801 As a final catch-all, Configure also offers an $otherlibdirs
802 variable. This variable contains a colon-separated list of additional
803 directories to add to @INC. By default, it will be empty.
804 Perl will search these directories (including architecture and
805 version-specific subdirectories) for add-on modules and extensions.
807 For example, if you have a bundle of perl libraries from a previous
808 installation, perhaps in a strange place:
810 sh Configure -Dotherlibdirs=/usr/lib/perl5/site_perl/5.8.1
814 There is one other way of adding paths to @INC at perl build time, and
815 that is by setting the APPLLIB_EXP C pre-processor token to a colon-
816 separated list of directories, like this
818 sh Configure -Accflags='-DAPPLLIB_EXP=\"/usr/libperl\"'
820 The directories defined by APPLLIB_EXP get added to @INC I<first>,
821 ahead of any others, and so provide a way to override the standard perl
822 modules should you, for example, want to distribute fixes without
823 touching the perl distribution proper. And, like otherlib dirs,
824 version and architecture specific subdirectories are also searched, if
825 present, at run time. Of course, you can still search other @INC
826 directories ahead of those in APPLLIB_EXP by using any of the standard
827 run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc.
829 =item default_inc_excludes_dot
831 Since version 5.26.0, default perl builds no longer includes C<'.'> as the
832 last element of @INC. The old behaviour can restored using
834 sh Configure -Udefault_inc_excludes_dot
836 Note that this is likely to make programs run under such a perl
837 interpreter less secure.
839 =item usesitecustomize
841 Run-time customization of @INC can be enabled with:
843 sh Configure -Dusesitecustomize
845 which will define USE_SITECUSTOMIZE and $Config{usesitecustomize}.
846 When enabled, this makes perl run F<$sitelibexp/sitecustomize.pl> before
847 anything else. This script can then be set up to add additional
852 By default, man pages will be installed in $man1dir and $man3dir, which
853 are normally /usr/local/man/man1 and /usr/local/man/man3. If you
854 want to use a .3pm suffix for perl man pages, you can do that with
856 sh Configure -Dman3ext=3pm
858 You can disable installation of man pages completely using
860 sh Configure -Dman1dir=none -Dman3dir=none
864 Currently, the standard perl installation does not do anything with
865 HTML documentation, but that may change in the future. Further, some
866 add-on modules may wish to install HTML documents. The html Configure
867 variables listed above are provided if you wish to specify where such
868 documents should be placed. The default is "none", but will likely
869 eventually change to something useful based on user feedback.
873 Some users prefer to append a "/share" to $privlib and $sitelib
874 to emphasize that those directories can be shared among different
877 Note that these are just the defaults. You can actually structure the
878 directories any way you like. They don't even have to be on the same
881 Further details about the installation directories, maintenance and
882 development subversions, and about supporting multiple versions are
883 discussed in L<"Coexistence with earlier versions of perl 5"> below.
885 If you specify a prefix that contains the string "perl", then the
886 library directory structure is slightly simplified. Instead of
887 suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib.
889 Thus, for example, if you Configure with
890 -Dprefix=/opt/perl, then the default library directories for 5.9.0 are
892 Configure variable Default value
893 $privlib /opt/perl/lib/5.9.0
894 $archlib /opt/perl/lib/5.9.0/$archname
895 $sitelib /opt/perl/lib/site_perl/5.9.0
896 $sitearch /opt/perl/lib/site_perl/5.9.0/$archname
898 =head2 Changing the installation directory
900 Configure distinguishes between the directory in which perl (and its
901 associated files) should be installed, and the directory in which it
902 will eventually reside. For most sites, these two are the same; for
903 sites that use AFS, this distinction is handled automatically.
904 However, sites that use package management software such as rpm or
905 dpkg, or users building binary packages for distribution may also
906 wish to install perl into a different directory before moving perl
907 to its final destination. There are two ways to do that:
913 To install perl under the /tmp/perl5 directory, use the following
916 sh Configure -Dinstallprefix=/tmp/perl5
918 (replace /tmp/perl5 by a directory of your choice).
920 Beware, though, that if you go to try to install new add-on
921 modules, they too will get installed in under '/tmp/perl5' if you
922 follow this example. That's why it's usually better to use DESTDIR,
923 as shown in the next section.
927 If you need to install perl on many identical systems, it is convenient
928 to compile it once and create an archive that can be installed on
929 multiple systems. Suppose, for example, that you want to create an
930 archive that can be installed in /opt/perl. One way to do that is by
931 using the DESTDIR variable during C<make install>. The DESTDIR is
932 automatically prepended to all the installation paths. Thus you
935 sh Configure -Dprefix=/opt/perl -des
938 make install DESTDIR=/tmp/perl5
939 cd /tmp/perl5/opt/perl
940 tar cvf /tmp/perl5-archive.tar .
944 =head2 Relocatable @INC
946 To create a relocatable perl tree, use the following command line:
948 sh Configure -Duserelocatableinc
950 Then the paths in @INC (and everything else in %Config) can be
951 optionally located via the path of the perl executable.
953 That means that, if the string ".../" is found at the start of any
954 path, it's substituted with the directory of $^X. So, the relocation
955 can be configured on a per-directory basis, although the default with
956 "-Duserelocatableinc" is that everything is relocated. The initial
957 install is done to the original configured prefix.
959 This option is not compatible with the building of a shared libperl
960 ("-Duseshrplib"), because in that case perl is linked with an hard-coded
961 rpath that points at the libperl.so, that cannot be relocated.
963 =head2 Site-wide Policy settings
965 After Configure runs, it stores a number of common site-wide "policy"
966 answers (such as installation directories) in the Policy.sh file.
967 If you want to build perl on another system using the same policy
968 defaults, simply copy the Policy.sh file to the new system's perl build
969 directory, and Configure will use it. This will work even if Policy.sh was
970 generated for another version of Perl, or on a system with a
971 different architecture and/or operating system. However, in such cases,
972 you should review the contents of the file before using it: for
973 example, your new target may not keep its man pages in the same place
974 as the system on which the file was generated.
976 Alternatively, if you wish to change some or all of those policy
981 to ensure that Configure doesn't re-use them.
983 Further information is in the Policy_sh.SH file itself.
985 If the generated Policy.sh file is unsuitable, you may freely edit it
986 to contain any valid shell commands. It will be run just after the
987 platform-specific hints files.
989 =head2 Disabling older versions of Perl
991 Configure will search for binary compatible versions of previously
992 installed perl binaries in the tree that is specified as target tree,
993 and these will be used as locations to search for modules by the perl
994 being built. The list of perl versions found will be put in the Configure
995 variable inc_version_list.
997 To disable this use of older perl modules, even completely valid pure
998 perl modules, you can specify to not include the paths found:
1000 sh Configure -Dinc_version_list=none ...
1002 If you do want to use modules from some previous perl versions, the
1003 variable must contain a space separated list of directories under the
1004 site_perl directory, and has to include architecture-dependent
1005 directories separately, eg.
1007 sh Configure -Dinc_version_list="5.16.0/x86_64-linux 5.16.0" ...
1009 When using the newer perl, you can add these paths again in the
1010 PERL5LIB environment variable or with perl's -I runtime option.
1012 =head2 Building Perl outside of the source directory
1014 Sometimes it is desirable to build Perl in a directory different from
1015 where the sources are, for example if you want to keep your sources
1016 read-only, or if you want to share the sources between different binary
1017 architectures. You can do this (if your file system supports symbolic
1020 mkdir /tmp/perl/build/directory
1021 cd /tmp/perl/build/directory
1022 sh /path/to/perl/source/Configure -Dmksymlinks ...
1024 This will create in /tmp/perl/build/directory a tree of symbolic links
1025 pointing to files in /path/to/perl/source. The original files are left
1026 unaffected. After Configure has finished you can just say
1032 as usual, and Perl will be built in /tmp/perl/build/directory.
1034 =head2 Building a debugging perl
1036 You can run perl scripts under the perl debugger at any time with
1037 B<perl -d your_script>. If, however, you want to debug perl itself,
1038 you probably want to have support for perl internal debugging code
1039 (activated by adding -DDEBUGGING to ccflags), and/or support for the
1040 system debugger by adding -g to the optimisation flags.
1042 A perl compiled with the DEBUGGING C preprocessor macro will support the
1043 C<-D> perl command-line switch, have assertions enabled, and have many
1044 extra checks compiled into the code; but will execute much more slowly
1045 (typically 2-3x) and the binary will be much larger (typically 2-3x).
1047 As a convenience, debugging code (-DDEBUGGING) and debugging symbols (-g)
1048 can be enabled jointly or separately using a Configure switch, also
1049 (somewhat confusingly) named -DDEBUGGING. For a more eye appealing call,
1050 -DEBUGGING is defined to be an alias for -DDEBUGGING. For both, the -U
1051 calls are also supported, in order to be able to overrule the hints or
1054 Here are the DEBUGGING modes:
1058 =item Configure -DDEBUGGING
1060 =item Configure -DEBUGGING
1062 =item Configure -DEBUGGING=both
1064 Sets both -DDEBUGGING in the ccflags, and adds -g to optimize.
1066 You can actually specify -g and -DDEBUGGING independently (see below),
1067 but usually it's convenient to have both.
1069 =item Configure -DEBUGGING=-g
1071 =item Configure -Doptimize=-g
1073 Adds -g to optimize, but does not set -DDEBUGGING.
1075 (Note: Your system may actually require something like cc -g2.
1076 Check your man pages for cc(1) and also any hint file for your system.)
1078 =item Configure -DEBUGGING=none
1080 =item Configure -UDEBUGGING
1082 Removes -g from optimize, and -DDEBUGGING from ccflags.
1086 If you are using a shared libperl, see the warnings about multiple
1087 versions of perl under L</Building a shared Perl library>.
1089 Note that a perl built with -DDEBUGGING will be much bigger and will run
1090 much, much more slowly than a standard perl.
1092 =head2 DTrace support
1094 On platforms where DTrace is available, it may be enabled by
1095 using the -Dusedtrace option to Configure. DTrace probes are available
1096 for subroutine entry (sub-entry) and subroutine exit (sub-exit). Here's a
1097 simple D script that uses them:
1099 perl$target:::sub-entry, perl$target:::sub-return {
1100 printf("%s %s (%s:%d)\n", probename == "sub-entry" ? "->" : "<-",
1101 copyinstr(arg0), copyinstr(arg1), arg2);
1107 Perl ships with a number of standard extensions. These are contained
1108 in the F<ext/> subdirectory.
1110 By default, Configure will offer to build every extension which appears
1111 to be supported. For example, Configure will offer to build GDBM_File
1112 only if it is able to find the gdbm library.
1114 To disable certain extensions so that they are not built, use the
1115 -Dnoextensions=... and -Donlyextensions=... options. They both accept
1116 a space-separated list of extensions, such as C<IPC/SysV>. The extensions
1118 C<noextensions> are removed from the list of extensions to build, while
1119 the C<onlyextensions> is rather more severe and builds only the listed
1120 extensions. The latter should be used with extreme caution since
1121 certain extensions are used by many other extensions and modules:
1122 examples of such modules include Fcntl and IO. The order of processing
1123 these options is first C<only> (if present), then C<no> (if present).
1125 Of course, you may always run Configure interactively and select only
1126 the extensions you want.
1128 If you unpack any additional extensions in the ext/ directory before
1129 running Configure, then Configure will offer to build those additional
1130 extensions as well. Most users probably shouldn't have to do this --
1131 it is usually easier to build additional extensions later after perl
1132 has been installed. However, if you wish to have those additional
1133 extensions statically linked into the perl binary, then this offers a
1134 convenient way to do that in one step. (It is not necessary, however;
1135 you can build and install extensions just fine even if you don't have
1136 dynamic loading. See lib/ExtUtils/MakeMaker.pm for more details.)
1137 Another way of specifying extra modules is described in
1138 L<"Adding extra modules to the build"> below.
1140 If you re-use an old config.sh but change your system (e.g. by
1141 adding libgdbm) Configure will still offer your old choices of extensions
1142 for the default answer, but it will also point out the discrepancy to
1145 =head2 Including locally-installed libraries
1147 Perl comes with interfaces to number of libraries, including threads,
1148 dbm, ndbm, gdbm, and Berkeley db. For the *db* extension, if
1149 Configure can find the appropriate header files and libraries, it will
1150 automatically include that extension. The threading extension needs
1151 to be specified explicitly (see L</Threads>).
1153 Those libraries are not distributed with perl. If your header (.h) files
1154 for those libraries are not in a directory normally searched by your C
1155 compiler, then you will need to include the appropriate -I/your/directory
1156 option when prompted by Configure. If your libraries are not in a
1157 directory normally searched by your C compiler and linker, then you will
1158 need to include the appropriate -L/your/directory option when prompted
1159 by Configure. See the examples below.
1165 =item gdbm in /usr/local
1167 Suppose you have gdbm and want Configure to find it and build the
1168 GDBM_File extension. This example assumes you have gdbm.h
1169 installed in /usr/local/include/gdbm.h and libgdbm.a installed in
1170 /usr/local/lib/libgdbm.a. Configure should figure all the
1171 necessary steps out automatically.
1173 Specifically, when Configure prompts you for flags for
1174 your C compiler, you should include -I/usr/local/include, if it's
1175 not here yet. Similarly, when Configure prompts you for linker flags,
1176 you should include -L/usr/local/lib.
1178 If you are using dynamic loading, then when Configure prompts you for
1179 linker flags for dynamic loading, you should again include
1182 Again, this should all happen automatically. This should also work if
1183 you have gdbm installed in any of (/usr/local, /opt/local, /usr/gnu,
1184 /opt/gnu, /usr/GNU, or /opt/GNU).
1186 =item BerkeleyDB in /usr/local/BerkeleyDB
1188 The version of BerkeleyDB distributed by Oracle installs in a
1189 version-specific directory by default, typically something like
1190 /usr/local/BerkeleyDB.4.7. To have Configure find that, you need to add
1191 -I/usr/local/BerkeleyDB.4.7/include to cc flags, as in the previous
1192 example, and you will also have to take extra steps to help Configure
1193 find -ldb. Specifically, when Configure prompts you for library
1194 directories, add /usr/local/BerkeleyDB.4.7/lib to the list. Also, you
1195 will need to add appropriate linker flags to tell the runtime linker
1196 where to find the BerkeleyDB shared libraries.
1198 It is possible to specify this from the command line (all on one
1202 -Dlocincpth='/usr/local/BerkeleyDB.4.7/include \
1203 /usr/local/include' \
1204 -Dloclibpth='/usr/local/BerkeleyDB.4.7/lib /usr/local/lib' \
1205 -Aldflags='-R/usr/local/BerkeleyDB.4.7/lib'
1207 locincpth is a space-separated list of include directories to search.
1208 Configure will automatically add the appropriate -I directives.
1210 loclibpth is a space-separated list of library directories to search.
1211 Configure will automatically add the appropriate -L directives.
1213 The addition to ldflags is so that the dynamic linker knows where to find
1214 the BerkeleyDB libraries. For Linux and Solaris, the -R option does that.
1215 Other systems may use different flags. Use the appropriate flag for your
1220 =head2 Specifying a logical root directory
1222 If you are cross-compiling, or are using a compiler which has it's own
1223 headers and libraries in a nonstandard location, and your compiler
1224 understands the C<--sysroot> option, you can use the C<-Dsysroot> option
1225 to specify the logical root directory under which all libraries and
1226 headers are searched for. This patch adjusts Configure to search under
1227 $sysroot, instead of /.
1229 --sysroot is added to ccflags and friends so that make in
1230 ExtUtils::MakeMaker, and other extensions, will use it.
1232 =head2 Overriding an old config.sh
1234 If you want to use an old config.sh produced by a previous run of
1235 Configure, but override some of the items with command line options, you
1236 need to use B<Configure -O>.
1238 =head2 GNU-style configure
1240 If you prefer the GNU-style configure command line interface, you can
1241 use the supplied configure.gnu command, e.g.
1243 CC=gcc ./configure.gnu
1245 The configure.gnu script emulates a few of the more common configure
1248 ./configure.gnu --help
1252 (The file is called configure.gnu to avoid problems on systems
1253 that would not distinguish the files "Configure" and "configure".)
1255 =head2 Malloc Issues
1257 Perl relies heavily on malloc(3) to grow data structures as needed,
1258 so perl's performance can be noticeably affected by the performance of
1259 the malloc function on your system. The perl source is shipped with a
1260 version of malloc that has been optimized for the typical requests from
1261 perl, so there's a chance that it may be both faster and use less memory
1262 than your system malloc.
1264 However, if your system already has an excellent malloc, or if you are
1265 experiencing difficulties with extensions that use third-party libraries
1266 that call malloc, then you should probably use your system's malloc.
1267 (Or, you might wish to explore the malloc flags discussed below.)
1271 =item Using the system malloc
1273 To build without perl's malloc, you can use the Configure command
1275 sh Configure -Uusemymalloc
1277 or you can answer 'n' at the appropriate interactive Configure prompt.
1279 Note that Perl's malloc isn't always used by default; that actually
1280 depends on your system. For example, on Linux and FreeBSD (and many more
1281 systems), Configure chooses to use the system's malloc by default.
1282 See the appropriate file in the F<hints/> directory to see how the
1285 =item -DPERL_POLLUTE_MALLOC
1287 NOTE: This flag is enabled automatically on some platforms if you just
1288 run Configure to accept all the defaults.
1290 Perl's malloc family of functions are normally called Perl_malloc(),
1291 Perl_realloc(), Perl_calloc() and Perl_mfree().
1292 These names do not clash with the system versions of these functions.
1294 If this flag is enabled, however, Perl's malloc family of functions
1295 will have the same names as the system versions. This may be required
1296 sometimes if you have libraries that like to free() data that may have
1297 been allocated by Perl_malloc() and vice versa.
1299 Note that enabling this option may sometimes lead to duplicate symbols
1300 from the linker for malloc et al. In such cases, the system probably
1301 does not allow its malloc functions to be fully replaced with custom
1304 =item -DPERL_DEBUGGING_MSTATS
1306 This flag enables debugging mstats, which is required to use the
1307 Devel::Peek::mstat() function. You cannot enable this unless you are
1308 using Perl's malloc, so a typical Configure command would be
1310 sh Configure -Accflags=-DPERL_DEBUGGING_MSTATS -Dusemymalloc
1312 to enable this option.
1316 =head2 What if it doesn't work?
1318 If you run into problems, try some of the following ideas.
1319 If none of them help, then see L<"Reporting Problems"> below.
1323 =item Running Configure Interactively
1325 If Configure runs into trouble, remember that you can always run
1326 Configure interactively so that you can check (and correct) its
1329 All the installation questions have been moved to the top, so you don't
1330 have to wait for them. Once you've handled them (and your C compiler and
1331 flags) you can type &-d at the next Configure prompt and Configure
1332 will use the defaults from then on.
1334 If you find yourself trying obscure command line incantations and
1335 config.over tricks, I recommend you run Configure interactively
1336 instead. You'll probably save yourself time in the long run.
1340 Hint files tell Configure about a number of things:
1346 The peculiarities or conventions of particular platforms -- non-standard
1347 library locations and names, default installation locations for binaries,
1352 The deficiencies of the platform -- for example, library functions that,
1353 although present, are too badly broken to be usable; or limits on
1354 resources that are generously available on most platforms.
1358 How best to optimize for the platform, both in terms of binary size
1359 and/or speed, and for Perl feature support. Because of wide variations in
1360 the implementation of shared libraries and of threading, for example,
1361 Configure often needs hints in order to be able to use these features.
1365 The perl distribution includes many system-specific hints files
1366 in the hints/ directory. If one of them matches your system, Configure
1367 will offer to use that hint file. Unless you have a very good reason
1368 not to, you should accept its offer.
1370 Several of the hint files contain additional important information.
1371 If you have any problems, it is a good idea to read the relevant hint
1372 file for further information. See hints/solaris_2.sh for an extensive
1373 example. More information about writing good hints is in the
1374 hints/README.hints file, which also explains hint files known as
1377 Note that any hint file is read before any Policy file, meaning that
1378 Policy overrides hints -- see L</Site-wide Policy settings>.
1382 If you are re-using an old config.sh, it's possible that Configure
1383 detects different values from the ones specified in this file. You will
1384 almost always want to keep the previous value, unless you have changed
1385 something on your system.
1387 For example, suppose you have added libgdbm.a to your system
1388 and you decide to reconfigure perl to use GDBM_File. When you run
1389 Configure again, you will need to add -lgdbm to the list of libraries.
1390 Now, Configure will find your gdbm include file and library and will
1393 *** WHOA THERE!!! ***
1394 The previous value for $i_gdbm on this machine was "undef"!
1395 Keep the previous value? [y]
1397 In this case, you do not want to keep the previous value, so you
1398 should answer 'n'. (You'll also have to manually add GDBM_File to
1399 the list of dynamic extensions to build.)
1401 =item Changing Compilers
1403 If you change compilers or make other significant changes, you should
1404 probably not re-use your old config.sh. Simply remove it or
1405 rename it, then rerun Configure with the options you want to use.
1407 =item Propagating your changes to config.sh
1409 If you make any changes to config.sh, you should propagate
1410 them to all the .SH files by running
1414 You will then have to rebuild by running
1419 =item config.over and config.arch
1421 You can also supply a shell script config.over to override
1422 Configure's guesses. It will get loaded up at the very end, just
1423 before config.sh is created. You have to be careful with this,
1424 however, as Configure does no checking that your changes make sense.
1425 This file is usually good for site-specific customizations.
1427 There is also another file that, if it exists, is loaded before the
1428 config.over, called config.arch. This file is intended to be per
1429 architecture, not per site, and usually it's the architecture-specific
1430 hints file that creates the config.arch.
1434 Many of the system dependencies are contained in config.h.
1435 Configure builds config.h by running the config_h.SH script.
1436 The values for the variables are taken from config.sh.
1438 If there are any problems, you can edit config.h directly. Beware,
1439 though, that the next time you run Configure, your changes will be
1444 If you have any additional changes to make to the C compiler command
1445 line, they can be made in cflags.SH. For instance, to turn off the
1446 optimizer on toke.c, find the switch structure marked 'or customize here',
1447 and add a line for toke.c ahead of the catch-all *) so that it now reads:
1452 toke) optimize='-g' ;;
1455 You should not edit the generated file cflags directly, as your changes
1456 will be lost the next time you run Configure, or if you edit config.sh.
1458 To explore various ways of changing ccflags from within a hint file,
1459 see the file hints/README.hints.
1461 To change the C flags for all the files, edit config.sh and change either
1462 $ccflags or $optimize, and then re-run
1469 If you don't have sh, you'll have to copy the sample file
1470 Porting/config.sh to config.sh and edit your config.sh to reflect your
1471 system's peculiarities. See Porting/pumpkin.pod for more information.
1472 You'll probably also have to extensively modify the extension building
1475 =item Porting information
1477 Specific information for the OS/2, Plan 9, VMS and Win32 ports is in the
1478 corresponding README files and subdirectories. Additional information,
1479 including a glossary of all those config.sh variables, is in the Porting
1480 subdirectory. Porting/Glossary should especially come in handy.
1482 Ports for other systems may also be available. You should check out
1483 L<https://www.cpan.org/ports> for current information on ports to
1484 various other operating systems.
1486 If you plan to port Perl to a new architecture, study carefully the
1487 section titled "Philosophical Issues in Patching and Porting Perl"
1488 in the file Porting/pumpkin.pod and the file pod/perlgit.pod.
1489 Study also how other non-UNIX ports have solved problems.
1493 =head2 Adding extra modules to the build
1495 You can specify extra modules or module bundles to be fetched from the
1496 CPAN and installed as part of the Perl build. Either use the -Dextras=...
1497 command line parameter to Configure, for example like this:
1499 Configure -Dextras="Bundle::LWP DBI"
1501 or answer first 'y' to the question 'Install any extra modules?' and
1502 then answer "Bundle::LWP DBI" to the 'Extras?' question.
1503 The module or the bundle names are as for the CPAN module 'install'
1504 command. This will only work if those modules are to be built as dynamic
1505 extensions. If you wish to include those extra modules as static
1506 extensions, see L<"Extensions"> above.
1508 Notice that because the CPAN module will be used to fetch the extra
1509 modules, you will need access to the CPAN, either via the Internet,
1510 or via a local copy such as a CD-ROM or a local CPAN mirror. If you
1511 do not, using the extra modules option will die horribly.
1513 Also notice that you yourself are responsible for satisfying any extra
1514 dependencies such as external headers or libraries BEFORE trying the
1515 build. For example: you will need to have the Foo database specific
1516 headers and libraries installed for the DBD::Foo module. The Configure
1517 process or the Perl build process will not help you with these.
1521 suidperl was an optional component of earlier releases of perl. It is no
1522 longer available. Instead, use a tool specifically designed to handle
1523 changes in privileges, such as B<sudo>.
1527 This will look for all the includes. The output is stored in makefile.
1528 The only difference between Makefile and makefile is the dependencies at
1529 the bottom of makefile. If you have to make any changes, you should edit
1530 makefile, not Makefile, since the Unix make command reads makefile first.
1531 (On non-Unix systems, the output may be stored in a different file.
1532 Check the value of $firstmakefile in your config.sh if in doubt.)
1534 Configure will offer to do this step for you, so it isn't listed
1539 This will attempt to make perl in the current directory.
1541 =head2 Expected errors
1543 These error reports are normal, and can be ignored:
1546 make: [extra.pods] Error 1 (ignored)
1548 make: [extras.make] Error 1 (ignored)
1550 =head2 What if it doesn't work?
1552 If you can't compile successfully, try some of the following ideas.
1553 If none of them help, and careful reading of the error message and
1554 the relevant manual pages on your system doesn't help,
1555 then see L<"Reporting Problems"> below.
1561 If you used a hint file, try reading the comments in the hint file
1562 for further tips and information.
1566 If you can successfully build miniperl, but the process crashes
1567 during the building of extensions, run
1571 to test your version of miniperl.
1575 If you have any locale-related environment variables set, try unsetting
1576 them. I have some reports that some versions of IRIX hang while
1577 running B<./miniperl configpm> with locales other than the C locale.
1578 See the discussion under L<"make test"> below about locales and the
1579 whole L<perllocale/"LOCALE PROBLEMS"> section in the file
1580 pod/perllocale.pod. The latter is especially useful if you see something
1583 perl: warning: Setting locale failed.
1584 perl: warning: Please check that your locale settings:
1587 are supported and installed on your system.
1588 perl: warning: Falling back to the standard locale ("C").
1592 =item other environment variables
1594 Configure does not check for environment variables that can sometimes
1595 have a major influence on how perl is built or tested. For example,
1596 OBJECT_MODE on AIX determines the way the compiler and linker deal with
1597 their objects, but this is a variable that only influences build-time
1598 behaviour, and should not affect the perl scripts that are eventually
1599 executed by the perl binary. Other variables, like PERL_UNICODE,
1600 PERL5LIB, and PERL5OPT will influence the behaviour of the test suite.
1601 So if you are getting strange test failures, you may want to try
1602 retesting with the various PERL variables unset.
1604 =item LD_LIBRARY_PATH
1606 If you run into dynamic loading problems, check your setting of
1607 the LD_LIBRARY_PATH environment variable (or on some systems the equivalent
1608 with a different name, see L</Building a shared Perl library>). If you're
1609 creating a static Perl library (libperl.a rather than libperl.so) it should
1610 build fine with LD_LIBRARY_PATH unset, though that may depend on details of
1615 If Configure seems to be having trouble finding library functions,
1616 try not using nm extraction. You can do this from the command line
1619 sh Configure -Uusenm
1621 or by answering the nm extraction question interactively.
1622 If you have previously run Configure, you should not reuse your old
1625 =item umask not found
1627 If the build processes encounters errors relating to umask(), the problem
1628 is probably that Configure couldn't find your umask() system call.
1629 Check your config.sh. You should have d_umask='define'. If you don't,
1630 this is probably the L<"nm extraction"> problem discussed above. Also,
1631 try reading the hints file for your system for further information.
1635 If you run into problems relating to do_aspawn or do_spawn, the
1636 problem is probably that Configure failed to detect your system's
1637 fork() function. Follow the procedure in the previous item
1638 on L<"nm extraction">.
1640 =item __inet_* errors
1642 If you receive unresolved symbol errors during Perl build and/or test
1643 referring to __inet_* symbols, check to see whether BIND 8.1 is
1644 installed. It installs a /usr/local/include/arpa/inet.h that refers to
1645 these symbols. Versions of BIND later than 8.1 do not install inet.h
1646 in that location and avoid the errors. You should probably update to a
1647 newer version of BIND (and remove the files the old one left behind).
1648 If you can't, you can either link with the updated resolver library
1649 provided with BIND 8.1 or rename /usr/local/bin/arpa/inet.h during the
1650 Perl build and test process to avoid the problem.
1652 =item .*_r() prototype NOT found
1654 On a related note, if you see a bunch of complaints like the above about
1655 reentrant functions -- specifically networking-related ones -- being
1656 present but without prototypes available, check to see if BIND 8.1 (or
1657 possibly other BIND 8 versions) is (or has been) installed. They install
1658 header files such as netdb.h into places such as /usr/local/include (or
1659 into another directory as specified at build/install time), at least
1660 optionally. Remove them or put them in someplace that isn't in the C
1661 preprocessor's header file include search path (determined by -I options
1662 plus defaults, normally /usr/include).
1664 =item #error "No DATAMODEL_NATIVE specified"
1666 This is a common error when trying to build perl on Solaris 2.6 with a
1667 gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files
1668 changed, so you need to update your gcc installation. You can either
1669 rerun the fixincludes script from gcc or take the opportunity to
1670 update your gcc installation.
1674 If you can't compile successfully, try turning off your compiler's
1675 optimizer. Edit config.sh and change the line
1683 then propagate your changes with B<sh Configure -S> and rebuild
1684 with B<make depend; make>.
1686 =item Missing functions and Undefined symbols
1688 If the build of miniperl fails with a long list of missing functions or
1689 undefined symbols, check the libs variable in the config.sh file. It
1690 should look something like
1692 libs='-lsocket -lnsl -ldl -lm -lc'
1694 The exact libraries will vary from system to system, but you typically
1695 need to include at least the math library -lm. Normally, Configure
1696 will suggest the correct defaults. If the libs variable is empty, you
1697 need to start all over again. Run
1701 and start from the very beginning. This time, unless you are sure of
1702 what you are doing, accept the default list of libraries suggested by
1705 If the libs variable is missing -lm, there is a chance that libm.so.1
1706 is available, but the required (symbolic) link to libm.so is missing.
1707 (same could be the case for other libraries like libcrypt.so). You
1708 should check your installation for packages that create that link, and
1709 if no package is installed that supplies that link or you cannot install
1710 them, make the symbolic link yourself e.g.:
1712 $ rpm -qf /usr/lib64/libm.so
1713 glibc-devel-2.15-22.17.1.x86_64
1714 $ ls -lgo /usr/lib64/libm.so
1715 lrwxrwxrwx 1 16 Jan 7 2013 /usr/lib64/libm.so -> /lib64/libm.so.6
1719 $ sudo ln -s /lib64/libm.so.6 /lib64/libm.so
1721 If the libs variable looks correct, you might have the
1722 L<"nm extraction"> problem discussed above.
1724 If you still have missing routines or undefined symbols, you probably
1725 need to add some library or other, make a symbolic link like described
1726 above, or you need to undefine some feature that Configure thought was
1727 there but is defective or incomplete. If you used a hint file, see if
1728 it has any relevant advice. You can also look through config.h
1729 for likely suspects.
1733 Some compilers will not compile or optimize the larger files (such as
1734 toke.c) without some extra switches to use larger jump offsets or
1735 allocate larger internal tables. You can customize the switches for
1736 each file in cflags.SH. It's okay to insert rules for specific files
1737 into makefile since a default rule only takes effect in the absence of a
1740 =item Missing dbmclose
1742 SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
1743 that includes libdbm.nfs (which includes dbmclose()) may be available.
1745 =item error: too few arguments to function 'dbmclose'
1747 Building ODBM_File on some (Open)SUSE distributions might run into this
1748 error, as the header file is broken. There are two ways to deal with this
1750 1. Disable the use of ODBM_FILE
1752 sh Configure ... -Dnoextensions=ODBM_File
1754 2. Fix the header file, somewhat like this:
1756 --- a/usr/include/dbm.h 2010-03-24 08:54:59.000000000 +0100
1757 +++ b/usr/include/dbm.h 2010-03-24 08:55:15.000000000 +0100
1758 @@ -59,4 +59,4 @@ extern datum firstkey __P((void));
1760 extern datum nextkey __P((datum key));
1762 -extern int dbmclose __P((DBM *));
1763 +extern int dbmclose __P((void));
1765 =item Warning (mostly harmless): No library found for -lsomething
1767 If you see such a message during the building of an extension, but
1768 the extension passes its tests anyway (see L<"make test"> below),
1769 then don't worry about the warning message. The extension
1770 Makefile.PL goes looking for various libraries needed on various
1771 systems; few systems will need all the possible libraries listed.
1772 Most users will see warnings for the ones they don't have. The
1773 phrase 'mostly harmless' is intended to reassure you that nothing
1774 unusual is happening, and the build process is continuing.
1776 On the other hand, if you are building GDBM_File and you get the
1779 Warning (mostly harmless): No library found for -lgdbm
1781 then it's likely you're going to run into trouble somewhere along
1782 the line, since it's hard to see how you can use the GDBM_File
1783 extension without the -lgdbm library.
1785 It is true that, in principle, Configure could have figured all of
1786 this out, but Configure and the extension building process are not
1787 quite that tightly coordinated.
1789 =item sh: ar: not found
1791 This is a message from your shell telling you that the command 'ar'
1792 was not found. You need to check your PATH environment variable to
1793 make sure that it includes the directory with the 'ar' command. This
1794 is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
1797 =item db-recno failure on tests 51, 53 and 55
1799 Old versions of the DB library (including the DB library which comes
1800 with FreeBSD 2.1) had broken handling of recno databases with modified
1801 bval settings. Upgrade your DB library or OS.
1803 =item Bad arg length for semctl, is XX, should be ZZZ
1805 If you get this error message from the F<cpan/IPC-SysV/t/sem.t> test, your
1806 System V IPC may be broken. The XX typically is 20, and that is what ZZZ
1807 also should be. Consider upgrading your OS, or reconfiguring your OS
1808 to include the System V semaphores.
1810 =item cpan/IPC-SysV/t/sem........semget: No space left on device
1812 Either your account or the whole system has run out of semaphores. Or
1813 both. Either list the semaphores with "ipcs" and remove the unneeded
1814 ones (which ones these are depends on your system and applications)
1815 with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
1820 If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
1821 tools you may be in for some trouble. For example creating archives
1822 with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
1823 may lead into linking problems. Either recompile your GNU binutils
1824 under your current operating system release, or modify your PATH not
1825 to include the GNU utils before running Configure, or specify the
1826 vendor-supplied utilities explicitly to Configure, for example by
1827 Configure -Dar=/bin/ar.
1829 =item THIS PACKAGE SEEMS TO BE INCOMPLETE
1831 The F<Configure> program has not been able to find all the files which
1832 make up the complete Perl distribution. You may have a damaged source
1833 archive file (in which case you may also have seen messages such as
1834 C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on
1835 archive file>), or you may have obtained a structurally-sound but
1836 incomplete archive. In either case, try downloading again from the
1837 official site named at the start of this document. If you do find
1838 that any site is carrying a corrupted or incomplete source code
1839 archive, please report it to the site's maintainer.
1841 =item invalid token: ##
1843 You are using a non-ANSI-compliant C compiler. To compile Perl, you
1844 need to use a compiler that supports ANSI C. If there is a README
1845 file for your system, it may have further details on your compiler
1850 Some additional things that have been reported:
1852 Genix may need to use libc rather than libc_s, or #undef VARARGS.
1854 NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
1856 UTS may need one or more of -K or -g, and #undef LSTAT.
1858 FreeBSD can fail the F<cpan/IPC-SysV/t/sem.t> test if SysV IPC has not been
1859 configured in the kernel. Perl tries to detect this, though, and
1860 you will get a message telling you what to do.
1862 Building Perl on a system that has also BIND (headers and libraries)
1863 installed may run into troubles because BIND installs its own netdb.h
1864 and socket.h, which may not agree with the operating system's ideas of
1865 the same files. Similarly, including -lbind may conflict with libc's
1866 view of the world. You may have to tweak -Dlocincpth and -Dloclibpth
1871 =head2 Cross-compilation
1873 Perl can be cross-compiled. It is just not trivial, cross-compilation
1874 rarely is. Perl is routinely cross-compiled for several platforms: as of
1875 June 2019, these include Android, Blackberry 10,
1876 ARM Linux, and Solaris. Previous versions of
1877 Perl also provided support for Open Zaurus, Symbian, and
1878 the IBM OS/400, but it's unknown if those ports are still functional.
1879 These platforms are known as the B<target> platforms, while the systems
1880 where the compilation takes place are the B<host> platforms.
1882 What makes the situation difficult is that first of all,
1883 cross-compilation environments vary significantly in how they are set
1884 up and used, and secondly because the primary way of configuring Perl
1885 (using the rather large Unix-tool-dependent Configure script) is not
1886 awfully well suited for cross-compilation. However, starting from
1887 version 5.18.0, the Configure script also knows two ways of supporting
1888 cross-compilation, so please keep reading.
1890 See the following files for more information about compiling Perl for
1891 the particular platforms:
1897 L<"Cross-compilation" in README.android or
1898 perlandroid|perlandroid/Cross-compilation>
1902 L<"Cross-compilation" in README.qnx or perlqnx|perlqnx/Cross-compilation>
1906 L<"CROSS-COMPILATION" in README.solaris or
1907 perlsolaris|perlsolaris/CROSS-COMPILATION>
1911 This document; See below.
1915 Packaging and transferring either the core Perl modules or CPAN
1916 modules to the target platform is also left up to the each
1917 cross-compilation environment. Often the cross-compilation target
1918 platforms are somewhat limited in diskspace: see the section
1919 L</Minimizing the Perl installation> to learn more of the minimal set
1920 of files required for a functional Perl installation.
1922 For some cross-compilation environments the Configure option
1923 C<-Dinstallprefix=...> might be handy, see L</Changing the installation
1926 About the cross-compilation support of Configure: There's two forms.
1927 The more common one requires some way of transferring and running
1928 executables in the target system, such as an ssh connection; this is the
1929 C<./Configure -Dusecrosscompile -Dtargethost=...> route. The second
1930 method doesn't need access to the target system, but requires you to
1931 provide a config.sh, and a canned Makefile; the rest of this section
1932 describes the former.
1934 This cross-compilation setup of Configure has successfully been used in
1935 a wide variety of setups, such as a 64-bit OS X host for an Android ARM
1936 target, or an amd64 Linux host targeting x86 Solaris, or even Windows.
1938 To run Configure in cross-compilation mode the basic switch that
1939 has to be used is C<-Dusecrosscompile>:
1941 sh ./Configure -des -Dusecrosscompile -D...
1943 This will make the cpp symbol USE_CROSS_COMPILE and the %Config
1944 symbol C<usecrosscompile> available.
1946 During the Configure and build, certain helper scripts will be created
1947 into the Cross/ subdirectory. The scripts are used to execute a
1948 cross-compiled executable, and to transfer files to and from the
1949 target host. The execution scripts are named F<run-*> and the
1950 transfer scripts F<to-*> and F<from-*>. The part after the dash is
1951 the method to use for remote execution and transfer: by default the
1952 methods are B<ssh> and B<scp>, thus making the scripts F<run-ssh>,
1953 F<to-scp>, and F<from-scp>.
1955 To configure the scripts for a target host and a directory (in which
1956 the execution will happen and which is to and from where the transfer
1957 happens), supply Configure with
1959 -Dtargethost=so.me.ho.st -Dtargetdir=/tar/get/dir
1961 The targethost is what e.g. ssh will use as the hostname, the targetdir
1962 must exist (the scripts won't create it), the targetdir defaults to /tmp.
1963 You can also specify a username to use for ssh/rsh logins
1967 but in case you don't, "root" will be used. Similarly, you can specify
1968 a non-standard (i.e. not 22) port for the connection, if applicable,
1973 If the name of C<cc> has the usual GNU C semantics for cross
1974 compilers, that is, CPU-OS-gcc, the target architecture (C<targetarch>),
1975 plus names of the C<ar>, C<nm>, and C<ranlib> will also be automatically
1976 chosen to be CPU-OS-ar and so on.
1977 (The C<ld> requires more thought and will be chosen later by Configure
1978 as appropriate). This will also aid in guessing the proper
1979 operating system name for the target, which has other repercussions, like
1980 better defaults and possibly critical fixes for the platform. If
1981 Configure isn't guessing the OS name properly, you may need to either add
1982 a hint file redirecting Configure's guess, or modify Configure to make
1985 If your compiler doesn't follow that convention, you will also need to
1986 specify which target environment to use, as well as C<ar> and friends:
1988 -Dtargetarch=arm-linux
1992 Additionally, a cross-compilation toolchain will usually install it's own
1993 logical system root somewhere -- that is, it'll create a directory
1994 somewhere which includes subdirectories like C<'include'> or C<'lib'>. For
1995 example, you may end up with F</skiff/local/arm-linux>, where
1996 F</skiff/local/arm-linux/bin> holds the binaries for cross-compilation,
1997 F</skiff/local/arm-linux/include> has the headers, and
1998 F</skiff/local/arm-linux/lib> has the library files.
1999 If this is the case, and you are using a compiler that understands
2000 C<--sysroot>, like gcc or clang, you'll want to specify the
2001 C<-Dsysroot> option for Configure:
2003 -Dsysroot=/skiff/local/arm-linux
2005 However, if your don't have a suitable directory to pass to C<-Dsysroot>,
2006 you will also need to specify which target environment to use:
2008 -Dusrinc=/skiff/local/arm-linux/include
2009 -Dincpth=/skiff/local/arm-linux/include
2010 -Dlibpth=/skiff/local/arm-linux/lib
2012 In addition to the default execution/transfer methods you can also
2013 choose B<rsh> for execution, and B<rcp> or B<cp> for transfer,
2016 -Dtargetrun=rsh -Dtargetto=rcp -Dtargetfrom=cp
2018 Putting it all together:
2020 sh ./Configure -des -Dusecrosscompile \
2021 -Dtargethost=so.me.ho.st \
2022 -Dtargetdir=/tar/get/dir \
2024 -Dtargetarch=arm-linux \
2025 -Dcc=arm-linux-gcc \
2026 -Dsysroot=/skiff/local/arm-linux \
2029 or if you are happy with the defaults:
2031 sh ./Configure -des -Dusecrosscompile \
2032 -Dtargethost=so.me.ho.st \
2033 -Dcc=arm-linux-gcc \
2036 Another example where the cross-compiler has been installed under
2037 F</usr/local/arm/2.95.5>:
2039 sh ./Configure -des -Dusecrosscompile \
2040 -Dtargethost=so.me.ho.st \
2041 -Dcc=/usr/local/arm/2.95.5/bin/arm-linux-gcc \
2042 -Dsysroot=/usr/local/arm/2.95.5
2044 There is also a C<targetenv> option for Configure which can be used
2045 to modify the environment of the target just before testing begins
2046 during 'make test'. For example, if the target system has a nonstandard
2047 /tmp location, you could do this:
2049 -Dtargetenv="export TMPDIR=/other/tmp;"
2051 If you are planning on cross-compiling to several platforms, or some
2052 other thing that would involve running Configure several times, there are
2053 two options that can be used to speed things up considerably.
2054 As a bit of background, when you
2055 call Configure with C<-Dusecrosscompile>, it begins by actually partially
2056 building a miniperl on the host machine, as well as the generate_uudmap
2057 binary, and we end up using that during the build.
2058 So instead of building that new perl every single time, you can build it
2059 just once in a separate directory, and then pass the resulting binaries
2060 to Configure like this:
2062 -Dhostperl=/path/to/second/build/dir/miniperl
2063 -Dhostgenerate=/path/to/second/build/dir/generate_uudmap
2065 Much less commonly, if you are cross-compiling from an ASCII host to an
2066 EBCDIC target, or vise versa, you'll have to pass C<-Uhostgenerate> to
2067 Configure, to signify that you want to build a generate_uudmap binary
2068 that, during make, will be run on the target system.
2072 This will run the regression tests on the perl you just made. If
2073 'make test' doesn't say "All tests successful" then something went
2076 Note that you can't run the tests in background if this disables
2077 opening of /dev/tty. You can use 'make test-notty' in that case but
2078 a few tty tests will be skipped.
2080 =head2 What if make test doesn't work?
2082 If make test bombs out, just cd to the t directory and run ./TEST
2083 by hand to see if it makes any difference.
2085 One way to get more detailed information about failed tests and
2086 individual subtests is to run the harness from the t directory:
2088 cd t ; ./perl harness <list of tests>
2090 (this assumes that most basic tests succeed, since harness uses
2091 complicated constructs). If no list of tests is provided, harness
2094 If individual tests fail, you can often run them by hand (from the main
2095 perl directory), e.g.,
2097 ./perl -I. -MTestInit t/op/groups.t
2099 You should also read the individual tests to see if there are any helpful
2100 comments that apply to your system. You may also need to setup your
2101 shared library path if you get errors like:
2103 /sbin/loader: Fatal Error: cannot map libperl.so
2105 The file t/README in the t subdirectory contains more information about
2106 running and modifying tests.
2108 See L</"Building a shared Perl library"> earlier in this document.
2114 Note: One possible reason for errors is that some external programs
2115 may be broken due to the combination of your environment and the way
2116 'make test' exercises them. For example, this may happen if you have
2117 one or more of these environment variables set: LC_ALL LC_CTYPE
2118 LC_COLLATE LANG. In some versions of UNIX, the non-English locales
2119 are known to cause programs to exhibit mysterious errors.
2121 If you have any of the above environment variables set, please try
2127 LC_ALL=C;export LC_ALL
2129 for Bourne or Korn shell) from the command line and then retry
2130 make test. If the tests then succeed, you may have a broken program that
2131 is confusing the testing. Please run the troublesome test by hand as
2132 shown above and see whether you can locate the program. Look for
2133 things like: exec, `backquoted command`, system, open("|...") or
2134 open("...|"). All these mean that Perl is trying to run some
2137 =item Timing problems
2139 Several tests in the test suite check timing functions, such as
2140 sleep(), and see if they return in a reasonable amount of time.
2141 If your system is quite busy and doesn't respond quickly enough,
2142 these tests might fail. If possible, try running the tests again
2143 with the system under a lighter load. These timing-sensitive
2144 and load-sensitive tests include F<t/op/alarm.t>,
2145 F<dist/Time-HiRes/t/alarm.t>, F<dist/Time-HiRes/t/clock.t>,
2146 F<dist/Time-HiRes/t/itimer.t>, F<dist/Time-HiRes/t/usleep.t>,
2147 F<dist/threads-shared/t/waithires.t>,
2148 F<dist/threads-shared/t/stress.t>, F<lib/Benchmark.t>,
2149 F<lib/Memoize/t/expmod_t.t>, and F<lib/Memoize/t/speed.t>.
2151 You might also experience some failures in F<t/op/stat.t> if you build
2152 perl on an NFS filesystem, if the remote clock and the system clock are
2157 On some systems, particularly those with smaller amounts of RAM, some
2158 of the tests in t/op/pat.t may fail with an "Out of memory" message.
2159 For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
2160 test 85 will fail if run under either t/TEST or t/harness.
2162 Try stopping other jobs on the system and then running the test by itself:
2164 ./perl -I. -MTestInit t/op/pat.t
2166 to see if you have any better luck. If your perl still fails this
2167 test, it does not necessarily mean you have a broken perl. This test
2168 tries to exercise the regular expression subsystem quite thoroughly,
2169 and may well be far more demanding than your normal usage.
2171 =item libgcc_s.so.1: cannot open shared object file
2173 This message has been reported on gcc-3.2.3 and earlier installed with
2174 a non-standard prefix. Setting the LD_LIBRARY_PATH environment variable
2175 (or equivalent) to include gcc's lib/ directory with the libgcc_s.so.1
2176 shared library should fix the problem.
2178 =item Failures from lib/File/Temp/t/security saying "system possibly insecure"
2180 First, such warnings are not necessarily serious or indicative of a
2181 real security threat. That being said, they bear investigating.
2183 Note that each of the tests is run twice. The first time is in the
2184 directory returned by File::Spec->tmpdir() (often /tmp on Unix
2185 systems), and the second time in the directory from which the test was
2186 run (usually the 't' directory, if the test was run as part of 'make
2189 The tests may fail for the following reasons:
2191 (1) If the directory the tests are being run in is owned by somebody
2192 other than the user running the tests, or by root (uid 0).
2194 This failure can happen if the Perl source code distribution is
2195 unpacked in such a way that the user IDs in the distribution package
2196 are used as-is. Some tar programs do this.
2198 (2) If the directory the tests are being run in is writable by group or
2199 by others, and there is no sticky bit set for the directory. (With
2200 UNIX/POSIX semantics, write access to a directory means the right to
2201 add or remove files in that directory. The 'sticky bit' is a feature
2202 used in some UNIXes to give extra protection to files: if the bit is
2203 set for a directory, no one but the owner (or root) can remove that
2204 file even if the permissions would otherwise allow file removal by
2207 This failure may or may not be a real problem: it depends on the
2208 permissions policy used on this particular system. This failure can
2209 also happen if the system either doesn't support the sticky bit (this
2210 is the case with many non-UNIX platforms: in principle File::Temp
2211 should know about these platforms and skip the tests), or if the system
2212 supports the sticky bit but for some reason or reasons it is not being
2213 used. This is, for example, the case with HP-UX: as of HP-UX release
2214 11.00, the sticky bit is very much supported, but HP-UX doesn't use it
2215 on its /tmp directory as shipped. Also, as with the permissions, some
2216 local policy might dictate that the stickiness is not used.
2218 (3) If the system supports the POSIX 'chown giveaway' feature and if
2219 any of the parent directories of the temporary file back to the root
2220 directory are 'unsafe', using the definitions given above in (1) and
2221 (2). For Unix systems, this is usually not an issue if you are
2222 building on a local disk. See the documentation for the File::Temp
2223 module for more information about 'chown giveaway'.
2225 See the documentation for the File::Temp module for more information
2226 about the various security aspects of temporary files.
2230 The core distribution can now run its regression tests in parallel on
2231 Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS>
2232 in your environment to the number of tests to run in parallel, and run
2233 C<make test_harness>. On a Bourne-like shell, this can be done as
2235 TEST_JOBS=3 make test_harness # Run 3 tests in parallel
2237 An environment variable is used, rather than parallel make itself,
2238 because L<TAP::Harness> needs to be able to schedule individual
2239 non-conflicting test scripts itself, and there is no standard interface
2240 to C<make> utilities to interact with their job schedulers.
2244 This will put perl into the public directory you specified to
2245 Configure; by default this is /usr/local/bin. It will also try to put
2246 the man pages in a reasonable place. It will not nroff the man pages,
2247 however. You may need to be root to run B<make install>. If you are not
2248 root, you must still have permission to install into the directories
2249 in question and you should ignore any messages about chown not working.
2251 If "make install" just says "'install' is up to date" or something
2252 similar, you may be on a case-insensitive filesystems such as Mac's HFS+,
2253 and you should say "make install-all". (This confusion is brought to you
2254 by the Perl distribution having a file called INSTALL.)
2256 =head2 Installing perl under different names
2258 If you want to install perl under a name other than "perl" (for example,
2259 when installing perl with special features enabled, such as debugging),
2260 indicate the alternate name on the "make install" line, such as:
2262 make install PERLNAME=myperl
2264 You can separately change the base used for versioned names (like
2265 "perl5.8.9") by setting PERLNAME_VERBASE, like
2267 make install PERLNAME=perl5 PERLNAME_VERBASE=perl
2269 This can be useful if you have to install perl as "perl5" (e.g. to avoid
2270 conflicts with an ancient version in /usr/bin supplied by your vendor).
2271 Without this the versioned binary would be called "perl55.8.8".
2273 =head2 Installing perl under a different directory
2275 You can install perl under a different destination directory by using
2276 the DESTDIR variable during C<make install>, with a command like
2278 make install DESTDIR=/tmp/perl5
2280 DESTDIR is automatically prepended to all the installation paths. See
2281 the example in L<"DESTDIR"> above.
2283 =head2 Installed files
2285 If you want to see exactly what will happen without installing
2286 anything, you can run
2288 ./perl installperl -n
2289 ./perl installman -n
2291 make install will install the following:
2296 perl5.n.n where 5.n.n is the current release number. This
2297 will be a link to perl.
2301 cppstdin This is used by the deprecated switch perl -P,
2302 if your cc -E can't read from stdin.
2303 corelist Shows versions of modules that come with
2306 cpan The CPAN shell.
2307 enc2xs Encoding module generator.
2308 h2ph Extract constants and simple macros from C
2310 h2xs Converts C .h header files to Perl extensions.
2311 instmodsh A shell to examine installed modules.
2312 libnetcfg Configure libnet.
2313 perlbug Tool to report bugs in Perl.
2314 perldoc Tool to read perl's pod documentation.
2315 perlivp Perl Installation Verification Procedure.
2316 piconv A Perl implementation of the encoding conversion
2318 pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules.
2319 pod2html, Converters from perl's pod documentation format
2323 podchecker POD syntax checker.
2324 podselect Prints sections of POD documentation.
2325 prove A command-line tool for running tests.
2326 psed A Perl implementation of sed.
2327 ptar A Perl implementation of tar.
2328 ptardiff A diff for tar archives.
2329 ptargrep A grep for tar archives.
2330 shasum A tool to print or check SHA checksums.
2331 splain Describe Perl warnings and errors.
2332 xsubpp Compiler to convert Perl XS code into C code.
2333 zipdetails display the internal structure of zip files
2337 in $privlib and $archlib specified to
2338 Configure, usually under /usr/local/lib/perl5/.
2342 man pages in $man1dir, usually /usr/local/man/man1.
2344 pages in $man3dir, usually /usr/local/man/man3.
2345 pod/*.pod in $privlib/pod/.
2347 installperl will also create the directories listed above
2348 in L<"Installation Directories">.
2350 Perl's *.h header files and the libperl library are also installed
2351 under $archlib so that any user may later build new modules, run the
2352 optional Perl compiler, or embed the perl interpreter into another
2353 program even if the Perl source is no longer available.
2355 =head2 Installing with a version-specific suffix
2357 Sometimes you only want to install the perl distribution with a
2358 version-specific suffix. For example, you may wish to install a newer
2359 version of perl alongside an already installed production version.
2360 To only install the version-specific parts of the perl installation, run
2362 Configure -Dversiononly
2364 or answer 'y' to the appropriate Configure prompt. Alternatively,
2365 you can just manually run
2367 ./perl installperl -v
2369 and skip installman altogether.
2371 See also L<"Maintaining completely separate versions"> for another
2374 =head1 cd /usr/include; h2ph *.h sys/*.h
2376 Some perl scripts need to be able to obtain information from the
2377 system header files. This command will convert the most commonly used
2378 header files in /usr/include into files that can be easily interpreted
2379 by perl. These files will be placed in the architecture-dependent
2380 library ($archlib) directory you specified to Configure.
2382 Note: Due to differences in the C and perl languages, the conversion
2383 of the header files is not perfect. You will probably have to
2384 hand-edit some of the converted files to get them to parse correctly.
2385 For example, h2ph breaks spectacularly on type casting and certain
2388 =head1 installhtml --help
2390 Some sites may wish to make perl documentation available in HTML
2391 format. The installhtml utility can be used to convert pod
2392 documentation into linked HTML files and install them.
2394 Currently, the supplied ./installhtml script does not make use of the
2395 html Configure variables. This should be fixed in a future release.
2397 The following command-line is an example of one used to convert
2402 --podpath=lib:ext:pod:vms \
2404 --htmldir=/perl/nmanual \
2405 --htmlroot=/perl/nmanual \
2406 --splithead=pod/perlipc \
2407 --splititem=pod/perlfunc \
2410 See the documentation in installhtml for more details. It can take
2411 many minutes to execute a large installation and you should expect to
2412 see warnings like "no title", "unexpected directive" and "cannot
2413 resolve" as the files are processed. We are aware of these problems
2414 (and would welcome patches for them).
2416 You may find it helpful to run installhtml twice. That should reduce
2417 the number of "cannot resolve" warnings.
2419 =head1 cd pod && make tex && (process the latex files)
2421 Some sites may also wish to make the documentation in the pod/ directory
2422 available in TeX format. Type
2424 (cd pod && make tex && <process the latex files>)
2426 =head1 Starting all over again
2428 If you wish to rebuild perl from the same build directory, you should
2429 clean it out with the command
2437 The only difference between the two is that make distclean also removes
2438 your old config.sh and Policy.sh files. (A plain 'make clean' is now
2439 equivalent to 'make realclean'.)
2441 If you are upgrading from a previous version of perl, or if you
2442 change systems or compilers or make other significant changes, or if
2443 you are experiencing difficulties building perl, you should not reuse
2446 If your reason to reuse your old config.sh is to save your particular
2447 installation choices, then you can probably achieve the same effect by
2448 using the Policy.sh file. See the section on L<"Site-wide Policy
2451 =head1 Reporting Problems
2453 Please report problems to the GitHub issue tracker at
2454 https://github.com/Perl/perl5/issues, which will ask for the
2455 appropriate summary configuration information about your perl, which
2456 may help us track down problems far more quickly. But first you should
2457 read the advice in this file, carefully re-read the error message and
2458 check the relevant manual pages on your system, as these may help you
2459 find an immediate solution. Once you've exhausted the documentation,
2460 please report bugs to us using the GitHub tracker.
2462 The summary configuration information can be printed with C<perl -V>.
2463 If the install fails, or you want to report problems with C<make test>
2464 without installing perl, then you can run it by hand from this source
2465 directory with C<./perl -V>.
2467 If the build fails too early to run perl, then please
2468 B<run> the C<./myconfig> shell script, and include its output along
2469 with an accurate description of your problem.
2471 If Configure itself fails, and does not generate a config.sh file
2472 (needed to run C<./myconfig>), then please open an issue with the
2473 description of how Configure fails along with details of your system
2474 -- for example the output from running C<uname -a>.
2476 Please try to make your message brief but clear. Brief, clear bug
2477 reports tend to get answered more quickly. Please don't worry if your
2478 written English is not great -- what matters is how well you describe
2479 the important technical details of the problem you have encountered,
2480 not whether your grammar and spelling is flawless.
2482 Trim out unnecessary information. Do not include large files (such as
2483 config.sh or a complete Configure or make log) unless absolutely
2484 necessary. Do not include a complete transcript of your build
2485 session. Just include the failing commands, the relevant error
2486 messages, and whatever preceding commands are necessary to give the
2487 appropriate context.
2489 If the bug you are reporting has security implications which make it
2490 inappropriate to send to a public issue tracker, then see
2491 L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
2492 for details of how to report the issue.
2494 If you are unsure what makes a good bug report please read "How to
2495 report Bugs Effectively" by Simon Tatham:
2496 L<https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>
2498 =head1 Coexistence with earlier versions of perl 5
2500 Perl 5.35.8 is not binary compatible with earlier versions of Perl.
2501 In other words, you will have to recompile your XS modules.
2503 In general, you can usually safely upgrade from one stable version of Perl
2504 (e.g. 5.30.0) to another similar minor version (e.g. 5.30.1) without
2505 re-compiling all of your extensions. You can also safely leave the old
2506 version around in case the new version causes you problems for some
2509 Usually, most extensions will probably not need to be recompiled to be
2510 used with a newer version of Perl. Here is how it is supposed to work.
2511 (These examples assume you accept all the Configure defaults.)
2513 Suppose you already have version 5.8.7 installed. The directories
2514 searched by 5.8.7 are typically like:
2516 /usr/local/lib/perl5/5.8.7/$archname
2517 /usr/local/lib/perl5/5.8.7
2518 /usr/local/lib/perl5/site_perl/5.8.7/$archname
2519 /usr/local/lib/perl5/site_perl/5.8.7
2521 Now, suppose you install version 5.8.8. The directories
2522 searched by version 5.8.8 will be:
2524 /usr/local/lib/perl5/5.8.8/$archname
2525 /usr/local/lib/perl5/5.8.8
2526 /usr/local/lib/perl5/site_perl/5.8.8/$archname
2527 /usr/local/lib/perl5/site_perl/5.8.8
2529 /usr/local/lib/perl5/site_perl/5.8.7/$archname
2530 /usr/local/lib/perl5/site_perl/5.8.7
2531 /usr/local/lib/perl5/site_perl/
2533 Notice the last three entries -- Perl understands the default structure
2534 of the $sitelib directories and will look back in older, compatible
2535 directories. This way, modules installed under 5.8.7 will continue
2536 to be usable by 5.8.7 but will also accessible to 5.8.8. Further,
2537 suppose that you upgrade a module to one which requires features
2538 present only in 5.8.8. That new module will get installed into
2539 /usr/local/lib/perl5/site_perl/5.8.8 and will be available to 5.8.8,
2540 but will not interfere with the 5.8.7 version.
2542 The last entry, /usr/local/lib/perl5/site_perl/, is there so that
2543 5.6.0 and above will look for 5.004-era pure perl modules.
2545 Lastly, suppose you now install 5.10.0, which is not binary compatible
2546 with 5.8.x. The directories searched by 5.10.0 (if you don't change the
2547 Configure defaults) will be:
2549 /usr/local/lib/perl5/5.10.0/$archname
2550 /usr/local/lib/perl5/5.10.0
2551 /usr/local/lib/perl5/site_perl/5.10.0/$archname
2552 /usr/local/lib/perl5/site_perl/5.10.0
2554 /usr/local/lib/perl5/site_perl/5.8.8
2556 /usr/local/lib/perl5/site_perl/5.8.7
2558 /usr/local/lib/perl5/site_perl/
2560 Note that the earlier $archname entries are now gone, but pure perl
2561 modules from earlier versions will still be found.
2563 This way, you can choose to share compatible extensions, but also upgrade
2564 to a newer version of an extension that may be incompatible with earlier
2565 versions, without breaking the earlier versions' installations.
2567 =head2 Maintaining completely separate versions
2569 Many users prefer to keep all versions of perl in completely
2570 separate directories. This guarantees that an update to one version
2571 won't interfere with another version. (The defaults guarantee this for
2572 libraries after 5.6.0, but not for executables. TODO?) One convenient
2573 way to do this is by using a separate prefix for each version, such as
2575 sh Configure -Dprefix=/opt/perl5.35.8
2577 and adding /opt/perl5.35.8/bin to the shell PATH variable. Such users
2578 may also wish to add a symbolic link /usr/local/bin/perl so that
2579 scripts can still start with #!/usr/local/bin/perl.
2581 Others might share a common directory for maintenance sub-versions
2582 (e.g. 5.10 for all 5.10.x versions), but change directory with
2585 If you are installing a development subversion, you probably ought to
2586 seriously consider using a separate directory, since development
2587 subversions may not have all the compatibility wrinkles ironed out
2590 =head2 Upgrading from 5.35.7 or earlier
2592 B<Perl 5.35.8 may not be binary compatible with Perl 5.35.7 or
2593 earlier Perl releases.> Perl modules having binary parts
2594 (meaning that a C compiler is used) will have to be recompiled to be
2595 used with 5.35.8. If you find you do need to rebuild an extension with
2596 5.35.8, you may safely do so without disturbing the older
2597 installations. (See L<"Coexistence with earlier versions of perl 5">
2600 See your installed copy of the perllocal.pod file for a (possibly
2601 incomplete) list of locally installed modules. Note that you want
2602 perllocal.pod, not perllocale.pod, for installed module information.
2604 =head1 Minimizing the Perl installation
2606 The following section is meant for people worrying about squeezing the
2607 Perl installation into minimal systems (for example when installing
2608 operating systems, or in really small filesystems).
2610 Leaving out as many extensions as possible is an obvious way:
2611 Encode, with its big conversion tables, consumes a lot of
2612 space. On the other hand, you cannot throw away everything. The
2613 Fcntl module is pretty essential. If you need to do network
2614 programming, you'll appreciate the Socket module, and so forth: it all
2615 depends on what do you need to do.
2617 In the following we offer two different slimmed down installation
2618 recipes. They are informative, not normative: the choice of files
2619 depends on what you need.
2621 Firstly, the bare minimum to run this script
2625 foreach my $f (</*>) {
2629 in Linux with perl-5.35.8 is as follows (under $Config{prefix}):
2632 ./lib/perl5/5.35.8/strict.pm
2633 ./lib/perl5/5.35.8/warnings.pm
2634 ./lib/perl5/5.35.8/i686-linux/File/Glob.pm
2635 ./lib/perl5/5.35.8/feature.pm
2636 ./lib/perl5/5.35.8/XSLoader.pm
2637 ./lib/perl5/5.35.8/i686-linux/auto/File/Glob/Glob.so
2639 Secondly, for perl-5.10.1, the Debian perl-base package contains 591
2640 files, (of which 510 are for lib/unicore) totaling about 3.5MB in its
2641 i386 version. Omitting the lib/unicore/* files for brevity, the
2642 remaining files are:
2646 /usr/lib/perl/5.10.1/Config.pm
2647 /usr/lib/perl/5.10.1/Config_git.pl
2648 /usr/lib/perl/5.10.1/Config_heavy.pl
2649 /usr/lib/perl/5.10.1/Cwd.pm
2650 /usr/lib/perl/5.10.1/DynaLoader.pm
2651 /usr/lib/perl/5.10.1/Errno.pm
2652 /usr/lib/perl/5.10.1/Fcntl.pm
2653 /usr/lib/perl/5.10.1/File/Glob.pm
2654 /usr/lib/perl/5.10.1/Hash/Util.pm
2655 /usr/lib/perl/5.10.1/IO.pm
2656 /usr/lib/perl/5.10.1/IO/File.pm
2657 /usr/lib/perl/5.10.1/IO/Handle.pm
2658 /usr/lib/perl/5.10.1/IO/Pipe.pm
2659 /usr/lib/perl/5.10.1/IO/Seekable.pm
2660 /usr/lib/perl/5.10.1/IO/Select.pm
2661 /usr/lib/perl/5.10.1/IO/Socket.pm
2662 /usr/lib/perl/5.10.1/IO/Socket/INET.pm
2663 /usr/lib/perl/5.10.1/IO/Socket/UNIX.pm
2664 /usr/lib/perl/5.10.1/List/Util.pm
2665 /usr/lib/perl/5.10.1/POSIX.pm
2666 /usr/lib/perl/5.10.1/Scalar/Util.pm
2667 /usr/lib/perl/5.10.1/Socket.pm
2668 /usr/lib/perl/5.10.1/XSLoader.pm
2669 /usr/lib/perl/5.10.1/auto/Cwd/Cwd.so
2670 /usr/lib/perl/5.10.1/auto/DynaLoader/autosplit.ix
2671 /usr/lib/perl/5.10.1/auto/DynaLoader/dl_expandspec.al
2672 /usr/lib/perl/5.10.1/auto/DynaLoader/dl_find_symbol_anywhere.al
2673 /usr/lib/perl/5.10.1/auto/DynaLoader/dl_findfile.al
2674 /usr/lib/perl/5.10.1/auto/Fcntl/Fcntl.so
2675 /usr/lib/perl/5.10.1/auto/File/Glob/Glob.so
2676 /usr/lib/perl/5.10.1/auto/Hash/Util/Util.so
2677 /usr/lib/perl/5.10.1/auto/IO/IO.so
2678 /usr/lib/perl/5.10.1/auto/List/Util/Util.so
2679 /usr/lib/perl/5.10.1/auto/POSIX/POSIX.so
2680 /usr/lib/perl/5.10.1/auto/POSIX/autosplit.ix
2681 /usr/lib/perl/5.10.1/auto/POSIX/load_imports.al
2682 /usr/lib/perl/5.10.1/auto/Socket/Socket.so
2683 /usr/lib/perl/5.10.1/lib.pm
2684 /usr/lib/perl/5.10.1/re.pm
2685 /usr/share/doc/perl/AUTHORS.gz
2686 /usr/share/doc/perl/Documentation
2687 /usr/share/doc/perl/README.Debian
2688 /usr/share/doc/perl/changelog.Debian.gz
2689 /usr/share/doc/perl/copyright
2690 /usr/share/lintian/overrides/perl-base
2691 /usr/share/man/man1/perl.1.gz
2692 /usr/share/man/man1/perl5.10.1.1.gz
2693 /usr/share/perl/5.10.1/AutoLoader.pm
2694 /usr/share/perl/5.10.1/Carp.pm
2695 /usr/share/perl/5.10.1/Carp/Heavy.pm
2696 /usr/share/perl/5.10.1/Exporter.pm
2697 /usr/share/perl/5.10.1/Exporter/Heavy.pm
2698 /usr/share/perl/5.10.1/File/Spec.pm
2699 /usr/share/perl/5.10.1/File/Spec/Unix.pm
2700 /usr/share/perl/5.10.1/FileHandle.pm
2701 /usr/share/perl/5.10.1/Getopt/Long.pm
2702 /usr/share/perl/5.10.1/IPC/Open2.pm
2703 /usr/share/perl/5.10.1/IPC/Open3.pm
2704 /usr/share/perl/5.10.1/SelectSaver.pm
2705 /usr/share/perl/5.10.1/Symbol.pm
2706 /usr/share/perl/5.10.1/Text/ParseWords.pm
2707 /usr/share/perl/5.10.1/Text/Tabs.pm
2708 /usr/share/perl/5.10.1/Text/Wrap.pm
2709 /usr/share/perl/5.10.1/Tie/Hash.pm
2710 /usr/share/perl/5.10.1/attributes.pm
2711 /usr/share/perl/5.10.1/base.pm
2712 /usr/share/perl/5.10.1/bytes.pm
2713 /usr/share/perl/5.10.1/bytes_heavy.pl
2714 /usr/share/perl/5.10.1/constant.pm
2715 /usr/share/perl/5.10.1/fields.pm
2716 /usr/share/perl/5.10.1/integer.pm
2717 /usr/share/perl/5.10.1/locale.pm
2718 /usr/share/perl/5.10.1/overload.pm
2719 /usr/share/perl/5.10.1/strict.pm
2720 /usr/share/perl/5.10.1/unicore/*
2721 /usr/share/perl/5.10.1/utf8.pm
2722 /usr/share/perl/5.10.1/utf8_heavy.pl
2723 /usr/share/perl/5.10.1/vars.pm
2724 /usr/share/perl/5.10.1/warnings.pm
2725 /usr/share/perl/5.10.1/warnings/register.pm
2727 A nice trick to find out the minimal set of Perl library files you will
2728 need to run a Perl program is
2730 perl -e 'do "prog.pl"; END { print "$_\n" for sort keys %INC }'
2732 (this will not find libraries required in runtime, unfortunately, but
2733 it's a minimal set) and if you want to find out all the files you can
2734 use something like the below
2736 strace perl -le 'do "x.pl"' 2>&1 \
2737 | perl -nle '/^open\(\"(.+?)"/ && print $1'
2739 (The 'strace' is Linux-specific, other similar utilities include 'truss'
2742 =head2 C<-DNO_MATHOMS>
2744 If you configure perl with C<-Accflags=-DNO_MATHOMS>, the functions from
2745 F<mathoms.c> will not be compiled in. Those functions are no longer used
2746 by perl itself; for source compatibility reasons, though, they weren't
2749 =head2 C<-DNO_PERL_INTERNAL_RAND_SEED>
2750 X<PERL_INTERNAL_RAND_SEED>
2752 If you configure perl with C<-Accflags=-DNO_PERL_INTERNAL_RAND_SEED>,
2753 perl will ignore the C<PERL_INTERNAL_RAND_SEED> environment variable.
2755 =head1 DOCUMENTATION
2757 Read the manual entries before running perl. The main documentation
2758 is in the F<pod/> subdirectory and should have been installed during the
2759 build process. Type B<man perl> to get started. Alternatively, you
2760 can type B<perldoc perl> to use the supplied perldoc script. This is
2761 sometimes useful for finding things in the library modules.
2765 Original author: Andy Dougherty doughera@lafayette.edu , borrowing very
2766 heavily from the original README by Larry Wall, with lots of helpful
2767 feedback and additions from the perl5-porters@perl.org folks.
2769 If you have problems, corrections, or questions, please see
2770 L<"Reporting Problems"> above.
2772 =head1 REDISTRIBUTION
2774 This document is part of the Perl package and may be distributed under
2775 the same terms as perl itself, with the following additional request:
2776 If you are distributing a modified version of perl (perhaps as part of
2777 a larger package) please B<do> modify these installation instructions
2778 and the contact information to match your distribution. Additional
2779 information for packagers is in F<PACKAGING>.