# Finch, for SchOS's own programs

**Two things, and only one of them is later.**

- *Bringing Finch into SchOS* (below) is **later** — behind [1.0.md](1.0.md)'s
  freeze like everything else here that is not named there.
- *Finishing Finch itself*, and making it fully self-hosting, is work on the
  Finch repository and does not touch this tree. It can proceed now; see
  [the gap](#the-self-hosting-gap).

Finch is the author's own language: <https://pandor.pl/git/nexoniarz/Finch>
(GitHub mirror: `Nexoniarz/Finch`). The plan is to write SchOS's own
applications and tools in it, in place of C, and so leave behind what C does
badly: silent narrowing, signed/unsigned mixing, undefined behaviour on an
out-of-range index, a forgotten `free`.

## What it is today (version 2.4.0)

Measured from the repository, not from its README alone:

- **LLVM front end**, C-like syntax, no semicolons, no headers, no preprocessor.
  It compiles through LLVM's `-O2` pipeline to native code; there is no
  garbage collector.
- **Values, not references:** lists, text and structs copy on assignment and
  are freed at the end of their block. Out-of-range indexes, division by zero
  and null pointers stop with a runtime error rather than undefined behaviour.
- **Errors as values** (`int(s) or 0`, `try read_file(p)`), maps, methods,
  modules.
- **C interop through libclang:** `import "foo.h"` plus `link "foo"` calls any C
  library, structs by value and callbacks included. That is the way in to
  everything SchOS already has — musl, the `/dev/*` interfaces, Alpine's
  libraries.
- **Targets:** Linux, macOS, Windows, on x86-64 and ARM64 (`src/platform.fch`;
  the System V, AAPCS64 and Microsoft x64 ABIs are in `src/gen.fch`). ARM64 and
  Windows programs are run under qemu and Wine in the tests; macOS is IR-checked.
- **Language:** enums, `match`, generics, errors as values, maps, methods,
  `defer`, and a standard library in Finch (`json`, `path`, `time`, `proc`).
- **Tooling:** a language server (`finch lsp`, written in Finch), VS Code and
  Kate support, 107 tests.
- **Written in itself:** the whole compiler is Finch (about 8,500 lines in
  `src/`, no C++) and builds itself from a committed seed to a byte-identical
  result — `bootstrap/build.sh`.

## What SchOS would need to do

1. **A `schos` target.** `finch` picks a triple, a C compiler and a linker per
   target. SchOS runs unmodified Alpine binaries and Alpine's musl
   (see [alpine.md](alpine.md)), so the first target is **the existing
   `x86_64-unknown-linux-musl`**, and a Finch program built on the host should
   run on SchOS before anything in Finch is made SchOS-specific. Test that
   before writing a line of target code.
2. **The compiler on SchOS.** Needs LLVM 21 and libclang, both of which Alpine
   packages. That is a question of apk and memory, not of SchOS.
3. **The Finch-written compiler on SchOS.** It emits LLVM IR as text and needs
   only `clang` and libclang, no LLVM C++ libraries, so it is the compiler that
   would ship in the image. It needs a seed made for the SchOS target.
4. **Bindings** for SchOS's own interfaces (`/dev/pci`, `/dev/netdev`,
   schinit's job protocol, the framebuffer) — generated by the C importer from
   the headers in `include/uapi/`, so they are not hand-written and cannot
   drift from the kernel.

## Where self-hosting stands

The compiler is written in Finch and nothing else. `bootstrap/build.sh` builds it
from the seed (its own IR, Linux x86-64 and ARM64) and then from itself, and
checks the two make identical IR. It passes the 107 tests: programs, refusals,
`-g` builds, a shared library and the language server. The work is on the
`finish-finch` branch of `github.com/Nexoniarz/Finch`; `before-bootstrap` there
is the all-C++ compiler, kept as the backup. `main` is untouched.

Left: the compiler does not run on macOS or Windows yet (it needs a seed made
with those systems' headers; programs for them are built from Linux with
`--target`), and `main` is switched to this branch only when the author says so,
after merging their local `embed` work.

## Rules

- Inference, not an instruction: the kernel stays in C. Finch is for
  applications and tools; the user said "our apps or stuff like that".
- No new capability starts until [the register of unfinished work](1.0.md#the-freeze-and-the-register-of-unfinished-work)
  is empty; the SchOS half of this document is a plan, not an exception to that.