From 558ceecbf79cc9e49fe096f030516e698cfc0102 Mon Sep 17 00:00:00 2001 From: Stephen Martindale Date: Mon, 16 Jan 2023 15:40:35 +0100 Subject: [PATCH 1/4] Documented effect of WinitSettings::return_from_run. --- crates/bevy_app/src/app.rs | 18 +++++++++++++++++ crates/bevy_winit/src/winit_config.rs | 29 +++++++++++++++++++-------- examples/app/return_after_run.rs | 12 +++++++++++ 3 files changed, 51 insertions(+), 8 deletions(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 2a47aabb964c0..4f78bef689f15 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -178,6 +178,24 @@ impl App { /// Finalizes the [`App`] configuration. For general usage, see the example on the item /// level documentation. /// + /// # `run()` might not return + /// + /// Calls to [`App::run()`] might never return. + /// + /// In simple and *headless* applications, one can expect that execution will + /// proceed, normally, after calling [`run()`](App::run()) but this is not the case for + /// windowed applications. + /// + /// Windowed apps are typically driven by an *event loop* or *message loop* and + /// some window-manager APIs expect programs to terminate when their primary + /// window is closed and that event loop terminates – behaviour of processes that + /// do not is often platform dependent or undocumented. + /// + /// By default, *Bevy* uses the `winit` *crate* for window creation. See + /// [`WinitSettings::return_from_run`](https://docs.rs/bevy/latest/bevy/winit/struct.WinitSettings.html#structfield.return_from_run) + /// for further discussion of this topic and for a mechanism to require that [`App::run()`] + /// *does* return – albeit one that carries its own caveats and disclaimers. + /// /// # Panics /// /// Panics if called from `Plugin::build()`, because it would prevent other plugins to properly build. diff --git a/crates/bevy_winit/src/winit_config.rs b/crates/bevy_winit/src/winit_config.rs index c1db2b2fd27e6..40bfd1f87323b 100644 --- a/crates/bevy_winit/src/winit_config.rs +++ b/crates/bevy_winit/src/winit_config.rs @@ -4,15 +4,28 @@ use bevy_utils::Duration; /// A resource for configuring usage of the `rust_winit` library. #[derive(Debug, Resource)] pub struct WinitSettings { - /// Configures the winit library to return control to the main thread after the - /// [run](bevy_app::App::run) loop is exited. Winit strongly recommends avoiding this when - /// possible. Before using this please read and understand the - /// [caveats](winit::platform::run_return::EventLoopExtRunReturn::run_return) in the winit - /// documentation. + /// Configures `winit` to return control to the caller after exiting the + /// event loop, enabling [`App::run()`](bevy_app::App::run()) to return. /// - /// This feature is only available on desktop `target_os` configurations. Namely `windows`, - /// `macos`, `linux`, `dragonfly`, `freebsd`, `netbsd`, and `openbsd`. If set to true on an - /// unsupported platform [run](bevy_app::App::run) will panic. + /// By default, [`return_from_run`](Self::return_from_run) is `false` and *Bevy* + /// will use `winit`'s + /// [`EventLoop::run()`](https://docs.rs/winit/latest/winit/event_loop/struct.EventLoop.html#method.run) + /// to initiate the event loop. + /// [`EventLoop::run()`](https://docs.rs/winit/latest/winit/event_loop/struct.EventLoop.html#method.run) + /// will never return but will terminate the process after the event loop exits. + /// + /// Setting [`return_from_run`](Self::return_from_run) to `true` will cause *Bevy* + /// to use `winit`'s + /// [`EventLoopExtRunReturn::run_return()`](https://docs.rs/winit/latest/winit/platform/run_return/trait.EventLoopExtRunReturn.html#tymethod.run_return) + /// instead which is strongly discouraged by the `winit` authors. + /// + /// # Supported platforms + /// + /// This feature is only available on the following desktop `target_os` configurations: + /// `windows`, `macos`, `linux`, `dragonfly`, `freebsd`, `netbsd`, and `openbsd`. + /// + /// Setting [`return_from_run`](Self::return_from_run) to `true` on + /// unsupported platforms will cause [`App::run()`](bevy_app::App::run()) to panic! pub return_from_run: bool, /// Configures how the winit event loop updates while the window is focused. pub focused_mode: UpdateMode, diff --git a/examples/app/return_after_run.rs b/examples/app/return_after_run.rs index 966659688655e..fd96fa74746a2 100644 --- a/examples/app/return_after_run.rs +++ b/examples/app/return_after_run.rs @@ -1,4 +1,16 @@ //! Shows how to return to the calling function after a windowed Bevy app has exited. +//! +//! In windowed *Bevy* applications, executing code below a call to `App::run()` is +//! not recommended because `App::run()` might never return. +//! +//! This example demonstrates the use of `WinitSettings::return_from_run` to +//! require that `App::run()` *does* return but this is not recommended. Be sure +//! to read the documentation on both `App::run()` and `WinitSettings::return_from_run` +//! for caveats and further details: +//! +//! - https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.run +//! - https://docs.rs/bevy/latest/bevy/winit/struct.WinitSettings.html#structfield.return_from_run + use bevy::{prelude::*, winit::WinitSettings}; From e4643fb0577c64a739091cee6e9104b9ebb15a9d Mon Sep 17 00:00:00 2001 From: Stephen Martindale Date: Mon, 16 Jan 2023 16:06:47 +0100 Subject: [PATCH 2/4] Fixed white-space blunder. --- examples/app/return_after_run.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/app/return_after_run.rs b/examples/app/return_after_run.rs index fd96fa74746a2..4a696c34b005a 100644 --- a/examples/app/return_after_run.rs +++ b/examples/app/return_after_run.rs @@ -11,7 +11,6 @@ //! - https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.run //! - https://docs.rs/bevy/latest/bevy/winit/struct.WinitSettings.html#structfield.return_from_run - use bevy::{prelude::*, winit::WinitSettings}; fn main() { From f24b4cc6d8cbfaba4b877d8edcc07a08d17d038e Mon Sep 17 00:00:00 2001 From: Stephen Martindale Date: Mon, 16 Jan 2023 16:16:10 +0100 Subject: [PATCH 3/4] Wrapped bare URLs in comments. --- examples/app/return_after_run.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/app/return_after_run.rs b/examples/app/return_after_run.rs index 4a696c34b005a..f1fc07b50c5c3 100644 --- a/examples/app/return_after_run.rs +++ b/examples/app/return_after_run.rs @@ -8,8 +8,8 @@ //! to read the documentation on both `App::run()` and `WinitSettings::return_from_run` //! for caveats and further details: //! -//! - https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.run -//! - https://docs.rs/bevy/latest/bevy/winit/struct.WinitSettings.html#structfield.return_from_run +//! - +//! - use bevy::{prelude::*, winit::WinitSettings}; From f758ee479318988912faf248dd0fb838033b5f8e Mon Sep 17 00:00:00 2001 From: Stephen Martindale Date: Tue, 17 Jan 2023 14:49:38 +0100 Subject: [PATCH 4/4] Update crates/bevy_app/src/app.rs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: François --- crates/bevy_app/src/app.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 4f78bef689f15..a8db6bfc042f1 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -191,7 +191,7 @@ impl App { /// window is closed and that event loop terminates – behaviour of processes that /// do not is often platform dependent or undocumented. /// - /// By default, *Bevy* uses the `winit` *crate* for window creation. See + /// By default, *Bevy* uses the `winit` crate for window creation. See /// [`WinitSettings::return_from_run`](https://docs.rs/bevy/latest/bevy/winit/struct.WinitSettings.html#structfield.return_from_run) /// for further discussion of this topic and for a mechanism to require that [`App::run()`] /// *does* return – albeit one that carries its own caveats and disclaimers.