Third-party plugin docs should encourage more granular dependencies

[james7132]

How can Bevy's documentation be improved?

The current third-party plugin guidelines suggest using bevy as the core dependency. This potentially introduces a heavy compile time bottleneck on the top level crate, which is exacerbated as there are some heavy dependencies in tree (i.e. serde and wgpu). This is likely to get progressively worse as the size and complexity of first party crates grows along with the ecosystem. Likewise, it also encourages plugin developers to target features on bevy instead of individual crates, leading to issues like #5753. To avoid this bottleneck, we should encourage plugin developers to directly depend on lower level bevy_* crates instead.

As @mockersf has noted here, this does break potential discoverability via https://lib.rs/crates/bevy/rev. This is, however, potentially mitigated by encouraging plugin developers to take bevy on as a dev-dependency instead, for ease of use when making examples and tests.

[alice-i-cecile]

I'm on board with this strategy.

take bevy on as a dev-dependency instead, for ease of use when making examples and tests.

This is a good compromise, and something I do for my examples and integration tests already.

[mockersf]

depending on sub crates in plugins makes patching Bevy a lot more painful

instead of

[patch.crates-io]
bevy = { git = "https://github.com/bevyengine/bevy" }

you end up with

[patch.crates-io]
# still patch the global crate for your own dependency on Bevy as a game
bevy = { git = "https://github.com/bevyengine/bevy" }
# also patch all subcrates to patch plugins
bevy_animation = { git = "https://github.com/bevyengine/bevy" }
bevy_app = { git = "https://github.com/bevyengine/bevy" }
bevy_asset = { git = "https://github.com/bevyengine/bevy" }
bevy_audio = { git = "https://github.com/bevyengine/bevy" }
bevy_core = { git = "https://github.com/bevyengine/bevy" }
bevy_core_pipeline = { git = "https://github.com/bevyengine/bevy" }
bevy_derive = { git = "https://github.com/bevyengine/bevy" }
bevy_diagnostic = { git = "https://github.com/bevyengine/bevy" }
bevy_ecs = { git = "https://github.com/bevyengine/bevy" }
bevy_encase_derive = { git = "https://github.com/bevyengine/bevy" }
bevy_gilrs = { git = "https://github.com/bevyengine/bevy" }
bevy_gltf = { git = "https://github.com/bevyengine/bevy" }
bevy_hierarchy = { git = "https://github.com/bevyengine/bevy" }
bevy_input = { git = "https://github.com/bevyengine/bevy" }
bevy_internal = { git = "https://github.com/bevyengine/bevy" }
bevy_log = { git = "https://github.com/bevyengine/bevy" }
bevy_macro_utils = { git = "https://github.com/bevyengine/bevy" }
bevy_math = { git = "https://github.com/bevyengine/bevy" }
bevy_mikktspace = { git = "https://github.com/bevyengine/bevy" }
bevy_pbr = { git = "https://github.com/bevyengine/bevy" }
bevy_ptr = { git = "https://github.com/bevyengine/bevy" }
bevy_reflect = { git = "https://github.com/bevyengine/bevy" }
bevy_render = { git = "https://github.com/bevyengine/bevy" }
bevy_scene = { git = "https://github.com/bevyengine/bevy" }
bevy_sprite = { git = "https://github.com/bevyengine/bevy" }
bevy_tasks = { git = "https://github.com/bevyengine/bevy" }
bevy_text = { git = "https://github.com/bevyengine/bevy" }
bevy_time = { git = "https://github.com/bevyengine/bevy" }
bevy_transform = { git = "https://github.com/bevyengine/bevy" }
bevy_ui = { git = "https://github.com/bevyengine/bevy" }
bevy_utils = { git = "https://github.com/bevyengine/bevy" }
bevy_window = { git = "https://github.com/bevyengine/bevy" }
bevy_winit = { git = "https://github.com/bevyengine/bevy" }

We currently don't have a place to document that. Patching Bevy comes up often enough that it would be nice to have somewhere.

[mockersf]

This potentially introduces a heavy compile time bottleneck on the top level crate

This cost is only on clean compile

[SkiFire13]

How does this interact with bevy_dylib? Would plugin crates link to the whole dylib (thus the bottleneck would still be there) or would they skip it, statically linking to the dependencies (but wouldn't bevy_dylib lose meaning then)?

[james7132]

@mockersf not every third party crate requires access to the full breadth of the engine. In practice, most of the ones I've seen only use a handful of first party crates. Even the rendering focused ones usually only need 3-5 first party dependencies. Doesn't seem all that impractical to me.

This cost is only on clean compile

The clean compile is the first experience users have with the engine right now, and also vital for fully auditable/reproducible builds. I wouldn't discount the importance of optimizing the collective dependency tree on that alone.

How does this interact with bevy_dylib? Would plugin crates link to the whole dylib (thus the bottleneck would still be there) or would they skip it, statically linking to the dependencies (but wouldn't bevy_dylib lose meaning then)?

That's a good point. It would lose meaning as the plugin would compile against the static versions of crates and end up incompatible or invoke UB after a reload of some kind. Not sure how to reconcile that.

[mockersf]

@mockersf not every third party crate requires access to the full breadth of the engine. In practice, most of the ones I've seen only use a handful of first party crates. Even the rendering focused ones usually only need 3-5 first party dependencies. Doesn't seem all that impractical to me.

Ha then that's actually worse, to patch Bevy you'll need to go check in each of your plugins on which sub crates they really depend.

[james7132]

I'd say it's better than blanket patching every crate in the workspace, not worse. If you're patching first party crates, you're already diving deep into the internals for the third party plugin, bevy itself, or both, and will dig for what you need. This is typically done as a temporary measure to test a change or prep a plugin crate update, and not a permanent feed-forward patch users are maintaining.

I was also under the impression that we were already breaking patching first party crates with 0.x.0-dev version bumps on main, or are we not doing that anymore?

[mockersf]

I'd say it's better than blanket patching every crate in the workspace, not worse.

I don't think blanket patching is nice, but having to pick up manually all the dependencies of your plugins is worse.

This is typically done as a temporary measure to test a change or prep a plugin crate update, and not a permanent feed-forward patch users are maintaining.

Or as permanent vendored dependency.

I was also under the impression that we were already breaking patching first party crates with 0.x.0-dev version bumps on main, or are we not doing that anymore?

It doesn't break patching, it makes creating a patchable version more involved. Once someone created a patchable version, patching is as easy as ever.

Also, please note I'm not saying this is a blocker if we want to go down that path, but it needs to be documented somewhere.