Rust WebAssembly: Farewell to --allow-undefined

Rust's WebAssembly (Wasm) targets are undergoing a significant change that could affect existing projects. The --allow-undefined flag, long passed to the wasm-ld linker, is being removed. This post explains what this flag does, why it's being removed, the risks it posed, and what you need to do to keep your Wasm builds working smoothly.

What change is coming to Rust's WebAssembly targets?

Rust has historically passed the --allow-undefined flag to wasm-ld when linking WebAssembly modules. This flag allowed undefined symbols (e.g., functions referenced in extern "C" blocks) to be silently converted into imported symbols in the final .wasm file. Starting soon, this flag will no longer be used, meaning any undefined symbol will trigger a compilation error instead of being tolerated. This change aligns WebAssembly targets with other platforms (like Linux or macOS) where undefined symbols cause linker errors.

What exactly is the --allow-undefined flag?

The --allow-undefined flag, as documented in wasm-ld, suppresses errors for symbols that are referenced but not defined during the link step. In Rust, this flag meant that calling a function via extern "C" without providing its definition would not fail. Instead, the linker would create an import in the WebAssembly module, allowing the symbol to be satisfied at runtime by the host environment. For example, mylibrary_init would become (import "env" "mylibrary_init" ...). This behavior is unique to WebAssembly and differs from traditional native linking.

Why was --allow-undefined used in the first place?

The exact reasons are somewhat lost to history, but it's believed that --allow-undefined was a workaround required in the early days of WebAssembly support in Rust. At that time, wasm-ld was still maturing, and the Rust toolchain needed a way to handle incomplete symbol resolution. This legacy persisted for years, becoming a default that masked potential issues. The flag essentially allowed quick experimentation and prototyping but also hid real build mistakes.

What risks does --allow-undefined introduce?

The main risk is that build errors go undetected. For instance:

• Typos: If you accidentally spell mylibrary_init as mylibraryinit, the linker will silently create an import for the wrong symbol instead of reporting an error.
• Missing libraries: If a C library that defines a symbol is not linked, the Wasm module will import the symbol at runtime, likely causing a crash or unexpected behavior.
• Misconfiguration: Complex build setups can produce broken modules that fail far from where the actual mistake was introduced, making debugging difficult.

By removing --allow-undefined, the Rust compiler will catch these issues at build time, just like on native platforms.

How does --allow-undefined affect the generated WebAssembly module?

When --allow-undefined is active, any undefined symbol becomes an import in the final .wasm file. For example, a Rust function calling external_function() via extern "C" without providing its definition would result in a module containing an import section like (import "env" "external_function" (func ...)). The module then expects the host environment (e.g., a web browser or Node.js) to provide that function. Without the flag, the linker will refuse to produce a binary if any symbol remains unresolved, forcing you to either define the symbol or explicitly mark it as an import using #[link(wasm_import_module = ...)].

How can I prepare my project for this change?

To avoid build failures, review any code that uses extern "C" blocks or #[no_mangle] functions that rely on external symbols. For symbols you intend to be provided at runtime, you must mark them explicitly as imports. The recommended way is to use the #[link(wasm_import_module = "module_name")] attribute on extern "C" blocks. For example:

#[link(wasm_import_module = "env")]
extern "C" {
    fn mylibrary_init();
}

If you are linking a native C library statically, ensure it is correctly compiled and included in the link step (e.g., via a build script). Finally, run cargo build --target wasm32-unknown-unknown with an up-to-date Rust toolchain to catch issues early.

Will this change break existing WebAssembly projects?

Yes, it may break projects that rely on the old behavior—especially those using extern "C" blocks without providing a definition or without explicit import attributes. The change turns silent runtime problems into compile-time errors, so previously working (but fragile) builds will now fail. However, this is ultimately beneficial: it forces correct symbol management, leading to more reliable WebAssembly modules. Updating to the new setup (by explicitly declaring imports or ensuring all referenced symbols are defined) will restore builds and make them robust.