Each of these is explained in further detail below.
For information on non-Unix systems, see the section on
-L<"Porting Information"> below.
+L<"Porting information"> below.
=head1 DESCRIPTION
page, rather than the B<less> program.
If you specify a prefix that contains the string "perl", then the
-directory structure is simplified. For example, if you Configure
-with -Dprefix=/opt/perl, then the defaults are
+directory structure is simplified. For example, if you Configure with
+-Dprefix=/opt/perl, then the defaults are
/opt/perl/lib/archname/5.004
/opt/perl/lib
packages may also wish to install perl into a different directory and
use that management software to move perl to its final destination.
This section describes how to do this. Someday, Configure may support
-an option C<-Dinstallprefix=/foo> to simplify this.
+an option -Dinstallprefix=/foo to simplify this.
Suppose you want to install perl under the F</tmp/perl5> directory.
You can edit F<config.sh> and change all the install* variables to
that you have sfio, then sfio will be the default suggested by
Configure.
+I<Note:> On some systems, sfio's B<iffe> configuration script fails
+to detect that you have an C<atexit> function (or equivalent).
+Apparently, this is a problem at least for some versions of Linux
+and SunOS 4.
+
+You can test if you have this problem by trying the following shell
+script. (You may have to add some extra cflags and libraries. A
+portable version of this may eventually make its way into Configure.)
+
+ #!/bin/sh
+ cat > try.c <<'EOCP'
+ #include <stdio.h>
+ main() { printf("42\n"); }
+ EOCP
+ cc -o try try.c -lsfio
+ val=`./try`
+ if test X$val = X42; then
+ echo "Your sfio looks ok"
+ else
+ echo "Your sfio has the exit problem."
+ fi
+
+If you have this problem, the fix is to go back to your sfio sources
+and correct iffe's guess about atexit (or whatever is appropriate for
+your platform.)
+
+There also might be a more recent release of Sfio that fixes your
+problem.
+
=item 2.
Normal stdio IO, but with all IO going through calls to the PerlIO
variables in config.sh, namely archlib, archlib_exp, and
installarchlib, to point to your new architecture-dependent library.
+=head2 Malloc Issues
+
+Perl relies heavily on malloc(3) to grow data structures as needed, so
+perl's performance can be noticeably affected by the performance of
+the malloc function on your system.
+
+The perl source is shipped with a version of malloc that is very fast
+but somewhat wasteful of space. On the other hand, your system's
+malloc() function is probably a bit slower but also a bit more frugal.
+
+For many uses, speed is probably the most important consideration, so
+the default behavior (for most systems) is to use the malloc supplied
+with perl. However, if you will be running very large applications
+(e.g. Tk or PDL) or if your system already has an excellent malloc, or
+if you are experiencing difficulties with extensions that use
+third-party libraries that call malloc, then you might wish to use
+your system's malloc. (Or, you might wish to explore the experimental
+malloc flags discussed below.)
+
+To build without perl's malloc, you can use the Configure command
+
+ sh Configure -Uusemymalloc
+
+or you can answer 'n' at the appropriate interactive Configure prompt.
+
+=head2 Malloc Performance Flags
+
+If you are using Perl's malloc, you may add one or
+more of the following items to your C<cflags> config.sh variable
+to change its behavior in potentially useful ways. You can find out
+more about these flags by reading the F<malloc.c> source.
+In a future version of perl, these might be enabled by default.
+
+=over 4
+
+=item -DDEBUGGING_MSTATS
+
+If C<DEBUGGING_MSTATS> is defined, you can extract malloc
+statistics from the Perl interpreter. The overhead this imposes is not
+large (perl just twiddles integers at malloc/free/sbrk time). When you
+run perl with the environment variable C<PERL_DEBUG_MSTATS> set to
+either 1 or 2, the interpreter will dump statistics to stderr at exit
+time and (with a value of 2) after compilation. If you install the
+Devel::Peek module you can get the statistics whenever you like by
+invoking its mstat() function.
+
+=item -DEMERGENCY_SBRK
+
+If C<EMERGENCY_SBRK> is defined, running out of memory need not be a
+fatal error: a memory pool can allocated by assigning to the special
+variable C<$^M>. See L<perlvar> for more details.
+
+=item -DPACK_MALLOC
+
+If C<PACK_MALLOC> is defined, malloc.c uses a slightly different
+algorithm for small allocations (up to 64 bytes long). Such small
+allocations are quite common in typical Perl scripts.
+
+The expected memory savings (with 8-byte alignment in C<alignbytes>) is
+about 20% for typical Perl usage. The expected slowdown due to the
+additional malloc overhead is in fractions of a percent. (It is hard
+to measure because of the effect of the saved memory on speed).
+
+=item -DTWO_POT_OPTIMIZE
+
+If C<TWO_POT_OPTIMIZE> is defined, malloc.c uses a slightly different
+algorithm for large allocations that are close to a power of two
+(starting with 16K). Such allocations are typical for big hashes and
+special-purpose scripts, especially image processing. If you will be
+manipulating very large blocks with sizes close to powers of two, it
+might be wise to define this macro.
+
+The expected saving of memory is 0-100% (100% in applications which
+require most memory in such 2**n chunks). The expected slowdown is
+negligible.
+
+=back
+
+=head2 Building a debugging perl
+
+You can run perl scripts under the perl debugger at any time with
+B<perl -d>. If, however, you want to debug perl itself,
+you probably want to do
+
+ sh Configure -Doptimize='-g'
+
+This will do two things: First, it will force compilation to use
+B<cc -g> so that you can use your system's debugger on the executable.
+Second, it will add a C<-DDEBUGGING> to your ccflags variable in
+F<config.sh> so that you can use B<perl -D> to access perl's internal
+state.
+
+If you are using a shared libperl, see the warnings about multiple
+versions of perl under L<Building a shared libperl.so Perl library>.
+
=head2 Other Compiler Flags
For most users, all of the Configure defaults are fine. However,
you can change a number of factors in the way perl is built
-by adding appropriate -D directives to your ccflags variable in
+by adding appropriate B<-D> directives to your ccflags variable in
config.sh.
For example, you can replace the rand() and srand() functions in the
=item Porting information
-Specific information for the OS/2, Plan9, VMS and Win32 ports are in the
+Specific information for the OS/2, Plan9, VMS and Win32 ports is in the
corresponding subdirectories. Additional information, including
a glossary of all those config.sh variables, is in the Porting
subdirectory.
=item *
-If you get duplicates upon linking for malloc et al,
-add -DHIDEMYMALLOC to your ccflags variable in config.sh.
+If you get duplicates upon linking for malloc et al, add -DHIDEMYMALLOC
+or -DEMBEDMYMALLOC to your ccflags variable in config.sh.
=item varargs
SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
that includes libdbm.nfs (which includes dbmclose()) may be available.
-=item Warning (will try anyway): No library found for -lposix
+=item Note (probably harmless): No library found for -lsomething
If you see such a message during the building of an extension, but
the extension passes its tests anyway (see L<"make test"> below),
systems; few systems will need all the possible libraries listed.
For example, a system may have -lcposix or -lposix, but it's
unlikely to have both, so most users will see warnings for the one
-they don't have. The message 'will try anyway' is intended to
-reassure you that the process is continuing.
+they don't have. The phrase 'probably harmless' is intended to
+reassure you that nothing unusual is happening, and the build
+process is continuing.
On the other hand, if you are building GDBM_File and you get the
message
- Warning (will try anyway): No library found for -lgdbm
+ Note (probably harmless): No library found for -lgdbm
then it's likely you're going to run into trouble somewhere along
the line, since it's hard to see how you can use the GDBM_File
NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
-UTS may need one or more of B<-DCRIPPLED_CC>, B<-K> or B<-g>, and undef LSTAT.
+UTS may need one or more of -DCRIPPLED_CC, B<-K> or B<-g>, and undef LSTAT.
If you get syntax errors on '(', try -DCRIPPLED_CC.
=head1 LAST MODIFIED
-18 February 1997
+$Id: INSTALL,v 1.8 1997/03/21 16:21:53 doughera Released $
projects / p5sagit/p5-mst-13.2.git / blobdiff