docs: update npm build description

[siemhesda]

Update node rebuild command

References

Closes #6453

[wraithgar]

While the existing docs don't properly describe what this does, neither does this update. The rebuild function in arborist does several things, including running the install scripts, linking bins, and linking in dependencies.

[siemhesda]

While the existing docs don't properly describe what this does, neither does this update. The rebuild function in arborist does several things, including running the install scripts, linking bins, and linking in dependencies.

Is this better?

[siemhesda]

This command does the following:

1. Execute lifecycle scripts (preinstall, install, postinstall, prepare)
2. Links bins depending on whether bin links are enabled

This command is particularly useful in scenarios including but not limited to:

1. Installing a new version of node.js, where you need to recompile all your C++ add-ons with the updated binary.
2. Installing with --ignore-scripts and --no-bin-links, to explicitly choose which packages to build and/or link bins.

If one or more package specs are provided, then only packages with a name and version matching one of the specifiers will be rebuilt.

Usually, you should not need to run npm rebuild as it is already done for you as part of npm install (unless you suppressed these steps with --ignore-scripts or --no-bin-links).

If there is a binding.gyp file in the root of your package, then npm will use a default install hook:

"scripts": {
    "install": "node-gyp rebuild"
}

This default behavior is suppressed if the package.json has its own install or preinstall scripts. It is also suppressed if the package specifies "gypfile": false

[wraithgar]

That looks like quite an improvement, yes.