mapbox / mapbox/node-pre-gyp

node-pre-gyp build behavior and documentation discrepancy

Open
#902 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.