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