Reeling in no_std and no_web virality

[cart]

Bevy increasingly has "no std" (supports platforms that don't have an std impl) and "no web" (supports wasm builds that don't have access to the full web). This is really cool!

However I think the "virality" of both std and web features (and the proliferation of them in our codebase) is a maintenance liability and an "ecosystem UX" liability. Writing a new crate that supports these platforms requires intimate knowledge of the patterns we use to support them, what Bevy crates currently support them, and how to wire everything up to ensure you enable these features in the relevant crates.

Things like this are now everywhere in our codebase:

bevy_animation = { path = "../bevy_animation", version = "0.16.0-dev", optional = true }
bevy_app = { path = "../bevy_app", version = "0.16.0-dev" }
bevy_asset = { path = "../bevy_asset", version = "0.16.0-dev" }
bevy_color = { path = "../bevy_color", version = "0.16.0-dev" }
bevy_core_pipeline = { path = "../bevy_core_pipeline", version = "0.16.0-dev" }
bevy_ecs = { path = "../bevy_ecs", version = "0.16.0-dev" }
bevy_image = { path = "../bevy_image", version = "0.16.0-dev" }
bevy_math = { path = "../bevy_math", version = "0.16.0-dev" }
bevy_mesh = { path = "../bevy_mesh", version = "0.16.0-dev" }
bevy_pbr = { path = "../bevy_pbr", version = "0.16.0-dev" }
bevy_reflect = { path = "../bevy_reflect", version = "0.16.0-dev" }
bevy_render = { path = "../bevy_render", version = "0.16.0-dev" }
bevy_scene = { path = "../bevy_scene", version = "0.16.0-dev", features = [
  "bevy_render",
] }
bevy_transform = { path = "../bevy_transform", version = "0.16.0-dev" }
bevy_tasks = { path = "../bevy_tasks", version = "0.16.0-dev" }
bevy_utils = { path = "../bevy_utils", version = "0.16.0-dev" }
bevy_platform_support = { path = "../bevy_platform_support", version = "0.16.0-dev", default-features = false, features = [
  "std",
  "serialize",
] }

[target.'cfg(target_arch = "wasm32")'.dependencies]
bevy_log = { path = "../bevy_log", version = "0.16.0-dev", default-features = false, features = [
  "web",
] }
bevy_app = { path = "../bevy_app", version = "0.16.0-dev", default-features = false, features = [
  "web",
] }
bevy_platform_support = { path = "../bevy_platform_support", version = "0.16.0-dev", default-features = false, features = [
  "web",
] }
bevy_reflect = { path = "../bevy_reflect", version = "0.16.0-dev", default-features = false, features = [
  "web",
] }
bevy_tasks = { path = "../bevy_tasks", version = "0.16.0-dev", default-features = false, features = [
  "web",
] }

Every time you add some bevy_x dependency (either official or 3rd party), you need to ask yourself:

1. Does this have no_std support? If yes, create a "std" feature in your crate, and ensure you enable bevy_x/std feature when that is enabled.
2. Does this have "no web" support? If yes, create a "web" feature in your crate and ensure you enable "bevy_x/web" when it is enabled.
3. Does my crate assume web support? If yes, ensure you enable bevy_x/web when building for the wasm32 target.

Likewise having #[cfg(feature = "std")] and #[cfg(feature = "web")] everywhere significantly affects legibility and maintainability.

I think the way these things are framed (optional, but "viral" cargo features) is correct, but I think we should investigate scoping down which crates needs to care about this (and in an ideal world, no crates need to care about this). If we had a single place that handled these platform specific concerns and provided platform agnostic interfaces consumers can code to (as in, the code compiles regardless of no_std / web-ness), then that crate wouldn't need to explicitly worry about platform configuration at all. Instead, the end user (or the bevy crate) could define the "web" / "std" features directly on that crate.

That way the interface could be this for crates that depend on "core" bevy crates :

[package]
name = "my_bevy_plugin"

[dependencies]
bevy_app = "0.16"
bevy_ecs = "0.16"
bevy_asset = "0.16"

Likewise consumers of "my_bevy_plugin" could just do

my_bevy_plugin = "1.0"

And then the top level app could do:

bevy_app = "0.16"
bevy_ecs = "0.16"
my_bevy_plugin = "1.0"
# bevy_platform_support defaults to "std" and "web", so this is no_std and no_web
bevy_platform_support = { version = "0.16",  default-features = false }

Or alternatively:

# bevy would default to "std" and "web"
bevy = "0.16"
my_bevy_plugin = "1.0"

Or

# this is "std", but "no web"
bevy = { version = "0.16", default-features = false, features = ["std"] }
my_bevy_plugin = "1.0"

The downside here is that all std and web functionality would need to live in bevy_platform_support (risking compile time bottlenecking), and we'd need to ensure that we expose platform agnostic interfaces. This is a technical challenge, but not necessarily insurmountable.

