Joseph Ferano
2dd13b5ae0
Nothing in it could. A game got a clock from raylib and a program without a window had none at all, so "how long did that take" was unanswerable in the half of daily use that is a tool rather than a game. Two clocks, because the mistake a single one invites is using it for the other job. monotonic-ns measures: it never goes backwards, nothing adjusts it, and its zero is arbitrary, so it is meaningless alone and correct as a difference. unix-ns dates: nanoseconds since 1970, which is what goes in a save file, and which jumps in either direction when somebody sets the system clock. The names are picked so that reaching for the wrong one reads wrong. This is Odin's shape, from core/time/time.odin and core/time/time_linux.odin: Tick against Time, both an i64 of nanoseconds, over MONOTONIC and REALTIME, with the seconds-valued face derived rather than a second syscall. Three C functions here and six Flan names over them, which is the rule flan_rt.c's own header states -- a primitive is the only thing implemented twice. The monotonic origin is the first read of the clock in the process, not boot, and that is the one decision worth arguing. CLOCK_MONOTONIC counts from boot, so on a machine up a hundred days the raw value is past 2^53 nanoseconds and monotonic-seconds would lose sub-microsecond resolution depending on the machine's uptime rather than on anything the program did. Latched to first read it stays integer-exact for a hundred days of process life, and it also matches what a game already has: raylib's GetTime is seconds since InitWindow, so the two numbers now mix without a conversion at every site. sleep-ns loops on EINTR, because otherwise a signal cuts the wait short and a frame loop wobbles for reasons nothing in the program explains. It is documented as at-least and not as a frame limiter; the shape that actually paces a loop is a deadline recomputed from monotonic-ns each turn, and the comment says so where somebody will read it. getenv answers an (Option [u8]) viewing the process environment, which needs no allocator and no free and is safe precisely because nothing in this language can call setenv or spawn a process. The absent case rides in the length rather than in the pointer: there is no null test to write, since a (Ptr T) here always addresses something, so flan_getenv answers -1 and a pointer at a valid empty string and the Flan side tests arithmetic. The runtime additions are a single block at the end of flan_rt.c, with <time.h> inside it for the reason <errno.h> sits beside the file section. programs/time.flan asserts invariants and never a reading -- t2 >= t1, a sleep that did not return early, a date after 2020 and before 2100 -- because the same file is in the corpus @x86 builds twice and diffs, so a timestamp would fail a correct compiler on its second run.
Flan
A statically typed Lisp for native games and interactive development.
Flan is an experimental, ahead-of-time compiled Lisp for programs that need predictable memory use and a fast edit–run loop. It combines S-expressions, static types, explicit ownership, and a development session that can replace a function in a running program without resetting its state.
It is being built around games, but the interesting part is broader: a compiled language where the running program remains available for inspection, experimentation, and small changes.
In practical terms: you get parentheses, a debugger that would like to have a conversation, and no garbage collector quietly choosing the dramatic moment to join your frame loop.
What it has
- Native compilation through LLVM, plus an in-progress direct x86-64 backend.
- C-like data layout: structs, fixed arrays, pointers, slices, and explicit allocation. There is no garbage collector.
- Owned
VecandMapcontainers, plus checked moves and borrowing-oriented slice operations. - Generics, algebraic unions, enums, macros, packages,
defer, and a C FFI. - Conditions and restarts for recoverable failures and interactive debugging.
- A raylib package and a collection of ported raylib examples.
- Native, WASI, and web build targets. The cross targets are useful but less complete than the native development workflow.
The project is exploratory software, not a stable language release. Some features are deliberately refused while their semantics are still undecided; the compiler aims to say why rather than quietly accepting a partial version. It has opinions, but at least they arrive as error messages.
Quick start
Building requires a current OCaml/Dune toolchain, LLVM/Clang, and the native C toolchain. Raylib is only needed for programs that use the bundled graphics package.
dune build
dune exec ./bin/main.exe -- run web/examples/hello.flan
To build a standalone native executable:
dune exec ./bin/main.exe -- build web/examples/hello.flan -o hello
./hello
The falling-sand demo uses raylib:
dune exec ./bin/main.exe -- run sand.flan
Once you are iterating regularly, put the built executable on your PATH if
you want to use the shorter flan commands shown below.
The live development loop
Start a long-lived development session:
flan dev sand.flan
The program runs normally and publishes a local socket beside the source file. The bundled Emacs mode can attach to it, evaluate expressions in the live process, inspect a stopped program, and recompile a top-level function from the buffer. A body change takes effect on the next call; changing a function's signature is intentionally rejected. The program keeps its state, which is especially nice when you have finally arranged the sand into something almost worth saving.
To set up the mode:
(add-to-list 'load-path "~/path/to/flan/emacs")
(require 'flan-mode)
Then use M-x flan-dev to start and attach, or C-c C-z to attach to a
session started in a terminal. The editor workflow is documented in
emacs/MANUAL.md.
A small example
(defstruct AssetMissing [id i32])
(defn load-asset [id i32] i32
(signal (AssetMissing {.id id}))
100)
(defn asset-or-placeholder [id i32] i32
(restart-case (load-asset id)
(use-placeholder [] -1)))
(defn main [] ()
(handler-bind [(AssetMissing [_] (invoke-restart 'use-placeholder))]
(println (asset-or-placeholder 7))))
Here a missing asset signals a typed condition. The handler chooses a restart, so execution continues with a placeholder instead of requiring error values to be threaded through every caller. See web/examples/restart.flan for a runnable version.
Commands
flan check <file.flan> type-check a program
flan run <file.flan> [args...] build and run it
flan build <file.flan> [-o out] [options] build a native executable
flan dev <file.flan> [-s socket] start a live development session
Useful build options include --debug, --sanitize, --no-bounds-checks,
--x86, and --target=wasm32-wasi|web. run is native-only; cross-built
output should be run with an appropriate WASI runtime or browser. A .wasm
file is not a tiny native executable in a trench coat.
Checking it
dune test the suite. Seconds. Run it constantly.
dune build @checks everything else that can fail. A couple of minutes.
dune build @sanitize the corpus under ASan and UBSan.
dune build @valgrind the corpus under memcheck. Tens of minutes.
dune test means "the language still works". @checks — which is @page,
@x86 and @cells — means "and everything written down about it is still
true": the reference page's examples still print what the page says, the
hand-written x86 backend still agrees with LLVM, and a --dev build still calls
through its indirection cells.
The two are separate on purpose. A suite that goes red because prose drifted
teaches you to skim past red. But @checks only helps if it is run, and nothing
runs it for you — there is no CI here. The convention that has to carry it is
that a lane's handoff quotes @checks, the way the x86 handoffs already quote
the survey's counts. Both of this repository's silent failures — two backend
refusals that sat for a month, a page of examples that stopped compiling for two
days — were found by accident, and neither would have survived one person
typing one command.
Project map
- web/index.html — language reference and fuller examples.
- spec-memory.md — ownership, containers, and generics.
- spec-conditions.md — conditions, handlers, and restarts.
- emacs/MANUAL.md — the interactive editor workflow.
- docs/BUILT.md — implementation rationale.
- NEXT.md — current work and known limits.
License
Flan is released under the MIT License. Third-party material under
vendor/ is distributed under its own licenses.