Finch 2.5.0

Finch 2.5.0 answers a long list of feedback from building a game with SDL3, miniaudio and Box2D.

Language

• "hp \(hp), speed \(v, 2)": code inside text (, 2 = two digits after the point)
• const, if as a value, """ text over several lines, 1e9 literals
• test "name" { assert(...) } blocks next to the code, run with finch test
• min, max, abs, clamp for any numbers
• a struct variable passed where ptr[T] goes: push(body) is push(addr(body))
• warnings for big hidden copies (a struct with 256+ bytes of numbers as a parameter or in for x in list)
• fixes: struct defaults inside structs, exit() in or { }, x * 2.0 stays f32, floats print as the shortest exact text

C, C++ and the rest

• C unions (SDL_Event) and their fields; #defines that are expressions, casts, text, or structs (raylib's RAYWHITE)
• static inline C functions (header-only helpers, MinGW's printf)
• link "glue.cpp": C++ files built and linked with the C++ compiler; Rust through a staticlib and a C header (see the guide)

Tools

• finch.toml: entry, module and header folders, libraries, flags, and settings per system; finch run with no file
• a build cache: the program's object and its link "x.c" files are reused until they or their headers change
• runtime errors show the chain of calls that led there (run, test, -g, -O0, --trace)
• finch fmt (and Format Document in editors)
• modules: import ui/button, import ui/button as btn; modules are known by their file

Library

• import thread: spawn, join, mutex, cpus; atomic_add/sub/load/store/swap/cas built in
• import fs: read/write bytes, exists, is_dir, mkdir, list, remove_dir, data_dir

Systems

• --target android (new: Finch's output compiles for Android; linking with the NDK and running on a device are not tried yet)
• CI is green again on Linux x64/ARM64, macOS, Windows and the cross tests (it had been failing since 2.4's last merge)

Docs (English and Polish) and the Kate and VS Code support are updated for all of it.

Finch 2.4.0: macOS, ARM64, methods, maps, errors as values

Finch now runs on macOS and ARM64, and gets three things real programs need: methods, maps and errors as values.

Platforms

• macOS (Apple Silicon): finch-macos-arm64.tar.gz below (needs brew install llvm@21). Apple frameworks: import "OpenGL/gl.h", link "Cocoa.framework".
• Linux ARM64 (Raspberry Pi 4/5, Graviton, …): finch-linux-arm64.tar.gz; also finch-linux-x64.tar.gz. Both need LLVM 21's libraries (libllvm21 libclang1-21 from apt.llvm.org).
• C structs by value follow AAPCS64 on ARM64 (float aggregates in vector registers, Apple's variants included).
• Cross-building: --target arm64 (runs with QEMU), --target macos, --target windows.
• CI builds and tests everything natively on Linux x86-64, Linux ARM64, macOS ARM64 and Windows: 74 tests each.

Language

struct Counter {
    map[str]int counts
}

fn Counter.add(str word) {          // a method: self is the caller's Counter, not a copy
    self.counts[word] += 1          // a missing key starts at 0
}

fn parse_port(str s) -> int! {      // ! = can fail
    n := int(s) or { return error("not a number: " + s) }
    return n
}

fn main() -> ! {
    port := parse_port("80") or 8080
    text := try read_file("words.txt")
    ...
}

• Methods: fn Point.move(int dx) { self.x += dx }, p.move(3); also on structs from C headers.
• Maps: map[K]V, ["a": 1], m[k], has, get(k, default), remove, keys, values, for k, v in m; insertion order is kept.
• Errors as values: -> T! / -> !, return error("..."), then or <value>, or { ... err ... } or try. Forgetting to handle a failure is a compile error. int(s), float(s), read_file, write_file, delete_file work with or / try too. fn main() -> ! prints the error and exits with 1.
• for i, x in list; str(x) works for arrays, maps and structs (the same text print shows).
• New example: examples/wordcount.fch.

Editors

• Kate (and KWrite/KDevelop): highlighting and language server setup in editors/kate (install.sh).
• The language server completes struct methods and map methods and shows method signatures.
• VS Code extension 2.4.0 (finch-lang-2.4.0.vsix below): new highlighting and snippets.

Docs

All three guides (beginners, technicians, engineers) and the cheat sheets, in English and Polish, cover the new features and platforms.

Finch 2.3.0: Windows, language server, VS Code

Finch now runs on Windows and has a language server with a VS Code extension.

Windows

• finch-windows-x64.zip (below): finch.exe + libclang.dll. Needs LLVM 21 (for clang) and Visual Studio Build Tools with Desktop development with C++. See Installing on Windows.
• Programs are normal .exe files. C structs follow the Microsoft x64 calling convention (1/2/4/8-byte structs in one register, others through a copy's address).
• Built and tested on Windows Server with MSVC in CI: all 59 tests pass.
• Cross-building from Linux: finch build game.fch --target windows (with MinGW-w64); finch run --target windows uses Wine. tests/windows.sh runs the whole suite that way.
• -g writes CodeView on Windows (Visual Studio debugger, WinDbg).

Editors

• finch lsp: errors as you type, hover (types, signatures, docs), go to definition, completion (variables, functions, structs, built-ins, struct fields and array/str methods after ., module members, names from C headers), document outline, parameter hints. It uses the real compiler, so the editor never disagrees with finch build.
• VS Code extension (finch-lang-2.3.0.vsix, below): highlighting, snippets, the language server, a ▶ Run button (Ctrl+F5) and Build with errors in the Problems panel. Install with Extensions → … → Install from VSIX.
• Works with any LSP editor (Neovim, Helix, Zed, Emacs, Sublime): run finch lsp.

Smaller things

• delete_file(path); stdin/stdout/stderr work everywhere (they're macros on Windows).
• Pointers print the same on every system: null or 0x….

Docs

• New cheat sheets with every function, method, operator and command: English, polski.
• Windows install, cross-building and VS Code in the technicians' guide; targets, the Microsoft ABI, the language server and the extension in the engineers' guide (en, pl).

Finch 2.2.0

New examples

• examples/opengl.fch: modern OpenGL 3.3 core with shaders, a vertex array and buffer, and a spinning, colorful triangle (GLFW).
• examples/vulkan.fch: creates a Vulkan instance, lists every GPU with its type, Vulkan version, memory heaps and queue families, then creates a logical device and gets a graphics queue.

Language and compiler

• ptr(n) and int(p) convert between numbers and pointers (OpenGL passes buffer offsets as pointers).
• .ptr works on string literals ("Finch".ptr for C struct fields).
• A comma after the last argument is allowed, which makes multi-line struct constructors tidy.
• If a header you import includes a header that's missing, the error now names the missing one.
• The .fn → .fch rename hint was removed.

The docs (technicians' guide, en/pl) have a new Graphics: OpenGL and Vulkan section. 59 tests, clean under valgrind; the self-hosted compiler still builds itself.

Finch 2.1.0

Finch source files now end in .fch instead of .fn, which is already used by other tools (for example Fennel).

• import name looks for name.fch.
• If only an old name.fn is there, the compiler says so and tells you to rename it.
• All examples, tests, the self-hosted compiler (boot/*.fch) and the docs use the new extension.

To update your own files: for f in *.fn; do mv "$f" "${f%.fn}.fch"; done

Finch 2.0.0

Finch 2.0 turns the small core of 1.0 into a complete small language, and a compiler that can build itself.

New in the language

• Structs with default values: Point(1, 2), Player(name: "Ola"), nested structs, print shows them
• Arrays []T with bounds checks: push pop insert remove clear resize find contains join slice reverse sort, for x in list
• Text that knows its length: +, .len, s[i], sub find contains starts_with ends_with split trim upper lower replace repeat, str(x), int(s), float(s)
• Memory without free: arrays, strings and structs are values; assignment copies, the end of a block frees, results move, parameters are lent. Every test runs clean under valgrind
• defer, and new(...)/free(...) for your own heap structures (lists, trees)
• Modules: import shapes → shapes.area(b), shapes.Box
• input(), read_file, write_file, file_exists, shell, exit, fn main([]str args)

C interop

• C structs by value with the System V x86-64 calling convention (raylib's Vector2/Color, libclang's CXCursor, …), C struct fields and fixed arrays
• addr(fn) gives C a callback
• link "mycode.c" compiles and links your own C files

Tools

• -g: DWARF debug info for gdb/lldb (breakpoints, locals, struct fields)
• finch run file.fn args... passes arguments to the program

Bootstrap

boot/ is a Finch compiler written in Finch (about 3,000 lines). Built by the C++ compiler, it compiles itself, and stage 2 and stage 3 produce byte-identical LLVM IR. tests/boot.sh checks it.

Branding

A logo (light and dark), an icon and a social preview: see assets/.

Docs

The guides for beginners, technicians and engineers, in English and Polish, now cover everything above. The engineers' guide includes the ownership model and the ABI work, with real compiler output.

Breaking changes from 1.0

• str now carries its length and is never null: s == null is an error (use s.len == 0). To pass text to a void* C parameter, use s.ptr.
• char * inside C structs and globals is ptr[char] (read it with str(p)); in function parameters and results it is still str.

Finch 1.0.0

The first release of Finch: a small, fast programming language on LLVM, with C-like syntax
that is simple enough to learn in an hour.

Language

• fn name(int a) -> int { ... } functions, x := 5 / int x = 5 variables
• Types: int, float, bool, char, str; sized i8…i64, u8…u64, f32, f64; pointers ptr[T] with addr(x), p.value, null
• if / else if / else, while, for i in 0..10, break, continue
• Arithmetic, comparison, logical and bitwise operators, with Go-style precedence (x & 1 == 0 means (x & 1) == 0)
• Implicit conversions only when nothing is lost; number literals adapt to their target type
• print(...) for every type

Safety without a runtime

• No silent narrowing, no signed/unsigned mixing
• Division by zero, MIN / -1 and .value on null stop with a clear runtime error and line number
• Readable compile errors with a source excerpt and a suggested fix

C interop

• import "stdio.h": functions (including variadic), enum values, numeric #defines and globals, read through libclang
• link "glfw": uses pkg-config when available; a forgotten link gets a precise suggestion

Performance

• LLVM O2 pipeline, native code, no GC. Recursive fib(40): about 0.19 s (clang -O2 on the same C: about 0.23 s)

Docs

Three guides, in English and Polish: beginners, technicians and engineers (full compiler internals). Start at the README.

Requirements

Linux x86-64, LLVM 21, libclang, CMake, Ninja. nix-shell sets everything up.