Add documentation for default UNIVERSAL methods
[p5sagit/p5-mst-13.2.git] / INSTALL
CommitLineData
8e07c86e 1=head1 NAME
2
3Install - Build and Installation guide for perl5.
4
5=head1 SYNOPSIS
6
7The basic steps to build and install perl5 are:
8
9 rm -f config.sh
10 sh Configure
11 make
12 make test
13 make install
14
15Each of these is explained in further detail below.
16
edb1cbcb 17You should probably at least skim through this entire document before
18proceeding. Special notes specific to this release are identified
19by B<NOTE>.
20
eed2e782 21If you're building Perl on a non-Unix system, you should also read
22the README file specific to your operating system, since this may
23provide additional or different instructions for building Perl.
24
25=head1 DESCRIPTION
26
27The following is the procedures you need to follow in order to successfully
28build perl.
8e07c86e 29
30=head1 Start with a Fresh Distribution.
31
edb1cbcb 32If you have built perl before, you should clean out the build directory
33with the command
34
35 make realclean
36
8e07c86e 37The results of a Configure run are stored in the config.sh file. If
38you are upgrading from a previous version of perl, or if you change
39systems or compilers or make other significant changes, or if you are
40experiencing difficulties building perl, you should probably I<not>
41re-use your old config.sh. Simply remove it or rename it, e.g.
42
43 mv config.sh config.sh.old
4633a7c4 44
8e07c86e 45Then run Configure.
46
47=head1 Run Configure.
48
49Configure will figure out various things about your system. Some
50things Configure will figure out for itself, other things it will ask
51you about. To accept the default, just press C<RETURN>. The default
52is almost always ok.
53
54After it runs, Configure will perform variable substitution on all the
55F<*.SH> files and offer to run B<make depend>.
56
57Configure supports a number of useful options. Run B<Configure -h>
58to get a listing. To compile with gcc, for example, you can run
59
60 sh Configure -Dcc=gcc
61
62This is the preferred way to specify gcc (or another alternative
63compiler) so that the hints files can set appropriate defaults.
64
4633a7c4 65If you want to use your old config.sh but override some of the items
66with command line options, you need to use B<Configure -O>.
67
8e07c86e 68If you are willing to accept all the defaults, and you want terse
69output, you can run
70
71 sh Configure -des
72
73By default, for most systems, perl will be installed in
74/usr/local/{bin, lib, man}. You can specify a different 'prefix' for
75the default installation directory, when Configure prompts you or by
76using the Configure command line option -Dprefix='/some/directory',
77e.g.
78
25f94b33 79 sh Configure -Dprefix=/opt/perl
4633a7c4 80
81If your prefix contains the string "perl", then the directories
82are simplified. For example, if you use prefix=/opt/perl,
83then Configure will suggest /opt/perl/lib instead of
84/usr/local/lib/perl5/.
8e07c86e 85
86By default, Configure will compile perl to use dynamic loading, if
87your system supports it. If you want to force perl to be compiled
88statically, you can either choose this when Configure prompts you or by
89using the Configure command line option -Uusedl.
90
24b3df7f 91=head2 Extensions
92
edb1cbcb 93By default, Configure will offer to build every extension which appears
94to be supported. For example, Configure will offer to build GDBM_File
95only if it is able to find the gdbm library. (See examples below.)
96DynaLoader, Fcntl and FileHandle are always built by default.
97Configure does not contain code to test for POSIX compliance, so POSIX
98is always built by default as well. If you wish to skip POSIX, you can
99set the Configure variable useposix=false either in a hint file or from
100the Configure command line. Similarly, the Safe extension is always
101built by default, but you can skip it by setting the Configure variable
24b3df7f 102usesafe=false either in a hint file for from the command line.
103
104In summary, here are the Configure command-line variables you can set
105to turn off each extension:
106
107 DB_File i_db
108 DynaLoader (Must always be included)
109 Fcntl (Always included by default)
edb1cbcb 110 FileHandle (Always included by default)
24b3df7f 111 GDBM_File i_gdbm
112 NDBM_File i_ndbm
113 ODBM_File i_dbm
114 POSIX useposix
115 SDBM_File (Always included by default)
116 Safe usesafe
117 Socket d_socket
118
119Thus to skip the NDBM_File extension, you can use
120
121 sh Configure -Ui_ndbm
122
123Again, this is taken care of automatically if you don't have the ndbm
124library.
125
126Of course, you may always run Configure interactively and select only
127the Extensions you want.
128
129Finally, if you have dynamic loading (most modern Unix systems do)
130remember that these extensions do not increase the size of your perl
131executable, nor do they impact start-up time, so you probably might as
132well build all the ones that will work on your system.
133
8e07c86e 134=head2 GNU-style configure
135
136If you prefer the GNU-style B<configure> command line interface, you can
137use the supplied B<configure> command, e.g.
138
139 CC=gcc ./configure
140
141The B<configure> script emulates several of the more common configure
142options. Try
143
144 ./configure --help
145
146for a listing.
147
148Cross compiling is currently not supported.
149
150=head2 Including locally-installed libraries
151
4633a7c4 152Perl5 comes with interfaces to number of database extensions, including
153dbm, ndbm, gdbm, and Berkeley db. For each extension, if
154Configure can find the appropriate header files and libraries, it will
155automatically include that extension. The gdbm and db libraries
156are B<not> included with perl. See the library documentation for
157how to obtain the libraries.
8e07c86e 158
159I<Note:> If your database header (.h) files are not in a
160directory normally searched by your C compiler, then you will need to
161include the appropriate B<-I/your/directory> option when prompted by
162Configure. If your database library (.a) files are not in a directory
163normally searched by your C compiler and linker, then you will need to
164include the appropriate B<-L/your/directory> option when prompted by
165Configure. See the examples below.
166
167=head2 Examples
168
169=over 4
170
171=item gdbm in /usr/local.
172
173Suppose you have gdbm and want Configure to find it and build the
174GDBM_File extension. This examples assumes you have F<gdbm.h>
175installed in F</usr/local/include/gdbm.h> and F<libgdbm.a> installed in
176F</usr/local/lib/libgdbm.a>. Configure should figure all the
177necessary steps out automatically.
178
179Specifically, when Configure prompts you for flags for
180your C compiler, you should include C<-I/usr/local/include>.
181
182When Configure prompts you for linker flags, you should include
183C<-L/usr/local/lib>.
184
185If you are using dynamic loading, then when Configure prompts you for
186linker flags for dynamic loading, you should again include
187C<-L/usr/local/lib>.
188
189Again, this should all happen automatically. If you want to accept the
190defaults for all the questions and have Configure print out only terse
191messages, then you can just run
192
193 sh Configure -des
194
195and Configure should include the GDBM_File extension automatically.
196
197This should actually work if you have gdbm installed in any of
198(/usr/local, /opt/local, /usr/gnu, /opt/gnu, /usr/GNU, or /opt/GNU).
199
200=item gdbm in /usr/you
201
202Suppose you have gdbm installed in some place other than /usr/local/,
203but you still want Configure to find it. To be specific, assume you
204have F</usr/you/include/gdbm.h> and F</usr/you/lib/libgdbm.a>. You
205still have to add B<-I/usr/you/include> to cc flags, but you have to take
206an extra step to help Configure find F<libgdbm.a>. Specifically, when
207Configure prompts you for library directories, you have to add
208F</usr/you/lib> to the list.
209
210It is possible to specify this from the command line too (all on one
211line):
212
213 sh Configure -des \
214 -Dlocincpth="/usr/you/include" \
215 -Dloclibpth="/usr/you/lib"
216
217C<locincpth> is a space-separated list of include directories to search.
218Configure will automatically add the appropriate B<-I> directives.
219
220C<loclibpth> is a space-separated list of library directories to search.
221Configure will automatically add the appropriate B<-L> directives. If
222you have some libraries under F</usr/local/> and others under
223F</usr/you>, then you have to include both, namely
224
225 sh Configure -des \
226 -Dlocincpth="/usr/you/include /usr/local/include" \
227 -Dloclibpth="/usr/you/lib /usr/local/lib"
228
229=back
230
4633a7c4 231=head2 Installation Directories.
232
233The installation directories can all be changed by answering the
234appropriate questions in Configure. For convenience, all the
235installation questions are near the beginning of Configure.
236
237By default, Configure uses the following directories for
238library files (archname is a string like sun4-sunos, determined
239by Configure)
240
241 /usr/local/lib/perl5/archname/5.002
242 /usr/local/lib/perl5/
24b3df7f 243 /usr/local/lib/perl5/site_perl/archname
244 /usr/local/lib/perl5/site_perl
4633a7c4 245
246and the following directories for manual pages:
247
248 /usr/local/man/man1
249 /usr/local/lib/perl5/man/man3
250
251(Actually, Configure recognizes the SVR3-style
252/usr/local/man/l_man/man1 directories, if present, and uses those
253instead.) The module man pages are stuck in that strange spot so that
254they don't collide with other man pages stored in /usr/local/man/man3,
255and so that Perl's man pages don't hide system man pages. On some
256systems, B<man less> would end up calling up Perl's less.pm module man
257page, rather than the B<less> program.
258
259If you specify a prefix that contains the string "perl", then the
260directory structure is simplified. For example, if you Configure
261with -Dprefix=/opt/perl, then the defaults are
262
263 /opt/perl/lib/archname/5.002
264 /opt/perl/lib
265 /opt/perl/lib/site_perl/archname
266 /opt/perl/lib/site_perl
267
268 /opt/perl/man/man1
269 /opt/perl/man/man3
270
271The perl executable will search the libraries in the order given
272above.
273
274The directories site_perl and site_perl/archname are empty, but are
275intended to be used for installing local or site-wide extensions. Perl
276will automatically look in these directories. Previously, most sites
277just put their local extensions in with the standard distribution.
278
279In order to support using things like #!/usr/local/bin/perl5.002 after
280a later version is released, architecture-dependent libraries are
281stored in a version-specific directory, such as
282/usr/local/lib/perl5/archname/5.002/. In 5.000 and 5.001, these files
283were just stored in /usr/local/lib/perl5/archname/. If you will not be
284using 5.001 binaries, you can delete the standard extensions from the
285/usr/local/lib/perl5/archname/ directory. Locally-added extensions can
286be moved to the site_perl and site_perl/archname directories.
287
288Again, these are just the defaults, and can be changed as you run
289Configure.
290
8e07c86e 291=head2 Changing the installation directory
292
293Configure distinguishes between the directory in which perl (and its
294associated files) should be installed and the directory in which it
295will eventually reside. For most sites, these two are the same; for
296sites that use AFS, this distinction is handled automatically.
297However, sites that use software such as B<depot> to manage software
298packages may also wish to install perl into a different directory and
299use that management software to move perl to its final destination.
300This section describes how to do this. Someday, Configure may support
301an option C<-Dinstallprefix=/foo> to simplify this.
302
303Suppose you want to install perl under the F</tmp/perl5> directory.
304You can edit F<config.sh> and change all the install* variables to
305point to F</tmp/perl5> instead of F</usr/local/wherever>. You could
306also set them all from the Configure command line. Or, you can
307automate this process by placing the following lines in a file
308F<config.over> B<before> you run Configure (replace /tmp/perl5 by a
309directory of your choice):
310
311 installprefix=/tmp/perl5
312 test -d $installprefix || mkdir $installprefix
313 test -d $installprefix/bin || mkdir $installprefix/bin
314 installarchlib=`echo $installarchlib | sed "s!$prefix!$installprefix!"`
315 installbin=`echo $installbin | sed "s!$prefix!$installprefix!"`
316 installman1dir=`echo $installman1dir | sed "s!$prefix!$installprefix!"`
317 installman3dir=`echo $installman3dir | sed "s!$prefix!$installprefix!"`
318 installprivlib=`echo $installprivlib | sed "s!$prefix!$installprefix!"`
319 installscript=`echo $installscript | sed "s!$prefix!$installprefix!"`
320 installsitelib=`echo $installsitelib | sed "s!$prefix!$installprefix!"`
4633a7c4 321 installsitearch=`echo $installsitearch | sed "s!$prefix!$installprefix!"`
91c9f482 322 shrpdir=`echo $shrpdir | sed "s!$prefix!$installprefix!"`
8e07c86e 323
324Then, you can Configure and install in the usual way:
325
25f94b33 326 sh Configure -des
8e07c86e 327 make
328 make test
329 make install
330
331=head2 Creating an installable tar archive
332
333If you need to install perl on many identical systems, it is
334convenient to compile it once and create an archive that can be
335installed on multiple systems. Here's one way to do that:
336
337 # Set up config.over to install perl into a different directory,
338 # e.g. /tmp/perl5 (see previous part).
25f94b33 339 sh Configure -des
8e07c86e 340 make
341 make test
342 make install
343 cd /tmp/perl5
344 tar cvf ../perl5-archive.tar .
345 # Then, on each machine where you want to install perl,
346 cd /usr/local # Or wherever you specified as $prefix
347 tar xvf perl5-archive.tar
348
349=head2 What if it doesn't work?
350
351=over 4
352
25f94b33 353=item Running Configure Interactively
354
355If Configure runs into trouble, remember that you can always run
356Configure interactively so that you can check (and correct) its
357guesses.
358
359All the installation questions have been moved to the top, so you don't
360have to wait for them. Once you've handled them (and your C compiler &
eed2e782 361flags) you can type C<&-d> at the next Configure prompt and Configure
25f94b33 362will use the defaults from then on.
363
364If you find yourself trying obscure command line incantations and
365config.over tricks, I recommend you run Configure interactively
366instead. You'll probably save yourself time in the long run.
367
8e07c86e 368=item Hint files.
369
370The perl distribution includes a number of system-specific hints files
371in the hints/ directory. If one of them matches your system, Configure
372will offer to use that hint file.
373
374Several of the hint files contain additional important information.
375If you have any problems, it is a good idea to read the relevant hint
376file for further information. See F<hints/solaris_2.sh> for an
377extensive example.
378
edb1cbcb 379=item *** WHOA THERE!!! ***
380
381Occasionally, Configure makes a wrong guess. For example, on SunOS
3824.1.3, Configure incorrectly concludes that tzname[] is in the
383standard C library. The hint file is set up to correct for this. You
384will see a message:
385
386 *** WHOA THERE!!! ***
387 The recommended value for $d_tzname on this machine was "undef"!
388 Keep the recommended value? [y]
389
390You should always keep the recommended value unless, after reading the
391relevant section of the hint file, you are sure you want to try
392overriding it.
393
394If you are re-using an old config.sh, the word "previous" will be
395used instead of "recommended". Again, you will almost always want
396to keep the previous value, unless you have changed something on your
397system.
398
399For example, suppose you have added libgdbm.a to your system
400and you decide to reconfigure perl to use GDBM_File. When you run
401Configure again, you will need to add -lgdbm to the list of libraries.
402Now, Configure will find your gdbm library and will issue a message:
403
404 *** WHOA THERE!!! ***
405 The previous value for $i_gdbm on this machine was "undef"!
406 Keep the previous value? [y]
407
408In this case, you do I<not> want to keep the previous value, so you
409should answer 'n'. (You'll also have to manuually add GDBM_File to
410the list of dynamic extensions to build.)
411
8e07c86e 412=item Changing Compilers
413
414If you change compilers or make other significant changes, you should
415probably I<not> re-use your old config.sh. Simply remove it or
416rename it, e.g. mv config.sh config.sh.old. Then rerun Configure
417with the options you want to use.
418
419This is a common source of problems. If you change from B<cc> to
420B<gcc>, you should almost always remove your old config.sh.
421
422=item Propagating your changes
423
424If you later make any changes to F<config.sh>, you should propagate
25f94b33 425them to all the .SH files by running B<sh Configure -S>.
8e07c86e 426
427=item config.over
428
429You can also supply a shell script config.over to over-ride Configure's
430guesses. It will get loaded up at the very end, just before config.sh
431is created. You have to be careful with this, however, as Configure
d52d4e46 432does no checking that your changes make sense. See the section on
433changing the installation directory for an example.
8e07c86e 434
435=item config.h
436
437Many of the system dependencies are contained in F<config.h>.
438F<Configure> builds F<config.h> by running the F<config_h.SH> script.
439The values for the variables are taken from F<config.sh>.
440
441If there are any problems, you can edit F<config.h> directly. Beware,
442though, that the next time you run B<Configure>, your changes will be
443lost.
444
445=item cflags
446
447If you have any additional changes to make to the C compiler command
448line, they can be made in F<cflags.SH>. For instance, to turn off the
449optimizer on F<toke.c>, find the line in the switch structure for
450F<toke.c> and put the command C<optimize='-g'> before the C<;;>. You
451can also edit F<cflags> directly, but beware that your changes will be
452lost the next time you run B<Configure>.
453
454To change the C flags for all the files, edit F<config.sh>
455and change either C<$ccflags> or C<$optimize>,
25f94b33 456and then re-run B<sh Configure -S ; make depend>.
8e07c86e 457
458=item No sh.
459
460If you don't have sh, you'll have to copy the sample file config_H to
461config.h and edit the config.h to reflect your system's peculiarities.
462You'll probably also have to extensively modify the extension building
463mechanism.
464
465=back
466
467=head1 make depend
468
469This will look for all the includes.
470The output is stored in F<makefile>. The only difference between
471F<Makefile> and F<makefile> is the dependencies at the bottom of
472F<makefile>. If you have to make any changes, you should edit
473F<makefile>, not F<Makefile> since the Unix B<make> command reads
4633a7c4 474F<makefile> first.
8e07c86e 475
476Configure will offer to do this step for you, so it isn't listed
477explicitly above.
478
479=head1 make
480
481This will attempt to make perl in the current directory.
482
483If you can't compile successfully, try some of the following ideas.
484
485=over 4
486
487=item *
488
489If you used a hint file, try reading the comments in the hint file
490for further tips and information.
491
492=item *
493
494If you can't compile successfully, try adding a C<-DCRIPPLED_CC> flag.
495(Just because you get no errors doesn't mean it compiled right!)
496This simplifies some complicated expressions for compilers that
497get indigestion easily. If that has no effect, try turning off
498optimization. If you have missing routines, you probably need to
499add some library or other, or you need to undefine some feature that
500Configure thought was there but is defective or incomplete.
501
502=item *
503
504Some compilers will not compile or optimize the larger files without
505some extra switches to use larger jump offsets or allocate larger
506internal tables. You can customize the switches for each file in
507F<cflags>. It's okay to insert rules for specific files into
508F<makefile> since a default rule only takes effect in the absence of a
509specific rule.
510
511=item *
512
513If you can successfully build F<miniperl>, but the process crashes
514during the building of extensions, you should run
515
516 make minitest
517
518to test your version of miniperl.
519
520=item *
521
522Some additional things that have been reported for either perl4 or perl5:
523
524Genix may need to use libc rather than libc_s, or #undef VARARGS.
525
526NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
527
528UTS may need one or more of B<-DCRIPPLED_CC>, B<-K> or B<-g>, and undef LSTAT.
529
530If you get syntax errors on '(', try -DCRIPPLED_CC.
531
532Machines with half-implemented dbm routines will need to #undef I_ODBM
533
534SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
535that includes libdbm.nfs (which includes dbmclose()) may be available.
536
537If you get duplicates upon linking for malloc et al, say -DHIDEMYMALLOC.
538
539If you get duplicate function definitions (a perl function has the
540same name as another function on your system) try -DEMBED.
541
542If you get varags problems with gcc, be sure that gcc is installed
543correctly. When using gcc, you should probably have i_stdarg='define'
544and i_varags='undef' in config.sh. The problem is usually solved
545by running fixincludes correctly.
546
91c9f482 547If you have problems with dynamic loading using gcc on SunOS or
548Solaris, and you are using GNU as and GNU ld, you may need to add
eed2e782 549B<-B/bin/> (for SunOS) or B<-B/usr/ccs/bin/> (for Solaris) to your
91c9f482 550$ccflags, $ldflags, and $lddlflags so that the system's versions of as
8e07c86e 551and ld are used.
552
553If you run into dynamic loading problems, check your setting of
554the LD_LIBRARY_PATH environment variable. Perl should build
555fine with LD_LIBRARY_PATH unset, though that may depend on details
556of your local set-up.
557
24b3df7f 558If Configure seems to be having trouble finding library functions,
559try not using nm extraction. You can do this from the command line
560with
561
562 sh Configure -Uusenm
563
8e07c86e 564=back
565
566=head1 make test
567
568This will run the regression tests on the perl you just made. If it
569doesn't say "All tests successful" then something went wrong. See the
570file F<t/README> in the F<t> subdirectory. Note that you can't run it
571in background if this disables opening of /dev/tty. If B<make test>
572bombs out, just B<cd> to the F<t> directory and run B<TEST> by hand
573to see if it makes any difference.
574If individual tests bomb, you can run them by hand, e.g.,
575
576 ./perl op/groups.t
577
edb1cbcb 578B<Note>: one possible reason for errors is that some external programs
c07a80fd 579may be broken due to the combination of your environment and the way
580C<make test> exercises them. This may happen for example if you have
581one or more of these environment variables set:
582C<LC_ALL LC_CTYPE LANG>. In certain UNIXes especially the non-English
583locales are known to cause programs to exhibit mysterious errors.
584If you have any of the above environment variables set, please try
585C<setenv LC_ALL C> or <LC_ALL=C;export LC_ALL>, for C<csh>-style and
586C<Bourne>-style shells, respectively, from the command line and then
587retry C<make test>. If the tests then succeed, you may have a broken
588program that is confusing the testing. Please run the troublesome test
589by hand as shown above and see whether you can locate the program.
590Look for things like:
591C<exec, `backquoted command`, system, open("|...")> or C<open("...|")>.
592All these mean that Perl is trying to run some external program.
eed2e782 593
8e07c86e 594=head1 INSTALLING PERL5
595
596=head1 make install
597
598This will put perl into the public directory you specified to
599B<Configure>; by default this is F</usr/local/bin>. It will also try
600to put the man pages in a reasonable place. It will not nroff the man
601page, however. You may need to be root to run B<make install>. If you
602are not root, you must own the directories in question and you should
603ignore any messages about chown not working.
604
edb1cbcb 605B<NOTE:> In the 5.002 release, you will see some harmless error
a5f75d66 606messages and warnings from pod2man. You may safely ignore them. (Yes,
607they should be fixed, but they didn't seem important enough to warrant
608holding up the entire 5.002 release.)
609
8e07c86e 610If you want to see exactly what will happen without installing
611anything, you can run
4633a7c4 612
8e07c86e 613 ./perl installperl -n
614 ./perl installman -n
615
616B<make install> will install the following:
617
618 perl,
619 perl5.nnn where nnn is the current release number. This
620 will be a link to perl.
621 suidperl,
622 sperl5.nnn If you requested setuid emulation.
623 a2p awk-to-perl translator
624 cppstdin This is used by perl -P, if your cc -E can't
625 read from stdin.
626 c2ph, pstruct Scripts for handling C structures in header files.
627 s2p sed-to-perl translator
628 find2perl find-to-perl translator
629 h2xs Converts C .h header files to Perl extensions.
24b3df7f 630 perlbug Tool to report bugs in Perl.
8e07c86e 631 perldoc Tool to read perl's pod documentation.
632 pod2html, Converters from perl's pod documentation format
633 pod2latex, and to other useful formats.
634 pod2man
635
636 library files in $privlib and $archlib specified to
637 Configure, usually under /usr/local/lib/perl5/.
638 man pages in the location specified to Configure, usually
639 something like /usr/local/man/man1.
640 module in the location specified to Configure, usually
641 man pages under /usr/local/lib/perl5/man/man3.
642 pod/*.pod in $privlib/pod/.
643
4633a7c4 644Installperl will also create the library directories $siteperl and
645$sitearch listed in config.sh. Usually, these are something like
24b3df7f 646 /usr/local/lib/perl5/site_perl/
647 /usr/local/lib/perl5/site_perl/$archname
4633a7c4 648where $archname is something like sun4-sunos. These directories
649will be used for installing extensions.
650
8e07c86e 651Perl's *.h header files and the libperl.a library are also
652installed under $archlib so that any user may later build new
653extensions even if the Perl source is no longer available.
654
655The libperl.a library is only needed for building new
656extensions and linking them statically into a new perl executable.
657If you will not be doing that, then you may safely delete
658$archlib/libperl.a after perl is installed.
659
660make install may also offer to install perl in a "standard" location.
661
662Most of the documentation in the pod/ directory is also available
663in HTML and LaTeX format. Type
664
665 cd pod; make html; cd ..
666
667to generate the html versions, and
668
669 cd pod; make tex; cd ..
670
671to generate the LaTeX versions.
672
eed2e782 673=head1 cd /usr/include; h2ph *.h sys/*.h
674
675Some of the perl library files need to be able to obtain information from
676the system header files. This command will convert the most commonly used
677header files in F</usr/include> into files that can be easily interpreted
678by perl. These files will be placed in architectural library directory
679you specified to B<Configure>; by default this is
680F</usr/local/lib/perl5/ARCH/VERSION>, where B<ARCH> is your architecture
681(such as C<sun4-solaris>) and B<VERSION> is the version of perl you are
682building (for example, C<5.003>).
683
684B<NOTE:> Due to differences in the C and perl languages, the conversion of
685the header files in not perfect. You may have to hand edit some of the
686converted files to get them to parse correctly. For example, it breaks
687spectacularly on type casting and certain structures.
688
4633a7c4 689=head1 Coexistence with earlier versions of perl5.
690
eed2e782 691You can safely install the current version of perl5 and still run scripts
692under the old binaries for versions 5.002 and later ONLY. Instead of
693starting your script with #!/usr/local/bin/perl, just start it with
694#!/usr/local/bin/perl5.001 (or whatever version you want to run.)
695If you want to retain a version of perl5 prior to perl5.002, you'll
696need to install the current version in a separate directory tree,
697since some of the architecture-independent library files have changed
698in incompatible ways.
4633a7c4 699
700The architecture-dependent files are stored in a version-specific
701directory (such as F</usr/local/lib/perl5/sun4-sunos/5.002>) so that
702they are still accessible. I<Note:> perl5.000 and perl5.001 did not
703put their architecture-dependent libraries in a version-specific
704directory. They are simply in F</usr/local/lib/perl5/$archname>. If
705you will not be using 5.000 or 5.001, you may safely remove those
706files.
707
708The standard library files in F</usr/local/lib/perl5>
eed2e782 709should be useable by all versions of perl5 since perl5.002.
4633a7c4 710
d52d4e46 711Most extensions will probably not need to be recompiled to use with a newer
4633a7c4 712version of perl. If you do run into problems, and you want to continue
713to use the old version of perl along with your extension, simply move
714those extension files to the appropriate version directory, such as
715F</usr/local/lib/perl/archname/5.002>. Then perl5.002 will find your
716files in the 5.002 directory, and newer versions of perl will find your
717newer extension in the site_perl directory.
718
d52d4e46 719Some users may prefer to keep all versions of perl in completely
720separate directories. One convenient way to do this is by
721using a separate prefix for each version, such as
722
723 sh Configure -Dprefix=/opt/perl5.002
724
725and adding /opt/perl5.002/bin to the shell PATH variable. Such users
726may also wish to add a symbolic link /usr/local/bin/perl so that
727scripts can still start with #!/usr/local/bin/perl.
728
edb1cbcb 729B<NOTE>: Starting with 5.002_01, all functions in the perl C source
730code are protected by default by the prefix Perl_ (or perl_) so that
731you may link with third-party libraries without fear of namespace
732collisons. This breaks compatability with the initially released
733version of 5.002, so once you install 5.002_01 (or higher) you will
734need to re-build and install all of your dynamically loadable
735extensions. (The standard extensions supplied with Perl are handled
736automatically). You can turn off this namespace protection by adding
737-DNO_EMBED to your ccflags variable in config.sh. This is a one-time
738change. In the future, we certainly hope that most extensions won't
739need to be recompiled for use with a newer version of perl.
740
8e07c86e 741=head1 Coexistence with perl4
742
743You can safely install perl5 even if you want to keep perl4 around.
744
745By default, the perl5 libraries go into F</usr/local/lib/perl5/>, so
746they don't override the perl4 libraries in F</usr/local/lib/perl/>.
747
748In your /usr/local/bin directory, you should have a binary named
749F<perl4.036>. That will not be touched by the perl5 installation
750process. Most perl4 scripts should run just fine under perl5.
751However, if you have any scripts that require perl4, you can replace
752the C<#!> line at the top of them by C<#!/usr/local/bin/perl4.036>
edb1cbcb 753(or whatever the appropriate pathname is). See pod/perltrap.pod
754for possible problems running perl4 scripts under perl5.
8e07c86e 755
756=head1 DOCUMENTATION
757
758Read the manual entries before running perl. The main documentation is
759in the pod/ subdirectory and should have been installed during the
760build process. Type B<man perl> to get started. Alternatively, you
761can type B<perldoc perl> to use the supplied B<perldoc> script. This
762is sometimes useful for finding things in the library modules.
763
764=head1 AUTHOR
765
766Andy Dougherty <doughera@lafcol.lafayette.edu>, borrowing I<very> heavily
767from the original README by Larry Wall.
768
a5f75d66 769=head1 LAST MODIFIED
24b3df7f 770
eed2e782 77107 July 1996