Cargo Feature Collections (#21472)

## Objective

Users of the `bevy` crate currently live one of two lifestyles:

1. Use all of Bevy's default features, potentially compiling many
features you don't need or don't want. If there is a feature you _cannot
have_ in your app, you must move on to option (2)
2. Disable Bevy's default features, and compose the complete list of
features yourself.

Living in the world of (2) is an exercise in frustration, as the list of
required features to accomplish a given task changes regularly across
releases as we add and change features. This is an _expert level_ task
that requires intimate knowledge of engine internals to get right. Even
I, Bevy's lead developer, would struggle here. To the point that I would
never voluntarily choose to disable Bevy's default features.

Most games/apps are 2D-only, 3D-only, or UI-only and don't require the
full set of features. We cannot currently in good conscience recommend
that those developers live in the "no default features" world. That is a
fast track to pain, suffering, and perhaps a quick exit from the Bevy
ecosystem.

The same problem exists for developers that want to build their own Bevy
renderer or replace Bevy UI with their own framework. Once again, we
_cannot_ recommend that those developers manage every Bevy feature
themselves.

Fixes: #21369
Alternative to: #20741 #21236

## Solution

Define a "standalone" set of features that enable Bevy developers to
disable default features, then opt in to the funtionality they want. The
"default" `bevy` feature set is now just:

```toml
default = ["2d", "3d", "ui"]
```

This enables developers to select only the features they need. For
example, a UI-only app would look like this:

```toml
bevy = { version = "0.17", default-features = false, features = [ "ui" ] }
```

"2d", "3d", and "ui" each contain the "full" Bevy experience for that
domain. This also includes:
- `default_platform`: the default "platform support" features (see docs)
- `default_app`: the default "app framework" features (see docs)

For developers that do not want the default bevy render / platform / app
functionality, this breaks down further into:

- `common_api`: common / core backend-less user-facing Bevy render api
- `2d_api`: common / core backend-less user-facing Bevy 2d api
- `3d_api`: common / core backend-less user-facing Bevy 3d api
- `ui_api`: common / core backend-less user-facing Bevy ui api

(and many others)

I've also added the `dev` feature to this PR, which enables the
recommended "dev only" features like dynamic linking, asset watching /
hot reloading, and dev / debug tools. Including dynamic linking is a bit
controversial here given that it doesn't work everywhere. But I'd like
to aggressively push people into the dynamic linking workflow wherever
possible, as developing without it is signficantly worse. And removing a
single `dev` feature is a much simpler release workflow.

---------

Co-authored-by: atlv <[email protected]>

Author: cart

Cargo.toml

@@ -125,65 +125,149 @@ unsafe_op_in_unsafe_fn = "warn"
 unused_qualifications = "warn"
 
 [features]
-default = [
-  "std",
+default = ["2d", "3d", "ui"]
+
+# PROFILE: The default 2D Bevy experience. This includes the core Bevy framework, 2D functionality, Bevy UI, scenes, audio, and picking.
+2d = [
+  "default_app",
+  "default_platform",
+  "2d_api",
+  "2d_bevy_render",
+  "ui",
+  "scene",
+  "audio",
+  "picking",
+]
+
+# PROFILE: The default 3D Bevy experience. This includes the core Bevy framework, 3D functionality, Bevy UI, scenes, audio, and picking.
+3d = [
+  "default_app",
+  "default_platform",
+  "3d_api",
+  "3d_bevy_render",
+  "ui",
+  "scene",
+  "audio",
+  "picking",
+]
+
+# PROFILE: The default Bevy UI experience.  This includes the core Bevy framework, Bevy UI, scenes, audio, and picking.
+ui = [
+  "default_app",
+  "default_platform",
+  "ui_api",
+  "ui_bevy_render",
+  "scene",
+  "audio",
+  "picking",
+]
+
+# COLLECTION: Enable this feature during development to improve the development experience. This adds features like asset hot-reloading and debugging tools. This should not be enabled for published apps!
+dev = [
+  "debug",          # TODO: rename this to something more specific ... this is a "debug ECS names" feature
+  "bevy_dev_tools",
+  "file_watcher",
+]
+
+# COLLECTION: Features used to build audio Bevy apps.
+audio = ["bevy_audio", "vorbis"]
+
+# COLLECTION: Features used to compose Bevy scenes.
+scene = ["bevy_scene"]
+
+# COLLECTION: Enables picking functionality
+picking = ["bevy_picking", "mesh_picking", "sprite_picking", "ui_picking"]
+
+# COLLECTION: The core pieces that most apps need. This serves as a baseline feature set for other higher level feature collections (such as "2d" and "3d"). It is also useful as a baseline feature set for scenarios like headless apps that require no rendering (ex: command line tools, servers, etc).
+default_app = [
   "async_executor",
+  "bevy_asset",
+  "bevy_input_focus",
+  "bevy_log",
+  "bevy_state",
+  "bevy_window",
+  "custom_cursor",
+  "reflect_auto_register",
+]
+
+# COLLECTION: These are platform support features, such as OS support/features, windowing and input backends, etc.
+default_platform = [
+  "std",
   "android-game-activity",
   "android_shared_stdcxx",
-  "gltf_animation",
-  "bevy_asset",
-  "bevy_audio",
-  "bevy_color",
-  "bevy_core_pipeline",
-  "bevy_post_process",
-  "bevy_anti_alias",
   "bevy_gilrs",
+  "bevy_winit",
+  "default_font",
+  "multi_threaded",
+  "webgl2",
+  "x11",
+  "wayland",
+  "sysinfo_plugin",
+]
+
+# COLLECTION: Default scene definition features. Note that this does not include an actual renderer, such as bevy_render (Bevy's default render backend).
+common_api = [
+  "bevy_animation",
+  "bevy_camera",
+  "bevy_color",
   "bevy_gizmos",
-  "bevy_gltf",
-  "bevy_input_focus",
-  "bevy_log",
-  "bevy_pbr",
-  "bevy_picking",
-  "bevy_render",
-  "bevy_scene",
   "bevy_image",
   "bevy_mesh",
-  "bevy_mikktspace",
-  "bevy_camera",
-  "bevy_light",
   "bevy_shader",
-  "bevy_sprite",
-  "bevy_sprite_render",
-  "bevy_state",
   "bevy_text",
-  "bevy_ui",
-  "bevy_ui_render",
-  "bevy_window",
-  "bevy_winit",
-  "custom_cursor",
-  "default_font",
   "hdr",
+  "png",
+]
+
+# COLLECTION: Features used to build 2D Bevy apps (does not include a render backend). You generally don't need to worry about this unless you are using a custom renderer.
+2d_api = ["common_api", "bevy_sprite"]
+
+# COLLECTION: Bevy's built-in 2D renderer, built on top of `bevy_render` 
+2d_bevy_render = [
+  "2d_api",
+  "bevy_render",
+  "bevy_core_pipeline",
+  "bevy_post_process",
+  "bevy_sprite_render",
+]
+
+# COLLECTION: Features used to build 3D Bevy apps (does not include a render backend). You generally don't need to worry about this unless you are using a custom renderer.
+3d_api = [
+  "common_api",
+  "bevy_light",
+  "bevy_mikktspace",
   "ktx2",
-  "mesh_picking",
-  "morph",
   "morph_animation",
-  "multi_threaded",
-  "png",
-  "reflect_auto_register",
+  "morph",
   "smaa_luts",
-  "sprite_picking",
-  "sysinfo_plugin",
   "tonemapping_luts",
-  "ui_picking",
-  "vorbis",
-  "webgl2",
-  "x11",
-  "wayland",
-  "debug",
   "zstd_rust",
 ]
 
-# Recommended defaults for no_std applications
+# COLLECTION: Bevy's built-in 3D renderer, built on top of `bevy_render` 
+3d_bevy_render = [
+  "3d_api",
+  "bevy_render",
+  "bevy_core_pipeline",
+  "bevy_anti_alias",
+  "bevy_gltf",
+  "bevy_pbr",
+  "bevy_post_process",
+  "gltf_animation",
+]
+
+# COLLECTION: Features used to build UI Bevy apps (does not include a render backend). You generally don't need to worry about this unless you are using a custom renderer.
+ui_api = ["default_app", "common_api", "bevy_ui"]
+
+# COLLECTION: Bevy's built-in UI renderer, built on top of `bevy_render` 
+ui_bevy_render = [
+  "ui_api",
+  "bevy_render",
+  "bevy_core_pipeline",
+  "bevy_ui_render",
+]
+
+# COLLECTION: Recommended defaults for no_std applications
 default_no_std = ["libm", "critical-section", "bevy_color", "bevy_state"]
 
 # Provides an implementation for picking meshes

crates/bevy_internal/Cargo.toml

@@ -321,10 +321,10 @@ bevy_picking = ["dep:bevy_picking"]
 mesh_picking = ["bevy_picking", "bevy_picking/mesh_picking"]
 
 # Provides a sprite picking backend
-sprite_picking = ["bevy_picking", "bevy_sprite/bevy_picking"]
+sprite_picking = ["bevy_picking", "bevy_sprite?/bevy_picking"]
 
 # Provides a UI picking backend
-ui_picking = ["bevy_picking", "bevy_ui/bevy_picking"]
+ui_picking = ["bevy_picking", "bevy_ui?/bevy_picking"]
 
 # Provides a UI debug overlay
 bevy_ui_debug = ["bevy_ui_render?/bevy_ui_debug"]

docs-template/features.md.tpl

@@ -4,19 +4,42 @@
 
 ## Cargo Features
 
-Bevy exposes many features to customize the engine. Enabling them add functionalities but often come at the cost of longer compilation times and extra dependencies.
+Bevy exposes many Cargo features to customize the engine. Enabling them adds functionality but may come at the cost of longer compilation times
+and extra dependencies.
 
-### Default Features
+### Profiles
 
-The default feature set enables most of the expected features of a game engine, like rendering in both 2D and 3D, asset loading, audio and UI. To help reduce compilation time, consider disabling default features and enabling only those you need.
+"Profiles" are high-level groups of cargo features that provide the full Bevy experience, but scoped to a specific domain.
+These exist to be paired with `default-features = false`, enabling compiling only the subset of Bevy that you need.
+This can cut down compile times and shrink your final binary size.
 
-|feature name|description|
+For example, you can compile only the "2D" Bevy features (without the 3D features) like this:
+
+```toml
+bevy = { version = "0.17", default-features = false, features = ["2d"] }
+```
+
+|Profile|Description|
+|-|-|
+{% for feature in features %}{% if feature.is_profile %}|{{ feature.name }}|{{ feature.description }}|
+{% endif %}{% endfor %}
+By default, the `bevy` crate enables the {% for feature in features %}{% if feature.is_default %}`{{ feature.name }}`{% endif %}{% endfor %} features.
+
+### Collections
+
+"Collections" are mid-level groups of cargo features. These are used to compose the high-level "profiles". If the default profiles don'templated
+suit your use case (ex: you want to use a custom renderer, you want to build a "headless" app, you want to target no_std, etc), then you can use these
+collections to build your own "profile" equivalent, without needing to manually manage _every single_ feature.
+
+|Collection|Description|
 |-|-|
-{% for feature in features %}{% if feature.is_default %}|{{ feature.name }}|{{ feature.description }}|
+{% for feature in features %}{% if feature.is_collection %}|{{ feature.name }}|{{ feature.description }}|
 {% endif %}{% endfor %}
-### Optional Features
+### Feature List
+
+This is the complete `bevy` cargo feature list, without "profiles" or "collections" (sorted by name):
 
-|feature name|description|
+|Feature|Description|
 |-|-|
-{% for feature in features %}{% if feature.is_default == False %}|{{ feature.name }}|{{ feature.description }}|
+{% for feature in sorted_features %}{% if feature.is_collection == False and feature.is_profile == False %}|{{ feature.name }}|{{ feature.description }}|
 {% endif %}{% endfor %}