diff --git a/Cargo.toml b/Cargo.toml index 86acffa412df2..78710ccf2d53b 100644 --- a/Cargo.toml +++ b/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 diff --git a/crates/bevy_internal/Cargo.toml b/crates/bevy_internal/Cargo.toml index f4dbbed2fec35..3077662631c51 100644 --- a/crates/bevy_internal/Cargo.toml +++ b/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"] diff --git a/docs-template/features.md.tpl b/docs-template/features.md.tpl index c9564b95fe41c..2d96fe7f3cf92 100644 --- a/docs-template/features.md.tpl +++ b/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 %} \ No newline at end of file diff --git a/docs/cargo_features.md b/docs/cargo_features.md index e498106d2826f..fb36c8f225000 100644 --- a/docs/cargo_features.md +++ b/docs/cargo_features.md @@ -4,23 +4,78 @@ ## 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| +|-|-| +|default|The full default Bevy experience. This is a combination of the following profiles: 2d, 3d, ui| +|2d|The default 2D Bevy experience. This includes the core Bevy framework, 2D functionality, Bevy UI, scenes, audio, and picking.| +|3d|The default 3D Bevy experience. This includes the core Bevy framework, 3D functionality, Bevy UI, scenes, audio, and picking.| +|ui|The default Bevy UI experience. This includes the core Bevy framework, Bevy UI, scenes, audio, and picking.| + +By default, the `bevy` crate enables the 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| +|-|-| +|dev|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!| +|audio|Features used to build audio Bevy apps.| +|scene|Features used to compose Bevy scenes.| +|picking|Enables picking functionality| +|default_app|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_platform|These are platform support features, such as OS support/features, windowing and input backends, etc.| +|common_api|Default scene definition features. Note that this does not include an actual renderer, such as bevy_render (Bevy's default render backend).| +|2d_api|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_bevy_render|Bevy's built-in 2D renderer, built on top of `bevy_render` | +|3d_api|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_bevy_render|Bevy's built-in 3D renderer, built on top of `bevy_render` | +|ui_api|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_bevy_render|Bevy's built-in UI renderer, built on top of `bevy_render` | +|default_no_std|Recommended defaults for no_std applications| + +### Feature List + +This is the complete `bevy` cargo feature list, without "profiles" or "collections" (sorted by name): + +|Feature|Description| |-|-| +|accesskit_unix|Enable AccessKit on Unix backends (currently only works with experimental screen readers and forks.)| |android-game-activity|Android GameActivity support. Default, choose between this and `android-native-activity`.| +|android-native-activity|Android NativeActivity support. Legacy, should be avoided for most new Android games.| |android_shared_stdcxx|Enable using a shared stdlib for cxx on Android| +|asset_processor|Enables the built-in asset processor for processed assets.| +|async-io|Use async-io's implementation of block_on instead of futures-lite's implementation. This is preferred if your application uses async-io.| |async_executor|Uses `async-executor` as a task execution backend.| +|basis-universal|Basis Universal compressed texture support| +|bevy_animation|Provides animation functionality| |bevy_anti_alias|Provides various anti aliasing solutions| |bevy_asset|Provides asset functionality| |bevy_audio|Provides audio functionality| |bevy_camera|Provides camera and visibility types, as well as culling primitives.| +|bevy_camera_controller|Provides a collection of prebuilt camera controllers| +|bevy_ci_testing|Enable systems that allow for automated testing on CI| |bevy_color|Provides shared color types and operations| |bevy_core_pipeline|Provides cameras and other basic render pipeline features| +|bevy_debug_stepping|Enable stepping-based debugging of Bevy systems| +|bevy_dev_tools|Provides a collection of developer tools| |bevy_gilrs|Adds gamepad support| |bevy_gizmos|Adds support for rendering gizmos| |bevy_gltf|[glTF](https://www.khronos.org/gltf/) support| @@ -33,65 +88,29 @@ The default feature set enables most of the expected features of a game engine, |bevy_pbr|Adds PBR rendering| |bevy_picking|Provides picking functionality| |bevy_post_process|Provides post process effects such as depth of field, bloom, chromatic aberration.| +|bevy_remote|Enable the Bevy Remote Protocol| |bevy_render|Provides rendering functionality| |bevy_scene|Provides scene functionality| |bevy_shader|Provides shaders usable through asset handles.| +|bevy_solari|Provides raytraced lighting (experimental)| |bevy_sprite|Provides sprite functionality| |bevy_sprite_render|Provides sprite rendering functionality| |bevy_state|Enable built in global state machines| |bevy_text|Provides text functionality| |bevy_ui|A custom ECS-driven UI framework| +|bevy_ui_debug|Provides a debug overlay for bevy UI| |bevy_ui_render|Provides rendering functionality for bevy_ui| |bevy_window|Windowing layer| |bevy_winit|winit window and input backend| -|custom_cursor|Enable winit custom cursor support| -|debug|Enable collecting debug information about systems and components to help with diagnostics| -|default_font|Include a default font, containing only ASCII characters, at the cost of a 20kB binary size increase| -|gltf_animation|Enable glTF animation loading| -|hdr|HDR image format support| -|ktx2|KTX2 compressed texture support| -|mesh_picking|Provides an implementation for picking meshes| -|morph|Enables support for morph target weights in bevy_mesh| -|morph_animation|Enables bevy_mesh and bevy_animation morph weight support| -|multi_threaded|Enables multithreaded parallelism in the engine. Disabling it forces all engine tasks to run on a single thread.| -|png|PNG image format support| -|reflect_auto_register|Enable automatic reflect registration| -|smaa_luts|Include SMAA Look Up Tables KTX2 Files| -|sprite_picking|Provides an implementation for picking sprites| -|std|Allows access to the `std` crate.| -|sysinfo_plugin|Enables system information diagnostic plugin| -|tonemapping_luts|Include tonemapping Look Up Tables KTX2 files. If everything is pink, you need to enable this feature or change the `Tonemapping` method for your `Camera2d` or `Camera3d`.| -|ui_picking|Provides an implementation for picking UI| -|vorbis|OGG/VORBIS audio format support| -|wayland|Wayland display server support| -|webgl2|Enable some limitations to be able to use WebGL2. Please refer to the [WebGL2 and WebGPU](https://github.com/bevyengine/bevy/tree/latest/examples#webgl2-and-webgpu) section of the examples README for more information on how to run Wasm builds with WebGPU.| -|x11|X11 display server support| -|zstd_rust|For KTX2 Zstandard decompression using pure rust [ruzstd](https://crates.io/crates/ruzstd). This is the safe default. For maximum performance, use "zstd_c".| - -### Optional Features - -|feature name|description| -|-|-| -|accesskit_unix|Enable AccessKit on Unix backends (currently only works with experimental screen readers and forks.)| -|android-native-activity|Android NativeActivity support. Legacy, should be avoided for most new Android games.| -|asset_processor|Enables the built-in asset processor for processed assets.| -|async-io|Use async-io's implementation of block_on instead of futures-lite's implementation. This is preferred if your application uses async-io.| -|basis-universal|Basis Universal compressed texture support| -|bevy_animation|Provides animation functionality| -|bevy_camera_controller|Provides a collection of prebuilt camera controllers| -|bevy_ci_testing|Enable systems that allow for automated testing on CI| -|bevy_debug_stepping|Enable stepping-based debugging of Bevy systems| -|bevy_dev_tools|Provides a collection of developer tools| -|bevy_remote|Enable the Bevy Remote Protocol| -|bevy_solari|Provides raytraced lighting (experimental)| -|bevy_ui_debug|Provides a debug overlay for bevy UI| |bluenoise_texture|Include spatio-temporal blue noise KTX2 file used by generated environment maps, Solari and atmosphere| |bmp|BMP image format support| |compressed_image_saver|Enables compressed KTX2 UASTC texture output on the asset processor| |critical-section|`critical-section` provides the building blocks for synchronization primitives on all platforms, including `no_std`.| +|custom_cursor|Enable winit custom cursor support| |dds|DDS compressed texture support| +|debug|Enable collecting debug information about systems and components to help with diagnostics| |debug_glam_assert|Enable assertions in debug builds to check the validity of parameters passed to glam| -|default_no_std|Recommended defaults for no_std applications| +|default_font|Include a default font, containing only ASCII characters, at the cost of a 20kB binary size increase| |detailed_trace|Enable detailed trace event logging. These trace events are expensive even when off, thus they require compile time opt-in| |dlss|NVIDIA Deep Learning Super Sampling| |dynamic_linking|Force dynamic linking, which improves iterative compile times| @@ -108,24 +127,33 @@ The default feature set enables most of the expected features of a game engine, |ghost_nodes|Experimental support for nodes that are ignored for UI layouting| |gif|GIF image format support| |glam_assert|Enable assertions to check the validity of parameters passed to glam| +|gltf_animation|Enable glTF animation loading| +|hdr|HDR image format support| |hotpatching|Enable hotpatching of Bevy systems| |http|Enables downloading assets from HTTP sources. Warning: there are security implications. Read the docs on WebAssetPlugin.| |https|Enables downloading assets from HTTPS sources. Warning: there are security implications. Read the docs on WebAssetPlugin.| |ico|ICO image format support| |jpeg|JPEG image format support| +|ktx2|KTX2 compressed texture support| |libm|Uses the `libm` maths library instead of the one provided in `std` and `core`.| +|mesh_picking|Provides an implementation for picking meshes| |meshlet|Enables the meshlet renderer for dense high-poly scenes (experimental)| |meshlet_processor|Enables processing meshes into meshlet meshes for bevy_pbr| +|morph|Enables support for morph target weights in bevy_mesh| +|morph_animation|Enables bevy_mesh and bevy_animation morph weight support| |mp3|MP3 audio format support| +|multi_threaded|Enables multithreaded parallelism in the engine. Disabling it forces all engine tasks to run on a single thread.| |pbr_anisotropy_texture|Enable support for anisotropy texture in the `StandardMaterial`, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs| |pbr_clustered_decals|Enable support for Clustered Decals| |pbr_light_textures|Enable support for Light Textures| |pbr_multi_layer_material_textures|Enable support for multi-layer material textures in the `StandardMaterial`, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs| |pbr_specular_textures|Enable support for specular textures in the `StandardMaterial`, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs| |pbr_transmission_textures|Enable support for transmission-related textures in the `StandardMaterial`, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs| +|png|PNG image format support| |pnm|PNM image format support, includes pam, pbm, pgm and ppm| |qoi|QOI image format support| |raw_vulkan_init|Forces the wgpu instance to be initialized using the raw Vulkan HAL, enabling additional configuration| +|reflect_auto_register|Enable automatic reflect registration| |reflect_auto_register_static|Enable automatic reflect registration without inventory. See `reflect::load_type_registrations` for more info.| |reflect_documentation|Enable documentation reflection| |reflect_functions|Enable function reflection| @@ -133,25 +161,36 @@ The default feature set enables most of the expected features of a game engine, |shader_format_glsl|Enable support for shaders in GLSL| |shader_format_spirv|Enable support for shaders in SPIR-V| |shader_format_wesl|Enable support for shaders in WESL| +|smaa_luts|Include SMAA Look Up Tables KTX2 Files| |spirv_shader_passthrough|Enable passthrough loading for SPIR-V shaders (Only supported on Vulkan, shader capabilities and extensions must agree with the platform implementation)| +|sprite_picking|Provides an implementation for picking sprites| |statically-linked-dxc|Statically linked DXC shader compiler for DirectX 12| +|std|Allows access to the `std` crate.| |symphonia-aac|AAC audio format support (through symphonia)| |symphonia-all|AAC, FLAC, MP3, MP4, OGG/VORBIS, and WAV audio formats support (through symphonia)| |symphonia-flac|FLAC audio format support (through symphonia)| |symphonia-isomp4|MP4 audio format support (through symphonia)| |symphonia-vorbis|OGG/VORBIS audio format support (through symphonia)| |symphonia-wav|WAV audio format support (through symphonia)| +|sysinfo_plugin|Enables system information diagnostic plugin| |tga|TGA image format support| |tiff|TIFF image format support| +|tonemapping_luts|Include tonemapping Look Up Tables KTX2 files. If everything is pink, you need to enable this feature or change the `Tonemapping` method for your `Camera2d` or `Camera3d`.| |trace|Tracing support| |trace_chrome|Tracing support, saving a file in Chrome Tracing format| |trace_tracy|Tracing support, exposing a port for Tracy| |trace_tracy_memory|Tracing support, with memory profiling, exposing a port for Tracy| |track_location|Enables source location tracking for change detection and spawning/despawning, which can assist with debugging| +|ui_picking|Provides an implementation for picking UI| +|vorbis|OGG/VORBIS audio format support| |wav|WAV audio format support| +|wayland|Wayland display server support| |web|Enables use of browser APIs. Note this is currently only applicable on `wasm32` architectures.| |web_asset_cache|Enable caching downloaded assets on the filesystem. NOTE: this cache currently never invalidates entries!| +|webgl2|Enable some limitations to be able to use WebGL2. Please refer to the [WebGL2 and WebGPU](https://github.com/bevyengine/bevy/tree/latest/examples#webgl2-and-webgpu) section of the examples README for more information on how to run Wasm builds with WebGPU.| |webgpu|Enable support for WebGPU in Wasm. When enabled, this feature will override the `webgl2` feature and you won't be able to run Wasm builds with WebGL2, only with WebGPU.| |webp|WebP image format support| +|x11|X11 display server support| |zlib|For KTX2 supercompression| |zstd_c|For KTX2 Zstandard decompression using [zstd](https://crates.io/crates/zstd). This is a faster backend, but uses unsafe C bindings. For the safe option, stick to the default backend with "zstd_rust".| +|zstd_rust|For KTX2 Zstandard decompression using pure rust [ruzstd](https://crates.io/crates/ruzstd). This is the safe default. For maximum performance, use "zstd_c".| diff --git a/release-content/migration-guides/cargo_feature_collections.md b/release-content/migration-guides/cargo_feature_collections.md new file mode 100644 index 0000000000000..61f1527039cf7 --- /dev/null +++ b/release-content/migration-guides/cargo_feature_collections.md @@ -0,0 +1,8 @@ +--- +title: Cargo Feature Collections +pull_requests: [21472] +--- + +Bevy now has high-level cargo feature collections (ex: `2d`, `3d`, `ui`) and mid-level feature collections (ex: `2d_api`, `3d_api`, `default_app`, `default_platform`). This isn't technically a breaking change, but if you were previously disabling Bevy's default features and manually enabling each specific cargo feature you wanted, we _highly_ recommend switching to using the higher level feature collections wherever possible. This will make it much easier to define the functionality you want, and it will reduce the burden of keeping your list of features up to date across Bevy releases. + +See the Cargo Feature Collections pull request for a full list of options. diff --git a/release-content/release-notes/cargo_feature_collections.md b/release-content/release-notes/cargo_feature_collections.md new file mode 100644 index 0000000000000..9fdbfd7e04754 --- /dev/null +++ b/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. diff --git a/tools/build-templated-pages/src/features.rs b/tools/build-templated-pages/src/features.rs index eb7478f6c0f66..9e69cd6cf531f 100644 --- a/tools/build-templated-pages/src/features.rs +++ b/tools/build-templated-pages/src/features.rs @@ -7,11 +7,12 @@ use toml_edit::DocumentMut; use crate::Command; -#[derive(Debug, Serialize, PartialEq, Eq)] +#[derive(Debug, Serialize, PartialEq, Eq, Clone)] struct Feature { name: String, description: String, - is_default: bool, + is_profile: bool, + is_collection: bool, } impl Ord for Feature { @@ -31,33 +32,23 @@ fn parse_features(panic_on_missing: bool) -> Vec { let manifest = manifest_file.parse::().unwrap(); let features = manifest["features"].as_table().unwrap(); - let default: Vec<_> = features - .get("default") - .unwrap() - .as_array() - .unwrap() - .iter() - .flat_map(|v| { - core::iter::once(v.as_str().unwrap().to_string()).chain( - features - .get(v.as_str().unwrap()) - .unwrap() - .as_array() - .unwrap() - .iter() - .map(|v| v.as_str().unwrap().to_string()), - ) - }) - .collect(); features .get_values() .iter() - .flat_map(|(key, _)| { + .flat_map(|(key, value)| { let key = key[0]; if key == "default" { - None + let values = value.as_array().unwrap().iter().flat_map(|v| v.as_str()).collect::>().join(", "); + let description = format!("The full default Bevy experience. This is a combination of the following profiles: {values}"); + + Some(Feature { + is_profile: true, + is_collection: false, + name: "default".to_string(), + description, + }) } else { let name = key .as_repr() @@ -71,14 +62,28 @@ fn parse_features(panic_on_missing: bool) -> Vec { if !description.starts_with("\n# ") || !description.ends_with('\n') { panic!("Missing description for feature {name}"); } - let description = description + let mut description = description .strip_prefix("\n# ") .unwrap() .strip_suffix('\n') .unwrap() .to_string(); + let is_profile = if let Some(trimmed) = description.strip_prefix("PROFILE: ") { + description = trimmed.to_string(); + true + } else { + false + }; + let is_collection = + if let Some(trimmed) = description.strip_prefix("COLLECTION: ") { + description = trimmed.to_string(); + true + } else { + false + }; Some(Feature { - is_default: default.contains(&name), + is_profile, + is_collection, name, description, }) @@ -93,12 +98,14 @@ fn parse_features(panic_on_missing: bool) -> Vec { } pub(crate) fn check(what_to_run: Command) { - let mut features = parse_features(what_to_run.contains(Command::CHECK_MISSING)); - features.sort(); + let features = parse_features(what_to_run.contains(Command::CHECK_MISSING)); + let mut sorted_features = features.clone(); + sorted_features.sort(); if what_to_run.contains(Command::UPDATE) { let mut context = Context::new(); context.insert("features", &features); + context.insert("sorted_features", &sorted_features); Tera::new("docs-template/*.md.tpl") .expect("error parsing template") .render_to(