Embedding › 06 Operations

Operations

Build with sanitizers, diagnose the usual failures, and know the current limits.

1. Building and testing hosts

make                       # VM objects + CLI
make libs                  # standard library plugins
make clean                 # after switching sanitizer modes

# AddressSanitizer / UndefinedBehaviorSanitizer
make clean && make CFLAGS="-O0 -std=gnu11 -g -fsanitize=address,undefined"

# ThreadSanitizer (concurrency bugs)
make tsan

Hosts link whatever objects are present, so a sanitizer build of the host must match a sanitizer build of the VM. Always make clean between modes. When linking a host, exclude the CLI entry point:

cc -O2 -std=gnu11 -I src host.c $(ls src/*.o | grep -v '/main.o$') \
   -rdynamic -lm -ldl -lpthread -o host

2. Troubleshooting

Symptom	Cause and fix
`module load failed`	A dependency was loaded after its user. Load the closure in order (chapter 3).
`[native] no implementation found for X (.so missing)`	The native library was not found. Check `native_set_lib_dir`, and run `make libs`.
`undefined symbol: vm_...` at load time	The host was linked without `-rdynamic`.
Crash inside `vm_destroy`	A worker thread is still running. Join every thread first; check `vm_live_threads`.
Values turn into garbage after a while	An unrooted `Value` was kept across allocations. Root it.
A run never ends	No step budget. Set `vm_set_max_steps` or the `LOTH_MAX_STEPS` environment variable for CLI runs.
Two VMs see different singletons	Expected: singletons are per VM. Use one shared VM if components must share state.

3. Limits worth knowing

Engine v1 does no dependency resolution: you load modules in order.
Dynamic loading (vm_load_module) is not safe while threads run language code.
One process may host many VMs, but each VM's memory is independent; there is no cross-VM object sharing.
There is no process isolation or IPC layer yet; that belongs to the OS layer above the VM.
The CLI refuses to destroy a VM while worker threads are alive and exits instead. Hosts should follow the same rule explicitly.