Self-hosting

Self-hosting & bootstrap

People hear minimal C, bootstrap, and self-hosting and picture one magic binary. ilusm splits those ideas on purpose: a tiny stage‑0 runner in C, and the real language implementation as Ilusm source under lib/. This page names each piece so nothing sounds like vapor.

1. What “self-hosting” means in this project

Self-hosting here means: the canonical lexer, parser, tree-walk evaluator, bytecode compiler, VM logic, and stdlib are written in Ilusm and live under lib/**/*.ilu. That tree is the semantic reference - not a sketch in another language.

It does not mean “you never compile a line of C.” Today you still build one small C program to get a runnable entrypoint. See About (design laws) - law 0b: the shipped bootstrap binary is C only; there is no second interpreter (Python, etc.) in-tree for running Ilusm.

2. Stage 0 - ilusm-min.c → ilusm-vm

lib/runtime/ilusm-min.c is compiled by ./build.sh into ilusm-vm. That binary is a minimal runner: its own scanner and evaluator in C, enough to execute some .ilu programs (loops, calls, basic expressions - what the gate and hand-picked examples rely on).

It is not a second full implementation of every rule in the spec. The README calls this honestly: the big story lives in lib/ as Ilusm; the shipped C runner is the bootstrap trampoline while that story and the binary converge over time.

Default gate: ./run-tests.sh uses ilusm-vm run on smoke tests and examples/*.ilu. Passing means those files work under the current C runner—not that every module in lib/stdlib/ runs there yet.

3. Full stack - everything in lib/

The pieces you would expect from a “real” implementation are in Ilusm:

• Frontend - lex.ilu, prs.ilu (tokens → AST with .t tags).
• Tree interpreter - evl.ilu (+ rt_interp.ilu, pipeline.ilu).
• Compiler + VM - compiler.ilu (AST → bytecode), ilusm_vm.ilu, mcde.ilu.
• Stdlib / platform - hundreds of modules under lib/stdlib/ and lib/platform/.

Running that stack end-to-end requires a conforming host: a program that loads .ilu, wires builtins per Syscall ABI / Syscall ABI, and matches the evaluation model described in Host contract. The C ilusm-vm is one host; a future “full” native host would implement the same contract for all of stdlib.

4. What “self-compile” means

Self-compilation is the step where Ilusm source is parsed into an AST and compiler.ilu lowers it to bytecode for ilusm_vm. When that pipeline runs on Ilusm’s own compiler sources, the compiler is compiling itself - in the usual “bootstrapping compiler” sense.

Doing that in practice still needs something to execute Ilusm (conforming host or an evolved ilusm-vm). The dependency order is:

1. C builds ilusm-vm (fixed seed).
2. Host runs Ilusm code that implements the full language (evl, compiler, …).
3. That code can read Ilusm sources (including itself) and emit bytecode.

So: self-hosting = implementation lives in Ilusm; self-compile = that implementation includes a compiler that targets the in-tree VM; bootstrap = the small C binary that gets you onto the ladder.

5. bootstrap/*.ilu scripts

Files under bootstrap/ (e.g. selfhost_quick.ilu, selfhost_minimal.ilu, stage2_compile.ilu) are checked-in demos and milestones for the self-hosting story. They document intent and progress; they are not a separate language.

6. One-page map

Term	Meaning in ilusm
Minimal C	ilusm-min.c only - builds ilusm-vm, not Flex/Yacc/LLVM.
Bootstrap	Using that C binary (and install layout) so .ilu runs at all; optional bootstrap/*.ilu demos.
Self-hosting	Full language implementation in lib/**/*.ilu as source of truth.
Self-compile	compiler.ilu compiling Ilusm (including itself) to bytecode, once a host can run the pipeline.
Conforming host	Any runner that honors the host contract + syscall ABI; ilusm-vm is the minimal one shipped today.