bootstrap: Rototill README.Solaris

Fix an earlier error, and separate/organize the two compiler sections.

1 files changed, 91 insertions, 61 deletions

diff --git a/bootstrap/README.Solaris b/bootstrap/README.Solaris
index e9d5f143c10..943cb1e398d 100644
--- a/bootstrap/README.Solaris
+++ b/bootstrap/README.Solaris
@@ -1,35 +1,29 @@
-$NetBSD: README.Solaris,v 1.18 2022/04/04 01:22:09 gutteridge Exp $
+$NetBSD: README.Solaris,v 1.19 2022/04/04 12:35:43 gdt Exp $
 
 This README describes pkgsrc on a variety of Solaris-derived operating
-systems.  It corresponds to pkgsrc/platform/SunOS.mk. The relevant
+systems.  It corresponds to pkgsrc/platform/SunOS.mk.  The relevant
 operating systems are:
   - Solaris (from Sun/Oracle, also Sun Solaris, Oracle Solaris)
   - OpenSolaris (from Sun)
-  - illumos (open-source fork, OpenIndiana, SmartOS, OmniOS, and others)
+  - illumos (open-source fork, OpenIndiana, OmniOS, SmartOS, and others)
 
-(pkgsrc is not currently known to work on SunOS 4.)
+OpenSolaris has not been maintained for a very long time, so the only
+platforms of interest are Oracle Solaris and illumos distributions.
+As of 2022, pkgsrc is believed to work well on Oracle Solaris and
+illumos.  pkgsrc is not currently known to work on SunOS 4 or
+OpenSolaris.
 
 Prerequisites
 -------------
 
-You will need a working C compiler. Any version of gcc >2.8 should
-work, 2.95.x and 3.x have been tested. SunPro 5 and 8 have been
-tested, but versions in between should work, too.
+You will need a working C compiler.  The two known options are gcc and
+Sun/Solaris Studio.  gcc can come from Sun, or other places.  On some
+systems, there is only one feasible choice.
 
-Please note the use of GNU binutils on Solaris is not supported.
+As with pkgsrc on other platforms, one should use the same compiler
+family and ideally the same compiler version for building all packages.
 
-Whichever compiler you use, please ensure the compiler tools and
-your $prefix are in your PATH. This includes /usr/ccs/{bin,lib}
-and e.g. /usr/pkg/{bin,sbin}.
-
-You should set the following variables in your mk.conf file:
-	CC= 	cc
-	CXX=	CC
-	CPP=	cc -E
-	CXXCPP=	CC -E
-
-To build 64-bit binaries, pass '--abi=64' to bootstrap, and also see the
-crle(1) man page to configure the runtime linking environment.
+Please note that the use of GNU binutils on Solaris is not supported.
 
 The following packages are the minimum required on Solaris 8 to
 bootstrap and build packages.
@@ -44,8 +38,10 @@ bootstrap and build packages.
 Realistically you will need more, such as SUNWlibm, and SUNWlibC for
 C++ packages if you are using SunPro.
 
