From 63bcbbbe548cd2d22bea452b1439c90ef1b4ef76 Mon Sep 17 00:00:00 2001 From: John Nunley Date: Tue, 26 Nov 2024 19:41:24 -0800 Subject: [PATCH] doc: Add installation instructions to docs This commit adds installation instructions to the top-level documentation for lib.rs. The main goal is to give the dependencies that X11/Wayland use in a formal place, since it's not written down anywhere to my knowledge. Signed-off-by: John Nunley --- src/lib.rs | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 3dadb80d1b..73cc32b898 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,5 +1,55 @@ //! Winit is a cross-platform window creation and event loop management library. //! +//! # Installation +//! +//! `winit` can be added to `Cargo.toml` as a dependency. It can be added via `cargo add`. +//! +//! ```bash +//! $ cargo add winit +//! ``` +//! +//! To only enable the X11 backend on Free Unix[^unix] systems, disable default features +//! and enable the `x11` feature. +//! +//! ```bash +//! $ cargo add winit --no-default-features --features x11 +//! ``` +//! +//! To only enable the Wayland backend on Free Unix systems, disable default features +//! and enable the `wayland` feature. +//! +//! ```bash +//! $ cargo add winit --no-default-features --features wayland +//! ``` +//! +//! These features have no effect on systems that are not Free Unix. +//! +//! ## Dependencies +//! +//! Dependencies on non-system libraries is managed through Cargo. For the X11 +//! backend, the following Ubuntu packages or their equivalents must be installed. +//! +//! - `libx11-dev` +//! - `libxcb1-dev` +//! - `libxi-dev` +//! - `libxcbcommon-dev` +//! - `libxcbcommon-x11-dev` +//! +//! For the Wayland backend, the following Ubuntu packages or their equivalents +//! must be installed. +//! +//! - `libwayland-dev` +//! - `libxcbcommon-dev` +//! +//! The "dev" packages are only needed for building binaries that use `winit`. On +//! deployed system the non-`dev` equivalents need to be installed. +//! +//! The other backends (Windows, macOS, etc) do not have any dependencies on system libraries +//! that don't already come with the operating system. However, note that the Windows backend +//! only supports Windows 10 and above. +//! +//! [^unix]: Unix systems outside of Android and Apple, like Linux or FreeBSD. +//! //! # Building windows //! //! Before you can create a [`Window`], you first need to build an [`EventLoop`]. This is done with