doc: update macOS_Catalina.md (#1992)

PR-URL: #1992
Reviewed-By: Christian Clauss <cclauss@me.com>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>

macOS_Catalina.md

@@ -1,39 +1,37 @@
 # Installation notes for macOS Catalina (v10.15)
 
-_This document specifically refers to upgrades from previous versions of macOS to Catalina (10.15). It should be removed from the source repository when Catalina ceases to be the latest macOS version or updated to deal with challenges involved in upgrades to the next version of macOS._
+_This document specifically refers to upgrades from previous versions of macOS to Catalina (10.15). It should be removed from the source repository when Catalina ceases to be the latest macOS version or when future Catalina versions no longer raise these issues._
 
-Lessons learned from:
-* https://github.com/nodejs/node-gyp/issues/1779
-* https://github.com/nodejs/node-gyp/issues/1861
-* https://github.com/nodejs/node-gyp/issues/1927 and elsewhere
-
-Installing `node-gyp` on macOS can be found at https://github.com/nodejs/node-gyp#on-macos
-
-However, upgrading to macOS Catalina changes some settings that may cause normal `node-gyp` installations to fail.
+**Upgrading to macOS Catalina may cause normal `node-gyp` installations to fail.**
 
 ### Is my Mac running macOS Catalina?
-Let's make first make sure that your Mac is currently running Catalina:
-% `sw_vers`
+Let's first make sure that your Mac is running Catalina:
+```
+% sw_vers
  ProductName: Mac OS X
  ProductVersion: 10.15
  BuildVersion: 19A602
+```
+If `ProductVersion` is less then `10.15` then this document is not for you. Normal install docs for `node-gyp` on macOS can be found at https://github.com/nodejs/node-gyp#on-macos
 
-If `ProductVersion` is less then `10.15` then this document is not really for you.
 
 ### The acid test
-Next, lets see if `Xcode Command Line Tools` are installed:
+To see if `Xcode Command Line Tools` is installed in a way that will work with `node-gyp`, run:
 1. `/usr/sbin/pkgutil --packages | grep CL`
- * If nothing is listed, then [skip to the next section](#Two-roads).
- * If `com.apple.pkg.CLTools_Executables` is listed then try:
+ * `com.apple.pkg.CLTools_Executables` should be listed. If it isn't, this test failed.
 2. `/usr/sbin/pkgutil --pkg-info com.apple.pkg.CLTools_Executables`
- * If `version: 11.0.0` or later is listed then _you are done_! Your Mac should be ready to install `node-gyp`. Doing `clang -v` should show `Apple clang version 11.0.0` or later.
+ * `version: 11.0.0` (or later) should be listed. If it isn't, this test failed.
+
+If both tests succeeded, _you are done_! You should be ready to install `node-gyp`.
+
+If either test failed, there is a problem with your Xcode Command Line Tools installation. [Continue to Solutions](#Solutions). 
 
-As you go through the remainder of this document, at anytime you can try these `acid test` commands. If they pass then your Mac should be ready to install `node-gyp`.
+### Solutions
+There are three ways to install the Xcode libraries `node-gyp` needs on macOS. People running Catalina have had success with some but not others in a way that has been unpredictable. 
 
-### Two roads
-There are two main ways to install `node-gyp` on macOS:
 1. With the full Xcode (~7.6 GB download) from the `App Store` app.
 2. With the _much_ smaller Xcode Command Line Tools via `xcode-select --install`
+3. With the _much_ smaller Xcode Command Line Tools via manual download. **For people running the latest version of Catalina (10.15.2 at the time of this writing), this has worked when the other two solutions haven't.**
 
 ### Installing `node-gyp` using the full Xcode
 1. `xcodebuild -version` should show `Xcode 11.1` or later.
@@ -52,7 +50,7 @@ There are two main ways to install `node-gyp` on macOS:
 10. `sudo xcode-select --reset` # Enter root password. No output is normal.
 11. Repeat step 7 above. Is the path different this time? Repeat the _acid test_.
 
-### Installing `node-gyp` using the Xcode Command Line Tools
+### Installing `node-gyp` using the Xcode Command Line Tools via `xcode-select --install`
 1. If the _acid test_ has not succeeded, then try `xcode-select --install`
 2. Wait until the install process is _complete_.
 3. `softwareupdate -l` # No listing is a good sign.
@@ -64,6 +62,11 @@ There are two main ways to install `node-gyp` on macOS:
 8. `sudo xcode-select --reset` # Enter root password. No output is normal.
 9. Repeat step 5 above. Is the path different this time? Repeat the _acid test_.
 
+### Installing `node-gyp` using the Xcode Command Line Tools via manual download
+1. Download the appropriate version of the "Command Line Tools for Xcode" for your version of Catalina from developer.apple.com/download. As of MacOS 10.15.2, that's Command_Line_Tools_for_Xcode_11.3.dmg
+2. Install the package.
+3. Run the _acid test_.
+
 ### I did all that and the acid test still does not pass :-(
 1. `sudo rm -rf $(xcode-select -print-path)` # Enter root password. No output is normal.
 2. `xcode-select --install`
@@ -72,3 +75,9 @@ There are two main ways to install `node-gyp` on macOS:
 5. `npm explore npm -g -- npm explore npm-lifecycle -- npm install node-gyp@latest`
 6. If the _acid test_ still does _not_ pass then...
 7. Add a comment to https://github.com/nodejs/node-gyp/issues/1927 so we can improve.
+
+Lessons learned from:
+* https://github.com/nodejs/node-gyp/issues/1779
+* https://github.com/nodejs/node-gyp/issues/1861
+* https://github.com/nodejs/node-gyp/issues/1927 and elsewhere
+* Thanks to @rrrix for discovering Solution 3