Tracking issue for #[wasm_import_module]

[alexcrichton]

This is a tracking issue for the #[wasm_import_module] attribute and the wasm_import_module feature. This attribute is applied to extern { ... } blocks like so:

#[wasm_import_module = "foo"]
extern {
    fn foo();
    fn bar();
    // ...
}

The WebAssembly specification requires that all imported values from the host environment have a two-level namespace:

All imports include two opaque names: a module name and an import name, which are required to be valid UTF-8. The interpretation of these names is up to the host environment but designed to allow a host environments, like the Web, to support a two-level namespace.

Additionally only globals (like static variables), functions, memories, and tables can be imported. The extern { ... } language block is used to import globals and functions, memories and tables cannot currently be manually imported.

Each field of the wasm import needs to be configurable by Rust as both fields have semantic meaning. Typically the first field of the import is the "module" interpreted as an ES module, and the second field is what to import from that module.

Currently LLVM and LLD will default imports to the "env" module. This means that if you compile this code:

extern {
    fn foo();
}

it will generate a wasm file that imports the function "foo" from the module "env". By using #[wasm_import_module] we can customize what happens here:

#[wasm_import_module = "somewhere else"]
extern {
    fn foo();
}

This attribute must be of the form #[wasm_import_module = "string"], no other forms are accepted. It can only be attached to an extern block. All items in the block are considered to come from the same module. Through the usage of #[link_name] we can then configure both fields of WebAssembly imports arbitrarily:

#[wasm_import_module = "somewhere else"]
extern {
    #[link_name = "some_other_name"]
    fn foo();
}

The #[wasm_import_module] is accepted on non-wasm platforms but has no effect, it is simply an ignored attribute.

Helpful links:

• Implementation
• Test for a well-formed attribute
• Test that it is emitted correctly in the wasm file
• Test that it is currently unstable

Open questions and TODO

• Documentation in the reference
• Should the attribute instead be #[link(wasm_import_module = "...")]?

cc rustwasm/team#82

[alexcrichton]

The WebAssembly target doesn't actually have any concept of a single-level import, so in that sense this doesn't necessarily make sense in wasm:

extern {
    fn foo();
}

We're currently relying on LLVM's defacto behavior to set the import module as "env", but we could also specify it ourselves to do that. Additionally we could also forbid this at compile time and simply require that all extern blocks have a specified module. I would personally lean towards the latter of these interpretations.

[alexcrichton]

I'd like to propose that this feature be put up for stabilization but I'm not currently a member of the compiler team to do so, would someone from @rust-lang/compiler like to help me champion this issue and FCP it for stabilization?

Also cc @rust-lang/wg-wasm

[Mark-Simulacrum]

Is it well-defined for the attribute to have a space as in the tracking issue #[wasm_import_section = "somewhere else"]? That seems counter intuitive to me; I haven't looked, but if not we should have the compiler itself deny invalid identifiers there.

[alexcrichton]

The WebAssembly specification only has the requirement of "required to be valid UTF-8", and beyond that there is no restriction on what the import module can be. We wouldn't want to restrict it to only Rust identifiers because it's frequently an ES module path like ./foo or foo/bar or @foo/bar/baz.