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