Finch/docs/en/for-technicians.md

Finch for Technicians

For people who know their way around a computer, but little or no programming. This guide covers installing Finch, using the finch tool, the whole language, memory, modules, C libraries, debugging and fixing common problems. It does not cover how the compiler works inside. For that, see the guide for engineers.

🇵🇱 Polska wersja: dla-technikow.md

---

Contents

1. What Finch is
2. Installing
3. The finch command
4. How a Finch file looks
5. Variables
6. Types
7. Operators
8. Control flow
9. Functions
10. Arrays and maps
11. Text (str)
12. Structs and methods
13. Memory: who frees what
14. Pointers
15. Built-in functions
16. Modules
17. Using C libraries
18. Errors
19. Editors: VS Code, Kate and others
20. Debugging
21. Troubleshooting
22. Project layout and tests
23. Enums and match
24. Generics
25. The standard library
26. Current limits
27. Tests: test blocks and finch test
28. A project: finch.toml
29. Threads
30. C++, Rust and Android
31. Vectors (SIMD)

---

1. What Finch is

Finch is a compiled programming language. The finch tool translates your .fch file into a real program (a native executable, like the ones made from C), using the LLVM compiler toolkit, the same backend that powers clang, Rust and Swift.

What that gives you:

• Speed close to C. No interpreter, virtual machine or garbage collector. Array bounds checks and other safety checks cost almost nothing after optimization.
• Small, standalone programs that you can copy and run.
• Memory handled for you. Lists and text are freed automatically at the end of the block that owns them, with no garbage collector involved.
• Direct access to C libraries. import "stdio.h" and call anything in it, even functions that take structs.

The design rules: one way to do each thing, C-like syntax without C's traps, and error messages that tell you how to fix the problem.

---

2. Installing

