This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
regcomp.c: Remove memory leak
[perl5.git] / README.solaris
index 202c8ff..7b11079 100644 (file)
@@ -4,7 +4,7 @@ specifically designed to be readable as is.
 
 =head1 NAME
 
-README.solaris - Perl version 5 on Solaris systems
+perlsolaris - Perl version 5 on Solaris systems
 
 =head1 DESCRIPTION
 
@@ -18,7 +18,7 @@ For the most part, everything should just work.
 Starting with Solaris 8, perl5.00503 (or higher) is supplied with the
 operating system, so you might not even need to build a newer version
 of perl at all.  The Sun-supplied version is installed in /usr/perl5
-with /usr/bin/perl pointing to /usr/perl5/bin/perl.  Do not disturb
+with F</usr/bin/perl> pointing to F</usr/perl5/bin/perl>.  Do not disturb
 that installation unless you really know what you are doing.  If you
 remove the perl supplied with the OS, you will render some bits of
 your system inoperable.  If you wish to install a newer version of perl,
@@ -26,16 +26,20 @@ install it under a different prefix from /usr/perl5.  Common prefixes
 to use are /usr/local and /opt/perl.
 
 You may wish to put your version of perl in the PATH of all users by
-changing the link /usr/bin/perl.  This is OK, as all perl scripts
-shipped with Solaris use an explicit path.  Solaris ships with a
-range of Solaris-specific modules.  If you choose to install your own
-version of perl you will find the source of many of these modules is
-available on CPAN under the Sun::Solaris:: namespace.
+changing the link F</usr/bin/perl>.  This is probably OK, as most perl
+scripts shipped with Solaris use an explicit path.  (There are a few
+exceptions, such as F</usr/bin/rpm2cpio> and F</etc/rcm/scripts/README>, but
+these are also sufficiently generic that the actual version of perl
+probably doesn't matter too much.)
+
+Solaris ships with a range of Solaris-specific modules.  If you choose
+to install your own version of perl you will find the source of many of
+these modules is available on CPAN under the Sun::Solaris:: namespace.
 
 Solaris may include two versions of perl, e.g. Solaris 9 includes
 both 5.005_03 and 5.6.1.  This is to provide stability across Solaris
 releases, in cases where a later perl version has incompatibilities
-with the version included in the preceeding Solaris release.  The
+with the version included in the preceding Solaris release.  The
 default perl version will always be the most recent, and in general
 the old version will only be retained for one Solaris release.  Note
 also that the default perl will NOT be configured to search for modules
@@ -139,18 +143,25 @@ shipped with SunOS4 will not do.
 Several tools needed to build perl are located in /usr/ccs/bin/:  ar,
 as, ld, and make.  Make sure that /usr/ccs/bin/ is in your PATH.
 
-You need to make sure the following packages are installed
-(this info is extracted from the Solaris FAQ):
+
+On all the released versions of Solaris (8, 9 and 10) you need to make sure the following packages are installed (this info is extracted from the Solaris FAQ):
 
 for tools (sccs, lex, yacc, make, nm, truss, ld, as): SUNWbtool,
 SUNWsprot, SUNWtoo
 
 for libraries & headers: SUNWhea, SUNWarc, SUNWlibm, SUNWlibms, SUNWdfbh,
-SUNWcg6h, SUNWxwinc, SUNWolinc
+SUNWcg6h, SUNWxwinc
+
+Additionally, on Solaris 8 and 9 you also need:
 
 for 64 bit development: SUNWarcx, SUNWbtoox, SUNWdplx, SUNWscpux,
 SUNWsprox, SUNWtoox, SUNWlmsx, SUNWlmx, SUNWlibCx
 
+And only on Solaris 8 you also need:
+
+for libraries & headers: SUNWolinc
+
+
 If you are in doubt which package contains a file you are missing,
 try to find an installation that has that file. Then do a
 
@@ -209,7 +220,7 @@ details.
 =head3 GNU as and GNU ld
 
 The following information applies to gcc version 2.  Volunteers to
-update it as appropropriate for gcc version 3 would be appreciated.
+update it as appropriately for gcc version 3 would be appreciated.
 
 The versions of as and ld supplied with Solaris work fine for building
 perl.  There is normally no need to install the GNU versions to
@@ -233,16 +244,6 @@ You may have to manually edit config.sh and add the -Wl,-E flags
 yourself, or else run Configure interactively and add the flags at the
 appropriate prompts.
 
-In SunOS 4.x you most probably want to use the SunOS ld, /usr/bin/ld,
-since the more recent versions of GNU ld (like 2.13) do not seem to
-work for building Perl anymore.  When linking the extensions, the
-GNU ld gets very unhappy and spews a lot of errors like this
-
-  ... relocation truncated to fit: BASE13 ...
-
-and dies.  Therefore the SunOS 4.1 hints file explicitly sets the
-ld to be /usr/bin/ld.
-
 If your gcc is configured to use GNU as and ld but you want to use the
 Solaris ones instead to build perl, then you'll need to add
 -B/usr/ccs/bin/ to the gcc command line.  One convenient way to do
@@ -483,20 +484,20 @@ malloc. [XXX further investigation is needed here.]
 
 If you have problems with dynamic loading using gcc on SunOS or
 Solaris, and you are using GNU as and GNU ld, see the section
-L<"GNU as and GNU ld"> above.
+L</"GNU as and GNU ld"> above.
 
 =item ld.so.1: ./perl: fatal: relocation error:
 
 If you get this message on SunOS or Solaris, and you're using gcc,
 it's probably the GNU as or GNU ld problem in the previous item
-L<"GNU as and GNU ld">.
+L</"GNU as and GNU ld">.
 
 =item dlopen: stub interception failed
 
 The primary cause of the 'dlopen: stub interception failed' message is
 that the LD_LIBRARY_PATH environment variable includes a directory
 which is a symlink to /usr/lib (such as /lib).  See
-L<"LD_LIBRARY_PATH"> above.
+L</"LD_LIBRARY_PATH"> above.
 
 =item #error "No DATAMODEL_NATIVE specified"
 
@@ -520,7 +521,7 @@ directory.
 
 =head2 op/stat.t test 4 in Solaris
 
-op/stat.t test 4 may fail if you are on a tmpfs of some sort.
+F<op/stat.t> test 4 may fail if you are on a tmpfs of some sort.
 Building in /tmp sometimes shows this behavior.  The
 test suite detects if you are building in /tmp, but it may not be able
 to catch all tmpfs situations.
@@ -529,6 +530,20 @@ to catch all tmpfs situations.
 
 See L<perlhpux/"nss_delete core dump from op/pwent or op/grent">.
 
+=head1 CROSS-COMPILATION
+
+Nothing too unusual here.  You can easily do this if you have a 
+cross-compiler available;  A usual Configure invocation when targetting a
+Solaris x86 looks something like this:
+
+    sh ./Configure -des -Dusecrosscompile \
+        -Dcc=i386-pc-solaris2.11-gcc      \
+        -Dsysroot=$SYSROOT                \
+        -Alddlflags=" -Wl,-z,notext"      \
+        -Dtargethost=... # The usual cross-compilation options
+
+The lddlflags addition is the only abnormal bit.
+
 =head1 PREBUILT BINARIES OF PERL FOR SOLARIS.
 
 You can pick up prebuilt binaries for Solaris from
@@ -549,7 +564,7 @@ through 255 can be used in a stream.  Since perl calls open() and
 then fdopen(3C) with the resulting file descriptor, perl is limited
 to 255 simultaneous open files, even if sysopen() is used.  If this
 proves to be an insurmountable problem, you can compile perl as a
-LP64 application, see L<Building an LP64 perl> for details.  Note
+LP64 application, see L</Building an LP64 perl> for details.  Note
 also that the default resource limit for open file descriptors on
 Solaris is 255, so you will have to modify your ulimit or rctl
 (Solaris 9 onwards) appropriately.
@@ -597,19 +612,102 @@ software products, for example the Sun WebServer, which is part of
 the Solaris Server Intranet Extension, or the Sun Directory Services,
 part of Solaris for ISPs) or download the ANDIrand package from
 L<http://www.cosy.sbg.ac.at/~andi/>. If you use SUNWski, make a
