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