aadd3a3ec2
# Objective - Acts on certain elements of #18799 - Closes #1615 - New baseline for #18170 ## Solution - Created a new `cfg` module in `bevy_platform` which contains two macros to aid in working with features like `web`, `std`, and `alloc`. - `switch` is a stable implementation of [`cfg_match`](https://doc.rust-lang.org/std/macro.cfg_match.html), which itself is a `core` alternative to [`cfg_if`](https://docs.rs/cfg-if). - `define_alias` is a `build.rs`-free alternative to [`cfg_aliases`](https://docs.rs/cfg_aliases) with the ability to share feature information between crates. - Switched to these macros within `bevy_platform` to demonstrate usage. ## Testing - CI --- ## Showcase Consider the typical `std` feature as an example of a "virality". With just `bevy_platform`, `bevy_utils`, and `bevy_ecs`, we have 3 crates in a chain where activating `std` in any of them should really activate it everywhere. The status-quo for this is for each crate to define its own `std` feature, and ensure it includes the `std` feature of every dependency in that feature. For crates which don't even interact with `std` directly, this can be quite cumbersome. Especially considering that Bevy has a fundamental crate, `bevy_platform`, which is a dependency for effectively every crate. Instead, we can use `define_alias` to create a macro which will conditionally compile code if and only if the specified configuration condition is met _in the defining crate_. ```rust // In `bevy_platform` define_alias! { #[cfg(feature = "std")] => { /// Indicates the `std` crate is available and can be used. std } #[cfg(all(target_arch = "wasm32", feature = "web"))] => { /// Indicates that this target has access to browser APIs. web } } ``` The above `web` and `std` macros will either no-op the provided code if the conditions are not met, or pass it unmodified if it is met. Since it is evaluated in the context of the defining crate, `bevy_platform/std` can be used to conditionally compile code in `bevy_utils` and `bevy_ecs` _without_ those crates including their own `std` features. ```rust // In `bevy_utils` use bevy_platform::cfg; // If `bevy_platform` has `std`, then we can too! cfg::std! { extern crate std; } ``` To aid in more complex configurations, `switch` is provided to provide a `cfg_if` alternative that is compatible with `define_alias`: ```rust use bevy_platform::cfg; cfg::switch! { #[cfg(feature = "foo")] => { /* use the foo API */ } cfg::web => { /* use browser API */ } cfg::std => { /* use std */ } _ => { /* use a fallback implementation */ } } ``` This paradigm would allow Bevy's sub-crates to avoid re-exporting viral features, and also enable functionality in response to availability in their dependencies, rather than from explicit features (bottom-up instead of top-down). I imagine that a "full rollout" of this paradigm would remove most viral features from Bevy's crates, leaving only `bevy_platform`, `bevy_internal`, and `bevy` (since `bevy`/`_internal` are explicitly re-exports of all of Bevy's crates). This bottom-up approach may be useful in other areas of Bevy's features too. For example, `bevy_core_pipeline/tonemapping_luts` requires: - bevy_render/ktx2 - bevy_image/ktx2 - bevy_image/zstd If `define_alias` was used in `bevy_image`, `bevy_render` would not need to re-export the `ktx2` feature, and `bevy_core_pipeline` could directly probe `bevy_image` for the status of `ktx2` and `zstd` features to determine if it should compile the `tonemapping_luts` functionality, rather than having an explicitly feature. Of course, an explicit feature is still important for _features_, so this may not be the best example, but it highlights that with this paradigm crates can reactively provide functionality, rather than needing to proactively declare feature combinations up-front and hope the user enables them. --------- Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com>
89 lines
2.7 KiB
TOML
89 lines
2.7 KiB
TOML
[package]
|
|
name = "bevy_platform"
|
|
version = "0.16.0-dev"
|
|
edition = "2024"
|
|
description = "Provides common platform agnostic APIs, as well as platform-specific features for Bevy Engine"
|
|
homepage = "https://bevyengine.org"
|
|
repository = "https://github.com/bevyengine/bevy"
|
|
license = "MIT OR Apache-2.0"
|
|
keywords = ["bevy"]
|
|
|
|
[features]
|
|
default = ["std"]
|
|
|
|
# Functionality
|
|
|
|
## Adds serialization support through `serde`.
|
|
serialize = ["dep:serde", "hashbrown/serde"]
|
|
|
|
## Adds integration with Rayon.
|
|
rayon = ["dep:rayon", "hashbrown/rayon"]
|
|
|
|
# Platform Compatibility
|
|
|
|
## Allows access to the `std` crate. Enabling this feature will prevent compilation
|
|
## on `no_std` targets, but provides access to certain additional features on
|
|
## supported platforms.
|
|
std = [
|
|
"alloc",
|
|
"critical-section?/std",
|
|
"portable-atomic/std",
|
|
"portable-atomic-util/std",
|
|
"spin/std",
|
|
"foldhash/std",
|
|
"serde?/std",
|
|
]
|
|
|
|
## Allows access to the `alloc` crate.
|
|
alloc = ["portable-atomic-util/alloc", "dep:hashbrown", "serde?/alloc"]
|
|
|
|
## `critical-section` provides the building blocks for synchronization primitives
|
|
## on all platforms, including `no_std`.
|
|
critical-section = ["dep:critical-section", "portable-atomic/critical-section"]
|
|
|
|
## Enables use of browser APIs.
|
|
## Note this is currently only applicable on `wasm32` architectures.
|
|
web = ["dep:web-time", "dep:getrandom"]
|
|
|
|
[dependencies]
|
|
critical-section = { version = "1.2.0", default-features = false, optional = true }
|
|
spin = { version = "0.10.0", default-features = false, features = [
|
|
"mutex",
|
|
"spin_mutex",
|
|
"rwlock",
|
|
"once",
|
|
"lazy",
|
|
"barrier",
|
|
] }
|
|
foldhash = { version = "0.1.3", default-features = false }
|
|
hashbrown = { version = "0.15.1", features = [
|
|
"equivalent",
|
|
"raw-entry",
|
|
], optional = true, default-features = false }
|
|
serde = { version = "1", default-features = false, optional = true }
|
|
rayon = { version = "1", default-features = false, optional = true }
|
|
|
|
[target.'cfg(target_arch = "wasm32")'.dependencies]
|
|
web-time = { version = "1.1", default-features = false, optional = true }
|
|
getrandom = { version = "0.2.0", default-features = false, optional = true, features = [
|
|
"js",
|
|
] }
|
|
|
|
[target.'cfg(not(all(target_has_atomic = "8", target_has_atomic = "16", target_has_atomic = "32", target_has_atomic = "64", target_has_atomic = "ptr")))'.dependencies]
|
|
portable-atomic = { version = "1", default-features = false, features = [
|
|
"fallback",
|
|
] }
|
|
spin = { version = "0.10.0", default-features = false, features = [
|
|
"portable-atomic",
|
|
] }
|
|
|
|
[target.'cfg(not(target_has_atomic = "ptr"))'.dependencies]
|
|
portable-atomic-util = { version = "0.2.4", default-features = false }
|
|
|
|
[lints]
|
|
workspace = true
|
|
|
|
[package.metadata.docs.rs]
|
|
rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
|
|
all-features = true
|