docs: accurate cross-compilation guide and flag reference#486
Merged
Conversation
Rewrite the three cross-flag option rows (--cross-compile/-x, --use-cross, --use-napi-cross) to state what each flag really does, mark --use-cross as legacy, and fix the wording that implied cargo-xwin is picked per host (it is picked per Windows MSVC target from a non-Windows host). Add a 'Cross-compilation flags' reference section: the one-line mental model table, the combination rules (pick exactly one; the two --use-napi-cross combo warnings are misleading), prerequisites per flag, and one example command per flag, linking to /docs/cross-build and the FAQ musl entry. Add a 'What napi build actually runs' section: the spawned command per mode, the RUSTFLAGS contract for musl/--strip and its .cargo/config.toml shadowing, TARGET_CC over CC, the CARGO env override, the default linker table for less common targets, and the always-on Android/WASI/OpenHarmony env. Refs napi-rs/napi-rs#3355 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…release links - FAQ: new 'GLIBC_x.yy not found' entry (build-host glibc inheritance; --use-napi-cross / -x as fixes; musl is not the fix), new rustls/aws-lc-sys + --use-napi-cross entry (TARGET_CC=clang or -x), amended Alpine/musl entry (CLI auto-appends -crt-static via RUSTFLAGS, which shadows .cargo/config.toml rustflags; mimalloc local_dynamic_tls), re-pointed the drifted line-pinned CI.yml link at a commit-pinned permalink that still shows the codegen-units workaround. - napi-config: clarify that targets drives scaffolding/packaging (napi new CI matrix, create-npm-dirs, artifacts), not multi-target builds; cross flags are CLI-only; link the triple explainer to /docs/cross-build. - release: replace the dangling 'Later we will describe...' sentence with links to /docs/cross-build, /docs/cli/artifacts and /docs/cli/pre-publish. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…oss-build guide Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Ran scripts/convert-content.mjs to sync the served pages with the content/ edits from the cross-build docs work. Reverted the known converter collateral (blog metadata stripping and /assets image-path rewrites in blog + untouched doc pages) so only the seven intended pages are committed. lib/nav/index.ts had no changes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- simple-package: reference /assets/CI.png in content (all locales) so pages/ is byte-identical converter output instead of hand-patched - simple-package: .cargo/config.toml note now states what the file actually contains (Windows MSVC static-CRT rustflags); cross-compile linker/toolchain config comes from the napi CLI; dropped the invented zig-red-herring claim (zig IS required for musl -x jobs) - cli/build + cross-build: -x routes ALL *-windows-* triples (not just MSVC) from a non-Windows host through cargo-xwin; only the selected helper is auto-installed, on first use; x86_64-pc-windows-gnu is an accepted CLI target since napi-rs#2935 (reviewer's "unsupported by design" was stale - corrected rather than copied) - cli/build: Android/WASI/OpenHarmony env split per platform with the real conditions (NDK warn-but-set, WASI_SDK_PATH only when set and existing with rust-lld fallback, OHOS_SDK_PATH/native or OHOS_SDK_NATIVE else warn-and-skip) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- getting-started: generated CI covers only template matrix targets; napi new filters rows, never adds them (new.ts filterTargetsInGithubActions) - cross-build: decision tree branches on target platform (Windows), not MSVC, matching the CLI's xwin routing; MSVC preference kept as policy text - cli/build + cross-build: -x prerequisites split by backend — zig only for cargo-zigbuild, clang (+ llvm-tools for assembly) for cargo-xwin - cross-build: musl proof no longer pins zig 0.14.1 (pnpm template uses 0.15.2); version-neutral "setup-zig step" - simple-package: .cargo/config.toml static-CRT claim narrowed to the targets actually present (x86_64; i686 in the pnpm template) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- cross-build intro: scope -x to its real cases (xwin for Windows from non-Windows hosts, zigbuild for musl/glibc/macOS/FreeBSD when needed); Android/WASI/OpenHarmony called out as no-flag + platform env - FreeBSD: no longer ruled out for cross-compilation — napi-rs' own CI cross-builds x86_64-unknown-freebsd with -x + zig on ubuntu-latest; recipe now presents both the VM reference path and the -x path - getting-started: untemplated targets get neither CI rows nor npm packages (napi new only filters the template's napi.targets) - napi-config: napi build does read napi.targets for WASI binding generation (wasm filename + emission gate) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- cli/build: scope the flag recommendation the same way as the cross-build intro — -x is for Windows-from-non-Windows, musl, and the zigbuild fallback cases; Android/WASI/OpenHarmony need no flag. Reword the "everything else" example comment to match. - cross-build: scope the -x Status cell in the flag-comparison table the same way, and stop claiming the generated CI FreeBSD VM job runs tests — it only builds and uploads the artifact; testing on FreeBSD is a step users add themselves. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 66ca7b8f80
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…MSVC-only) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…H claim Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… sync intro pages Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… page The shared lib/i18n/route-map.gen.ts diff covers both new locales (cn + pt-BR) on its changed lines, so it lands in this final commit. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…se sentence Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
14 native-reader wording fixes across cn/pt-BR (colloquialisms and calques only — no claim changes): 落进→落入, 压过→覆盖, 坏掉→无效, double-negative in the verify section, manylinux2014 phrasing, "se alguma"→"(se houver)", "testada em batalha"→"comprovada na prática", "recua para"→"faz fallback para", and similar. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addresses napi-rs/napi-rs#3355 — the cross-build flags (
--cross-compile/-x,--use-cross,--use-napi-cross) were documented only by naming the tool behind each one, with no guidance on the differences, when to use which, or whether they combine.What changed
/docs/cli/build— the three flag rows rewritten; new Cross-compilation flags section (mental-model table: binary swap vs subcommand swap vs env-only; combination rules — pick exactly one; per-flag prerequisites and what is/isn't auto-installed); new What napi build actually runs section (exact command per mode, RUSTFLAGS/musl contract,TARGET_CC>CC, theCARGOenv override, baseline linker table, per-platform env conditions for Android/WASI/OpenHarmony)./docs/cross-build— rewritten as the decision hub: host×target decision matrix + mermaid decision tree, flag comparison table, per-target copy-paste recipes tied to the generated CI jobs that prove them, glibc-version section (whyGLIBC_x.yy not foundhappens, why musl is not the fix), artifact verification snippet, native-dependency recipes (TARGET_CC=clang, aws-lc-sys/rustls limitation, vendored TLS), docker-image deprecation callout (migrate to--use-napi-cross/-x), and an add-a-target-to-an-existing-project recipe.GLIBC_x.yy not found, rustls/aws-lc-sys ×--use-napi-cross; musl entry amended (auto-crt-static, mimalloclocal_dynamic_tls)./docs/cli/napi-config—targetsclarified (scaffolding/packaging + WASI binding emission; not a multi-target build switch).pages/regenerated viaconvert-content.mjs(byte-identical to converter output; blog sidecars untouched).Verification
cli/src/api/build.tset al.), extracted by a research fan-out and adversarially verified.yarn buildgreen; converter re-run produces zero diff on every page this branch touches.Deferred follow-ups
--helpstrings (cli/codegen/commands.ts) + CLI bug suggestions (misleading combo warnings, silent--use-napi-crossfallback) — plan §4–§5.build.pt-BR.mdx).🤖 Generated with Claude Code