Cargo Feature Collections

Cargo.toml

@@ -125,67 +125,173 @@ unsafe_op_in_unsafe_fn = "warn"
 unused_qualifications = "warn"
 
 [features]
-default = [
-  "std",
+default = ["2d", "3d", "ui"]
+
+# SECTION: Feature Collections
+# High level scoped collections of features that give the "full" bevy experience,
+# but scoped to a specific domain. These are then combined together to form the default Bevy feature set.
+# 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.
+
+# Features used to build 2D Bevy apps (this includes the bevy_render backend).
+# Add this to your app if you would like the "default" 2D Bevy experience.
+2d = [
+  "default_app",
+  "default_platform",
+  "2d_api",
+  "2d_bevy_render",
+  "ui",
+  "scene",
+  "audio",
+  "picking",
+]
+
+# Features used to build 3D Bevy apps (this includes the bevy_render backend).
+# Add this to your app if you would like the "default" 3D Bevy experience.
+3d = [
+  "default_app",
+  "default_platform",
+  "3d_api",
+  "3d_bevy_render",
+  "ui",
+  "scene",
+  "audio",
+  "picking",
+]
+
+# Features used to build UI Bevy apps (this includes the bevy_render backend).
+# Add this to your app if you would like the "default" Bevy UI experience.
+# If you are using Bevy as "just" a UI framework, enable this feature.
+ui = [
+  "default_app",
+  "default_platform",
+  "ui_api",
+  "ui_bevy_render",
+  "scene",
+  "audio",
+  "picking",
+]
+
+# Features used to build audio Bevy apps.
+audio = ["bevy_audio", "vorbis"]
+
+# Features used to compose Bevy scenes.
+scene = ["bevy_scene"]
+
+# Enables "picking" functionality
+picking = ["bevy_picking", "mesh_picking", "sprite_picking", "ui_picking"]
+
+# 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",
+]
+
+# These are "platform support" features like "adding OS support or 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",
+]
+
+# Default "render" features. Note that this does not include "render backend" features, such as bevy_render (Bevy's default render backend).
+render_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",
+]
+
+# 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 = ["render_api", "bevy_sprite"]
+
+# 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",
+]
+
+# 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 = [
+  "render_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",
 ]
 
+# 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",
+]
+
+# 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", "render_api", "bevy_ui"]
+
+# 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",
+]
+
+# 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!
+#
+# Note: We recommend also enabling `dynamic_linking` during development as it can significantly improve
+# iteration times.
+dev = [
+  "debug",          # TODO: rename this to something more specific ... this is a "debug ECS names" feature
+  "bevy_dev_tools",
+  "file_watcher",
+]
+
 # Recommended defaults for no_std applications
 default_no_std = ["libm", "critical-section", "bevy_color", "bevy_state"]
 
+# END SECTION: Default Feature Collections
+
 # Provides an implementation for picking meshes
 mesh_picking = ["bevy_internal/mesh_picking"]
 

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"]

release-content/release-notes/cargo_feature_collections.md

@@ -0,0 +1,41 @@
+---
+title: Cargo Feature Collections
+authors: ["@cart"]
+pull_requests: [21472]
+---
+
+Historically, Bevy developers have lived one of two lifestyles:
+
+1. Use all of Bevy's default features, potentially compiling many unwanted or unneeded features.
+2. Disable Bevy's default features and manually define the complete list of features.
+
+Living in the world of (2) was an exercise in frustration, as the list of bevy features is _massive_ and the features required to accomplish a given task changes regularly across releases. This was an _expert level_ task that required intimate knowledge of engine internals to get right.
+
+**Bevy 0.18** introduces high-level "cargo feature collections" to the `bevy` crate: `2d`, `3d`, and `ui`. This enables developers to easily select the kind of app they want to build, and only compile the pieces of Bevy needed for that app.
+
+This means scenarios like using Bevy as a UI framework, without pulling in the rest of the engine, is now as easy as:
+
+```toml
+bevy = { version = "0.18", default-features = false, features = ["ui"] }
+```
+
+We've also added mid-level feature collections like `2d_api`, which is Bevy's 2D API _without the default Bevy renderer_. This makes it much easier to swap out the default Bevy renderer for a custom one.
+
+For example, the `2d` profile looks like this:
+
+```toml
+2d = [
+  "default_app",
+  "default_platform",
+  "2d_api",
+  "2d_bevy_render",
+  "ui",
+  "scene",
+  "audio",
+  "picking",
+]
+```
+
+Someone building a custom 2D renderer now just needs to remove `2d_bevy_render` and provide their own.
+
+Developers can now define their own high-level cargo feature profiles from these mid-level pieces, making it _much_ easier to define the subset of Bevy you want to build into your app.