|
1 | | -# winit - Cross-platform window creation and management in Rust |
| 1 | +You are probably looking for the [real winit crate](https://crates.io/crates/winit). |
2 | 2 |
|
3 | | -[](https://crates.io/crates/winit) |
4 | | -[](https://docs.rs/winit) |
5 | | -[](https://github.com/rust-windowing/winit/actions) |
6 | | - |
7 | | -```toml |
8 | | -[dependencies] |
9 | | -winit = "0.29.4" |
10 | | -``` |
11 | | - |
12 | | -## [Documentation](https://docs.rs/winit) |
13 | | - |
14 | | -For features _within_ the scope of winit, see [FEATURES.md](FEATURES.md). |
15 | | - |
16 | | -For features _outside_ the scope of winit, see [Are we GUI Yet?](https://areweguiyet.com/) and [Are we game yet?](https://arewegameyet.rs/), depending on what kind of project you're looking to do. |
17 | | - |
18 | | -## Contact Us |
19 | | - |
20 | | -Join us in any of these: |
21 | | - |
22 | | -[](https://matrix.to/#/#rust-windowing:matrix.org) |
23 | | -[](https://web.libera.chat/#winit) |
24 | | - |
25 | | -## Usage |
26 | | - |
27 | | -Winit is a window creation and management library. It can create windows and lets you handle |
28 | | -events (for example: the window being resized, a key being pressed, a mouse movement, etc.) |
29 | | -produced by the window. |
30 | | - |
31 | | -Winit is designed to be a low-level brick in a hierarchy of libraries. Consequently, in order to |
32 | | -show something on the window you need to use the platform-specific getters provided by winit, or |
33 | | -another library. |
34 | | - |
35 | | -### Cargo Features |
36 | | - |
37 | | -Winit provides the following features, which can be enabled in your `Cargo.toml` file: |
38 | | -* `serde`: Enables serialization/deserialization of certain types with [Serde](https://crates.io/crates/serde). |
39 | | -* `x11` (enabled by default): On Unix platform, compiles with the X11 backend |
40 | | -* `wayland` (enabled by default): On Unix platform, compiles with the Wayland backend |
41 | | -* `mint`: Enables mint (math interoperability standard types) conversions. |
42 | | - |
43 | | -## MSRV Policy |
44 | | - |
45 | | -This crate's Minimum Supported Rust Version (MSRV) is **1.65**. Changes to |
46 | | -the MSRV will be accompanied by a minor version bump. |
47 | | - |
48 | | -As a **tentative** policy, the upper bound of the MSRV is given by the following |
49 | | -formula: |
50 | | - |
51 | | -``` |
52 | | -min(sid, stable - 3) |
53 | | -``` |
54 | | - |
55 | | -Where `sid` is the current version of `rustc` provided by [Debian Sid], and |
56 | | -`stable` is the latest stable version of Rust. This bound may be broken in case of a major ecosystem shift or a security vulnerability. |
57 | | - |
58 | | -[Debian Sid]: https://packages.debian.org/sid/rustc |
59 | | - |
60 | | -The exception is for the Android platform, where a higher Rust version |
61 | | -must be used for certain Android features. In this case, the MSRV will be |
62 | | -capped at the latest stable version of Rust minus three. This inconsistency is |
63 | | -not reflected in Cargo metadata, as it is not powerful enough to expose this |
64 | | -restriction. |
65 | | - |
66 | | -All crates in the [`rust-windowing`] organizations have the |
67 | | -same MSRV policy. |
68 | | - |
69 | | -[`rust-windowing`]: https://github.com/rust-windowing |
70 | | - |
71 | | -### Platform-specific usage |
72 | | - |
73 | | -#### Wayland |
74 | | - |
75 | | -Note that windows don't appear on Wayland until you draw/present to them. |
76 | | - |
77 | | -#### WebAssembly |
78 | | - |
79 | | -To run the web example: `cargo run-wasm --example web` |
80 | | - |
81 | | -Winit supports compiling to the `wasm32-unknown-unknown` target with `web-sys`. |
82 | | - |
83 | | -On the web platform, a Winit window is backed by a `<canvas>` element. You can |
84 | | -either [provide Winit with a `<canvas>` element][web with_canvas], or [let Winit |
85 | | -create a `<canvas>` element which you can then retrieve][web canvas getter] and |
86 | | -insert it into the DOM yourself. |
87 | | - |
88 | | -For the example code using Winit with WebAssembly, check out the [web example]. For |
89 | | -information on using Rust on WebAssembly, check out the [Rust and WebAssembly |
90 | | -book]. |
91 | | - |
92 | | -[web with_canvas]: https://docs.rs/winit/latest/wasm32-unknown-unknown/winit/platform/web/trait.WindowBuilderExtWebSys.html#tymethod.with_canvas |
93 | | -[web canvas getter]: https://docs.rs/winit/latest/wasm32-unknown-unknown/winit/platform/web/trait.WindowExtWebSys.html#tymethod.canvas |
94 | | -[web example]: ./examples/web.rs |
95 | | -[Rust and WebAssembly book]: https://rustwasm.github.io/book/ |
96 | | - |
97 | | -#### Android |
98 | | - |
99 | | -The Android backend builds on (and exposes types from) the [`ndk`](https://docs.rs/ndk/latest/ndk/) crate. |
100 | | - |
101 | | -Native Android applications need some form of "glue" crate that is responsible |
102 | | -for defining the main entry point for your Rust application as well as tracking |
103 | | -various life-cycle events and synchronizing with the main JVM thread. |
104 | | - |
105 | | -Winit uses the [android-activity](https://github.com/rib/android-activity) as a |
106 | | -glue crate (prior to `0.28` it used |
107 | | -[ndk-glue](https://github.com/rust-windowing/android-ndk-rs/tree/master/ndk-glue)). |
108 | | - |
109 | | -The version of the glue crate that your application depends on _must_ match the |
110 | | -version that Winit depends on because the glue crate is responsible for your |
111 | | -application's main entry point. If Cargo resolves multiple versions, they will |
112 | | -clash. |
113 | | - |
114 | | -`winit` glue compatibility table: |
115 | | - |
116 | | -| winit | ndk-glue | |
117 | | -| :---: | :--------------------------: | |
118 | | -| 0.29 | `android-activity = "0.5"` | |
119 | | -| 0.28 | `android-activity = "0.4"` | |
120 | | -| 0.27 | `ndk-glue = "0.7"` | |
121 | | -| 0.26 | `ndk-glue = "0.5"` | |
122 | | -| 0.25 | `ndk-glue = "0.3"` | |
123 | | -| 0.24 | `ndk-glue = "0.2"` | |
124 | | - |
125 | | -The recommended way to avoid a conflict with the glue version is to avoid explicitly |
126 | | -depending on the `android-activity` crate, and instead consume the API that |
127 | | -is re-exported by Winit under `winit::platform::android::activity::*` |
128 | | - |
129 | | -Running on an Android device needs a dynamic system library. Add this to Cargo.toml: |
130 | | - |
131 | | -```toml |
132 | | -[lib] |
133 | | -name = "main" |
134 | | -crate-type = ["cdylib"] |
135 | | -``` |
136 | | - |
137 | | -All Android applications are based on an `Activity` subclass, and the |
138 | | -`android-activity` crate is designed to support different choices for this base |
139 | | -class. Your application _must_ specify the base class it needs via a feature flag: |
140 | | - |
141 | | -| Base Class | Feature Flag | Notes | |
142 | | -| :--------------: | :---------------: | :-----: | |
143 | | -| `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.| |
144 | | -| [`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`]) | |
145 | | - |
146 | | -[`GameActivity`]: https://developer.android.com/games/agdk/game-activity |
147 | | -[`GameTextInput`]: https://developer.android.com/games/agdk/add-support-for-text-input |
148 | | -[`AndroidAppCompat`]: https://developer.android.com/reference/androidx/appcompat/app/AppCompatActivity |
149 | | -[agdk_jetpack]: https://developer.android.com/jetpack/androidx/releases/games |
150 | | -[agdk_releases]: https://developer.android.com/games/agdk/download#agdk-libraries |
151 | | -[Gradle]: https://developer.android.com/studio/build |
152 | | - |
153 | | -For more details, refer to these `android-activity` [example applications](https://github.com/rib/android-activity/tree/main/examples). |
154 | | - |
155 | | -##### Converting from `ndk-glue` to `android-activity` |
156 | | - |
157 | | -If your application is currently based on `NativeActivity` via the `ndk-glue` crate and building with `cargo apk`, then the minimal changes would be: |
158 | | -1. Remove `ndk-glue` from your `Cargo.toml` |
159 | | -2. Enable the `"android-native-activity"` feature for Winit: `winit = { version = "0.29.4", features = [ "android-native-activity" ] }` |
160 | | -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). |
161 | | -4. Pass a clone of the `AndroidApp` that your application receives to Winit when building your event loop (as shown above). |
162 | | - |
163 | | -#### MacOS |
164 | | - |
165 | | -A lot of functionality expects the application to be ready before you start |
166 | | -doing anything; this includes creating windows, fetching monitors, drawing, |
167 | | -and so on, see issues [#2238], [#2051] and [#2087]. |
168 | | - |
169 | | -If you encounter problems, you should try doing your initialization inside |
170 | | -`Event::Resumed`. |
171 | | - |
172 | | -#### iOS |
173 | | - |
174 | | -Similar to macOS, iOS's main `UIApplicationMain` does some init work that's required |
175 | | -by all UI-related code (see issue [#1705]). It would be best to consider creating your windows |
176 | | -inside `Event::Resumed`. |
177 | | - |
178 | | - |
179 | | -[#2238]: https://github.com/rust-windowing/winit/issues/2238 |
180 | | -[#2051]: https://github.com/rust-windowing/winit/issues/2051 |
181 | | -[#2087]: https://github.com/rust-windowing/winit/issues/2087 |
182 | | -[#1705]: https://github.com/rust-windowing/winit/issues/1705 |
183 | | - |
184 | | -#### Redox OS |
185 | | - |
186 | | -Redox OS has some functionality not yet present that will be implemented when |
187 | | -its orbital display server provides it. |
| 3 | +Floem depends on winit changes that haven't been upstreamed. To make Floem publishable on crates.io, all its dependencies have to be published there - hence this unofficial crate. |
0 commit comments