From 853d8c317031398129d9b5bd32a5b832195df480 Mon Sep 17 00:00:00 2001 From: Uli Schlachter Date: Sun, 8 Oct 2023 10:42:38 +0200 Subject: [PATCH] Improve documentation of feature flags x11rb has some explanation of its feature flags on its main documentation page. This commit improves this to explicitly say which "X11 extensions that are needed internally" are always enabled. Additionally, some unnecessary "crate::" at the beginning of links is removed. Then, a similar documentation is added to x11rb-protocol and x11rb-async. Signed-off-by: Uli Schlachter --- x11rb-async/src/lib.rs | 37 +++++++++++++++++++++++++++++++++++++ x11rb-protocol/src/lib.rs | 31 +++++++++++++++++++++++++++++++ x11rb/src/lib.rs | 16 ++++++++-------- 3 files changed, 76 insertions(+), 8 deletions(-) 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 //! . +//! +//! # 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