Skip to content

Commit 97cfdd4

Browse files
madsmtmmadsmtm
authored
Move some of our documentation to docs.rs (#3478)
* Move platform-specific documentation to `winit::platform` module * Document cargo features in crate docs * Move version requirements to crate-level docs
1 parent a127bd6 commit 97cfdd4

File tree

13 files changed

+223
-201
lines changed

13 files changed

+223
-201
lines changed

‎Cargo.toml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ targets = [
4242
]
4343
rustdoc-args = ["--cfg", "docsrs"]
4444

45+
# Features are documented in either `lib.rs` or under `winit::platform`.
4546
[features]
4647
default = ["rwh_06", "x11", "wayland", "wayland-dlopen", "wayland-csd-adwaita"]
4748
x11 = ["x11-dl", "bytemuck", "percent-encoding", "xkbcommon-dl/x11", "x11rb"]
@@ -53,6 +54,7 @@ wayland-csd-adwaita-notitle = ["sctk-adwaita"]
5354
android-native-activity = ["android-activity/native-activity"]
5455
android-game-activity = ["android-activity/game-activity"]
5556
serde = ["dep:serde", "cursor-icon/serde", "smol_str/serde"]
57+
mint = ["dep:mint"]
5658
rwh_04 = ["dep:rwh_04", "ndk/rwh_04"]
5759
rwh_05 = ["dep:rwh_05", "ndk/rwh_05"]
5860
rwh_06 = ["dep:rwh_06", "ndk/rwh_06"]

‎FEATURES.md

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
Winit aims to expose an interface that abstracts over window creation and input handling and can
44
be used to create both games and applications. It supports the following main graphical platforms:
55
- Desktop
6-
- Windows 7+ (10+ is tested regularly)
7-
- macOS 10.7+ (10.14+ is tested regularly)
6+
- Windows
7+
- macOS
88
- Unix
99
- via X11
1010
- via Wayland
@@ -13,9 +13,6 @@ be used to create both games and applications. It supports the following main gr
1313
- iOS
1414
- Android
1515
- Web
16-
- Chrome
17-
- Firefox
18-
- Safari 13.1+
1916

2017
Most platforms expose capabilities that cannot be meaningfully transposed onto others. Winit does not
2118
aim to support every single feature of every platform, but rather to abstract over the common features
@@ -151,7 +148,6 @@ If your PR makes notable changes to Winit's features, please update this section
151148
* Setting the X11 parent window
152149

153150
### iOS
154-
* `winit` has a minimum OS requirement of iOS 8
155151
* Get the `UIScreen` object pointer
156152
* Setting the `UIView` hidpi factor
157153
* Valid orientations
@@ -164,9 +160,6 @@ If your PR makes notable changes to Winit's features, please update this section
164160
### Web
165161
* Get if the systems preferred color scheme is "dark"
166162

167-
## Usability
168-
* `serde`: Enables serialization/deserialization of certain types with Serde. (Maintainer: @Osspial)
169-
170163
## Compatibility Matrix
171164

172165
Legend:

‎README.md

Lines changed: 1 addition & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -33,14 +33,6 @@ Winit is designed to be a low-level brick in a hierarchy of libraries. Consequen
3333
show something on the window you need to use the platform-specific getters provided by winit, or
3434
another library.
3535

36-
### Cargo Features
37-
38-
Winit provides the following features, which can be enabled in your `Cargo.toml` file:
39-
* `serde`: Enables serialization/deserialization of certain types with [Serde](https://crates.io/crates/serde).
40-
* `x11` (enabled by default): On Unix platform, compiles with the X11 backend
41-
* `wayland` (enabled by default): On Unix platform, compiles with the Wayland backend
42-
* `mint`: Enables mint (math interoperability standard types) conversions.
43-
4436
## MSRV Policy
4537

4638
This crate's Minimum Supported Rust Version (MSRV) is **1.70**. Changes to
@@ -71,118 +63,4 @@ same MSRV policy.
7163

7264
### Platform-specific usage
7365

74-
#### Wayland
75-
76-
Note that windows don't appear on Wayland until you draw/present to them.
77-
78-
#### Web
79-
80-
To run the web example: `cargo run-wasm --example web`
81-
82-
Winit supports compiling to the `wasm32-unknown-unknown` target with `web-sys`.
83-
84-
On the web platform, a Winit window is backed by a `<canvas>` element. You can
85-
either [provide Winit with a `<canvas>` element][web with_canvas], or [let Winit
86-
create a `<canvas>` element which you can then retrieve][web canvas getter] and
87-
insert it into the DOM yourself.
88-
89-
For the example code using Winit on Web, check out the [web example]. For
90-
information on using Rust on WebAssembly, check out the [Rust and WebAssembly
91-
book].
92-
93-
[web with_canvas]: https://docs.rs/winit/latest/wasm32-unknown-unknown/winit/platform/web/trait.WindowBuilderExtWebSys.html#tymethod.with_canvas
94-
[web canvas getter]: https://docs.rs/winit/latest/wasm32-unknown-unknown/winit/platform/web/trait.WindowExtWebSys.html#tymethod.canvas
95-
[web example]: ./examples/web.rs
96-
[Rust and WebAssembly book]: https://rustwasm.github.io/book/
97-
98-
#### Android
99-
100-
The Android backend builds on (and exposes types from) the [`ndk`](https://docs.rs/ndk/latest/ndk/) crate.
101-
102-
Native Android applications need some form of "glue" crate that is responsible
103-
for defining the main entry point for your Rust application as well as tracking
104-
various life-cycle events and synchronizing with the main JVM thread.
105-
106-
Winit uses the [android-activity](https://github.com/rib/android-activity) as a
107-
glue crate (prior to `0.28` it used
108-
[ndk-glue](https://github.com/rust-windowing/android-ndk-rs/tree/master/ndk-glue)).
109-
110-
The version of the glue crate that your application depends on _must_ match the
111-
version that Winit depends on because the glue crate is responsible for your
112-
application's main entry point. If Cargo resolves multiple versions, they will
113-
clash.
114-
115-
`winit` glue compatibility table:
116-
117-
| winit | ndk-glue |
118-
| :---: | :--------------------------: |
119-
| 0.29 | `android-activity = "0.5"` |
120-
| 0.28 | `android-activity = "0.4"` |
121-
| 0.27 | `ndk-glue = "0.7"` |
122-
| 0.26 | `ndk-glue = "0.5"` |
123-
| 0.25 | `ndk-glue = "0.3"` |
124-
| 0.24 | `ndk-glue = "0.2"` |
125-
126-
The recommended way to avoid a conflict with the glue version is to avoid explicitly
127-
depending on the `android-activity` crate, and instead consume the API that
128-
is re-exported by Winit under `winit::platform::android::activity::*`
129-
130-
Running on an Android device needs a dynamic system library. Add this to Cargo.toml:
131-
132-
```toml
133-
[lib]
134-
name = "main"
135-
crate-type = ["cdylib"]
136-
```
137-
138-
All Android applications are based on an `Activity` subclass, and the
139-
`android-activity` crate is designed to support different choices for this base
140-
class. Your application _must_ specify the base class it needs via a feature flag:
141-
142-
| Base Class | Feature Flag | Notes |
143-
| :--------------: | :---------------: | :-----: |
144-
| `NativeActivity` | `android-native-activity` | Built-in to Android - it is possible to use without compiling any Java or Kotlin code. Java or Kotlin code may be needed to subclass `NativeActivity` to access some platform features. It does not derive from the [`AndroidAppCompat`] base class.|
145-
| [`GameActivity`] | `android-game-activity` | Derives from [`AndroidAppCompat`], a defacto standard `Activity` base class that helps support a wider range of Android versions. Requires a build system that can compile Java or Kotlin and fetch Android dependencies from a [Maven repository][agdk_jetpack] (or link with an embedded [release][agdk_releases] of [`GameActivity`]) |
146-
147-
[`GameActivity`]: https://developer.android.com/games/agdk/game-activity
148-
[`GameTextInput`]: https://developer.android.com/games/agdk/add-support-for-text-input
149-
[`AndroidAppCompat`]: https://developer.android.com/reference/androidx/appcompat/app/AppCompatActivity
150-
[agdk_jetpack]: https://developer.android.com/jetpack/androidx/releases/games
151-
[agdk_releases]: https://developer.android.com/games/agdk/download#agdk-libraries
152-
[Gradle]: https://developer.android.com/studio/build
153-
154-
For more details, refer to these `android-activity` [example applications](https://github.com/rust-mobile/android-activity/tree/main/examples).
155-
156-
##### Converting from `ndk-glue` to `android-activity`
157-
158-
If your application is currently based on `NativeActivity` via the `ndk-glue` crate and building with `cargo apk`, then the minimal changes would be:
159-
1. Remove `ndk-glue` from your `Cargo.toml`
160-
2. Enable the `"android-native-activity"` feature for Winit: `winit = { version = "0.29.10", features = [ "android-native-activity" ] }`
161-
3. Add an `android_main` entrypoint (as above), instead of using the '`[ndk_glue::main]` proc macro from `ndk-macros` (optionally add a dependency on `android_logger` and initialize logging as above).
162-
4. Pass a clone of the `AndroidApp` that your application receives to Winit when building your event loop (as shown above).
163-
164-
#### MacOS
165-
166-
A lot of functionality expects the application to be ready before you start
167-
doing anything; this includes creating windows, fetching monitors, drawing,
168-
and so on, see issues [#2238], [#2051] and [#2087].
169-
170-
If you encounter problems, you should try doing your initialization inside
171-
`Event::Resumed`.
172-
173-
#### iOS
174-
175-
Similar to macOS, iOS's main `UIApplicationMain` does some init work that's required
176-
by all UI-related code (see issue [#1705]). It would be best to consider creating your windows
177-
inside `Event::Resumed`.
178-
179-
180-
[#2238]: https://github.com/rust-windowing/winit/issues/2238
181-
[#2051]: https://github.com/rust-windowing/winit/issues/2051
182-
[#2087]: https://github.com/rust-windowing/winit/issues/2087
183-
[#1705]: https://github.com/rust-windowing/winit/issues/1705
184-
185-
#### Redox OS
186-
187-
Redox OS has some functionality not yet present that will be implemented when
188-
its orbital display server provides it.
66+
Check out the [`winit::platform`](https://rust-windowing.github.io/winit/winit/platform/index.html) module for platform-specific usage.

‎src/lib.rs

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,23 @@
126126
//! [`visible` set to `false`](crate::window::WindowAttributes::with_visible) and explicitly make the
127127
//! window visible only once you're ready to render into it.
128128
//!
129+
//! # Cargo Features
130+
//!
131+
//! Winit provides the following Cargo features:
132+
//!
133+
//! * `x11` (enabled by default): On Unix platforms, enables the X11 backend.
134+
//! * `wayland` (enabled by default): On Unix platforms, enables the Wayland
135+
//! backend.
136+
//! * `rwh_04`: Implement `raw-window-handle v0.4` traits.
137+
//! * `rwh_05`: Implement `raw-window-handle v0.5` traits.
138+
//! * `rwh_06`: Implement `raw-window-handle v0.6` traits.
139+
//! * `serde`: Enables serialization/deserialization of certain types with
140+
//! [Serde](https://crates.io/crates/serde).
141+
//! * `mint`: Enables mint (math interoperability standard types) conversions.
142+
//!
143+
//! See the [`platform`] module for documentation on platform-specific cargo
144+
//! features.
145+
//!
129146
//! [`EventLoop`]: event_loop::EventLoop
130147
//! [`EventLoop::new()`]: event_loop::EventLoop::new
131148
//! [`EventLoop::run()`]: event_loop::EventLoop::run

‎src/platform/android.rs

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,69 @@
1+
//! # Android
2+
//!
3+
//! The Android backend builds on (and exposes types from) the [`ndk`](https://docs.rs/ndk/) crate.
4+
//!
5+
//! Native Android applications need some form of "glue" crate that is responsible
6+
//! for defining the main entry point for your Rust application as well as tracking
7+
//! various life-cycle events and synchronizing with the main JVM thread.
8+
//!
9+
//! Winit uses the [android-activity](https://docs.rs/android-activity/) as a
10+
//! glue crate (prior to `0.28` it used
11+
//! [ndk-glue](https://github.com/rust-windowing/android-ndk-rs/tree/master/ndk-glue)).
12+
//!
13+
//! The version of the glue crate that your application depends on _must_ match the
14+
//! version that Winit depends on because the glue crate is responsible for your
15+
//! application's main entry point. If Cargo resolves multiple versions, they will
16+
//! clash.
17+
//!
18+
//! `winit` glue compatibility table:
19+
//!
20+
//! | winit | ndk-glue |
21+
//! | :---: | :--------------------------: |
22+
//! | 0.29 | `android-activity = "0.5"` |
23+
//! | 0.28 | `android-activity = "0.4"` |
24+
//! | 0.27 | `ndk-glue = "0.7"` |
25+
//! | 0.26 | `ndk-glue = "0.5"` |
26+
//! | 0.25 | `ndk-glue = "0.3"` |
27+
//! | 0.24 | `ndk-glue = "0.2"` |
28+
//!
29+
//! The recommended way to avoid a conflict with the glue version is to avoid explicitly
30+
//! depending on the `android-activity` crate, and instead consume the API that
31+
//! is re-exported by Winit under `winit::platform::android::activity::*`
32+
//!
33+
//! Running on an Android device needs a dynamic system library. Add this to Cargo.toml:
34+
//!
35+
//! ```toml
36+
//! [lib]
37+
//! name = "main"
38+
//! crate-type = ["cdylib"]
39+
//! ```
40+
//!
41+
//! All Android applications are based on an `Activity` subclass, and the
42+
//! `android-activity` crate is designed to support different choices for this base
43+
//! class. Your application _must_ specify the base class it needs via a feature flag:
44+
//!
45+
//! | Base Class | Feature Flag | Notes |
46+
//! | :--------------: | :---------------: | :-----: |
47+
//! | `NativeActivity` | `android-native-activity` | Built-in to Android - it is possible to use without compiling any Java or Kotlin code. Java or Kotlin code may be needed to subclass `NativeActivity` to access some platform features. It does not derive from the [`AndroidAppCompat`] base class.|
48+
//! | [`GameActivity`] | `android-game-activity` | Derives from [`AndroidAppCompat`], a defacto standard `Activity` base class that helps support a wider range of Android versions. Requires a build system that can compile Java or Kotlin and fetch Android dependencies from a [Maven repository][agdk_jetpack] (or link with an embedded [release][agdk_releases] of [`GameActivity`]) |
49+
//!
50+
//! [`GameActivity`]: https://developer.android.com/games/agdk/game-activity
51+
//! [`GameTextInput`]: https://developer.android.com/games/agdk/add-support-for-text-input
52+
//! [`AndroidAppCompat`]: https://developer.android.com/reference/androidx/appcompat/app/AppCompatActivity
53+
//! [agdk_jetpack]: https://developer.android.com/jetpack/androidx/releases/games
54+
//! [agdk_releases]: https://developer.android.com/games/agdk/download#agdk-libraries
55+
//! [Gradle]: https://developer.android.com/studio/build
56+
//!
57+
//! For more details, refer to these `android-activity` [example applications](https://github.com/rust-mobile/android-activity/tree/main/examples).
58+
//!
59+
//! ## Converting from `ndk-glue` to `android-activity`
60+
//!
61+
//! If your application is currently based on `NativeActivity` via the `ndk-glue` crate and building with `cargo apk`, then the minimal changes would be:
62+
//! 1. Remove `ndk-glue` from your `Cargo.toml`
63+
//! 2. Enable the `"android-native-activity"` feature for Winit: `winit = { version = "0.29.10", features = [ "android-native-activity" ] }`
64+
//! 3. Add an `android_main` entrypoint (as above), instead of using the '`[ndk_glue::main]` proc macro from `ndk-macros` (optionally add a dependency on `android_logger` and initialize logging as above).
65+
//! 4. Pass a clone of the `AndroidApp` that your application receives to Winit when building your event loop (as shown above).
66+
167
use crate::{
268
event_loop::{ActiveEventLoop, EventLoop, EventLoopBuilder},
369
window::{Window, WindowAttributes},

‎src/platform/ios.rs

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,69 @@
1+
//! # iOS / UIKit
2+
//!
3+
//! Winit has an OS requirement of iOS 8 or higher, and is regularly tested on
4+
//! iOS 9.3.
5+
//!
6+
//! iOS's main `UIApplicationMain` does some init work that's required by all
7+
//! UI-related code (see issue [#1705]). It is best to create your windows
8+
//! inside `Event::Resumed`.
9+
//!
10+
//! [#1705]: https://github.com/rust-windowing/winit/issues/1705
11+
//!
12+
//! ## Building app
13+
//!
14+
//! To build ios app you will need rustc built for this targets:
15+
//!
16+
//! - armv7-apple-ios
17+
//! - armv7s-apple-ios
18+
//! - i386-apple-ios
19+
//! - aarch64-apple-ios
20+
//! - x86_64-apple-ios
21+
//!
22+
//! Then
23+
//!
24+
//! ```
25+
//! cargo build --target=...
26+
//! ```
27+
//! The simplest way to integrate your app into xcode environment is to build it
28+
//! as a static library. Wrap your main function and export it.
29+
//!
30+
//! ```rust, ignore
31+
//! #[no_mangle]
32+
//! pub extern fn start_winit_app() {
33+
//! start_inner()
34+
//! }
35+
//!
36+
//! fn start_inner() {
37+
//! ...
38+
//! }
39+
//! ```
40+
//!
41+
//! Compile project and then drag resulting .a into Xcode project. Add winit.h to xcode.
42+
//!
43+
//! ```ignore
44+
//! void start_winit_app();
45+
//! ```
46+
//!
47+
//! Use start_winit_app inside your xcode's main function.
48+
//!
49+
//!
50+
//! ## App lifecycle and events
51+
//!
52+
//! iOS environment is very different from other platforms and you must be very
53+
//! careful with it's events. Familiarize yourself with
54+
//! [app lifecycle](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIApplicationDelegate_Protocol/).
55+
//!
56+
//! This is how those event are represented in winit:
57+
//!
58+
//! - applicationDidBecomeActive is Resumed
59+
//! - applicationWillResignActive is Suspended
60+
//! - applicationWillTerminate is LoopExiting
61+
//!
62+
//! Keep in mind that after LoopExiting event is received every attempt to draw with
63+
//! opengl will result in segfault.
64+
//!
65+
//! Also note that app may not receive the LoopExiting event if suspended; it might be SIGKILL'ed.
66+
167
use std::os::raw::c_void;
268

369
use crate::{

‎src/platform/macos.rs

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,19 @@
1+
//! # macOS / AppKit
2+
//!
3+
//! Winit has an OS requirement of macOS 10.11 or higher (same as Rust
4+
//! itself), and is regularly tested on macOS 10.14.
5+
//!
6+
//! A lot of functionality expects the application to be ready before you
7+
//! start doing anything; this includes creating windows, fetching monitors,
8+
//! drawing, and so on, see issues [#2238], [#2051] and [#2087].
9+
//!
10+
//! If you encounter problems, you should try doing your initialization inside
11+
//! `Event::Resumed`.
12+
//!
13+
//! [#2238]: https://github.com/rust-windowing/winit/issues/2238
14+
//! [#2051]: https://github.com/rust-windowing/winit/issues/2051
15+
//! [#2087]: https://github.com/rust-windowing/winit/issues/2087
16+
117
use std::os::raw::c_void;
218

319
#[cfg(feature = "serde")]

‎src/platform/orbital.rs

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,6 @@
1+
//! # Orbital / Redox OS
2+
//!
3+
//! Redox OS has some functionality not yet present that will be implemented
4+
//! when its orbital display server provides it.
5+
16
// There are no Orbital specific traits yet.

‎src/platform/wayland.rs

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,18 @@
1+
//! # Wayland
2+
//!
3+
//! **Note:** Windows don't appear on Wayland until you draw/present to them.
4+
//!
5+
//! By default, Winit loads system libraries using `dlopen`. This can be
6+
//! disabled by disabling the `"wayland-dlopen"` cargo feature.
7+
//!
8+
//! ## Client-side decorations
9+
//!
10+
//! Winit provides client-side decorations by default, but the behaviour can
11+
//! be controlled with the following feature flags:
12+
//!
13+
//! * `wayland-csd-adwaita` (default).
14+
//! * `wayland-csd-adwaita-crossfont`.
15+
//! * `wayland-csd-adwaita-notitle`.
116
use crate::{
217
event_loop::{ActiveEventLoop, EventLoopBuilder},
318
monitor::MonitorHandle,

0 commit comments

Comments
 (0)