Patch to README.solaris

Message-ID: <3F09728D.1070408@sun.com>

p4raw-id: //depot/perl@20053

1 files changed, 174 insertions, 108 deletions

diff --git a/README.solaris b/README.solaris
index 69d05053f7..47338b6ef9 100644
--- a/README.solaris
+++ b/README.solaris
@@ -20,14 +20,54 @@ 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
 that installation unless you really know what you are doing.  If you
-remove the perl supplied with the OS, there is a good chance you will
-render some bits of your system inoperable.  If you wish to install a
-newer version of perl, install it under a different prefix from
-/usr/perl5.  Common prefixes to use are /usr/local and /opt/perl.
+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,
+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 /usr/perl5/bin/perl.
+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.
+
+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
+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
+in the older version, again due to compatibility/stability concerns.
+As a consequence if you upgrade Solaris, you will have to
+rebuild/reinstall any additional CPAN modules that you installed for
+the previous Solaris version.  See the CPAN manpage under 'autobundle'
+for a quick way of doing this.
+
+As an interim measure, you may either change the #! line of your
+scripts to specifically refer to the old perl version, e.g. on
+Solaris 9 use #!/usr/perl5/5.00503/bin/perl to use the perl version
+that was the default for Solaris 8, or if you have a large number of
+scripts it may be more convenient to make the old version of perl the
+default on your system.  You can do this by changing the appropriate
+symlinks under /usr/perl5 as follows (example for Solaris 9):
+
+ # cd /usr/perl5
+ # rm bin man pod
+ # ln -s ./5.00503/bin
+ # ln -s ./5.00503/man
+ # ln -s ./5.00503/lib/pod
+ # rm /usr/bin/perl
+ # ln -s ../perl5/5.00503/bin/perl /usr/bin/perl
+
+In both cases this should only be considered to be a temporary
+measure - you should upgrade to the later version of perl as soon as
+is practicable.
+
+Note also that the perl command-line utilities (e.g. perldoc) and any
+that are added by modules that you install will be under
+/usr/perl5/bin, so that directory should be added to your PATH.
 
 =head2 Solaris Version Numbers.
 
@@ -35,11 +75,13 @@ For consistency with common usage, perl's Configure script performs
 some minor manipulations on the operating system name and version
 number as reported by uname.  Here's a partial translation table:
 
-             Sun:                      perl's Configure:
-    uname    uname -r   Name           osname     osvers
-    SunOS    4.1.3     Solaris 1.1     sunos      4.1.3
-    SunOS    5.6       Solaris 2.6     solaris    2.6
-    SunOS    5.8       Solaris 8       solaris    2.8
+          Sun:                      perl's Configure:
+ uname    uname -r   Name           osname     osvers
+ SunOS    4.1.3     Solaris 1.1     sunos      4.1.3
+ SunOS    5.6       Solaris 2.6     solaris    2.6
+ SunOS    5.8       Solaris 8       solaris    2.8
+ SunOS    5.9       Solaris 9       solaris    2.9
+ SunOS    5.10      Solaris 10      solaris    2.10
 
 The complete table can be found in the Sun Managers' FAQ
 L<ftp://ftp.cs.toronto.edu/pub/jdd/sunmanagers/faq> under
@@ -62,8 +104,9 @@ L<ftp://ftp.cs.toronto.edu/pub/jdd/sunmanagers/faq>
 
 =item Precompiled Binaries
 
-Precompiled binaries, links to many sites, and much, much more is
-available at L<http://www.sunfreeware.com/>.
+Precompiled binaries, links to many sites, and much, much more are
+available at L<http://www.sunfreeware.com/> and
+L<http://www.blastwave.org/>.
 
 =item Solaris Documentation
 
@@ -111,7 +154,7 @@ SUNWsprox, SUNWtoox, SUNWlmsx, SUNWlmx, SUNWlibCx
 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
 
-	grep /my/missing/file /var/sadm/install/contents
+ $ grep /my/missing/file /var/sadm/install/contents
 
 This will display a line like this:
 
@@ -133,12 +176,12 @@ If you use Sun's C compiler, make sure the correct directory
 =head3 GCC
 
 If you use gcc, make sure your installation is recent and complete.
