Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: update macOS_Catalina.md #1992

Merged
merged 4 commits into from
Dec 29, 2019
Merged

doc: update macOS_Catalina.md #1992

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
72592a9
Fix typo in README.md (#1985)
suraneti Dec 13, 2019
c2fab21
Update macOS_Catalina.md
jameshome Dec 15, 2019
58c4140
Update macOS_Catalina.md
jameshome Dec 15, 2019
50e6081
Update macOS_Catalina.md
jameshome Dec 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ etc.), regardless of what version of Node.js is actually installed on your syste
## Features

* The same build commands work on any of the supported platforms
* Supports the targetting of different versions of Node.js
* Supports the targeting of different versions of Node.js

## Installation

Expand Down
49 changes: 29 additions & 20 deletions macOS_Catalina.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 Catalina has been fixed to solve these problems._
jameshome marked this conversation as resolved.
Show resolved Hide resolved

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:
* This should return `com.apple.pkg.CLTools_Executables`. If it doesn't, this test failed.
jameshome marked this conversation as resolved.
Show resolved Hide resolved
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.
* This should return `version: 11.0.0` (or later). If it doesn'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.
Expand All @@ -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.
Expand All @@ -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`
Expand All @@ -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