Skip to content

BooleOS 0.19.0 - Phase 19: SDK / app-development experience

Choose a tag to compare

@TheShannonDev TheShannonDev released this 25 Sep 22:30
· 43 commits to main since this release

BooleOS 0.19.0 - Phase 19: SDK / app-development experience

All you need to run it is QEMU; the exact command is in the README.txt inside the ISO package.

  • booleos-0.19.0-iso-img(originally-nullos).zip: the bootable ISO built from this tag (the image itself still says NullOS, because the project was renamed after this version), the blank disk image when this version has one, and a README.txt with the QEMU command and what this ISO does
  • booleos-0.19.0-docs-original.zip: the docs of this version, exactly as they were

Changes

Added

  • exec() runs programs from FAT16, not only from the ramfs baked into the
    ISO. The program is found with vfs_open() — the lookup every file open
    uses: the ramfs first (so a disk file can never shadow a system program),
    then FAT16 resolved against the caller's cwd, so run dir/prog.elf works. A
    FAT16 program is read from disk whole by its directory-entry size (at most
    192 KB) into a temporary heap buffer, loaded and freed; the ramfs path stays
    zero-copy. No change to the on-disk format.
  • SDK for writing programs from outside the kernel tree: sdk/hello.c (the
    template) and sdk/Makefile, which builds every *.c to build/<name>.elf
    reusing the system's own compiler flags, linker script (user/link.ld) and
    library sources, and make inject PROG=<name> to copy the result into
    build/disk.img without rebuilding the ISO. New guide docs/sdk.md for
    someone writing a program (rules, build, running it, the library, printf).
  • printf family in libnos (user/lib/nosstdio.c): printf, vprintf,
    sprintf, snprintf, vsnprintf with the standard libc names — %d %i %u %x %X %c %s %p %%, flags - 0 + space, width and precision (also *), h/hh/l.
    No floating point, no 64-bit, no #. A separate object linked only into the
    programs that use it.
  • make test-elf (tools/test_elf_load.c): a host-side test of the real
    kernel/elf.c on every built user program, plus truncation, header fuzzing and
    crafted hostile headers.
  • selftest: three new tests (exec of a program that exists only on FAT16;
    malformed, truncated and missing programs rejected; the printf family) —
    21 tests.

Changed

  • elf_load() takes the file size and no longer trusts the image: the program
    header table and every segment's file data are checked against it, segments
    must lie in [0x00800000, 0x02000000), and all checks use 64-bit arithmetic so
    a 32-bit field cannot wrap. All headers are validated before anything is
    mapped. This also closes the "elf_load never receives the file size / page_end
    overflow" item of the Phase 28 plan.

  • The kernel heap is grown to 256 KB when it is initialized, and heap_expand()
    takes exactly the physical page at heap_end (pmm_alloc_page_at(), new)
    instead of the lowest free one — the heap's virtual addresses are the
    identity-mapped physical ones (see Fixed). The heap can no longer grow once
    processes exist, a limit recorded in PROGRESS.md for Phase 22.

  • tools/Makefile: the user ELFs have the user target as an order-only
    prerequisite, so any target that needs them builds user/ first.

  • tools/prev/ holds the v0.18.0 build (the "previous release" GRUB entry of
    this version).

  • Documentation brought up to date for this phase: docs/testing.md (the 21-test
    selftest and make test-elf), docs/filesystem.md (exec() as a vfs_open()
    consumer and the shared-buffer hazard), docs/syscalls.md (SYS_EXEC /
    SYS_EXEC_PIPE name resolution), docs/security.md (the ELF loader does not
    trust the file), docs/shell.md (run a FAT16 program), docs/setup.md
    (make test-elf, the order-only rule) and the README (file list, docs list,
    make test-elf).

  • CLAUDE.md: a "Definition of Done" checklist (literal, not prose) at the top —
    what must be done in every subtask commit (a docs/TODO.md trace, a
    [Unreleased] CHANGELOG entry) and in the closing commit of a phase (the
    consolidated CHANGELOG entry as a blocking item, README, ROADMAP,
    version.h, TODO resolved into real docs, PROGRESS, syscall table, selftest),
    ending with "read this checklist item by item against the real state of the
    files"; plus the release conventions: every version merged into main gets an
    annotated vX.Y.Z tag, make snapshot is run on the tagged tree and
    tools/prev/ committed back to nightly, and a GitHub Release with a
    ready-to-run zip (bootable ISO, a blank disk image, a README with the QEMU
    command) is published — a version is not released with only the tag.

  • ROADMAP.md: a proposed phase "Crash handler leads into Safe Mode" is
    recorded (unnumbered, outside the priority order until it gets a place): a
    kernel crash saves its dump in the boot config sector, resets by itself and
    lands in Safe Mode with the reason and a "view last crash" item.

  • Documentation split by audience: the new docs/quickstart.md covers only
    "download a release zip, install QEMU, run one command" (no toolchain, no
    Docker, no compiling), and docs/setup.md is now developer-only. setup.md
    was re-checked against tools/Makefile and the scripts: it now states that the
    Makefile runs grub2-mkrescue (the Fedora name) and that the Docker script
    installs neither dosfstools nor python3 (both unverified), documents
    make disk, make snapshot, the exact make run flags (including -display sdl), the four-entry GRUB menu, that the debug boot argument is parsed but
    not acted on yet, and adds a "Branches and versions" section (main = last
    release with an annotated tag, nightly = daily work, the -nightly suffix,
    tools/prev/). README.md and docs/kernel.md now link the right document
    for each case.
    Follow-up: version numbers in the quickstart's explanatory text are now the
    placeholders vX.Y.Z (current) and vA.B.C (previous release) instead of
    hardcoded values; the QEMU installation section covers Linux, macOS (Homebrew,
    MacPorts) and Windows evenly; a new section explains running the ISO and disk
    image in other virtual machines (general requirements, plus step-by-step
    VirtualBox and VMware Workstation/Player, including the one-time raw-to-VDI/VMDK
    conversion — general guidance, not verified by the project); and setup.md now
    explains how to switch to the nightly branch to build the development
    version.

Fixed

  • A kernel page fault (#PF inside vmm_get_user_phys_from_dir) when the heap
    had to grow after a process existed. heap_expand() mapped heap_end — an
    address inside the identity-mapped 4–8 MB range — to the lowest free physical
    page, which repointed the kernel's view of the physical page at that address;
    if it held a process's page directory or page table, the kernel read another
    page's contents through it. Latent since the heap and processes shared that
    range; the first kmalloc large enough to grow the heap after boot (an
    exec() from FAT16) exposed it.
  • make run (or any target that needs the user programs) right after make clean failed with "No rule to make target ../build/user/init.elf"; it now builds
    user/ first.

Full history: CHANGELOG.md