fix: doc how to update node-gyp independently from npm

[owl-from-hogvarts]

Checklist

• npm install && npm test passes
• tests are included
• documentation is changed or added
• commit message follows commit guidelines

Description of change

#2272

[cclauss]

My sense is that we should have a separate docs for Windows and Linux/macOS. Most of the open issues and complexity is on the Windows side. The Linux/macOS doc would be more streamlined.

[owl-from-hogvarts]

IMO what you are suggesting should be done in separate pull request. This one is only for incldujg important notes to docs.

After including that we can start work on separating docs by platforms.

[rvagg]

not sure we need this line if you've captured the essence of it below

[rvagg]

Seems fine to me but can you please go over the text and look for missing spaces, there's a bunch of run-ins in many of the lines. I did start a suggestion review but it impacts most of the first half of this at least. Maybe a copy/paste problem?

Also I'm fine with just getting this into a good state and then we could fork it into separate docs if it gets large enough.

[cclauss]

My sense is that this sentence is more meandering and less clear than the original.

[owl-from-hogvarts]

agree

[owl-from-hogvarts]

@cclauss can this be merged?

[rvagg]

Suggested change

Generally, npm's library files are installed inside your global "node_modules",where npm is installed (run `npm prefix` and add `lib/node_modules`, or just `node_modules` for Windows). There are some exceptions to this. Inside this global `node_modules/`there will be an `npm/` directory and inside this you'll find a `node_modules/node-gyp/` directory. So it may look something like `/usr/local/lib/node_modules/npm/node_modules/node-gyp/`. This is the version of node-gyp that ships with npm.

Generally, npm's library files are installed inside your global "node_modules", where npm is installed (run `npm prefix` and add `lib/node_modules`, or just `node_modules` for Windows). There are some exceptions to this. Inside this global `node_modules/` there will be an `npm/` directory and inside this you'll find a `node_modules/node-gyp/` directory. So it may look something like `/usr/local/lib/node_modules/npm/node_modules/node-gyp/`. This is the version of node-gyp that ships with npm.

[owl-from-hogvarts]

On windows global node_modules and node's node_modules are two diffrent dirs, aren't they? Thats why

Generally, npm's library files are installed inside your global "node_modules", where npm is installed

can really mislead.

I propose this:

So npm's internal copy of node-gyp isn't stored inside global node_modules and thus isn't available for use as a standalone package. Npm uses it's internal copy of node-gyp to automatically build native addon when you are trying to it install via npm install

[cclauss]

Conflicting files docs/Updating-npm-bundled-node-gyp.md

Are we convinced that the majority of users are going to remember to undo/redo when upgrading?

[owl-from-hogvarts]

When updating npm or node-gyp?

As i understand npm config writes to .npmrc which i asume should persist when updating npm. And also does path to global node-gyp really breaks when updating?

[owl-from-hogvarts]

Does my own addition to this file should be done as separate PR?

[owl-from-hogvarts]

@rvagg @cclauss Can this finally be merged, pls?

[rvagg]

yes, it can! sorry, I didn't see that you'd updated based on the review, thanks @owl-from-hogvarts!

[DeeDeeG]

Hi folks.

Short summary: This doesn't work in npm 7 or newer.

This advice is not applicable to npm 7 or 8 at the moment. npm authors inadvertently broke the node_gyp npm config var's functionality, starting in npm 7, and it has not been fixed since. Still broken in the latest npm 8.1.3 as I write this comment. npm maintainers have acknowledged the issue.

See these open issues I filed at the npm repo: https://github.com/npm/cli/issues?q=is%3Aissue+is%3Aopen+node-gyp+author%3ADeeDeeG

The advice in this file, as of this PR, boils down to setting that config var. So it won't work on npm 7 or npm 8.

The catch is that npm won't use this version unless you tell it to, it'll keep on using the one you have installed. You need to instruct it to by setting the node_gyp config variable (which goes into your ~/.npmrc). You do this by running the npm config set command as below. Then npm will use the command in the path you supply whenever it needs to build a native addon.

That advice is unfortunately not true on npm 7 and 8 at the moment.

[DeeDeeG]

Short summary: The content of this docs page from before this PR had steps that work in npm 7. Please host/restore the old content of this docs page somewhere. Furthermore, this PR caused the title/filename to not match the content. Please make it so the titles/filenames match the content.

---

Also: The title and filename of this do not match the content anymore, as of this PR. This advice is more about "Having npm use an independent copy of node-gyp instead of its bundled copy".

The title ("Updating the npm-bundled version of node-gyp") matches the previous content.

I would request that the previous content of this file be hosted somewhere in the docs... Preferably under this filename, to make the edit history follow-able. (In other words, please consider restoring the previous content of this file, and moving the new content to another file.)

I would humbly suggest to move the updated content to a new file, under an appropriate filename and title, with the understanding that it applies ONLY to npm 6 and lower, and saying so somewhere in this file, so users don't get surprised when it doesn't work in npm 7 or higher.

The method described as of this PR is a more durable, maybe less hacky fix for npm 6 users. So I do like this method. It's just a minor disappointment it doesn't work on newer npm right now.