GH-454 Updates to README and README.OSX installation instructions.

3 files changed, 40 insertions, 24 deletions

diff --git a/Changes b/Changes
index b4887bd..de30d8e 100644
--- a/Changes
+++ b/Changes
@@ -155,6 +155,8 @@ Revision history for Perl extension Net::SSLeay.
 	  Net::SSLeay. This may still be a requirement on some
 	  platforms, but, for example, with Linux and macOS mixing
 	  clang and gcc appears to work.
+	- Add general installation instructions in README. Thanks to
+	  GitHub user viviparous. Update README and README.OSX.
 
 1.93_02 2023-02-22
 	- Update ppport.h to version 3.68. This eliminates thousands of
diff --git a/README b/README
index a5380fd..0a392fb 100644
--- a/README
+++ b/README
@@ -10,7 +10,6 @@ for the released versions:
    https://metacpan.org/release/Net-SSLeay
 
 for the latest and possibly unstable version from git:
-
    https://github.com/radiator-software/p5-net-ssleay
 
 
@@ -61,30 +60,36 @@ Installing
 ----------
 
 General:
-If your OpenSSL is installed in an unusual place, you can tell
-	Net-SSLeay where to find it with by setting the OPENSSL_PREFIX environment
-	variable. Example:
+	Makefile.PL tries to find OpenSSL installation location from a
+	number of pre-defined paths. It will print the version and
+	location of OpenSSL or LibreSSL it finds, or warn if it doesn't
+	find anything usable.
+
+	If your OpenSSL is installed in an unusual place, you can tell
+	Makefile.PL from where to find it with by setting the
+	OPENSSL_PREFIX environment variable.
+
+	On Linux, macOS and other Unix type systems:
+	OPENSSL_PREFIX=/home/mikem/playpen/openssl-1.0.2c perl Makefile.PL
 
-  export OPENSSL_PREFIX=/my/non-standard/path/usr
+	On Windows:
+	set OPENSSL_PREFIX=C:\playpen\openssl-1.0.2.c
+	perl Makefile.PL
 
-The logic in Makefile.PL appends include/openssl to the environment 
-variable OPENSSL_PREFIX.
+	The logic in Makefile.PL tries to resolve the required
+	libraries and include directories based on the environment
+	variable OPENSSL_PREFIX.
 
 Unix:
-	# build or install OpenSSL as per instructions in that package
+	Build or install OpenSSL as per instructions in that
+	package. Review section 'General:' above before continuing.
 
 	gunzip <Net-SSLeay.pm-1.35.tar.gz | tar xvf -
 	cd Net-SSLeay.pm-1.35
-	perl Makefile.PL     # builds and tests it
+	perl Makefile.PL     # Build it. Use OPENSSL_PREFIX, if needed.
 	make test            # Run the test suite
 	make install         # You probably have to su to root to do this
 
-	If your OpenSSL is installed in an unusual place, you can tell
-	Net-SSLeay where to find it with the OPENSSL_PREFIX environment
-	variable:
-	OPENSSL_PREFIX=/home/mikem/playpen/openssl-1.0.2c perl Makefile.PL
-	....
-
 HPUX:
 	In principle the Unix build should work (Makefile.PL contains
 	special code to detect aCC), but historically there have been
@@ -94,12 +99,12 @@ HPUX:
 
 	Configuring OpenSSL:
 
-		./Configure no-asm --prefix=/openssl/path hpux-parisc2-cc
+	./Configure no-asm --prefix=/openssl/path hpux-parisc2-cc
 
 	Configuring Net::SSLeay:
-	
-		OPENSSL_PREFIX=/openssl/path perl Makefile.PL CCFLAGS='-D_HPUX_SOURCE \
-		 -Aa -I/usr/local/include +e'
+
+	OPENSSL_PREFIX=/openssl/path perl Makefile.PL CCFLAGS='-D_HPUX_SOURCE \
+	 -Aa -I/usr/local/include +e'
 
 	The magic bit seemed to be the `+e' flag. Since version 1.14
 	Makefile.PL tries to figure this out.
@@ -110,9 +115,9 @@ Windows:
 	Supported on 32 and 64 bit platforms
 	See README.Win32 for details
 
-OS X:
+macOS, also known as OS X:
 	See README.OSX
----------------------------------	
+---------------------------------
 You should also be able to use CPAN.pm to install this module if you like.
 
 Problems (read this before filing a bug)
diff --git a/README.OSX b/README.OSX
index 52aafa6..fc9631e 100644
--- a/README.OSX
+++ b/README.OSX
@@ -1,8 +1,9 @@
-As of 15 Jun 2015, Apply no longer ships OpenSSL with OS X:
+As of 15 Jun 2015, Apple no longer ships OpenSSL with OS X:
 (http://lists.apple.com/archives/macnetworkprog/2015/Jun/msg00025.html)
 
-Some OS X packages and bundles install OpenSSL, typically in /opt/local
-if that is the case it is sufficient for you to unpack and build
+Some OS X packages and bundles install OpenSSL to locations known by
+Makefile.PL, for example, /opt/homebrew, /usr/local or /opt/local.
+If that is the case it is sufficient for you to unpack and build
 Net-SSLeay in the usual way:
 
 #cd to a working directory
@@ -11,6 +12,7 @@ cd /Users/mikem/tmp/
 tar zxvf /Volumes/projects/net-ssleay/trunk/Net-SSLeay-1.72.tar.gz
 cd Net-SSLeay-1.72
 # Build it for 64 bits (default)
+# Use OPENSSL_PREFIX, see README, if needed
 perl Makefile.PL
 make
 make test
@@ -20,6 +22,13 @@ make install
 If a working openssl is not installed already the above will fail, 
 but you can still build your own OpenSSL to link against:
 (https://wiki.openssl.org/index.php/Compilation_and_Installation), and build Net-SSLeay against it:
+
+
+
+Here are some older instructions. The current, year 2024, OpenSSL and
+LibreSSL versions come with installation instructions that you should
+primarily follow. Then install Net::SSLeay as shown above.
+
 Test compilation etc in a private directory eg:
 
 #cd to a working directory