1 //! # Embedding API for the Component Model
2 //!
3 //! This module contains the embedding API for the [Component Model] in
4 //! Wasmtime. This module requires the `component-model` feature to be enabled,
5 //! which is enabled by default. The embedding API here is mirrored after the
6 //! core wasm embedding API at the crate root and is intended to have the same
7 //! look-and-feel while handling concepts of the component model.
8 //!
9 //! [Component Model]: https://component-model.bytecodealliance.org
10 //!
11 //! The component model is a broad topic which can't be explained here fully, so
12 //! it's recommended to read over individual items' documentation to see more
13 //! about the capabilities of the embedding API. At a high-level, however,
14 //! perhaps the most interesting items in this module are:
15 //!
16 //! * [`Component`] - a compiled component ready to be instantiated. Similar to
17 //!   a [`Module`](crate::Module) for core wasm.
18 //!
19 //! * [`Linker`] - a component-style location for defining host functions. This
20 //!   is not the same as [`wasmtime::Linker`](crate::Linker) for core wasm
21 //!   modules.
22 //!
23 //! * [`bindgen!`] - a macro to generate Rust bindings for a [WIT] [world]. This
24 //!   maps all WIT types into Rust automatically and generates traits for
25 //!   embedders to implement.
26 //!
27 //! [WIT]: https://component-model.bytecodealliance.org/design/wit.html
28 //! [world]: https://component-model.bytecodealliance.org/design/worlds.html
29 //!
30 //! Embedders of the component model will typically start by defining their API
31 //! in [WIT]. This describes what will be available to guests and what needs to
32 //! be provided to the embedder by the guest. This [`world`][world] that was
33 //! created is then fed into [`bindgen!`] to generate types and traits for the
34 //! embedder to use. The embedder then implements these traits, adds
35 //! functionality via the generated `add_to_linker` method (see [`bindgen!`] for
36 //! more info), and then instantiates/executes a component.
37 //!
38 //! It's recommended to read over the [documentation for the Component
39 //! Model][Component Model] to get an overview about how to build components
40 //! from various languages.
41 //!
42 //! ## Example Usage
43 //!
44 //! Imagine you have the following WIT package definition in a file called world.wit
45 //! along with a component (my_component.wasm) that targets `my-world`:
46 //!
47 //! ```text,ignore
48 //! package component:my-package;
49 //!
50 //! world my-world {
51 //!     import name: func() -> string;
52 //!     export greet: func() -> string;
53 //! }
54 //! ```
55 //!
56 //! You can instantiate and call the component like so:
57 //!
58 //! ```
59 //! fn main() -> wasmtime::Result<()> {
60 //!     #   if true { return Ok(()) }
61 //!     // Instantiate the engine and store
62 //!     let engine = wasmtime::Engine::default();
63 //!     let mut store = wasmtime::Store::new(&engine, ());
64 //!
65 //!     // Load the component from disk
66 //!     let bytes = std::fs::read("my_component.wasm")?;
67 //!     let component = wasmtime::component::Component::new(&engine, bytes)?;
68 //!
69 //!     // Configure the linker
70 //!     let mut linker = wasmtime::component::Linker::new(&engine);
71 //!     // The component expects one import `name` that
72 //!     // takes no params and returns a string
73 //!     linker
74 //!         .root()
75 //!         .func_wrap("name", |_store, _params: ()| {
76 //!             Ok((String::from("Alice"),))
77 //!         })?;
78 //!
79 //!     // Instantiate the component
80 //!     let instance = linker.instantiate(&mut store, &component)?;
81 //!
82 //!     // Call the `greet` function
83 //!     let func = instance.get_func(&mut store, "greet").expect("greet export not found");
84 //!     let mut result = [wasmtime::component::Val::String("".into())];
85 //!     func.call(&mut store, &[], &mut result)?;
86 //!
87 //!     // This should print out `Greeting: [String("Hello, Alice!")]`
88 //!     println!("Greeting: {:?}", result);
89 //!
90 //!     Ok(())
91 //! }
92 //! ```
93 //!
94 //! Manually configuring the linker and calling untyped component exports is
95 //! a bit tedious and error prone. The [`bindgen!`] macro can be used to
96 //! generate bindings eliminating much of this boilerplate.
97 //!
98 //! See the docs for [`bindgen!`] for more information on how to use it.
99 
100 #![allow(
101     rustdoc::redundant_explicit_links,
102     reason = "rustdoc appears to lie about a warning above, so squelch it for now"
103 )]
104 
105 mod component;
106 #[cfg(feature = "component-model-async")]
107 pub(crate) mod concurrent;
108 mod func;
109 mod has_data;
110 mod instance;
111 mod linker;
112 mod matching;
113 mod resource_table;
114 mod resources;
115 mod storage;
116 pub(crate) mod store;
117 pub mod types;
118 mod values;
119 pub use self::component::{Component, ComponentExportIndex};
120 #[cfg(feature = "component-model-async")]
121 pub use self::concurrent::{
122     Access, Accessor, AccessorTask, AsAccessor, ErrorContext, FutureReader, FutureWriter,
123     GuardedFutureReader, GuardedFutureWriter, GuardedStreamReader, GuardedStreamWriter, JoinHandle,
124     ReadBuffer, StreamReader, StreamWriter, VMComponentAsyncStore, VecBuffer, WriteBuffer,
125 };
126 pub use self::func::{
127     ComponentNamedList, ComponentType, Func, Lift, Lower, TypedFunc, WasmList, WasmStr,
128 };
129 pub use self::has_data::*;
130 pub use self::instance::{Instance, InstanceExportLookup, InstancePre};
131 pub use self::linker::{Linker, LinkerInstance};
132 pub use self::resource_table::{ResourceTable, ResourceTableError};
133 pub use self::resources::{Resource, ResourceAny};
134 pub use self::types::{ResourceType, Type};
135 pub use self::values::Val;
136 
137 pub(crate) use self::instance::RuntimeImport;
138 pub(crate) use self::resources::HostResourceData;
139 pub(crate) use self::store::ComponentInstanceId;
140 
141 // Re-export wasm_wave crate so the compatible version of this dep doesn't have to be
142 // tracked separately from wasmtime.
143 #[cfg(feature = "wave")]
144 pub use wasm_wave;
145 
146 // These items are used by `#[derive(ComponentType, Lift, Lower)]`, but they are not part of
147 // Wasmtime's API stability guarantees
148 #[doc(hidden)]
149 pub mod __internal {
150     pub use super::func::{
151         ComponentVariant, LiftContext, LowerContext, Options, bad_type_info, format_flags,
152         lower_payload, typecheck_enum, typecheck_flags, typecheck_record, typecheck_variant,
153     };
154     pub use super::matching::InstanceType;
155     pub use crate::MaybeUninitExt;
156     pub use crate::map_maybe_uninit;
157     pub use crate::store::StoreOpaque;
158     pub use alloc::boxed::Box;
159     pub use alloc::string::String;
160     pub use alloc::vec::Vec;
161     pub use anyhow;
162     pub use core::cell::RefCell;
163     pub use core::future::Future;
164     pub use core::mem::transmute;
165     pub use wasmtime_environ;
166     pub use wasmtime_environ::component::{CanonicalAbiInfo, ComponentTypes, InterfaceType};
167 }
168 
169 pub(crate) use self::store::ComponentStoreData;
170 
171 /// Generate bindings for a [WIT world].
172 ///
173 /// [WIT world]: https://component-model.bytecodealliance.org/design/worlds.html
174 /// [WIT package]: https://component-model.bytecodealliance.org/design/packages.html
175 ///
176 /// This macro ingests a [WIT world] and will generate all the necessary
177 /// bindings for instantiating components that ascribe to the `world`. This
178 /// provides a higher-level representation of working with a component than the
179 /// raw [`Instance`] type which must be manually-type-checked and manually have
180 /// its imports provided via the [`Linker`] type.
181 ///
182 /// # Examples
183 ///
184 /// Examples for this macro can be found in the [`bindgen_examples`] module
185 /// documentation. That module has a submodule-per-example which includes the
186 /// source code, with WIT, used to generate the structures along with the
187 /// generated code itself in documentation.
188 ///
189 /// # Debugging and Exploring
190 ///
191 /// If you need to debug the output of `bindgen!` you can try using the
192 /// `WASMTIME_DEBUG_BINDGEN=1` environment variable. This will write the
193 /// generated code to a file on disk so rustc can produce better error messages
194 /// against the actual generated source instead of the macro invocation itself.
195 /// This additionally can enable opening up the generated code in an editor and
196 /// exploring it (through an error message).
197 ///
198 /// The generated bindings can additionally be explored with `cargo doc` to see
199 /// what's generated. It's also recommended to browse the [`bindgen_examples`]
200 /// for example generated structures and example generated code.
201 ///
202 /// # Syntax
203 ///
204 /// This procedural macro accepts a few different syntaxes. The primary purpose
205 /// of this macro is to locate a WIT package, parse it, and then extract a
206 /// `world` from the parsed package. There are then codegen-specific options to
207 /// the bindings themselves which can additionally be specified.
208 ///
209 /// Usage of this macro looks like:
210 ///
211 /// ```rust
212 /// # macro_rules! bindgen { ($($t:tt)*) => () }
213 /// // Parse the `wit/` folder adjacent to this crate's `Cargo.toml` and look
214 /// // for a single `world` in it. There must be exactly one for this to
215 /// // succeed.
216 /// bindgen!();
217 ///
218 /// // Parse the `wit/` folder adjacent to this crate's `Cargo.toml` and look
219 /// // for the world `foo` contained in it.
220 /// bindgen!("foo");
221 ///
222 /// // Parse the folder `other/wit/folder` adjacent to `Cargo.toml`.
223 /// bindgen!(in "other/wit/folder");
224 /// bindgen!("foo" in "other/wit/folder");
225 ///
226 /// // Parse the file `foo.wit` as a single-file WIT package with no
227 /// // dependencies.
228 /// bindgen!("foo" in "foo.wit");
229 ///
230 /// // Specify a suite of options to the bindings generation, documented below
231 /// bindgen!({
232 ///     world: "foo",
233 ///     path: "other/path/to/wit",
234 ///     // ...
235 /// });
236 /// ```
237 ///
238 /// # Options Reference
239 ///
240 /// This is an example listing of all options that this macro supports along
241 /// with documentation for each option and example syntax for each option.
242 ///
243 /// ```rust
244 /// # macro_rules! bindgen { ($($t:tt)*) => () }
245 /// bindgen!({
246 ///     world: "foo", // not needed if `path` has one `world`
247 ///
248 ///     // same as in `bindgen!(in "other/wit/folder")
249 ///     path: "other/wit/folder",
250 ///
251 ///     // Instead of `path` the WIT document can be provided inline if
252 ///     // desired.
253 ///     inline: "
254 ///         package my:inline;
255 ///
256 ///         world foo {
257 ///             // ...
258 ///         }
259 ///     ",
260 ///
261 ///     // Further configuration of imported functions. This can be used to add
262 ///     // functionality per-function or by default for all imports. Note that
263 ///     // exports are also supported via the `exports` key below.
264 ///     //
265 ///     // Functions in this list are specified as their interface first then
266 ///     // the raw wasm name of the function. Interface versions can be
267 ///     // optionally omitted and prefixes are also supported to configure
268 ///     // entire interfaces at once for example. Only the first matching item
269 ///     // in this list is used to configure a function.
270 ///     //
271 ///     // Configuration for a function is a set of flags which can be added
272 ///     // per-function. Each flag's meaning is documented below and the final
273 ///     // set of flags for a function are calculated by the first matching
274 ///     // rule below unioned with the default flags inferred from the WIT
275 ///     // signature itself (unless below configures the `ignore_wit` flag).
276 ///     //
277 ///     // Specifically the defaults for a normal WIT function are empty,
278 ///     // meaning all flags below are disabled. For a WIT `async` function the
279 ///     // `async | store` flags are enabled by default, but all others are
280 ///     // still disabled.
281 ///     //
282 ///     // Note that unused keys in this map are a compile-time error. All
283 ///     // keys are required to be used and consulted.
284 ///     imports: {
285 ///         // The `async` flag is used to indicate that a Rust-level `async`
286 ///         // function is used on the host. This means that the host is allowed
287 ///         // to do async I/O. Note though that to WebAssembly itself the
288 ///         // function will still be blocking. This requires
289 ///         // `Config::async_support` to be `true` as well.
290 ///         "wasi:io/poll/poll": async,
291 ///
292 ///         // The `store` flag means that the host function will have access
293 ///         // to the store during its execution. By default host functions take
294 ///         // `&mut self` which only has access to the data in question
295 ///         // implementing the generated traits from `bindgen!`. This
296 ///         // configuration means that in addition to `Self` the entire store
297 ///         // will be accessible if necessary.
298 ///         //
299 ///         // Functions that have access to a `store` are generated in a
300 ///         // `HostWithStore` trait. Functions without a `store` are generated
301 ///         // in a `Host` trait.
302 ///         //
303 ///         // > Note: this is not yet implemented for non-async functions. This
304 ///         // > will result in bindgen errors right now and is intended to be
305 ///         // > implemented in the near future.
306 ///         "wasi:clocks/monotonic-clock/now": store,
307 ///
308 ///         // This is an example of combining flags where the `async` and
309 ///         // `store` flags are combined. This means that the generated
310 ///         // host function is both `async` and additionally has access to
311 ///         // the `store`. Note though that this configuration is not necessary
312 ///         // as the WIT function is itself already marked as `async`. That
313 ///         // means that this is the default already applied meaning that
314 ///         // specifying it here would be redundant.
315 ///         //
316 ///         // "wasi:clocks/monotonic-clock/[async]wait-until": async | store,
317 ///
318 ///         // The `tracing` flag indicates that `tracing!` will be used to log
319 ///         // entries and exits into this host API. This can assist with
320 ///         // debugging or just generally be used to provide logs for the host.
321 ///         //
322 ///         // By default values are traced unless they contain lists, but
323 ///         // tracing of lists can be enabled with `verbose_tracing` below.
324 ///         "my:local/api/foo": tracing,
325 ///
326 ///         // The `verbose_tracing` flag indicates that when combined with
327 ///         // `tracing` the values of parameters/results are added to logs.
328 ///         // This may include lists which may be very large.
329 ///         "my:local/api/other-function": tracing | verbose_tracing,
330 ///
331 ///         // The `trappable` flag indicates that this import is allowed to
332 ///         // generate a trap.
333 ///         //
334 ///         // Imports that may trap have their return types wrapped in
335 ///         // `wasmtime::Result<T>` where the `Err` variant indicates that a
336 ///         // trap will be raised in the guest.
337 ///         //
338 ///         // By default imports cannot trap and the return value is the return
339 ///         // value from the WIT bindings itself.
340 ///         //
341 ///         // Note that the `trappable` configuration can be combined with the
342 ///         // `trappable_error_type` configuration below to avoid having a
343 ///         // host function return `wasmtime::Result<Result<WitOk, WitErr>>`
344 ///         // for example and instead return `Result<WitOk, RustErrorType>`.
345 ///         "my:local/api/fallible": trappable,
346 ///
347 ///         // The `ignore_wit` flag discards the WIT-level defaults of a
348 ///         // function. For example this `async` WIT function will be ignored
349 ///         // and a synchronous function will be generated on the host.
350 ///         "my:local/api/[async]wait": ignore_wit,
351 ///
352 ///         // The `exact` flag ensures that the filter, here "f", only matches
353 ///         // functions exactly. For example "f" here would only refer to
354 ///         // `import f: func()` in a world. Without this flag then "f"
355 ///         // would also configure any package `f:*/*/*` for example.
356 ///         "f": exact,
357 ///
358 ///         // This is used to configure the defaults of all functions if no
359 ///         // other key above matches a function. Note that if specific
360 ///         // functions mentioned above want these flags too then the flags
361 ///         // must be added there too because only one matching rule in this
362 ///         // map is used per-function.
363 ///         default: async | trappable,
364 ///     },
365 ///
366 ///     // Same as `imports` above, but applies to exported functions.
367 ///     exports: { /* ... */ },
368 ///
369 ///     // This can be used to translate WIT return values of the form
370 ///     // `result<T, error-type>` into `Result<T, RustErrorType>` in Rust.
371 ///     // Users must define `RustErrorType` and the `Host` trait for the
372 ///     // interface which defines `error-type` will have a method
373 ///     // called `convert_error_type` which converts `RustErrorType`
374 ///     // into `wasmtime::Result<ErrorType>`. This conversion can either
375 ///     // return the raw WIT error (`ErrorType` here) or a trap.
376 ///     //
377 ///     // By default this option is not specified. This option only takes
378 ///     // effect when `trappable_imports` is set for some imports.
379 ///     trappable_error_type: {
380 ///         "wasi:io/streams/stream-error" => RustErrorType,
381 ///     },
382 ///
383 ///     // All generated bindgen types are "owned" meaning types like `String`
384 ///     // are used instead of `&str`, for example. This is the default and
385 ///     // ensures that the same type used in both imports and exports uses the
386 ///     // same generated type.
387 ///     ownership: Owning,
388 ///
389 ///     // Alternative to `Owning` above where borrowed types attempt to be used
390 ///     // instead. The `duplicate_if_necessary` configures whether duplicate
391 ///     // Rust types will be generated for the same WIT type if necessary, for
392 ///     // example when a type is used both as an import and an export.
393 ///     ownership: Borrowing {
394 ///         duplicate_if_necessary: true
395 ///     },
396 ///
397 ///     // Restrict the code generated to what's needed for the interface
398 ///     // imports in the inlined WIT document fragment.
399 ///     interfaces: "
400 ///         import wasi:cli/command;
401 ///     ",
402 ///
403 ///     // Remap imported interfaces or resources to types defined in Rust
404 ///     // elsewhere. Using this option will prevent any code from being
405 ///     // generated for interfaces mentioned here. Resources named here will
406 ///     // not have a type generated to represent the resource.
407 ///     //
408 ///     // Interfaces mapped with this option should be previously generated
409 ///     // with an invocation of this macro. Resources need to be mapped to a
410 ///     // Rust type name.
411 ///     with: {
412 ///         // This can be used to indicate that entire interfaces have
413 ///         // bindings generated elsewhere with a path pointing to the
414 ///         // bindinges-generated module.
415 ///         "wasi:random/random": wasmtime_wasi::p2::bindings::random::random,
416 ///
417 ///         // Similarly entire packages can also be specified.
418 ///         "wasi:cli": wasmtime_wasi::p2::bindings::cli,
419 ///
420 ///         // Or, if applicable, entire namespaces can additionally be mapped.
421 ///         "wasi": wasmtime_wasi::p2::bindings,
422 ///
423 ///         // Versions are supported if multiple versions are in play:
424 ///         "wasi:http/types@0.2.0": wasmtime_wasi_http::bindings::http::types,
425 ///         "wasi:[email protected]": wasmtime_wasi_http::bindings::http,
426 ///
427 ///         // The `with` key can also be used to specify the `T` used in
428 ///         // import bindings of `Resource<T>`. This can be done to configure
429 ///         // which typed resource shows up in generated bindings and can be
430 ///         // useful when working with the typed methods of `ResourceTable`.
431 ///         "wasi:filesystem/types/descriptor": MyDescriptorType,
432 ///     },
433 ///
434 ///     // Additional derive attributes to include on generated types (structs or enums).
435 ///     //
436 ///     // These are deduplicated and attached in a deterministic order.
437 ///     additional_derives: [
438 ///         Hash,
439 ///         serde::Deserialize,
440 ///         serde::Serialize,
441 ///     ],
442 ///
443 ///     // An niche configuration option to require that the `T` in `Store<T>`
444 ///     // is always `Send` in the generated bindings. Typically not needed
445 ///     // but if synchronous bindings depend on asynchronous bindings using
446 ///     // the `with` key then this may be required.
447 ///     require_store_data_send: false,
448 ///
449 ///     // If the `wasmtime` crate is depended on at a nonstandard location
450 ///     // or is renamed then this is the path to the root of the `wasmtime`
451 ///     // crate. Much of the generated code needs to refer to `wasmtime` so
452 ///     // this should be used if the `wasmtime` name is not wasmtime itself.
453 ///     //
454 ///     // By default this is `wasmtime`.
455 ///     wasmtime_crate: path::to::wasmtime,
456 ///
457 ///     // This is an in-source alternative to using `WASMTIME_DEBUG_BINDGEN`.
458 ///     //
459 ///     // Note that if this option is specified then the compiler will always
460 ///     // recompile your bindings. Cargo records the start time of when rustc
461 ///     // is spawned by this will write a file during compilation. To Cargo
462 ///     // that looks like a file was modified after `rustc` was spawned,
463 ///     // so Cargo will always think your project is "dirty" and thus always
464 ///     // recompile it. Recompiling will then overwrite the file again,
465 ///     // starting the cycle anew. This is only recommended for debugging.
466 ///     //
467 ///     // This option defaults to false.
468 ///     include_generated_code_from_file: false,
469 /// });
470 /// ```
471 pub use wasmtime_component_macro::bindgen;
472 
473 /// Derive macro to generate implementations of the [`ComponentType`] trait.
474 ///
475 /// This derive macro can be applied to `struct` and `enum` definitions and is
476 /// used to bind either a `record`, `enum`, or `variant` in the component model.
477 ///
478 /// Note you might be looking for [`bindgen!`] rather than this macro as that
479 /// will generate the entire type for you rather than just a trait
480 /// implementation.
481 ///
482 /// This macro supports a `#[component]` attribute which is used to customize
483 /// how the type is bound to the component model. A top-level `#[component]`
484 /// attribute is required to specify either `record`, `enum`, or `variant`.
485 ///
486 /// ## Records
487 ///
488 /// `record`s in the component model correspond to `struct`s in Rust. An example
489 /// is:
490 ///
491 /// ```rust
492 /// use wasmtime::component::ComponentType;
493 ///
494 /// #[derive(ComponentType)]
495 /// #[component(record)]
496 /// struct Color {
497 ///     r: u8,
498 ///     g: u8,
499 ///     b: u8,
500 /// }
501 /// ```
502 ///
503 /// which corresponds to the WIT type:
504 ///
505 /// ```wit
506 /// record color {
507 ///     r: u8,
508 ///     g: u8,
509 ///     b: u8,
510 /// }
511 /// ```
512 ///
513 /// Note that the name `Color` here does not need to match the name in WIT.
514 /// That's purely used as a name in Rust of what to refer to. The field names
515 /// must match that in WIT, however. Field names can be customized with the
516 /// `#[component]` attribute though.
517 ///
518 /// ```rust
519 /// use wasmtime::component::ComponentType;
520 ///
521 /// #[derive(ComponentType)]
522 /// #[component(record)]
523 /// struct VerboseColor {
524 ///     #[component(name = "r")]
525 ///     red: u8,
526 ///     #[component(name = "g")]
527 ///     green: u8,
528 ///     #[component(name = "b")]
529 ///     blue: u8,
530 /// }
531 /// ```
532 ///
533 /// Also note that field ordering is significant at this time and must match
534 /// WIT.
535 ///
536 /// ## Variants
537 ///
538 /// `variant`s in the component model correspond to a subset of shapes of a Rust
539 /// `enum`. Variants in the component model have a single optional payload type
540 /// which means that not all Rust `enum`s correspond to component model
541 /// `variant`s. An example variant is:
542 ///
543 /// ```rust
544 /// use wasmtime::component::ComponentType;
545 ///
546 /// #[derive(ComponentType)]
547 /// #[component(variant)]
548 /// enum Filter {
549 ///     #[component(name = "none")]
550 ///     None,
551 ///     #[component(name = "all")]
552 ///     All,
553 ///     #[component(name = "some")]
554 ///     Some(Vec<String>),
555 /// }
556 /// ```
557 ///
558 /// which corresponds to the WIT type:
559 ///
560 /// ```wit
561 /// variant filter {
562 ///     none,
563 ///     all,
564 ///     some(list<string>),
565 /// }
566 /// ```
567 ///
568 /// The `variant` style of derive allows an optional payload on Rust `enum`
569 /// variants but it must be a single unnamed field. Variants of the form `Foo(T,
570 /// U)` or `Foo { name: T }` are not supported at this time.
571 ///
572 /// Note that the order of variants in Rust must match the order of variants in
573 /// WIT. Additionally it's likely that `#[component(name = "...")]` is required
574 /// on all Rust `enum` variants because the name currently defaults to the Rust
575 /// name which is typically UpperCamelCase whereas WIT uses kebab-case.
576 ///
577 /// ## Enums
578 ///
579 /// `enum`s in the component model correspond to C-like `enum`s in Rust. Note
580 /// that a component model `enum` does not allow any payloads so the Rust `enum`
581 /// must additionally have no payloads.
582 ///
583 /// ```rust
584 /// use wasmtime::component::ComponentType;
585 ///
586 /// #[derive(ComponentType)]
587 /// #[component(enum)]
588 /// #[repr(u8)]
589 /// enum Setting {
590 ///     #[component(name = "yes")]
591 ///     Yes,
592 ///     #[component(name = "no")]
593 ///     No,
594 ///     #[component(name = "auto")]
595 ///     Auto,
596 /// }
597 /// ```
598 ///
599 /// which corresponds to the WIT type:
600 ///
601 /// ```wit
602 /// enum setting {
603 ///     yes,
604 ///     no,
605 ///     auto,
606 /// }
607 /// ```
608 ///
609 /// Note that the order of variants in Rust must match the order of variants in
610 /// WIT. Additionally it's likely that `#[component(name = "...")]` is required
611 /// on all Rust `enum` variants because the name currently defaults to the Rust
612 /// name which is typically UpperCamelCase whereas WIT uses kebab-case.
613 pub use wasmtime_component_macro::ComponentType;
614 
615 /// A derive macro for generating implementations of the [`Lift`] trait.
616 ///
617 /// This macro will likely be applied in conjunction with the
618 /// [`#[derive(ComponentType)]`](macro@ComponentType) macro along the lines
619 /// of `#[derive(ComponentType, Lift)]`. This trait enables reading values from
620 /// WebAssembly.
621 ///
622 /// Note you might be looking for [`bindgen!`] rather than this macro as that
623 /// will generate the entire type for you rather than just a trait
624 /// implementation.
625 ///
626 /// At this time this derive macro has no configuration.
627 ///
628 /// ## Examples
629 ///
630 /// ```rust
631 /// use wasmtime::component::{ComponentType, Lift};
632 ///
633 /// #[derive(ComponentType, Lift)]
634 /// #[component(record)]
635 /// struct Color {
636 ///     r: u8,
637 ///     g: u8,
638 ///     b: u8,
639 /// }
640 /// ```
641 pub use wasmtime_component_macro::Lift;
642 
643 /// A derive macro for generating implementations of the [`Lower`] trait.
644 ///
645 /// This macro will likely be applied in conjunction with the
646 /// [`#[derive(ComponentType)]`](macro@ComponentType) macro along the lines
647 /// of `#[derive(ComponentType, Lower)]`. This trait enables passing values to
648 /// WebAssembly.
649 ///
650 /// Note you might be looking for [`bindgen!`] rather than this macro as that
651 /// will generate the entire type for you rather than just a trait
652 /// implementation.
653 ///
654 /// At this time this derive macro has no configuration.
655 ///
656 /// ## Examples
657 ///
658 /// ```rust
659 /// use wasmtime::component::{ComponentType, Lower};
660 ///
661 /// #[derive(ComponentType, Lower)]
662 /// #[component(record)]
663 /// struct Color {
664 ///     r: u8,
665 ///     g: u8,
666 ///     b: u8,
667 /// }
668 /// ```
669 pub use wasmtime_component_macro::Lower;
670 
671 /// A macro to generate a Rust type corresponding to WIT `flags`
672 ///
673 /// This macro generates a type that implements the [`ComponentType`], [`Lift`],
674 /// and [`Lower`] traits. The generated Rust type corresponds to the `flags`
675 /// type in WIT.
676 ///
677 /// Example usage of this looks like:
678 ///
679 /// ```rust
680 /// use wasmtime::component::flags;
681 ///
682 /// flags! {
683 ///     Permissions {
684 ///         #[component(name = "read")]
685 ///         const READ;
686 ///         #[component(name = "write")]
687 ///         const WRITE;
688 ///         #[component(name = "execute")]
689 ///         const EXECUTE;
690 ///     }
691 /// }
692 ///
693 /// fn validate_permissions(permissions: &mut Permissions) {
694 ///     if permissions.contains(Permissions::EXECUTE | Permissions::WRITE) {
695 ///         panic!("cannot enable both writable and executable at the same time");
696 ///     }
697 ///
698 ///     if permissions.contains(Permissions::READ) {
699 ///         panic!("permissions must at least contain read");
700 ///     }
701 /// }
702 /// ```
703 ///
704 /// which corresponds to the WIT type:
705 ///
706 /// ```wit
707 /// flags permissions {
708 ///     read,
709 ///     write,
710 ///     execute,
711 /// }
712 /// ```
713 ///
714 /// This generates a structure which is similar to/inspired by the [`bitflags`
715 /// crate](https://crates.io/crates/bitflags). The `Permissions` structure
716 /// generated implements the [`PartialEq`], [`Eq`], [`Debug`], [`BitOr`],
717 /// [`BitOrAssign`], [`BitAnd`], [`BitAndAssign`], [`BitXor`], [`BitXorAssign`],
718 /// and [`Not`] traits - in addition to the Wasmtime-specific component ones
719 /// [`ComponentType`], [`Lift`], and [`Lower`].
720 ///
721 /// [`BitOr`]: std::ops::BitOr
722 /// [`BitOrAssign`]: std::ops::BitOrAssign
723 /// [`BitAnd`]: std::ops::BitAnd
724 /// [`BitAndAssign`]: std::ops::BitAndAssign
725 /// [`BitXor`]: std::ops::BitXor
726 /// [`BitXorAssign`]: std::ops::BitXorAssign
727 /// [`Not`]: std::ops::Not
728 pub use wasmtime_component_macro::flags;
729 
730 #[cfg(any(docsrs, test, doctest))]
731 pub mod bindgen_examples;
732 
733 // NB: needed for the links in the docs above to work in all `cargo doc`
734 // configurations and avoid errors.
735 #[cfg(not(any(docsrs, test, doctest)))]
736 #[doc(hidden)]
737 pub mod bindgen_examples {}
738 
739 #[cfg(not(feature = "component-model-async"))]
740 pub(crate) mod concurrent_disabled;
741 
742 #[cfg(not(feature = "component-model-async"))]
743 pub(crate) use concurrent_disabled as concurrent;
744