diff options
Diffstat (limited to 'README.solaris')
| -rw-r--r-- | README.solaris | 475 |
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 $ |