The Finch compiler is written in Finch (see the engineers' guide). It runs on Linux (x86-64 and ARM64), macOS (Apple Silicon and Intel) and Windows (x86-64), and builds programs for all of them. On every system it needs clang (it compiles each program with it) and libclang from LLVM 21 (it reads C headers with it).

Option A: a ready build

Download the archive for your system from the releases and unpack it. Keep runtime/ and std/ next to the finch file (or install it, below).

System	Archive	Also install
Linux x86-64	finch-linux-x64.tar.gz	clang 21 and libclang (table below)
Linux ARM64 (Raspberry Pi 4/5, Graviton…)	finch-linux-arm64.tar.gz	the same
macOS, Apple Silicon	finch-macos-arm64.tar.gz	xcode-select --install (clang and the system headers), brew install llvm@21 (libclang)
macOS, Intel	finch-macos-x64.tar.gz	the same
Windows x64	finch-windows-x64.zip (finch.exe with libclang.dll)	llvm-mingw (the ucrt-x86_64 zip): unpack it and put its bin folder on your PATH

On Linux:

Distribution	Packages
Debian / Ubuntu	clang-21 libclang-21-dev from apt.llvm.org, pkg-config
Fedora	clang clang-devel pkgconf
Arch	clang pkgconf
Nix	nix-shell in the repository gives all of it

On Windows, llvm-mingw gives Finch clang, the C headers and the linker in one folder; Windows programs built with it need nothing else to run. Keep libclang.dll next to finch.exe.

Option B: build it yourself

git clone https://github.com/Nexoniarz/Finch.git
cd Finch
nix-shell                        # Linux: clang, libclang, pkg-config (or install them with your distribution)
bootstrap/build.sh               # build/finch
./build/finch version

bootstrap/build.sh compiles the seed (bootstrap/<system>.ll, the compiler's own LLVM IR) into a first compiler, builds src/ with it, builds src/ again with the result and checks the two are identical. If libclang isn't where the linker looks, tell it: FINCH_LIBCLANG="-L/usr/lib/llvm-21/lib -lclang-21" bootstrap/build.sh.

On a Mac, with Homebrew's LLVM:

brew install llvm@21
export FINCH_CLANG="$(brew --prefix llvm@21)/bin/clang"
export FINCH_LIBCLANG="-L$(brew --prefix llvm@21)/lib -lclang"
export FINCH_LLVM_INCLUDE="$(brew --prefix llvm@21)/include"
bootstrap/build.sh

On Windows, in Git Bash, with llvm-mingw on the PATH and the official LLVM for Windows (for libclang.dll and its headers) unpacked to C:/llvm:

export FINCH_LIBCLANG="C:/llvm/bin/libclang.dll"
export FINCH_LLVM_INCLUDE="C:/llvm/include"
export FINCH_LDFLAGS="-LC:/llvm/bin"
bootstrap/build.sh               # build/finch.exe, with libclang.dll copied next to it

Building for another system

--target builds a program for another system. Finch needs that system's C compiler to link:

--target	Builds	C compiler used	finch run uses
windows	a Windows .exe	x86_64-w64-mingw32-gcc (MinGW-w64)	Wine
arm64	an ARM64 Linux program	aarch64-linux-gnu-gcc	qemu-aarch64
linux	an x86-64 Linux program	clang --target=…
macos	a macOS program (on a Mac: for the other processor)	clang --target=…
any LLVM triple	e.g. aarch64-unknown-linux-gnu	clang --target=<triple>

finch build game.fch --target windows      # game.exe
finch run game.fch --target arm64          # builds for ARM64 and runs it with QEMU
FINCH_CC=aarch64-unknown-linux-gnu-gcc finch build tool.fch --target arm64   # another compiler name

On Nix the compilers are pkgsCross.mingwW64.buildPackages.gcc and pkgsCross.aarch64-multiplatform.buildPackages.gcc.

Putting finch on your PATH (optional)

sudo bootstrap/install.sh          # /usr/local/bin/finch, and /usr/local/share/finch/{runtime,std}
bootstrap/install.sh ~/.local      # or into your own folder
finch version

At run time Finch needs clang (it compiles each program's IR and links it). The small runtime library is built once and kept in ~/.cache/finch. FINCH_CC names a different compiler to link with; FINCH_PATH adds folders to look for modules in.

---

3. The finch command

finch run   <file.fch> [args...]    compile and run right away
finch build <file.fch> [-o name]    compile into a program (default name: the file's name)
finch test  <file.fch>              run its test "..." { } blocks (section 27)
finch fmt   [--check] [files/dirs]  tidy the indentation of .fch files (all under here by default)
finch ir    <file.fch>              print the LLVM IR (for the curious)
finch lsp                          the language server, for editors
finch version                      show the version

options:
  -l <lib>          link a C library, same as  link "lib"  in the file
  -I <dir>          look for C headers there too
  --target <name>   build for another system: windows, linux, arm64, macos, android, or an LLVM triple
  --cpu <name>      use every instruction of a processor: native (this one), x86-64-v3 (AVX2),
                    x86-64-v4 (AVX-512), apple-m1, ... (section 31)
  -g                add debug info (for gdb and lldb)
  -O0               skip optimizations
  --trace           runtime errors show the chain of calls (on anyway for run, test, -g and -O0)
  --no-trace        they don't (a plain finch build doesn't: keeping the chain makes calls slower)

In a folder with a finch.toml (section 28), finch run, finch build and finch test need no file name.

The compiled program and the C files it builds (link "x.c") are kept in a cache (~/.cache/finch, or %LOCALAPPDATA% on Windows). The second build of the same code, or of code whose C files did not change, skips that work.

finch fmt changes only the layout: four spaces per { } level, no spaces at line ends, at most one empty line in a row. Lines that continue an expression (inside ( ) or after a +) and """ text keep their shape. finch fmt --check changes nothing and fails if a file would change (for CI). Editors with the language server format on request.

Examples:

finch run hello.fch                 # prints the output
finch run tool.fch input.txt -v     # arguments after the file go to the program
finch build game.fch -o mygame      # creates ./mygame
finch build game.fch -g -O0         # a build for the debugger

finch run passes on your program's exit code. If the program crashes, it says how (for example the program crashed: Segmentation fault).

---

4. How a Finch file looks

// comments start with two slashes
/* or span
   several lines */

import "math.h"          // C headers (optional), at the top
import shapes            // Finch modules (optional): shapes.fch next to this file
link "m"                 // C libraries or C files to link (optional)

struct Point {           // your own types
    int x
    int y
}

fn main() {              // the program starts here
    print("Hello")
}

Rules worth knowing:

• One statement per line. There are no semicolons. To split a long expression, break the line after an operator (a +⏎ b) or anywhere inside brackets ( ) or [ ].
• Curly braces are always required after if, else, for, while, and the opening { goes on the same line.
• No brackets around conditions: if x > 5 {, not if (x > 5) {.
• Functions and structs can be in any order in the file.
• main is fn main(), fn main() -> int (returns the exit code) or fn main([]str args) (gets the command-line arguments; args[0] is the program's own path).

---

5. Variables

x := 5               // new variable, type inferred (int)
int y = 10           // new variable, type written explicitly
int z                // no value: starts at zero ("" for str, [] for arrays, null for pointers)
Point p              // a struct with no value: zero, or the struct's default values

x = 7                // assign
x += 1               // also -= *= /= %=

• A name can be declared once in a function. Finch does not allow reusing a name in an inner block (no "shadowing"), because that is a common source of confusion.
• Variables exist from their declaration to the end of the { } block they are in.
• Names: ASCII letters, digits and _, not starting with a digit. Non-ASCII letters are allowed only inside strings. Type names (int, u8, …), built-in function names and keywords are reserved.

Keywords: fn return if else while for in break continue true false null import link struct enum match defer or try const export

Constants

const WIDTH = 640
const HEIGHT = WIDTH / 2          // from other constants
const f32 GRAVITY = 9.8           // with a type
const TITLE = "My game"

A constant is written at the top level of a file, next to the functions, and can't be changed. It is made of numbers, text, true/false, chars, other constants and operators; a module's constant is shapes.SIDES.

---

6. Types

Everyday types

Type	Holds	Example
int	whole number, 64-bit (same as i64)	42, -7, 0xFF, 1_000_000
float	decimal number, 64-bit (same as f64)	3.14
bool	true or false
char	one byte-sized character	'A', '\n'
str	text	"hello\tworld"
[]T	a list (array) of T	[1, 2, 3]
map[K]V	values of type V found by a key of type K	["a": 1, "b": 2]
your structs	named groups of values	Point(1, 2)

String and char escapes: \n new line, \t tab, \r, \0, \\, \", \'.

Sized types (for files, hardware, C libraries)

Signed	Range	Unsigned	Range
i8	−128 … 127	u8	0 … 255
i16	−32 768 … 32 767	u16	0 … 65 535
i32	about ±2.1 billion	u32	0 … about 4.29 billion
i64	about ±9.2 × 10¹⁸	u64	0 … about 1.8 × 10¹⁹

f32 is a 32-bit decimal number (about 7 significant digits), f64 a 64-bit one (about 15–16).

Conversions

Finch converts automatically only when nothing can be lost:

From	To	Automatic?
a smaller whole number	a bigger one of the same signedness (i8→i32, u8→u64)	✅
unsigned	a strictly bigger signed (u8→i16, u32→i64)	✅
any whole number	float / f32	✅
f32	f64	✅
null	any pointer	✅
any pointer	ptr, and ptr to any pointer	✅
anything else		❌ write it: type(value)

Number literals adapt. A number written in the code fits into any type that can hold it: u8 b = 200 works, u8 b = 300 is an error. The same applies to constants imported from C headers.

Explicit conversions use the type name like a function:

int(3.99)        // 3     (cuts off the fraction)
float(7) / 2     // 3.5
u8(300)          // 44    (keeps the lowest 8 bits)
int('A')         // 65
char(66)         // 'B'
bool(0)          // false (any non-zero number is true)
str(42)          // "42"  (also floats, bools, chars; str([]u8) turns bytes into text)
int("42")        // 42    (stops the program if the text isn't a number)
float("2.5")     // 2.5
ptr(p)           // a typed pointer as an untyped one
ptr(16)          // a number as a pointer (C APIs that pass offsets as pointers, like OpenGL)
int(p)           // a pointer as a number (its address)
str(p)           // a C char pointer as text

Fixed-size numbers wrap around, like real hardware: a u8 holding 255 plus 1 becomes 0. Calculations happen in the type of the values involved, so u8(250) + 10 is 4, not 260.

Decimal numbers: what is guaranteed

f32 and f64 are IEEE 754 numbers, and Finch computes them exactly as written, the same on every processor and with every --cpu:

• Each operation rounds once, in the order written. a * b - c * d is two multiplies and a subtract, never folded into a fused multiply-add (C compilers often do that by default, which changes the last digits).
• Nothing is reordered or simplified: (a + b) + c is not turned into a + (b + c), and x * 0.0 is not assumed to be 0 (it is NaN when x is). The one exception is v.sum() on a vector, which adds the lanes in the fastest order.

When speed matters more than the last bit, ask for it by name:

fma(a, b, c)	a * b + c with a single rounding, always. One instruction where the processor has FMA (with --cpu, on ARM64); a slower library call elsewhere.
muladd(a, b, c)	a * b + c the fastest way on this processor: fused where it can be, a multiply and an add where not.

Both work on numbers and on vectors (v.fma(b, c), v.muladd(b, c)).

Numbers as bits. File formats and model weights store numbers as raw bits. These look at the bits without converting the value (all of them also work lane by lane on vectors):

f32_bits(x) / f32_from_bits(u)	f32 ↔ the u32 with the same bits (f32_bits(1.0) is 0x3f800000)
f64_bits(x) / f64_from_bits(u)	f64 ↔ u64
f16_to_f32(h) / f32_to_f16(x)	half precision, kept in a u16, ↔ f32 (rounded to the nearest)
bf16_to_f32(b) / f32_to_bf16(x)	bfloat16, kept in a u16, ↔ f32 (rounded to the nearest, ties to even)

[]u16 weights = read_weights()               // f16 numbers from a file
v := f16_to_f32(u16x8(weights, 0))           // 8 of them as f32, at once

---

7. Operators

By priority (higher binds tighter)

Priority	Operators	Meaning
5	* / % << >> &	multiply, divide, remainder, shift left/right, bitwise AND
4	+ - | ^	add (and join text), subtract, bitwise OR, bitwise XOR
3	== != < <= > >=	comparisons
2	&&	logical AND
1	||	logical OR

Unary (in front of a value): -x negate, !x logical NOT, ~x flip all bits.

Different from C, on purpose: bit operators bind tighter than comparisons, so flags & 4 != 0 means (flags & 4) != 0.

Notes:

• / on whole numbers rounds toward zero: 7 / 2 is 3. % takes the sign of the left side.
• Dividing by zero stops the program with runtime error: division by zero and the line number.
• && and || only evaluate the right side if needed.
• Text: + joins, == != compare contents, < > compare alphabetically (byte by byte).
• Pointers can be compared with == and !=, including against null. A str is never null.
• Arrays and structs can't be compared with ==; compare their parts.

---

8. Control flow

if can also give a value; each branch holds one value, and the else is needed:

label := if score > 100 { "high" } else if score > 10 { "mid" } else { "low" }
f32 speed = if running { 2.5 } else { 1.0 }

if x > 10 {
    ...
} else if x > 0 {
    ...
} else {
    ...
}

while count > 0 {
    count -= 1
}

for i in 0..10 {          // i = 0, 1, …, 9  (the end is not included)
    if i == 3 { continue }
    if i == 8 { break }
}

for name in names {       // every element of an array (or every char of a str)
    print(name)
}

for i, name in names {    // with its index: 0, 1, 2, ...
    print(i, name)
}

for key, value in ages {  // every entry of a map, in the order the keys were added
    print(key, value)     // (for key in ages: just the keys)
}

• A condition must be a bool. if x { with a number is an error; write if x != 0 {.
• In for i in a..b, both ends are evaluated once. i is an int and cannot be changed in the loop.
• In for x in list, x cannot be changed either. To change elements, loop over the indexes: for i in 0..list.len { list[i] = ... }. Adding to the list inside the loop is fine.
• while true { ... } loops until a break or return.
• Code after return, break or continue in the same block is an error, because it can never run.

defer

defer runs a statement when the current block ends, however it ends: normally, by return, break or continue. Several defers run in reverse order. Handy for cleanup:

f := fopen("data.txt", "r")
defer fclose(f)
// ... use f; it is closed when the block ends, on every path

A deferred statement can't contain return, break or continue.

---

9. Functions

fn name(type1 param1, type2 param2) -> return_type {
    ...
    return value
}

fn no_result(str message) {       // no "->": returns nothing
    print(message)
}

• Arguments behave like copies: changing a parameter never changes the caller's variable. (Finch only really copies when needed: a function that doesn't change an array gets it for free.) To change the caller's variable, pass a pointer: see Pointers.
• A function with -> type must return a value on every path. Finch checks this.
• A function cannot be defined inside another function.
• A function that can fail is written -> int! (or -> ! with no result); see Errors as values.
• Long calls can be split over several lines inside the brackets; a comma after the last argument is fine.

---

10. Arrays and maps

nums := [5, 3, 8]          // an array of int
[]str names                // an empty array of str
grid := [[1, 2], [3, 4]]   // arrays of arrays
[]f32 xs = [1, 2.5]        // the type decides what the numbers become

Operation	Meaning
a.len	number of elements
a[i]	element i (from 0); out of range stops the program with a clear message
a[i] = x	change an element
a.push(x)	add at the end
a.pop()	remove the last one and give it back
a.insert(i, x)	put x at position i, moving the rest
a.remove(i)	remove position i and give it back
a.clear()	remove everything
a.resize(n)	make it n long (new elements are zero)
a.contains(x), a.find(x)	is x there? its index, or -1 (numbers, chars, bools, str)
a.sort(), a.reverse()	in place (numbers, chars, str)
a.slice(s, e)	a new array with elements s … e-1
a.join(sep)	for []str: one text with sep between the parts
a.ptr	the address of the first element (for C)
print(a)	prints [1, 2, 3]

Assigning copies: after b := a, changing b does not change a.

Maps

A map[K]V finds values by a key. Keys can be whole numbers, char, bool or str; values can be anything (arrays, structs, other maps). Iterating goes in the order the keys were first added.

ages := ["anna": 31, "bob": 25]     // a map literal: map[str]int
map[str][]str groups                // an empty map
map[int]str names = [:]             // [:] is an empty map where the type is known

Operation	Meaning
m[k]	the value for k; a missing key stops the program with the key "k" is not in the map
m[k] = v	add or replace
m[k] += 1, m[k].push(x), m[k].field = …	changing a missing key adds it first, with the value type's default (0, "", [], …)
m.len	the number of keys
m.has(k)	is k there?
m.get(k, default)	the value, or default (only computed when needed)
m.remove(k)	removes k; true if it was there
m.clear()	removes everything
m.keys(), m.values()	new arrays, in insertion order
print(m), str(m)	{"anna": 31, "bob": 25}

map[str]int counts
for word in text.split(" ") {
    counts[word] += 1                 // counting: a new word starts at 0
}
for word, n in counts {
    print(word, n)
}

Lookups are hash-based (average constant time). Like arrays, maps own their keys and values, copy on assignment, and are freed at the end of their block. Don't add or remove keys of a map inside a for over that same map; collect them in an array and change the map after the loop.

---

11. Text (str)

s := "Hello"
s += ", world"            // join
print(s.len, s[0])        // 12 H   (.len counts bytes; ą, ż, … take 2)
s[0] = 'J'                // change a character

Method	Gives back
s.sub(a, b)	the part from a to b-1
s.find(t)	where t starts, or -1
s.contains(t), s.starts_with(t), s.ends_with(t)	bool
s.split(sep)	[]str; split("") gives single characters
s.trim()	without spaces/newlines at both ends
s.upper(), s.lower()	A–Z / a–z changed (ASCII letters)
s.replace(a, b)	every a replaced by b
s.repeat(n)	s n times
s.bytes()	[]u8 with the bytes
s.ptr	a ptr[char] for C (valid while s lives)

Values go into text with \(...): any code, and , 2 after a number for two digits after the point. A \ before the ( you want to keep: "\\(not code)".

print("hp \(hp) of \(max_hp), speed \(v, 2), name \(p.name.upper())")

str keeps its length, so .len is instant, and it is always NUL-terminated, so passing it to C as char* works. The other way round, a C function that gives back a char * gives you a str (a copy is made when you keep it), and str(p) reads a ptr[char] you got some other way.

Text over several lines goes between """. The line break after the opening quotes is dropped, and so is the indentation of the closing quotes, from every line, so the text can be indented with your code:

shader := """
    #version 330
    void main() { gl_Position = vec4(0.0); }
    """

Numbers as text: str(x) is the shortest text that reads back as the same number (0.1, 0.30000000000000004, 1e+20); str(x, 2) always has two digits after the point (3.14).

---

12. Structs and methods

struct Player {
    str name
    int lives = 3            // a default value
    []int scores
    Point pos                // structs inside structs
}

p := Player(name: "Ola")                     // by name: missing fields get their default (or zero)
q := Point(1, 2)                             // in order: then every field must be given
p.lives -= 1
p.scores.push(10)
p.pos.x = 5
print(p)       // Player(name: "Ola", lives: 2, scores: [10], pos: Point(x: 5, y: 0))

• Assigning or passing a struct copies it, together with its arrays and text.
• A struct can't contain itself directly; use ptr[Node] or []Node for that field (trees, lists).

Methods

A method is a function that belongs to a struct: fn Struct.name(...). Inside, self is the struct it was called on, and it is the caller's value itself, not a copy: changes to self stay.

fn Player.heal(int amount) {
    self.lives += amount
}

fn Player.is_alive() -> bool {
    return self.lives > 0
}

p := Player(name: "Ola")
p.heal(2)                  // p.lives is now 5
if p.is_alive() { ... }

team[0].heal(1)            // on an array element, a field, m[key], through a ptr[Player] ...

• A method goes in the same file (module) as its struct, and is available wherever the struct is.
• Methods can also be added to structs from C headers: fn Vector2.length() -> f32 { ... }.
• A method can't have the name of a field.
• Calling a method that changes self on a loop variable (for p in team { p.heal(1) }) is an error, because the loop variable is read-only; use for i in 0..team.len { team[i].heal(1) }.
• Like functions, methods can fail (-> !); see Errors as values.

---

13. Memory: who frees what

You never free arrays, text or structs. Finch does it for you, at a predictable moment: when the block that owns the value ends (}), or earlier on return, break, continue.

• A variable owns its value. Assigning copies it, so two variables never share one list.
• A value produced by a function call or an expression is moved where it's stored: no copy.
• return list moves the variable out of the function: no copy.
• Function parameters are lent: the function gets the caller's value without a copy. If the function changes the parameter, Finch makes it a private copy first. You never notice except in speed.

For memory you manage yourself (linked lists, trees, sharing between structures):

node := new(Node(value: 1))     // put a value on the heap, get a ptr[Node]
defer free(node)                // free(...) gives it back (and frees its arrays and text)

Memory from C (malloc, library objects) is freed with C's functions, as in C.

---

14. Pointers

A pointer holds the address of a value. Finch uses words instead of C's * and &:

C	Finch	Meaning
int *p	ptr[int] p	p points to an int
&x	addr(x)	the address of x (also addr(a[i]), addr(s.field))
*p	p.value	the value p points to
p->field	p.field	a field of the struct p points to
p[i]	p[i]	C-style indexing (no bounds check)
NULL	null	points nowhere
void *	ptr	points to something of unknown type

fn double(ptr[int] p) {
    p.value = p.value * 2
}

x := 21
double(addr(x))           // x is 42

If a struct has its own field called value, then p.value on a pointer to it means that field.

Using .value, .field or [i] on a null pointer stops the program with a clear message.

⚠️ A pointer to a variable must not be used after the variable's block has ended. Finch does not check this.

---

15. Built-in functions

Function	What it does
print(a, b, ...)	Prints all values separated by spaces, then a new line. Works with every type, including arrays and structs.
input(), input("question")	Reads one line typed by the user (without the newline). Empty text at end of input.
read_file(path)	The whole file as str. Stops the program with a clear message if it can't be read, unless handled: read_file(p) or ....
write_file(path, text)	Writes (replaces) the file; gives back true if it worked. With or / try, the failure carries the reason.
file_exists(path)	true / false
delete_file(path)	Deletes the file; true if it worked (or the reason, with or / try).
error(message)	The failure a fallible function returns: return error("...").
shell(command)	Runs a shell command, gives back its exit code.
exit(code)	Ends the program right away.
addr(x)	A pointer to x; addr(function) gives C a function pointer (callback).
new(value), free(p)	Manual heap memory (see Memory).
fma(a, b, c), muladd(a, b, c)	a * b + c with one rounding / the fastest way (see Decimal numbers).
f32_bits(x), f32_from_bits(u), f16_to_f32(h), …	A number's bits, and half-precision numbers (see Decimal numbers).
int(x), str(x), u8(x), …	Conversions (see Conversions). str(x) works on every type and gives the same text print shows. int(text) or 0 handles text that isn't a number.

---

16. Modules

Split a program into files. import shapes loads shapes.fch from the same folder (or from a folder listed in the FINCH_PATH environment variable, separated by :).

// shapes.fch
struct Box {
    float w
    float h
}

fn area(Box b) -> float {
    return b.w * b.h
}

// main.fch
import shapes

fn main() {
    b := shapes.Box(2, 3)
    print(shapes.area(b))
    shapes.Box other         // a module's type in a declaration
}

• Everything in a module is used with the module's name in front: shapes.area, shapes.Box.
• A module doesn't have main. Modules can import other modules.
• Modules in folders: import ui/button loads ui/button.fch and is used as button.draw().
• Another name: import ui/button as btn → btn.draw(). Two imports can't use the same name.

---

17. Using C libraries

Step 1: import the header

import "stdio.h"
import "GLFW/glfw3.h"     // a path inside the system include folders
import "mylib.h"          // a header next to your .fch file

Finch reads the header with libclang (clang's C parser) and makes these usable:

• functions, including ones with a variable number of arguments, like printf,
• structs, by value and by pointer (Vector2, SDL_Rect, CXCursor, …), with their fields,
• enum values and simple #define constants (M_PI, GL_COLOR_BUFFER_BIT),
• global variables, like stdout and stderr.

Step 2: link the library

link "glfw"              // uses libglfw.so (pkg-config is asked first, if installed)
link "helpers.c"         // compile and link your own C file (next to the .fch file)
link "prebuilt.a"        // or an object file / static library

If you forget the link line, Finch tells you exactly what is missing:

error: glfwInit, glfwCreateWindow, glfwMakeContextCurrent and 5 more come from "GLFW/glfw3.h", but its library isn't linked
  ...
      link "glfw"

How C types appear in Finch

C	Finch
char, signed char, unsigned char	char, i8, u8
short, int, long, long long	i16, i32, i64, i64 (by actual size)
unsigned …	u16, u32, u64
float, double	f32, f64
_Bool / bool	bool
enum	the matching signed integer
char * as a parameter or result	str
char * inside a struct or behind a pointer	ptr[char] (use str(p) to read it)
struct X by value	X, a struct with the same fields
struct X *, int *, …	ptr[X], ptr[i32], …
int arr[16] inside a struct	[16]i32: index it and use .len
void *, function pointers, incomplete structs	ptr

Example: structs and callbacks

import "raylib.h"
link "raylib"

fn main() {
    InitWindow(800, 450, "Finch")
    while !WindowShouldClose() {
        BeginDrawing()
        ClearBackground(Color(r: 30, g: 30, b: 40, a: 255))
        DrawCircleV(Vector2(400, 225), 50, Color(255, 136, 0, 255))
        EndDrawing()
    }
    CloseWindow()
}

To give C a function to call back (like qsort's comparator), use addr(myFunction). Its parameters must be C types (numbers, pointers, C structs).

Graphics: OpenGL and Vulkan

Both work directly; examples/opengl.fch and examples/vulkan.fch are complete programs.

• OpenGL 3+ on Linux: the modern functions (glCreateShader, glGenVertexArrays, …) are only declared when GL_GLEXT_PROTOTYPES is defined. Finch can't define C macros, so put the includes in a tiny header next to your program and import that:

  // opengl.h
  #define GL_GLEXT_PROTOTYPES
  #include <GL/gl.h>
  #include <GL/glext.h>
  #include <GLFW/glfw3.h>
  

  Then import "opengl.h", link "glfw", link "GL". Out-parameters use addr(...) (glGenBuffers(1, addr(vbo))), buffer data uses .ptr (vertices.ptr), and byte offsets use ptr(...) (glVertexAttribPointer(1, 3, GL_FLOAT, GL_FALSE, stride, ptr(8))).

• Vulkan: import "vulkan/vulkan.h" and link "vulkan". Vulkan's create-info structs are built with named fields (missing ones are zero), handles are ptr, and lists come from the usual "call twice" pattern: once for the count, once with list.ptr after list.resize(count). Function-like macros such as VK_MAKE_API_VERSION aren't available; compute the number instead (1 << 22 is Vulkan 1.0).

What does not work yet

• C unions and structs with bit fields passed to or returned from a C function by value (pointers to them work, and so do unions as variables: SDL_Event e, e.type, e.key.key, SDL_PollEvent(addr(e))).
• Function-like macros (#define MAX(a, b) ...). Macros that are a number, a text, an expression of them ((1u << 3), ((Uint64)1), (A | B)) or a struct of numbers (raylib's RAYWHITE, (Color){ 245, 245, 245, 255 }) work.
• long double, 128-bit integers.

---

18. Errors

Errors as values

Some failures are normal: the user types abc, a file is missing. Finch handles them without exceptions and without hidden control flow. A function that can fail says so with ! after its result type, and fails with return error("message"):

fn parse_port(str text) -> int! {
    n := int(text) or { return error("'" + text + "' is not a number") }
    if n < 1 || n > 65535 {
        return error("port " + str(n) + " is out of range")
    }
    return n
}

fn save(str path, str text) -> ! {     // can fail, gives back nothing
    try write_file(path, text)
}

The caller must handle the failure, in one of three ways (forgetting is a compile error):

Code	On failure
port := parse_port(s) or 8080	use this value instead (it's only computed on failure; it can be another call with or)
port := parse_port(s) or { print(err); return }	run the block; err is the message (a str). The block must leave (return, break, continue, exit) unless the result isn't used.
port := try parse_port(s)	fail the current function with the same error (it must be fallible too)

fn load(str path) -> Config! {
    text := try read_file(path)
    port := try parse_port(text.trim())
    return Config(port: port)
}

fn main() -> ! {                // main can fail too: the error is printed, and the exit code is 1
    config := try load("app.conf")
    ...
}

Built-ins that can fail work the same way: int(text), float(text), read_file, write_file, delete_file. Without or / try they behave as before (int("x") stops the program, write_file gives back a bool).

Under the hood a fallible function returns its value plus a flag and the message: no allocation on success, no unwinding, and the cost of a failure is building its message.

Compile errors

game.fch:12:9: error: 'score' must be int, but this is str
   12 |     score = "high"
      |             ^

Format: file:line:column: error: explanation, then the line with a ^ under the spot.

Runtime errors

Instead of undefined behavior (as in C), Finch stops with a message and exit code 1:

Message	Cause
runtime error: division by zero	/ or % by a variable that was 0
runtime error: division overflows …	the smallest signed number divided by −1
runtime error: index 5 is out of range (the length is 3)	a[5] on a shorter array or str
runtime error: pop() on an empty array
runtime error: used .value on a null pointer	also .field and [i] through null
runtime error: can't turn "x" into int	int(...) / float(...) on text that isn't a number
runtime error: can't read the file "…"	read_file on a missing or unreadable file (handle it with or)
runtime error: the key "x" is not in the map …	m["x"] when the map has no such key (use .has or .get)
runtime error: called .f() on a null pointer	a method called through a null ptr[T]
runtime error: assert failed: …	assert(cond, "…") with a false cond

Under the message comes the chain of calls that led there, the innermost first:

game.fch:6: runtime error: index 3 is out of range (the length is 2)
  in Enemy.next (game.fch:6)
  in step (game.fch:10)
  in main (game.fch:15)

finch run, finch test, -g and -O0 builds keep it; a plain finch build leaves it out because keeping it costs time in every call (about 3x in a program that is nothing but tiny calls, much less in a real one). --trace puts it in.

---

19. Editors: VS Code, Kate and others

Every editor feature comes from the same language server, finch lsp, which uses the real compiler: errors as you type, types and docs on hover, go to definition, completion (fields, methods, map and array methods after ., module members, names from C headers), the file's outline, and parameter hints.

Kate (and KWrite, KDevelop)

editors/kate/install.sh

It installs the highlighting (~/.local/share/org.kde.syntax-highlighting/syntax/finch.xml) and adds finch to Kate's LSP client settings, keeping your other servers. Restart Kate and enable the LSP Client plugin. To run programs, add finch run %f as a target in the Build & Run plugin; Finch's file:line:column: error: messages are then clickable. Details: editors/kate/README.md.

VS Code

The Finch extension (editors/vscode, also attached to each release as a .vsix file) gives you: highlighting, errors as you type, completion (also fields and methods after .), types on hover, go to definition (F12), an outline of the file, parameter hints, snippets, and a ▶ Run button (Ctrl+F5). Errors from Finch: Build This File appear in the Problems panel.

Install: Extensions → … → Install from VSIX… → pick finch-lang-*.vsix. The extension runs finch from your PATH; if it is somewhere else, set Finch: Path in the settings.

Others

Neovim, Helix, Zed, Emacs, Sublime and any other editor that speaks the Language Server Protocol: run finch lsp for files ending in .fch (stdin/stdout, no options).

20. Debugging

finch build game.fch -g -O0 -o game
gdb ./game
(gdb) break game.fch:12
(gdb) run
(gdb) bt                # where are we, through which functions
(gdb) info locals       # all variables
(gdb) print player.lives

-g adds debug info (lines, functions, variables, struct fields). -O0 keeps every variable visible; without it the optimizer may remove some. On Windows the debug info is DWARF as well: use the lldb that comes with llvm-mingw, or gdb.

---

21. Troubleshooting

Problem	Solution
can't find the C header 'x.h'	The library's development files are missing. Install them (Debian: libx-dev; Nix: add to shell.nix).
… come from "x.h", but its library isn't linked	Add link "name" at the top of the file.
the library 'x' wasn't found	Not installed, or a wrong name. On Nix, add it to shell.nix and run inside nix-shell.
the C function 'f' can't be used from Finch yet	It uses a union, bit fields or another unsupported type by value. Look for a variant that takes pointers.
--cpu native: the program stops with Illegal instruction on another computer	It was built for the processor that built it. Build without --cpu, or with an older one (x86-64-v2).
can't find the module 'x'	Put x.fch next to the importing file, or set FINCH_PATH.
couldn't build the Finch runtime	No working C compiler. Install gcc or clang, or set CC.
A library is not found when the program starts	It was linked from a folder the system doesn't search. Run inside the same nix-shell, or install it system-wide.
Windows: no C compiler found to link with ('clang')	Put llvm-mingw's bin folder on your PATH (section 2).
Windows: finch.exe doesn't start (missing libclang.dll)	Keep libclang.dll next to finch.exe.
macOS: finch doesn't start (Library not loaded: …libLLVM…)	brew install llvm@21.
macOS: can't find the C header 'stdio.h'	Install the command line tools: xcode-select --install.
--target arm64: no C compiler found to link with	Install aarch64-linux-gnu-gcc (Debian: gcc-aarch64-linux-gnu), or set FINCH_CC.
clang inside nix-shell can't find stdio.h	You have an old shell.nix: llvmPackages.clang must be listed before llvmPackages.libclang.
A program never ends	A loop condition never becomes false. Press Ctrl+C.

---

22. Project layout and tests

Finch/
├── src/            the compiler, in Finch (lexer, parser, gen: LLVM IR as text, cimport: libclang, lsp, main ...)
├── std/            the standard library, in Finch: json, path, time, proc, fs, thread
├── runtime/        finch_rt.c: the small runtime (text, arrays, maps, input, files)
├── bootstrap/      build.sh, install.sh and the seeds (the compiler's own IR, one per system)
├── examples/       hello, tour, types, structs, todo, guess, wordcount, c_import, simd, window, opengl, vulkan, raylib, llvm
├── tests/
│   ├── run/ new/   programs + the exact output they must print (.out), input (.in)
│   ├── fail/ new/fail/   programs that must fail, with the expected error in line 1
│   ├── tool/       finch test, finch fmt, the chain of calls, a finch.toml project
│   ├── run.sh      the test runner (MEMCHECK=1 also checks memory with valgrind)
│   ├── cross.sh    every test built for Windows / ARM64 and run under Wine / QEMU
│   └── lsp_test.py the language server, talked to like an editor does
├── editors/        the VS Code extension (vscode/), Kate highlighting and LSP setup (kate/)
├── docs/           this documentation (en, pl), including the cheat sheet
└── shell.nix       the Nix development environment

tests/run.sh                 # programs, expected errors, -g builds, a shared library, the language server
MEMCHECK=1 tests/run.sh      # the same under valgrind: no leaks, no bad memory access
tests/cross.sh windows       # every test built for Windows and run with Wine
tests/cross.sh arm64         # every test built for ARM64 Linux and run with QEMU

---

23. Enums and match

An enum is a type with a short list of named values.

enum Color { Red, Green, Blue }
enum Status { Ok = 200, NotFound = 404 }      // give a variant a number if it needs one

c := Color.Green
print(c)                    // Green
print(int(Status.NotFound)) // 404
print(Color(2))             // Blue: a number turned into the enum (checked: Color(7) is an error)

Variants are written Color.Red. They can be compared with == and != (not with <), used as map keys, struct fields and array elements, and an enum can have methods like a struct: fn Color.next() -> Color { ... }.

match picks what to do from a value, instead of a ladder of if:

match c {
    Red -> print("warm")                  // inside a match on an enum, the bare name is enough
    Green, Blue -> print("cool")          // several values for one arm
}

size := match n {                         // as an expression: it gives a value
    1, 2, 3 -> "small"
    4, 5 -> "medium"
    else -> "large"
}

match word {
    "quit" -> {
        print("bye")
        return
    }
    else -> print("what?")
}

match works on enums, whole numbers, chars, text and bools. The arms are tried in order. A match on an enum has to handle every variant or end with else (the compiler says which are missing); any other match needs else. In an expression, every arm gives the same type.

Variants that hold values

A variant can carry values. Make one with Shape.Circle(2.0), take them out with match, which names them:

enum Shape {
    Circle(float)
    Rect(float, float)
    Point
}

fn Shape.area() -> float {
    return match self {
        Circle(r) -> 3.14 * r * r
        Rect(w, h) -> w * h
        Point -> 0.0
    }
}

_ ignores a value. match must handle every variant (or end with else). Printing shows Rect(2, 3.5). Such an enum is copied and freed like a struct; it can't be compared with == (match on it). Variants of these enums can't have numbers.

24. Generics

Write a function or a struct once for any type, with the type as a name in square brackets:

fn max[T](T a, T b) -> T {
    if a > b {
        return a
    }
    return b
}

struct Stack[T] {
    []T items
}

fn Stack[T].push(T x) {
    self.items.push(x)
}

print(max(3, 9), max("apple", "pear"))    // T is worked out from the arguments
print(max[float](1, 2.5))                 // or written out, where it can't be worked out
s := Stack[int]()                         // a generic struct is always written with its type
s.push(7)

Several parameters work (struct Pair[A, B]), and so do nested types (Stack[Pair[int, str]]). Each use makes its own copy of the code, so a generic is as fast as code written by hand. There are no constraints: if T can't do what the function does (a > b on a struct), the error says so and tells which version it was building, like (while building bigger[Point]).

25. The standard library

Modules that come with Finch, written in Finch. import json finds json.fch next to your file first, and the library's second, so your own file of the same name wins.

Module	What it does
path	join, base, dir, ext, stem, parts, clean, is_abs: paths as text, separated by /
time	now(), millis() (a clock for measuring), sleep(ms), date(t), local(t), format(t, "%Y-%m-%d"), days_in_month
proc	run(cmd) (the exit code), output(cmd) (what it printed; an error if it failed), env(name, fallback), pid(), cwd()
json	parse(text), stringify(v), pretty(v), and the value type Json with get, at, set, push, has, str_or, int_or ...
fs	read_bytes(p) / write_bytes(p, data) ([]u8, any bytes), exists, is_dir, mkdir (with the folders above), list (sorted names), remove_dir, data_dir(app) (a folder for the user's saves)
thread	spawn(addr(work), addr(data)), t.join(), mutex() with lock, unlock, close, cpus() (section 29)

min(a, b, ...), max(a, b, ...), abs(x) and clamp(x, lo, hi) work on any numbers without an import (a function of your own with the same name wins).

import json
import path

doc := try json.parse(read_file("config.json"))
name := doc.get("name").str_or("unnamed")        // a missing key is null, so chains never fail
doc.set("name", json.new_text(name + "!"))
write_file(path.join("out", "config.json"), json.pretty(doc))

26. Current limits

Not there yet:

• Interfaces.
• Unicode-aware text: .len, s[i] and upper() work on bytes / ASCII.
• Checks that stop two threads from changing the same array at once (use a mutex).
• Windows on ARM64, 32-bit systems, WebAssembly.

Warnings about big copies

A struct with 256 bytes or more of plain data (numbers, structs of numbers, C's [N]T) is copied byte by byte when it is a parameter (fn f(Body b)) and in for x in bodies. Finch says so, and still builds the program:

game.fch:27:11: warning: 'b' is a Body (264 bytes), copied on every call to weight; take ptr[Body] to share it instead (callers can still pass the variable as it is)
game.fch:45:5: warning: each Body (264 bytes) is copied into 'x'; for i in 0..bodies.len with bodies[i] works on it in place

Text, arrays and maps inside a struct don't count: passing the struct copies only their handles, not what they hold. b := a is not warned about: it says "copy" in the code. A method never copies self. Editors show the warnings in yellow.

See the roadmap in the README.

27. Tests: test blocks and finch test

Tests go next to the code they test:

fn damage(int hp, int hit) -> int {
    return max(hp - hit, 0)
}

test "damage never goes below zero" {
    assert(damage(5, 10) == 0)
    assert(damage(5, 2) == 3, "got \(damage(5, 2))")
}

finch test game.fch runs every test block of the file and of the modules it imports (not of the standard library), each on its own: a failed assert or any runtime error ends only that test, and the next one runs.

ok   damage never goes below zero
FAIL loading a level
     level.fch:31: runtime error: can't read the file "levels/1.txt"

1 passed, 1 failed

The exit code is 1 when a test failed, so CI can use it. finch run and finch build leave test blocks out. assert(cond) also works outside tests: it stops the program with assert failed when cond is false.

28. A project: finch.toml

A finch.toml next to the code says once what would otherwise go on every command line:

name = "game"                        # the program finch build makes (from the entry)
entry = "src/main.fch"               # used when finch run / build / test get no file
paths = ["src", "lib"]               # folders with Finch modules
include = ["vendor/SDL3/include"]    # folders with C headers (also for your .c / .cpp files)
links = ["SDL3", "native/glue.cpp"]  # libraries, and your own .c / .cpp / .o / .a files
libdirs = ["vendor/SDL3/lib"]        # folders with libraries
cflags = ["-DFAST"]                  # for your .c / .cpp files
ldflags = ["-Wl,-rpath,$ORIGIN"]     # for the linker
cpu = "native"                       # the same as --cpu native (section 31)

[target.windows]                     # added only when building for Windows
links = ["ws2_32"]
libdirs = ["vendor/SDL3/lib/x64"]

[target.linux-arm64]                 # system and CPU: windows, linux, macos, android, and -x86_64 / -arm64
libdirs = ["vendor/SDL3/lib/arm64"]

Folders are relative to finch.toml. Finch looks for it in the file's folder and the folders above, so finch run src/tools/editor.fch inside the project uses it too. Only this much of TOML is read: [sections], key = "text", key = ["a", "b"] (over several lines too), numbers, true/false and # comments.

29. Threads

import thread

struct Chunk {
    []float samples
    float peak
}

fn analyse(ptr arg) {               // a thread's function takes one ptr
    ptr[Chunk] c = arg
    for s in c.samples {
        c.peak = max(c.peak, abs(s))
    }
}

fn main() {
    []Chunk chunks = load_chunks()
    []thread.Thread running
    for i in 0..chunks.len {
        running.push(thread.spawn(addr(analyse), addr(chunks[i])) or {
            print(err)
            exit(1)
        })
    }
    for i in 0..running.len {
        running[i].join()            // wait for all of them
    }
}

What a thread gets is shared, not copied, so:

• it must live until join() (here chunks lives to the end of main);
• don't change the array the threads point into (no push) until they are joined;
• what more than one thread changes goes under a lock, or is a number changed with atomic_....

m := thread.mutex()
defer m.close()
m.lock()
log.push("done")                    // one thread at a time between lock and unlock
m.unlock()

atomic_add(addr(done), 1)           // done is an int shared by the threads
n := atomic_load(addr(done))

atomic_add, atomic_sub, atomic_swap give back the old value; atomic_cas(p, old, new) puts new only if old is there and says whether it did. thread.cpus() says how many threads the machine runs at once.

30. C++, Rust and Android

Finch talks to other languages through C, the way every language does.

C++: put what Finch calls behind a C header, with extern "C" on the C++ side:

// glue.h
#ifdef __cplusplus
extern "C" {
#endif
int physics_step(float dt);
#ifdef __cplusplus
}
#endif

and import "glue.h" with link "glue.cpp" (or links = ["glue.cpp"] in finch.toml). The .cpp file is built with the C++ compiler (clang++ or g++, or FINCH_CXX), which then also links, so the C++ library comes along. A C++ library that has a C API (Box2D 3, Jolt's JoltC, PhysX's C wrapper) is imported like any C library.

Rust: make a staticlib and export C functions:

// Cargo.toml: [lib] crate-type = ["staticlib"]
#[no_mangle]
pub extern "C" fn path_len(x: f32, y: f32) -> f32 { (x * x + y * y).sqrt() }

Write the header (float path_len(float x, float y);, or let cbindgen write it), then import "pathfind.h" and link "target/release/libpathfind.a". On Linux a Rust static library also needs links = ["dl", "pthread"].

Android: finch build game.fch --target android --shared makes libgame.so for 64-bit ARM Android (API 24 and up) with the NDK's clang, found through ANDROID_NDK_HOME (or FINCH_CC). Load it from an app, for example through SDL3's Android project (the library's SDL_main is an export fn). Thread-local data goes through the emulated TLS that older Android versions need.

---

31. Vectors (SIMD)

A processor can add or multiply several numbers with one instruction: 4 floats at once with SSE, 8 with AVX2, 16 with AVX-512, 4 with ARM's NEON. That is SIMD (single instruction, multiple data), and it is how image filters, audio, physics and neural networks get their speed. In Finch it is a type: f32x8 is 8 f32 side by side.

a := f32x4(1.0, 2.0, 3.0, 4.0)
b := f32x4(0.5)                  // 0.5 in every lane
print(a + b)                     // f32x4(1.5, 2.5, 3.5, 4.5)
print(a * 2.0)                   // a plain number counts for every lane: f32x4(2, 4, 6, 8)
print(a.sum(), a[2], a.len)      // 10 3 4

The types are a number type, x, and how many lanes: f32x4 f32x8 f32x16, f64x2 f64x4 f64x8, i8x16 i8x32 i8x64, i16x8 i16x16, i32x4 i32x8 i32x16, i64x2 i64x4, and the same with u (unsigned). 2 to 64 lanes, at most 512 bits in all. A vector is a plain value like an int: it goes into variables, struct fields, arrays, maps and function parameters, and print and str show it.

Making one:

f32x8(x)	x in every lane
f32x8(a, b, c, d, e, f, g, h)	one number per lane
f32x8(list, i)	list[i] … list[i+7] from a []f32 (or through a ptr[f32]); stops the program if they aren't all in the list
f32x8(v)	another 8-lane vector converted lane by lane: f32x8(ints), i32x8(floats) (cuts the fractions), i16x8(i32s)

Working with it:

+ - * /	lane by lane (/ on floats only: x86 and ARM can't divide whole numbers lane by lane)
& | ^ << >> ~	lane by lane, on whole-number lanes
-v	every lane negated
v[i], v[i] = x, v.len	one lane; the number of lanes
min(v, w), max(v, w), abs(v), clamp(v, lo, hi)	lane by lane; lo, hi and w can be plain numbers
v.sum(), v.min(), v.max()	all the lanes made into one number
v.dot(w)	(v * w).sum()
v.sqrt(), v.floor(), v.ceil(), v.round()	every lane (float lanes)
v.fma(b, c)	v * b + c with one rounding, always (the same on every processor)
v.muladd(b, c)	v * b + c the fastest way here: one instruction where the processor can (the last bit may differ between processors)
v.store(list, i)	writes the lanes to list[i] … (or through a ptr)

A real loop. The usual shape: as many whole vectors as fit, then the rest one by one.

fn dot([]f32 a, []f32 b) -> f32 {
    acc := f32x8(0.0)
    i := 0
    while i + 8 <= a.len {
        acc = f32x8(a, i).muladd(f32x8(b, i), acc)
        i += 8
    }
    total := acc.sum()
    while i < a.len {
        total += a[i] * b[i]
        i += 1
    }
    return total
}

examples/simd.fch times this against the plain loop.

Masks: comparing, choosing, the end of a list

Comparing vectors compares every lane, so the answer is a mask: one true/false a lane, of type boolx8 (for 8 lanes).

v := f32x8(-2.0, -1.0, 0.0, 1.0, 2.0, 3.0, -4.0, 5.0)
m := v > 0.0                      // boolx8(false, false, false, true, true, true, false, true)
relu := select(m, v, 0.0)         // v where the mask is true, 0 elsewhere
print(m.count(), m.any(), m.all())    // 4 true false
if (v == w).all() { ... }         // a condition needs one bool: all() or any()

v < w, <=, >, >=, ==, !=	a mask (a plain number on one side counts for every lane)
select(m, a, b)	lane by lane: a where m is true, b where false (either may be a plain number)
m.any(), m.all(), m.count()	is any lane true, are all, how many
m & n, m | n, m ^ n, !m	masks combined
m[i]	one lane, as a bool
i32x8(m), boolx8(v)	true is 1; a lane that isn't 0 is true

The end of a list. A list is rarely a whole number of vectors long. Two forms touch only the lanes that are inside it:

f32x8(list, i, fill)	list[i] … as far as the list goes; the lanes past its end are fill
v.store_part(list, i)	writes only the lanes that fit in the list

fn add_one([]f32 xs) {
    i := 0
    while i < xs.len {                          // no separate loop for the rest
        (f32x8(xs, i, 0.0) + 1.0).store_part(xs, i)
        i += 8
    }
}

Moving lanes

v.shuffle(3, 2, 1, 0)	the lanes with these numbers (written in the code), in this order; as many lanes as numbers
v.lo(), v.hi()	the lower and the upper half
concat(a, b)	a's lanes, then b's
table.lookup(idx)	for every lane of idx: table[idx % table.len]. A byte table (u8x16, i8x16) is one pshufb on x86, tbl on ARM

Unpacking 4-bit numbers (two to a byte, as quantized models store them) is shuffle, mask and lookup:

fn unpack4(u8x8 packed, i8x16 meaning) -> i8x16 {
    pairs := packed.shuffle(0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7)   // each byte twice
    odd := u8x16(0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1) == 1
    nibbles := select(odd, pairs >> 4, pairs & 15)                         // low nibble, then high
    return meaning.lookup(nibbles)                                         // 0..15 -> what it stands for
}

Int8 dot products: dot_add

acc.dot_add(a, b) is the step of a quantized model's matrix multiply. acc is an i32x8 of sums; a and b have four times as many bytes (u8x32 and i8x32; i8 × i8 and u8 × u8 work too). Each lane of acc gains the sum of four products, a[4k]*b[4k] + … + a[4k+3]*b[4k+3], exactly (no saturation), and the sums stay in the vector:

acc := i32x8(0)
i := 0
while i + 32 <= weights.len {
    acc = acc.dot_add(u8x32(activations, i), i8x32(weights, i))
    i += 32
}
total := acc.sum()                // once, at the end

It is one instruction where the processor has one: vpdpbusd with AVX-VNNI (Intel since Alder Lake, AMD Zen 5) or AVX-512 VNNI, usdot/sdot/udot on ARM with the dot-product features. Elsewhere it is a few instructions (pmaddwd and adds), with the same result. Which one is used depends on --cpu or the function's @cpu (below).

Choosing the instructions: --cpu, @cpu and cpu_has

By default a program runs on every processor of its system (on x86-64 that means SSE2, so an f32x8 is done as two halves). Three ways to use more:

--cpu, for the whole program. --cpu native (or cpu = "native" in finch.toml) lets LLVM use everything the processor that builds it has: AVX2 and FMA, AVX-512, VNNI, or NEON's newer parts on ARM. The program then needs a processor like that one. To pick a level instead: --cpu x86-64-v3 (AVX2, most PCs since 2015), --cpu x86-64-v4 (AVX-512), --cpu alderlake, --cpu apple-m1, --cpu neoverse-v1.

@cpu, for one function, and cpu_has to choose at run time. One program can carry an AVX-512 version, an AVX2 version and a plain one, and pick the best the computer it runs on has:

@cpu("avx512f,avx512bw,avx512vl,avx512vnni")
fn matmul_avx512([]u8 a, []i8 b, []i32 out) { ... }      // may use AVX-512 inside

@cpu("x86-64-v3")
fn matmul_avx2([]u8 a, []i8 b, []i32 out) { ... }        // a level works too

fn matmul([]u8 a, []i8 b, []i32 out) {
    if cpu_has("avx512vnni") && cpu_has("avx512vl") {
        matmul_avx512(a, b, out)
    } else if cpu_has("avx2") {
        matmul_avx2(a, b, out)
    } else {
        matmul_plain(a, b, out)
    }
}

• The features are x86's sse3 ssse3 sse4.1 sse4.2 popcnt avx avx2 fma f16c bmi1 bmi2 avx512f avx512bw avx512dq avx512vl avx512vnni avx512bf16 avx512fp16 avxvnni, the levels x86-64-v2/v3/v4, and ARM's neon fp16 dotprod i8mm bf16 sve sve2.
• Names of the other architecture are left out when building, so the x86 and ARM versions sit side by side in one file (and cpu_has says false for them).
• Call a @cpu function only after cpu_has said yes: on a processor without the feature it stops with Illegal instruction.
• A vector wider than 16 bytes (f32x8, i32x16 …) can't be passed between functions with different @cpu: the two sides would expect it in different registers. Pass the list (or a ptr) instead; Finch says so if you try.

Lanes wider than the processor's registers are split by LLVM, and the same code builds for x86-64 and ARM64 alike. v.sum() on float lanes adds them in whatever order is fastest, so the last digits can differ from adding them one by one.

On NixOS, Nix's clang wrapper removes -march=native inside nix-shell. Finch tells the wrapper to keep it, so --cpu native works there too; if it ever has no effect, Finch warns.