wl_client_builder/
lib.rs

1//! This crate provides a builder that generates type-safe wrappers for the [`wl-client`]
2//! crate.
3//!
4//! [`wl-client`]: https://docs.rs/wl-client
5//!
6//! # Generating code in `build.rs`
7//!
8//! The simplest way to generate code looks like this
9//!
10//! ```
11//! // build.rs
12//! use wl_client_builder::Builder;
13//!
14//! # fn no_run() {
15//! fn main() {
16//!     Builder::default().build().unwrap();
17//! }
18//! # }
19//! ```
20//!
21//! This will
22//!
23//! 1. load all XML protocols stored in the `wayland-protocols` directory next to the
24//!    `Cargo.toml`,
25//! 2. generate code into `$OUT_DIR/wayland-protocols/mod.rs`.
26//!
27//! This code can be used with the `include!` macro:
28//!
29//! ```ignore
30//! mod wayland_protocols {
31//!     include!(concat!(env!("OUT_DIR"), "/wayland-protocols/mod.rs"));
32//! }
33//! ```
34//!
35//! # Enabling mutable data
36//!
37//! If you want to pass mutable data to event handlers, you must explicitly enable the
38//! `mutable_data` flag:
39//!
40//! ```
41//! # use wl_client_builder::Builder;
42//! #
43//! # fn no_run() {
44//! Builder::default().with_mutable_data(true).build().unwrap();
45//! # }
46//! ```
47//!
48//! # Generating code with the CLI
49//!
50//! Wrappers can be generated ahead of time with the [`wl-client-builder`] application.
51//!
52//! This might be preferable if you want to check the generated code into your repository
53//! or if you cannot use `build.rs`.
54//!
55//! [`wl-client-builder`]: https://crates.io/crates/wl-client-builder-cli
56//!
57//! Assuming that you are storing the XML files in a directory called `protocols` and
58//! want to generate files into `src/protocols/mod.rs`, you can use the CLI as follows:
59//!
60//! ```shell
61//! $ rm -rf src/protocols
62//! $ wl-client-builder --xml-dir protocols src/protocols
63//! $ rustfmt src/protocols/mod.rs
64//! ```
65//!
66//! # Generating code with a custom application
67//!
68//! By default the [`Builder`] assumes that it is being used from `build.rs` and will emit
69//! messages for cargo. All of this can be customized.
70//!
71//! ```
72//! # use wl_client_builder::Builder;
73//! #
74//! # fn no_run() {
75//! Builder::default()
76//!     // Disable build.rs behavior.
77//!     .for_build_rs(false)
78//!     // Don't try to load XML files from the `wayland-protocols` directory.
79//!     .with_default_dir(false)
80//!     // ...
81//!     .build().unwrap();
82//! # }
83//! ```
84
85#![allow(clippy::collapsible_else_if, clippy::len_zero)]
86
87pub use {builder::Builder, error::Error};
88
89mod ast;
90mod builder;
91mod error;
92mod formatter;
93mod parser;
wl_client_builder/lib.rs

wl_client_builder/
lib.rs
