Conventions for namespaces generated by macros

[NewGyu]

Hello developers, I'm one of cargo-component funs.

I have a question about the namespace conventions for bindings generated by cargo_component_bindings::generate!() macro. The namespaces of the bindings generated in the two cases below are different. What are the generation rules? I especially concerned about the lack of exports in the namespace for Guest trait in case1.

Case0

package component:case0;

interface random {
    enum algorithm {
        goblin,
        orge
    }

    record seed {
        value: u32,
        algorithm: algorithm
    }

    rand: func(seed: seed) -> u32;
}

world random-generator {
    export random;
}                

Generated bindings.

use bindings::exports::component::case0::random::{
    Algorithm, Guest, Seed
};

• In this case, the world exports the entire ramdom interface.
• All bindings are under "bindings::exports::${package name}::${interface name}::".

Case1

WIT file.

package component:case1;

interface random {
    enum algorithm {
        goblin,
        orge
    }

    record seed {
        value: u32,
        algorithm: algorithm
    }
}

world random-generator {
    use random.{seed};

    export rand: func(seed: seed) -> u32;
}                

Generated bindings.

use bindings::Guest;
use bindings::component::case1::random::{Algorithm, Seed};

• In this case, the world exports only rand function. And the world uses Seed type the function depends on.
• Bindings are...
  • Guest trait is under binding:: namespace.
  • Types are under "bindings::${package name}::${interface name}::".
    • exports is not contained in the namespace.

[peterhuene]

Hi @NewGyu, thanks for the question!

This is a convention that comes from the wit-bindgen crate; the only difference is that cargo_component_bindings::generate! puts all of the bindings into a bindings module rather than where the macro is invoked.

Functions that are directly exported from the world are represented with a "top-level" Guest trait (i.e. bindings::Guest).

Interfaces exported from the world go in the bindings::exports module, where each sub-module is for an interface that is exported (e.g. bindings::exports::component::case0::random).

The exports module differentiates from an import of an interface in the world (e.g. bindings::component::case1::random; in that example, it's imported because of the use).

[NewGyu]

Hello @peterhuene, thank you for the detailed explanation. That was very helpful.

[NewGyu]

Functions that are directly exported from the world are represented with a "top-level" Guest trait (i.e. bindings::Guest).

Just my personal opinion, I think the namespace of the Guest trait should be unified to start with bindings::exports:: even if the world exports "top-level" function.