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