wit_bindgen/

lib.rs

//! Bindings generation support for Rust with the Component Model.
//!
//! This crate is a bindings generator for [WIT] and the [Component Model].
//! Users are likely interested in the [`generate!`] macro which actually
//! generates bindings. Otherwise this crate provides any runtime support
//! necessary for the macro-generated code.
//!
//! [WIT]: https://component-model.bytecodealliance.org/design/wit.html
//! [Component Model]: https://component-model.bytecodealliance.org/

#![no_std]

#[cfg(not(feature = "rustc-dep-of-std"))]
extern crate alloc;
#[cfg(feature = "std")]
extern crate std;

/// Generate bindings for an input WIT document.
///
/// This macro is the bread-and-butter of the `wit-bindgen` crate. The macro
/// here will parse [WIT] as input and generate Rust bindings to work with the
/// `world` that's specified in the [WIT]. For a primer on WIT see [this
/// documentation][WIT] and for a primer on worlds see [here][worlds].
///
/// [WIT]: https://component-model.bytecodealliance.org/design/wit.html
/// [worlds]: https://component-model.bytecodealliance.org/design/worlds.html
///
/// This macro takes as input a [WIT package] as well as a [`world`][worlds]
/// within that package. It will then generate a Rust function for all `import`s
/// into the world. If there are any `export`s then a Rust `trait` will be
/// generated for you to implement. The macro additionally takes a number of
/// configuration parameters documented below as well.
///
/// Basic invocation of the macro can look like:
///
/// ```
/// use wit_bindgen::generate;
/// # macro_rules! generate { ($($t:tt)*) => () }
///
/// generate!();
/// ```
///
/// This will parse a WIT package in the `wit` folder adjacent to your project's
/// `Cargo.toml` file. Within this WIT package there must be precisely one
/// `world` and that world will be the one that has bindings generated for it.
/// All other options remain at their default values (more on this below).
///
/// If your WIT package has more than one `world`, or if you want to select a
/// world from the dependencies, you can specify a world explicitly:
///
/// ```
/// use wit_bindgen::generate;
/// # macro_rules! generate { ($($t:tt)*) => () }
///
/// generate!("my-world");
/// generate!("wasi:cli/imports");
/// ```
///
/// This form of the macro takes a single string as an argument which is a
/// "world specifier" to select which world is being generated. As a single
/// string, such as `"my-world"`, this selects the world named `my-world` in the
/// package being parsed in the `wit` folder. The longer form specification
/// `"wasi:cli/imports"` indicates that the `wasi:cli` package, located in the
/// `wit/deps` folder, will have a world named `imports` and those bindings will
/// be generated.
///
/// If your WIT package is located in a different directory than one called
/// `wit` then it can be specified with the `in` keyword:
///
/// ```
/// use wit_bindgen::generate;
/// # macro_rules! generate { ($($t:tt)*) => () }
///
/// generate!(in "./my/other/path/to/wit");
/// generate!("a-world" in "../path/to/wit");
/// ```
///
/// The full-form of the macro, however, takes a braced structure which is a
/// "bag of options":
///
/// ```
/// use wit_bindgen::generate;
/// # macro_rules! generate { ($($t:tt)*) => () }
///
/// generate!({
///     world: "my-world",
///     path: "../path/to/wit",
///     // ...
/// });
/// ```
///
/// For documentation on each option, see below.
///
/// ## Exploring generated bindings
///
/// Once bindings have been generated they can be explored via a number of means
/// to see what was generated:
///
/// * Using `cargo doc` should render all of the generated bindings in addition
///   to the original comments in the WIT format itself.
/// * If your IDE supports `rust-analyzer` code completion should be available
///   to explore and see types.
/// * The `wit-bindgen` CLI tool, packaged as `wit-bindgen-cli` on crates.io,
///   can be executed the same as the `generate!` macro and the output can be
///   read.
/// * If you're seeing an error, `WIT_BINDGEN_DEBUG=1` can help debug what's
///   happening (more on this below) by emitting macro output to a file.
/// * This documentation can be consulted for various constructs as well.
///
/// Currently browsing generated code may have road bumps on the way. If you run
/// into issues or have idea of how to improve the situation please [file an
/// issue].
///
/// [file an issue]: https://github.com/bytecodealliance/wit-bindgen/issues/new
///
/// ## Namespacing
///
/// In WIT, worlds can import and export `interface`s, functions, and types. Each
/// `interface` can either be "anonymous" and only named within the context of a
/// `world` or it can have a "package ID" associated with it. Names in Rust take
/// into account all the names associated with a WIT `interface`. For example
/// the package ID `foo:bar/baz` would create a `mod foo` which contains a `mod
/// bar` which contains a `mod baz`.
///
/// WIT imports and exports are additionally separated into their own
/// namespaces. Imports are generated at the level of the `generate!` macro
/// where exports are generated under an `exports` namespace.
///
/// ## Imports
///
/// Imports into a `world` can be types, resources, functions, and interfaces.
/// Each of these is bound as a Rust type, function, or module. The intent is
/// that the WIT interfaces map to what is roughly idiomatic Rust for the given
/// interface.
///
/// ### Imports: Top-level functions and types
///
/// Imports at the top-level of a world are generated directly where the
/// `generate!` macro is invoked.
///
/// ```
/// use wit_bindgen::generate;
///
/// generate!({
///     inline: r"
///         package a:b;
///
///         world the-world {
///             record fahrenheit {
///                 degrees: f32,
///             }
///
///             import what-temperature-is-it: func() -> fahrenheit;
///
///             record celsius {
///                 degrees: f32,
///             }
///
///             import convert-to-celsius: func(a: fahrenheit) -> celsius;
///         }
///     ",
/// });
///
/// fn test() {
///     let current_temp = what_temperature_is_it();
///     println!("current temp in fahrenheit is {}", current_temp.degrees);
///     let in_celsius: Celsius = convert_to_celsius(current_temp);
///     println!("current temp in celsius is {}", in_celsius.degrees);
/// }
/// ```
///
/// ### Imports: Interfaces
///
/// Interfaces are placed into submodules where the `generate!` macro is
/// invoked and are namespaced based on their identifiers.
///
/// ```
/// use wit_bindgen::generate;
///
/// generate!({
///     inline: r"
///         package my:test;
///
///         interface logging {
///             enum level {
///                 debug,
///                 info,
///                 error,
///             }
///             log: func(level: level, msg: string);
///         }
///
///         world the-world {
///             import logging;
///             import global-logger: interface {
///                 use logging.{level};
///
///                 set-current-level: func(level: level);
///                 get-current-level: func() -> level;
///             }
///         }
///     ",
/// });
///
/// // `my` and `test` are from `package my:test;` and `logging` is for the
/// // interfac name.
/// use my::test::logging::Level;
///
/// fn test() {
///     let current_level = global_logger::get_current_level();
///     println!("current logging level is {current_level:?}");
///     global_logger::set_current_level(Level::Error);
///
///     my::test::logging::log(Level::Info, "Hello there!");
/// }
/// #
/// # fn main() {}
/// ```
///
/// ### Imports: Resources
///
/// Imported resources generate a type named after the name of the resource.
/// This type is then used both for borrows as `&T` as well as via ownership as
/// `T`. Resource methods are bound as methods on the type `T`.
///
/// ```
/// use wit_bindgen::generate;
///
/// generate!({
///     inline: r#"
///         package my:test;
///
///         interface logger {
///             enum level {
///                 debug,
///                 info,
///                 error,
///             }
///
///             resource logger {
///                 constructor(destination: string);
///                 log: func(level: level, msg: string);
///             }
///         }
///
///         // Note that while this world does not textually import the above
///         // `logger` interface it is a transitive dependency via the `use`
///         // statement so the "elaborated world" imports the logger.
///         world the-world {
///             use logger.{logger};
///
///             import get-global-logger: func() -> logger;
///         }
///     "#,
/// });
///
/// use my::test::logger::Level;
///
/// fn test() {
///     let logger = get_global_logger();
///     logger.log(Level::Debug, "This is a global message");
///
///     let logger2 = Logger::new("/tmp/other.log");
///     logger2.log(Level::Info, "This is not a global message");
/// }
/// #
/// # fn main() {}
/// ```
///
/// Note in the above example the lack of import of `Logger`. The `use`
/// statement imported the `Logger` type, an alias of it, from the `logger`
/// interface into `the-world`. This generated a Rust `type` alias so `Logger`
/// was available at the top-level.
///
/// ## Exports: Basic Usage
///
/// A WIT world can not only `import` functionality but can additionally
/// `export` functionality as well. An `export` represents a contract that the
/// Rust program must implement to be able to work correctly. The `generate!`
/// macro's goal is to take care of all the low-level and ABI details for you,
/// so the end result is that `generate!`, for exports, will generate Rust
/// `trait`s that you must implement.
///
/// A minimal example of this is:
///
/// ```
/// use wit_bindgen::generate;
///
/// generate!({
///     inline: r#"
///         package my:test;
///
///         world my-world {
///             export hello: func();
///         }
///     "#,
/// });
///
/// struct MyComponent;
///
/// impl Guest for MyComponent {
///     fn hello() {}
/// }
///
/// export!(MyComponent);
/// #
/// # fn main() {}
/// ```
///
/// Here the `Guest` trait was generated by the `generate!` macro and represents
/// the functions at the top-level of `my-world`, in this case the function
/// `hello`. A custom type, here called `MyComponent`, is created and the trait
/// is implemented for that type.
///
/// Additionally a macro is generated by `generate!` (macros generating macros)
/// called `export!`. The `export!` macro is given a component that implements
/// the export `trait`s and then it will itself generate all necessary
/// `#[unsafe(no_mangle)]` functions to implement the ABI required.
///
/// ## Exports: Multiple Interfaces
///
/// Each `interface` in WIT will generate a `trait` that must be implemented in
/// addition to the top-level `trait` for the world. All traits are named
/// `Guest` here and are namespaced appropriately in modules:
///
/// ```
/// use wit_bindgen::generate;
///
/// generate!({
///     inline: r#"
///         package my:test;
///
///         interface a {
///             func-in-a: func();
///             second-func-in-a: func();
///         }
///
///         world my-world {
///             export a;
///             export b: interface {
///                 func-in-b: func();
///             }
///             export c: func();
///         }
///     "#,
/// });
///
/// struct MyComponent;
///
/// impl Guest for MyComponent {
///     fn c() {}
/// }
///
/// impl exports::my::test::a::Guest for MyComponent {
///     fn func_in_a() {}
///     fn second_func_in_a() {}
/// }
///
/// impl exports::b::Guest for MyComponent {
///     fn func_in_b() {}
/// }
///
/// export!(MyComponent);
/// #
/// # fn main() {}
/// ```
///
/// Here note that there were three `Guest` traits generated for each of the
/// three groups: two interfaces and one `world`. Also note that traits (and
/// types) for exports are namespaced in an `exports` module.
///
/// Note that when the top-level `world` does not have any exported functions,
/// or if an interface does not have any functions, then no `trait` is
/// generated:
///
/// ```
/// use wit_bindgen::generate;
///
/// generate!({
///     inline: r#"
///         package my:test;
///
///         interface a {
///             type my-type = u32;
///         }
///
///         world my-world {
///             export b: interface {
///                 use a.{my-type};
///
///                 foo: func() -> my-type;
///             }
///         }
///     "#,
/// });
///
/// struct MyComponent;
///
/// impl exports::b::Guest for MyComponent {
///     fn foo() -> u32 {
///         42
///     }
/// }
///
/// export!(MyComponent);
/// #
/// # fn main() {}
/// ```
///
/// ## Exports: Resources
///
/// Exporting a resource is significantly different than importing a resource.
/// A component defining a resource can create new resources of that type at any
/// time, for example. Additionally resources can be "dereferenced" into their
/// underlying values within the component.
///
/// Owned resources have a custom type generated and borrowed resources are
/// generated with a type of the same name suffixed with `Borrow<'_>`, such as
/// `MyResource` and `MyResourceBorrow<'_>`.
///
/// Like `interface`s the methods and functions used with a `resource` are
/// packaged up into a `trait`.
///
/// Specifying a custom resource type is done with an associated type on the
/// corresponding trait for the resource's containing interface/world:
///
/// ```
/// use wit_bindgen::generate;
/// use std::cell::{RefCell, Cell};
///
/// generate!({
///     inline: r#"
///         package my:test;
///
///         interface logging {
///             enum level {
///                 debug,
///                 info,
///                 error,
///             }
///
///             resource logger {
///                 constructor(level: level);
///                 log: func(level: level, msg: string);
///                 level: func() -> level;
///                 set-level: func(level: level);
///             }
///         }
///
///         world my-world {
///             export logging;
///         }
///     "#,
/// });
///
/// use exports::my::test::logging::{Guest, GuestLogger, Level};
///
/// struct MyComponent;
///
/// // Note that the `logging` interface has no methods of its own but a trait
/// // is required to be implemented here to specify the type of `Logger`.
/// impl Guest for MyComponent {
///     type Logger = MyLogger;
/// }
///
/// struct MyLogger {
///     level: Cell<Level>,
///     contents: RefCell<String>,
/// }
///
/// impl GuestLogger for MyLogger {
///     fn new(level: Level) -> MyLogger {
///         MyLogger {
///             level: Cell::new(level),
///             contents: RefCell::new(String::new()),
///         }
///     }
///
///     fn log(&self, level: Level, msg: String) {
///         if level as u32 <= self.level.get() as u32 {
///             self.contents.borrow_mut().push_str(&msg);
///             self.contents.borrow_mut().push_str("\n");
///         }
///     }
///
///     fn level(&self) -> Level {
///         self.level.get()
///     }
///
///     fn set_level(&self, level: Level) {
///         self.level.set(level);
///     }
/// }
///
/// export!(MyComponent);
/// #
/// # fn main() {}
/// ```
///
/// It's important to note that resources in Rust do not get `&mut self` as
/// methods, but instead are required to be defined with `&self`. This requires
/// the use of interior mutability such as `Cell` and `RefCell` above from the
/// `std::cell` module.
///
/// ## Exports: The `export!` macro
///
/// Components are created by having exported WebAssembly functions with
/// specific names, and these functions are not created when `generate!` is
/// invoked. Instead these functions are created afterwards once you've defined
/// your own type an implemented the various `trait`s for it. The
/// `#[unsafe(no_mangle)]` functions that will become the component are created
/// with the generated `export!` macro.
///
/// Each call to `generate!` will itself generate a macro called `export!`.
/// The macro's first argument is the name of a type that implements the traits
/// generated:
///
/// ```
/// use wit_bindgen::generate;
///
/// generate!({
///     inline: r#"
///         package my:test;
///
///         world my-world {
/// #           export hello: func();
///             // ...
///         }
///     "#,
/// });
///
/// struct MyComponent;
///
/// impl Guest for MyComponent {
/// #   fn hello() {}
///     // ...
/// }
///
/// export!(MyComponent);
/// #
/// # fn main() {}
/// ```
///
/// This argument is a Rust type which implements the `Guest` traits generated
/// by `generate!`. Note that all `Guest` traits must be implemented for the
/// type provided or an error will be generated.
///
/// This macro additionally accepts a second argument. The macro itself needs to
/// be able to find the module where the `generate!` macro itself was originally
/// invoked. Currently that can't be done automatically so a path to where
/// `generate!` was provided can also be passed to the macro. By default, the
/// argument is set to `self`:
///
/// ```
/// use wit_bindgen::generate;
///
/// generate!({
///     // ...
/// #   inline: r#"
/// #       package my:test;
/// #
/// #       world my-world {
/// #           export hello: func();
/// #           // ...
/// #       }
/// #   "#,
/// });
/// #
/// # struct MyComponent;
/// #
/// # impl Guest for MyComponent {
/// #   fn hello() {}
/// #     // ...
/// # }
/// #
/// export!(MyComponent with_types_in self);
/// #
/// # fn main() {}
/// ```
///
/// This indicates that the current module, referred to with `self`, is the one
/// which had the `generate!` macro expanded.
///
/// If, however, the `generate!` macro was run in a different module then that
/// must be configured:
///
/// ```
/// mod bindings {
///     wit_bindgen::generate!({
///         // ...
/// #   inline: r#"
/// #       package my:test;
/// #
/// #       world my-world {
/// #           export hello: func();
/// #           // ...
/// #       }
/// #   "#,
///     });
/// }
/// #
/// # struct MyComponent;
/// #
/// # impl bindings::Guest for MyComponent {
/// #   fn hello() {}
/// #     // ...
/// # }
/// #
/// bindings::export!(MyComponent with_types_in bindings);
/// #
/// # fn main() {}
/// ```
///
/// ## Debugging output to `generate!`
///
/// While `wit-bindgen` is tested to the best of our ability there are
/// inevitably bugs and issues that arise. These can range from bad error
/// messages to misconfigured invocations to bugs in the macro itself. To assist
/// with debugging these situations the macro recognizes an environment
/// variable:
///
/// ```shell
/// export WIT_BINDGEN_DEBUG=1
/// ```
///
/// When set the macro will emit the result of expansion to a file and then
/// `include!` that file. Any error messages generated by `rustc` should then
/// point to the generated file and allow you to open it up, read it, and
/// inspect it. This can often provide better context to the error than rustc
/// provides by default with macros.
///
/// It is not recommended to set this environment variable by default as it will
/// cause excessive rebuilds of Cargo projects. It's recommended to only use it
/// as necessary to debug issues.
///
/// ## Options to `generate!`
///
/// The full list of options that can be passed to the `generate!` macro are as
/// follows. Note that there are no required options, they all have default
/// values.
///
///
/// ```
/// use wit_bindgen::generate;
/// # macro_rules! generate { ($($t:tt)*) => () }
///
/// generate!({
///     // The name of the world that bindings are being generated for. If this
///     // is not specified then it's required that the package selected
///     // below has a single `world` in it.
///     world: "my-world",
///
///     // Path to parse WIT and its dependencies from. Defaults to the `wit`
///     // folder adjacent to your `Cargo.toml`.
///     //
///     // This parameter also supports the form of a list, such as:
///     // ["../path/to/wit1", "../path/to/wit2"]
///     // Usually used in testing, our test suite may want to generate code
///     // from wit files located in multiple paths within a single mod, and we
///     // don't want to copy these files again. Currently these locations must
///     // be ordered, as later paths can't contain dependencies on earlier
///     // paths. This restriction may be lifted in the future.
///     path: "../path/to/wit",
///
///     // Enables passing "inline WIT". If specified this is the default
///     // package that a world is selected from. Any dependencies that this
///     // inline WIT refers to must be defined in the `path` option above.
///     //
///     // By default this is not specified.
///     inline: "
///         world my-world {
///             import wasi:cli/imports;
///
///             export my-run: func()
///         }
///     ",
///
///     // Additional traits to derive for all defined types. Note that not all
///     // types may be able to implement these traits, such as resources.
///     //
///     // By default this set is empty.
///     additional_derives: [PartialEq, Eq, Hash, Clone],
///
///     // When generating bindings for interfaces that are not defined in the
///     // same package as `world`, this option can be used to either generate
///     // those bindings or point to already generated bindings.
///     // For example, if your world refers to WASI types then the `wasi` crate
///     // already has generated bindings for all WASI types and structures. In this
///     // situation the key `with` here can be used to use those types
///     // elsewhere rather than regenerating types.
///     // If for example your world refers to some type and you want to use
///     // your own custom implementation of that type then you can specify
///     // that here as well. There is a requirement on the remapped (custom)
///     // type to have the same internal structure and identical to what would
///     // wit-bindgen generate (including alignment, etc.), since
///     // lifting/lowering uses its fields directly.
///     //
///     // If, however, your world refers to interfaces for which you don't have
///     // already generated bindings then you can use the special `generate` value
///     // to have those bindings generated.
///     //
///     // The `with` key here works for interfaces and individual types.
///     //
///     // When an interface or type is specified here no bindings will be
///     // generated at all. It's assumed bindings are fully generated
///     // somewhere else. This is an indicator that any further references to types
///     // defined in these interfaces should use the upstream paths specified
///     // here instead.
///     //
///     // Any unused keys in this map are considered an error.
///     with: {
///         "wasi:io/poll": wasi::io::poll,
///         "some:package/my-interface": generate,
///         "some:package/my-interface/my-type": my_crate::types::MyType,
///     },
///
///     // Indicates that all interfaces not present in `with` should be assumed
///     // to be marked with `generate`.
///     generate_all,
///
///     // An optional list of function names to skip generating bindings for.
///     // This is only applicable to imports and the name specified is the name
///     // of the function.
///     skip: ["foo", "bar", "baz"],
///
///     // Configuration of how Rust types are generated.
///     //
///     // This option will change how WIT types are mapped to Rust types. There
///     // are a number of ways this can be done depending on the context. For
///     // example a Rust `&str` is suitable to pass to an imported function but
///     // an exported function receives a `String`. These both represent the
///     // WIT type `string`, however.
///     //
///     // Type generation becomes extra-significant when aggregates come into
///     // play (such as a WIT `record` or `variant`), especially when the
///     // aggregate is used both in an imported function and exported one.
///     //
///     // There are three modes of ownership, documented here, but only one
///     // can be specified.
///     //
///     // The default mode is "Owning" meaning that all Rust types will by
///     // default contain their owned containers. For example a `record` with
///     // a `string` will map to a Rust `struct` containing a `String`. This
///     // maximizes the chance that types can be shared between imports and
///     // exports but can come at a cost where calling an import may require
///     // more allocations than necessary.
///     ownership: Owning,
///
///     // Specifies an alternative name for the `export!` macro generated for
///     // any exports this world has.
///     //
///     // Defaults to "export"
///     export_macro_name: "export",
///
///     // Indicates whether the `export!` macro is `pub` or just `pub(crate)`.
///     //
///     // This defaults to `false`.
///     pub_export_macro: false,
///
///     // The second mode of ownership is "Borrowing". This mode then
///     // additionally has a boolean flag indicating whether duplicate types
///     // should be generated if necessary.
///     //
///     // This mode will prefer using borrowed values in Rust to represent WIT
///     // values where possible. For example if the argument to an imported
///     // function is a record-with-a-string then in Rust that will generate a
///     // `struct` with a lifetime parameter storing `&'a str`.
///     //
///     // The `duplicate_if_necessary` flag will cause duplicate types to be
///     // generated when a WIT type is used both in an import and export. In
///     // this situation one will be called `FooParam` and one will be called
///     // `FooResult` (where `foo` is the WIT name).
///     //
///     // It's generally recommended to not turn this on unless performance
///     // requires it. Even if so, please feel free to open an issue on the
///     // `wit-bindgen` repository to help improve the default "Owning" use
///     // case above if possible.
///     ownership: Borrowing { duplicate_if_necessary: false },
///
///     // The generated `export!` macro, if any, will by default look for
///     // generated types adjacent to where the `export!` macro is invoked
///     // through the `self` module. This option can be used to change the
///     // defaults to look somewhere else instead.
///     default_bindings_module: "path::to::bindings",
///
///     // This will suffix the custom section containing component type
///     // information with the specified string. This is not required by
///     // default but if the same world is generated in two different locations
///     // in the crate then one bindings generation location will need this
///     // suffix to avoid having the custom sections corrupt each other.
///     type_section_suffix: "suffix",
///
///     // Configures the path to the `wit-bindgen` crate itself. By default
///     // this is `wit_bindgen` assuming that your crate depends on the
///     // `wit-bindgen` crate itself.
///     runtime_path: "path::to::wit_bindgen",
///
///     // Configure where the `bitflags` crate is located. By default this
///     // is `wit_bindgen::bitflags` which already reexports `bitflags` for
///     // you.
///     bitflags_path: "path::to::bitflags",
///
///     // Indicates that instead of `&str` and `String` the `&[u8]` and
///     // `Vec<u8>` types should be used. Only intended for cases where
///     // compiled size is of the utmost concern as this can avoid pulling in
///     // UTF-8 validation.
///     raw_strings,
///
///     // Emits `#[cfg(feature = "std")]` around `impl Error for ... {}` blocks
///     // for generated types. This is a niche option that is only here to
///     // support the standard library itself depending on this crate one day.
///     std_feature,
///
///     // Disable a workaround to force wasm constructors to be run only once
///     // when exported functions are called.
///     disable_run_ctors_once_workaround: false,
///
///     // Whether to generate unused `record`, `enum`, `variant` types.
///     // By default, they will not be generated unless they are used as input
///     // or return value of a function.
///     generate_unused_types: false,
///
///     // A list of "features" which correspond to WIT features to activate
///     // when parsing WIT files. This enables `@unstable` annotations showing
///     // up and having bindings generated for them.
///     //
///     // By default this is an empty list.
///     features: ["foo", "bar", "baz"],
///
///     // Disables generation of a `#[used]` static to try harder to get the
///     // custom section describing WIT types linked into the binary when
///     // used in library-like situations. This is `false` by default with
///     // `#[used]` statics being emitted.
///     disable_custom_section_link_helpers: false,
///
///     // Write generated code to a .rs file, which allows the compiler to
///     // emit more useful diagnostics for errors in the generated code.  This
///     // is primarily useful for `wit-bindgen` developers.
///     //
///     // This does the same thing as setting `WIT_BINDGEN_DEBUG=1`, except
///     // that it can be used on a more fine-grained basis (i.e. it only affects
///     // the specific `generate!` call where it is used.
///     debug: true,
///
///     // Generate async import and/or export bindings.
///     //
///     // The resulting bindings will use the component model
///     // [async ABI](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Async.md).
///     //
///     // If this option is not provided then the WIT's source annotation will
///     // be used instead.
///     async: true,    // all bindings are async
///     async: false,   // all bindings are sync
///     // With an array per-function configuration can be specified. A leading
///     // '-' will disable async for that particular function.
///     async: [
///         "wasi:http/types@0.3.0-draft#[static]body.finish",
///         "import:wasi:http/handler@0.3.0-draft#handle",
///         "-export:wasi:http/handler@0.3.0-draft#handle",
///         "all",
///     ],
/// });
/// ```
///
/// [WIT package]: https://component-model.bytecodealliance.org/design/packages.html
#[cfg(feature = "macros")]
pub use wit_bindgen_rust_macro::generate;

#[cfg(docsrs)]
pub mod examples;

#[doc(hidden)]
pub mod rt;

#[cfg(feature = "async")]
pub use rt::async_support::{
    backpressure_dec, backpressure_inc, backpressure_set, block_on, spawn, yield_async,
    yield_blocking, AbiBuffer, FutureRead, FutureReader, FutureWrite, FutureWriteCancel,
    FutureWriteError, FutureWriter, StreamRead, StreamReader, StreamResult, StreamWrite,
    StreamWriter,
};