node-pre-gyp build behavior and documentation discrepancy
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 1.2k
- Forks
- 271
- Avg merge
- 23h 40m
- Merged PRs (30d)
- 2
Description
### ❓ Question: `node-pre-gyp build` behavior and documentation discrepancy
While working with `node-pre-gyp`, I noticed a potential discrepancy between:
1. The `README.md` command list
2. The inline code comments
3. The actual behavior in source
### 📌 Context
In the code comments, it says "We map node-pre-gyp build to node-gyp configure build", but in practice, node-pre-gyp build does not trigger node-gyp configure — only node-pre-gyp rebuild does.
However, the README does not mention anything about whether configure is required before running build or rebuild, which could be confusing for users.
Here is the source code:
```js
function build(gyp, argv, callback) {
// Form up commands to pass to node-gyp:
// We map `node-pre-gyp build` to `node-gyp configure build` so that we do not
// trigger a clean and therefore do not pay the penalty of a full recompile
if (argv.length && (argv.indexOf('rebuild') > -1)) {
argv.shift(); // remove `rebuild`
// here we map `node-pre-gyp rebuild` to `node-gyp rebuild` which internally means
// "clean + configure + build" and triggers a full recompile
compile.run_gyp(['clean'], {}, (err3) => {
if (err3) return callback(err3);
configure(gyp, argv, (err4) => {
if (err4) return callback(err4);
return do_build(gyp, argv, callback);
});
});
} else {
return do_build(gyp, argv, callback);
}
}
```
### 🧩 My Questions
1. Is this behavior intentional?
2. Would it be possible to:
- update the README to explicitly mention the need for configure before build?
- clarify the inline comment in build.js to avoid confusion?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read README.md and build.js, focusing on the build(gyp, argv, callback) entry point and its handling of build versus rebuild. Confirm the current behavior and intended configure requirement before updating the command documentation and clarifying the inline comment; done means both descriptions match the verified behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, node.js
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100