dylo-runtime

dylo-runtime handles module loading on MacOS and Linux. End users shouldn't need to use this crate directly - it exists as a dependency of the dylo crate and crates generated by the dylo-cli tool.

dylo used to build modules, but now it just loads them — it will look for them in:

• $DYLO_MOD_DIR (if set)
• @executable_path/../libexec/
• @executable_path/
• @executable_path/../../libexec/release/
  • This takes care of cases where the binary is built into target/bin/release/my-app, and the modules are in target/libexec/release/libmod_blah.dylib

Where @executable_path is the return value of https://doc.rust-lang.org/stable/std/env/fn.current_exe.html.

Note: if the returned value of current_exe is a symlink, it will be canonicalized first — ie., we'll search against the path it points to

(The libexec nomenclature comes from homebrew — you typically don't want to link your dylo modules into the homebrew prefix — they're "private-use, see https://apple.stackexchange.com/questions/277606/why-are-all-the-homebrew-formulas-located-in-the-libexec-folder)

Environment Variables

• DYLO_DEBUG: Set to 1 to enable debug logging for dylo's module loading process.
• DYLO_MOD_DIR: Set to an absolute path to prepend to dylo's module search path. This directory must exist.

Note: If DYLO_MOD_DIR is set to a non-absolute path or a non-existent directory, dylo will panic with an informative error message.

Preparing modules for dylo

Warning Make sure to build your mods with the dylo-runtime/import-globals and impl features enabled.

See the rubicon docs for more details: essentially, your mods need to refer to the same process-local and thread-local variables that your main app does, or stuff like tokio etc. will break.

That is, if your Cargo workspace looks like this:

workspace/
  Cargo.toml
  mods/
    mod-markdown/
    mod-clap/
    con-markdown/
    con-clap/
  my-app/
    Cargo.toml
    src/lib.rs etc.

Then dylo-runtime expects a file hierarchy like this:

workspace/
  target/
    debug/
      my-app
      libmod_markdown.dylib
      libmod_clap.dylib

Except it doesn't actually need to be in target/debug/ of anywhere — this could all be in a container image under /app or whatever, or it could be packaged up as a Homebrew package with libexec/libmod_markdown.dylib and bin/my-app.

ABI Safety

dylo uses rubicon to ensure that the ABI of the module matches the ABI of the app they're being loaded into.

If you mess something up, you should get a detailed panic with colors and emojis explaining exactly what you got wrong.

Note that if you need crates like tokio, tracing, eyre, etc. you should use their patched versions, see the rubicon compatibility tracker.