-pkgsrc in Solaris Zones
------------------------
+Solaris Zones:
+
+(It is not clear if this is really about zones, or is just a different
+prereq list for a particular variant.)
 
 If you are trying to bootstrap pkgsrc in a Solaris Zone then you will
 need to install the following packages (assuming you will bootstrap using
@@ -65,14 +61,23 @@ Sun's gcc package):
 
 Tested on OpenSolaris 5.11 snv_105 and pkgsrc bootstrap as at Jan 2009.
 
+General
+------
+
+To build 64-bit binaries, pass '--abi=64' to bootstrap, and also see
+the crle(1) man page to configure the runtime linking environment.
+(It is not clear if this is the default on sparc64/amd64, and if not,
+why not.)
+
+On illumos, gcc is the only workable option.
+
+
 If you are using gcc
 --------------------
 
-It makes life much simpler if you only use the same gcc consistently
-for building all packages.
-
-See http://www.NetBSD.org/docs/software/packages.html for
-binary kits and initial packages, including gcc.
+See https://wiki.netbsd.org/pkgsrc/solarish/ for information about
+installing gcc on various illumos distributions.  One can use a
+distribution-provided gcc, or a gcc that has been built from sources.
 
 If the gcc installation is not in your $PATH you will need to pass
 additional flags to bootstrap, for example:
@@ -87,21 +92,45 @@ pkgsrc gcc is installed and used.
 
 Binary packages of gcc can be found through
 http://www.sunfreeware.com/
+[2020-04-04: This link appears no longer valid and is on a 30-day timer to be fixed or deleted.]
+
+
+Alternatively, see https://pkgsrc.joyent.com/install-on-illumos/ for
+binary kits and initial packages (including gcc) that run on illumos
+variants.
 
-If you are using Sun WorkShop
------------------------------
 
-You will need at least the following packages installed to build C and
-C++ packages.
+If you are using Sun Studio
+---------------------------
 
-WorkShop 5.0:
+This section describes the use of Sun-provided compilers, variously
+termed WorkShop and Studio.
+
+You must ensure that the compiler tools and your $prefix are in your
+PATH.  This includes /usr/ccs/{bin,lib} and e.g. /usr/pkg/{bin,sbin}.
+Set the following variables in your mk.conf file:
+	CC= 	cc
+	CXX=	CC
+	CPP=	cc -E
+	CXXCPP=	CC -E
+NB: The make variable CC holds the command for the C compiler, and the
+command for the C++ compiler is CC.
+[It is not clear if one needs to specify these variables to bootstrap
+or not, and if so, whether they are in the generated mk.conf,a nd if
+not, why not.]
+
+The following indented sections provide a list of Solaris packages
+that must be installed in order for pkgsrc to build C and C++
+packages.
+
+    WorkShop 5.0:
 
 	SPROcc		Sun WorkShop Compiler C 5.0
 	SPROcpl		Sun WorkShop Compiler C++ 5.0
 	SPROild		Sun WorkShop Incremental Linker
 	SPROlang	Sun WorkShop Compilers common components
 
-Sun ONE Studio 8:
+    Sun ONE Studio 8:
 
 	SPROcc		Sun ONE Studio 8 Compiler C
 	SPROcpl		Sun ONE Studio 8 Compiler C++
@@ -113,45 +142,48 @@ Sun ONE Studio 8:
 	SPROtlbn7	Sun ONE Studio 8 Tools.h++ 7.1 Class Library for C++
 	SPROutool	Sun ONE Studio 8 Common Tools
 
-The corresponding 64-bit packages are also required to build 64-bit
-binaries and libraries.
+	The corresponding 64-bit packages are also required to build
+	64-bit binaries and libraries.
 
-Oracle Studio 12 (IPS):
+    Oracle Studio 12 (IPS):
 
 	pkg:/developer/developerstudio-12[3-6]	studio
 	pkg:/system/library/studio-runtime	Runtime Support For Solaris Studio
 
-This will install the whole toolchain, along with the observability tools and
-the studio IDE.
+	This will install the whole toolchain, along with the
+	observability tools and the studio IDE.
 
-If you want to select individual packages, make sure to have runtime libraries
-installed. For instance, on Studio 12.6, you can do that with:
+	If you want to select individual packages, make sure to have
+	runtime libraries installed. For instance, on Studio 12.6, you
+	can do that with:
 
-   pkg install --accept developerstudio-126/library/c++-libs \
-        developerstudio-126/library/c-libs \
-        developerstudio-126/library/f90-libs \
-        developerstudio-126/library/math-libs \
-        developerstudio-126/library/perflib \
-        developerstudio-126/library/studio-gccrt
+	pkg install --accept developerstudio-126/library/c++-libs \
+	    developerstudio-126/library/c-libs \
+	    developerstudio-126/library/f90-libs \
+	    developerstudio-126/library/math-libs \
+	    developerstudio-126/library/perflib \
+	    developerstudio-126/library/studio-gccrt
 
-pkgsrc defaults to finding the Sun compiler in /opt/SUNWspro.  If you use a
-different prefix, pass SUNWSPROBASE in the environment to bootstrap.  If 'cc'
-is not in your path, pass CC as well.  So, to build 64-bit Sun compiler
-bootstrap with a non-standard install:
+        To build with Studio 12 on Solaris 11:
 
-	env CC=/opt/studio12/SUNWspro/bin/cc \
-	    SUNWSPROBASE=/opt/studio12/SUNWspro \
+	env CC=/opt/developerstudio12.*/bin/cc \
+	    SUNWSPROBASE=/opt/developerstudio12.* \
+	    PKGSRC_COMPILER=sunpro \
 	    ./bootstrap --abi=64
 
-On Solaris 11:
+	pkgsrc defaults to finding the Sun compiler in /opt/SUNWspro.
+	If you use a different prefix, pass SUNWSPROBASE in the
+	environment to bootstrap.  If 'cc' is not in your path, pass
+	CC as well.  So, to build 64-bit Sun compiler bootstrap with a
+	non-standard install:
 
-    env CC=/opt/developerstudio12.*/bin/cc \
-        SUNWSPROBASE=/opt/developerstudio12.* \
-        PKGSRC_COMPILER=sunpro \
-        ./bootstrap --abi=64
+	env CC=/opt/studio12/SUNWspro/bin/cc \
+	    SUNWSPROBASE=/opt/studio12/SUNWspro \
+	    ./bootstrap --abi=64
 
-When bootstrap is finished your default mk.conf will contain ABI and
-SUNWSPROBASE so you will not need to set these variables again.
+	When bootstrap is finished your default mk.conf will contain
+	ABI and SUNWSPROBASE so you will not need to set these
+	variables again.
 
 Common problems
 ---------------
@@ -164,5 +196,3 @@ installing shells/bash and adding the following lines to your mk.conf:
 	WRAPPER_SHELL=  ${LOCALBASE}/bin/bash
 
 Then, rebuild the devel/libtool-base package.
-
-bootstrap-pkgsrc has been tested on Solaris 2.6 -> 11.