feat(rust) add native link option

crates/core/src/lib.rs

@@ -16,6 +16,7 @@ mod async_;
 pub use async_::AsyncFilterSet;
 mod chainable_method;
 pub use chainable_method::{ChainableMethodFilterSet, ChainingMode};
+pub mod symbol_name;
 
 #[derive(Default, Copy, Clone, PartialEq, Eq, Debug)]
 pub enum Direction {

crates/cpp/src/symbol_name.rs → crates/core/src/symbol_name.rs

@@ -1,4 +1,4 @@
-use wit_bindgen_core::abi;
+use crate::abi;
 
 fn hexdigit(v: u32) -> char {
     if v < 10 {

crates/cpp/src/lib.rs

@@ -9,12 +9,13 @@ use std::{
     process::{Command, Stdio},
     str::FromStr,
 };
-use symbol_name::{make_external_component, make_external_symbol};
 use wit_bindgen_c::to_c_ident;
 use wit_bindgen_core::{
     Files, InterfaceGenerator, Source, Types, WorldGenerator,
     abi::{self, AbiVariant, Bindgen, Bitcast, LiftLower, WasmSignature, WasmType},
-    name_package_module, uwrite, uwriteln,
+    name_package_module,
+    symbol_name::{make_external_component, make_external_symbol},
+    uwrite, uwriteln,
     wit_parser::{
         Alignment, ArchitectureSize, Docs, Function, FunctionKind, Handle, Int, InterfaceId, Param,
         Resolve, SizeAlign, Stability, Type, TypeDef, TypeDefKind, TypeId, TypeOwner, WorldId,
@@ -24,7 +25,6 @@ use wit_bindgen_core::{
 use wit_parser::TypeIdVisitor;
 
 // mod wamr;
-mod symbol_name;
 
 pub const RESOURCE_IMPORT_BASE_CLASS_NAME: &str = "ResourceImportBase";
 pub const RESOURCE_EXPORT_BASE_CLASS_NAME: &str = "ResourceExportBase";

crates/guest-rust/src/lib.rs

@@ -894,6 +894,72 @@ extern crate std;
 /// });
 /// ```
 ///
+/// ## Native (non-WebAssembly) targets
+///
+/// Generated bindings also compile for native targets, which is useful for
+/// testing component code without a wasm runtime or for building it as a
+/// `cdylib` plugin. Native linkers don't accept the `:`, `/`, `#`, `[` and
+/// `]` characters that canonical ABI symbol names use, so on native targets
+/// symbols are hex-encoded with the scheme in
+/// `wit_bindgen_core::symbol_name` (the same one the C++ generator uses).
+///
+/// Imports are not resolved by the native linker. Each import calls through
+/// a function pointer that starts out null and is looked up on first use
+/// from a host-installed resolver: after loading the library a host calls
+/// the exported `__wit_bindgen_set_import_resolver` function with a callback
+/// that maps an import's core module and function names to a function
+/// pointer with the import's core signature. Its signature is
+///
+/// ```c
+/// void __wit_bindgen_set_import_resolver(
+///     void *(*resolver)(void *ctx, const char *import),
+///     void *ctx);
+/// ```
+///
+/// where `import` is the import's core module and function name joined by
+/// `#` as one NUL-terminated string, e.g. `my:pkg/[email protected]#[method]res.frob`
+/// (see `wit_bindgen::rt::ImportResolver`). Passing a null `resolver`
+/// uninstalls the current one.
+///
+/// This means everything links whether or not a host is present, the import
+/// shims define no global symbols at all, and a host only needs to implement
+/// the imports it cares about — calling an import the resolver doesn't
+/// provide aborts with a message naming it.
+///
+/// The resolver should be installed once, before any export is called: each
+/// import caches the pointer it was given, so a later
+/// `__wit_bindgen_set_import_resolver` call won't be seen by imports that
+/// have already been resolved. The resolver is also shared by every
+/// `generate!` invocation linked into the library and is keyed only by core
+/// module and function name, so two worlds importing the same core name
+/// necessarily get the same implementation.
+///
+/// Exports, including post-return functions, async callbacks, and resource
+/// destructors, are exported under their hex-encoded core export names. A
+/// `__wit_bindgen_cabi_realloc` function is also exported so hosts can
+/// allocate guest-owned memory when lowering arguments, as the canonical ABI
+/// requires. That symbol and `__wit_bindgen_set_import_resolver` are defined
+/// once in the `wit-bindgen` runtime crate rather than per world.
+///
+/// Each world additionally exports a marker function
+/// `const char *__wit_bindgen_world_<world>(void)`, where `<world>` is the
+/// hex-encoded fully qualified world name including its package version and
+/// `type_section_suffix`, e.g. `my:[email protected]/my-world`. Since `dlsym` can't
+/// tell a host whether the library it opened implements the world it expects
+/// — and the canonical ABI lowering of a world changes with the world, so
+/// guessing wrong corrupts memory instead of failing cleanly — a host should
+/// look this symbol up before installing a resolver or calling an export, and
+/// treat a missing symbol as the wrong plugin. Calling it returns the world
+/// name as a NUL-terminated string, for the resulting error message.
+///
+/// This marker is keyed the same way as the `component-type` custom section a
+/// wasm build emits, so the rules are the ones a wasm build already imposes.
+/// Binding the same world twice needs a `type_section_suffix` to tell the
+/// markers apart (plus `export_prefix` for the core export names). Two
+/// *different* worlds sharing one fully qualified name is not a supported
+/// configuration at all: here the linker rejects the duplicate marker, and on
+/// wasm `wit-component` refuses to merge the two packages.
+///
 /// [WIT package]: https://component-model.bytecodealliance.org/design/packages.html
 #[cfg(feature = "macros")]
 pub use wit_bindgen_rust_macro::generate;

crates/guest-rust/src/rt/mod.rs

@@ -153,7 +153,7 @@ pub fn maybe_link_cabi_realloc() {
 /// `cabi_realloc` module above. It's otherwise never explicitly called.
 ///
 /// For more information about this see `./ci/rebuild-libwit-bindgen-cabi.sh`.
-#[cfg(any(target_env = "p1", target_env = ""))]
+#[cfg(any(target_env = "p1", target_env = "", not(target_arch = "wasm32")))]
 pub unsafe fn cabi_realloc(
     old_ptr: *mut u8,
     old_len: usize,
@@ -192,6 +192,105 @@ pub unsafe fn cabi_realloc(
     return ptr;
 }
 
+/// Native (non-wasm) import resolution.
+///
+/// On native targets imports aren't resolved by the linker. Each generated
+/// import shim instead asks a host-installed resolver for its implementation
+/// the first time it's called, identifying the import by its core module and
+/// function name as plain strings. The host installs the resolver once per
+/// loaded library through `__wit_bindgen_set_import_resolver`, so the import
+/// shims define no global symbols at all and any number of `generate!`
+/// invocations can share one resolver. (Export symbols and world markers are
+/// a separate matter: those are global, so binding the same world twice in
+/// one binary needs `export_prefix` and `type_section_suffix` respectively to
+/// avoid duplicate symbols.)
+///
+/// Because each shim caches the pointer the resolver handed it, installing a
+/// resolver a second time has no effect on imports that have already been
+/// called. Hosts are expected to install one before calling any export.
+#[cfg(not(target_arch = "wasm32"))]
+mod native_imports {
+    use core::ffi::{CStr, c_char};
+    use core::sync::atomic::{AtomicPtr, Ordering};
+
+    /// A host-provided callback returning the implementation of the import
+    /// named by `import`, or null if the host doesn't implement it. The
+    /// returned pointer must be a function with the import's core signature.
+    /// `ctx` is the value passed alongside the resolver, returned to the host
+    /// on every call.
+    ///
+    /// `import` is the import's canonical ABI core module and function name
+    /// joined by `#`, as a single NUL-terminated string — for example
+    /// `my:pkg/[email protected]#[method]res.frob`, or `$root#some-func` for a
+    /// function imported at the top level of a world. (Note the package
+    /// version trails the interface name here, unlike in a world name.) It
+    /// points into the guest's static data and stays valid for as long as the
+    /// library is loaded, so a host may use it as a lookup key without
+    /// copying it.
+    pub type ImportResolver = unsafe extern "C" fn(ctx: *mut (), import: *const c_char) -> *mut ();
+
+    static RESOLVER: AtomicPtr<()> = AtomicPtr::new(core::ptr::null_mut());
+    static RESOLVER_CTX: AtomicPtr<()> = AtomicPtr::new(core::ptr::null_mut());
+
+    /// Installs the import resolver for this linkage unit. Hosts call this
+    /// (typically via `dlsym`) after loading the library and before calling
+    /// any export.
+    ///
+    /// Passing `None` for `resolver` uninstalls the current one. That only
+    /// affects imports which haven't been resolved yet; imports already
+    /// called keep the pointer they cached.
+    #[unsafe(no_mangle)]
+    pub unsafe extern "C" fn __wit_bindgen_set_import_resolver(
+        resolver: Option<ImportResolver>,
+        ctx: *mut (),
+    ) {
+        let resolver = match resolver {
+            Some(resolver) => resolver as *mut (),
+            None => core::ptr::null_mut(),
+        };
+        RESOLVER_CTX.store(ctx, Ordering::Relaxed);
+        // The release store of the resolver publishes the context above.
+        RESOLVER.store(resolver, Ordering::Release);
+    }
+
+    /// Called by generated import shims on their first invocation.
+    ///
+    /// `import` is the `module#name` string described on [`ImportResolver`].
+    pub fn resolve_import(import: &CStr) -> *mut () {
+        let display = import.to_str().unwrap_or("<invalid utf-8>");
+        let resolver = RESOLVER.load(Ordering::Acquire);
+        assert!(
+            !resolver.is_null(),
+            "import `{display}` was called before the host installed an \
+             import resolver via `__wit_bindgen_set_import_resolver`"
+        );
+        let ctx = RESOLVER_CTX.load(Ordering::Relaxed);
+        let resolver: ImportResolver = unsafe { core::mem::transmute(resolver) };
+        let ptr = unsafe { resolver(ctx, import.as_ptr()) };
+        assert!(
+            !ptr.is_null(),
+            "the host's import resolver provided no implementation for \
+             import `{display}`"
+        );
+        ptr
+    }
+
+    /// The guest allocator, exported so hosts can allocate guest-owned
+    /// memory when lowering data, as the canonical ABI requires.
+    #[unsafe(no_mangle)]
+    pub unsafe extern "C" fn __wit_bindgen_cabi_realloc(
+        old_ptr: *mut u8,
+        old_len: usize,
+        align: usize,
+        new_len: usize,
+    ) -> *mut u8 {
+        unsafe { crate::rt::cabi_realloc(old_ptr, old_len, align, new_len) }
+    }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+pub use native_imports::{ImportResolver, resolve_import};
+
 /// Provide a hook for generated export functions to run static constructors at
 /// most once.
 ///

crates/rust/src/bindgen.rs

@@ -67,6 +67,7 @@ impl<'a, 'b> FunctionBindgen<'a, 'b> {
             &rust_name,
             params,
             results,
+            self.r#gen.r#gen.runtime_path(),
         ));
         rust_name
     }

crates/rust/src/interface.rs

@@ -12,7 +12,7 @@ use std::fmt::Write as _;
 use std::mem;
 use wit_bindgen_core::abi::{self, AbiVariant, LiftLower};
 use wit_bindgen_core::{
-    AnonymousTypeGenerator, ChainingMode, Source, TypeInfo, dealias, uwrite, uwriteln,
+    AnonymousTypeGenerator, ChainingMode, Source, TypeInfo, dealias, symbol_name, uwrite, uwriteln,
     wit_parser::*,
 };
 
@@ -218,13 +218,15 @@ impl<'i> InterfaceGenerator<'i> {
                 "new",
                 &[abi::WasmType::Pointer],
                 &[abi::WasmType::I32],
+                self.r#gen.runtime_path(),
             );
             let import_rep = crate::declare_import(
                 &wasm_import_module,
                 &format!("[resource-rep]{resource_name}"),
                 "rep",
                 &[abi::WasmType::I32],
                 &[abi::WasmType::Pointer],
+                self.r#gen.runtime_path(),
             );
             uwriteln!(
                 self.src,
@@ -353,7 +355,6 @@ macro_rules! {macro_name} {{
             };
             self.generate_raw_cabi_export(func, &ty, "$($path_to_types)*", async_);
         }
-        let export_prefix = self.r#gen.opts.export_prefix.as_deref().unwrap_or("");
         for name in resources_to_drop {
             let module = match self.identifier {
                 Identifier::Interface(_, key) => self.resolve.name_world_key(key),
@@ -362,13 +363,13 @@ macro_rules! {macro_name} {{
                 }
             };
             let camel = name.to_upper_camel_case();
+            let attrs = self.core_export_attrs(&format!("{module}#[dtor]{name}"));
             uwriteln!(
                 self.src,
                 r#"
                 const _: () = {{
                     #[doc(hidden)]
-                    #[unsafe(export_name = "{export_prefix}{module}#[dtor]{name}")]
-                    #[allow(non_snake_case)]
+                    {attrs}#[allow(non_snake_case)]
                     unsafe extern "C" fn dtor(rep: *mut u8) {{
                         unsafe {{
                             $($path_to_types)*::{camel}::dtor::<
@@ -1036,6 +1037,7 @@ fn abi_layout(&mut self) -> ::core::alloc::Layout {{
             "call",
             &sig.params,
             &sig.results,
+            self.r#gen.runtime_path(),
         );
         let mut args = String::new();
         for i in 0..params_lower.len() {
@@ -1298,21 +1300,20 @@ unsafe fn call_import(&mut self, _params: Self::ParamsLower, _results: *mut u8)
             Identifier::World(_) => None,
             Identifier::StreamOrFuturePayload => unreachable!(),
         };
-        let export_prefix = self.r#gen.opts.export_prefix.as_deref().unwrap_or("");
         let export_name = func.legacy_core_export_name(wasm_module_export_name.as_deref());
         let export_name = if async_ {
             format!("[async-lift]{export_name}")
         } else {
             export_name.to_string()
         };
+
+        let attrs = self.core_export_attrs(&export_name);
         uwrite!(
             self.src,
             "\
-                #[unsafe(export_name = \"{export_prefix}{export_name}\")]
-                unsafe extern \"C\" fn export_{name_snake}\
+                {attrs}unsafe extern \"C\" fn export_{name_snake}\
 ",
         );
-
         let params = self.print_export_sig(func, async_);
         self.push_str(" {\n");
         uwriteln!(
@@ -1322,25 +1323,24 @@ unsafe fn call_import(&mut self, _params: Self::ParamsLower, _results: *mut u8)
         );
         self.push_str("}\n");
 
-        let export_prefix = self.r#gen.opts.export_prefix.as_deref().unwrap_or("");
         if async_ {
+            let attrs = self.core_export_attrs(&format!("[callback]{export_name}"));
             uwrite!(
                 self.src,
                 "\
-                    #[unsafe(export_name = \"{export_prefix}[callback]{export_name}\")]
-                    unsafe extern \"C\" fn _callback_{name_snake}(event0: u32, event1: u32, event2: u32) -> u32 {{
+                    {attrs}unsafe extern \"C\" fn _callback_{name_snake}(event0: u32, event1: u32, event2: u32) -> u32 {{
                         unsafe {{
                             {path_to_self}::__callback_{name_snake}(event0, event1, event2)
                         }}
                     }}
                 "
             );
         } else if abi::guest_export_needs_post_return(self.resolve, func) {
+            let attrs = self.core_export_attrs(&format!("cabi_post_{export_name}"));
             uwrite!(
                 self.src,
                 "\
-                    #[unsafe(export_name = \"{export_prefix}cabi_post_{export_name}\")]
-                    unsafe extern \"C\" fn _post_return_{name_snake}\
+                    {attrs}unsafe extern \"C\" fn _post_return_{name_snake}\
 "
             );
             let params = self.print_post_return_sig(func);
@@ -1354,6 +1354,24 @@ unsafe fn call_import(&mut self, _params: Self::ParamsLower, _results: *mut u8)
         }
     }
 
+    /// Returns the `export_name` attributes for a core export named
+    /// `export_name`.
+    ///
+    /// Has to exist due to the fact that native names cannot contain
+    /// special characters that wasm32 can like '/'.
+    ///
+    /// `cfg_attr` conditions are mutually exclusive, so exactly one attribute
+    /// applies on any target (for names that survive encoding unchanged, such
+    /// as `$root` exports, both carry the same string).
+    fn core_export_attrs(&self, export_name: &str) -> String {
+        let prefix = self.r#gen.opts.export_prefix.as_deref().unwrap_or("");
+        let native = symbol_name::make_external_component(export_name);
+        format!(
+            "#[cfg_attr(target_arch = \"wasm32\", unsafe(export_name = \"{prefix}{export_name}\"))]\n\
+             #[cfg_attr(not(target_arch = \"wasm32\"), unsafe(export_name = \"{prefix}{native}\"))]\n"
+        )
+    }
+
     fn print_export_sig(&mut self, func: &Function, async_: bool) -> Vec<String> {
         self.src.push_str("(");
         let variant = if async_ {
@@ -2987,6 +3005,7 @@ impl<'a> {camel}Borrow<'a>{{
             "drop",
             &[abi::WasmType::I32],
             &[],
+            self.r#gen.runtime_path(),
         );
         uwriteln!(
             self.src,