It also wouldn't necessarily need to be exhaustive. We could focus on the low hanging fruit and piecemeal port things over to that paradigm, which could reduce how "deep" the roots currently go.

To keep bevy_platform_support slim, we could feature gate what it provides (ex: a "log" feature, a "collections" feature, etc).

I'll note that pretty much every platform-agnostic app framework builds interfaces like this (and we already use this approach in plenty of places, we're just overly leaky atm) .

In practice, this would result in writing some APIs that do nothing on some platforms, adding runtime if bevy_platform_support::IS_WEB { } checks (which would be const), etc.

[bushrat011899]

As patient zero of this viral outbreak, I completely agree with your assessment of the situation. Here are some solutions I can think of in no particular order:

Remove the features as much as possible

The fewer crates that care about a feature, the easier it is to manage. This would require a bottom-up approach where we stabilize the public API across platforms through a combination of runtime feature detection and polyfills (like portable-atomic, spin, etc.).

Put the features everywhere!

We might not be able to remove the boilerplate, but standardizing on a set of features for every crate would make it consistent, removing the guess work from the equation. That is, add a web feature to all crates even if it's a no-op.

Environment variables and/or features

Cargo environment variables can be set once and read at compile time just like feature flags, but with the added benefit of being visible across all dependencies. Perhaps we could control these features using the Bevy CLI tool, or some build.rs wizardry.

portable-atomic-styled macros

portable-atomic has a series of macro_rules macros you can use to conditionally compile code based on what the target supports without the need for features in the consuming crate. Effectively, they turn code into a no-op in the negative case, or pass the code as-is in the positive. We could build similar cfg_std! {...}, cfg_no_std! {...} macros in bevy_platform_support and control them with feature flags only on that crate.

This doesn't handle conditional dependencies tho, so we still need to be careful in that regard.

[cart]

I'm currently on team "remove the features as much as possible", with standardization of APIs under the bevy_platform_support crate (maybe with a "friendlier" rename to bevy::platform or bevy::core ).

We could build similar cfg_std! {...}, cfg_no_std! {...} macros in bevy_platform_support and control them with feature flags only on that crate

Yeah this might be better than if bevy_platform_support::IS_WEB {}. But its worth looking at the codegen as IS_WEB is better ux.

[bushrat011899]

Could do both, since cfg_web! would also handle cases where code is invalid (since it gets deleted by the macro). So for example, bevy_platform_support could re-export js_sys for the browser API bindings but only with the bevy_platform_support/web feature. Then, cfg_web! could safely assume the existence of bevy_platform_support::js_sys, since the code will be deleted when bevy_platform_support/web isn't enabled.

So if IS_WEB { ... } for branching but legal behaviour, and cfg_web! { ... } for behaviour only legal on web.

[bushrat011899]

Also +1 on bevy_platform. bevy_core already existed as a crate so that might cause issues with people migrating from much older versions of Bevy. bevy_platform_support was chosen before its utility was fully understood, so a rename is probably warranted. Shame we can't just claim btd as "Bevy's Standard Library" lol.

[TimJentzsch]

Perhaps we could control these features using the Bevy CLI tool [...]

Please note that it's one goal of the Bevy CLI to be "as optional as possible", i.e. we want to keep things as ergonomic as possible for users who don't want to use it (for whatever reason).
So if there is a way to simplify this without complicating the workflow for pure cargo users, I think we should strive to prefer that approach.

[NWPlayer123]

How much is no_alloc factoring into all this? To my understanding, no_std means no sync primitives and no OS-specific features (std::sys and std::os), but that leaves both core and alloc. Some crates are no_alloc as well, which involves things like using heapless to allocate e.g. Vecs onto the stack, but that also comes with significant limitations, and I'd hate to slow down development speed with those hurdles.

[cart]

Pretty much everything Bevy does involves allocation, down to the core ECS level. Imo this isn't worth worrying about.

[bushrat011899]

For the very few crates that Bevy has which do have no_alloc support (bevy_ptr, bevy_utils, bevy_platform_support, bevy_color) whatever technique we use to minimise the problem for std/web/etc. should equally apply to alloc, just with much lower stakes.

[cart]

I put together a bevy_platform consolidation branch that starts to reel this in:
https://github.com/cart/bevy/commits/bevy-platform-consolidation/

[bushrat011899]

Have an initial PR for better feature management and a bottom-up feature communication paradigm here.

[JMS55]

One thing that would be nice to address is imports. It's annoying to have to manually make sure I use core imports and not std.

[bushrat011899]

Do you have any examples of this happening? There should be some Clippy lints that highlight exactly what items should come from core or alloc instead of std.

The only alternative I can think of would be to never have extern crate std; and instead re-export the std contents from bevy_platform, but that's pretty drastic and might be harder to work with...