Cargo Feature Collections

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 %}