dylo-runtime 2.3.0

Dynamic library loader for con traits
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

[![license: MIT/Apache-2.0](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE-MIT)
[![crates.io](https://img.shields.io/crates/v/dylo-runtime.svg)](https://crates.io/crates/dylo-runtime)
[![docs.rs](https://docs.rs/dylo-runtime/badge.svg)](https://docs.rs/dylo-runtime)

# 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](https://crates.io/crates/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](https://brew.sh) — 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](https://crates.io/crates/rubicon) 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:

```text,ignore
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:

```text,ignore
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](https://github.com/bearcove/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](https://github.com/bearcove/rubicon/issues/3).