view release on metacpan or  search on metacpan

INSTALL  view on Meta::CPAN

linking the "perl library" libperl.a with perlmain.o, your static
extensions, and various extra libraries, such as -lm.

On systems that support dynamic loading, it may be possible to
replace libperl.a with a shared libperl.so.  If you anticipate building
several different perl binaries (e.g. by embedding libperl into
different programs, or by using the optional compiler extension), then
you might wish to build a shared libperl.so so that all your binaries
can share the same library.

The disadvantages are that there may be a significant performance
penalty associated with the shared libperl.so, and that the overall
mechanism is still rather fragile with respect to different versions
and upgrades.

In terms of performance, on my test system (Solaris 2.5_x86) the perl
test suite took roughly 15% longer to run with the shared libperl.so.
Your system and typical applications may well give quite different
results.

The default name for the shared library is typically something like
libperl.so.5.8.8 (for Perl 5.8.8), or libperl.so.588, or simply
libperl.so.  Configure tries to guess a sensible naming convention
based on your C library name.  Since the library gets installed in a
version-specific architecture-dependent directory, the exact name
isn't very important anyway, as long as your linker is happy.

You can elect to build a shared libperl by

	sh Configure -Duseshrplib

To build a shared libperl, the environment variable controlling shared
library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
Darwin, LD_LIBRARY_PATH/SHLIB_PATH
for HP-UX, LIBPATH for AIX and z/OS, PATH for Cygwin) must be set up to include
the Perl build directory because that's where the shared libperl will
be created.  Configure arranges makefile to have the correct shared
library search settings.  You can find the name of the environment
variable Perl thinks works in your your system by

	grep ldlibpthname config.sh

However, there are some special cases where manually setting the
shared library path might be required.  For example, if you want to run
something like the following with the newly-built but not-yet-installed
./perl:

        ./perl -I. -MTestInit t/misc/failing_test.t

or

        ./perl -Ilib ~/my_mission_critical_test

then you need to set up the shared library path explicitly.
You can do this with

   LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH

for Bourne-style shells, or

   setenv LD_LIBRARY_PATH `pwd`

for Csh-style shells.  (This procedure may also be needed if for some
unexpected reason Configure fails to set up makefile correctly.) (And
again, it may be something other than LD_LIBRARY_PATH for you, see above.)

You can often recognize failures to build/use a shared libperl from error
messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
for example:

    18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so

There is also a potential problem with the shared perl library if you
want to have more than one "flavor" of the same version of perl (e.g.
with and without -DDEBUGGING).  For example, suppose you build and
install a standard Perl 5.10.0 with a shared library.  Then, suppose you
try to build Perl 5.10.0 with -DDEBUGGING enabled, but everything else
the same, including all the installation directories.  How can you
ensure that your newly built perl will link with your newly built
libperl.so.8 rather with the installed libperl.so.8?  The answer is
that you might not be able to.  The installation directory is encoded
in the perl binary with the LD_RUN_PATH environment variable (or
equivalent ld command-line option).  On Solaris, you can override that
with LD_LIBRARY_PATH; on Linux, you can only override at runtime via
LD_PRELOAD, specifying the exact filename you wish to be used; and on
Digital Unix, you can override LD_LIBRARY_PATH by setting the
_RLD_ROOT environment variable to point to the perl build directory.

In other words, it is generally not a good idea to try to build a perl
with a shared library if $archlib/CORE/$libperl already exists from a
previous build.

A good workaround is to specify a different directory for the
architecture-dependent library for your -DDEBUGGING version of perl.
You can do this by changing all the *archlib* variables in config.sh to
point to your new architecture-dependent library.

=head3 External glob

Before File::Glob entered core in 5.6.0 globbing was implemented by shelling
out. If the environmental variable PERL_EXTERNAL_GLOB is defined and if the
F<csh> shell is available, perl will still do this the old way.

=head2 Installation Directories

The installation directories can all be changed by answering the
appropriate questions in Configure.  For convenience, all the installation
questions are near the beginning of Configure.  Do not include trailing
slashes on directory names.  At any point during the Configure process,
you can answer a question with  &-d  and Configure will use the defaults
from then on.  Alternatively, you can

	grep '^install' config.sh

after Configure has run to verify the installation paths.

The defaults are intended to be reasonable and sensible for most
people building from sources.  Those who build and distribute binary
distributions or who export perl to a range of systems will probably
need to alter them.  If you are content to just accept the defaults,
you can safely skip the next section.

