cc69fdd0c6
# Objective - Fixes #15460 (will open new issues for further `no_std` efforts) - Supersedes #17715 ## Solution - Threaded in new features as required - Made certain crates optional but default enabled - Removed `compile-check-no-std` from internal `ci` tool since GitHub CI can now simply check `bevy` itself now - Added CI task to check `bevy` on `thumbv6m-none-eabi` to ensure `portable-atomic` support is still valid [^1] [^1]: This may be controversial, since it could be interpreted as implying Bevy will maintain support for `thumbv6m-none-eabi` going forward. In reality, just like `x86_64-unknown-none`, this is a [canary](https://en.wiktionary.org/wiki/canary_in_a_coal_mine) target to make it clear when `portable-atomic` no longer works as intended (fixing atomic support on atomically challenged platforms). If a PR comes through and makes supporting this class of platforms impossible, then this CI task can be removed. I however wager this won't be a problem. ## Testing - CI --- ## Release Notes Bevy now has support for `no_std` directly from the `bevy` crate. Users can disable default features and enable a new `default_no_std` feature instead, allowing `bevy` to be used in `no_std` applications and libraries. ```toml # Bevy for `no_std` platforms bevy = { version = "0.16", default-features = false, features = ["default_no_std"] } ``` `default_no_std` enables certain required features, such as `libm` and `critical-section`, and as many optional crates as possible (currently just `bevy_state`). For atomically-challenged platforms such as the Raspberry Pi Pico, `portable-atomic` will be used automatically. For library authors, we recommend depending on `bevy` with `default-features = false` to allow `std` and `no_std` users to both depend on your crate. Here are some recommended features a library crate may want to expose: ```toml [features] # Most users will be on a platform which has `std` and can use the more-powerful `async_executor`. default = ["std", "async_executor"] # Features for typical platforms. std = ["bevy/std"] async_executor = ["bevy/async_executor"] # Features for `no_std` platforms. libm = ["bevy/libm"] critical-section = ["bevy/critical-section"] [dependencies] # We disable default features to ensure we don't accidentally enable `std` on `no_std` targets, for example. bevy = { version = "0.16", default-features = false } ``` While this is verbose, it gives the maximum control to end-users to decide how they wish to use Bevy on their platform. We encourage library authors to experiment with `no_std` support. For libraries relying exclusively on `bevy` and no other dependencies, it may be as simple as adding `#![no_std]` to your `lib.rs` and exposing features as above! Bevy can also provide many `std` types, such as `HashMap`, `Mutex`, and `Instant` on all platforms. See `bevy::platform_support` for details on what's available out of the box! ## Migration Guide - If you were previously relying on `bevy` with default features disabled, you may need to enable the `std` and `async_executor` features. - `bevy_reflect` has had its `bevy` feature removed. If you were relying on this feature, simply enable `smallvec` and `smol_str` instead. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2.9 KiB
Bevy Platform Support
Rust is a fantastic multi-platform language with extensive support for modern targets through its standard library.
However, some items within the standard library have alternatives that are better suited for Bevy and game engines in general.
Additionally, to support embedded and other esoteric platforms, it's often necessary to shed reliance on std, making your crate no_std.
These needs are handled by this crate, bevy_platform_support.
The goal of this crate is to provide alternatives and extensions to the Rust standard library which minimize friction when developing with and for Bevy across multiple platforms.
Getting Started
Like any dependency from crates.io, use cargo to add it to your Cargo.toml file:
cargo add bevy_platform_support
Now, instead of importing from std you can use bevy_platform_support for items it has alternative for.
See the documentation for what items are available, and explanations for why you may want to use them.
no_std Support
By default, bevy_platform_support will activate the std feature, requiring access to the std crate for whichever platforms you're targeting.
To use this crate on no_std platforms, disable default features:
bevy_platform_support = { version = "x.y.z", default-features = false }
Features
std (default)
Enables usage of the standard library. Note that where this crate has alternatives to the standard library that it considers better than what's provided, it will provide the alternative even when std is enabled.
This is explicitly incompatible with no_std targets.
alloc (default)
Enables usage of the alloc crate. Note that this feature is automatically enabled when enabling std.
This is compatible with most no_std targets, but not all.
critical-section
Switches to using critical-section as a backend for synchronization.
You may need to enable this feature on platforms with little to no support for atomic operations.