Deprecate dynamic plugins (#13080)

# Objective

- The current implementation for dynamic plugins is unsound. Please see
#11969 for background and justification.
- Closes #11969 and closes #13073.

## Solution

- Deprecate all dynamic plugin items for Bevy 0.14, with plans to remove
them for Bevy 0.15.

## Discussion

One thing I want to make clear is that I'm not opposed to dynamic
plugins _in general_. I think they can be handy, especially for DLC and
modding, but I think the current system is the wrong approach. It's too
much of a footgun for the meager benefit is provides.

---

## Changelog

- Deprecated the current dynamic plugin system.
- Dynamic plugins will be removed in Bevy 0.15. For now you can continue
using them by marking your code with `#[allow(deprecated)]`.

## Migration Guide

If possible, remove all usage of dynamic plugins.

```rust
// Old
#[derive(DynamicPlugin)]
pub struct MyPlugin;

App::new()
    .load_plugin("path/to/plugin")
    .run();

// New
pub struct MyPlugin;

App::new()
    .add_plugins(MyPlugin)
    .run();
```

If you are unable to do that, you may temporarily silence the
deprecation warnings.

```rust
#[allow(deprecated)]
```

Please note that the current dynamic plugin system will be removed by
the next major Bevy release, so you will have to migrate eventually. You
may be interested in these safer alternatives:

- [Bevy Assets - Scripting]: Scripting and modding libraries for Bevy
- [Bevy Assets - Development tools]: Hot reloading and other development
functionality
- [`stabby`]: Stable Rust ABI

[Bevy Assets - Scripting]: https://bevyengine.org/assets/#scripting
[Bevy Assets - Development tools]:
https://bevyengine.org/assets/#development-tools
[`stabby`]: https://github.com/ZettaScaleLabs/stabby
This commit is contained in:
BD103 2024-05-20 16:01:28 -04:00 committed by GitHub
parent 612e77ef78
commit 2940636e0a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 39 additions and 0 deletions

View file

@ -124,6 +124,10 @@ impl Plugin for PlaceholderPlugin {
/// It is used for dynamically loading plugins.
///
/// See `bevy_dynamic_plugin/src/loader.rs#dynamically_load_plugin`.
#[deprecated(
since = "0.14.0",
note = "The current dynamic plugin system is unsound and will be removed in 0.15."
)]
pub type CreatePlugin = unsafe fn() -> *mut dyn Plugin;
/// Types that represent a set of [`Plugin`]s.

View file

@ -2,6 +2,10 @@ use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};
#[deprecated(
since = "0.14.0",
note = "The current dynamic plugin system is unsound and will be removed in 0.15."
)]
pub fn derive_dynamic_plugin(input: TokenStream) -> TokenStream {
let ast = parse_macro_input!(input as DeriveInput);
let struct_name = &ast.ident;

View file

@ -19,8 +19,15 @@ use proc_macro::TokenStream;
use quote::format_ident;
/// Generates a dynamic plugin entry point function for the given `Plugin` type.
///
/// This is deprecated since 0.14. The current dynamic plugin system is unsound and will be removed in 0.15.
#[proc_macro_derive(DynamicPlugin)]
#[deprecated(
since = "0.14.0",
note = "The current dynamic plugin system is unsound and will be removed in 0.15."
)]
pub fn derive_dynamic_plugin(input: TokenStream) -> TokenStream {
#[allow(deprecated)]
app_plugin::derive_dynamic_plugin(input)
}

View file

@ -9,12 +9,23 @@
//! This crate allows loading dynamic libraries (`.dylib`, `.so`) that export a single
//! [`Plugin`](bevy_app::Plugin). For usage, see [`dynamically_load_plugin`].
//!
//! # Deprecation
//!
//! The current dynamic plugin system is unsound and will be removed in 0.15. You may be interested
//! in the [Alternatives](#alternatives) listed below. If your use-case is not supported, please
//! consider commenting on [#13080](https://github.com/bevyengine/bevy/pull/13080) describing how
//! you use dynamic plugins in your project.
//!
//! # Warning
//!
//! Note that dynamic linking and loading is inherently unsafe because it allows executing foreign
//! code. Additionally, Rust does not have a stable ABI and may produce
//! incompatible libraries across Rust versions, or even subsequent compilations. This will not work
//! well in scenarios such as modding, but can work if the dynamic plugins and the main app are
//! built at the same time, such as with Downloadable Content (DLC) packs.
//!
//! # Alternatives
//!
//! You may be interested in these safer alternatives:
//!
//! - [Bevy Assets - Scripting]: Scripting and modding libraries for Bevy

View file

@ -1,4 +1,5 @@
#![allow(unsafe_code)]
#![allow(deprecated)]
use libloading::{Library, Symbol};
use std::ffi::OsStr;
@ -8,6 +9,10 @@ use bevy_app::{App, CreatePlugin, Plugin};
/// Errors that can occur when loading a dynamic plugin
#[derive(Debug, Error)]
#[deprecated(
since = "0.14.0",
note = "The current dynamic plugin system is unsound and will be removed in 0.15."
)]
pub enum DynamicPluginLoadError {
/// An error occurred when loading a dynamic library.
#[error("cannot load library for dynamic plugin: {0}")]
@ -30,6 +35,10 @@ pub enum DynamicPluginLoadError {
/// foreign code, initialization routines may be run (as well as termination routines when the
/// program exits). The caller of this function is responsible for ensuring these routines are
/// sound. For more information, please see the safety section of [`libloading::Library::new`].
#[deprecated(
since = "0.14.0",
note = "The current dynamic plugin system is unsound and will be removed in 0.15."
)]
pub unsafe fn dynamically_load_plugin<P: AsRef<OsStr>>(
path: P,
) -> Result<(Library, Box<dyn Plugin>), DynamicPluginLoadError> {
@ -51,6 +60,10 @@ pub unsafe fn dynamically_load_plugin<P: AsRef<OsStr>>(
}
/// An extension trait for [`App`] that allows loading dynamic plugins.
#[deprecated(
since = "0.14.0",
note = "The current dynamic plugin system is unsound and will be removed in 0.15."
)]
pub trait DynamicPluginExt {
/// Dynamically links a plugin at the given path, registering the plugin.
///