This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
This is patch.2b1c to perl5.002beta1. This patch includes
[perl5.git] / INSTALL
CommitLineData
8e07c86e
AD
1=head1 NAME
2
3Install - Build and Installation guide for perl5.
4
5=head1 SYNOPSIS
6
7The basic steps to build and install perl5 are:
8
9 rm -f config.sh
10 sh Configure
11 make
12 make test
13 make install
14
15Each of these is explained in further detail below.
16
17=head1 BUILDING PERL5
18
19=head1 Start with a Fresh Distribution.
20
21The results of a Configure run are stored in the config.sh file. If
22you are upgrading from a previous version of perl, or if you change
23systems or compilers or make other significant changes, or if you are
24experiencing difficulties building perl, you should probably I<not>
25re-use your old config.sh. Simply remove it or rename it, e.g.
26
27 mv config.sh config.sh.old
4633a7c4 28
8e07c86e
AD
29Then run Configure.
30
31=head1 Run Configure.
32
33Configure will figure out various things about your system. Some
34things Configure will figure out for itself, other things it will ask
35you about. To accept the default, just press C<RETURN>. The default
36is almost always ok.
37
38After it runs, Configure will perform variable substitution on all the
39F<*.SH> files and offer to run B<make depend>.
40
41Configure supports a number of useful options. Run B<Configure -h>
42to get a listing. To compile with gcc, for example, you can run
43
44 sh Configure -Dcc=gcc
45
46This is the preferred way to specify gcc (or another alternative
47compiler) so that the hints files can set appropriate defaults.
48
4633a7c4
LW
49If you want to use your old config.sh but override some of the items
50with command line options, you need to use B<Configure -O>.
51
8e07c86e
AD
52If you are willing to accept all the defaults, and you want terse
53output, you can run
54
55 sh Configure -des
56
57By default, for most systems, perl will be installed in
58/usr/local/{bin, lib, man}. You can specify a different 'prefix' for
59the default installation directory, when Configure prompts you or by
60using the Configure command line option -Dprefix='/some/directory',
61e.g.
62
4633a7c4
LW
63 Configure -Dprefix=/opt/perl
64
65If your prefix contains the string "perl", then the directories
66are simplified. For example, if you use prefix=/opt/perl,
67then Configure will suggest /opt/perl/lib instead of
68/usr/local/lib/perl5/.
8e07c86e
AD
69
70By default, Configure will compile perl to use dynamic loading, if
71your system supports it. If you want to force perl to be compiled
72statically, you can either choose this when Configure prompts you or by
73using the Configure command line option -Uusedl.
74
75=head2 GNU-style configure
76
77If you prefer the GNU-style B<configure> command line interface, you can
78use the supplied B<configure> command, e.g.
79
80 CC=gcc ./configure
81
82The B<configure> script emulates several of the more common configure
83options. Try
84
85 ./configure --help
86
87for a listing.
88
89Cross compiling is currently not supported.
90
91=head2 Including locally-installed libraries
92
4633a7c4
LW
93Perl5 comes with interfaces to number of database extensions, including
94dbm, ndbm, gdbm, and Berkeley db. For each extension, if
95Configure can find the appropriate header files and libraries, it will
96automatically include that extension. The gdbm and db libraries
97are B<not> included with perl. See the library documentation for
98how to obtain the libraries.
8e07c86e
AD
99
100I<Note:> If your database header (.h) files are not in a
101directory normally searched by your C compiler, then you will need to
102include the appropriate B<-I/your/directory> option when prompted by
103Configure. If your database library (.a) files are not in a directory
104normally searched by your C compiler and linker, then you will need to
105include the appropriate B<-L/your/directory> option when prompted by
106Configure. See the examples below.
107
108=head2 Examples
109
110=over 4
111
112=item gdbm in /usr/local.
113
114Suppose you have gdbm and want Configure to find it and build the
115GDBM_File extension. This examples assumes you have F<gdbm.h>
116installed in F</usr/local/include/gdbm.h> and F<libgdbm.a> installed in
117F</usr/local/lib/libgdbm.a>. Configure should figure all the
118necessary steps out automatically.
119
120Specifically, when Configure prompts you for flags for
121your C compiler, you should include C<-I/usr/local/include>.
122
123When Configure prompts you for linker flags, you should include
124C<-L/usr/local/lib>.
125
126If you are using dynamic loading, then when Configure prompts you for
127linker flags for dynamic loading, you should again include
128C<-L/usr/local/lib>.
129
130Again, this should all happen automatically. If you want to accept the
131defaults for all the questions and have Configure print out only terse
132messages, then you can just run
133
134 sh Configure -des
135
136and Configure should include the GDBM_File extension automatically.
137
138This should actually work if you have gdbm installed in any of
139(/usr/local, /opt/local, /usr/gnu, /opt/gnu, /usr/GNU, or /opt/GNU).
140
141=item gdbm in /usr/you
142
143Suppose you have gdbm installed in some place other than /usr/local/,
144but you still want Configure to find it. To be specific, assume you
145have F</usr/you/include/gdbm.h> and F</usr/you/lib/libgdbm.a>. You
146still have to add B<-I/usr/you/include> to cc flags, but you have to take
147an extra step to help Configure find F<libgdbm.a>. Specifically, when
148Configure prompts you for library directories, you have to add
149F</usr/you/lib> to the list.
150
151It is possible to specify this from the command line too (all on one
152line):
153
154 sh Configure -des \
155 -Dlocincpth="/usr/you/include" \
156 -Dloclibpth="/usr/you/lib"
157
158C<locincpth> is a space-separated list of include directories to search.
159Configure will automatically add the appropriate B<-I> directives.
160
161C<loclibpth> is a space-separated list of library directories to search.
162Configure will automatically add the appropriate B<-L> directives. If
163you have some libraries under F</usr/local/> and others under
164F</usr/you>, then you have to include both, namely
165
166 sh Configure -des \
167 -Dlocincpth="/usr/you/include /usr/local/include" \
168 -Dloclibpth="/usr/you/lib /usr/local/lib"
169
170=back
171
4633a7c4
LW
172=head2 Installation Directories.
173
174The installation directories can all be changed by answering the
175appropriate questions in Configure. For convenience, all the
176installation questions are near the beginning of Configure.
177
178By default, Configure uses the following directories for
179library files (archname is a string like sun4-sunos, determined
180by Configure)
181
182 /usr/local/lib/perl5/archname/5.002
183 /usr/local/lib/perl5/
184 /usr/local/lib/site_perl/archname
185 /usr/local/lib/site_perl
186
187and the following directories for manual pages:
188
189 /usr/local/man/man1
190 /usr/local/lib/perl5/man/man3
191
192(Actually, Configure recognizes the SVR3-style
193/usr/local/man/l_man/man1 directories, if present, and uses those
194instead.) The module man pages are stuck in that strange spot so that
195they don't collide with other man pages stored in /usr/local/man/man3,
196and so that Perl's man pages don't hide system man pages. On some
197systems, B<man less> would end up calling up Perl's less.pm module man
198page, rather than the B<less> program.
199
200If you specify a prefix that contains the string "perl", then the
201directory structure is simplified. For example, if you Configure
202with -Dprefix=/opt/perl, then the defaults are
203
204 /opt/perl/lib/archname/5.002
205 /opt/perl/lib
206 /opt/perl/lib/site_perl/archname
207 /opt/perl/lib/site_perl
208
209 /opt/perl/man/man1
210 /opt/perl/man/man3
211
212The perl executable will search the libraries in the order given
213above.
214
215The directories site_perl and site_perl/archname are empty, but are
216intended to be used for installing local or site-wide extensions. Perl
217will automatically look in these directories. Previously, most sites
218just put their local extensions in with the standard distribution.
219
220In order to support using things like #!/usr/local/bin/perl5.002 after
221a later version is released, architecture-dependent libraries are
222stored in a version-specific directory, such as
223/usr/local/lib/perl5/archname/5.002/. In 5.000 and 5.001, these files
224were just stored in /usr/local/lib/perl5/archname/. If you will not be
225using 5.001 binaries, you can delete the standard extensions from the
226/usr/local/lib/perl5/archname/ directory. Locally-added extensions can
227be moved to the site_perl and site_perl/archname directories.
228
229Again, these are just the defaults, and can be changed as you run
230Configure.
231
8e07c86e
AD
232=head2 Changing the installation directory
233
234Configure distinguishes between the directory in which perl (and its
235associated files) should be installed and the directory in which it
236will eventually reside. For most sites, these two are the same; for
237sites that use AFS, this distinction is handled automatically.
238However, sites that use software such as B<depot> to manage software
239packages may also wish to install perl into a different directory and
240use that management software to move perl to its final destination.
241This section describes how to do this. Someday, Configure may support
242an option C<-Dinstallprefix=/foo> to simplify this.
243
244Suppose you want to install perl under the F</tmp/perl5> directory.
245You can edit F<config.sh> and change all the install* variables to
246point to F</tmp/perl5> instead of F</usr/local/wherever>. You could
247also set them all from the Configure command line. Or, you can
248automate this process by placing the following lines in a file
249F<config.over> B<before> you run Configure (replace /tmp/perl5 by a
250directory of your choice):
251
252 installprefix=/tmp/perl5
253 test -d $installprefix || mkdir $installprefix
254 test -d $installprefix/bin || mkdir $installprefix/bin
255 installarchlib=`echo $installarchlib | sed "s!$prefix!$installprefix!"`
256 installbin=`echo $installbin | sed "s!$prefix!$installprefix!"`
257 installman1dir=`echo $installman1dir | sed "s!$prefix!$installprefix!"`
258 installman3dir=`echo $installman3dir | sed "s!$prefix!$installprefix!"`
259 installprivlib=`echo $installprivlib | sed "s!$prefix!$installprefix!"`
260 installscript=`echo $installscript | sed "s!$prefix!$installprefix!"`
261 installsitelib=`echo $installsitelib | sed "s!$prefix!$installprefix!"`
4633a7c4 262 installsitearch=`echo $installsitearch | sed "s!$prefix!$installprefix!"`
8e07c86e
AD
263
264Then, you can Configure and install in the usual way:
265
266 sh ./Configure -des
267 make
268 make test
269 make install
270
271=head2 Creating an installable tar archive
272
273If you need to install perl on many identical systems, it is
274convenient to compile it once and create an archive that can be
275installed on multiple systems. Here's one way to do that:
276
277 # Set up config.over to install perl into a different directory,
278 # e.g. /tmp/perl5 (see previous part).
279 sh ./Configure -des
280 make
281 make test
282 make install
283 cd /tmp/perl5
284 tar cvf ../perl5-archive.tar .
285 # Then, on each machine where you want to install perl,
286 cd /usr/local # Or wherever you specified as $prefix
287 tar xvf perl5-archive.tar
288
289=head2 What if it doesn't work?
290
291=over 4
292
293=item Hint files.
294
295The perl distribution includes a number of system-specific hints files
296in the hints/ directory. If one of them matches your system, Configure
297will offer to use that hint file.
298
299Several of the hint files contain additional important information.
300If you have any problems, it is a good idea to read the relevant hint
301file for further information. See F<hints/solaris_2.sh> for an
302extensive example.
303
304=item Changing Compilers
305
306If you change compilers or make other significant changes, you should
307probably I<not> re-use your old config.sh. Simply remove it or
308rename it, e.g. mv config.sh config.sh.old. Then rerun Configure
309with the options you want to use.
310
311This is a common source of problems. If you change from B<cc> to
312B<gcc>, you should almost always remove your old config.sh.
313
314=item Propagating your changes
315
316If you later make any changes to F<config.sh>, you should propagate
317them to all the .SH files by running B<Configure -S>.
318
319=item config.over
320
321You can also supply a shell script config.over to over-ride Configure's
322guesses. It will get loaded up at the very end, just before config.sh
323is created. You have to be careful with this, however, as Configure
324does no checking that your changes make sense.
325
326=item config.h
327
328Many of the system dependencies are contained in F<config.h>.
329F<Configure> builds F<config.h> by running the F<config_h.SH> script.
330The values for the variables are taken from F<config.sh>.
331
332If there are any problems, you can edit F<config.h> directly. Beware,
333though, that the next time you run B<Configure>, your changes will be
334lost.
335
336=item cflags
337
338If you have any additional changes to make to the C compiler command
339line, they can be made in F<cflags.SH>. For instance, to turn off the
340optimizer on F<toke.c>, find the line in the switch structure for
341F<toke.c> and put the command C<optimize='-g'> before the C<;;>. You
342can also edit F<cflags> directly, but beware that your changes will be
343lost the next time you run B<Configure>.
344
345To change the C flags for all the files, edit F<config.sh>
346and change either C<$ccflags> or C<$optimize>,
347and then re-run B<Configure -S ; make depend>.
348
349=item No sh.
350
351If you don't have sh, you'll have to copy the sample file config_H to
352config.h and edit the config.h to reflect your system's peculiarities.
353You'll probably also have to extensively modify the extension building
354mechanism.
355
356=back
357
358=head1 make depend
359
360This will look for all the includes.
361The output is stored in F<makefile>. The only difference between
362F<Makefile> and F<makefile> is the dependencies at the bottom of
363F<makefile>. If you have to make any changes, you should edit
364F<makefile>, not F<Makefile> since the Unix B<make> command reads
4633a7c4 365F<makefile> first.
8e07c86e
AD
366
367Configure will offer to do this step for you, so it isn't listed
368explicitly above.
369
370=head1 make
371
372This will attempt to make perl in the current directory.
373
374If you can't compile successfully, try some of the following ideas.
375
376=over 4
377
378=item *
379
380If you used a hint file, try reading the comments in the hint file
381for further tips and information.
382
383=item *
384
385If you can't compile successfully, try adding a C<-DCRIPPLED_CC> flag.
386(Just because you get no errors doesn't mean it compiled right!)
387This simplifies some complicated expressions for compilers that
388get indigestion easily. If that has no effect, try turning off
389optimization. If you have missing routines, you probably need to
390add some library or other, or you need to undefine some feature that
391Configure thought was there but is defective or incomplete.
392
393=item *
394
395Some compilers will not compile or optimize the larger files without
396some extra switches to use larger jump offsets or allocate larger
397internal tables. You can customize the switches for each file in
398F<cflags>. It's okay to insert rules for specific files into
399F<makefile> since a default rule only takes effect in the absence of a
400specific rule.
401
402=item *
403
404If you can successfully build F<miniperl>, but the process crashes
405during the building of extensions, you should run
406
407 make minitest
408
409to test your version of miniperl.
410
411=item *
412
413Some additional things that have been reported for either perl4 or perl5:
414
415Genix may need to use libc rather than libc_s, or #undef VARARGS.
416
417NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
418
419UTS may need one or more of B<-DCRIPPLED_CC>, B<-K> or B<-g>, and undef LSTAT.
420
421If you get syntax errors on '(', try -DCRIPPLED_CC.
422
423Machines with half-implemented dbm routines will need to #undef I_ODBM
424
425SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
426that includes libdbm.nfs (which includes dbmclose()) may be available.
427
428If you get duplicates upon linking for malloc et al, say -DHIDEMYMALLOC.
429
430If you get duplicate function definitions (a perl function has the
431same name as another function on your system) try -DEMBED.
432
433If you get varags problems with gcc, be sure that gcc is installed
434correctly. When using gcc, you should probably have i_stdarg='define'
435and i_varags='undef' in config.sh. The problem is usually solved
436by running fixincludes correctly.
437
438If you wish to use dynamic loading on SunOS or Solaris, and you
439have GNU as and GNU ld installed, you may need to add B<-B/bin/> to
440your $ccflags and $ldflags so that the system's versions of as
441and ld are used.
442
443If you run into dynamic loading problems, check your setting of
444the LD_LIBRARY_PATH environment variable. Perl should build
445fine with LD_LIBRARY_PATH unset, though that may depend on details
446of your local set-up.
447
448=back
449
450=head1 make test
451
452This will run the regression tests on the perl you just made. If it
453doesn't say "All tests successful" then something went wrong. See the
454file F<t/README> in the F<t> subdirectory. Note that you can't run it
455in background if this disables opening of /dev/tty. If B<make test>
456bombs out, just B<cd> to the F<t> directory and run B<TEST> by hand
457to see if it makes any difference.
458If individual tests bomb, you can run them by hand, e.g.,
459
460 ./perl op/groups.t
461
462=head1 INSTALLING PERL5
463
464=head1 make install
465
466This will put perl into the public directory you specified to
467B<Configure>; by default this is F</usr/local/bin>. It will also try
468to put the man pages in a reasonable place. It will not nroff the man
469page, however. You may need to be root to run B<make install>. If you
470are not root, you must own the directories in question and you should
471ignore any messages about chown not working.
472
473If you want to see exactly what will happen without installing
474anything, you can run
4633a7c4 475
8e07c86e
AD
476 ./perl installperl -n
477 ./perl installman -n
478
479B<make install> will install the following:
480
481 perl,
482 perl5.nnn where nnn is the current release number. This
483 will be a link to perl.
484 suidperl,
485 sperl5.nnn If you requested setuid emulation.
486 a2p awk-to-perl translator
487 cppstdin This is used by perl -P, if your cc -E can't
488 read from stdin.
489 c2ph, pstruct Scripts for handling C structures in header files.
490 s2p sed-to-perl translator
491 find2perl find-to-perl translator
492 h2xs Converts C .h header files to Perl extensions.
493 perldoc Tool to read perl's pod documentation.
494 pod2html, Converters from perl's pod documentation format
495 pod2latex, and to other useful formats.
496 pod2man
497
498 library files in $privlib and $archlib specified to
499 Configure, usually under /usr/local/lib/perl5/.
500 man pages in the location specified to Configure, usually
501 something like /usr/local/man/man1.
502 module in the location specified to Configure, usually
503 man pages under /usr/local/lib/perl5/man/man3.
504 pod/*.pod in $privlib/pod/.
505
4633a7c4
LW
506Installperl will also create the library directories $siteperl and
507$sitearch listed in config.sh. Usually, these are something like
508 /usr/local/lib/site_perl/
509 /usr/local/lib/site_perl/$archname
510where $archname is something like sun4-sunos. These directories
511will be used for installing extensions.
512
8e07c86e
AD
513Perl's *.h header files and the libperl.a library are also
514installed under $archlib so that any user may later build new
515extensions even if the Perl source is no longer available.
516
517The libperl.a library is only needed for building new
518extensions and linking them statically into a new perl executable.
519If you will not be doing that, then you may safely delete
520$archlib/libperl.a after perl is installed.
521
522make install may also offer to install perl in a "standard" location.
523
524Most of the documentation in the pod/ directory is also available
525in HTML and LaTeX format. Type
526
527 cd pod; make html; cd ..
528
529to generate the html versions, and
530
531 cd pod; make tex; cd ..
532
533to generate the LaTeX versions.
534
4633a7c4
LW
535=head1 Coexistence with earlier versions of perl5.
536
537You can safely install the current version of perl5 and still run
538scripts under the old binaries. Instead of starting your script with
539#!/usr/local/bin/perl, just start it with #!/usr/local/bin/perl5.001
540(or whatever version you want to run.)
541
542The architecture-dependent files are stored in a version-specific
543directory (such as F</usr/local/lib/perl5/sun4-sunos/5.002>) so that
544they are still accessible. I<Note:> perl5.000 and perl5.001 did not
545put their architecture-dependent libraries in a version-specific
546directory. They are simply in F</usr/local/lib/perl5/$archname>. If
547you will not be using 5.000 or 5.001, you may safely remove those
548files.
549
550The standard library files in F</usr/local/lib/perl5>
551should be useable by all versions of perl5.
552
553Most extensions will not need to be recompiled to use with a newer
554version of perl. If you do run into problems, and you want to continue
555to use the old version of perl along with your extension, simply move
556those extension files to the appropriate version directory, such as
557F</usr/local/lib/perl/archname/5.002>. Then perl5.002 will find your
558files in the 5.002 directory, and newer versions of perl will find your
559newer extension in the site_perl directory.
560
8e07c86e
AD
561=head1 Coexistence with perl4
562
563You can safely install perl5 even if you want to keep perl4 around.
564
565By default, the perl5 libraries go into F</usr/local/lib/perl5/>, so
566they don't override the perl4 libraries in F</usr/local/lib/perl/>.
567
568In your /usr/local/bin directory, you should have a binary named
569F<perl4.036>. That will not be touched by the perl5 installation
570process. Most perl4 scripts should run just fine under perl5.
571However, if you have any scripts that require perl4, you can replace
572the C<#!> line at the top of them by C<#!/usr/local/bin/perl4.036>
573(or whatever the appropriate pathname is).
574
575=head1 DOCUMENTATION
576
577Read the manual entries before running perl. The main documentation is
578in the pod/ subdirectory and should have been installed during the
579build process. Type B<man perl> to get started. Alternatively, you
580can type B<perldoc perl> to use the supplied B<perldoc> script. This
581is sometimes useful for finding things in the library modules.
582
583=head1 AUTHOR
584
585Andy Dougherty <doughera@lafcol.lafayette.edu>, borrowing I<very> heavily
586from the original README by Larry Wall.
587
58818 October 1995