---
title: Cross-build FAQ
description: Answers to recurring napi-rs cross-compilation and native loading questions.
---

# Cross-build FAQ

This page collects target-specific build questions. For installation, loading,
runtime, type-generation, and publishing failures, start with the
[troubleshooting guide](./troubleshooting). For choosing a cross-compilation
strategy, use the [Cross build](../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`](https://github.com/purpleprotocol/mimalloc_rust) 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](../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](../cross-build#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`](https://github.com/napi-rs/cross-toolchain) is too old for `aws-lc-sys` ([cross-toolchain#4](https://github.com/napi-rs/cross-toolchain/issues/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](../cross-build#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](https://github.com/rust-lang/rust/issues/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](https://github.com/napi-rs/package-template/blob/50ecdec7c7d31c60b693d5d52be6e13ba9b32bf8/.github/workflows/CI.yaml#L89-L91).