TempleOS user-space loader

How is this useful?

templeos-loader allows you to use your Linux system for some tasks that previously required running full TempleOS on hardware or in a VM:

compiling the kernel, compiler, or a whole distribution ISO
running non-interactive HolyC programs (file processing, network services)

However, the primary goal is not "to bring HolyC to Linux". The TempleOS programming environment is heavily graphics-based, and too unique to blend in with anything else. Therefore, in the long run, we would like to reproduce the complete, authentic TempleOS experience, in Linux user-space, without a clunky VM.

Building prerequisites

glibc definitely does not appreciate the way we handle memory. For this reason, to avoid crashing, you must use a libc that is more "accomodating", such as musl. CMake 3.13 and the Python3 dataclasses module are also required.

Build musl libc

git clone git://git.musl-libc.org/musl musl-src
cd musl-src
./configure --prefix=$PWD/../build/musl --disable-shared
make install
cd ..
export PATH=$PWD/build/musl/bin:$PATH

Build PhysFS

git submodule update --init --recursive
cd physfslt-3.0.2
env CC=musl-gcc cmake -DCMAKE_INSTALL_PREFIX:PATH=$PWD/../build/physfs -DPHYSFS_BUILD_SHARED=OFF -DPHYSFS_BUILD_TEST=OFF . && make install
cd ..

Build TempleOS On Linux ("static mode", recommended)

mkdir cmake-build-debug
cd cmake-build-debug
env CC=musl-gcc PHYSFSDIR=$PWD/../build/physfs/ cmake ..
cmake --build . --target templeoskernel
cd ..

Run

# Example: compile the HolyC runtime
mkdir -p CmpOutput

env STARTOS=D:/HolyCRT/CmpHolyCRT.HC \
    ./cmake-build-debug/templeoskernel \
    --drive=C,MiniSystem \
    --drive=D,.,CmpOutput

Building a TempleOS ISO from source

# check out the TempleOS source tree
git clone https://github.com/cia-foundation/TempleOS.git
cd TempleOS

# bootstrap the necessary programs
mkdir -p User/Kernel
cp $LOADER_DIR/examples/StartDoDistro.HC User/

# build it!
env STARTOS=StartDoDistro $LOADER_DIR/cmake-build-debug/templeos --drive=C,.,User

# look at the result
ls -l User/Tmp/MyDistro.ISO.C

Build TempleOS Loader For Linux ("dynamic mode")

mkdir cmake-build-debug
cd cmake-build-debug
env CC=musl-gcc PHYSFSDIR=$PWD/../build/physfs/ cmake ..
cmake --build . --target templeos-loader
cd ..

Environment variables

loader is actually agnostic to these, but for now we document them here:

COMPILER (default Compiler) - compiler binary path relative to /Compiler/ (relevant only in dynamic mode)
STARTOS (default StartOS) - StartOS.HC path relative to /

Note that these files must be accessible through one of the virtualized drives!

Other tips

To not break into GDB every time a SEGV is trapped (e.g. when encountering an unpatched CLI instruction), use the GDB command handle SIGSEGV nostop

TODO

bug: PhysFS will not create necessary directories that exist in RO but not in RW overlay!!
implement fopen, fread, fwrite as syscalls
basedir() call is questionable
Clean up syscalls

Design details

To be covered in a series of blog posts.

Calling conventions

See https://www.jwhitham.org/2015/07/redirecting-system-calls-from-c-library.html

TempleOS calling convention: RAX function()

SysV ABI: EAX function(RDI, RSI, RDX, RCX, R8, R9)

Goal: keep VKernel Host ABI-agnostic

minexew / templeos-loader

readme