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