-Perl versions since 5.6.0 build fine with gcc > 2.8.1 on Solaris >=
+perl versions since 5.6.0 build fine with gcc > 2.8.1 on Solaris >=
 2.6.
 
 You must Configure perl with
 
-	sh Configure -Dcc=gcc
+ $ sh Configure -Dcc=gcc
 
 If you don't, you may experience strange build errors.
 
@@ -151,8 +194,17 @@ Solaris than you are running, then you will need to rebuild gcc for
 your new version of Solaris.
 
 You can get a precompiled version of gcc from
-L<http://www.sunfreeware.com/>. Make sure you pick up the package for
-your Solaris release.
+L<http://www.sunfreeware.com/> or L<http://www.blastwave.org/>. Make
+sure you pick up the package for your Solaris release.
+
+If you wish to use gcc to build add-on modules for use with the perl
+shipped with Solaris, you should use the Solaris::PerlGcc module
+which is available from CPAN.  The perl shipped with Solaris
+is configured and built with the Sun compilers, and the compiler
+configuration information stored in Config.pm is therefore only
+relevant to the Sun compilers.  The Solaris:PerlGcc module contains a
+replacement Config.pm that is correct for gcc - see the module for
+details.
 
 =head3 GNU as and GNU ld
 
@@ -169,11 +221,11 @@ are apparently new enough.  Older versions may have trouble with
 dynamic loading.
 
 If you wish to use GNU ld, then you need to pass it the -Wl,-E flag.
-The hints/solaris_2.sh file tries to do this automatically by executing
-the following commands:
+The hints/solaris_2.sh file tries to do this automatically by setting
+the following Configure variables:
 
-	ccdlflags="$ccdlflags -Wl,-E"
-	lddlflags="$lddlflags -Wl,-E -G"
+ ccdlflags="$ccdlflags -Wl,-E"
+ lddlflags="$lddlflags -Wl,-E -G"
 
 However, over the years, changes in gcc, GNU ld, and Solaris ld have made
 it difficult to automatically detect which ld ultimately gets called.
@@ -186,12 +238,12 @@ 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
 that is with
 
-	sh Configure -Dcc='gcc -B/usr/ccs/bin/'
+ $ sh Configure -Dcc='gcc -B/usr/ccs/bin/'
 
 Note that the trailing slash is required.  This will result in some
 harmless warnings as Configure is run:
 
-	gcc: file path prefix `/usr/ccs/bin/' never used
+ gcc: file path prefix `/usr/ccs/bin/' never used
 
 These messages may safely be ignored.
 (Note that for a SunOS4 system, you must use -B/bin/ instead.)
@@ -200,13 +252,19 @@ Alternatively, you can use the GCC_EXEC_PREFIX environment variable to
 ensure that Sun's as and ld are used.  Consult your gcc documentation
 for further information on the -B option and the GCC_EXEC_PREFIX variable.
 
-=head3 GNU make
+=head3 Sun and GNU make
 
-Sun's make works fine for building perl.
-If you wish to use GNU make anyway, be sure that the set-group-id bit is not
-set.  If it is, then arrange your PATH so that /usr/ccs/bin/make is
-before GNU make or else have the system administrator disable the
-set-group-id bit on GNU make.
+The make under /usr/ccs/bin works fine for building perl.  If you
+have the Sun C compilers, you will also have a parallel version of
+make (dmake).  This works fine to build perl, but can sometimes cause
+problems when running 'make test' due to underspecified dependencies
+between the different test harness files.  The same problem can also
+affect the building of some add-on modules, so in those cases either
+specify '-m serial' on the dmake command line, or use
+/usr/ccs/bin/make instead.  If you wish to use GNU make, be sure that
+the set-group-id bit is not set.  If it is, then arrange your PATH so
+that /usr/ccs/bin/make is before GNU make or else have the system
+administrator disable the set-group-id bit on GNU make.
 
 =head3 Avoid libucb.
 
@@ -217,7 +275,7 @@ Normally this is not a problem since the solaris hints file prevents
 Configure from even looking in /usr/ucblib for libraries, and also
 explicitly omits -lucb.
 
-=head2 Environment for Compiling Perl on Solaris
+=head2 Environment for Compiling perl on Solaris
 
 =head3 PATH
 
