On 7/9/2026 10:13 AM, Ziyang Zhang wrote: > Hi, > > On Fri, 10 Jul 2026 01:04:37 +0800, Ziyang Zhang wrote: >> Document the dlcall plugin under Example Plugins: what it does, the >> trusted- >> guests and guest_base == 0 constraints, how to load it, and a pointer to >> Lorelei, one end-to-end userspace implementation, for the toolchain and a >> runnable example. >> Patch 2/2 walks through the hello example one step at a time. If you > would rather not run those steps by hand, the self-contained Makefile > below does the whole thing in one command: it downloads the devkit, > writes the sources, and builds the thunk tree from patch 2/2. After > that, > > make QEMU=<your qemu-x86_64> PLUGIN=<contrib/plugins/libdlcall.so> run > > runs the guest both ways and prints hello from guest then hello from > host. > > It only needs wget or curl to fetch the devkit from the GitHub release, > plus a qemu-x86_64 built from this series for the run step. Drop it in > an empty directory and run make. > > > # ---- Makefile ---- > # One-click Lorelei hello quickstart. From nothing, this Makefile > downloads the > # devkit, writes the example sources, and builds the thunk tree from the > # walkthrough. Everything lands under this directory. > # > # make download the devkit if needed, then build the tree > # make tree print the resulting directory tree > # make run run baseline then thunked (set QEMU= and PLUGIN=) > # make clean remove the generated src/ build/ thunks/ > # make distclean also remove the downloaded devkit and tarball > # > # Set DEVKIT= to reuse an already-unpacked devkit (then nothing is > downloaded). > # Override VERSION= or ARCH= to pick a different release or host > architecture. > > VERSION ?= 1.0.5.0 > ARCH ?= $(shell uname -m) > DEVKIT ?= lorelei-devkit-$(ARCH) > TARBALL := $(DEVKIT)-$(VERSION).tar.xz > URL := https://github.com/rover2024/lorelei/releases/download/ > v$(VERSION)/$(TARBALL) > > QEMU ?= > PLUGIN ?= > > CLANG = $(DEVKIT)/bin/x86_64-linux-gnu-clang > MKTHUNK = $(DEVKIT)/bin/LoreMakeThunk.py > GTL = thunks/x86_64/lib/x86_64-LoreGTL > > .PHONY: all tree run clean distclean > > all: build/guest/main $(GTL)/libhello.so > > # 0. the devkit, downloaded and unpacked only when $(MKTHUNK) is > missing, so > # pointing DEVKIT= at an existing devkit skips the download. > $(MKTHUNK): > @echo ">> downloading $(TARBALL)" > @command -v wget >/dev/null 2>&1 && wget -O $(TARBALL) $(URL) \ > || curl -fSL -o $(TARBALL) $(URL) > tar -xf $(TARBALL) > > # 1. the sources, written out so the whole tree comes from this one > Makefile. > # The guest and host builds print "from guest" and "from host", so a run > shows > # which one ran. > src/hello.h: > @mkdir -p src > @printf '%s\n' \ > '#ifdef __cplusplus' 'extern "C" {' '#endif' \ > 'void hello(const char *name, int lucky);' \ > '#ifdef __cplusplus' '}' '#endif' > $@ > > src/hello_guest.c: | src/hello.h > @printf '%s\n' \ > '#include "hello.h"' '#include <stdio.h>' '' \ > 'void hello(const char *name, int lucky)' '{' \ > ' printf("hello from guest: %s, lucky %d\n", name, lucky);' \ > ' fflush(stdout);' '}' > $@ > > src/hello_host.c: | src/hello.h > @printf '%s\n' \ > '#include "hello.h"' '#include <stdio.h>' '' \ > 'void hello(const char *name, int lucky)' '{' \ > ' printf("hello from host: %s, lucky %d\n", name, lucky);' \ > ' fflush(stdout);' '}' > $@ > > src/main.c: | src/hello.h > @printf '%s\n' \ > '#include "hello.h"' '' \ > 'int main(void)' '{' \ > ' hello("world", 7);' ' return 0;' '}' > $@ > > # 2. the guest libhello.so (x86_64) and the guest program. main has no > rpath, > # so which libhello.so it loads is decided by LD_LIBRARY_PATH at run time. > build/guest/main: src/hello_guest.c src/main.c src/hello.h | $(MKTHUNK) > mkdir -p build/guest > $(CLANG) -shared -fPIC src/hello_guest.c -o build/guest/libhello.so > $(CLANG) src/main.c -Isrc -Lbuild/guest -lhello -o $@ > > # 3. the host libhello.so, native to this host, for the host thunk to use. > build/host/libhello.so: src/hello_host.c src/hello.h > mkdir -p build/host > cc -shared -fPIC src/hello_host.c -o $@ > > # 4. the thunk pack (host HTL + guest GTL) generated from the host library. > $(GTL)/libhello.so: build/host/libhello.so | $(MKTHUNK) > $(MKTHUNK) --name hello --lib $< --header hello.h -o thunks -- -Isrc > > # print the produced tree > tree: all > @command -v tree >/dev/null 2>&1 && tree src build thunks \ > || find src build thunks | sort > > # run baseline (guest build) then thunked (host build) under qemu. > run: all > @echo "== without the thunk ==" > $(QEMU) -E LD_LIBRARY_PATH=build/guest build/guest/main > @echo "== with the thunk ==" > LORELEI_THUNK_PATH=thunks LD_LIBRARY_PATH=$(DEVKIT)/lib:build/host \ > $(QEMU) -plugin $(PLUGIN) \ > -E LD_LIBRARY_PATH=$(DEVKIT)/x86_64/lib:$(GTL) \ > build/guest/main > > clean: > rm -rf src build thunks > > distclean: clean > rm -rf $(DEVKIT) $(TARBALL) >
The problem is not to automate the 5 commands we need to copy paste, but to have a functional example, which is not yet the case. On Lorelei side, feel free to do what you want for the docs and examples, but for QEMU doc, we'll stick to have something as simple as possible, without any Makefile. I politely ask you to not add anything else to documentation out of what was asked in v9. This just makes things slower, and more iteration needed. Also, please see the comments sent on v9, you can answer to them directly on v9. Regards, Pierrick
