# tiny-xlib
A tiny set of bindings to the [Xlib] library.
The primary contemporary library for handling [Xlib] is the [`x11-dl`] crate. However, there are three
primary issues.
1. **You should not be using Xlib in 2023.** [Xlib] is legacy code, and even that doesn't get across
how poor the API decisions that it's locked itself into are. It has a global error hook for
some reason, thread-safety is a mess, and it has so many soundness holes it might as well be made
out of swiss cheese. You should not be using [Xlib]. If you *have* to use [Xlib], you should just
run all of your logic using the much more sound [XCB] library, or, even more ideally, something
like [`x11rb`]. Then, you take the `Display` pointer and use it for whatever legacy API you've
locked yourself into, and use [XCB] or [`x11rb`] for everything else. Yes, I just called [GLX]
a legacy API. It's the 2020's now. [Vulkan] and [`wgpu`] run everywhere aside from legacy machines.
Not to mention, they support [XCB].
2. Even if you manage to use [`x11-dl`] without tripping over the legacy API, it is a massive crate.
[Xlib] comes with quite a few functions, most of which are unnecessary in the 21st century.
Even if you don't use any of these and just stick to [XCB], you still pay the price for it.
Binaries that use [`x11-dl`] need to dedicate a significant amount of their binary and memory
space to the library. Even on Release builds, I have recorded [`x11-dl`] taking up to seven
percent of the binary.
3. Global error handling. [Xlib] has a single global error hook. This is reminiscent of the Unix
signal handling API, in that it makes it difficult to create well-modularized programs
since they will fight with each-other over the error handlers. However, unlike the signal
handling API, there is no way to tell if you're replacing an existing error hook.
`tiny-xlib` aims to solve all of these problems. It provides a safe API around [Xlib] that is
conducive to being handed off to both [XCB] APIs and legacy [Xlib] APIs. The library only
imports absolutely necessary functions. In addition, it also provides a common API for
handling errors in a safe, modular way.
# Features
- Safe API around [Xlib]. See the [`Display`] structure.
- Minimal set of dependencies.
- Implements [`AsRawXcbConnection`], which allows it to be used with [XCB] APIs.
- Modular error handling.
# Non-Features
- Any API outside of opening [`Display`]s and handling errors. If this library doesn't support some
feature, it's probably intentional. You should use [XCB] or [`x11rb`] instead. This includes:
- Window management.
- Any extensions outside of `Xlib-xcb`.
- IME handling.
- Hardware rendering.
# Examples
```no_run
use as_raw_xcb_connection::AsRawXcbConnection;
use tiny_xlib::Display;
use x11rb::connection::Connection;
use x11rb::xcb_ffi::XCBConnection;
// Open a display.
let display = Display::new(None)?;
// Get the XCB connection.
let xcb_conn = display.as_raw_xcb_connection();
// Use that pointer to create a new XCB connection.
let xcb_conn = unsafe {
XCBConnection::from_raw_xcb_connection(xcb_conn.cast(), false)?
};
// Register a handler for X11 errors.
loop {
println!("Event: {:?}", xcb_conn.wait_for_event()?);
}
```
[Xlib]: https://en.wikipedia.org/wiki/Xlib
[XCB]: https://xcb.freedesktop.org/
[`x11-dl`]: https://crates.io/crates/x11-dl
[`x11rb`]: https://crates.io/crates/x11rb
[GLX]: https://en.wikipedia.org/wiki/GLX
[Vulkan]: https://www.khronos.org/vulkan/
[`wgpu`]: https://crates.io/crates/wgpu
[`Display`]: https://docs.rs/tiny-xlib/latest/tiny-xlib/struct.Display.html
[`AsRawXcbConnection`]: https://docs.rs/as_raw_xcb_connection/latest/as_raw_xcb_connection/trait.AsRawXcbConnection.html
## License
Licensed under either of
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
* Zlib license ([LICENSE-ZLIB](LICENSE-ZLIB) or https://opensource.org/licenses/Zlib)
at your option.
#### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.