WASM32-UNKNONOW-UNKNONW-C HELP TO YOU MUST KNOW

Its extern "C" For help wasm32-unknown-unknown Target has used a non-standard definition from the establishment of a target as it does not apply the official C ADs of Webassembly and leaks in addition to the details of the implementation of both Rust Compiler and LLVM's internal compiler. It changes in the future version of the rust compiler and instead of official C help is used.

This post describes the history and justification behind this change as to why it is announced here, but you can skip directly: “Does I affect me?” Also.

History wasm32-unknown-unknown'SC HELP

If wasm32-unknown-unknown Target was originally added in 2017, especially not cared for much extern "C" Help at that time. In 2018, the definition of help was added to WASM and the target still uses this definition to this day. These definitions have become more and more problematic over time, and although some problems have been solved, the root cause remains.

Namely, this aid definition does not correspond to the definition of C API tool conventions, which is the current standard, how webassemble tool chains should talk to each other. Initially, this non -standard definition was used for all Webassemblly's main targets, except Emscripten, but it changed in 2021, where rust WASI targets use the definition of improved assistance. However, a non -standard definition remained in use wasm32-unknown-unknownTo.

The time has now reached to correct this historical error and the rust compiler will soon use the correct definition of help wasm32-unknown-unknown Target. This means, however, that the generated web sets are different from before.

What is Webassemblly C Help?

The definition of assistance answers the questions as follows:

• What registers are these arguments?
• What registers will be handed over?
• How are the 128-bit integers a argument?
• How are a union This return value?
• When will the parameters be given memory instead of registers?
• What is the size and alignment of the type of memory?

For Webassemble, these answers are slightly different than natural platforms. For example, webassemble has no physical records and all functions must be notes with the type. What Webassemblbly does is like this type like i32To do, i64To do, f32and f64To. This means that for Webassemble, help must be determined by how to represent this type of values.

This is where the tool convention document comes. This document provides a definition of how to represent CI in a primitive website format and, in addition to how the C-function signatures are mapped by the signatures of the Webassemble function. Such as rust u32 represents a web set i32 And it is transmitted directly as a parameter as an argument for the function. If the structure of the rust #[repr(C)] struct Pair(f32, f64) Returned from the function, then the back -up is used, which must have a alignment of 8 and 16 bytes.

In essence, webassemble C help acts as a bridge between type C system and a Webassemble type system. This includes details such as memory places and C-function signature translations to the signature of the Webassembr.

How is it wasm32-unknown-unknown Non -standard?

Despite the fact that the definition of assistance is non -standard today, many aspects of it are still the same as the tool conventions. For example, the size/alignment of the types is the same as. Example (where you can monitor Godbolt) is:

#[repr(C)]
pub struct Pair {
    x: u32,
    y: u32,
}

#[unsafe(no_mangle)]
pub extern "C" fn pair_add(pair: Pair) -> u32 {
    pair.x + pair.y
}

This generates the feature of the following website:

(func $pair_add (param i32 i32) (result i32)
  local.get 1
  local.get 0
  i32.add
)

Namely you see this structure here Pair was “sprayed” into its two components, so the actual $pair_add The function takes two arguments, x and y fields. Tool Conventions, however, say “other structure[s] or union[s]”Provided indirectly, especially through memory. This is what we can see with this C -code:

struct Pair {
    unsigned x;
    unsigned y;
};

unsigned pair_add(struct Pair pair) {
    return pair.x + pair.y;
}

that gives a generated function:

(func (param i32) (result i32)
  local.get 0
  i32.load offset=4
  local.get 0
  i32.load
  i32.add
)

Here we can definitely see enough pair It is given in linear memory and has only one argument, not two. This argument is a pointer in the linear memory that saves x and y fields.

The diplomat project has compiled a much more comprehensive overview of it and is recommended to check it if you are curious for even deeper.

Why hasn't it been fixed for a long time?

For wasm32-unknown-unknown It was already known in 2021 when the wast was updated that the help was non -standard. So why isn't the help fixed with WAS? Initially, the main reason for this was the Wasm-Bindgen project.

In wasm-bindgen The aim is to easily change the integration of rust to the web browser with Webassembly. JavaScript is used to interact with the Host API and the rust module. Of course, this communication concerns many help details! The problem was that wasm-bindgen Based on the example above, especially Pair “Splats” over arguments, not indirectly. The generated JS would not work properly if the argument was accepted in memory.

