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