INSTALL  view on Meta::CPAN

    -Dhostgenerate=/path/to/second/build/dir/generate_uudmap

Much less commonly, if you are cross-compiling from an ASCII host to an
EBCDIC target, or vise versa, you'll have to pass C<-Uhostgenerate> to
Configure, to signify that you want to build a generate_uudmap binary
that, during make, will be run on the target system.

=head1 make test

This will run the regression tests on the perl you just made.  If
'make test' doesn't say "All tests successful" then something went
wrong.

Note that you can't run the tests in background if this disables
opening of /dev/tty. You can use 'make test-notty' in that case but
a few tty tests will be skipped.

=head2 What if make test doesn't work?

If make test bombs out, just cd to the t directory and run ./TEST
by hand to see if it makes any difference.

One way to get more detailed information about failed tests and
individual subtests is to run the harness from the t directory:

	cd t ; ./perl harness <list of tests>

(this assumes that most basic tests succeed, since harness uses
complicated constructs). If no list of tests is provided, harness
will run all tests.

If individual tests fail, you can often run them by hand (from the main
perl directory), e.g.,

	./perl -I. -MTestInit t/op/groups.t

You should also read the individual tests to see if there are any helpful
comments that apply to your system.  You may also need to setup your
shared library path if you get errors like:

	/sbin/loader: Fatal Error: cannot map libperl.so

The file t/README in the t subdirectory contains more information about
running and modifying tests.

See L</"Building a shared Perl library"> earlier in this document.

=over 4

=item locale

Note:  One possible reason for errors is that some external programs
may be broken due to the combination of your environment and the way
'make test' exercises them.  For example, this may happen if you have
one or more of these environment variables set:  LC_ALL LC_CTYPE
LC_COLLATE LANG.  In some versions of UNIX, the non-English locales
are known to cause programs to exhibit mysterious errors.

If you have any of the above environment variables set, please try

	setenv LC_ALL C

(for C shell) or

	LC_ALL=C;export LC_ALL

for Bourne or Korn shell) from the command line and then retry
make test.  If the tests then succeed, you may have a broken program that
is confusing the testing.  Please run the troublesome test by hand as
shown above and see whether you can locate the program.  Look for
things like:  exec, `backquoted command`, system, open("|...") or
open("...|").  All these mean that Perl is trying to run some
external program.

=item Timing problems

Several tests in the test suite check timing functions, such as
sleep(), and see if they return in a reasonable amount of time.
If your system is quite busy and doesn't respond quickly enough,
these tests might fail.  If possible, try running the tests again
with the system under a lighter load.  These timing-sensitive
and load-sensitive tests include F<t/op/alarm.t>,
F<dist/Time-HiRes/t/alarm.t>, F<dist/Time-HiRes/t/clock.t>,
F<dist/Time-HiRes/t/itimer.t>, F<dist/Time-HiRes/t/usleep.t>,
F<dist/threads-shared/t/waithires.t>,
F<dist/threads-shared/t/stress.t>, F<lib/Benchmark.t>,
F<lib/Memoize/t/expmod_t.t>, and F<lib/Memoize/t/speed.t>.

You might also experience some failures in F<t/op/stat.t> if you build
perl on an NFS filesystem, if the remote clock and the system clock are
different.

=item Out of memory

On some systems, particularly those with smaller amounts of RAM, some
of the tests in t/op/pat.t may fail with an "Out of memory" message.
For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
test 85 will fail if run under either t/TEST or t/harness.

Try stopping other jobs on the system and then running the test by itself:

	./perl -I. -MTestInit t/op/pat.t

to see if you have any better luck.  If your perl still fails this
test, it does not necessarily mean you have a broken perl.  This test
tries to exercise the regular expression subsystem quite thoroughly,
and may well be far more demanding than your normal usage.

=item libgcc_s.so.1: cannot open shared object file

This message has been reported on gcc-3.2.3 and earlier installed with
a non-standard prefix.  Setting the LD_LIBRARY_PATH environment variable
(or equivalent) to include gcc's lib/ directory with the libgcc_s.so.1
shared library should fix the problem.

=item Failures from lib/File/Temp/t/security saying "system possibly insecure"

First, such warnings are not necessarily serious or indicative of a
real security threat.  That being said, they bear investigating.

Note that each of the tests is run twice.  The first time is in the