@@ -238,7 +296,7 @@ the directory with that library (e.g. /usr/local/lib).
 
 If you get an error message
 
-	dlopen: stub interception failed
+ dlopen: stub interception failed
 
 it is probably because your LD_LIBRARY_PATH environment variable
 includes a directory which is a symlink to /usr/lib (such as /lib).
@@ -254,7 +312,7 @@ See the INSTALL file for general information regarding Configure.
 Only Solaris-specific issues are discussed here.  Usually, the
 defaults should be fine.
 
-=head2 64-bit Issues with Perl on Solaris.
+=head2 64-bit perl on Solaris.
 
 See the INSTALL file for general information regarding 64-bit compiles.
 In general, the defaults should be fine for most people.
@@ -277,18 +335,19 @@ The discriminating feature of a LP64 bit app is its ability to utilise a
 that supports both 64-bit integers (long long) and largefiles (> 2GB),
 and this is the default for perl-5.6.0.
 
-For a more complete explanation of 64-bit issues, see the Solaris 64-bit
-Developer's Guide at L<http://docs.sun.com:80/ab2/coll.45.13/SOL64TRANS/>
+For a more complete explanation of 64-bit issues, see the
+"Solaris 64-bit Developer's Guide" at L<http://docs.sun.com/>
 
 You can detect the OS mode using "isainfo -v", e.g.
 
-      fubar$ isainfo -v   # Ultra 30 in 64 bit mode
-      64-bit sparcv9 applications
-      32-bit sparc applications
+ $ isainfo -v   # Ultra 30 in 64 bit mode
+ 64-bit sparcv9 applications
+ 32-bit sparc applications
 
-By default, perl will be compiled as a 32-bit application.  Unless you
-want to allocate more than ~ 4GB of memory inside Perl, you probably
-don't need Perl to be a 64-bit app.
+By default, perl will be compiled as a 32-bit application.  Unless
+you want to allocate more than ~ 4GB of memory inside perl, or unless
+you need more than 255 open file descriptors, you probably don't need
+perl to be a 64-bit app.
 
 =head3 Large File Support
 
@@ -300,34 +359,34 @@ by default.)
 First is the "transitional compilation environment", described in
 lfcompile64(5).  According to the man page,
 
-    The transitional compilation  environment  exports  all  the
-    explicit 64-bit functions (xxx64()) and types in addition to
-    all the regular functions (xxx()) and types. Both xxx()  and
-    xxx64()  functions  are  available to the program source.  A
-    32-bit application must use the xxx64() functions in  order
-    to  access  large  files.  See the lf64(5) manual page for a
-    complete listing of the 64-bit transitional interfaces.
+ The transitional compilation  environment  exports  all  the
+ explicit 64-bit functions (xxx64()) and types in addition to
+ all the regular functions (xxx()) and types. Both xxx()  and
+ xxx64()  functions  are  available to the program source.  A
+ 32-bit application must use the xxx64() functions in  order
+ to  access  large  files.  See the lf64(5) manual page for a
+ complete listing of the 64-bit transitional interfaces.
 
 The transitional compilation environment is obtained with the
 following compiler and linker flags:
 
-    getconf LFS64_CFLAGS        -D_LARGEFILE64_SOURCE
-    getconf LFS64_LDFLAG        # nothing special needed
-    getconf LFS64_LIBS          # nothing special needed
+ getconf LFS64_CFLAGS        -D_LARGEFILE64_SOURCE
+ getconf LFS64_LDFLAG        # nothing special needed
+ getconf LFS64_LIBS          # nothing special needed
 
 Second is the "large file compilation environment", described in
 lfcompile(5).  According to the man page,
 
-    Each interface named xxx() that needs to access 64-bit entities
-    to  access  large  files maps to a xxx64() call in the
-    resulting binary. All relevant data types are defined to  be
-    of correct size (for example, off_t has a typedef definition
-    for a 64-bit entity).
+ Each interface named xxx() that needs to access 64-bit entities
+ to  access  large  files maps to a xxx64() call in the
+ resulting binary. All relevant data types are defined to  be
+ of correct size (for example, off_t has a typedef definition
+ for a 64-bit entity).
 
