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