hot-lib-reloader-rs

Hot-reloading Rust code via dynamic libraries has several critical constraints that can lead to crashes if not managed:

• No signature changes: Changing the parameter or return types of a hot-reloadable function will cause a crash because the executable's expectations will no longer match the library's implementation.
• Type changes require care: Structs and enums shared between the executable and the library cannot have their memory layout changed freely. Differing layouts cause undefined behavior and crashes.
• No generics: Functions marked for hot-reloading cannot be generic because #[unsafe(no_mangle)] does not support them.
• Global state issues: If your library contains global state (or depends on a crate that does), it must be re-initialized after a reload. Additionally, crates relying on TypeId (like many ECS systems) may fail because types have different IDs after a reload.

For a detailed discussion on these caveats, refer to the official blog post on hot-reloading Rust.

To enable hot-reloading in the Bevy example, you must run two commands in parallel. One command watches the source crates (systems and components) and rebuilds the dynamic library when changes occur, while the other runs the main application with the reload feature enabled.

Linux and macOS

Use the following commands:

$ cargo watch -w systems -w components -x "build -p systems --features dynamic"
$ cargo run --features reload

Windows

On Windows, you must use a separate target directory for the executable to avoid file locking issues caused by bevy_dylib.dll.

$ cargo watch -w systems -w components -x "build -p systems --features dynamic"
$ cargo run --features reload --target-dir "target-bin"

# Linux/macOS
$ cargo watch -w systems -w components -x "build -p systems --features dynamic"
$ cargo run --features reload

# Windows
$ cargo watch -w systems -w components -x "build -p systems --features dynamic"
$ cargo run --features reload --target-dir "target-bin"

You can make hot reloading optional in your project by wrapping the hot-reloading logic behind a Cargo feature (e.g., reload). This allows you to switch between a hot-reloading development environment and a standard statically compiled binary without changing your source code structure.

Development Workflow

To use hot reloading, run the binary with the reload feature enabled in one terminal, and use a separate terminal to watch and rebuild the library crate whenever it changes.

1. Start the reloader binary:

   cargo watch -i lib -x 'run --features reload'

2. Watch and rebuild the library:

   cargo watch -w lib -x 'build -p lib'

Production/Static Workflow

To run the application as a standard, statically compiled binary (without the reloader), simply use the standard run command:

cargo run

# Terminal 1: Run the binary with the reload feature
cargo watch -i lib -x 'run --features reload'

# Terminal 2: Rebuild the library crate on change
cargo watch -w lib -x 'build -p lib'

# Standard static run
cargo run

To use hot-lib-reloader, you must structure your project as a workspace where the hot-reloadable code resides in a library (dylib) and the main application resides in an executable.

1. Library Configuration

In your library's Cargo.toml (e.g., ./lib/Cargo.toml), set the crate-type to include dylib:

[package]
name = "lib"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["rlib", "dylib"]

Functions intended for hot-reloading must be pub and annotated with #[unsafe(no_mangle)].

#[unsafe(no_mangle)]
pub fn step(state: &mut State) {
    // ...
}

2. Executable Configuration

In your main executable's Cargo.toml (e.g., ./Cargo.toml), add hot-lib-reloader and your library as dependencies:

[workspace]
resolver = "2"
members = ["lib"]

[package]
name = "bin"
version = "0.1.0"
edition = "2024"

[dependencies]
hot-lib-reloader = "0.8"
lib = { path = "lib" }

3. Integrating the Hot Module

In your main.rs, use the #[hot_lib_reloader::hot_module] macro to wrap the library functions. You must also use the hot_functions_from_file! macro to point to the library's source file.

#[hot_lib_reloader::hot_module(dylib = "lib")]
mod hot_lib {
    // Path relative to project root
    hot_functions_from_file!("lib/src/lib.rs");

    // Re-export types used in function signatures
    pub use lib::State;
}