README.solaris

Message-ID: <Pine.SOL.4.10.10011101217100.28341-100000@maxwell.phys.lafayette.edu>

p4raw-id: //depot/perl@7639

1 files changed, 475 insertions, 0 deletions

diff --git a/README.solaris b/README.solaris
new file mode 100644
index 0000000000..eccf9055db
--- /dev/null
+++ b/README.solaris
@@ -0,0 +1,475 @@
+If you read this file _as_is_, just ignore the funny characters you
+see.  It is written in the POD format (see pod/perlpod.pod) which is
+specifically designed to be readable as is.
+
+=head1 NAME
+
+README.solaris - Perl version 5 on Solaris systems
+
+=head1 DESCRIPTION
+
+This document describes various features of Sun's Solaris operating system
+that will affect how Perl version 5 (hereafter just perl) is
+compiled and/or runs.  Some issues relating to the older SunOS 4.x are
+also discussed, though they may be out of date.
+
+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 a link to /usr/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.
+
+=head2 Solaris Version Numbers.
+
+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     SunOS 4.1.3     sunos      4.1.3
+    SunOS    5.6       Solaris 2.6     solaris    2.6
+    SunOS    5.8       Solaris 8       solaris    2.8
+
+=head1 RESOURCES
+
+There are many, many source for Solaris information.  A few of the
+important ones for perl:
+
+=over 4
+
+=item Solaris FAQ
+
+The Solaris FAQ is available at
+L<http://www.science.uva.nl/pub/solaris/solaris2.html>.
+
+=item Precompiled Binaries
+
+Precompiled binaries, links to many sites, and much, much more is
+available at L<http://www.sunfreeware.com>.
+
+=item Solaris Documentation
+
+All Solaris documentation is available on-line at L<http://docs.sun.com>.
+
+=back
+
+=head1 SETTING UP
+
+=head2 File Extraction Problems.
+
+Be sure to use a tar program compiled under Solaris (not SunOS 4.x)
+to extract the perl-5.x.x.tar.gz file.  Do not use GNU tar compiled
+for SunOS4 on Solaris.  (GNU tar compiled for Solaris should be fine.)
+When you run SunOS4 binaries on Solaris, the run-time system magically
+alters pathnames matching m#lib/locale# so that when tar tries to create
+lib/locale.pm, a file named lib/oldlocale.pm gets created instead.
+If you ignore this advice and use a a SunOS4-compiled tar anyway, you
+must find the incorrectly renamed file and move it back to lib/locale.pm.
+
+=head2 Compiler and Related Tools.
+
+You must use an ANSI C compiler to build perl.  Perl can be compiled
+with either Sun's add-on C compiler or with gcc.  The C compiler that
+shipped with SunOS4 will not do.
+
+=head3 Include /usr/ccs/bin/ in your PATH.
+
+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):
+
+for tools (sccs, lex, yacc, make, nm, truss, ld, as): SUNWbtool,
+SUNWsprot, SUNWtoo
+
+for libraries & headers: SUNWhea, SUNWarc, SUNWlibm, SUNWlibms, SUNWdfbh,
+SUNWcg6h, SUNWxwinc, SUNWolinc
+
+for 64 bit development: SUNWarcx, SUNWbtoox, SUNWdplx, SUNWscpux,
+SUNWsprox, SUNWtoox, SUNWlmsx, SUNWlmx, SUNWlibCx
+
+=head3 Avoid /usr/ucb/cc.
+
+You don't need to have /usr/ucb/ in your PATH to build perl.  If you
+want /usr/ucb/ in your PATH anyway, make sure that /usr/ucb/cc is NOT
+in your PATH before the real C compiler.
+
+=head3 Sun's C Compiler
+
+If you use Sun's C compiler, make sure the correct directory
+(usually /opt/SUNWspro/bin/) is in your PATH before /usr/ucb/.
+
+=head3 GCC
+
+If you use gcc, make sure your installation is recent and
+complete.  As a point of reference, perl-5.6.0 built fine with
+gcc-2.8.1 on both Solaris 2.6 and Solaris 8.  You'll be able to
+Configure perl with
+
+	sh Configure -Dcc=gcc
+
+If you have updated your Solaris version, you may also have to update
+your GCC.  For example, if you are running Solaris 2.6 and your gcc is
+installed under /usr/local, check in /usr/local/lib/gcc-lib and make
+sure you have the appropriate directory sparc-sun-solaris2.6/.  If gcc's
+directory is for a different version of 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/>.
+
+=head3 GNU as and GNU ld
+
+The versions of as and ld supplied with Solaris work fine for building
+perl.  There is normally no need to install the GNU versions.
+
+If you decide to ignore this advice and use the GNU versions anyway,
+then be sure that they are relatively recent.  Versions newer than 2.7
+are apparently new enough.  Older versions may have trouble with
+dynamic loading.
+
+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
+that is with
+
+	sh Configure -Dcc='gcc -B/usr/ccs/bin/'
+
+Note that the trailing slash is required.  This will result in some
+harmless error messages as Configure is run:
+
+	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.)
+
+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
+
+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.
+
+=head3 Avoid libucb.
+
+Solaris provides some BSD-compatibility functions in /usr/ucblib/libucb.a.
+Perl will not build and run correctly if linked against -lucb since it
+contains routines that are incompatible with the standard Solaris libc.
+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
+
+=head3 PATH
+
+Make sure your PATH includes the compiler (/opt/SUNWspro/bin/ if you're
+using Sun's compiler) as well as /usr/ccs/bin/ to pick up the other
+development tools (such as make, ar, as, and ld).  Make sure your path
+either doesn't include /usr/ucb or that it includes it after the
+compiler and compiler tools and other standard Solaris directories.
+You definitely don't want /usr/ucb/cc.
+
+=head3 LD_LIBRARY_PATH
+
+If you have the LD_LIBRARY_PATH environment variable set, be sure that
+it does NOT include /lib or /usr/lib.  If you will be building
+extensions that call third-party shared libraries (e.g. Berkeley DB)
+then make sure that your LD_LIBRARY_PATH environment variable includes
+the directory with that library (e.g. /usr/local/lib).
+
+If you get an error message
+
+	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).
+The reason this causes a problem is quite subtle.  The file
+libdl.so.1.0 actually *only* contains functions which generate 'stub
+interception failed' errors!  The runtime linker intercepts links to
+"/usr/lib/libdl.so.1.0" and links in internal implementations of those
+functions instead.  [Thanks to Tim Bunce for this explanation.]
+
+=head1 RUN CONFIGURE.
+
+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.
+
+See the INSTALL file for general information regarding 64-bit compiles.
+In general, the defaults should be fine for most people.
+
+By default, perl-5.6.0 (or later) is compiled as a 32-bit application
+with largefile and long-long support.
+
+=head3 General 32-bit vs. 64-bit issues.
+
+Solaris 2.7 and above will run in either 32 bit or 64 bit mode, via a reboot.
+You can build 64 bit apps whilst running 32 bit mode and vice-versa.
+32 bit apps will run under Solaris running in either 32 or 64 bit mode.
+64 bit apps require Solaris to be running 64 bit mode
+
+Existing 32 bit apps are properly known as LP32, i.e. Longs and
+Pointers are 32 bit.  64-bit apps are more properly known as LP64.
+The discriminating feature of a LP64 bit app is its ability to utilise a
+64-bit address space.  It is perfectly possible to have a LP32 bit app
+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 http://docs.sun.com:80/ab2/coll.45.13/SOL64TRANS/
+
+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
+
+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.
+
+=head3 Large File Suppprt
+
+For Solaris 2.6 and onwards, there are two different ways for 32-bit
+applications to manipulate large files (files whose size is > 2Gbyte).
+(A 64-bit application automatically has largefile support built in
+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 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
+
+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).
+
+    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
+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
+
+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
+
+To compile a 64-bit application 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
+
+This flag is supported in Sun WorkShop Compilers 5.0 and onwards when
+used on Solaris 2.7 onwards.
+
+If you are using gcc, you need to use -mcpu=v9 -m64 instead.  This
+option is not supported in the installation of gcc-2.8.1 that I have
+at hand, but is supported in more recent versions.  [XXX -- any
+precise citations?]
+
+All this should be handled automatically by the hints file, if
+requested.
+
+If you do want to be able to allocate more than 4Gb memory inside
+perl, then you should use the Solaris malloc, since the perl
+malloc breaks when dealing with more than 2Gb of memory.  You can do
+this with
+
+	sh Configure -Uusemymalloc
+
+=head3 Long Doubles.
+
+As of 5.6.0, long doubles are not working.
+
+=head2 Threads.
+
+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.
+
+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
+appears to go away under -DDEBUGGING, so it has been difficult to
+track down.  Sun's compiler appears to be ok with or without perl's
+malloc. [XXX further investigation is needed here.]
+
+You should also not use perl's malloc if you are building perl as
+an LP64 application, since perl's malloc has trouble allocating more
+than 2Gb of memory.
+
+You can avoid perl's malloc by Configuring with
+
+	sh Configure -Uusemymalloc
+
+=head1 MAKE PROBLEMS.
+
+=over 4
+
+=item Dynamic Loading Problems With GNU as and GNU ld
+
+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.
+
+=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">.
+
+=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.
+
+=item #error "No DATAMODEL_NATIVE specified"
+
+This is a common error when trying to build perl on Solaris 2.6 with a
+gcc installation from Solaris 2.5 or 2.5.1.  The Solaris header files
+changed, so you need to update your gcc installation.  You can either
+rerun the fixincludes script from gcc or take the opportunity to
+update your gcc installation.
+
+=item sh: ar: not found
+
+This is a message from your shell telling you that the command 'ar'
+was not found.  You need to check your PATH environment variable to
+make sure that it includes the directory with the 'ar' command.  This
+is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin/
+directory.
+
+=back
+
+=head1 MAKE TEST
+
+=head2 op/stat.t test 4
+
+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.
+
+=head1 PREBUILT BINARIES.
+
+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.
+
+=head1 RUNTIME ISSUES.
+
+=head2 Limits on Numbers of Open Files.
+
+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.
+
+=head1 SOLARIS-SPECIFIC MODULES.
+
+See the modules under the Solaris:: namespace on CPAN,
+L<http://www.cpan.org/modules/by-module/Solaris/>.
+
+=head1 SOLARIS-SPECIFIC PROBLEMS WITH MODULES.
+
+=head2 Proc::ProcessTable
+
+Proc::ProcessTable does not compile on Solaris with perl5.6.0 and higher
+if you have LARGEFILES defined.  Since largefile support is the
+default in 5.6.0 and later, you have to take special steps to use this
+module.
+
+The problem is that various structures visible via procfs use off_t,
+and if you compile with largefile support these change from 32 bits to
+64 bits.  Thus what you get back from procfs doesn't match up with
+the structures in perl, resulting in garbage.  See proc(4) for further
+discussion.
+
+A fix for Proc::ProcessTable is to edit Makefile to
+explicitly remove the largefile flags from the ones MakeMaker picks up
+from Config.pm.  This will result in Proc::ProcessTable being built
+under the correct environment.  Everyting should then be OK as long as
+Proc::ProcessTable doesn't try to share off_t's with the rest of perl,
+or if it does they should be explicitly specified as off64_t.
+
+=head2 BSD::Resource
+
+BSD::Resource versions earlier than 1.09 do not compile on Solaris
+with perl 5.6.0 and higher, for the same reasons as Proc::ProcessTable.
+BSD::Resource versions starting from 1.09 have a workaround for the problem.
+
+=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.3 2000/11/09 19:11:27 doughera Exp $