wit_bindgen_wrpc/lib.rs
1//! Bindings generation support for wRPC using Rust with the Component Model.
2//!
3//! This crate is a bindings generator for [WIT] and the [Component Model].
4//! Users are likely interested in the [`generate!`] macro which actually
5//! generates bindings. Otherwise this crate provides any runtime support
6//! necessary for the macro-generated code.
7//!
8//! [WIT]: https://component-model.bytecodealliance.org/design/wit.html
9//! [Component Model]: https://component-model.bytecodealliance.org/
10
11/// Generate bindings for an input WIT document.
12///
13/// This macro is the bread-and-butter of the `wit-bindgen-wrpc` crate. The macro
14/// here will parse [WIT] as input and generate Rust bindings to work with the
15/// `world` that's specified in the [WIT]. For a primer on WIT see [this
16/// documentation][WIT] and for a primer on worlds see [here][worlds].
17///
18/// [WIT]: https://component-model.bytecodealliance.org/design/wit.html
19/// [worlds]: https://component-model.bytecodealliance.org/design/worlds.html
20///
21/// This macro takes as input a [WIT package] as well as a [`world`][worlds]
22/// within that package. It will then generate a Rust function for all `import`s
23/// into the world. If there are any `export`s then a Rust `trait` will be
24/// generated for you to implement. The macro additionally takes a number of
25/// configuration parameters documented below as well.
26///
27/// Basic invocation of the macro can look like:
28///
29/// ```
30/// use wit_bindgen_wrpc::generate;
31/// # macro_rules! generate { ($($t:tt)*) => () }
32///
33/// generate!();
34/// ```
35///
36/// This will parse a WIT package in the `wit` folder adjacent to your project's
37/// `Cargo.toml` file. Within this WIT package there must be precisely one
38/// `world` and that world will be the one that has bindings generated for it.
39/// All other options remain at their default values (more on this below).
40///
41/// If your WIT package has more than one `world`, or if you want to select a
42/// world from the dependencies, you can specify a world explicitly:
43///
44/// ```
45/// use wit_bindgen_wrpc::generate;
46/// # macro_rules! generate { ($($t:tt)*) => () }
47///
48/// generate!("my-world");
49/// generate!("wasi:cli/imports");
50/// ```
51///
52/// This form of the macro takes a single string as an argument which is a
53/// "world specifier" to select which world is being generated. As a single
54/// string, such as `"my-world"`, this selects the world named `my-world` in the
55/// package being parsed in the `wit` folder. The longer form specification
56/// `"wasi:cli/imports"` indicates that the `wasi:cli` package, located in the
57/// `wit/deps` folder, will have a world named `imports` and those bindings will
58/// be generated.
59///
60/// If your WIT package is located in a different directory than one called
61/// `wit` then it can be specified with the `in` keyword:
62///
63/// ```
64/// use wit_bindgen_wrpc::generate;
65/// # macro_rules! generate { ($($t:tt)*) => () }
66///
67/// generate!(in "./my/other/path/to/wit");
68/// generate!("a-world" in "../path/to/wit");
69/// ```
70///
71/// The full-form of the macro, however, takes a braced structure which is a
72/// "bag of options":
73///
74/// ```
75/// use wit_bindgen_wrpc::generate;
76/// # macro_rules! generate { ($($t:tt)*) => () }
77///
78/// generate!({
79/// world: "my-world",
80/// path: "../path/to/wit",
81/// // ...
82/// });
83/// ```
84///
85/// For documentation on each option, see below.
86///
87/// ## Exploring generated bindings
88///
89/// Once bindings have been generated they can be explored via a number of means
90/// to see what was generated:
91///
92/// * Using `cargo doc` should render all of the generated bindings in addition
93/// to the original comments in the WIT format itself.
94/// * If your IDE supports `rust-analyzer` code completion should be available
95/// to explore and see types.
96/// * The `wit-bindgen-wrpc` CLI tool, packaged as `wit-bindgen-wrpc-cli` on crates.io,
97/// can be executed the same as the `generate!` macro and the output can be
98/// read.
99/// * If you're seeing an error, `WIT_BINDGEN_DEBUG=1` can help debug what's
100/// happening (more on this below) by emitting macro output to a file.
101/// * This documentation can be consulted for various constructs as well.
102///
103/// Currently browsing generated code may have road bumps on the way. If you run
104/// into issues or have idea of how to improve the situation please [file an
105/// issue].
106///
107/// [file an issue]: https://github.com/bytecodealliance/wrpc/issues/new
108///
109/// ## Namespacing
110///
111/// In WIT, worlds can import and export `interface`s, functions, and types. Each
112/// `interface` can either be "anonymous" and only named within the context of a
113/// `world` or it can have a "package ID" associated with it. Names in Rust take
114/// into account all the names associated with a WIT `interface`. For example
115/// the package ID `foo:bar/baz` would create a `mod foo` which contains a `mod
116/// bar` which contains a `mod baz`.
117///
118/// WIT imports and exports are additionally separated into their own
119/// namespaces. Imports are generated at the level of the `generate!` macro
120/// where exports are generated under an `exports` namespace.
121///
122/// ## Imports
123///
124/// Imports into a `world` can be types, resources, functions, and interfaces.
125/// Each of these is bound as a Rust type, function, or module. The intent is
126/// that the WIT interfaces map to what is roughly idiomatic Rust for the given
127/// interface.
128///
129/// ### Imports: Top-level functions and types
130///
131/// Imports at the top-level of a world are generated directly where the
132/// `generate!` macro is invoked.
133///
134/// ```
135/// mod bindings {
136/// use wit_bindgen_wrpc::generate;
137///
138/// generate!({
139/// inline: r"
140/// package a:b;
141///
142/// world the-world {
143/// record fahrenheit {
144/// degrees: f32,
145/// }
146///
147/// import what-temperature-is-it: func() -> fahrenheit;
148///
149/// record celsius {
150/// degrees: f32,
151/// }
152///
153/// import convert-to-celsius: func(a: fahrenheit) -> celsius;
154/// }
155/// ",
156/// });
157/// }
158///
159/// use bindings::Celsius;
160///
161/// async fn test(wrpc: &impl wrpc_transport::Invoke<Context = ()>) -> anyhow::Result<()> {
162/// let current_temp = bindings::what_temperature_is_it(wrpc, ()).await?;
163/// println!("current temp in fahrenheit is {}", current_temp.degrees);
164/// let in_celsius: Celsius = bindings::convert_to_celsius(wrpc, (), ¤t_temp).await?;
165/// println!("current temp in celsius is {}", in_celsius.degrees);
166/// Ok(())
167/// }
168/// ```
169///
170/// ### Imports: Interfaces
171///
172/// Interfaces are placed into submodules where the `generate!` macro is
173/// invoked and are namespaced based on their identifiers.
174///
175/// ```
176/// use wit_bindgen_wrpc::generate;
177///
178/// generate!({
179/// inline: r"
180/// package my:test;
181///
182/// interface logging {
183/// enum level {
184/// debug,
185/// info,
186/// error,
187/// }
188/// log: func(level: level, msg: string);
189/// }
190///
191/// world the-world {
192/// import logging;
193/// import global-logger: interface {
194/// use logging.{level};
195///
196/// set-current-level: func(level: level);
197/// get-current-level: func() -> level;
198/// }
199/// }
200/// ",
201/// });
202///
203/// // `my` and `test` are from `package my:test;` and `logging` is for the
204/// // interface name.
205/// use my::test::logging::Level;
206///
207/// async fn test(wrpc: &impl wrpc_transport::Invoke<Context = ()>) -> anyhow::Result<()> {
208/// let current_level = global_logger::get_current_level(wrpc, ()).await?;
209/// println!("current logging level is {current_level:?}");
210/// global_logger::set_current_level(wrpc, (), Level::Error).await?;
211///
212/// my::test::logging::log(wrpc, (), Level::Info, "Hello there!").await?;
213/// Ok(())
214/// }
215/// #
216/// # fn main() {}
217/// ```
218///
219/// ### Imports: Resources
220///
221/// Imported resources generate a type named after the name of the resource.
222/// This type is then used both for borrows as `&T` as well as via ownership as
223/// `T`. Resource methods are bound as methods on the type `T`.
224///
225/// ```
226/// use wit_bindgen_wrpc::generate;
227///
228/// generate!({
229/// inline: r#"
230/// package my:test;
231///
232/// interface logger {
233/// enum level {
234/// debug,
235/// info,
236/// error,
237/// }
238///
239/// resource logger {
240/// constructor(destination: string);
241/// log: func(level: level, msg: string);
242/// }
243/// }
244///
245/// // Note that while this world does not textually import the above
246/// // `logger` interface it is a transitive dependency via the `use`
247/// // statement so the "elaborated world" imports the logger.
248/// world the-world {
249/// use logger.{logger};
250///
251/// import get-global-logger: func() -> logger;
252/// }
253/// "#,
254/// });
255///
256/// use my::test::logger::{self, Level};
257///
258/// async fn test(wrpc: &impl wrpc_transport::Invoke<Context = ()>) -> anyhow::Result<()> {
259/// let logger = get_global_logger(wrpc, ()).await?;
260/// Logger::log(wrpc, (), &logger.as_borrow(), Level::Debug, "This is a global message");
261///
262/// let logger2 = Logger::new(wrpc, (), "/tmp/other.log").await?;
263/// Logger::log(wrpc, (), &logger2.as_borrow(), Level::Info, "This is not a global message").await?;
264/// Ok(())
265/// }
266/// #
267/// # fn main() {}
268/// ```
269///
270/// Note in the above example the lack of import of `Logger`. The `use`
271/// statement imported the `Logger` type, an alias of it, from the `logger`
272/// interface into `the-world`. This generated a Rust `type` alias so `Logger`
273/// was available at the top-level.
274///
275/// ## Exports: Basic Usage
276///
277/// A WIT world can not only `import` functionality but can additionally
278/// `export` functionality as well. An `export` represents a contract that the
279/// Rust program must implement to be able to work correctly. The `generate!`
280/// macro's goal is to take care of all the low-level and ABI details for you,
281/// so the end result is that `generate!`, for exports, will generate Rust
282/// `trait`s that you must implement.
283///
284/// A minimal example of this is:
285///
286/// ```
287/// use futures::stream::TryStreamExt as _;
288/// use wit_bindgen_wrpc::generate;
289///
290/// generate!({
291/// inline: r#"
292/// package my:test;
293///
294/// world my-world {
295/// export hello: func();
296/// }
297/// "#,
298/// });
299///
300/// #[derive(Clone)]
301/// struct MyComponent;
302///
303/// impl<Ctx: Send> Handler<Ctx> for MyComponent {
304/// async fn hello(&self, cx: Ctx) -> anyhow::Result<()> { Ok(()) }
305/// }
306///
307/// async fn serve_exports(wrpc: &impl wrpc_transport::Serve) {
308/// let invocations = serve(wrpc, MyComponent).await.unwrap();
309/// invocations.into_iter().for_each(|(instance, name, st)| {
310/// tokio::spawn(async move {
311/// eprintln!("serving {instance} {name}");
312/// st.try_collect::<Vec<_>>().await.unwrap();
313/// });
314/// })
315/// }
316/// ```
317///
318/// Here the `Handler` trait was generated by the `generate!` macro and represents
319/// the functions at the top-level of `my-world`, in this case the function
320/// `hello`. A custom type, here called `MyComponent`, is created and the trait
321/// is implemented for that type.
322///
323/// Additionally a macro is generated by `generate!` (macros generating macros)
324/// called `serve`. The `serve` function is given a component that implements
325/// the export `trait`s and then it will itself generate all necessary
326/// `#[no_mangle]` functions to implement the ABI required.
327///
328/// ## Exports: Multiple Interfaces
329///
330/// Each `interface` in WIT will generate a `trait` that must be implemented in
331/// addition to the top-level `trait` for the world. All traits are named
332/// `Handler` here and are namespaced appropriately in modules:
333///
334/// ```
335/// use futures::stream::TryStreamExt as _;
336/// use wit_bindgen_wrpc::generate;
337///
338/// generate!({
339/// inline: r#"
340/// package my:test;
341///
342/// interface a {
343/// func-in-a: func();
344/// second-func-in-a: func();
345/// }
346///
347/// world my-world {
348/// export a;
349/// export b: interface {
350/// func-in-b: func();
351/// }
352/// export c: func();
353/// }
354/// "#,
355/// });
356///
357/// #[derive(Clone)]
358/// struct MyComponent;
359///
360/// impl<Ctx: Send> Handler<Ctx> for MyComponent {
361/// async fn c(&self, cx: Ctx) -> anyhow::Result<()> { Ok(()) }
362/// }
363///
364/// impl<Ctx: Send> exports::my::test::a::Handler<Ctx> for MyComponent {
365/// async fn func_in_a(&self, cx: Ctx) -> anyhow::Result<()> { Ok(()) }
366/// async fn second_func_in_a(&self, cx: Ctx) -> anyhow::Result<()> { Ok(()) }
367/// }
368///
369/// impl<Ctx: Send> exports::b::Handler<Ctx> for MyComponent {
370/// async fn func_in_b(&self, cx: Ctx) -> anyhow::Result<()> { Ok(()) }
371/// }
372///
373/// async fn serve_exports(wrpc: &impl wrpc_transport::Serve) {
374/// let invocations = serve(wrpc, MyComponent).await.unwrap();
375/// invocations.into_iter().for_each(|(instance, name, st)| {
376/// tokio::spawn(async move {
377/// eprintln!("serving {instance} {name}");
378/// st.try_collect::<Vec<_>>().await.unwrap();
379/// });
380/// })
381/// }
382/// ```
383///
384/// Here note that there were three `Handler` traits generated for each of the
385/// three groups: two interfaces and one `world`. Also note that traits (and
386/// types) for exports are namespaced in an `exports` module.
387///
388/// Note that when the top-level `world` does not have any exported functions,
389/// or if an interface does not have any functions, then no `trait` is
390/// generated:
391///
392/// ```
393/// use futures::stream::TryStreamExt as _;
394///
395/// mod bindings {
396/// use wit_bindgen_wrpc::generate;
397///
398/// generate!({
399/// inline: r#"
400/// package my:test;
401///
402/// interface a {
403/// type my-type = u32;
404/// }
405///
406/// world my-world {
407/// export b: interface {
408/// use a.{my-type};
409///
410/// foo: func() -> my-type;
411/// }
412/// }
413/// "#,
414/// });
415/// }
416///
417/// #[derive(Clone)]
418/// struct MyComponent;
419///
420/// impl<Ctx: Send> bindings::exports::b::Handler<Ctx> for MyComponent {
421/// async fn foo(&self, cx: Ctx) -> anyhow::Result<u32> {
422/// Ok(42)
423/// }
424/// }
425///
426/// async fn serve_exports(wrpc: &impl wrpc_transport::Serve) {
427/// let invocations = bindings::serve(wrpc, MyComponent).await.unwrap();
428/// invocations.into_iter().for_each(|(instance, name, st)| {
429/// tokio::spawn(async move {
430/// eprintln!("serving {instance} {name}");
431/// st.try_collect::<Vec<_>>().await.unwrap();
432/// });
433/// })
434/// }
435/// ```
436///
437/// ## Exports: Resources
438///
439/// Exporting a resource is significantly different than importing a resource.
440/// A component defining a resource can create new resources of that type at any
441/// time, for example. Additionally resources can be "dereferenced" into their
442/// underlying values within the component.
443///
444/// Owned resources have a custom type generated and borrowed resources are
445/// generated with a type of the same name suffixed with `Borrow<'_>`, such as
446/// `MyResource` and `MyResourceBorrow<'_>`.
447///
448/// Like `interface`s the methods and functions used with a `resource` are
449/// packaged up into a `trait`.
450///
451/// Specifying a custom resource type is done with an associated type on the
452/// corresponding trait for the resource's containing interface/world:
453///
454/// ```
455/// use std::sync::{Arc, RwLock};
456///
457/// use anyhow::Context;
458/// use bytes::Bytes;
459/// use futures::stream::TryStreamExt as _;
460/// use wrpc_transport::{ResourceBorrow, ResourceOwn};
461///
462/// mod bindings {
463/// use wit_bindgen_wrpc::generate;
464///
465/// generate!({
466/// inline: r#"
467/// package my:test;
468///
469/// interface logging {
470/// enum level {
471/// debug,
472/// info,
473/// error,
474/// }
475///
476/// resource logger {
477/// constructor(level: level);
478/// log: func(level: level, msg: string);
479/// level: func() -> level;
480/// set-level: func(level: level);
481/// }
482/// }
483///
484/// world my-world {
485/// export logging;
486/// }
487/// "#,
488/// });
489/// }
490///
491/// use bindings::exports::my::test::logging::{Handler, HandlerLogger, Level, Logger};
492///
493/// #[derive(Clone, Default)]
494/// struct MyComponent{
495/// loggers: Arc<RwLock<Vec<MyLogger>>>,
496/// }
497///
498/// // Note that the `logging` interface has no methods of its own but a trait
499/// // is required to be implemented here to specify the type of `Logger`.
500/// impl<Ctx: Send> Handler<Ctx> for MyComponent {}
501///
502/// struct MyLogger {
503/// level: RwLock<Level>,
504/// contents: RwLock<String>,
505/// }
506///
507/// impl<Ctx: Send> HandlerLogger<Ctx> for MyComponent {
508/// async fn new(&self, cx: Ctx, level: Level) -> anyhow::Result<ResourceOwn<Logger>> {
509/// let mut loggers = self.loggers.write().unwrap();
510/// let handle = loggers.len().to_le_bytes();
511/// loggers.push(MyLogger {
512/// level: RwLock::new(level),
513/// contents: RwLock::new(String::new()),
514/// });
515/// Ok(ResourceOwn::from(Bytes::copy_from_slice(&handle)))
516/// }
517///
518/// async fn log(&self, cx: Ctx, logger: ResourceBorrow<Logger>, level: Level, msg: String) -> anyhow::Result<()> {
519/// let i = Bytes::from(logger).as_ref().try_into()?;
520/// let i = usize::from_le_bytes(i);
521/// let loggers = self.loggers.read().unwrap();
522/// let logger = loggers.get(i).context("invalid resource handle")?;
523/// if level as u32 <= *logger.level.read().unwrap() as u32 {
524/// let mut contents = logger.contents.write().unwrap();
525/// contents.push_str(&msg);
526/// contents.push_str("\n");
527/// }
528/// Ok(())
529/// }
530///
531/// async fn level(&self, cx: Ctx, logger: ResourceBorrow<Logger>) -> anyhow::Result<Level> {
532/// let i = Bytes::from(logger).as_ref().try_into()?;
533/// let i = usize::from_le_bytes(i);
534/// let loggers = self.loggers.read().unwrap();
535/// let logger = loggers.get(i).context("invalid resource handle")?;
536/// let level = logger.level.read().unwrap();
537/// Ok(level.clone())
538/// }
539///
540/// async fn set_level(&self, cx: Ctx, logger: ResourceBorrow<Logger>, level: Level) -> anyhow::Result<()> {
541/// let i = Bytes::from(logger).as_ref().try_into()?;
542/// let i = usize::from_le_bytes(i);
543/// let loggers = self.loggers.read().unwrap();
544/// let logger = loggers.get(i).context("invalid resource handle")?;
545/// *logger.level.write().unwrap() = level;
546/// Ok(())
547/// }
548/// }
549///
550/// async fn serve_exports(wrpc: &impl wrpc_transport::Serve) {
551/// let invocations = bindings::serve(wrpc, MyComponent::default()).await.unwrap();
552/// invocations.into_iter().for_each(|(instance, name, st)| {
553/// tokio::spawn(async move {
554/// eprintln!("serving {instance} {name}");
555/// st.try_collect::<Vec<_>>().await.unwrap();
556/// });
557/// })
558/// }
559/// ```
560///
561/// It's important to note that resources in Rust do not get `&mut self` as
562/// methods, but instead are required to be defined with `&self`. This requires
563/// the use of interior mutability such as `RwLock` above from the
564/// `std::sync` module.
565///
566/// ## Exports: The `serve` function
567///
568/// Components are created by having exported WebAssembly functions with
569/// specific names, and these functions are not created when `generate!` is
570/// invoked. Instead these functions are created afterwards once you've defined
571/// your own type an implemented the various `trait`s for it. The `#[no_mangle]`
572/// functions that will become the component are created with the generated
573/// `serve` function.
574///
575/// Each call to `generate!` will itself generate a macro called `serve`.
576/// The macro's first argument is the name of a type that implements the traits
577/// generated:
578///
579/// ```
580/// use futures::stream::TryStreamExt as _;
581/// use wit_bindgen_wrpc::generate;
582///
583/// generate!({
584/// inline: r#"
585/// package my:test;
586///
587/// world my-world {
588/// # export hello: func();
589/// // ...
590/// }
591/// "#,
592/// });
593///
594/// #[derive(Clone)]
595/// struct MyComponent;
596///
597/// impl<Ctx: Send> Handler<Ctx> for MyComponent {
598/// # async fn hello(&self, cx: Ctx) -> anyhow::Result<()> { Ok(()) }
599/// // ...
600/// }
601///
602/// async fn serve_exports(wrpc: &impl wrpc_transport::Serve) {
603/// let invocations = serve(wrpc, MyComponent).await.unwrap();
604/// invocations.into_iter().for_each(|(instance, name, st)| {
605/// tokio::spawn(async move {
606/// eprintln!("serving {instance} {name}");
607/// st.try_collect::<Vec<_>>().await.unwrap();
608/// });
609/// })
610/// }
611/// ```
612///
613/// This argument is a Rust type which implements the `Handler` traits generated
614/// by `generate!`. Note that all `Handler` traits must be implemented for the
615/// type provided or an error will be generated.
616///
617/// This macro additionally accepts a second argument. The macro itself needs to
618/// be able to find the module where the `generate!` macro itself was originally
619/// invoked. Currently that can't be done automatically so a path to where
620/// `generate!` was provided can also be passed to the macro. By default, the
621/// argument is set to `self`:
622///
623/// ```
624/// use futures::stream::TryStreamExt as _;
625/// use wit_bindgen_wrpc::generate;
626///
627/// generate!({
628/// // ...
629/// # inline: r#"
630/// # package my:test;
631/// #
632/// # world my-world {
633/// # export hello: func();
634/// # // ...
635/// # }
636/// # "#,
637/// });
638/// #
639/// # #[derive(Clone)]
640/// # struct MyComponent;
641/// #
642/// # impl<Ctx: Send> Handler<Ctx> for MyComponent {
643/// # async fn hello(&self, cx: Ctx) -> anyhow::Result<()> { Ok(()) }
644/// # // ...
645/// # }
646/// #
647///
648///
649/// async fn serve_exports(wrpc: &impl wrpc_transport::Serve) {
650/// let invocations = serve(wrpc, MyComponent).await.unwrap();
651/// invocations.into_iter().for_each(|(instance, name, st)| {
652/// tokio::spawn(async move {
653/// eprintln!("serving {instance} {name}");
654/// st.try_collect::<Vec<_>>().await.unwrap();
655/// });
656/// })
657/// }
658/// ```
659///
660/// This indicates that the current module, referred to with `self`, is the one
661/// which had the `generate!` macro expanded.
662///
663/// If, however, the `generate!` macro was run in a different module then that
664/// must be configured:
665///
666/// ```
667/// use futures::stream::TryStreamExt as _;
668///
669/// mod bindings {
670/// wit_bindgen_wrpc::generate!({
671/// // ...
672/// # inline: r#"
673/// # package my:test;
674/// #
675/// # world my-world {
676/// # export hello: func();
677/// # // ...
678/// # }
679/// # "#,
680/// });
681/// }
682/// #
683/// # #[derive(Clone)]
684/// # struct MyComponent;
685/// #
686/// # impl<Ctx: Send> bindings::Handler<Ctx> for MyComponent {
687/// # async fn hello(&self, cx: Ctx) -> anyhow::Result<()> { Ok(()) }
688/// # // ...
689/// # }
690/// #
691/// ;
692/// #
693/// async fn serve_exports(wrpc: &impl wrpc_transport::Serve) {
694/// let invocations = bindings::serve(wrpc, MyComponent).await.unwrap();
695/// invocations.into_iter().for_each(|(instance, name, st)| {
696/// tokio::spawn(async move {
697/// eprintln!("serving {instance} {name}");
698/// st.try_collect::<Vec<_>>().await.unwrap();
699/// });
700/// })
701/// }
702/// ```
703///
704/// ## Debugging output to `generate!`
705///
706/// While `wit-bindgen-wrpc` is tested to the best of our ability there are
707/// inevitably bugs and issues that arise. These can range from bad error
708/// messages to misconfigured invocations to bugs in the macro itself. To assist
709/// with debugging these situations the macro recognizes an environment
710/// variable:
711///
712/// ```shell
713/// export WIT_BINDGEN_DEBUG=1
714/// ```
715///
716/// When set the macro will emit the result of expansion to a file and then
717/// `include!` that file. Any error messages generated by `rustc` should then
718/// point to the generated file and allow you to open it up, read it, and
719/// inspect it. This can often provide better context to the error than rustc
720/// provides by default with macros.
721///
722/// It is not recommended to set this environment variable by default as it will
723/// cause excessive rebuilds of Cargo projects. It's recommended to only use it
724/// as necessary to debug issues.
725///
726/// ## Options to `generate!`
727///
728/// The full list of options that can be passed to the `generate!` macro are as
729/// follows. Note that there are no required options, they all have default
730/// values.
731///
732///
733/// ```
734/// use wit_bindgen_wrpc::generate;
735/// # macro_rules! generate { ($($t:tt)*) => () }
736///
737/// generate!({
738/// // The name of the world that bindings are being generated for. If this
739/// // is not specified then it's required that the package selected
740/// // below has a single `world` in it.
741/// world: "my-world",
742///
743/// // Path to parse WIT and its dependencies from. Defaults to the `wit`
744/// // folder adjacent to your `Cargo.toml`.
745/// //
746/// // This parameter also supports the form of a list, such as:
747/// // ["../path/to/wit1", "../path/to/wit2"]
748/// // Usually used in testing, our test suite may want to generate code
749/// // from wit files located in multiple paths within a single mod, and we
750/// // don't want to copy these files again.
751/// path: "../path/to/wit",
752///
753/// // Enables passing "inline WIT". If specified this is the default
754/// // package that a world is selected from. Any dependencies that this
755/// // inline WIT refers to must be defined in the `path` option above.
756/// //
757/// // By default this is not specified.
758/// inline: "
759/// world my-world {
760/// import wasi:cli/imports;
761///
762/// export my-run: func()
763/// }
764/// ",
765///
766/// // Additional traits to derive for all defined types. Note that not all
767/// // types may be able to implement these traits, such as resources.
768/// //
769/// // By default this set is empty.
770/// additional_derives: [core::cmp::PartialEq, core::cmp::Eq, core::hash::Hash, core::clone::Clone],
771///
772/// // When generating bindings for interfaces that are not defined in the
773/// // same package as `world`, this option can be used to either generate
774/// // those bindings or point to already generated bindings.
775/// // For example, if your world refers to WASI types then the `wasi` crate
776/// // already has generated bindings for all WASI types and structures. In this
777/// // situation the key `with` here can be used to use those types
778/// // elsewhere rather than regenerating types.
779/// //
780/// // If, however, your world refers to interfaces for which you don't have
781/// // already generated bindings then you can use the special `generate` value
782/// // to have those bindings generated.
783/// //
784/// // The `with` key only supports replacing types at the interface level
785/// // at this time.
786/// //
787/// // When an interface is specified no bindings will be generated at
788/// // all. It's assumed bindings are fully generated somewhere else. This is an
789/// // indicator that any further references to types defined in these
790/// // interfaces should use the upstream paths specified here instead.
791/// //
792/// // Any unused keys in this map are considered an error.
793/// with: {
794/// "wasi:io/poll": wasi::io::poll,
795/// "some:package/my-interface": generate,
796/// },
797///
798/// // Indicates that all interfaces not present in `with` should be assumed
799/// // to be marked with `generate`.
800/// generate_all,
801///
802/// // An optional list of function names to skip generating bindings for.
803/// // This is only applicable to imports and the name specified is the name
804/// // of the function.
805/// skip: ["foo", "bar", "baz"],
806///
807/// // Configure where the `bitflags` crate is located. By default this
808/// // is `wit_bindgen_wrpc::bitflags` which already reexports `bitflags` for
809/// // you.
810/// bitflags_path: "path::to::bitflags",
811///
812/// // Whether to generate unused `record`, `enum`, `variant` types.
813/// // By default, they will not be generated unless they are used as input
814/// // or return value of a function.
815/// generate_unused_types: false,
816///
817/// // A list of "features" which correspond to WIT features to activate
818/// // when parsing WIT files. This enables `@unstable` annotations showing
819/// // up and having bindings generated for them.
820/// //
821/// // By default this is an empty list.
822/// features: ["foo", "bar", "baz"],
823/// });
824/// ```
825///
826/// [WIT package]: https://component-model.bytecodealliance.org/design/packages.html
827pub use wit_bindgen_wrpc_rust_macro::generate;
828
829#[cfg(docsrs)]
830pub mod examples;
831
832pub use anyhow;
833pub use bitflags;
834pub use bytes;
835pub use futures;
836pub use tokio;
837pub use tokio_util;
838pub use tracing;
839pub use wasm_tokio;
840pub use wrpc_transport;