-    An application compiled in this environment is able  to  use
-    the  xxx()  source interfaces to access both large and small
-    files, rather than having to explicitly utilize the  transitional
-    xxx64()  interface  calls to access large files.
+ An application compiled in this environment is able  to  use
+ the  xxx()  source interfaces to access both large and small
+ files, rather than having to explicitly utilize the  transitional
+ xxx64()  interface  calls to access large files.
 
 Two exceptions are fseek() and ftell().  32-bit applications should
 use fseeko(3C) and ftello(3C).  These will get automatically mapped
@@ -335,31 +394,31 @@ to fseeko64() and ftello64().
 
 The large file compilation environment is obtained with
 
-	getconf LFS_CFLAGS      -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64
-	getconf LFS_LDFLAGS     # nothing special needed
-	getconf LFS_LIBS        # nothing special needed
+ getconf LFS_CFLAGS      -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64
+ getconf LFS_LDFLAGS     # nothing special needed
+ getconf LFS_LIBS        # nothing special needed
 
 By default, perl uses the large file compilation environment and
 relies on Solaris to do the underlying mapping of interfaces.
 
-=head3 Building an LP64 Perl
+=head3 Building an LP64 perl
 
 To compile a 64-bit application on an UltraSparc with a recent Sun Compiler,
 you need to use the flag "-xarch=v9".  getconf(1) will tell you this, e.g.
 
-      fubar$ getconf -a | grep v9
-      XBS5_LP64_OFF64_CFLAGS:         -xarch=v9
-      XBS5_LP64_OFF64_LDFLAGS:        -xarch=v9
-      XBS5_LP64_OFF64_LINTFLAGS:      -xarch=v9
-      XBS5_LPBIG_OFFBIG_CFLAGS:       -xarch=v9
-      XBS5_LPBIG_OFFBIG_LDFLAGS:      -xarch=v9
-      XBS5_LPBIG_OFFBIG_LINTFLAGS:    -xarch=v9
-      _XBS5_LP64_OFF64_CFLAGS:        -xarch=v9
-      _XBS5_LP64_OFF64_LDFLAGS:       -xarch=v9
-      _XBS5_LP64_OFF64_LINTFLAGS:     -xarch=v9
-      _XBS5_LPBIG_OFFBIG_CFLAGS:      -xarch=v9
-      _XBS5_LPBIG_OFFBIG_LDFLAGS:     -xarch=v9
-      _XBS5_LPBIG_OFFBIG_LINTFLAGS:   -xarch=v9
+ $ getconf -a | grep v9
+ XBS5_LP64_OFF64_CFLAGS:         -xarch=v9
+ XBS5_LP64_OFF64_LDFLAGS:        -xarch=v9
+ XBS5_LP64_OFF64_LINTFLAGS:      -xarch=v9
+ XBS5_LPBIG_OFFBIG_CFLAGS:       -xarch=v9
+ XBS5_LPBIG_OFFBIG_LDFLAGS:      -xarch=v9
+ XBS5_LPBIG_OFFBIG_LINTFLAGS:    -xarch=v9
+ _XBS5_LP64_OFF64_CFLAGS:        -xarch=v9
+ _XBS5_LP64_OFF64_LDFLAGS:       -xarch=v9
+ _XBS5_LP64_OFF64_LINTFLAGS:     -xarch=v9
+ _XBS5_LPBIG_OFFBIG_CFLAGS:      -xarch=v9
+ _XBS5_LPBIG_OFFBIG_LDFLAGS:     -xarch=v9
+ _XBS5_LPBIG_OFFBIG_LINTFLAGS:   -xarch=v9
 
 This flag is supported in Sun WorkShop Compilers 5.0 and onwards
 (now marketed under the name Forte) when used on Solaris 7 or later on
@@ -369,38 +428,36 @@ If you are using gcc, you would need to use -mcpu=v9 -m64 instead.  This
 option is not yet supported as of gcc 2.95.2; from install/SPECIFIC
 in that release:
 