-symbolic link /dev/urandom pointing to /dev/random.
+symbolic link /dev/urandom pointing to /dev/random.  For more details,
+see Document ID27606 entitled "Differing /dev/random support requirements
+within Solaris[TM] Operating Environments", available at
+L<http://sunsolve.sun.com> .
 
 It may be possible to use the Entropy Gathering Daemon (written in
 Perl!), available from L<http://www.lothar.com/tech/crypto/>.
 
+=head1 SunOS 4.x
+
+In SunOS 4.x you most probably want to use the SunOS ld, /usr/bin/ld,
+since the more recent versions of GNU ld (like 2.13) do not seem to
+work for building Perl anymore.  When linking the extensions, the
+GNU ld gets very unhappy and spews a lot of errors like this
+
+  ... relocation truncated to fit: BASE13 ...
+
+and dies.  Therefore the SunOS 4.1 hints file explicitly sets the
+ld to be F</usr/bin/ld>.
+
+As of Perl 5.8.1 the dynamic loading of libraries (DynaLoader, XSLoader)
+also seems to have become broken in in SunOS 4.x.  Therefore the default
+is to build Perl statically.
+
+Running the test suite in SunOS 4.1 is a bit tricky since the
+F<dist/Tie-File/t/09_gen_rs.t> test hangs (subtest #51, FWIW) for some
+unknown reason.  Just stop the test and kill that particular Perl
+process.
+
+There are various other failures, that as of SunOS 4.1.4 and gcc 3.2.2
+look a lot like gcc bugs.  Many of the failures happen in the Encode
+tests, where for example when the test expects "0" you get "&#48;"
+which should after a little squinting look very odd indeed.
+Another example is earlier in F<t/run/fresh_perl> where chr(0xff) is
+expected but the test fails because the result is chr(0xff).  Exactly.
+
+This is the "make test" result from the said combination:
+
+  Failed 27 test scripts out of 745, 96.38% okay.
+
+Running the C<harness> is painful because of the many failing
+Unicode-related tests will output megabytes of failure messages,
+but if one patiently waits, one gets these results:
+
+ Failed Test                     Stat Wstat Total Fail  Failed  List of Failed
+ -----------------------------------------------------------------------------
+ ...
+ ../ext/Encode/t/at-cn.t            4  1024    29    4  13.79%  14-17
+ ../ext/Encode/t/at-tw.t           10  2560    17   10  58.82%  2 4 6 8 10 12
+                                                                14-17
+ ../ext/Encode/t/enc_data.t        29  7424    ??   ??       %  ??
+ ../ext/Encode/t/enc_eucjp.t       29  7424    ??   ??       %  ??
+ ../ext/Encode/t/enc_module.t      29  7424    ??   ??       %  ??
+ ../ext/Encode/t/encoding.t        29  7424    ??   ??       %  ??
+ ../ext/Encode/t/grow.t            12  3072    24   12  50.00%  2 4 6 8 10 12 14
+                                                                16 18 20 22 24
+  Failed Test                     Stat Wstat Total Fail  Failed  List of Failed
+ ------------------------------------------------------------------------------
+ ../ext/Encode/t/guess.t          255 65280    29   40 137.93%  10-29
+ ../ext/Encode/t/jperl.t           29  7424    15   30 200.00%  1-15
+ ../ext/Encode/t/mime-header.t      2   512    10    2  20.00%  2-3
+ ../ext/Encode/t/perlio.t          22  5632    38   22  57.89%  1-4 9-16 19-20
+                                                                23-24 27-32
+ ../ext/List/Util/t/shuffle.t       0   139    ??   ??       %  ??
+ ../ext/PerlIO/t/encoding.t                    14    1   7.14%  11
+ ../ext/PerlIO/t/fallback.t                     9    2  22.22%  3 5
+ ../ext/Socket/t/socketpair.t       0     2    45   70 155.56%  11-45
+ ../lib/CPAN/t/vcmp.t                          30    1   3.33%  25
+ ../lib/Tie/File/t/09_gen_rs.t      0    15    ??   ??       %  ??
+ ../lib/Unicode/Collate/t/test.t              199   30  15.08%  7 26-27 71-75
+                                                                81-88 95 101
+                                                                103-104 106 108-
+                                                                109 122 124 161
+                                                                169-172
+ ../lib/sort.t                      0   139   119   26  21.85%  107-119
+ op/alarm.t                                     4    1  25.00%  4
+ op/utfhash.t                                  97    1   1.03%  31
+ run/fresh_perl.t                              91    1   1.10%  32
+ uni/tr_7jis.t                                 ??   ??       %  ??
+ uni/tr_eucjp.t                    29  7424     6   12 200.00%  1-6
+ uni/tr_sjis.t                     29  7424     6   12 200.00%  1-6
+ 56 tests and 467 subtests skipped.
+ Failed 27/811 test scripts, 96.67% okay. 1383/75399 subtests failed,
+   98.17% okay.
+
+The alarm() test failure is caused by system() apparently blocking
+alarm().  That is probably a libc bug, and given that SunOS 4.x
+has been end-of-lifed years ago, don't hold your breath for a fix.
+In addition to that, don't try anything too Unicode-y, especially
+with Encode, and you should be fine in SunOS 4.x.
+
 =head1 AUTHOR
 
 The original was written by Andy Dougherty F<doughera@lafayette.edu>
 drawing heavily on advice from Alan Burlison, Nick Ing-Simmons, Tim Bunce,
 and many other Solaris users over the years.
 
-Please report any errors, updates, or suggestions to F<perlbug@perl.org>.
-
-=head1 LAST MODIFIED
-
-$Id: README.solaris,v 1.4 2000/11/11 20:29:58 doughera Exp $
+Please report any errors, updates, or suggestions to
+L<https://github.com/Perl/perl5/issues>.