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