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