diff --git a/x11rb-async/src/lib.rs b/x11rb-async/src/lib.rs index 8a9c89ac..733517d4 100644 --- a/x11rb-async/src/lib.rs +++ b/x11rb-async/src/lib.rs @@ -1,6 +1,43 @@ // This code is dual licensed under MIT OR Apache 2.0. //! Asynchronous X11 rust bindings. +//! +//! This library allows to interact with an X11 server from rust code. A connection to an X11 +//! server is represented by an implementation of the `Connection` trait. +//! +//! The client can interact with the server by sending requests. The server can answer requests and +//! can also generate events. +//! +//! The examples that come with this library might be a good starting point for new users. +//! +//! +//! # Feature flags +//! +//! This crate uses [feature +//! flags](https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section) to reduce +//! the amount of compiled code. There are two kinds of feature flags available: +//! +//! * Feature flags for specific X11 extensions +//! * Feature flags for additional functionality +//! +//! ## Feature flags for specific X11 extensions +//! +//! By default, only the core X11 protocol and X11 extensions that are needed internally are +//! enabled. These are the `bigreq`, `ge` and `xc_misc` extensions. Further extensions need to be +//! explicitly enabled via their feature flag: +//! +//! `composite`, `damage`, `dpms`, `dri2`, `dri3`, `glx`, `present`, `randr`, `record`, `render`, +//! `res`, `screensaver`, `shape`, `shm`, `sync`, `xevie`, `xf86dri`, `xf86vidmode`, `xfixes`, +//! `xinerama`, `xinput`, `xkb`, `xprint`, `xselinux`, `xtest`, `xv`, `xvmc`. +//! +//! If you want to take the "I do not want to think about this"-approach, you can enable the +//! `all-extensions` feature to just enable, well, all extensions. +//! +//! ## Feature flags for additional functionality +//! +//! Additionally, the following flags exist: +//! * `allow-unsafe-code`: Enable the same feature in x11rb and implement +//! [`blocking::BlockingConnection`] for [`x11rb::xcb_ffi::XCBConnection`] // -- Public Modules -- diff --git a/x11rb-protocol/src/lib.rs b/x11rb-protocol/src/lib.rs index 1b3280d9..e71f6028 100644 --- a/x11rb-protocol/src/lib.rs +++ b/x11rb-protocol/src/lib.rs @@ -5,6 +5,37 @@ //! //! This protocol does not do any I/O. If you need an X11 client library, look at //! <https://docs.rs/x11rb/latest/x11rb/>. +//! +//! # Feature flags +//! +//! This crate uses [feature +//! flags](https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section) to reduce +//! the amount of compiled code. There are two kinds of feature flags available: +//! +//! * Feature flags for specific X11 extensions +//! * Feature flags for additional functionality +//! +//! ## Feature flags for specific X11 extensions +//! +//! By default, only the core X11 protocol and some small, commonly needed X11 extensions are +//! enabled. These are the `bigreq`, `ge` and `xc_misc` extensions. Further extensions need to be +//! explicitly enabled via their feature flag: +//! +//! `composite`, `damage`, `dpms`, `dri2`, `dri3`, `glx`, `present`, `randr`, `record`, `render`, +//! `res`, `screensaver`, `shape`, `shm`, `sync`, `xevie`, `xf86dri`, `xf86vidmode`, `xfixes`, +//! `xinerama`, `xinput`, `xkb`, `xprint`, `xselinux`, `xtest`, `xv`, `xvmc`. +//! +//! If you want to take the "I do not want to think about this"-approach, you can enable the +//! `all-extensions` feature to just enable, well, all extensions. +//! +//! ## Feature flags for additional functionality +//! +//! Additionally, the following flags exist: +//! * `std` (enabled by default): Enable functionality needing the std library, e.g. environment +//! variables or [`std::os::unix::io::OwnedFd`]. +//! * `resource_manager`: Enable the code in [resource_manager] for loading and querying the +//! X11 resource database. +//! * `serde`: Implement [`serde::Serialize`] and [`serde::Deserialize`] for all objects. #![forbid( missing_copy_implementations, diff --git a/x11rb/src/lib.rs b/x11rb/src/lib.rs index 2faf2df4..b5b869ef 100644 --- a/x11rb/src/lib.rs +++ b/x11rb/src/lib.rs @@ -84,9 +84,9 @@ //! //! ### Feature flags for specific X11 extensions //! -//! By default, only the core X11 protocol and X11 extensions that are -//! needed internally are enabled. Further extensions need to be explicitly enabled via their -//! feature flag: +//! By default, only the core X11 protocol and X11 extensions that are needed internally are +//! enabled. These are the `bigreq`, `ge` and `xc_misc` extensions. Further extensions need to be +//! explicitly enabled via their feature flag: //! //! `composite`, `damage`, `dpms`, `dri2`, `dri3`, `glx`, `present`, `randr`, `record`, `render`, //! `res`, `screensaver`, `shape`, `shm`, `sync`, `xevie`, `xf86dri`, `xf86vidmode`, `xfixes`, @@ -99,14 +99,14 @@ //! //! Additionally, the following flags exist: //! * `allow-unsafe-code`: Enable features that require `unsafe`. Without this flag, -//! `x11rb::xcb_ffi::XCBConnection` and some support code for it are unavailable. -//! * `cursor`: Enable the code in [crate::cursor] for loading cursor files. -//! * `resource_manager`: Enable the code in [crate::resource_manager] for loading and querying the +//! [`xcb_ffi::XCBConnection`] and some support code for it are unavailable. +//! * `cursor`: Enable the code in [cursor] for loading cursor files. +//! * `resource_manager`: Enable the code in [resource_manager] for loading and querying the //! X11 resource database. -//! * `image`: Enable the code in [crate::image] for working with pixel image data. +//! * `image`: Enable the code in [image] for working with pixel image data. //! * `dl-libxcb`: Enabling this feature will prevent from libxcb being linked to the //! resulting executable. Instead libxcb will be dynamically loaded at runtime. -//! This feature adds the [`crate::xcb_ffi::load_libxcb`] function, that allows to load +//! This feature adds the [`xcb_ffi::load_libxcb`] function, that allows to load //! libxcb and check for success or failure. //! //! # Integrating x11rb with an Event Loop