This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Perl Social Contract
[perl5.git] / INSTALL
CommitLineData
8e07c86e
AD
1=head1 NAME
2
3Install - Build and Installation guide for perl5.
4
5=head1 SYNOPSIS
6
7f678428 7The basic steps to build and install perl5 on a Unix system are:
8e07c86e 8
dc45a647 9 rm -f config.sh Policy.sh
8e07c86e
AD
10 sh Configure
11 make
12 make test
13 make install
36477c24 14
aa689395
PP
15 # You may also wish to add these:
16 (cd /usr/include && h2ph *.h sys/*.h)
3e3baf6d 17 (installhtml --help)
aa689395 18 (cd pod && make tex && <process the latex files>)
8e07c86e
AD
19
20Each of these is explained in further detail below.
21
7beaa944
AD
22For information on non-Unix systems, see the section on
23L<"Porting information"> below.
7f678428 24
7beaa944
AD
25For information on what's new in this release, see the
26pod/perldelta.pod file. For more detailed information about specific
27changes, see the Changes file.
c3edaffb 28
1ec51d55 29=head1 DESCRIPTION
edb1cbcb 30
c3edaffb
PP
31This document is written in pod format as an easy way to indicate its
32structure. The pod format is described in pod/perlpod.pod, but you can
1ec51d55
CS
33read it as is with any pager or editor. Headings and items are marked
34by lines beginning with '='. The other mark-up used is
35
36 B<text> embolden text, used for switches, programs or commands
37 C<code> literal code
38 L<name> A link (cross reference) to name
39
40You should probably at least skim through this entire document before
41proceeding.
c3edaffb 42
eed2e782
PP
43If you're building Perl on a non-Unix system, you should also read
44the README file specific to your operating system, since this may
45provide additional or different instructions for building Perl.
46
203c3eec
AD
47If there is a hint file for your system (in the hints/ directory) you
48should also read that hint file for specific information for your
49system. (Unixware users should use the svr4.sh hint file.)
50
693762b4
AD
51=head1 NOTE: This version is not binary compatible with Perl 5.004.
52
53For Perl 5.004 it was possible to be binary compatible with 5.003.
54Starting from Perl 5.004_50 this is no longer possible because there were
55many deep and far-reaching changes to the language internals.
56
57If you have dynamically loaded extensions that you built under perl
585.003 or 5.004 and the so-called 'bincompat3' mode (the default mode)
59and that you wish to continue to use with perl 5.005, you may need to
60reinstall the extensions. If you wish to continue to support both 5.004
61and 5.005 on your system, you will have to move the 5.004 extensions
62over to the 5.004 architecture-dependent library. See the discussion
63below on L<"Coexistence with earlier versions of perl5.">
64
65The standard extensions supplied with Perl will be handled automatically.
66
67In a related issue, old extensions may possibly be affected by the
68changes in the Perl language in the current release. Please see
69pod/perldelta.pod for a description of what's changed.
70
aa689395 71=head1 Space Requirements
eed2e782 72
dc45a647
MB
73The complete perl5 source tree takes up about 10 MB of disk space. The
74complete tree after completing make takes roughly 20 MB, though the
1ec51d55 75actual total is likely to be quite system-dependent. The installation
dc45a647 76directories need something on the order of 10 MB, though again that
1ec51d55 77value is system-dependent.
8e07c86e 78
aa689395 79=head1 Start with a Fresh Distribution
8e07c86e 80
edb1cbcb
PP
81If you have built perl before, you should clean out the build directory
82with the command
83
dc45a647
MB
84 make distclean
85
86or
87
edb1cbcb 88 make realclean
c3edaffb 89
dc45a647
MB
90The only difference between the two is that make distclean also removes
91your old config.sh and Policy.sh files.
92
93The results of a Configure run are stored in the config.sh and Policy.sh
94files. If you are upgrading from a previous version of perl, or if you
95change systems or compilers or make other significant changes, or if
96you are experiencing difficulties building perl, you should probably
97not re-use your old config.sh. Simply remove it or rename it, e.g.
8e07c86e
AD
98
99 mv config.sh config.sh.old
4633a7c4 100
e57fd563
PP
101If you wish to use your old config.sh, be especially attentive to the
102version and architecture-specific questions and answers. For example,
103the default directory for architecture-dependent library modules
104includes the version name. By default, Configure will reuse your old
105name (e.g. /opt/perl/lib/i86pc-solaris/5.003) even if you're running
106Configure for a different version, e.g. 5.004. Yes, Configure should
107probably check and correct for this, but it doesn't, presently.
108Similarly, if you used a shared libperl.so (see below) with version
109numbers, you will probably want to adjust them as well.
110
111Also, be careful to check your architecture name. Some Linux systems
1ec51d55
CS
112(such as Debian) use i386, while others may use i486 or i586. If you
113pick up a precompiled binary, it might not use the same name.
e57fd563
PP
114
115In short, if you wish to use your old config.sh, I recommend running
116Configure interactively rather than blindly accepting the defaults.
8e07c86e 117
dc45a647
MB
118If your reason to reuse your old config.sh is to save your
119particular installation choices, then you can probably achieve the
120same effect by using the new Policy.sh file. See the section on
121L<"Site-wide Policy settings"> below.
122
aa689395 123=head1 Run Configure
8e07c86e
AD
124
125Configure will figure out various things about your system. Some
126things Configure will figure out for itself, other things it will ask
1ec51d55 127you about. To accept the default, just press RETURN. The default
203c3eec
AD
128is almost always ok. At any Configure prompt, you can type &-d
129and Configure will use the defaults from then on.
8e07c86e
AD
130
131After it runs, Configure will perform variable substitution on all the
1ec51d55 132*.SH files and offer to run make depend.
8e07c86e 133
fb73857a
PP
134Configure supports a number of useful options. Run B<Configure -h> to
135get a listing. See the Porting/Glossary file for a complete list of
136Configure variables you can set and their definitions.
137
138To compile with gcc, for example, you should run
8e07c86e
AD
139
140 sh Configure -Dcc=gcc
141
142This is the preferred way to specify gcc (or another alternative
143compiler) so that the hints files can set appropriate defaults.
144
4633a7c4
LW
145If you want to use your old config.sh but override some of the items
146with command line options, you need to use B<Configure -O>.
147
8e07c86e
AD
148By default, for most systems, perl will be installed in
149/usr/local/{bin, lib, man}. You can specify a different 'prefix' for
150the default installation directory, when Configure prompts you or by
151using the Configure command line option -Dprefix='/some/directory',
152e.g.
153
25f94b33 154 sh Configure -Dprefix=/opt/perl
4633a7c4
LW
155
156If your prefix contains the string "perl", then the directories
157are simplified. For example, if you use prefix=/opt/perl,
158then Configure will suggest /opt/perl/lib instead of
4fdae800 159/opt/perl/lib/perl5/.
8e07c86e 160
84902520
TB
161NOTE: You must not specify an installation directory that is below
162your perl source directory. If you do, installperl will attempt
163infinite recursion.
164
aa689395 165By default, Configure will compile perl to use dynamic loading if
8e07c86e 166your system supports it. If you want to force perl to be compiled
56c6f531
JH
167statically, you can either choose this when Configure prompts you or
168you can use the Configure command line option -Uusedl.
8e07c86e 169
203c3eec
AD
170If you are willing to accept all the defaults, and you want terse
171output, you can run
172
173 sh Configure -des
174
175For my Solaris system, I usually use
176
177 sh Configure -Dprefix=/opt/perl -Doptimize='-xpentium -xO4' -des
178
46bb10fb
CS
179=head2 GNU-style configure
180
1ec51d55 181If you prefer the GNU-style configure command line interface, you can
dc45a647 182use the supplied configure.gnu command, e.g.
46bb10fb 183
693762b4 184 CC=gcc ./configure.gnu
46bb10fb 185
dc45a647 186The configure.gnu script emulates a few of the more common configure
46bb10fb
CS
187options. Try
188
693762b4 189 ./configure.gnu --help
46bb10fb
CS
190
191for a listing.
192
aa689395 193Cross compiling is not supported.
46bb10fb 194
dc45a647 195(The file is called configure.gnu to avoid problems on systems
693762b4 196that would not distinguish the files "Configure" and "configure".)
46bb10fb 197
24b3df7f
PP
198=head2 Extensions
199
edb1cbcb
PP
200By default, Configure will offer to build every extension which appears
201to be supported. For example, Configure will offer to build GDBM_File
202only if it is able to find the gdbm library. (See examples below.)
693762b4
AD
203B, DynaLoader, Fcntl, IO, and attrs are always built by default.
204Configure does not contain code to test for POSIX compliance, so POSIX
205is always built by default as well. If you wish to skip POSIX, you can
206set the Configure variable useposix=false either in a hint file or from
207the Configure command line. Similarly, the Opcode extension is always
208built by default, but you can skip it by setting the Configure variable
c3edaffb 209useopcode=false either in a hint file for from the command line.
24b3df7f 210
1ec51d55
CS
211You can learn more about each of these extensions by consulting the
212documentation in the individual .pm modules, located under the
213ext/ subdirectory.
214
56c6f531
JH
215Even if you do not have dynamic loading, you must still build the
216DynaLoader extension; you should just build the stub dl_none.xs
217version. (Configure will suggest this as the default.)
218
24b3df7f
PP
219In summary, here are the Configure command-line variables you can set
220to turn off each extension:
221
693762b4 222 B (Always included by default)
24b3df7f 223 DB_File i_db
56c6f531 224 DynaLoader (Must always be included as a static extension)
24b3df7f
PP
225 Fcntl (Always included by default)
226 GDBM_File i_gdbm
9d67150a 227 IO (Always included by default)
24b3df7f
PP
228 NDBM_File i_ndbm
229 ODBM_File i_dbm
230 POSIX useposix
231 SDBM_File (Always included by default)
c3edaffb 232 Opcode useopcode
24b3df7f 233 Socket d_socket
693762b4
AD
234 Threads usethreads
235 attrs (Always included by default)
24b3df7f
PP
236
237Thus to skip the NDBM_File extension, you can use
238
239 sh Configure -Ui_ndbm
240
241Again, this is taken care of automatically if you don't have the ndbm
242library.
243
244Of course, you may always run Configure interactively and select only
aa689395 245the extensions you want.
24b3df7f 246
693762b4
AD
247Note: The DB_File module will only work with version 1.x of Berkeley
248DB or newer releases of version 2. Configure will automatically detect
249this for you and refuse to try to build DB_File with version 2.
1ec51d55 250
dc45a647
MB
251If you re-use your old config.sh but change your system (e.g. by
252adding libgdbm) Configure will still offer your old choices of extensions
253for the default answer, but it will also point out the discrepancy to
254you.
255
24b3df7f
PP
256Finally, if you have dynamic loading (most modern Unix systems do)
257remember that these extensions do not increase the size of your perl
258executable, nor do they impact start-up time, so you probably might as
259well build all the ones that will work on your system.
260
8e07c86e
AD
261=head2 Including locally-installed libraries
262
4633a7c4
LW
263Perl5 comes with interfaces to number of database extensions, including
264dbm, ndbm, gdbm, and Berkeley db. For each extension, if
265Configure can find the appropriate header files and libraries, it will
266automatically include that extension. The gdbm and db libraries
1ec51d55 267are not included with perl. See the library documentation for
4633a7c4 268how to obtain the libraries.
8e07c86e 269
1ec51d55 270Note: If your database header (.h) files are not in a
8e07c86e 271directory normally searched by your C compiler, then you will need to
1ec51d55 272include the appropriate -I/your/directory option when prompted by
8e07c86e
AD
273Configure. If your database library (.a) files are not in a directory
274normally searched by your C compiler and linker, then you will need to
1ec51d55 275include the appropriate -L/your/directory option when prompted by
8e07c86e
AD
276Configure. See the examples below.
277
278=head2 Examples
279
280=over 4
281
aa689395 282=item gdbm in /usr/local
8e07c86e
AD
283
284Suppose you have gdbm and want Configure to find it and build the
1ec51d55
CS
285GDBM_File extension. This examples assumes you have gdbm.h
286installed in /usr/local/include/gdbm.h and libgdbm.a installed in
287/usr/local/lib/libgdbm.a. Configure should figure all the
8e07c86e
AD
288necessary steps out automatically.
289
290Specifically, when Configure prompts you for flags for
1ec51d55 291your C compiler, you should include -I/usr/local/include.
8e07c86e
AD
292
293When Configure prompts you for linker flags, you should include
1ec51d55 294-L/usr/local/lib.
8e07c86e
AD
295
296If you are using dynamic loading, then when Configure prompts you for
297linker flags for dynamic loading, you should again include
1ec51d55 298-L/usr/local/lib.
8e07c86e
AD
299
300Again, this should all happen automatically. If you want to accept the
301defaults for all the questions and have Configure print out only terse
302messages, then you can just run
303
304 sh Configure -des
305
306and Configure should include the GDBM_File extension automatically.
307
308This should actually work if you have gdbm installed in any of
309(/usr/local, /opt/local, /usr/gnu, /opt/gnu, /usr/GNU, or /opt/GNU).
310
311=item gdbm in /usr/you
312
313Suppose you have gdbm installed in some place other than /usr/local/,
314but you still want Configure to find it. To be specific, assume you
1ec51d55
CS
315have /usr/you/include/gdbm.h and /usr/you/lib/libgdbm.a. You
316still have to add -I/usr/you/include to cc flags, but you have to take
317an extra step to help Configure find libgdbm.a. Specifically, when
8e07c86e 318Configure prompts you for library directories, you have to add
1ec51d55 319/usr/you/lib to the list.
8e07c86e
AD
320
321It is possible to specify this from the command line too (all on one
322line):
323
324 sh Configure -des \
325 -Dlocincpth="/usr/you/include" \
326 -Dloclibpth="/usr/you/lib"
327
1ec51d55
CS
328locincpth is a space-separated list of include directories to search.
329Configure will automatically add the appropriate -I directives.
8e07c86e 330
1ec51d55
CS
331loclibpth is a space-separated list of library directories to search.
332Configure will automatically add the appropriate -L directives. If
333you have some libraries under /usr/local/ and others under
334/usr/you, then you have to include both, namely
8e07c86e
AD
335
336 sh Configure -des \
337 -Dlocincpth="/usr/you/include /usr/local/include" \
338 -Dloclibpth="/usr/you/lib /usr/local/lib"
339
340=back
341
aa689395 342=head2 Installation Directories
4633a7c4
LW
343
344The installation directories can all be changed by answering the
345appropriate questions in Configure. For convenience, all the
346installation questions are near the beginning of Configure.
347
7beaa944
AD
348I highly recommend running Configure interactively to be sure it puts
349everything where you want it. At any point during the Configure
350process, you can answer a question with &-d and Configure
351will use the defaults from then on.
1ec51d55 352
4633a7c4
LW
353By default, Configure uses the following directories for
354library files (archname is a string like sun4-sunos, determined
355by Configure)
356
46bb10fb 357 /usr/local/lib/perl5/archname/5.004
4633a7c4 358 /usr/local/lib/perl5/
24b3df7f
PP
359 /usr/local/lib/perl5/site_perl/archname
360 /usr/local/lib/perl5/site_perl
4633a7c4
LW
361
362and the following directories for manual pages:
363
364 /usr/local/man/man1
365 /usr/local/lib/perl5/man/man3
366
367(Actually, Configure recognizes the SVR3-style
368/usr/local/man/l_man/man1 directories, if present, and uses those
fb73857a
PP
369instead.)
370
371The module man pages are stuck in that strange spot so that
4633a7c4
LW
372they don't collide with other man pages stored in /usr/local/man/man3,
373and so that Perl's man pages don't hide system man pages. On some
374systems, B<man less> would end up calling up Perl's less.pm module man
fb73857a
PP
375page, rather than the less program. (This default location will likely
376change to /usr/local/man/man3 in a future release of perl.)
1ec51d55
CS
377
378Note: Many users prefer to store the module man pages in
379/usr/local/man/man3. You can do this from the command line with
380
381 sh Configure -Dman3dir=/usr/local/man/man3
382
383Some users also prefer to use a .3pm suffix. You can do that with
384
385 sh Configure -Dman3ext=3pm
4633a7c4
LW
386
387If you specify a prefix that contains the string "perl", then the
aa689395
PP
388directory structure is simplified. For example, if you Configure with
389-Dprefix=/opt/perl, then the defaults are
4633a7c4 390
46bb10fb 391 /opt/perl/lib/archname/5.004
4633a7c4
LW
392 /opt/perl/lib
393 /opt/perl/lib/site_perl/archname
394 /opt/perl/lib/site_perl
395
396 /opt/perl/man/man1
397 /opt/perl/man/man3
398
399The perl executable will search the libraries in the order given
400above.
401
402The directories site_perl and site_perl/archname are empty, but are
403intended to be used for installing local or site-wide extensions. Perl
693762b4 404will automatically look in these directories.
4633a7c4 405
46bb10fb 406In order to support using things like #!/usr/local/bin/perl5.004 after
4633a7c4
LW
407a later version is released, architecture-dependent libraries are
408stored in a version-specific directory, such as
693762b4 409/usr/local/lib/perl5/archname/5.004/.
4633a7c4
LW
410
411Again, these are just the defaults, and can be changed as you run
412Configure.
413
aa689395
PP
414=head2 Changing the installation directory
415
416Configure distinguishes between the directory in which perl (and its
417associated files) should be installed and the directory in which it
418will eventually reside. For most sites, these two are the same; for
419sites that use AFS, this distinction is handled automatically.
1ec51d55 420However, sites that use software such as depot to manage software
aa689395
PP
421packages may also wish to install perl into a different directory and
422use that management software to move perl to its final destination.
423This section describes how to do this. Someday, Configure may support
424an option -Dinstallprefix=/foo to simplify this.
425
0dcb58f4
AD
426Suppose you want to install perl under the /tmp/perl5 directory. You
427can edit config.sh and change all the install* variables to point to
428/tmp/perl5 instead of /usr/local/wherever. Or, you can automate this
429process by placing the following lines in a file config.over before you
430run Configure (replace /tmp/perl5 by a directory of your choice):
aa689395
PP
431
432 installprefix=/tmp/perl5
433 test -d $installprefix || mkdir $installprefix
434 test -d $installprefix/bin || mkdir $installprefix/bin
435 installarchlib=`echo $installarchlib | sed "s!$prefix!$installprefix!"`
436 installbin=`echo $installbin | sed "s!$prefix!$installprefix!"`
437 installman1dir=`echo $installman1dir | sed "s!$prefix!$installprefix!"`
438 installman3dir=`echo $installman3dir | sed "s!$prefix!$installprefix!"`
439 installprivlib=`echo $installprivlib | sed "s!$prefix!$installprefix!"`
440 installscript=`echo $installscript | sed "s!$prefix!$installprefix!"`
441 installsitelib=`echo $installsitelib | sed "s!$prefix!$installprefix!"`
442 installsitearch=`echo $installsitearch | sed "s!$prefix!$installprefix!"`
443
444Then, you can Configure and install in the usual way:
445
446 sh Configure -des
447 make
448 make test
449 make install
450
693762b4
AD
451Beware, though, that if you go to try to install new add-on
452extensions, they too will get installed in under '/tmp/perl5' if you
453follow this example. The next section shows one way of dealing with
454that problem.
455
aa689395
PP
456=head2 Creating an installable tar archive
457
458If you need to install perl on many identical systems, it is
459convenient to compile it once and create an archive that can be
460installed on multiple systems. Here's one way to do that:
461
462 # Set up config.over to install perl into a different directory,
463 # e.g. /tmp/perl5 (see previous part).
464 sh Configure -des
465 make
466 make test
467 make install
468 cd /tmp/perl5
fb73857a
PP
469 # Edit lib/<archname>/<version>/Config.pm to change all the
470 # install* variables back to reflect where everything will
471 # really be installed.
aa689395
PP
472 tar cvf ../perl5-archive.tar .
473 # Then, on each machine where you want to install perl,
474 cd /usr/local # Or wherever you specified as $prefix
475 tar xvf perl5-archive.tar
476
dc45a647 477=head2 Site-wide Policy settings
693762b4
AD
478
479After Configure runs, it stores a number of common site-wide "policy"
480answers (such as installation directories and the local perl contact
481person) in the Policy.sh file. If you want to build perl on another
482system using the same policy defaults, simply copy the Policy.sh file
483to the new system and Configure will use it along with the appropriate
484hint file for your system.
485
dc45a647
MB
486Alternatively, if you wish to change some or all of those policy
487answers, you should
488
489 rm -f Policy.sh
490
491to ensure that Configure doesn't re-use them.
492
493Further information is in the Policy_sh.SH file itself.
494
aa689395
PP
495=head2 Configure-time Options
496
497There are several different ways to Configure and build perl for your
498system. For most users, the defaults are sensible and will work.
499Some users, however, may wish to further customize perl. Here are
500some of the main things you can change.
501
693762b4 502=head2 Threads
aa689395 503
693762b4
AD
504On some platforms, perl5.005 can be compiled to use threads. To
505enable this, read the file README.threads, and then try
f7542a9d 506
693762b4 507 sh Configure -Dusethreads
aa689395 508
693762b4
AD
509Currently, you need to specify -Dusethreads on the Configure command
510line so that the hint files can make appropriate adjustments.
511
512The default is to compile without thread support.
3fe9a6f1 513
46bb10fb
CS
514=head2 Selecting File IO mechanisms
515
516Previous versions of perl used the standard IO mechanisms as defined in
1ec51d55 517stdio.h. Versions 5.003_02 and later of perl allow alternate IO
46bb10fb
CS
518mechanisms via a "PerlIO" abstraction, but the stdio mechanism is still
519the default and is the only supported mechanism.
520
521This PerlIO abstraction can be enabled either on the Configure command
522line with
523
524 sh Configure -Duseperlio
525
526or interactively at the appropriate Configure prompt.
527
528If you choose to use the PerlIO abstraction layer, there are two
529(experimental) possibilities for the underlying IO calls. These have been
530tested to some extent on some platforms, but are not guaranteed to work
531everywhere.
532
533=over 4
534
535=item 1.
536
1ec51d55 537AT&T's "sfio". This has superior performance to stdio.h in many
aa689395 538cases, and is extensible by the use of "discipline" modules. Sfio
46bb10fb
CS
539currently only builds on a subset of the UNIX platforms perl supports.
540Because the data structures are completely different from stdio, perl
541extension modules or external libraries may not work. This
542configuration exists to allow these issues to be worked on.
543
544This option requires the 'sfio' package to have been built and installed.
545A (fairly old) version of sfio is in CPAN, and work is in progress to make
546it more easily buildable by adding Configure support.
547
548You select this option by
549
550 sh Configure -Duseperlio -Dusesfio
551
552If you have already selected -Duseperlio, and if Configure detects
553that you have sfio, then sfio will be the default suggested by
554Configure.
555
1ec51d55
CS
556Note: On some systems, sfio's iffe configuration script fails
557to detect that you have an atexit function (or equivalent).
33e6ee5f
AD
558Apparently, this is a problem at least for some versions of Linux
559and SunOS 4.
560
561You can test if you have this problem by trying the following shell
562script. (You may have to add some extra cflags and libraries. A
563portable version of this may eventually make its way into Configure.)
564
565 #!/bin/sh
566 cat > try.c <<'EOCP'
567 #include <stdio.h>
568 main() { printf("42\n"); }
569 EOCP
570 cc -o try try.c -lsfio
571 val=`./try`
572 if test X$val = X42; then
573 echo "Your sfio looks ok"
574 else
575 echo "Your sfio has the exit problem."
576 fi
577
578If you have this problem, the fix is to go back to your sfio sources
579and correct iffe's guess about atexit (or whatever is appropriate for
580your platform.)
581
582There also might be a more recent release of Sfio that fixes your
583problem.
584
46bb10fb
CS
585=item 2.
586
587Normal stdio IO, but with all IO going through calls to the PerlIO
588abstraction layer. This configuration can be used to check that perl and
589extension modules have been correctly converted to use the PerlIO
590abstraction.
591
592This configuration should work on all platforms (but might not).
593
aa689395 594You select this option via:
46bb10fb
CS
595
596 sh Configure -Duseperlio -Uusesfio
597
598If you have already selected -Duseperlio, and if Configure does not
599detect sfio, then this will be the default suggested by Configure.
600
601=back
602
aa689395 603=head2 Building a shared libperl.so Perl library
c3edaffb
PP
604
605Currently, for most systems, the main perl executable is built by
606linking the "perl library" libperl.a with perlmain.o, your static
607extensions (usually just DynaLoader.a) and various extra libraries,
608such as -lm.
609
9d67150a
PP
610On some systems that support dynamic loading, it may be possible to
611replace libperl.a with a shared libperl.so. If you anticipate building
c3edaffb
PP
612several different perl binaries (e.g. by embedding libperl into
613different programs, or by using the optional compiler extension), then
9d67150a 614you might wish to build a shared libperl.so so that all your binaries
c3edaffb
PP
615can share the same library.
616
617The disadvantages are that there may be a significant performance
9d67150a 618penalty associated with the shared libperl.so, and that the overall
aa689395 619mechanism is still rather fragile with respect to different versions
c3edaffb
PP
620and upgrades.
621
622In terms of performance, on my test system (Solaris 2.5_x86) the perl
9d67150a 623test suite took roughly 15% longer to run with the shared libperl.so.
c3edaffb
PP
624Your system and typical applications may well give quite different
625results.
626
627The default name for the shared library is typically something like
a6006777 628libperl.so.3.2 (for Perl 5.003_02) or libperl.so.302 or simply
9d67150a 629libperl.so. Configure tries to guess a sensible naming convention
c3edaffb
PP
630based on your C library name. Since the library gets installed in a
631version-specific architecture-dependent directory, the exact name
632isn't very important anyway, as long as your linker is happy.
633
634For some systems (mostly SVR4), building a shared libperl is required
635for dynamic loading to work, and hence is already the default.
636
637You can elect to build a shared libperl by
638
639 sh Configure -Duseshrplib
640
641To actually build perl, you must add the current working directory to your
aa689395 642LD_LIBRARY_PATH environment variable before running make. You can do
c3edaffb
PP
643this with
644
645 LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
646
647for Bourne-style shells, or
648
649 setenv LD_LIBRARY_PATH `pwd`
650
651for Csh-style shells. You *MUST* do this before running make.
652Folks running NeXT OPENSTEP must substitute DYLD_LIBRARY_PATH for
653LD_LIBRARY_PATH above.
654
9d67150a
PP
655There is also an potential problem with the shared perl library if you
656want to have more than one "flavor" of the same version of perl (e.g.
657with and without -DDEBUGGING). For example, suppose you build and
a6006777
PP
658install a standard Perl 5.004 with a shared library. Then, suppose you
659try to build Perl 5.004 with -DDEBUGGING enabled, but everything else
9d67150a
PP
660the same, including all the installation directories. How can you
661ensure that your newly built perl will link with your newly built
7f678428 662libperl.so.4 rather with the installed libperl.so.4? The answer is
9d67150a 663that you might not be able to. The installation directory is encoded
56c6f531
JH
664in the perl binary with the LD_RUN_PATH environment variable (or
665equivalent ld command-line option). On Solaris, you can override that
7beaa944 666with LD_LIBRARY_PATH; on Linux you can't. On Digital Unix, you can
0dcb58f4 667override LD_LIBRARY_PATH by setting the _RLD_ROOT environment variable
7beaa944 668to point to the perl build directory.
9d67150a
PP
669
670The only reliable answer is that you should specify a different
671directory for the architecture-dependent library for your -DDEBUGGING
fb73857a 672version of perl. You can do this by changing all the *archlib*
9d67150a
PP
673variables in config.sh, namely archlib, archlib_exp, and
674installarchlib, to point to your new architecture-dependent library.
675
55479bb6
AD
676=head2 Malloc Issues
677
678Perl relies heavily on malloc(3) to grow data structures as needed, so
679perl's performance can be noticeably affected by the performance of
680the malloc function on your system.
681
682The perl source is shipped with a version of malloc that is very fast
683but somewhat wasteful of space. On the other hand, your system's
693762b4 684malloc() function may be a bit slower but also a bit more frugal.
55479bb6
AD
685
686For many uses, speed is probably the most important consideration, so
687the default behavior (for most systems) is to use the malloc supplied
688with perl. However, if you will be running very large applications
689(e.g. Tk or PDL) or if your system already has an excellent malloc, or
690if you are experiencing difficulties with extensions that use
691third-party libraries that call malloc, then you might wish to use
692your system's malloc. (Or, you might wish to explore the experimental
693malloc flags discussed below.)
694
695To build without perl's malloc, you can use the Configure command
696
697 sh Configure -Uusemymalloc
698
699or you can answer 'n' at the appropriate interactive Configure prompt.
700
aa689395 701=head2 Malloc Performance Flags
c3edaffb 702
55479bb6 703If you are using Perl's malloc, you may add one or
1ec51d55 704more of the following items to your cflags config.sh variable
55479bb6 705to change its behavior in potentially useful ways. You can find out
1ec51d55 706more about these flags by reading the malloc.c source.
55479bb6 707In a future version of perl, these might be enabled by default.
c3edaffb 708
aa689395
PP
709=over 4
710
84902520 711=item -DPERL_EMERGENCY_SBRK
2ae324a7 712
84902520 713If PERL_EMERGENCY_SBRK is defined, running out of memory need not be a
2ae324a7 714fatal error: a memory pool can allocated by assigning to the special
1ec51d55 715variable $^M. See perlvar(1) for more details.
aa689395
PP
716
717=item -DPACK_MALLOC
718
1ec51d55 719If PACK_MALLOC is defined, malloc.c uses a slightly different
55479bb6
AD
720algorithm for small allocations (up to 64 bytes long). Such small
721allocations are quite common in typical Perl scripts.
aa689395 722
1ec51d55 723The expected memory savings (with 8-byte alignment in $alignbytes) is
55479bb6
AD
724about 20% for typical Perl usage. The expected slowdown due to the
725additional malloc overhead is in fractions of a percent. (It is hard
726to measure because of the effect of the saved memory on speed).
aa689395
PP
727
728=item -DTWO_POT_OPTIMIZE
729
1ec51d55 730If TWO_POT_OPTIMIZE is defined, malloc.c uses a slightly different
55479bb6
AD
731algorithm for large allocations that are close to a power of two
732(starting with 16K). Such allocations are typical for big hashes and
733special-purpose scripts, especially image processing. If you will be
734manipulating very large blocks with sizes close to powers of two, it
735might be wise to define this macro.
aa689395 736
55479bb6
AD
737The expected saving of memory is 0-100% (100% in applications which
738require most memory in such 2**n chunks). The expected slowdown is
aa689395
PP
739negligible.
740
741=back
742
3bf462b8
CS
743=head2 Building a debugging perl
744
745You can run perl scripts under the perl debugger at any time with
3fe9a6f1 746B<perl -d your_script>. If, however, you want to debug perl itself,
3bf462b8
CS
747you probably want to do
748
749 sh Configure -Doptimize='-g'
750
203c3eec
AD
751This will do two independent things: First, it will force compilation
752to use cc -g so that you can use your system's debugger on the
753executable. (Note: Your system may actually require something like
754cc -g2. Check you man pages for cc(1) and also any hint file for your
755system.) Second, it will add -DDEBUGGING to your ccflags variable in
1ec51d55 756config.sh so that you can use B<perl -D> to access perl's internal
203c3eec 757state. (Note: Configure will only add -DDEBUGGING by
1ec51d55
CS
758default if you are not reusing your old config.sh. If you want to
759reuse your old config.sh, then you can just edit it and change the
3fe9a6f1 760optimize and ccflags variables by hand and then propagate your changes
203c3eec
AD
761as shown in L<"Propagating your changes to config.sh"> below.)
762
763You can actually specify -g and -DDEBUGGING independently, but usually
764it's convenient to have both.
3bf462b8
CS
765
766If you are using a shared libperl, see the warnings about multiple
767versions of perl under L<Building a shared libperl.so Perl library>.
768
aa689395
PP
769=head2 Other Compiler Flags
770
771For most users, all of the Configure defaults are fine. However,
772you can change a number of factors in the way perl is built
1ec51d55 773by adding appropriate -D directives to your ccflags variable in
aa689395
PP
774config.sh.
775
776For example, you can replace the rand() and srand() functions in the
777perl source by any other random number generator by a trick such as the
778following:
779
780 sh Configure -Dccflags='-Drand=random -Dsrand=srandom'
781
203c3eec
AD
782or by adding -Drand=random and -Dsrand=srandom to your ccflags
783at the appropriate Configure prompt. (Note: Although this worked for
784me, it might not work for you if your system's header files give
785different prototypes for rand() and random() or srand() and srandom().)
786
787You should also run Configure interactively to verify that a hint file
788doesn't inadvertently override your ccflags setting. (Hints files
789shouldn't do that, but some might.)
c3edaffb 790
8e07c86e
AD
791=head2 What if it doesn't work?
792
793=over 4
794
25f94b33
AD
795=item Running Configure Interactively
796
797If Configure runs into trouble, remember that you can always run
798Configure interactively so that you can check (and correct) its
799guesses.
800
801All the installation questions have been moved to the top, so you don't
aa689395 802have to wait for them. Once you've handled them (and your C compiler and
1ec51d55 803flags) you can type &-d at the next Configure prompt and Configure
25f94b33
AD
804will use the defaults from then on.
805
806If you find yourself trying obscure command line incantations and
807config.over tricks, I recommend you run Configure interactively
808instead. You'll probably save yourself time in the long run.
809
aa689395 810=item Hint files
8e07c86e
AD
811
812The perl distribution includes a number of system-specific hints files
813in the hints/ directory. If one of them matches your system, Configure
814will offer to use that hint file.
815
816Several of the hint files contain additional important information.
817If you have any problems, it is a good idea to read the relevant hint
1ec51d55 818file for further information. See hints/solaris_2.sh for an
8e07c86e
AD
819extensive example.
820
edb1cbcb
PP
821=item *** WHOA THERE!!! ***
822
823Occasionally, Configure makes a wrong guess. For example, on SunOS
8244.1.3, Configure incorrectly concludes that tzname[] is in the
825standard C library. The hint file is set up to correct for this. You
826will see a message:
827
828 *** WHOA THERE!!! ***
829 The recommended value for $d_tzname on this machine was "undef"!
830 Keep the recommended value? [y]
831
832You should always keep the recommended value unless, after reading the
833relevant section of the hint file, you are sure you want to try
834overriding it.
835
836If you are re-using an old config.sh, the word "previous" will be
837used instead of "recommended". Again, you will almost always want
838to keep the previous value, unless you have changed something on your
839system.
840
841For example, suppose you have added libgdbm.a to your system
842and you decide to reconfigure perl to use GDBM_File. When you run
843Configure again, you will need to add -lgdbm to the list of libraries.
844Now, Configure will find your gdbm library and will issue a message:
845
846 *** WHOA THERE!!! ***
847 The previous value for $i_gdbm on this machine was "undef"!
848 Keep the previous value? [y]
849
1ec51d55 850In this case, you do not want to keep the previous value, so you
c3edaffb 851should answer 'n'. (You'll also have to manually add GDBM_File to
edb1cbcb
PP
852the list of dynamic extensions to build.)
853
8e07c86e
AD
854=item Changing Compilers
855
856If you change compilers or make other significant changes, you should
1ec51d55 857probably not re-use your old config.sh. Simply remove it or
8e07c86e
AD
858rename it, e.g. mv config.sh config.sh.old. Then rerun Configure
859with the options you want to use.
860
1ec51d55
CS
861This is a common source of problems. If you change from cc to
862gcc, you should almost always remove your old config.sh.
8e07c86e 863
c3edaffb 864=item Propagating your changes to config.sh
8e07c86e 865
1ec51d55
CS
866If you make any changes to config.sh, you should propagate
867them to all the .SH files by running
868
869 sh Configure -S
870
871You will then have to rebuild by running
9d67150a
PP
872
873 make depend
874 make
8e07c86e
AD
875
876=item config.over
877
878You can also supply a shell script config.over to over-ride Configure's
879guesses. It will get loaded up at the very end, just before config.sh
880is created. You have to be careful with this, however, as Configure
d52d4e46 881does no checking that your changes make sense. See the section on
7f678428 882L<"Changing the installation directory"> for an example.
8e07c86e
AD
883
884=item config.h
885
1ec51d55
CS
886Many of the system dependencies are contained in config.h.
887Configure builds config.h by running the config_h.SH script.
888The values for the variables are taken from config.sh.
8e07c86e 889
1ec51d55
CS
890If there are any problems, you can edit config.h directly. Beware,
891though, that the next time you run Configure, your changes will be
8e07c86e
AD
892lost.
893
894=item cflags
895
896If you have any additional changes to make to the C compiler command
1ec51d55
CS
897line, they can be made in cflags.SH. For instance, to turn off the
898optimizer on toke.c, find the line in the switch structure for
899toke.c and put the command optimize='-g' before the ;; . You
900can also edit cflags directly, but beware that your changes will be
901lost the next time you run Configure.
8e07c86e 902
1ec51d55
CS
903To change the C flags for all the files, edit config.sh
904and change either $ccflags or $optimize,
905and then re-run
906
907 sh Configure -S
908 make depend
8e07c86e 909
aa689395 910=item No sh
8e07c86e 911
dfe9444c
AD
912If you don't have sh, you'll have to copy the sample file Porting/config_H
913to config.h and edit the config.h to reflect your system's peculiarities.
8e07c86e
AD
914You'll probably also have to extensively modify the extension building
915mechanism.
916
c3edaffb
PP
917=item Porting information
918
2ae324a7 919Specific information for the OS/2, Plan9, VMS and Win32 ports is in the
1ec51d55
CS
920corresponding README files and subdirectories. Additional information,
921including a glossary of all those config.sh variables, is in the Porting
c3edaffb
PP
922subdirectory.
923
7f678428 924Ports for other systems may also be available. You should check out
1ec51d55 925http://www.perl.com/CPAN/ports for current information on ports to
7f678428
PP
926various other operating systems.
927
8e07c86e
AD
928=back
929
930=head1 make depend
931
932This will look for all the includes.
1ec51d55
CS
933The output is stored in makefile. The only difference between
934Makefile and makefile is the dependencies at the bottom of
935makefile. If you have to make any changes, you should edit
936makefile, not Makefile since the Unix make command reads
937makefile first. (On non-Unix systems, the output may be stored in
c3edaffb
PP
938a different file. Check the value of $firstmakefile in your config.sh
939if in doubt.)
8e07c86e
AD
940
941Configure will offer to do this step for you, so it isn't listed
942explicitly above.
943
944=head1 make
945
946This will attempt to make perl in the current directory.
947
948If you can't compile successfully, try some of the following ideas.
7f678428
PP
949If none of them help, and careful reading of the error message and
950the relevant manual pages on your system doesn't help, you can
951send a message to either the comp.lang.perl.misc newsgroup or to
952perlbug@perl.com with an accurate description of your problem.
aa689395 953See L<"Reporting Problems"> below.
8e07c86e
AD
954
955=over 4
956
1ec51d55 957=item hints
8e07c86e
AD
958
959If you used a hint file, try reading the comments in the hint file
960for further tips and information.
961
1ec51d55 962=item extensions
8e07c86e 963
1ec51d55 964If you can successfully build miniperl, but the process crashes
c3edaffb
PP
965during the building of extensions, you should run
966
967 make minitest
968
969to test your version of miniperl.
970
e57fd563
PP
971=item locale
972
973If you have any locale-related environment variables set, try
974unsetting them. I have some reports that some versions of IRIX hang
975while running B<./miniperl configpm> with locales other than the C
3e6e419a
JH
976locale. See the discussion under L<"make test"> below about locales
977and the whole L<Locale problems> section in the file pod/perllocale.pod.
978The latter is especially useful if you see something like this
979
980 perl: warning: Setting locale failed.
981 perl: warning: Please check that your locale settings:
982 LC_ALL = "En_US",
983 LANG = (unset)
984 are supported and installed on your system.
985 perl: warning: Falling back to the standard locale ("C").
986
987at Perl startup.
e57fd563 988
1ec51d55 989=item malloc duplicates
c3edaffb 990
dc45a647
MB
991If you get duplicates upon linking for malloc et al, add -DEMBEDMYMALLOC
992to your ccflags variable in config.sh.
c3edaffb 993
7f678428 994=item varargs
c3edaffb
PP
995
996If you get varargs problems with gcc, be sure that gcc is installed
997correctly. When using gcc, you should probably have i_stdarg='define'
998and i_varargs='undef' in config.sh. The problem is usually solved by
999running fixincludes correctly. If you do change config.sh, don't
7f678428
PP
1000forget to propagate your changes (see
1001L<"Propagating your changes to config.sh"> below).
1002See also the L<"vsprintf"> item below.
c3edaffb 1003
1ec51d55 1004=item croak
c3edaffb
PP
1005
1006If you get error messages such as the following (the exact line
1007numbers will vary in different versions of perl):
1008
1009 util.c: In function `Perl_croak':
1010 util.c:962: number of arguments doesn't match prototype
1011 proto.h:45: prototype declaration
1012
1013it might well be a symptom of the gcc "varargs problem". See the
7f678428 1014previous L<"varargs"> item.
c3edaffb 1015
9d67150a 1016=item Solaris and SunOS dynamic loading
c3edaffb
PP
1017
1018If you have problems with dynamic loading using gcc on SunOS or
1019Solaris, and you are using GNU as and GNU ld, you may need to add
1ec51d55 1020-B/bin/ (for SunOS) or -B/usr/ccs/bin/ (for Solaris) to your
c3edaffb 1021$ccflags, $ldflags, and $lddlflags so that the system's versions of as
6877a1cf
AD
1022and ld are used. Note that the trailing '/' is required.
1023Alternatively, you can use the GCC_EXEC_PREFIX
c3edaffb 1024environment variable to ensure that Sun's as and ld are used. Consult
1ec51d55 1025your gcc documentation for further information on the -B option and
c3edaffb
PP
1026the GCC_EXEC_PREFIX variable.
1027
7beaa944
AD
1028One convenient way to ensure you are not using GNU as and ld is to
1029invoke Configure with
1030
1031 sh Configure -Dcc='gcc -B/usr/ccs/bin/'
1032
1033for Solaris systems. For a SunOS system, you must use -B/bin/
1034instead.
1035
84902520
TB
1036Alternatively, recent versions of GNU ld reportedly work if you
1037include C<-Wl,-export-dynamic> in the ccdlflags variable in
1038config.sh.
1039
9d67150a
PP
1040=item ld.so.1: ./perl: fatal: relocation error:
1041
1042If you get this message on SunOS or Solaris, and you're using gcc,
7f678428
PP
1043it's probably the GNU as or GNU ld problem in the previous item
1044L<"Solaris and SunOS dynamic loading">.
9d67150a 1045
1ec51d55 1046=item LD_LIBRARY_PATH
c3edaffb
PP
1047
1048If you run into dynamic loading problems, check your setting of
aa689395
PP
1049the LD_LIBRARY_PATH environment variable. If you're creating a static
1050Perl library (libperl.a rather than libperl.so) it should build
c3edaffb
PP
1051fine with LD_LIBRARY_PATH unset, though that may depend on details
1052of your local set-up.
1053
1054=item dlopen: stub interception failed
1055
1056The primary cause of the 'dlopen: stub interception failed' message is
1057that the LD_LIBRARY_PATH environment variable includes a directory
1058which is a symlink to /usr/lib (such as /lib).
1059
aa689395 1060The reason this causes a problem is quite subtle. The file libdl.so.1.0
c3edaffb
PP
1061actually *only* contains functions which generate 'stub interception
1062failed' errors! The runtime linker intercepts links to
1063"/usr/lib/libdl.so.1.0" and links in internal implementation of those
1064functions instead. [Thanks to Tim Bunce for this explanation.]
1065
aa689395 1066=item nm extraction
c3edaffb
PP
1067
1068If Configure seems to be having trouble finding library functions,
1069try not using nm extraction. You can do this from the command line
1070with
1071
1072 sh Configure -Uusenm
1073
1074or by answering the nm extraction question interactively.
1ec51d55 1075If you have previously run Configure, you should not reuse your old
c3edaffb
PP
1076config.sh.
1077
7f678428 1078=item vsprintf
c3edaffb
PP
1079
1080If you run into problems with vsprintf in compiling util.c, the
1081problem is probably that Configure failed to detect your system's
1082version of vsprintf(). Check whether your system has vprintf().
1083(Virtually all modern Unix systems do.) Then, check the variable
1084d_vprintf in config.sh. If your system has vprintf, it should be:
1085
1086 d_vprintf='define'
1087
1088If Configure guessed wrong, it is likely that Configure guessed wrong
1089on a number of other common functions too. You are probably better off
1090re-running Configure without using nm extraction (see previous item).
1091
3fe9a6f1
PP
1092=item do_aspawn
1093
1094If you run into problems relating to do_aspawn or do_spawn, the
1095problem is probably that Configure failed to detect your system's
1096fork() function. Follow the procedure in the previous items
1097on L<"vsprintf"> and L<"nm extraction">.
1098
84902520
TB
1099=item __inet_* errors
1100
1101If you receive unresolved symbol errors during Perl build and/or test
1102referring to __inet_* symbols, check to see whether BIND 8.1 is
1103installed. It installs a /usr/local/include/arpa/inet.h that refers to
1104these symbols. Versions of BIND later than 8.1 do not install inet.h
1105in that location and avoid the errors. You should probably update to a
1106newer version of BIND. If you can't, you can either link with the
1107updated resolver library provided with BIND 8.1 or rename
1108/usr/local/bin/arpa/inet.h during the Perl build and test process to
1109avoid the problem.
1110
aa689395 1111=item Optimizer
c3edaffb 1112
9d67150a 1113If you can't compile successfully, try turning off your compiler's
aa689395 1114optimizer. Edit config.sh and change the line
9d67150a
PP
1115
1116 optimize='-O'
1117
1118to something like
1119
1120 optimize=' '
1121
1122then propagate your changes with B<sh Configure -S> and rebuild
1123with B<make depend; make>.
1124
1ec51d55 1125=item CRIPPLED_CC
9d67150a 1126
1ec51d55 1127If you still can't compile successfully, try adding a -DCRIPPLED_CC
56c6f531
JH
1128flag. (Just because you get no errors doesn't mean it compiled right!)
1129This simplifies some complicated expressions for compilers that get
1130indigestion easily.
9d67150a
PP
1131
1132=item Missing functions
1133
1134If you have missing routines, you probably need to add some library or
1135other, or you need to undefine some feature that Configure thought was
1136there but is defective or incomplete. Look through config.h for
1137likely suspects.
8e07c86e 1138
1ec51d55 1139=item toke.c
8e07c86e 1140
1ec51d55
CS
1141Some compilers will not compile or optimize the larger files (such as
1142toke.c) without some extra switches to use larger jump offsets or
1143allocate larger internal tables. You can customize the switches for
1144each file in cflags. It's okay to insert rules for specific files into
1145makefile since a default rule only takes effect in the absence of a
8e07c86e
AD
1146specific rule.
1147
7f678428 1148=item Missing dbmclose
8e07c86e 1149
c3edaffb
PP
1150SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
1151that includes libdbm.nfs (which includes dbmclose()) may be available.
8e07c86e 1152
f3d9a6ba 1153=item Note (probably harmless): No library found for -lsomething
7f678428
PP
1154
1155If you see such a message during the building of an extension, but
1156the extension passes its tests anyway (see L<"make test"> below),
1157then don't worry about the warning message. The extension
1158Makefile.PL goes looking for various libraries needed on various
aa689395 1159systems; few systems will need all the possible libraries listed.
7f678428
PP
1160For example, a system may have -lcposix or -lposix, but it's
1161unlikely to have both, so most users will see warnings for the one
f3d9a6ba
CS
1162they don't have. The phrase 'probably harmless' is intended to
1163reassure you that nothing unusual is happening, and the build
1164process is continuing.
7f678428
PP
1165
1166On the other hand, if you are building GDBM_File and you get the
1167message
1168
f3d9a6ba 1169 Note (probably harmless): No library found for -lgdbm
7f678428
PP
1170
1171then it's likely you're going to run into trouble somewhere along
1172the line, since it's hard to see how you can use the GDBM_File
1173extension without the -lgdbm library.
1174
1175It is true that, in principle, Configure could have figured all of
1176this out, but Configure and the extension building process are not
1177quite that tightly coordinated.
1178
aa689395
PP
1179=item sh: ar: not found
1180
1181This is a message from your shell telling you that the command 'ar'
1182was not found. You need to check your PATH environment variable to
1183make sure that it includes the directory with the 'ar' command. This
1ec51d55 1184is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
aa689395
PP
1185directory.
1186
1187=item db-recno failure on tests 51, 53 and 55
1188
1189Old versions of the DB library (including the DB library which comes
1190with FreeBSD 2.1) had broken handling of recno databases with modified
1191bval settings. Upgrade your DB library or OS.
1192
1ec51d55 1193=item Miscellaneous
8e07c86e
AD
1194
1195Some additional things that have been reported for either perl4 or perl5:
1196
1197Genix may need to use libc rather than libc_s, or #undef VARARGS.
1198
1199NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
1200
1ec51d55 1201UTS may need one or more of -DCRIPPLED_CC, -K or -g, and undef LSTAT.
8e07c86e
AD
1202
1203If you get syntax errors on '(', try -DCRIPPLED_CC.
1204
1205Machines with half-implemented dbm routines will need to #undef I_ODBM
1206
8e07c86e
AD
1207=back
1208
1209=head1 make test
1210
84902520
TB
1211This will run the regression tests on the perl you just made (you
1212should run plain 'make' before 'make test' otherwise you won't have a
1213complete build). If 'make test' doesn't say "All tests successful"
1214then something went wrong. See the file t/README in the t subdirectory.
1215
84902520 1216Note that you can't run the tests in background if this disables
fb73857a
PP
1217opening of /dev/tty. You can use 'make test-notty' in that case but
1218a few tty tests will be skipped.
c3edaffb 1219
1ec51d55
CS
1220If make test bombs out, just cd to the t directory and run ./TEST
1221by hand to see if it makes any difference. If individual tests
c3edaffb 1222bomb, you can run them by hand, e.g.,
8e07c86e
AD
1223
1224 ./perl op/groups.t
1225
aa689395 1226Another way to get more detailed information about failed tests and
1ec51d55 1227individual subtests is to cd to the t directory and run
aa689395
PP
1228
1229 ./perl harness
1230
fb73857a 1231(this assumes that most basic tests succeed, since harness uses
aa689395
PP
1232complicated constructs).
1233
fb73857a 1234You should also read the individual tests to see if there are any helpful
c3edaffb
PP
1235comments that apply to your system.
1236
1ec51d55 1237Note: One possible reason for errors is that some external programs
c07a80fd 1238may be broken due to the combination of your environment and the way
3fe9a6f1 1239B<make test> exercises them. For example, this may happen if you have
1ec51d55
CS
1240one or more of these environment variables set: LC_ALL LC_CTYPE
1241LC_COLLATE LANG. In some versions of UNIX, the non-English locales
e57fd563
PP
1242are known to cause programs to exhibit mysterious errors.
1243
1244If you have any of the above environment variables set, please try
aa689395
PP
1245
1246 setenv LC_ALL C
1247
1248(for C shell) or
1249
1250 LC_ALL=C;export LC_ALL
1251
1ec51d55
CS
1252for Bourne or Korn shell) from the command line and then retry
1253make test. If the tests then succeed, you may have a broken program that
aa689395 1254is confusing the testing. Please run the troublesome test by hand as
e57fd563 1255shown above and see whether you can locate the program. Look for
1ec51d55
CS
1256things like: exec, `backquoted command`, system, open("|...") or
1257open("...|"). All these mean that Perl is trying to run some
e57fd563 1258external program.
eed2e782 1259
8e07c86e
AD
1260=head1 make install
1261
1262This will put perl into the public directory you specified to
1ec51d55 1263Configure; by default this is /usr/local/bin. It will also try
8e07c86e 1264to put the man pages in a reasonable place. It will not nroff the man
aa689395 1265pages, however. You may need to be root to run B<make install>. If you
8e07c86e
AD
1266are not root, you must own the directories in question and you should
1267ignore any messages about chown not working.
1268
1269If you want to see exactly what will happen without installing
1270anything, you can run
4633a7c4 1271
8e07c86e
AD
1272 ./perl installperl -n
1273 ./perl installman -n
1274
1ec51d55 1275make install will install the following:
8e07c86e
AD
1276
1277 perl,
1278 perl5.nnn where nnn is the current release number. This
1279 will be a link to perl.
1280 suidperl,
1281 sperl5.nnn If you requested setuid emulation.
1282 a2p awk-to-perl translator
1283 cppstdin This is used by perl -P, if your cc -E can't
1284 read from stdin.
1285 c2ph, pstruct Scripts for handling C structures in header files.
1286 s2p sed-to-perl translator
1287 find2perl find-to-perl translator
aa689395 1288 h2ph Extract constants and simple macros from C headers
8e07c86e 1289 h2xs Converts C .h header files to Perl extensions.
24b3df7f 1290 perlbug Tool to report bugs in Perl.
8e07c86e 1291 perldoc Tool to read perl's pod documentation.
aa689395 1292 pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules
8e07c86e 1293 pod2html, Converters from perl's pod documentation format
aa689395
PP
1294 pod2latex, to other useful formats.
1295 pod2man, and
1296 pod2text
1297 splain Describe Perl warnings and errors
8e07c86e
AD
1298
1299 library files in $privlib and $archlib specified to
1300 Configure, usually under /usr/local/lib/perl5/.
1301 man pages in the location specified to Configure, usually
1302 something like /usr/local/man/man1.
1303 module in the location specified to Configure, usually
1304 man pages under /usr/local/lib/perl5/man/man3.
1305 pod/*.pod in $privlib/pod/.
1306
4633a7c4
LW
1307Installperl will also create the library directories $siteperl and
1308$sitearch listed in config.sh. Usually, these are something like
24b3df7f
PP
1309 /usr/local/lib/perl5/site_perl/
1310 /usr/local/lib/perl5/site_perl/$archname
4633a7c4
LW
1311where $archname is something like sun4-sunos. These directories
1312will be used for installing extensions.
1313
56c6f531
JH
1314Perl's *.h header files and the libperl.a library are also installed
1315under $archlib so that any user may later build new extensions, run the
1316optional Perl compiler, or embed the perl interpreter into another
1317program even if the Perl source is no longer available.
8e07c86e 1318
aa689395 1319=head1 Coexistence with earlier versions of perl5
4633a7c4 1320
693762b4
AD
1321WARNING: The upgrade from 5.004_0x to 5.005 is going to be a bit
1322tricky. See L<"Upgrading from 5.004 to 5.005"> below.
1323
1324In general, you can usually safely upgrade from one version of Perl (e.g.
13255.004_04) to another similar version (e.g. 5.004_05) without re-compiling
1326all of your add-on extensions. You can also safely leave the old version
1327around in case the new version causes you problems for some reason.
1328For example, if you want to be sure that your script continues to run
dc45a647 1329with 5.004_04, simply replace the '#!/usr/local/bin/perl' line at the
693762b4
AD
1330top of the script with the particular version you want to run, e.g.
1331#!/usr/local/bin/perl5.00404.
1332
1333(If you are upgrading from 5.002 or earlier, beware that some of the
1334standard library files have changed in incompatible ways, so you are
1335probably better off starting with a fresh installation.)
1336
1337The standard library files in /usr/local/lib/perl5 should be usable by
1338all versions of perl5 after 5.002. An exception is the diagnostics.pm
1339module. Since that module uses the /usr/local/lib/perl5/pod/perldiag.pod
1340documentation file, the C<use diagnostics;> pragma and the splain script
1341will only identify and explain any warnings or errors that the most
1342recently-installed version of perl can generate. Usually, this is not
1343a problem.
1344
1345Most extensions will probably not need to be recompiled to use
1346with a newer version of perl. Here is how it is supposed to work.
1347(These examples assume you accept all the Configure defaults.)
1348
1349The directories searched by version 5.004_05 will be
1350
1351 /usr/local/lib/perl5/archname/5.00405
1352 /usr/local/lib/perl5/
1353 /usr/local/lib/perl5/site_perl/archname
1354 /usr/local/lib/perl5/site_perl
1355
1356while the directories searched by version 5.004_04 are
1357
1358 /usr/local/lib/perl5/archname/5.00404
1359 /usr/local/lib/perl5/
1360 /usr/local/lib/perl5/site_perl/archname
1361 /usr/local/lib/perl5/site_perl
1362
1363When you install an add-on extension, it gets installed into
1364/usr/local/lib/perl5/site_perl/archname (if it is architecture-specific.)
1365This directory is deliberately NOT version-specific so that both 5.004_04
1366and 5.004_05 can use the extension.
1367
1368However, if you do run into problems, and you want to continue to
1369use the old version of perl along with your extension, simply move
4633a7c4 1370those extension files to the appropriate version directory, such as
693762b4
AD
1371/usr/local/lib/perl5/archname/5.00404. Then use your newer version of
1372perl to rebuild and re-install the extension into site_perl. This way,
1373Perl 5.004_04 will find your files in the 5.00404 directory, and
1374newer versions of perl will find your newer extension in the site_perl
1375directory.
1376
1377=head2 Maintaining completely separate versions
4633a7c4 1378
1ec51d55 1379Many users prefer to keep all versions of perl in completely
d52d4e46
PP
1380separate directories. One convenient way to do this is by
1381using a separate prefix for each version, such as
1382
46bb10fb 1383 sh Configure -Dprefix=/opt/perl5.004
d52d4e46 1384
46bb10fb 1385and adding /opt/perl5.004/bin to the shell PATH variable. Such users
d52d4e46
PP
1386may also wish to add a symbolic link /usr/local/bin/perl so that
1387scripts can still start with #!/usr/local/bin/perl.
1388
693762b4
AD
1389Others might share a common directory for maintenance sub-versions
1390(e.g. 5.004 for all 5.004_0x versions), but change directory with
1391each major version.
1392
6877a1cf
AD
1393If you are installing a development subversion, you probably ought to
1394seriously consider using a separate directory, since development
1395subversions may not have all the compatibility wrinkles ironed out
1396yet.
1397
693762b4
AD
1398=head2 Upgrading from 5.004 to 5.005
1399
1400Extensions compiled with versions of perl prior to 5.004_50 will need
1401to be recompiled to be used with 5.004_50 and later.
1402
1403If you wish to continue using those extensions under 5.004_04, for
1404example, then you need to move those extensions from their current
dc45a647 1405directories, which are something like
693762b4
AD
1406
1407 /usr/local/lib/perl5/site_perl/
1408 /usr/local/lib/perl5/site_perl/archname
1409
1410to the version-specific directory such as
1411
1412 /usr/local/lib/perl5/archname/5.00404
1413
1414as described above.
1415
1416Once you have moved the 5.00404 versions of the extensions out of the
1417way, you may recompile and reinstall with 5.005.
1418
8e07c86e
AD
1419=head1 Coexistence with perl4
1420
1421You can safely install perl5 even if you want to keep perl4 around.
1422
1ec51d55
CS
1423By default, the perl5 libraries go into /usr/local/lib/perl5/, so
1424they don't override the perl4 libraries in /usr/local/lib/perl/.
8e07c86e
AD
1425
1426In your /usr/local/bin directory, you should have a binary named
1ec51d55 1427perl4.036. That will not be touched by the perl5 installation
8e07c86e
AD
1428process. Most perl4 scripts should run just fine under perl5.
1429However, if you have any scripts that require perl4, you can replace
1ec51d55 1430the #! line at the top of them by #!/usr/local/bin/perl4.036
edb1cbcb
PP
1431(or whatever the appropriate pathname is). See pod/perltrap.pod
1432for possible problems running perl4 scripts under perl5.
8e07c86e 1433
aa689395
PP
1434=head1 cd /usr/include; h2ph *.h sys/*.h
1435
1436Some perl scripts need to be able to obtain information from
1437the system header files. This command will convert the most commonly used
1ec51d55 1438header files in /usr/include into files that can be easily interpreted
aa689395 1439by perl. These files will be placed in the architectural library directory
1ec51d55
CS
1440you specified to Configure; by default this is
1441/usr/local/lib/perl5/ARCH/VERSION, where ARCH is your architecture
1442(such as sun4-solaris) and VERSION is the version of perl you are
1443building (for example, 5.004).
aa689395 1444
1ec51d55 1445Note: Due to differences in the C and perl languages, the
aa689395
PP
1446conversion of the header files is not perfect. You will probably have
1447to hand-edit some of the converted files to get them to parse
1448correctly. For example, h2ph breaks spectacularly on type casting and
1449certain structures.
1450
fb73857a 1451=head1 installhtml --help
aa689395 1452
3e3baf6d
TB
1453Some sites may wish to make perl documentation available in HTML
1454format. The installhtml utility can be used to convert pod
fb73857a 1455documentation into linked HTML files and install them.
aa689395 1456
fb73857a 1457The following command-line is an example of one used to convert
3e3baf6d 1458perl documentation:
aa689395 1459
3e3baf6d
TB
1460 ./installhtml \
1461 --podroot=. \
1462 --podpath=lib:ext:pod:vms \
1463 --recurse \
1464 --htmldir=/perl/nmanual \
1465 --htmlroot=/perl/nmanual \
1466 --splithead=pod/perlipc \
1467 --splititem=pod/perlfunc \
1468 --libpods=perlfunc:perlguts:perlvar:perlrun:perlop \
1469 --verbose
1470
1471See the documentation in installhtml for more details. It can take
1472many minutes to execute a large installation and you should expect to
1473see warnings like "no title", "unexpected directive" and "cannot
1474resolve" as the files are processed. We are aware of these problems
1475(and would welcome patches for them).
aa689395 1476
fb73857a
PP
1477You may find it helpful to run installhtml twice. That should reduce
1478the number of "cannot resolve" warnings.
1479
aa689395
PP
1480=head1 cd pod && make tex && (process the latex files)
1481
1482Some sites may also wish to make the documentation in the pod/ directory
1483available in TeX format. Type
1484
1485 (cd pod && make tex && <process the latex files>)
1486
1487=head1 Reporting Problems
1488
1489If you have difficulty building perl, and none of the advice in this
1490file helps, and careful reading of the error message and the relevant
1491manual pages on your system doesn't help either, then you should send a
1492message to either the comp.lang.perl.misc newsgroup or to
1493perlbug@perl.com with an accurate description of your problem.
1494
1ec51d55 1495Please include the output of the ./myconfig shell script
aa689395 1496that comes with the distribution. Alternatively, you can use the
1ec51d55 1497perlbug program that comes with the perl distribution,
aa689395
PP
1498but you need to have perl compiled and installed before you can use it.
1499
1ec51d55 1500You might also find helpful information in the Porting
aa689395
PP
1501directory of the perl distribution.
1502
8e07c86e
AD
1503=head1 DOCUMENTATION
1504
1505Read the manual entries before running perl. The main documentation is
1506in the pod/ subdirectory and should have been installed during the
1507build process. Type B<man perl> to get started. Alternatively, you
1ec51d55 1508can type B<perldoc perl> to use the supplied perldoc script. This
8e07c86e
AD
1509is sometimes useful for finding things in the library modules.
1510
1ec51d55
CS
1511Under UNIX, you can produce a documentation book in postscript form,
1512along with its table of contents, by going to the pod/ subdirectory
34a2a22e
RM
1513and running (either):
1514
1515 ./roffitall -groff # If you have GNU groff installed
aa689395 1516 ./roffitall -psroff # If you have psroff
34a2a22e
RM
1517
1518This will leave you with two postscript files ready to be printed.
aa689395
PP
1519(You may need to fix the roffitall command to use your local troff
1520set-up.)
34a2a22e
RM
1521
1522Note that you must have performed the installation already before
1523running the above, since the script collects the installed files to
1524generate the documentation.
1525
8e07c86e
AD
1526=head1 AUTHOR
1527
fb73857a
PP
1528Original author: Andy Dougherty doughera@lafcol.lafayette.edu ,
1529borrowing very heavily from the original README by Larry Wall,
1530with lots of helpful feedback and additions from the
1531perl5-porters@perl.org folks.
1532
1533If you have problems or questions, please see L<"Reporting Problems">
1534above.
8e07c86e 1535
a5f75d66 1536=head1 LAST MODIFIED
24b3df7f 1537
dc45a647 1538$Id: INSTALL,v 1.32 1998/03/20 19:20:08 doughera Released $