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//! # Generating code with the CLI
36//!
37//! Wrappers can be generated ahead of time with the [`wl-client-builder`] application.
38//!
39//! This might be preferable if you want to check the generated code into your repository
40//! or if you cannot use `build.rs`.
41//!
42//! [`wl-client-builder`]: https://crates.io/crates/wl-client-builder-cli
43//!
44//! Assuming that you are storing the XML files in a directory called `protocols` and
45//! want to generate files into `src/protocols/mod.rs`, you can use the CLI as follows:
46//!
47//! ```shell
48//! $ rm -rf src/protocols
49//! $ wl-client-builder --xml-dir protocols src/protocols
50//! $ rustfmt src/protocols/mod.rs
51//! ```
52//!
53//! # Generating code with a custom application
54//!
55//! By default the [`Builder`] assumes that it is being used from `build.rs` and will emit
56//! messages for cargo. All of this can be customized.
57//!
58//! ```
59//! # use wl_client_builder::Builder;
60//! Builder::default()
61//!     // Disable build.rs behavior.
62//!     .for_build_rs(false)
63//!     // Don't try to load XML files from the `wayland-protocols` directory.
64//!     .with_default_dir(false)
65//!     // ...
66//!     .build().unwrap();
67//! ```
68
69#![allow(clippy::collapsible_else_if, clippy::len_zero)]
70
71pub use {builder::Builder, error::Error};
72
73mod ast;
74mod builder;
75mod error;
76mod formatter;
77mod parser;
wl_client_builder/lib.rs

wl_client_builder/
lib.rs