At that time it was found to be remarkably difficult to improve wasm-bindgen Do not rely on this fragmenting behavior. During this time, it was not considered a widespread topic and the compiler was not expensive to have non -standard help. The pressure has increased over the years. The rust compiler is bearing a constantly growing list of hacks to work around non -standard C assistance wasm32-unknown-unknownTo. In addition, more projects have begun to rely on this “spraying” behavior and the risk has become greater to the unknown projects based on non -standard behavior.

2023. At the end of the year, the generation of fixed volumes of the Wasm-Bindgen project, not affected by the transition to standard definition extern "C"To. In the following months, Rustc was added to the future in order to travel specifically for old users wasm-bindgen versions to the “fixed” version. It was as expected change of help wasm32-unknown-unknown When enough time had passed. From the beginning of 2025 wasm-bindgen The versions are now getting a difficult mistake by asking them to upgrade.

Despite all this co -workers' heroic efforts, it has now become apparent that there are more projects than wasm-bindgen Based on this definition of non -standard assistance. Consequently, this blog post is intended for other users for notice wasm32-unknown-unknown The fact that the help pause is future and projects may need to be changed.

Does I suffer?

If you do not use wasm32-unknown-unknown Target, this change does not affect you. If you do not use extern "C" on wasm32-unknown-unknown Target, you are not affected either. If you get into this bucket, you may still be influenced!

There are some tools at your disposal to determine the impact of the project:

• A new future-intersect warning is added to the Rust compiler, which will provide a warning if it identifies a signature that changes to change the aid.
• In 2023 a -Zwasm-c-abi=(legacy|spec) A flag was added to the rust compiler. This default -Zwasm-c-abi=legacyNon -standard definition. The code can be used -Zwasm-c-abi=spec Use the standard definition of C aid for the crate to test whether the changes will work.

The best way to test the crate is to compile nightly-2025-03-27 or later make sure there are no warnings and then test that your project is still working -Zwasm-c-abi=specTo. If all this passes, you will be good to go and C for the upcoming change will not affect your project.

I suffer, what now?

So you are using wasm32-unknown-unknownyou are using extern "C"And the night compiler gives you warnings. In addition, your project is broken if they are prepared -Zwasm-c-abi=specTo. What's now?

Unfortunately, this is a somewhat approximate transition period for you. There are some options at your disposal, but they all have shelter:

1. Attach the version of your rust compiler to the current stable, do not refresh until the help has changed. This means that you will not receive the compiler warnings (as old compilers do not warn) and you will not break if you change the help (as you do not change the compiler). Finally, when you update a stable compiler with -Zwasm-c-abi=spec As a default value, you need to work with your JS or volumes to work with a new help.
2. Update Rust at night as your compiler and passes -Zwasm-c-abi=specTo. It will load the work you need in your target in paragraph 1. You can compatible your project -Zwasm-c-abi=spec Today. The downside of this approach is that your project will only run a nightly compiler and -Zwasm-c-abi=spec And you can't use stable until default.
3. Refresh your project so as not to rely on non -standard behavior -Zwasm-c-abi=legacyTo. This includes, for example, in parameters by structures. You can pass by &Pair above PairTo. It is similar to the above point 2, where the work is done immediately to update the project, but it has the advantage of continuing to work on stable rust. However, its downside is that in some situations you may not easily change or update your C help.
4. Update Rust at night as your compiler and passes -Zwasm-c-abi=legacyTo. It mute the compiler warnings right now, but keep in mind that the help will change in the future and -Zwasm-c-abi=legacy The choice is completely removed. If -Zwasm-c-abi=legacy The choice is removed, the only option is the usual C help that -Zwasm-c-abi=spec Today promises.

If you have uncertainty, questions or difficulties, feel free to contact the future-income warning or Zulip tracking problem.

Help of change time scale

At this time, there is no exact schedule of how the help changes. It is expected to take 3-6 months and look like this:

• March 2025: (Soon) – The compiler will be added to the future warning to warn the projects if this aid change will affect them.
• 2025-05-15: This Warning for Future Demand will reach the stable rust channel as 1.87.0.
• 2025 Summer: (ISH) – -Zwasm-c-abi The flag is removed from the compiler and legacy The choice is completely removed.

Exactly when -Zwasm-c-abi The removed depends on the feedback of the community and whether the future-income warning triggers a lot. It is hoped that shortly after rust 1.87.0, it is stable that the behavior of the old heritage can be removed.

Credits: Alex Crichton

Published here too

Photo: Ross Findon on Unsplash