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
453 that by setting the C<PERL_HASH_USE_SBOX32_ALSO> in the Configure process,
454 with something like this
456 -Accflags='-DPERL_HASH_USE_SBOX32_ALSO=0'
458 or alternatively you can use the simple define C<PERL_HASH_NO_SBOX32> like this:
460 -Accflags='-DPERL_HASH_NO_SBOX32'
462 By default Perl will use SBOX32 to hash strings 24 bytes
463 or shorter, you can change this length by setting C<SBOX32_MAX_LEN>
464 to the desired length, with the maximum length being 256. For example with
467 -Accflags='-DSBOX_MAX_LEN=128'
469 As of Perl 5.18 the order returned by keys(), values(), and each() is
470 non-deterministic and distinct per hash, and the insert order for
471 colliding keys is randomized as well, and perl allows for controlling this
472 by the PERL_PERTURB_KEYS environment setting. You can disable this behavior
473 entirely with the define C<PERL_PERTURB_KEYS_DISABLED> with
475 -Accflags='-DPERL_PERTURB_KEYS_DISABLED'
477 You can disable the environment variable checks and compile time specify
478 the type of key traversal randomization to be used by defining either
479 C<PERL_PERTURB_KEYS_RANDOM> or C<PERL_PERTURB_KEYS_DETERMINISTIC> with
481 -Accflags='-DPERL_PERTURB_KEYS_RANDOM'
485 -Accflags='-DPERL_PERTURB_KEYS_DETERMINISTIC'
487 Since Perl 5.18 the seed used for the hash function is randomly selected
488 at process start, which can be overridden by specifying a seed by setting
489 the PERL_HASH_SEED environment variable. Be aware that
490 PERL_PERTURB_KEYS_DETERMINISTIC and the equivalent environment variable
491 setting will produce the same results if and only if the code does not
492 put non-deterministic data into a hash, and the code is executed in exactly
493 the same context in terms of the environment. If the code populates a hash
494 with random data, or builds a hash using the address of its items, or
495 if the code is run in a different environment context with a different
496 number or selection of environment variables then the result may differ.
497 DETERMINISTIC in this context means "if everything else is kept the same
498 the same results should be observed".
500 You can change this behavior so that your perl is built with a hard coded
501 seed with the define C<NO_HASH_SEED> by providing to Configure
503 -Accflags='-DNO_HASH_SEED'
505 Note that if you do this you should modify the code in hv_func.h to specify
506 your own key. In the future this define may be renamed and replaced with one
507 that requires you to specify the key to use.
509 B<NOTE WELL: Perl has never guaranteed any ordering of the hash keys>, and the
510 ordering has already changed several times during the lifetime of Perl
511 5. Also, the ordering of hash keys has always been, and continues to
512 be, affected by the insertion order regardless of whether you build with
513 or without the randomization features. Note that because of this
514 and especially with randomization that the key order of a hash is *undefined*
515 and that things like Data::Dumper, for example, may produce different output
516 between different runs of Perl, since Data::Dumper serializes the key in the
517 native order for the hash. The use of the Data::Dumper C<Sortkeys> option is
518 recommended if you are comparing dumps between different invocations of perl.
520 See L<perlrun/PERL_HASH_SEED> and L<perlrun/PERL_PERTURB_KEYS> for
521 details on the environment variables, and L<perlsec/Algorithmic
522 Complexity Attacks> for further security details.
524 The C<PERL_HASH_SEED> and C<PERL_PERTURB_KEYS> environment variables can
525 be disabled by building configuring perl with
526 C<-Accflags=-DNO_PERL_HASH_ENV>.
528 The C<PERL_HASH_SEED_DEBUG> environment variable can be disabled by
529 configuring perl with C<-Accflags=-DNO_PERL_HASH_SEED_DEBUG>.
533 Perl can be configured to be 'socksified', that is, to use the SOCKS
534 TCP/IP proxy protocol library. SOCKS is used to give applications
535 access to transport layer network proxies. Perl supports only SOCKS
536 Version 5. The corresponding Configure option is -Dusesocks.
537 You can find more about SOCKS from wikipedia at
538 L<https://en.wikipedia.org/wiki/SOCKS>.
540 =head3 Dynamic Loading
542 By default, Configure will compile perl to use dynamic loading.
543 If you want to force perl to be compiled completely
544 statically, you can either choose this when Configure prompts you or
545 you can use the Configure command line option -Uusedl.
546 With this option, you won't be able to use any new extension
547 (XS) module without recompiling perl itself.
549 =head3 Building a shared Perl library
551 Currently, for most systems, the main perl executable is built by
552 linking the "perl library" libperl.a with perlmain.o, your static
553 extensions, and various extra libraries, such as -lm.
555 On systems that support dynamic loading, it may be possible to
556 replace libperl.a with a shared libperl.so. If you anticipate building
557 several different perl binaries (e.g. by embedding libperl into
558 different programs, or by using the optional compiler extension), then
559 you might wish to build a shared libperl.so so that all your binaries
560 can share the same library.
562 The disadvantages are that there may be a significant performance
563 penalty associated with the shared libperl.so, and that the overall
564 mechanism is still rather fragile with respect to different versions
567 In terms of performance, on my test system (Solaris 2.5_x86) the perl
568 test suite took roughly 15% longer to run with the shared libperl.so.
569 Your system and typical applications may well give quite different
572 The default name for the shared library is typically something like
573 libperl.so.5.8.8 (for Perl 5.8.8), or libperl.so.588, or simply
574 libperl.so. Configure tries to guess a sensible naming convention
575 based on your C library name. Since the library gets installed in a
576 version-specific architecture-dependent directory, the exact name
577 isn't very important anyway, as long as your linker is happy.
579 You can elect to build a shared libperl by
581 sh Configure -Duseshrplib
583 To build a shared libperl, the environment variable controlling shared
584 library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
585 Darwin, LD_LIBRARY_PATH/SHLIB_PATH
586 for HP-UX, LIBPATH for AIX and z/OS, PATH for Cygwin) must be set up to include
587 the Perl build directory because that's where the shared libperl will
588 be created. Configure arranges makefile to have the correct shared
589 library search settings. You can find the name of the environment
590 variable Perl thinks works in your your system by
592 grep ldlibpthname config.sh
594 However, there are some special cases where manually setting the
595 shared library path might be required. For example, if you want to run
596 something like the following with the newly-built but not-yet-installed
599 ./perl -I. -MTestInit t/misc/failing_test.t
603 ./perl -Ilib ~/my_mission_critical_test
605 then you need to set up the shared library path explicitly.
608 LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
610 for Bourne-style shells, or
612 setenv LD_LIBRARY_PATH `pwd`
614 for Csh-style shells. (This procedure may also be needed if for some
615 unexpected reason Configure fails to set up makefile correctly.) (And
616 again, it may be something other than LD_LIBRARY_PATH for you, see above.)
618 You can often recognize failures to build/use a shared libperl from error
619 messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
622 18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
624 There is also an potential problem with the shared perl library if you
625 want to have more than one "flavor" of the same version of perl (e.g.
626 with and without -DDEBUGGING). For example, suppose you build and
627 install a standard Perl 5.10.0 with a shared library. Then, suppose you
628 try to build Perl 5.10.0 with -DDEBUGGING enabled, but everything else
629 the same, including all the installation directories. How can you
630 ensure that your newly built perl will link with your newly built
631 libperl.so.8 rather with the installed libperl.so.8? The answer is
632 that you might not be able to. The installation directory is encoded
633 in the perl binary with the LD_RUN_PATH environment variable (or
634 equivalent ld command-line option). On Solaris, you can override that
635 with LD_LIBRARY_PATH; on Linux, you can only override at runtime via
636 LD_PRELOAD, specifying the exact filename you wish to be used; and on
637 Digital Unix, you can override LD_LIBRARY_PATH by setting the
638 _RLD_ROOT environment variable to point to the perl build directory.
640 In other words, it is generally not a good idea to try to build a perl
641 with a shared library if $archlib/CORE/$libperl already exists from a
644 A good workaround is to specify a different directory for the
645 architecture-dependent library for your -DDEBUGGING version of perl.
646 You can do this by changing all the *archlib* variables in config.sh to
647 point to your new architecture-dependent library.
651 Before File::Glob entered core in 5.6.0 globbing was implemented by shelling
652 out. If the environmental variable PERL_EXTERNAL_GLOB is defined and if the
653 F<csh> shell is available, perl will still do this the old way.
655 =head2 Installation Directories
657 The installation directories can all be changed by answering the
658 appropriate questions in Configure. For convenience, all the installation
659 questions are near the beginning of Configure. Do not include trailing
660 slashes on directory names. At any point during the Configure process,
661 you can answer a question with &-d and Configure will use the defaults
662 from then on. Alternatively, you can
664 grep '^install' config.sh
666 after Configure has run to verify the installation paths.
668 The defaults are intended to be reasonable and sensible for most
669 people building from sources. Those who build and distribute binary
670 distributions or who export perl to a range of systems will probably
671 need to alter them. If you are content to just accept the defaults,
672 you can safely skip the next section.
674 The directories set up by Configure fall into three broad categories.
678 =item Directories for the perl distribution
680 By default, Configure will use the following directories for 5.37.4.
681 $version is the full perl version number, including subversion, e.g.
682 5.12.3, and $archname is a string like sun4-sunos,
683 determined by Configure. The full definitions of all Configure
684 variables are in the file Porting/Glossary.
686 Configure variable Default value
687 $prefixexp /usr/local
688 $binexp $prefixexp/bin
689 $scriptdirexp $prefixexp/bin
690 $privlibexp $prefixexp/lib/perl5/$version
691 $archlibexp $prefixexp/lib/perl5/$version/$archname
692 $man1direxp $prefixexp/man/man1
693 $man3direxp $prefixexp/man/man3
697 $prefixexp is generated from $prefix, with ~ expansion done to convert
698 home directories into absolute paths. Similarly for the other variables
699 listed. As file system calls do not do this, you should always reference
700 the ...exp variables, to support users who build perl in their home
703 Actually, Configure recognizes the SVR3-style
704 /usr/local/man/l_man/man1 directories, if present, and uses those
705 instead. Also, if $prefix contains the string "perl", the library
706 directories are simplified as described below. For simplicity, only
707 the common style is shown here.
709 =item Directories for site-specific add-on files
711 After perl is installed, you may later wish to add modules (e.g. from
712 CPAN) or scripts. Configure will set up the following directories to
713 be used for installing those add-on modules and scripts.
717 $siteprefixexp $prefixexp
718 $sitebinexp $siteprefixexp/bin
719 $sitescriptexp $siteprefixexp/bin
720 $sitelibexp $siteprefixexp/lib/perl5/site_perl/$version
722 $siteprefixexp/lib/perl5/site_perl/$version/$archname
723 $siteman1direxp $siteprefixexp/man/man1
724 $siteman3direxp $siteprefixexp/man/man3
725 $sitehtml1direxp (none)
726 $sitehtml3direxp (none)
728 By default, ExtUtils::MakeMaker will install architecture-independent
729 modules into $sitelib and architecture-dependent modules into $sitearch.
731 =item Directories for vendor-supplied add-on files
733 Lastly, if you are building a binary distribution of perl for
734 distribution, Configure can optionally set up the following directories
735 for you to use to distribute add-on modules.
739 $vendorprefixexp (none)
741 (The next ones are set only if vendorprefix is set.)
743 $vendorbinexp $vendorprefixexp/bin
744 $vendorscriptexp $vendorprefixexp/bin
745 $vendorlibexp $vendorprefixexp/lib/perl5/vendor_perl/$version
747 $vendorprefixexp/lib/perl5/vendor_perl/$version/$archname
748 $vendorman1direxp $vendorprefixexp/man/man1
749 $vendorman3direxp $vendorprefixexp/man/man3
750 $vendorhtml1direxp (none)
751 $vendorhtml3direxp (none)
753 These are normally empty, but may be set as needed. For example,
754 a vendor might choose the following settings:
757 $siteprefix /usr/local
760 This would have the effect of setting the following:
763 $scriptdirexp /usr/bin
764 $privlibexp /usr/lib/perl5/$version
765 $archlibexp /usr/lib/perl5/$version/$archname
766 $man1direxp /usr/man/man1
767 $man3direxp /usr/man/man3
769 $sitebinexp /usr/local/bin
770 $sitescriptexp /usr/local/bin
771 $sitelibexp /usr/local/lib/perl5/site_perl/$version
772 $sitearchexp /usr/local/lib/perl5/site_perl/$version/$archname
773 $siteman1direxp /usr/local/man/man1
774 $siteman3direxp /usr/local/man/man3
776 $vendorbinexp /usr/bin
777 $vendorscriptexp /usr/bin
778 $vendorlibexp /usr/lib/perl5/vendor_perl/$version
779 $vendorarchexp /usr/lib/perl5/vendor_perl/$version/$archname
780 $vendorman1direxp /usr/man/man1
781 $vendorman3direxp /usr/man/man3
783 Note how in this example, the vendor-supplied directories are in the
784 /usr hierarchy, while the directories reserved for the end user are in
785 the /usr/local hierarchy.
787 The entire installed library hierarchy is installed in locations with
788 version numbers, keeping the installations of different versions distinct.
789 However, later installations of Perl can still be configured to search
790 the installed libraries corresponding to compatible earlier versions.
791 See L<"Coexistence with earlier versions of perl 5"> below for more
792 details on how Perl can be made to search older version directories.
794 Of course you may use these directories however you see fit. For
795 example, you may wish to use $siteprefix for site-specific files that
796 are stored locally on your own disk and use $vendorprefix for
797 site-specific files that are stored elsewhere on your organization's
798 network. One way to do that would be something like
800 sh Configure -Dsiteprefix=/usr/local -Dvendorprefix=/usr/share/perl
804 As a final catch-all, Configure also offers an $otherlibdirs
805 variable. This variable contains a colon-separated list of additional
806 directories to add to @INC. By default, it will be empty.
807 Perl will search these directories (including architecture and
808 version-specific subdirectories) for add-on modules and extensions.
810 For example, if you have a bundle of perl libraries from a previous
811 installation, perhaps in a strange place:
813 sh Configure -Dotherlibdirs=/usr/lib/perl5/site_perl/5.8.1
817 There is one other way of adding paths to @INC at perl build time, and
818 that is by setting the APPLLIB_EXP C pre-processor token to a colon-
819 separated list of directories, like this
821 sh Configure -Accflags='-DAPPLLIB_EXP=\"/usr/libperl\"'
823 The directories defined by APPLLIB_EXP get added to @INC I<first>,
824 ahead of any others, and so provide a way to override the standard perl
825 modules should you, for example, want to distribute fixes without
826 touching the perl distribution proper. And, like otherlib dirs,
827 version and architecture specific subdirectories are also searched, if
828 present, at run time. Of course, you can still search other @INC
829 directories ahead of those in APPLLIB_EXP by using any of the standard
830 run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc.
832 =item default_inc_excludes_dot
834 Since version 5.26.0, default perl builds no longer includes C<'.'> as the
835 last element of @INC. The old behaviour can restored using
837 sh Configure -Udefault_inc_excludes_dot
839 Note that this is likely to make programs run under such a perl
840 interpreter less secure.
842 =item usesitecustomize
844 Run-time customization of @INC can be enabled with:
846 sh Configure -Dusesitecustomize
848 which will define USE_SITECUSTOMIZE and $Config{usesitecustomize}.
849 When enabled, this makes perl run F<$sitelibexp/sitecustomize.pl> before
850 anything else. This script can then be set up to add additional
855 By default, man pages will be installed in $man1dir and $man3dir, which
856 are normally /usr/local/man/man1 and /usr/local/man/man3. If you
857 want to use a .3pm suffix for perl man pages, you can do that with
859 sh Configure -Dman3ext=3pm
861 You can disable installation of man pages completely using
863 sh Configure -Dman1dir=none -Dman3dir=none
867 Currently, the standard perl installation does not do anything with
868 HTML documentation, but that may change in the future. Further, some
869 add-on modules may wish to install HTML documents. The html Configure
870 variables listed above are provided if you wish to specify where such
871 documents should be placed. The default is "none", but will likely
872 eventually change to something useful based on user feedback.
876 Some users prefer to append a "/share" to $privlib and $sitelib
877 to emphasize that those directories can be shared among different
880 Note that these are just the defaults. You can actually structure the
881 directories any way you like. They don't even have to be on the same
884 Further details about the installation directories, maintenance and
885 development subversions, and about supporting multiple versions are
886 discussed in L<"Coexistence with earlier versions of perl 5"> below.
888 If you specify a prefix that contains the string "perl", then the
889 library directory structure is slightly simplified. Instead of
890 suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib.
892 Thus, for example, if you Configure with
893 -Dprefix=/opt/perl, then the default library directories for 5.9.0 are
895 Configure variable Default value
896 $privlib /opt/perl/lib/5.9.0
897 $archlib /opt/perl/lib/5.9.0/$archname
898 $sitelib /opt/perl/lib/site_perl/5.9.0
899 $sitearch /opt/perl/lib/site_perl/5.9.0/$archname
901 =head2 Changing the installation directory
903 Configure distinguishes between the directory in which perl (and its
904 associated files) should be installed, and the directory in which it
905 will eventually reside. For most sites, these two are the same; for
906 sites that use AFS, this distinction is handled automatically.
907 However, sites that use package management software such as rpm or
908 dpkg, or users building binary packages for distribution may also
909 wish to install perl into a different directory before moving perl
910 to its final destination. There are two ways to do that:
916 To install perl under the /tmp/perl5 directory, use the following
919 sh Configure -Dinstallprefix=/tmp/perl5
921 (replace /tmp/perl5 by a directory of your choice).
923 Beware, though, that if you go to try to install new add-on
924 modules, they too will get installed in under '/tmp/perl5' if you
925 follow this example. That's why it's usually better to use DESTDIR,
926 as shown in the next section.
930 If you need to install perl on many identical systems, it is convenient
931 to compile it once and create an archive that can be installed on
932 multiple systems. Suppose, for example, that you want to create an
933 archive that can be installed in /opt/perl. One way to do that is by
934 using the DESTDIR variable during C<make install>. The DESTDIR is
935 automatically prepended to all the installation paths. Thus you
938 sh Configure -Dprefix=/opt/perl -des
941 make install DESTDIR=/tmp/perl5
942 cd /tmp/perl5/opt/perl
943 tar cvf /tmp/perl5-archive.tar .
947 =head2 Relocatable @INC
949 To create a relocatable perl tree, use the following command line:
951 sh Configure -Duserelocatableinc
953 Then the paths in @INC (and everything else in %Config) can be
954 optionally located via the path of the perl executable.
956 That means that, if the string ".../" is found at the start of any
957 path, it's substituted with the directory of $^X. So, the relocation
958 can be configured on a per-directory basis, although the default with
959 "-Duserelocatableinc" is that everything is relocated. The initial
960 install is done to the original configured prefix.
962 This option is not compatible with the building of a shared libperl
963 ("-Duseshrplib"), because in that case perl is linked with an hard-coded
964 rpath that points at the libperl.so, that cannot be relocated.
966 =head2 Site-wide Policy settings
968 After Configure runs, it stores a number of common site-wide "policy"
969 answers (such as installation directories) in the Policy.sh file.
970 If you want to build perl on another system using the same policy
971 defaults, simply copy the Policy.sh file to the new system's perl build
972 directory, and Configure will use it. This will work even if Policy.sh was
973 generated for another version of Perl, or on a system with a
974 different architecture and/or operating system. However, in such cases,
975 you should review the contents of the file before using it: for
976 example, your new target may not keep its man pages in the same place
977 as the system on which the file was generated.
979 Alternatively, if you wish to change some or all of those policy
984 to ensure that Configure doesn't re-use them.
986 Further information is in the Policy_sh.SH file itself.
988 If the generated Policy.sh file is unsuitable, you may freely edit it
989 to contain any valid shell commands. It will be run just after the
990 platform-specific hints files.
992 =head2 Disabling older versions of Perl
994 Configure will search for binary compatible versions of previously
995 installed perl binaries in the tree that is specified as target tree,
996 and these will be used as locations to search for modules by the perl
997 being built. The list of perl versions found will be put in the Configure
998 variable inc_version_list.
1000 To disable this use of older perl modules, even completely valid pure
1001 perl modules, you can specify to not include the paths found:
1003 sh Configure -Dinc_version_list=none ...
1005 If you do want to use modules from some previous perl versions, the
1006 variable must contain a space separated list of directories under the
1007 site_perl directory, and has to include architecture-dependent
1008 directories separately, eg.
1010 sh Configure -Dinc_version_list="5.16.0/x86_64-linux 5.16.0" ...
1012 When using the newer perl, you can add these paths again in the
1013 PERL5LIB environment variable or with perl's -I runtime option.
1015 =head2 Building Perl outside of the source directory
1017 Sometimes it is desirable to build Perl in a directory different from
1018 where the sources are, for example if you want to keep your sources
1019 read-only, or if you want to share the sources between different binary
1020 architectures. You can do this (if your file system supports symbolic
1023 mkdir /tmp/perl/build/directory
1024 cd /tmp/perl/build/directory
1025 sh /path/to/perl/source/Configure -Dmksymlinks ...
1027 This will create in /tmp/perl/build/directory a tree of symbolic links
1028 pointing to files in /path/to/perl/source. The original files are left
1029 unaffected. After Configure has finished you can just say
1035 as usual, and Perl will be built in /tmp/perl/build/directory.
1037 =head2 Building a debugging perl
1039 You can run perl scripts under the perl debugger at any time with
1040 B<perl -d your_script>. If, however, you want to debug perl itself,
1041 you probably want to have support for perl internal debugging code
1042 (activated by adding -DDEBUGGING to ccflags), and/or support for the
1043 system debugger by adding -g to the optimisation flags.
1045 A perl compiled with the DEBUGGING C preprocessor macro will support the
1046 C<-D> perl command-line switch, have assertions enabled, and have many
1047 extra checks compiled into the code; but will execute much more slowly
1048 (typically 2-3x) and the binary will be much larger (typically 2-3x).
1050 As a convenience, debugging code (-DDEBUGGING) and debugging symbols (-g)
1051 can be enabled jointly or separately using a Configure switch, also
1052 (somewhat confusingly) named -DDEBUGGING. For a more eye appealing call,
1053 -DEBUGGING is defined to be an alias for -DDEBUGGING. For both, the -U
1054 calls are also supported, in order to be able to overrule the hints or
1057 Here are the DEBUGGING modes:
1061 =item Configure -DDEBUGGING
1063 =item Configure -DEBUGGING
1065 =item Configure -DEBUGGING=both
1067 Sets both -DDEBUGGING in the ccflags, and adds -g to optimize.
1069 You can actually specify -g and -DDEBUGGING independently (see below),
1070 but usually it's convenient to have both.
1072 =item Configure -DEBUGGING=-g
1074 =item Configure -Doptimize=-g
1076 Adds -g to optimize, but does not set -DDEBUGGING.
1078 (Note: Your system may actually require something like cc -g2.
1079 Check your man pages for cc(1) and also any hint file for your system.)
1081 =item Configure -DEBUGGING=none
1083 =item Configure -UDEBUGGING
1085 Removes -g from optimize, and -DDEBUGGING from ccflags.
1089 If you are using a shared libperl, see the warnings about multiple
1090 versions of perl under L</Building a shared Perl library>.
1092 Note that a perl built with -DDEBUGGING will be much bigger and will run
1093 much, much more slowly than a standard perl.
1095 =head2 DTrace support
1097 On platforms where DTrace is available, it may be enabled by
1098 using the -Dusedtrace option to Configure. DTrace probes are available
1099 for subroutine entry (sub-entry) and subroutine exit (sub-exit). Here's a
1100 simple D script that uses them:
1102 perl$target:::sub-entry, perl$target:::sub-return {
1103 printf("%s %s (%s:%d)\n", probename == "sub-entry" ? "->" : "<-",
1104 copyinstr(arg0), copyinstr(arg1), arg2);
1110 Perl ships with a number of standard extensions. These are contained
1111 in the F<ext/> subdirectory.
1113 By default, Configure will offer to build every extension which appears
1114 to be supported. For example, Configure will offer to build GDBM_File
1115 only if it is able to find the gdbm library.
1117 To disable certain extensions so that they are not built, use the
1118 -Dnoextensions=... and -Donlyextensions=... options. They both accept
1119 a space-separated list of extensions, such as C<IPC/SysV>. The extensions
1121 C<noextensions> are removed from the list of extensions to build, while
1122 the C<onlyextensions> is rather more severe and builds only the listed
1123 extensions. The latter should be used with extreme caution since
1124 certain extensions are used by many other extensions and modules:
1125 examples of such modules include Fcntl and IO. The order of processing
1126 these options is first C<only> (if present), then C<no> (if present).
1128 Of course, you may always run Configure interactively and select only
1129 the extensions you want.
1131 If you unpack any additional extensions in the ext/ directory before
1132 running Configure, then Configure will offer to build those additional
1133 extensions as well. Most users probably shouldn't have to do this --
1134 it is usually easier to build additional extensions later after perl
1135 has been installed. However, if you wish to have those additional
1136 extensions statically linked into the perl binary, then this offers a
1137 convenient way to do that in one step. (It is not necessary, however;
1138 you can build and install extensions just fine even if you don't have
1139 dynamic loading. See lib/ExtUtils/MakeMaker.pm for more details.)
1140 Another way of specifying extra modules is described in
1141 L<"Adding extra modules to the build"> below.
1143 If you re-use an old config.sh but change your system (e.g. by
1144 adding libgdbm) Configure will still offer your old choices of extensions
1145 for the default answer, but it will also point out the discrepancy to
1148 =head2 Including locally-installed libraries
1150 Perl comes with interfaces to number of libraries, including threads,
1151 dbm, ndbm, gdbm, and Berkeley db. For the *db* extension, if
1152 Configure can find the appropriate header files and libraries, it will
1153 automatically include that extension. The threading extension needs
1154 to be specified explicitly (see L</Threads>).
1156 Those libraries are not distributed with perl. If your header (.h) files
1157 for those libraries are not in a directory normally searched by your C
1158 compiler, then you will need to include the appropriate -I/your/directory
1159 option when prompted by Configure. If your libraries are not in a
1160 directory normally searched by your C compiler and linker, then you will
1161 need to include the appropriate -L/your/directory option when prompted
1162 by Configure. See the examples below.
1168 =item gdbm in /usr/local
1170 Suppose you have gdbm and want Configure to find it and build the
1171 GDBM_File extension. This example assumes you have gdbm.h
1172 installed in /usr/local/include/gdbm.h and libgdbm.a installed in
1173 /usr/local/lib/libgdbm.a. Configure should figure all the
1174 necessary steps out automatically.
1176 Specifically, when Configure prompts you for flags for
1177 your C compiler, you should include -I/usr/local/include, if it's
1178 not here yet. Similarly, when Configure prompts you for linker flags,
1179 you should include -L/usr/local/lib.
1181 If you are using dynamic loading, then when Configure prompts you for
1182 linker flags for dynamic loading, you should again include
1185 Again, this should all happen automatically. This should also work if
1186 you have gdbm installed in any of (/usr/local, /opt/local, /usr/gnu,
1187 /opt/gnu, /usr/GNU, or /opt/GNU).
1189 =item BerkeleyDB in /usr/local/BerkeleyDB
1191 The version of BerkeleyDB distributed by Oracle installs in a
1192 version-specific directory by default, typically something like
1193 /usr/local/BerkeleyDB.4.7. To have Configure find that, you need to add
1194 -I/usr/local/BerkeleyDB.4.7/include to cc flags, as in the previous
1195 example, and you will also have to take extra steps to help Configure
1196 find -ldb. Specifically, when Configure prompts you for library
1197 directories, add /usr/local/BerkeleyDB.4.7/lib to the list. Also, you
1198 will need to add appropriate linker flags to tell the runtime linker
1199 where to find the BerkeleyDB shared libraries.
1201 It is possible to specify this from the command line (all on one
1205 -Dlocincpth='/usr/local/BerkeleyDB.4.7/include \
1206 /usr/local/include' \
1207 -Dloclibpth='/usr/local/BerkeleyDB.4.7/lib /usr/local/lib' \
1208 -Aldflags='-R/usr/local/BerkeleyDB.4.7/lib'
1210 locincpth is a space-separated list of include directories to search.
1211 Configure will automatically add the appropriate -I directives.
1213 loclibpth is a space-separated list of library directories to search.
1214 Configure will automatically add the appropriate -L directives.
1216 The addition to ldflags is so that the dynamic linker knows where to find
1217 the BerkeleyDB libraries. For Linux and Solaris, the -R option does that.
1218 Other systems may use different flags. Use the appropriate flag for your
1223 =head2 Specifying a logical root directory
1225 If you are cross-compiling, or are using a compiler which has it's own
1226 headers and libraries in a nonstandard location, and your compiler
1227 understands the C<--sysroot> option, you can use the C<-Dsysroot> option
1228 to specify the logical root directory under which all libraries and
1229 headers are searched for. This patch adjusts Configure to search under
1230 $sysroot, instead of /.
1232 --sysroot is added to ccflags and friends so that make in
1233 ExtUtils::MakeMaker, and other extensions, will use it.
1235 =head2 Overriding an old config.sh
1237 If you want to use an old config.sh produced by a previous run of
1238 Configure, but override some of the items with command line options, you
1239 need to use B<Configure -O>.
1241 =head2 GNU-style configure
1243 If you prefer the GNU-style configure command line interface, you can
1244 use the supplied configure.gnu command, e.g.
1246 CC=gcc ./configure.gnu
1248 The configure.gnu script emulates a few of the more common configure
1251 ./configure.gnu --help
1255 (The file is called configure.gnu to avoid problems on systems
1256 that would not distinguish the files "Configure" and "configure".)
1258 =head2 Malloc Issues
1260 Perl relies heavily on malloc(3) to grow data structures as needed,
1261 so perl's performance can be noticeably affected by the performance of
1262 the malloc function on your system. The perl source is shipped with a
1263 version of malloc that has been optimized for the typical requests from
1264 perl, so there's a chance that it may be both faster and use less memory
1265 than your system malloc.
1267 However, if your system already has an excellent malloc, or if you are
1268 experiencing difficulties with extensions that use third-party libraries
1269 that call malloc, then you should probably use your system's malloc.
1270 (Or, you might wish to explore the malloc flags discussed below.)
1274 =item Using the system malloc
1276 To build without perl's malloc, you can use the Configure command
1278 sh Configure -Uusemymalloc
1280 or you can answer 'n' at the appropriate interactive Configure prompt.
1282 Note that Perl's malloc isn't always used by default; that actually
1283 depends on your system. For example, on Linux and FreeBSD (and many more
1284 systems), Configure chooses to use the system's malloc by default.
1285 See the appropriate file in the F<hints/> directory to see how the
1288 =item -DPERL_POLLUTE_MALLOC
1290 NOTE: This flag is enabled automatically on some platforms if you just
1291 run Configure to accept all the defaults.
1293 Perl's malloc family of functions are normally called Perl_malloc(),
1294 Perl_realloc(), Perl_calloc() and Perl_mfree().
1295 These names do not clash with the system versions of these functions.
1297 If this flag is enabled, however, Perl's malloc family of functions
1298 will have the same names as the system versions. This may be required
1299 sometimes if you have libraries that like to free() data that may have
1300 been allocated by Perl_malloc() and vice versa.
1302 Note that enabling this option may sometimes lead to duplicate symbols
1303 from the linker for malloc et al. In such cases, the system probably
1304 does not allow its malloc functions to be fully replaced with custom
1307 =item -DPERL_DEBUGGING_MSTATS
1309 This flag enables debugging mstats, which is required to use the
1310 Devel::Peek::mstat() function. You cannot enable this unless you are
1311 using Perl's malloc, so a typical Configure command would be
1313 sh Configure -Accflags=-DPERL_DEBUGGING_MSTATS -Dusemymalloc
1315 to enable this option.
1319 =head2 What if it doesn't work?
1321 If you run into problems, try some of the following ideas.
1322 If none of them help, then see L<"Reporting Problems"> below.
1326 =item Running Configure Interactively
1328 If Configure runs into trouble, remember that you can always run
1329 Configure interactively so that you can check (and correct) its
1332 All the installation questions have been moved to the top, so you don't
1333 have to wait for them. Once you've handled them (and your C compiler and
1334 flags) you can type &-d at the next Configure prompt and Configure
1335 will use the defaults from then on.
1337 If you find yourself trying obscure command line incantations and
1338 config.over tricks, I recommend you run Configure interactively
1339 instead. You'll probably save yourself time in the long run.
1343 Hint files tell Configure about a number of things:
1349 The peculiarities or conventions of particular platforms -- non-standard
1350 library locations and names, default installation locations for binaries,
1355 The deficiencies of the platform -- for example, library functions that,
1356 although present, are too badly broken to be usable; or limits on
1357 resources that are generously available on most platforms.
1361 How best to optimize for the platform, both in terms of binary size
1362 and/or speed, and for Perl feature support. Because of wide variations in
1363 the implementation of shared libraries and of threading, for example,
1364 Configure often needs hints in order to be able to use these features.
1368 The perl distribution includes many system-specific hints files
1369 in the hints/ directory. If one of them matches your system, Configure
1370 will offer to use that hint file. Unless you have a very good reason
1371 not to, you should accept its offer.
1373 Several of the hint files contain additional important information.
1374 If you have any problems, it is a good idea to read the relevant hint
1375 file for further information. See hints/solaris_2.sh for an extensive
1376 example. More information about writing good hints is in the
1377 hints/README.hints file, which also explains hint files known as
1380 Note that any hint file is read before any Policy file, meaning that
1381 Policy overrides hints -- see L</Site-wide Policy settings>.
1385 If you are re-using an old config.sh, it's possible that Configure
1386 detects different values from the ones specified in this file. You will
1387 almost always want to keep the previous value, unless you have changed
1388 something on your system.
1390 For example, suppose you have added libgdbm.a to your system
1391 and you decide to reconfigure perl to use GDBM_File. When you run
1392 Configure again, you will need to add -lgdbm to the list of libraries.
1393 Now, Configure will find your gdbm include file and library and will
1396 *** WHOA THERE!!! ***
1397 The previous value for $i_gdbm on this machine was "undef"!
1398 Keep the previous value? [y]
1400 In this case, you do not want to keep the previous value, so you
1401 should answer 'n'. (You'll also have to manually add GDBM_File to
1402 the list of dynamic extensions to build.)
1404 =item Changing Compilers
1406 If you change compilers or make other significant changes, you should
1407 probably not re-use your old config.sh. Simply remove it or
1408 rename it, then rerun Configure with the options you want to use.
1410 =item Propagating your changes to config.sh
1412 If you make any changes to config.sh, you should propagate
1413 them to all the .SH files by running
1417 You will then have to rebuild by running
1422 =item config.over and config.arch
1424 You can also supply a shell script config.over to override
1425 Configure's guesses. It will get loaded up at the very end, just
1426 before config.sh is created. You have to be careful with this,
1427 however, as Configure does no checking that your changes make sense.
1428 This file is usually good for site-specific customizations.
1430 There is also another file that, if it exists, is loaded before the
1431 config.over, called config.arch. This file is intended to be per
1432 architecture, not per site, and usually it's the architecture-specific
1433 hints file that creates the config.arch.
1437 Many of the system dependencies are contained in config.h.
1438 Configure builds config.h by running the config_h.SH script.
1439 The values for the variables are taken from config.sh.
1441 If there are any problems, you can edit config.h directly. Beware,
1442 though, that the next time you run Configure, your changes will be
1447 If you have any additional changes to make to the C compiler command
1448 line, they can be made in cflags.SH. For instance, to turn off the
1449 optimizer on toke.c, find the switch structure marked 'or customize here',
1450 and add a line for toke.c ahead of the catch-all *) so that it now reads:
1455 toke) optimize='-g' ;;
1458 You should not edit the generated file cflags directly, as your changes
1459 will be lost the next time you run Configure, or if you edit config.sh.
1461 To explore various ways of changing ccflags from within a hint file,
1462 see the file hints/README.hints.
1464 To change the C flags for all the files, edit config.sh and change either
1465 $ccflags or $optimize, and then re-run
1472 If you don't have sh, you'll have to copy the sample file
1473 Porting/config.sh to config.sh and edit your config.sh to reflect your
1474 system's peculiarities. See Porting/pumpkin.pod for more information.
1475 You'll probably also have to extensively modify the extension building
1478 =item Porting information
1480 Specific information for the OS/2, Plan 9, VMS and Win32 ports is in the
1481 corresponding README files and subdirectories. Additional information,
1482 including a glossary of all those config.sh variables, is in the Porting
1483 subdirectory. Porting/Glossary should especially come in handy.
1485 Ports for other systems may also be available. You should check out
1486 L<https://www.cpan.org/ports> for current information on ports to
1487 various other operating systems.
1489 If you plan to port Perl to a new architecture, study carefully the
1490 section titled "Philosophical Issues in Patching and Porting Perl"
1491 in the file Porting/pumpkin.pod and the file pod/perlgit.pod.
1492 Study also how other non-UNIX ports have solved problems.
1496 =head2 Adding extra modules to the build
1498 You can specify extra modules or module bundles to be fetched from the
1499 CPAN and installed as part of the Perl build. Either use the -Dextras=...
1500 command line parameter to Configure, for example like this:
1502 Configure -Dextras="Bundle::LWP DBI"
1504 or answer first 'y' to the question 'Install any extra modules?' and
1505 then answer "Bundle::LWP DBI" to the 'Extras?' question.
1506 The module or the bundle names are as for the CPAN module 'install'
1507 command. This will only work if those modules are to be built as dynamic
1508 extensions. If you wish to include those extra modules as static
1509 extensions, see L<"Extensions"> above.
1511 Notice that because the CPAN module will be used to fetch the extra
1512 modules, you will need access to the CPAN, either via the Internet,
1513 or via a local copy such as a CD-ROM or a local CPAN mirror. If you
1514 do not, using the extra modules option will die horribly.
1516 Also notice that you yourself are responsible for satisfying any extra
1517 dependencies such as external headers or libraries BEFORE trying the
1518 build. For example: you will need to have the Foo database specific
1519 headers and libraries installed for the DBD::Foo module. The Configure
1520 process or the Perl build process will not help you with these.
1524 suidperl was an optional component of earlier releases of perl. It is no
1525 longer available. Instead, use a tool specifically designed to handle
1526 changes in privileges, such as B<sudo>.
1530 This will look for all the includes. The output is stored in makefile.
1531 The only difference between Makefile and makefile is the dependencies at
1532 the bottom of makefile. If you have to make any changes, you should edit
1533 makefile, not Makefile, since the Unix make command reads makefile first.
1534 (On non-Unix systems, the output may be stored in a different file.
1535 Check the value of $firstmakefile in your config.sh if in doubt.)
1537 Configure will offer to do this step for you, so it isn't listed
1542 This will attempt to make perl in the current directory.
1544 =head2 Expected errors
1546 These error reports are normal, and can be ignored:
1549 make: [extra.pods] Error 1 (ignored)
1551 make: [extras.make] Error 1 (ignored)
1553 =head2 What if it doesn't work?
1555 If you can't compile successfully, try some of the following ideas.
1556 If none of them help, and careful reading of the error message and
1557 the relevant manual pages on your system doesn't help,
1558 then see L<"Reporting Problems"> below.
1564 If you used a hint file, try reading the comments in the hint file
1565 for further tips and information.
1569 If you can successfully build miniperl, but the process crashes
1570 during the building of extensions, run
1574 to test your version of miniperl.
1578 If you have any locale-related environment variables set, try unsetting
1579 them. I have some reports that some versions of IRIX hang while
1580 running B<./miniperl configpm> with locales other than the C locale.
1581 See the discussion under L<"make test"> below about locales and the
1582 whole L<perllocale/"LOCALE PROBLEMS"> section in the file
1583 pod/perllocale.pod. The latter is especially useful if you see something
1586 perl: warning: Setting locale failed.
1587 perl: warning: Please check that your locale settings:
1590 are supported and installed on your system.
1591 perl: warning: Falling back to the standard locale ("C").
1595 =item other environment variables
1597 Configure does not check for environment variables that can sometimes
1598 have a major influence on how perl is built or tested. For example,
1599 OBJECT_MODE on AIX determines the way the compiler and linker deal with
1600 their objects, but this is a variable that only influences build-time
1601 behaviour, and should not affect the perl scripts that are eventually
1602 executed by the perl binary. Other variables, like PERL_UNICODE,
1603 PERL5LIB, and PERL5OPT will influence the behaviour of the test suite.
1604 So if you are getting strange test failures, you may want to try
1605 retesting with the various PERL variables unset.
1607 =item LD_LIBRARY_PATH
1609 If you run into dynamic loading problems, check your setting of
1610 the LD_LIBRARY_PATH environment variable (or on some systems the equivalent
1611 with a different name, see L</Building a shared Perl library>). If you're
1612 creating a static Perl library (libperl.a rather than libperl.so) it should
1613 build fine with LD_LIBRARY_PATH unset, though that may depend on details of
1618 If Configure seems to be having trouble finding library functions,
1619 try not using nm extraction. You can do this from the command line
1622 sh Configure -Uusenm
1624 or by answering the nm extraction question interactively.
1625 If you have previously run Configure, you should not reuse your old
1628 =item umask not found
1630 If the build processes encounters errors relating to umask(), the problem
1631 is probably that Configure couldn't find your umask() system call.
1632 Check your config.sh. You should have d_umask='define'. If you don't,
1633 this is probably the L<"nm extraction"> problem discussed above. Also,
1634 try reading the hints file for your system for further information.
1638 If you run into problems relating to do_aspawn or do_spawn, the
1639 problem is probably that Configure failed to detect your system's
1640 fork() function. Follow the procedure in the previous item
1641 on L<"nm extraction">.
1643 =item __inet_* errors
1645 If you receive unresolved symbol errors during Perl build and/or test
1646 referring to __inet_* symbols, check to see whether BIND 8.1 is
1647 installed. It installs a /usr/local/include/arpa/inet.h that refers to
1648 these symbols. Versions of BIND later than 8.1 do not install inet.h
1649 in that location and avoid the errors. You should probably update to a
1650 newer version of BIND (and remove the files the old one left behind).
1651 If you can't, you can either link with the updated resolver library
1652 provided with BIND 8.1 or rename /usr/local/bin/arpa/inet.h during the
1653 Perl build and test process to avoid the problem.
1655 =item .*_r() prototype NOT found
1657 On a related note, if you see a bunch of complaints like the above about
1658 reentrant functions -- specifically networking-related ones -- being
1659 present but without prototypes available, check to see if BIND 8.1 (or
1660 possibly other BIND 8 versions) is (or has been) installed. They install
1661 header files such as netdb.h into places such as /usr/local/include (or
1662 into another directory as specified at build/install time), at least
1663 optionally. Remove them or put them in someplace that isn't in the C
1664 preprocessor's header file include search path (determined by -I options
1665 plus defaults, normally /usr/include).
1667 =item #error "No DATAMODEL_NATIVE specified"
1669 This is a common error when trying to build perl on Solaris 2.6 with a
1670 gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files
1671 changed, so you need to update your gcc installation. You can either
1672 rerun the fixincludes script from gcc or take the opportunity to
1673 update your gcc installation.
1677 If you can't compile successfully, try turning off your compiler's
1678 optimizer. Edit config.sh and change the line
1686 then propagate your changes with B<sh Configure -S> and rebuild
1687 with B<make depend; make>.
1689 =item Missing functions and Undefined symbols
1691 If the build of miniperl fails with a long list of missing functions or
1692 undefined symbols, check the libs variable in the config.sh file. It
1693 should look something like
1695 libs='-lsocket -lnsl -ldl -lm -lc'
1697 The exact libraries will vary from system to system, but you typically
1698 need to include at least the math library -lm. Normally, Configure
1699 will suggest the correct defaults. If the libs variable is empty, you
1700 need to start all over again. Run
1704 and start from the very beginning. This time, unless you are sure of
1705 what you are doing, accept the default list of libraries suggested by
1708 If the libs variable is missing -lm, there is a chance that libm.so.1
1709 is available, but the required (symbolic) link to libm.so is missing.
1710 (same could be the case for other libraries like libcrypt.so). You
1711 should check your installation for packages that create that link, and
1712 if no package is installed that supplies that link or you cannot install
1713 them, make the symbolic link yourself e.g.:
1715 $ rpm -qf /usr/lib64/libm.so
1716 glibc-devel-2.15-22.17.1.x86_64
1717 $ ls -lgo /usr/lib64/libm.so
1718 lrwxrwxrwx 1 16 Jan 7 2013 /usr/lib64/libm.so -> /lib64/libm.so.6
1722 $ sudo ln -s /lib64/libm.so.6 /lib64/libm.so
1724 If the libs variable looks correct, you might have the
1725 L<"nm extraction"> problem discussed above.
1727 If you still have missing routines or undefined symbols, you probably
1728 need to add some library or other, make a symbolic link like described
1729 above, or you need to undefine some feature that Configure thought was
1730 there but is defective or incomplete. If you used a hint file, see if
1731 it has any relevant advice. You can also look through config.h
1732 for likely suspects.
1736 Some compilers will not compile or optimize the larger files (such as
1737 toke.c) without some extra switches to use larger jump offsets or
1738 allocate larger internal tables. You can customize the switches for
1739 each file in cflags.SH. It's okay to insert rules for specific files
1740 into makefile since a default rule only takes effect in the absence of a
1743 =item Missing dbmclose
1745 SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
1746 that includes libdbm.nfs (which includes dbmclose()) may be available.
1748 =item error: too few arguments to function 'dbmclose'
1750 Building ODBM_File on some (Open)SUSE distributions might run into this
1751 error, as the header file is broken. There are two ways to deal with this
1753 1. Disable the use of ODBM_FILE
1755 sh Configure ... -Dnoextensions=ODBM_File
1757 2. Fix the header file, somewhat like this:
1759 --- a/usr/include/dbm.h 2010-03-24 08:54:59.000000000 +0100
1760 +++ b/usr/include/dbm.h 2010-03-24 08:55:15.000000000 +0100
1761 @@ -59,4 +59,4 @@ extern datum firstkey __P((void));
1763 extern datum nextkey __P((datum key));
1765 -extern int dbmclose __P((DBM *));
1766 +extern int dbmclose __P((void));
1768 =item Warning (mostly harmless): No library found for -lsomething
1770 If you see such a message during the building of an extension, but
1771 the extension passes its tests anyway (see L<"make test"> below),
1772 then don't worry about the warning message. The extension
1773 Makefile.PL goes looking for various libraries needed on various
1774 systems; few systems will need all the possible libraries listed.
1775 Most users will see warnings for the ones they don't have. The
1776 phrase 'mostly harmless' is intended to reassure you that nothing
1777 unusual is happening, and the build process is continuing.
1779 On the other hand, if you are building GDBM_File and you get the
1782 Warning (mostly harmless): No library found for -lgdbm
1784 then it's likely you're going to run into trouble somewhere along
1785 the line, since it's hard to see how you can use the GDBM_File
1786 extension without the -lgdbm library.
1788 It is true that, in principle, Configure could have figured all of
1789 this out, but Configure and the extension building process are not
1790 quite that tightly coordinated.
1792 =item sh: ar: not found
1794 This is a message from your shell telling you that the command 'ar'
1795 was not found. You need to check your PATH environment variable to
1796 make sure that it includes the directory with the 'ar' command. This
1797 is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
1800 =item db-recno failure on tests 51, 53 and 55
1802 Old versions of the DB library (including the DB library which comes
1803 with FreeBSD 2.1) had broken handling of recno databases with modified
1804 bval settings. Upgrade your DB library or OS.
1806 =item Bad arg length for semctl, is XX, should be ZZZ
1808 If you get this error message from the F<cpan/IPC-SysV/t/sem.t> test, your
1809 System V IPC may be broken. The XX typically is 20, and that is what ZZZ
1810 also should be. Consider upgrading your OS, or reconfiguring your OS
1811 to include the System V semaphores.
1813 =item cpan/IPC-SysV/t/sem........semget: No space left on device
1815 Either your account or the whole system has run out of semaphores. Or
1816 both. Either list the semaphores with "ipcs" and remove the unneeded
1817 ones (which ones these are depends on your system and applications)
1818 with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
1823 If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
1824 tools you may be in for some trouble. For example creating archives
1825 with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
1826 may lead into linking problems. Either recompile your GNU binutils
1827 under your current operating system release, or modify your PATH not
1828 to include the GNU utils before running Configure, or specify the
1829 vendor-supplied utilities explicitly to Configure, for example by
1830 Configure -Dar=/bin/ar.
1832 =item THIS PACKAGE SEEMS TO BE INCOMPLETE
1834 The F<Configure> program has not been able to find all the files which
1835 make up the complete Perl distribution. You may have a damaged source
1836 archive file (in which case you may also have seen messages such as
1837 C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on
1838 archive file>), or you may have obtained a structurally-sound but
1839 incomplete archive. In either case, try downloading again from the
1840 official site named at the start of this document. If you do find
1841 that any site is carrying a corrupted or incomplete source code
1842 archive, please report it to the site's maintainer.
1844 =item invalid token: ##
1846 You are using a non-ANSI-compliant C compiler. To compile Perl, you
1847 need to use a compiler that supports ANSI C. If there is a README
1848 file for your system, it may have further details on your compiler
1853 Some additional things that have been reported:
1855 Genix may need to use libc rather than libc_s, or #undef VARARGS.
1857 NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
1859 UTS may need one or more of -K or -g, and #undef LSTAT.
1861 FreeBSD can fail the F<cpan/IPC-SysV/t/sem.t> test if SysV IPC has not been
1862 configured in the kernel. Perl tries to detect this, though, and
1863 you will get a message telling you what to do.
1865 Building Perl on a system that has also BIND (headers and libraries)
1866 installed may run into troubles because BIND installs its own netdb.h
1867 and socket.h, which may not agree with the operating system's ideas of
1868 the same files. Similarly, including -lbind may conflict with libc's
1869 view of the world. You may have to tweak -Dlocincpth and -Dloclibpth
1874 =head2 Cross-compilation
1876 Perl can be cross-compiled. It is just not trivial, cross-compilation
1877 rarely is. Perl is routinely cross-compiled for several platforms: as of
1878 June 2019, these include Android, Blackberry 10,
1879 ARM Linux, and Solaris. Previous versions of
1880 Perl also provided support for Open Zaurus, Symbian, and
1881 the IBM OS/400, but it's unknown if those ports are still functional.
1882 These platforms are known as the B<target> platforms, while the systems
1883 where the compilation takes place are the B<host> platforms.
1885 What makes the situation difficult is that first of all,
1886 cross-compilation environments vary significantly in how they are set
1887 up and used, and secondly because the primary way of configuring Perl
1888 (using the rather large Unix-tool-dependent Configure script) is not
1889 awfully well suited for cross-compilation. However, starting from
1890 version 5.18.0, the Configure script also knows two ways of supporting
1891 cross-compilation, so please keep reading.
1893 See the following files for more information about compiling Perl for
1894 the particular platforms:
1900 L<"Cross-compilation" in README.android or
1901 perlandroid|perlandroid/Cross-compilation>
1905 L<"Cross-compilation" in README.qnx or perlqnx|perlqnx/Cross-compilation>
1909 L<"CROSS-COMPILATION" in README.solaris or
1910 perlsolaris|perlsolaris/CROSS-COMPILATION>
1914 This document; See below.
1918 Packaging and transferring either the core Perl modules or CPAN
1919 modules to the target platform is also left up to the each
1920 cross-compilation environment. Often the cross-compilation target
1921 platforms are somewhat limited in diskspace: see the section
1922 L</Minimizing the Perl installation> to learn more of the minimal set
1923 of files required for a functional Perl installation.
1925 For some cross-compilation environments the Configure option
1926 C<-Dinstallprefix=...> might be handy, see L</Changing the installation
1929 About the cross-compilation support of Configure: There's two forms.
1930 The more common one requires some way of transferring and running
1931 executables in the target system, such as an ssh connection; this is the
1932 C<./Configure -Dusecrosscompile -Dtargethost=...> route. The second
1933 method doesn't need access to the target system, but requires you to
1934 provide a config.sh, and a canned Makefile; the rest of this section
1935 describes the former.
1937 This cross-compilation setup of Configure has successfully been used in
1938 a wide variety of setups, such as a 64-bit OS X host for an Android ARM
1939 target, or an amd64 Linux host targeting x86 Solaris, or even Windows.
1941 To run Configure in cross-compilation mode the basic switch that
1942 has to be used is C<-Dusecrosscompile>:
1944 sh ./Configure -des -Dusecrosscompile -D...
1946 This will make the cpp symbol USE_CROSS_COMPILE and the %Config
1947 symbol C<usecrosscompile> available.
1949 During the Configure and build, certain helper scripts will be created
1950 into the Cross/ subdirectory. The scripts are used to execute a
1951 cross-compiled executable, and to transfer files to and from the
1952 target host. The execution scripts are named F<run-*> and the
1953 transfer scripts F<to-*> and F<from-*>. The part after the dash is
1954 the method to use for remote execution and transfer: by default the
1955 methods are B<ssh> and B<scp>, thus making the scripts F<run-ssh>,
1956 F<to-scp>, and F<from-scp>.
1958 To configure the scripts for a target host and a directory (in which
1959 the execution will happen and which is to and from where the transfer
1960 happens), supply Configure with
1962 -Dtargethost=so.me.ho.st -Dtargetdir=/tar/get/dir
1964 The targethost is what e.g. ssh will use as the hostname, the targetdir
1965 must exist (the scripts won't create it), the targetdir defaults to /tmp.
1966 You can also specify a username to use for ssh/rsh logins
1970 but in case you don't, "root" will be used. Similarly, you can specify
1971 a non-standard (i.e. not 22) port for the connection, if applicable,
1976 If the name of C<cc> has the usual GNU C semantics for cross
1977 compilers, that is, CPU-OS-gcc, the target architecture (C<targetarch>),
1978 plus names of the C<ar>, C<nm>, and C<ranlib> will also be automatically
1979 chosen to be CPU-OS-ar and so on.
1980 (The C<ld> requires more thought and will be chosen later by Configure
1981 as appropriate). This will also aid in guessing the proper
1982 operating system name for the target, which has other repercussions, like
1983 better defaults and possibly critical fixes for the platform. If
1984 Configure isn't guessing the OS name properly, you may need to either add
1985 a hint file redirecting Configure's guess, or modify Configure to make
1988 If your compiler doesn't follow that convention, you will also need to
1989 specify which target environment to use, as well as C<ar> and friends:
1991 -Dtargetarch=arm-linux
1995 Additionally, a cross-compilation toolchain will usually install it's own
1996 logical system root somewhere -- that is, it'll create a directory
1997 somewhere which includes subdirectories like C<'include'> or C<'lib'>. For
1998 example, you may end up with F</skiff/local/arm-linux>, where
1999 F</skiff/local/arm-linux/bin> holds the binaries for cross-compilation,
2000 F</skiff/local/arm-linux/include> has the headers, and
2001 F</skiff/local/arm-linux/lib> has the library files.
2002 If this is the case, and you are using a compiler that understands
2003 C<--sysroot>, like gcc or clang, you'll want to specify the
2004 C<-Dsysroot> option for Configure:
2006 -Dsysroot=/skiff/local/arm-linux
2008 However, if your don't have a suitable directory to pass to C<-Dsysroot>,
2009 you will also need to specify which target environment to use:
2011 -Dusrinc=/skiff/local/arm-linux/include
2012 -Dincpth=/skiff/local/arm-linux/include
2013 -Dlibpth=/skiff/local/arm-linux/lib
2015 In addition to the default execution/transfer methods you can also
2016 choose B<rsh> for execution, and B<rcp> or B<cp> for transfer,
2019 -Dtargetrun=rsh -Dtargetto=rcp -Dtargetfrom=cp
2021 Putting it all together:
2023 sh ./Configure -des -Dusecrosscompile \
2024 -Dtargethost=so.me.ho.st \
2025 -Dtargetdir=/tar/get/dir \
2027 -Dtargetarch=arm-linux \
2028 -Dcc=arm-linux-gcc \
2029 -Dsysroot=/skiff/local/arm-linux \
2032 or if you are happy with the defaults:
2034 sh ./Configure -des -Dusecrosscompile \
2035 -Dtargethost=so.me.ho.st \
2036 -Dcc=arm-linux-gcc \
2039 Another example where the cross-compiler has been installed under
2040 F</usr/local/arm/2.95.5>:
2042 sh ./Configure -des -Dusecrosscompile \
2043 -Dtargethost=so.me.ho.st \
2044 -Dcc=/usr/local/arm/2.95.5/bin/arm-linux-gcc \
2045 -Dsysroot=/usr/local/arm/2.95.5
2047 There is also a C<targetenv> option for Configure which can be used
2048 to modify the environment of the target just before testing begins
2049 during 'make test'. For example, if the target system has a nonstandard
2050 /tmp location, you could do this:
2052 -Dtargetenv="export TMPDIR=/other/tmp;"
2054 If you are planning on cross-compiling to several platforms, or some
2055 other thing that would involve running Configure several times, there are
2056 two options that can be used to speed things up considerably.
2057 As a bit of background, when you
2058 call Configure with C<-Dusecrosscompile>, it begins by actually partially
2059 building a miniperl on the host machine, as well as the generate_uudmap
2060 binary, and we end up using that during the build.
2061 So instead of building that new perl every single time, you can build it
2062 just once in a separate directory, and then pass the resulting binaries
2063 to Configure like this:
2065 -Dhostperl=/path/to/second/build/dir/miniperl
2066 -Dhostgenerate=/path/to/second/build/dir/generate_uudmap
2068 Much less commonly, if you are cross-compiling from an ASCII host to an
2069 EBCDIC target, or vise versa, you'll have to pass C<-Uhostgenerate> to
2070 Configure, to signify that you want to build a generate_uudmap binary
2071 that, during make, will be run on the target system.
2075 This will run the regression tests on the perl you just made. If
2076 'make test' doesn't say "All tests successful" then something went
2079 Note that you can't run the tests in background if this disables
2080 opening of /dev/tty. You can use 'make test-notty' in that case but
2081 a few tty tests will be skipped.
2083 =head2 What if make test doesn't work?
2085 If make test bombs out, just cd to the t directory and run ./TEST
2086 by hand to see if it makes any difference.
2088 One way to get more detailed information about failed tests and
2089 individual subtests is to run the harness from the t directory:
2091 cd t ; ./perl harness <list of tests>
2093 (this assumes that most basic tests succeed, since harness uses
2094 complicated constructs). If no list of tests is provided, harness
2097 If individual tests fail, you can often run them by hand (from the main
2098 perl directory), e.g.,
2100 ./perl -I. -MTestInit t/op/groups.t
2102 You should also read the individual tests to see if there are any helpful
2103 comments that apply to your system. You may also need to setup your
2104 shared library path if you get errors like:
2106 /sbin/loader: Fatal Error: cannot map libperl.so
2108 The file t/README in the t subdirectory contains more information about
2109 running and modifying tests.
2111 See L</"Building a shared Perl library"> earlier in this document.
2117 Note: One possible reason for errors is that some external programs
2118 may be broken due to the combination of your environment and the way
2119 'make test' exercises them. For example, this may happen if you have
2120 one or more of these environment variables set: LC_ALL LC_CTYPE
2121 LC_COLLATE LANG. In some versions of UNIX, the non-English locales
2122 are known to cause programs to exhibit mysterious errors.
2124 If you have any of the above environment variables set, please try
2130 LC_ALL=C;export LC_ALL
2132 for Bourne or Korn shell) from the command line and then retry
2133 make test. If the tests then succeed, you may have a broken program that
2134 is confusing the testing. Please run the troublesome test by hand as
2135 shown above and see whether you can locate the program. Look for
2136 things like: exec, `backquoted command`, system, open("|...") or
2137 open("...|"). All these mean that Perl is trying to run some
2140 =item Timing problems
2142 Several tests in the test suite check timing functions, such as
2143 sleep(), and see if they return in a reasonable amount of time.
2144 If your system is quite busy and doesn't respond quickly enough,
2145 these tests might fail. If possible, try running the tests again
2146 with the system under a lighter load. These timing-sensitive
2147 and load-sensitive tests include F<t/op/alarm.t>,
2148 F<dist/Time-HiRes/t/alarm.t>, F<dist/Time-HiRes/t/clock.t>,
2149 F<dist/Time-HiRes/t/itimer.t>, F<dist/Time-HiRes/t/usleep.t>,
2150 F<dist/threads-shared/t/waithires.t>,
2151 F<dist/threads-shared/t/stress.t>, F<lib/Benchmark.t>,
2152 F<lib/Memoize/t/expmod_t.t>, and F<lib/Memoize/t/speed.t>.
2154 You might also experience some failures in F<t/op/stat.t> if you build
2155 perl on an NFS filesystem, if the remote clock and the system clock are
2160 On some systems, particularly those with smaller amounts of RAM, some
2161 of the tests in t/op/pat.t may fail with an "Out of memory" message.
2162 For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
2163 test 85 will fail if run under either t/TEST or t/harness.
2165 Try stopping other jobs on the system and then running the test by itself:
2167 ./perl -I. -MTestInit t/op/pat.t
2169 to see if you have any better luck. If your perl still fails this
2170 test, it does not necessarily mean you have a broken perl. This test
2171 tries to exercise the regular expression subsystem quite thoroughly,
2172 and may well be far more demanding than your normal usage.
2174 =item libgcc_s.so.1: cannot open shared object file
2176 This message has been reported on gcc-3.2.3 and earlier installed with
2177 a non-standard prefix. Setting the LD_LIBRARY_PATH environment variable
2178 (or equivalent) to include gcc's lib/ directory with the libgcc_s.so.1
2179 shared library should fix the problem.
2181 =item Failures from lib/File/Temp/t/security saying "system possibly insecure"
2183 First, such warnings are not necessarily serious or indicative of a
2184 real security threat. That being said, they bear investigating.
2186 Note that each of the tests is run twice. The first time is in the
2187 directory returned by File::Spec->tmpdir() (often /tmp on Unix
2188 systems), and the second time in the directory from which the test was
2189 run (usually the 't' directory, if the test was run as part of 'make
2192 The tests may fail for the following reasons:
2194 (1) If the directory the tests are being run in is owned by somebody
2195 other than the user running the tests, or by root (uid 0).
2197 This failure can happen if the Perl source code distribution is
2198 unpacked in such a way that the user IDs in the distribution package
2199 are used as-is. Some tar programs do this.
2201 (2) If the directory the tests are being run in is writable by group or
2202 by others, and there is no sticky bit set for the directory. (With
2203 UNIX/POSIX semantics, write access to a directory means the right to
2204 add or remove files in that directory. The 'sticky bit' is a feature
2205 used in some UNIXes to give extra protection to files: if the bit is
2206 set for a directory, no one but the owner (or root) can remove that
2207 file even if the permissions would otherwise allow file removal by
2210 This failure may or may not be a real problem: it depends on the
2211 permissions policy used on this particular system. This failure can
2212 also happen if the system either doesn't support the sticky bit (this
2213 is the case with many non-UNIX platforms: in principle File::Temp
2214 should know about these platforms and skip the tests), or if the system
2215 supports the sticky bit but for some reason or reasons it is not being
2216 used. This is, for example, the case with HP-UX: as of HP-UX release
2217 11.00, the sticky bit is very much supported, but HP-UX doesn't use it
2218 on its /tmp directory as shipped. Also, as with the permissions, some
2219 local policy might dictate that the stickiness is not used.
2221 (3) If the system supports the POSIX 'chown giveaway' feature and if
2222 any of the parent directories of the temporary file back to the root
2223 directory are 'unsafe', using the definitions given above in (1) and
2224 (2). For Unix systems, this is usually not an issue if you are
2225 building on a local disk. See the documentation for the File::Temp
2226 module for more information about 'chown giveaway'.
2228 See the documentation for the File::Temp module for more information
2229 about the various security aspects of temporary files.
2233 The core distribution can now run its regression tests in parallel on
2234 Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS>
2235 in your environment to the number of tests to run in parallel, and run
2236 C<make test_harness>. On a Bourne-like shell, this can be done as
2238 TEST_JOBS=3 make test_harness # Run 3 tests in parallel
2240 An environment variable is used, rather than parallel make itself,
2241 because L<TAP::Harness> needs to be able to schedule individual
2242 non-conflicting test scripts itself, and there is no standard interface
2243 to C<make> utilities to interact with their job schedulers.
2247 This will put perl into the public directory you specified to
2248 Configure; by default this is /usr/local/bin. It will also try to put
2249 the man pages in a reasonable place. It will not nroff the man pages,
2250 however. You may need to be root to run B<make install>. If you are not
2251 root, you must still have permission to install into the directories
2252 in question and you should ignore any messages about chown not working.
2254 If "make install" just says "'install' is up to date" or something
2255 similar, you may be on a case-insensitive filesystems such as Mac's HFS+,
2256 and you should say "make install-all". (This confusion is brought to you
2257 by the Perl distribution having a file called INSTALL.)
2259 =head2 Installing perl under different names
2261 If you want to install perl under a name other than "perl" (for example,
2262 when installing perl with special features enabled, such as debugging),
2263 indicate the alternate name on the "make install" line, such as:
2265 make install PERLNAME=myperl
2267 You can separately change the base used for versioned names (like
2268 "perl5.8.9") by setting PERLNAME_VERBASE, like
2270 make install PERLNAME=perl5 PERLNAME_VERBASE=perl
2272 This can be useful if you have to install perl as "perl5" (e.g. to avoid
2273 conflicts with an ancient version in /usr/bin supplied by your vendor).
2274 Without this the versioned binary would be called "perl55.8.8".
2276 =head2 Installing perl under a different directory
2278 You can install perl under a different destination directory by using
2279 the DESTDIR variable during C<make install>, with a command like
2281 make install DESTDIR=/tmp/perl5
2283 DESTDIR is automatically prepended to all the installation paths. See
2284 the example in L<"DESTDIR"> above.
2286 =head2 Installed files
2288 If you want to see exactly what will happen without installing
2289 anything, you can run
2291 ./perl installperl -n
2292 ./perl installman -n
2294 make install will install the following:
2299 perl5.n.n where 5.n.n is the current release number. This
2300 will be a link to perl.
2304 cppstdin This is used by the deprecated switch perl -P,
2305 if your cc -E can't read from stdin.
2306 corelist Shows versions of modules that come with
2309 cpan The CPAN shell.
2310 enc2xs Encoding module generator.
2311 h2ph Extract constants and simple macros from C
2313 h2xs Converts C .h header files to Perl extensions.
2314 instmodsh A shell to examine installed modules.
2315 libnetcfg Configure libnet.
2316 perlbug Tool to report bugs in Perl.
2317 perldoc Tool to read perl's pod documentation.
2318 perlivp Perl Installation Verification Procedure.
2319 piconv A Perl implementation of the encoding conversion
2321 pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules.
2322 pod2html, Converters from perl's pod documentation format
2326 podchecker POD syntax checker.
2327 podselect Prints sections of POD documentation.
2328 prove A command-line tool for running tests.
2329 psed A Perl implementation of sed.
2330 ptar A Perl implementation of tar.
2331 ptardiff A diff for tar archives.
2332 ptargrep A grep for tar archives.
2333 shasum A tool to print or check SHA checksums.
2334 splain Describe Perl warnings and errors.
2335 xsubpp Compiler to convert Perl XS code into C code.
2336 zipdetails display the internal structure of zip files
2340 in $privlib and $archlib specified to
2341 Configure, usually under /usr/local/lib/perl5/.
2345 man pages in $man1dir, usually /usr/local/man/man1.
2347 pages in $man3dir, usually /usr/local/man/man3.
2348 pod/*.pod in $privlib/pod/.
2350 installperl will also create the directories listed above
2351 in L<"Installation Directories">.
2353 Perl's *.h header files and the libperl library are also installed
2354 under $archlib so that any user may later build new modules, run the
2355 optional Perl compiler, or embed the perl interpreter into another
2356 program even if the Perl source is no longer available.
2358 =head2 Installing with a version-specific suffix
2360 Sometimes you only want to install the perl distribution with a
2361 version-specific suffix. For example, you may wish to install a newer
2362 version of perl alongside an already installed production version.
2363 To only install the version-specific parts of the perl installation, run
2365 Configure -Dversiononly
2367 or answer 'y' to the appropriate Configure prompt. Alternatively,
2368 you can just manually run
2370 ./perl installperl -v
2372 and skip installman altogether.
2374 See also L<"Maintaining completely separate versions"> for another
2377 =head1 cd /usr/include; h2ph *.h sys/*.h
2379 Some perl scripts need to be able to obtain information from the
2380 system header files. This command will convert the most commonly used
2381 header files in /usr/include into files that can be easily interpreted
2382 by perl. These files will be placed in the architecture-dependent
2383 library ($archlib) directory you specified to Configure.
2385 Note: Due to differences in the C and perl languages, the conversion
2386 of the header files is not perfect. You will probably have to
2387 hand-edit some of the converted files to get them to parse correctly.
2388 For example, h2ph breaks spectacularly on type casting and certain
2391 =head1 installhtml --help
2393 Some sites may wish to make perl documentation available in HTML
2394 format. The installhtml utility can be used to convert pod
2395 documentation into linked HTML files and install them.
2397 Currently, the supplied ./installhtml script does not make use of the
2398 html Configure variables. This should be fixed in a future release.
2400 The following command-line is an example of one used to convert
2405 --podpath=lib:ext:pod:vms \
2407 --htmldir=/perl/nmanual \
2408 --htmlroot=/perl/nmanual \
2409 --splithead=pod/perlipc \
2410 --splititem=pod/perlfunc \
2413 See the documentation in installhtml for more details. It can take
2414 many minutes to execute a large installation and you should expect to
2415 see warnings like "no title", "unexpected directive" and "cannot
2416 resolve" as the files are processed. We are aware of these problems
2417 (and would welcome patches for them).
2419 You may find it helpful to run installhtml twice. That should reduce
2420 the number of "cannot resolve" warnings.
2422 =head1 cd pod && make tex && (process the latex files)
2424 Some sites may also wish to make the documentation in the pod/ directory
2425 available in TeX format. Type
2427 (cd pod && make tex && <process the latex files>)
2429 =head1 Starting all over again
2431 If you wish to rebuild perl from the same build directory, you should
2432 clean it out with the command
2440 The only difference between the two is that make distclean also removes
2441 your old config.sh and Policy.sh files. (A plain 'make clean' is now
2442 equivalent to 'make realclean'.)
2444 If you are upgrading from a previous version of perl, or if you
2445 change systems or compilers or make other significant changes, or if
2446 you are experiencing difficulties building perl, you should not reuse
2449 If your reason to reuse your old config.sh is to save your particular
2450 installation choices, then you can probably achieve the same effect by
2451 using the Policy.sh file. See the section on L<"Site-wide Policy
2454 =head1 Reporting Problems
2456 Please report problems to the GitHub issue tracker at
2457 https://github.com/Perl/perl5/issues, which will ask for the
2458 appropriate summary configuration information about your perl, which
2459 may help us track down problems far more quickly. But first you should
2460 read the advice in this file, carefully re-read the error message and
2461 check the relevant manual pages on your system, as these may help you
2462 find an immediate solution. Once you've exhausted the documentation,
2463 please report bugs to us using the GitHub tracker.
2465 The summary configuration information can be printed with C<perl -V>.
2466 If the install fails, or you want to report problems with C<make test>
2467 without installing perl, then you can run it by hand from this source
2468 directory with C<./perl -V>.
2470 If the build fails too early to run perl, then please
2471 B<run> the C<./myconfig> shell script, and include its output along
2472 with an accurate description of your problem.
2474 If Configure itself fails, and does not generate a config.sh file
2475 (needed to run C<./myconfig>), then please open an issue with the
2476 description of how Configure fails along with details of your system
2477 -- for example the output from running C<uname -a>.
2479 Please try to make your message brief but clear. Brief, clear bug
2480 reports tend to get answered more quickly. Please don't worry if your
2481 written English is not great -- what matters is how well you describe
2482 the important technical details of the problem you have encountered,
2483 not whether your grammar and spelling is flawless.
2485 Trim out unnecessary information. Do not include large files (such as
2486 config.sh or a complete Configure or make log) unless absolutely
2487 necessary. Do not include a complete transcript of your build
2488 session. Just include the failing commands, the relevant error
2489 messages, and whatever preceding commands are necessary to give the
2490 appropriate context.
2492 If the bug you are reporting has security implications which make it
2493 inappropriate to send to a public issue tracker, then see
2494 L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
2495 for details of how to report the issue.
2497 If you are unsure what makes a good bug report please read "How to
2498 report Bugs Effectively" by Simon Tatham:
2499 L<https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>
2501 =head1 Coexistence with earlier versions of perl 5
2503 Perl 5.37.4 is not binary compatible with earlier versions of Perl.
2504 In other words, you will have to recompile your XS modules.
2506 In general, you can usually safely upgrade from one stable version of Perl
2507 (e.g. 5.30.0) to another similar minor version (e.g. 5.30.1) without
2508 re-compiling all of your extensions. You can also safely leave the old
2509 version around in case the new version causes you problems for some
2512 Usually, most extensions will probably not need to be recompiled to be
2513 used with a newer version of Perl. Here is how it is supposed to work.
2514 (These examples assume you accept all the Configure defaults.)
2516 Suppose you already have version 5.8.7 installed. The directories
2517 searched by 5.8.7 are typically like:
2519 /usr/local/lib/perl5/5.8.7/$archname
2520 /usr/local/lib/perl5/5.8.7
2521 /usr/local/lib/perl5/site_perl/5.8.7/$archname
2522 /usr/local/lib/perl5/site_perl/5.8.7
2524 Now, suppose you install version 5.8.8. The directories
2525 searched by version 5.8.8 will be:
2527 /usr/local/lib/perl5/5.8.8/$archname
2528 /usr/local/lib/perl5/5.8.8
2529 /usr/local/lib/perl5/site_perl/5.8.8/$archname
2530 /usr/local/lib/perl5/site_perl/5.8.8
2532 /usr/local/lib/perl5/site_perl/5.8.7/$archname
2533 /usr/local/lib/perl5/site_perl/5.8.7
2534 /usr/local/lib/perl5/site_perl/
2536 Notice the last three entries -- Perl understands the default structure
2537 of the $sitelib directories and will look back in older, compatible
2538 directories. This way, modules installed under 5.8.7 will continue
2539 to be usable by 5.8.7 but will also accessible to 5.8.8. Further,
2540 suppose that you upgrade a module to one which requires features
2541 present only in 5.8.8. That new module will get installed into
2542 /usr/local/lib/perl5/site_perl/5.8.8 and will be available to 5.8.8,
2543 but will not interfere with the 5.8.7 version.
2545 The last entry, /usr/local/lib/perl5/site_perl/, is there so that
2546 5.6.0 and above will look for 5.004-era pure perl modules.
2548 Lastly, suppose you now install 5.10.0, which is not binary compatible
2549 with 5.8.x. The directories searched by 5.10.0 (if you don't change the
2550 Configure defaults) will be:
2552 /usr/local/lib/perl5/5.10.0/$archname
2553 /usr/local/lib/perl5/5.10.0
2554 /usr/local/lib/perl5/site_perl/5.10.0/$archname
2555 /usr/local/lib/perl5/site_perl/5.10.0
2557 /usr/local/lib/perl5/site_perl/5.8.8
2559 /usr/local/lib/perl5/site_perl/5.8.7
2561 /usr/local/lib/perl5/site_perl/
2563 Note that the earlier $archname entries are now gone, but pure perl
2564 modules from earlier versions will still be found.
2566 This way, you can choose to share compatible extensions, but also upgrade
2567 to a newer version of an extension that may be incompatible with earlier
2568 versions, without breaking the earlier versions' installations.
2570 =head2 Maintaining completely separate versions
2572 Many users prefer to keep all versions of perl in completely
2573 separate directories. This guarantees that an update to one version
2574 won't interfere with another version. (The defaults guarantee this for
2575 libraries after 5.6.0, but not for executables. TODO?) One convenient
2576 way to do this is by using a separate prefix for each version, such as
2578 sh Configure -Dprefix=/opt/perl5.37.4
2580 and adding /opt/perl5.37.4/bin to the shell PATH variable. Such users
2581 may also wish to add a symbolic link /usr/local/bin/perl so that
2582 scripts can still start with #!/usr/local/bin/perl.
2584 Others might share a common directory for maintenance sub-versions
2585 (e.g. 5.10 for all 5.10.x versions), but change directory with
2588 If you are installing a development subversion, you probably ought to
2589 seriously consider using a separate directory, since development
2590 subversions may not have all the compatibility wrinkles ironed out
2593 =head2 Upgrading from 5.37.3 or earlier
2595 B<Perl 5.37.4 may not be binary compatible with Perl 5.37.3 or
2596 earlier Perl releases.> Perl modules having binary parts
2597 (meaning that a C compiler is used) will have to be recompiled to be
2598 used with 5.37.4. If you find you do need to rebuild an extension with
2599 5.37.4, you may safely do so without disturbing the older
2600 installations. (See L<"Coexistence with earlier versions of perl 5">
2603 See your installed copy of the perllocal.pod file for a (possibly
2604 incomplete) list of locally installed modules. Note that you want
2605 perllocal.pod, not perllocale.pod, for installed module information.
2607 =head1 Minimizing the Perl installation
2609 The following section is meant for people worrying about squeezing the
2610 Perl installation into minimal systems (for example when installing
2611 operating systems, or in really small filesystems).
2613 Leaving out as many extensions as possible is an obvious way:
2614 Encode, with its big conversion tables, consumes a lot of
2615 space. On the other hand, you cannot throw away everything. The
2616 Fcntl module is pretty essential. If you need to do network
2617 programming, you'll appreciate the Socket module, and so forth: it all
2618 depends on what do you need to do.
2620 In the following we offer two different slimmed down installation
2621 recipes. They are informative, not normative: the choice of files
2622 depends on what you need.
2624 Firstly, the bare minimum to run this script
2628 foreach my $f (</*>) {
2632 in Linux with perl-5.37.4 is as follows (under $Config{prefix}):
2635 ./lib/perl5/5.37.4/strict.pm
2636 ./lib/perl5/5.37.4/warnings.pm
2637 ./lib/perl5/5.37.4/i686-linux/File/Glob.pm
2638 ./lib/perl5/5.37.4/feature.pm
2639 ./lib/perl5/5.37.4/XSLoader.pm
2640 ./lib/perl5/5.37.4/i686-linux/auto/File/Glob/Glob.so
2642 Secondly, for perl-5.10.1, the Debian perl-base package contains 591
2643 files, (of which 510 are for lib/unicore) totaling about 3.5MB in its
2644 i386 version. Omitting the lib/unicore/* files for brevity, the
2645 remaining files are:
2649 /usr/lib/perl/5.10.1/Config.pm
2650 /usr/lib/perl/5.10.1/Config_git.pl
2651 /usr/lib/perl/5.10.1/Config_heavy.pl
2652 /usr/lib/perl/5.10.1/Cwd.pm
2653 /usr/lib/perl/5.10.1/DynaLoader.pm
2654 /usr/lib/perl/5.10.1/Errno.pm
2655 /usr/lib/perl/5.10.1/Fcntl.pm
2656 /usr/lib/perl/5.10.1/File/Glob.pm
2657 /usr/lib/perl/5.10.1/Hash/Util.pm
2658 /usr/lib/perl/5.10.1/IO.pm
2659 /usr/lib/perl/5.10.1/IO/File.pm
2660 /usr/lib/perl/5.10.1/IO/Handle.pm
2661 /usr/lib/perl/5.10.1/IO/Pipe.pm
2662 /usr/lib/perl/5.10.1/IO/Seekable.pm
2663 /usr/lib/perl/5.10.1/IO/Select.pm
2664 /usr/lib/perl/5.10.1/IO/Socket.pm
2665 /usr/lib/perl/5.10.1/IO/Socket/INET.pm
2666 /usr/lib/perl/5.10.1/IO/Socket/UNIX.pm
2667 /usr/lib/perl/5.10.1/List/Util.pm
2668 /usr/lib/perl/5.10.1/POSIX.pm
2669 /usr/lib/perl/5.10.1/Scalar/Util.pm
2670 /usr/lib/perl/5.10.1/Socket.pm
2671 /usr/lib/perl/5.10.1/XSLoader.pm
2672 /usr/lib/perl/5.10.1/auto/Cwd/Cwd.so
2673 /usr/lib/perl/5.10.1/auto/DynaLoader/autosplit.ix
2674 /usr/lib/perl/5.10.1/auto/DynaLoader/dl_expandspec.al
2675 /usr/lib/perl/5.10.1/auto/DynaLoader/dl_find_symbol_anywhere.al
2676 /usr/lib/perl/5.10.1/auto/DynaLoader/dl_findfile.al
2677 /usr/lib/perl/5.10.1/auto/Fcntl/Fcntl.so
2678 /usr/lib/perl/5.10.1/auto/File/Glob/Glob.so
2679 /usr/lib/perl/5.10.1/auto/Hash/Util/Util.so
2680 /usr/lib/perl/5.10.1/auto/IO/IO.so
2681 /usr/lib/perl/5.10.1/auto/List/Util/Util.so
2682 /usr/lib/perl/5.10.1/auto/POSIX/POSIX.so
2683 /usr/lib/perl/5.10.1/auto/POSIX/autosplit.ix
2684 /usr/lib/perl/5.10.1/auto/POSIX/load_imports.al
2685 /usr/lib/perl/5.10.1/auto/Socket/Socket.so
2686 /usr/lib/perl/5.10.1/lib.pm
2687 /usr/lib/perl/5.10.1/re.pm
2688 /usr/share/doc/perl/AUTHORS.gz
2689 /usr/share/doc/perl/Documentation
2690 /usr/share/doc/perl/README.Debian
2691 /usr/share/doc/perl/changelog.Debian.gz
2692 /usr/share/doc/perl/copyright
2693 /usr/share/lintian/overrides/perl-base
2694 /usr/share/man/man1/perl.1.gz
2695 /usr/share/man/man1/perl5.10.1.1.gz
2696 /usr/share/perl/5.10.1/AutoLoader.pm
2697 /usr/share/perl/5.10.1/Carp.pm
2698 /usr/share/perl/5.10.1/Carp/Heavy.pm
2699 /usr/share/perl/5.10.1/Exporter.pm
2700 /usr/share/perl/5.10.1/Exporter/Heavy.pm
2701 /usr/share/perl/5.10.1/File/Spec.pm
2702 /usr/share/perl/5.10.1/File/Spec/Unix.pm
2703 /usr/share/perl/5.10.1/FileHandle.pm
2704 /usr/share/perl/5.10.1/Getopt/Long.pm
2705 /usr/share/perl/5.10.1/IPC/Open2.pm
2706 /usr/share/perl/5.10.1/IPC/Open3.pm
2707 /usr/share/perl/5.10.1/SelectSaver.pm
2708 /usr/share/perl/5.10.1/Symbol.pm
2709 /usr/share/perl/5.10.1/Text/ParseWords.pm
2710 /usr/share/perl/5.10.1/Text/Tabs.pm
2711 /usr/share/perl/5.10.1/Text/Wrap.pm
2712 /usr/share/perl/5.10.1/Tie/Hash.pm
2713 /usr/share/perl/5.10.1/attributes.pm
2714 /usr/share/perl/5.10.1/base.pm
2715 /usr/share/perl/5.10.1/bytes.pm
2716 /usr/share/perl/5.10.1/bytes_heavy.pl
2717 /usr/share/perl/5.10.1/constant.pm
2718 /usr/share/perl/5.10.1/fields.pm
2719 /usr/share/perl/5.10.1/integer.pm
2720 /usr/share/perl/5.10.1/locale.pm
2721 /usr/share/perl/5.10.1/overload.pm
2722 /usr/share/perl/5.10.1/strict.pm
2723 /usr/share/perl/5.10.1/unicore/*
2724 /usr/share/perl/5.10.1/utf8.pm
2725 /usr/share/perl/5.10.1/utf8_heavy.pl
2726 /usr/share/perl/5.10.1/vars.pm
2727 /usr/share/perl/5.10.1/warnings.pm
2728 /usr/share/perl/5.10.1/warnings/register.pm
2730 A nice trick to find out the minimal set of Perl library files you will
2731 need to run a Perl program is
2733 perl -e 'do "prog.pl"; END { print "$_\n" for sort keys %INC }'
2735 (this will not find libraries required in runtime, unfortunately, but
2736 it's a minimal set) and if you want to find out all the files you can
2737 use something like the below
2739 strace perl -le 'do "x.pl"' 2>&1 \
2740 | perl -nle '/^open\(\"(.+?)"/ && print $1'
2742 (The 'strace' is Linux-specific, other similar utilities include 'truss'
2745 =head2 C<-DNO_MATHOMS>
2747 If you configure perl with C<-Accflags=-DNO_MATHOMS>, the functions from
2748 F<mathoms.c> will not be compiled in. Those functions are no longer used
2749 by perl itself; for source compatibility reasons, though, they weren't
2752 =head2 C<-DNO_PERL_INTERNAL_RAND_SEED>
2753 X<PERL_INTERNAL_RAND_SEED>
2755 If you configure perl with C<-Accflags=-DNO_PERL_INTERNAL_RAND_SEED>,
2756 perl will ignore the C<PERL_INTERNAL_RAND_SEED> environment variable.
2758 =head2 C<-DNO_PERL_RAND_SEED>
2761 If you configure perl with C<-Accflags=-DNO_PERL_RAND_SEED>,
2762 perl will ignore the C<PERL_RAND_SEED> environment variable.
2764 =head1 DOCUMENTATION
2766 Read the manual entries before running perl. The main documentation
2767 is in the F<pod/> subdirectory and should have been installed during the
2768 build process. Type B<man perl> to get started. Alternatively, you
2769 can type B<perldoc perl> to use the supplied perldoc script. This is
2770 sometimes useful for finding things in the library modules.
2774 Original author: Andy Dougherty doughera@lafayette.edu , borrowing very
2775 heavily from the original README by Larry Wall, with lots of helpful
2776 feedback and additions from the perl5-porters@perl.org folks.
2778 If you have problems, corrections, or questions, please see
2779 L<"Reporting Problems"> above.
2781 =head1 REDISTRIBUTION
2783 This document is part of the Perl package and may be distributed under
2784 the same terms as perl itself, with the following additional request:
2785 If you are distributing a modified version of perl (perhaps as part of
2786 a larger package) please B<do> modify these installation instructions
2787 and the contact information to match your distribution. Additional
2788 information for packagers is in F<PACKAGING>.