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