-GCC version 2.95 is not able to compile code correctly for sparc64
-targets. Users of the Linux kernel, at least, can use the sparc32
-program to start up a new shell invocation with an environment that
-causes configure to recognize (via uname -a) the system as sparc-*-*
-instead.
+ GCC version 2.95 is not able to compile code correctly for sparc64
+ targets. Users of the Linux kernel, at least, can use the sparc32
+ program to start up a new shell invocation with an environment that
+ causes configure to recognize (via uname -a) the system as sparc-*-*
+ instead.
 
 All this should be handled automatically by the hints file, if
 requested.
 
 =head3 Long Doubles.
 
-As of 5.6.0, long doubles are not working.
+As of 5.8.1, long doubles are working if you use the Sun compilers
+(needed for additional math routines not included in libm).
 
-=head2 Threads in Perl on Solaris.
+=head2 Threads in perl on Solaris.
 
 It is possible to build a threaded version of perl on Solaris.  The entire
 perl thread implementation is still experimental, however, so beware.
-Perl uses the sched_yield(3RT) function.  In versions of Solaris up
-to 2.6, that function is in -lposix4.  Starting with Solaris 7, it is
-in -lrt.  The hints file should handle adding this automatically.
 
-=head2 Malloc Issues with Perl on Solaris.
+=head2 Malloc Issues with perl on Solaris.
 
-Starting from Perl 5.7.1 Perl uses the Solaris malloc, since the perl
+Starting from perl 5.7.1 perl uses the Solaris malloc, since the perl
 malloc breaks when dealing with more than 2GB of memory, and the Solaris
 malloc also seems to be faster.
 
 If you for some reason (such as binary backward compatibility) really
-need to use perl's malloc, you can rebuild Perl from the sources
+need to use perl's malloc, you can rebuild perl from the sources
 and Configure the build with 
 
-	sh Configure -Dusemymalloc
+ $ sh Configure -Dusemymalloc
 
 You should not use perl's malloc if you are building with gcc.  There
 are reports of core dumps, especially in the PDL module.  The problem
@@ -465,25 +522,33 @@ See L<perlhpux/"nss_delete core dump from op/pwent or op/grent">.
 =head1 PREBUILT BINARIES OF PERL FOR SOLARIS.
 
 You can pick up prebuilt binaries for Solaris from
-L<http://www.sunfreeware.com/>, ActiveState L<http://www.activestate.com/>,
-and L<http://www.perl.com/> under the Binaries list at the top of the page.
-There are probably other sources as well.  Please note that these sites
-are under the control of their respective owners, not the perl developers.
+L<http://www.sunfreeware.com/>, L<http://www.blastwave.org>,
+ActiveState L<http://www.activestate.com/>, and
+L<http://www.perl.com/> under the Binaries list at the top of the
+page.  There are probably other sources as well.  Please note that
+these sites are under the control of their respective owners, not the
+perl developers.
 
 =head1 RUNTIME ISSUES FOR PERL ON SOLARIS.
 
 =head2 Limits on Numbers of Open Files on Solaris.
 
-The stdio(3C) manpage notes that only 255 files may be opened using
-fopen(), and only file descriptors 0 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.
+The stdio(3C) manpage notes that for LP32 applications, only 255
+files may be opened using fopen(), and only file descriptors 0
+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
+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.
 
 =head1 SOLARIS-SPECIFIC MODULES.
 
-See the modules under the Solaris:: namespace on CPAN,
-L<http://www.cpan.org/modules/by-module/Solaris/>.
+See the modules under the Solaris:: and Sun::Solaris namespaces on CPAN,
+see L<http://www.cpan.org/modules/by-module/Solaris/> and
+L<http://www.cpan.org/modules/by-module/Sun/>.
 
 =head1 SOLARIS-SPECIFIC PROBLEMS WITH MODULES.
 
@@ -515,12 +580,13 @@ BSD::Resource versions starting from 1.09 have a workaround for the problem.
 
 =head2 Net::SSLeay on Solaris
 
-Net::SSLeay requires a /dev/urandom to be present. This device is not
-part of Solaris. You can either get the package SUNWski (packaged with
-several Sun 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
+Net::SSLeay requires a /dev/urandom to be present. This device is
+available from Solaris 9 onwards.  For earlier Solaris versions you
+can either get the package SUNWski (packaged with several Sun
+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.
 
 It may be possible to use the Entropy Gathering Daemon (written in