This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl 5.002beta1h patch: Configure
[perl5.git] / INSTALL
CommitLineData
8e07c86e
AD
1=head1 NAME
2
3Install - Build and Installation guide for perl5.
4
5=head1 SYNOPSIS
6
7The basic steps to build and install perl5 are:
8
9 rm -f config.sh
10 sh Configure
11 make
12 make test
13 make install
14
15Each of these is explained in further detail below.
16
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
25f94b33 63 sh Configure -Dprefix=/opt/perl
4633a7c4
LW
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
25f94b33 266 sh Configure -des
8e07c86e
AD
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).
25f94b33 279 sh Configure -des
8e07c86e
AD
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
25f94b33
AD
293=item Running Configure Interactively
294
295If Configure runs into trouble, remember that you can always run
296Configure interactively so that you can check (and correct) its
297guesses.
298
299All the installation questions have been moved to the top, so you don't
300have to wait for them. Once you've handled them (and your C compiler &
301flags) you can type '&-d' at the next Configure prompt and Configure
302will use the defaults from then on.
303
304If you find yourself trying obscure command line incantations and
305config.over tricks, I recommend you run Configure interactively
306instead. You'll probably save yourself time in the long run.
307
8e07c86e
AD
308=item Hint files.
309
310The perl distribution includes a number of system-specific hints files
311in the hints/ directory. If one of them matches your system, Configure
312will offer to use that hint file.
313
314Several of the hint files contain additional important information.
315If you have any problems, it is a good idea to read the relevant hint
316file for further information. See F<hints/solaris_2.sh> for an
317extensive example.
318
319=item Changing Compilers
320
321If you change compilers or make other significant changes, you should
322probably I<not> re-use your old config.sh. Simply remove it or
323rename it, e.g. mv config.sh config.sh.old. Then rerun Configure
324with the options you want to use.
325
326This is a common source of problems. If you change from B<cc> to
327B<gcc>, you should almost always remove your old config.sh.
328
329=item Propagating your changes
330
331If you later make any changes to F<config.sh>, you should propagate
25f94b33 332them to all the .SH files by running B<sh Configure -S>.
8e07c86e
AD
333
334=item config.over
335
336You can also supply a shell script config.over to over-ride Configure's
337guesses. It will get loaded up at the very end, just before config.sh
338is created. You have to be careful with this, however, as Configure
339does no checking that your changes make sense.
340
341=item config.h
342
343Many of the system dependencies are contained in F<config.h>.
344F<Configure> builds F<config.h> by running the F<config_h.SH> script.
345The values for the variables are taken from F<config.sh>.
346
347If there are any problems, you can edit F<config.h> directly. Beware,
348though, that the next time you run B<Configure>, your changes will be
349lost.
350
351=item cflags
352
353If you have any additional changes to make to the C compiler command
354line, they can be made in F<cflags.SH>. For instance, to turn off the
355optimizer on F<toke.c>, find the line in the switch structure for
356F<toke.c> and put the command C<optimize='-g'> before the C<;;>. You
357can also edit F<cflags> directly, but beware that your changes will be
358lost the next time you run B<Configure>.
359
360To change the C flags for all the files, edit F<config.sh>
361and change either C<$ccflags> or C<$optimize>,
25f94b33 362and then re-run B<sh Configure -S ; make depend>.
8e07c86e
AD
363
364=item No sh.
365
366If you don't have sh, you'll have to copy the sample file config_H to
367config.h and edit the config.h to reflect your system's peculiarities.
368You'll probably also have to extensively modify the extension building
369mechanism.
370
371=back
372
373=head1 make depend
374
375This will look for all the includes.
376The output is stored in F<makefile>. The only difference between
377F<Makefile> and F<makefile> is the dependencies at the bottom of
378F<makefile>. If you have to make any changes, you should edit
379F<makefile>, not F<Makefile> since the Unix B<make> command reads
4633a7c4 380F<makefile> first.
8e07c86e
AD
381
382Configure will offer to do this step for you, so it isn't listed
383explicitly above.
384
385=head1 make
386
387This will attempt to make perl in the current directory.
388
389If you can't compile successfully, try some of the following ideas.
390
391=over 4
392
393=item *
394
395If you used a hint file, try reading the comments in the hint file
396for further tips and information.
397
398=item *
399
400If you can't compile successfully, try adding a C<-DCRIPPLED_CC> flag.
401(Just because you get no errors doesn't mean it compiled right!)
402This simplifies some complicated expressions for compilers that
403get indigestion easily. If that has no effect, try turning off
404optimization. If you have missing routines, you probably need to
405add some library or other, or you need to undefine some feature that
406Configure thought was there but is defective or incomplete.
407
408=item *
409
410Some compilers will not compile or optimize the larger files without
411some extra switches to use larger jump offsets or allocate larger
412internal tables. You can customize the switches for each file in
413F<cflags>. It's okay to insert rules for specific files into
414F<makefile> since a default rule only takes effect in the absence of a
415specific rule.
416
417=item *
418
419If you can successfully build F<miniperl>, but the process crashes
420during the building of extensions, you should run
421
422 make minitest
423
424to test your version of miniperl.
425
426=item *
427
428Some additional things that have been reported for either perl4 or perl5:
429
430Genix may need to use libc rather than libc_s, or #undef VARARGS.
431
432NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
433
434UTS may need one or more of B<-DCRIPPLED_CC>, B<-K> or B<-g>, and undef LSTAT.
435
436If you get syntax errors on '(', try -DCRIPPLED_CC.
437
438Machines with half-implemented dbm routines will need to #undef I_ODBM
439
440SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
441that includes libdbm.nfs (which includes dbmclose()) may be available.
442
443If you get duplicates upon linking for malloc et al, say -DHIDEMYMALLOC.
444
445If you get duplicate function definitions (a perl function has the
446same name as another function on your system) try -DEMBED.
447
448If you get varags problems with gcc, be sure that gcc is installed
449correctly. When using gcc, you should probably have i_stdarg='define'
450and i_varags='undef' in config.sh. The problem is usually solved
451by running fixincludes correctly.
452
453If you wish to use dynamic loading on SunOS or Solaris, and you
454have GNU as and GNU ld installed, you may need to add B<-B/bin/> to
455your $ccflags and $ldflags so that the system's versions of as
456and ld are used.
457
458If you run into dynamic loading problems, check your setting of
459the LD_LIBRARY_PATH environment variable. Perl should build
460fine with LD_LIBRARY_PATH unset, though that may depend on details
461of your local set-up.
462
463=back
464
465=head1 make test
466
467This will run the regression tests on the perl you just made. If it
468doesn't say "All tests successful" then something went wrong. See the
469file F<t/README> in the F<t> subdirectory. Note that you can't run it
470in background if this disables opening of /dev/tty. If B<make test>
471bombs out, just B<cd> to the F<t> directory and run B<TEST> by hand
472to see if it makes any difference.
473If individual tests bomb, you can run them by hand, e.g.,
474
475 ./perl op/groups.t
476
477=head1 INSTALLING PERL5
478
479=head1 make install
480
481This will put perl into the public directory you specified to
482B<Configure>; by default this is F</usr/local/bin>. It will also try
483to put the man pages in a reasonable place. It will not nroff the man
484page, however. You may need to be root to run B<make install>. If you
485are not root, you must own the directories in question and you should
486ignore any messages about chown not working.
487
488If you want to see exactly what will happen without installing
489anything, you can run
4633a7c4 490
8e07c86e
AD
491 ./perl installperl -n
492 ./perl installman -n
493
494B<make install> will install the following:
495
496 perl,
497 perl5.nnn where nnn is the current release number. This
498 will be a link to perl.
499 suidperl,
500 sperl5.nnn If you requested setuid emulation.
501 a2p awk-to-perl translator
502 cppstdin This is used by perl -P, if your cc -E can't
503 read from stdin.
504 c2ph, pstruct Scripts for handling C structures in header files.
505 s2p sed-to-perl translator
506 find2perl find-to-perl translator
507 h2xs Converts C .h header files to Perl extensions.
508 perldoc Tool to read perl's pod documentation.
509 pod2html, Converters from perl's pod documentation format
510 pod2latex, and to other useful formats.
511 pod2man
512
513 library files in $privlib and $archlib specified to
514 Configure, usually under /usr/local/lib/perl5/.
515 man pages in the location specified to Configure, usually
516 something like /usr/local/man/man1.
517 module in the location specified to Configure, usually
518 man pages under /usr/local/lib/perl5/man/man3.
519 pod/*.pod in $privlib/pod/.
520
4633a7c4
LW
521Installperl will also create the library directories $siteperl and
522$sitearch listed in config.sh. Usually, these are something like
523 /usr/local/lib/site_perl/
524 /usr/local/lib/site_perl/$archname
525where $archname is something like sun4-sunos. These directories
526will be used for installing extensions.
527
8e07c86e
AD
528Perl's *.h header files and the libperl.a library are also
529installed under $archlib so that any user may later build new
530extensions even if the Perl source is no longer available.
531
532The libperl.a library is only needed for building new
533extensions and linking them statically into a new perl executable.
534If you will not be doing that, then you may safely delete
535$archlib/libperl.a after perl is installed.
536
537make install may also offer to install perl in a "standard" location.
538
539Most of the documentation in the pod/ directory is also available
540in HTML and LaTeX format. Type
541
542 cd pod; make html; cd ..
543
544to generate the html versions, and
545
546 cd pod; make tex; cd ..
547
548to generate the LaTeX versions.
549
4633a7c4
LW
550=head1 Coexistence with earlier versions of perl5.
551
552You can safely install the current version of perl5 and still run
553scripts under the old binaries. Instead of starting your script with
554#!/usr/local/bin/perl, just start it with #!/usr/local/bin/perl5.001
555(or whatever version you want to run.)
556
557The architecture-dependent files are stored in a version-specific
558directory (such as F</usr/local/lib/perl5/sun4-sunos/5.002>) so that
559they are still accessible. I<Note:> perl5.000 and perl5.001 did not
560put their architecture-dependent libraries in a version-specific
561directory. They are simply in F</usr/local/lib/perl5/$archname>. If
562you will not be using 5.000 or 5.001, you may safely remove those
563files.
564
565The standard library files in F</usr/local/lib/perl5>
566should be useable by all versions of perl5.
567
568Most extensions will not need to be recompiled to use with a newer
569version of perl. If you do run into problems, and you want to continue
570to use the old version of perl along with your extension, simply move
571those extension files to the appropriate version directory, such as
572F</usr/local/lib/perl/archname/5.002>. Then perl5.002 will find your
573files in the 5.002 directory, and newer versions of perl will find your
574newer extension in the site_perl directory.
575
8e07c86e
AD
576=head1 Coexistence with perl4
577
578You can safely install perl5 even if you want to keep perl4 around.
579
580By default, the perl5 libraries go into F</usr/local/lib/perl5/>, so
581they don't override the perl4 libraries in F</usr/local/lib/perl/>.
582
583In your /usr/local/bin directory, you should have a binary named
584F<perl4.036>. That will not be touched by the perl5 installation
585process. Most perl4 scripts should run just fine under perl5.
586However, if you have any scripts that require perl4, you can replace
587the C<#!> line at the top of them by C<#!/usr/local/bin/perl4.036>
588(or whatever the appropriate pathname is).
589
590=head1 DOCUMENTATION
591
592Read the manual entries before running perl. The main documentation is
593in the pod/ subdirectory and should have been installed during the
594build process. Type B<man perl> to get started. Alternatively, you
595can type B<perldoc perl> to use the supplied B<perldoc> script. This
596is sometimes useful for finding things in the library modules.
597
598=head1 AUTHOR
599
600Andy Dougherty <doughera@lafcol.lafayette.edu>, borrowing I<very> heavily
601from the original README by Larry Wall.
602
60318 October 1995