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