# Cross-build FAQ

This page collects target-specific build questions. For installation, loading, runtime, type-generation, and publishing failures, start with the troubleshooting guide. For choosing a cross-compilation strategy, use the Cross build decision guide.

# Build for Linux alpine

https://github.com/rust-lang/rust/pull/40113#issuecomment-323193341

You cannot set compile crate-type to cdylib when the compile target is *-unknown-linux-musl by default.

If you want to do so, you need to pass -C target-feature=-crt-static to rustc.

The NAPI-RS CLI handles this for you: for any *musl* target, napi build automatically appends -C target-feature=-crt-static to the RUSTFLAGS environment variable, and the project generated by napi new builds its musl targets this way out of the box.

Because the CLI exports this via the RUSTFLAGS environment variable, any rustflags in your .cargo/config.toml are ignored for musl builds (environment variables take precedence in Cargo). If you need extra rustc flags for a musl target, add them to the RUSTFLAGS environment variable instead of .cargo/config.toml.

If you use the mimalloc allocator, enable its local_dynamic_tls feature for musl targets; otherwise the addon can fail at runtime with a thread-local storage allocation error.

See Cross build for how to build musl targets from any host.

# GLIBC_x.yy not found

Error: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found

A *-linux-gnu addon links glibc dynamically and requires at least the glibc version of the machine that built it. If the build host runs a newer distro than the deploy host, the addon fails to load with this error.

The fix is to build against an older glibc:

• On a Linux x64/arm64 host, build with --use-napi-cross — it pins the glibc floor to 2.17, which loads on virtually every glibc distro.
• From a macOS or Windows host, build with --cross-compile (-x) — the floor becomes zig's default glibc: newer than 2.17, but independent of your host distro.

Do not switch to a *-musl target to fix this error — musl is a different libc for Alpine-style distros, not a way to lower a glibc requirement. See Glibc versions for the details.

# rustls / aws-lc-sys fails with --use-napi-cross on aarch64

If your crate depends on rustls — often transitively, via reqwest or hyper-rustls — its default backend aws-lc-sys fails to cross-compile for aarch64-unknown-linux-gnu with --use-napi-cross: the gcc bundled in @napi-rs/cross-toolchain is too old for aws-lc-sys (cross-toolchain#4).

Two workarounds:

• Compile the C parts with clang instead of the bundled gcc:

  sh

  TARGET_CC=clang TARGET_CXX=clang++ napi build --release --target aarch64-unknown-linux-gnu --use-napi-cross
  

• Use --cross-compile (-x) instead of --use-napi-cross.

See the Native dependencies section of the Cross build guide for the other recurring C/C++ cross-compilation problems.

# Build for Windows i686

There is codegen error when compile target is i686-windows-*: Rust issue 67497.

There is a workaround to avoid this issue:

• Set lto to false. If you haven't set lto in your Cargo.toml, the value is false by default, so you can ignore this step.
• Set codegen-units to 32 (or higher). The default value of codegen-units is 16 when the compile target is release. You can set CARGO_PROFILE_RELEASE_CODEGEN_UNITS=32 and CARGO_PROFILE_RELEASE_LTO='false' to make the compiler happy when targeting i686-windows-*. Here is an example.