mirror of
https://github.com/Nexoniarz/Finch.git
synced 2026-11-03 08:54:25 +00:00
Install, CI, seeds and docs for the compiler written in Finch
bootstrap/install.sh and a share/finch lookup for the runtime and std; an ARM64 Linux seed; bootstrap/README.md; CI builds from the seed on x64 and ARM64 and runs every test on Windows (Wine) and ARM64 (qemu); README, install and layout sections of the guides (EN+PL) no longer talk about CMake; editors know enum, match and export. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015f73FesGZGYPkmDvUcj6QX
This commit is contained in:
Nexoniarz
parent
636eaefe59
commit
81df9f8c3e
15 changed files with 125197 additions and 30152 deletions
|
|
@ -63,8 +63,7 @@ these lines one by one, pressing **Enter** after each:
|
|||
git clone https://github.com/Nexoniarz/Finch.git
|
||||
cd Finch
|
||||
nix-shell
|
||||
cmake -S . -B build -G Ninja
|
||||
ninja -C build
|
||||
bootstrap/build.sh
|
||||
```
|
||||
|
||||
If the last line finishes without the word `error`, Finch is ready.
|
||||
|
|
@ -77,7 +76,7 @@ To check it works, type:
|
|||
./build/finch version
|
||||
```
|
||||
|
||||
You should see something like `finch 2.4.0`.
|
||||
You should see something like `Finch 2.4.0`.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -63,78 +63,40 @@ messages that tell you how to fix the problem.
|
|||
|
||||
## 2. Installing
|
||||
|
||||
Finch runs on **Linux** (x86-64 and ARM64), **macOS** (Apple Silicon and Intel) and **Windows** (x86-64),
|
||||
and is built with **LLVM 21**. Each [release](https://github.com/Nexoniarz/Finch/releases) has a ready
|
||||
`finch` for Windows, Linux x86-64, Linux ARM64 and macOS ARM64.
|
||||
The Finch compiler is written in Finch (see the [engineers' guide](for-engineers.md)). It runs on **Linux**
|
||||
(x86-64 and ARM64) and builds programs for **Linux, Windows and macOS**. It needs **clang 21** and **libclang**
|
||||
(LLVM 21) to read C headers and to compile its output.
|
||||
|
||||
### Windows
|
||||
The compiler does not run on macOS or Windows yet; it needs a seed made with that system's headers
|
||||
([bootstrap/README.md](../../bootstrap/README.md) says why). Until then, build your Windows and macOS programs from Linux
|
||||
with `--target` (below), or use the older C++ compiler from the `before-bootstrap` branch.
|
||||
|
||||
1. Download **`finch-windows-x64.zip`** from the [releases](https://github.com/Nexoniarz/Finch/releases)
|
||||
and unpack it, for example to `C:\finch`. It contains `finch.exe` and `libclang.dll`.
|
||||
2. Install **LLVM 21** (`LLVM-21.x.x-win64.exe` from the
|
||||
[LLVM releases](https://github.com/llvm/llvm-project/releases)) and tick *Add LLVM to the system PATH*.
|
||||
Finch uses its `clang` to link programs.
|
||||
3. Install **Visual Studio Build Tools 2022** with *Desktop development with C++*: it provides the Windows
|
||||
libraries every program is linked with.
|
||||
4. Add `C:\finch` to your PATH, open a new terminal, and run `finch version`.
|
||||
### Option A: a ready build (Linux)
|
||||
|
||||
Programs are normal `.exe` files. To build from source on Windows instead, follow `.github/workflows/ci.yml`
|
||||
(Visual Studio 2022 + the `clang+llvm-21.x-x86_64-pc-windows-msvc` package from LLVM's releases).
|
||||
Download `finch-linux-x64.tar.gz` or `finch-linux-arm64.tar.gz` from the
|
||||
[releases](https://github.com/Nexoniarz/Finch/releases) and unpack it. Keep `runtime/` and `std/` next to the `finch` file
|
||||
(or install it, below). You also need `clang` 21 and its libclang library:
|
||||
|
||||
### macOS
|
||||
| Distribution | Packages |
|
||||
|---|---|
|
||||
| Debian / Ubuntu | `clang-21 libclang-21-dev` from [apt.llvm.org](https://apt.llvm.org), `pkg-config` |
|
||||
| Fedora | `clang clang-devel pkgconf` |
|
||||
| Arch | `clang pkgconf` |
|
||||
| Nix | `nix-shell` in the repository gives all of it |
|
||||
|
||||
```sh
|
||||
brew install llvm@21 # Finch's LLVM; programs are linked with Apple's clang
|
||||
```
|
||||
|
||||
Then either unpack **`finch-macos-arm64.tar.gz`** from the releases (it uses Homebrew's `llvm@21`),
|
||||
or build it yourself (Xcode command line tools: `xcode-select --install`):
|
||||
|
||||
```sh
|
||||
git clone https://github.com/Nexoniarz/Finch.git && cd Finch
|
||||
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_DIR="$(brew --prefix llvm@21)/lib/cmake/llvm"
|
||||
ninja -C build
|
||||
./build/finch version
|
||||
```
|
||||
|
||||
Apple frameworks link with `link "Cocoa.framework"` (`-framework Cocoa`), and their headers import as usual:
|
||||
`import "OpenGL/gl.h"`.
|
||||
|
||||
### Linux
|
||||
|
||||
The ready `finch-linux-x64.tar.gz` / `finch-linux-arm64.tar.gz` need LLVM 21's libraries
|
||||
(Debian/Ubuntu: `libllvm21 libclang1-21` from [apt.llvm.org](https://apt.llvm.org)) and a C compiler (`cc`).
|
||||
Building it yourself works the same on x86-64 and ARM64 (Raspberry Pi 4/5, Graviton, …).
|
||||
Other LLVM versions will likely fail to compile, because LLVM's C++ API changes between releases.
|
||||
|
||||
### Option A: Nix (recommended, nothing to install by hand)
|
||||
### Option B: build it yourself
|
||||
|
||||
```sh
|
||||
git clone https://github.com/Nexoniarz/Finch.git
|
||||
cd Finch
|
||||
nix-shell # downloads LLVM, libclang, clang, cmake, ninja, pkg-config
|
||||
cmake -S . -B build -G Ninja
|
||||
ninja -C build
|
||||
./build/finch version # finch 2.4.0 (LLVM 21.x)
|
||||
nix-shell # clang, libclang, pkg-config (or install them with your distribution)
|
||||
bootstrap/build.sh # build/finch
|
||||
./build/finch version
|
||||
```
|
||||
|
||||
### Option B: your distribution's packages
|
||||
|
||||
You need: a C/C++ compiler, CMake ≥ 3.20, Ninja (or Make), LLVM 21 development files,
|
||||
libclang 21 development files, and optionally `pkg-config`.
|
||||
|
||||
| Distribution | Packages (names can differ slightly by version) |
|
||||
|---|---|
|
||||
| Debian / Ubuntu | `build-essential cmake ninja-build pkg-config llvm-21-dev libclang-21-dev` |
|
||||
| Fedora | `gcc-c++ cmake ninja-build pkgconf llvm-devel clang-devel` |
|
||||
| Arch | `base-devel cmake ninja pkgconf llvm clang` |
|
||||
|
||||
These have not been tested; if CMake cannot find LLVM, point it there:
|
||||
|
||||
```sh
|
||||
cmake -S . -B build -G Ninja -DLLVM_DIR=/usr/lib/llvm-21/lib/cmake/llvm
|
||||
ninja -C build
|
||||
```
|
||||
`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`.
|
||||
|
||||
### Building for another system
|
||||
|
||||
|
|
@ -160,12 +122,13 @@ On Nix the compilers are `pkgsCross.mingwW64.buildPackages.gcc` and
|
|||
### Putting `finch` on your PATH (optional)
|
||||
|
||||
```sh
|
||||
sudo cp build/finch /usr/local/bin/
|
||||
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 a C compiler (`cc`). It is used to link programs, and once to build
|
||||
Finch's small runtime library, which is kept in `~/.cache/finch`. Set `CC` to use a different one.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -938,28 +901,27 @@ Visual Studio debugger and WinDbg read.
|
|||
|
||||
```
|
||||
Finch/
|
||||
├── src/ the compiler (C++)
|
||||
├── runtime/ finch_rt.c: the small runtime (text, arrays, input, files)
|
||||
├── boot/ the Finch compiler written in Finch (see the engineers' guide)
|
||||
├── 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
|
||||
├── 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, c_import, window, opengl, vulkan, raylib, llvm
|
||||
├── tests/
|
||||
│ ├── run/ programs + the exact output they must print (.out), input (.in)
|
||||
│ ├── fail/ programs that must fail, with the expected error in line 1
|
||||
│ ├── 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
|
||||
│ ├── run.sh the test runner (MEMCHECK=1 also checks memory with valgrind)
|
||||
│ └── boot.sh builds the self-hosted compiler with itself and compares
|
||||
│ ├── 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
|
||||
└── CMakeLists.txt
|
||||
└── shell.nix the Nix development environment
|
||||
```
|
||||
|
||||
```sh
|
||||
tests/run.sh # → 74 passed, 0 failed
|
||||
tests/run.sh # programs, refusals, -g builds, a shared library, the language server
|
||||
MEMCHECK=1 tests/run.sh # the same under valgrind: no leaks, no bad memory access
|
||||
tests/boot.sh # the self-hosting check (needs clang)
|
||||
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
|
||||
python3 tests/lsp_test.py # the language server
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -63,8 +63,7 @@ i wpisz te linijki po kolei, naciskając **Enter** po każdej:
|
|||
git clone https://github.com/Nexoniarz/Finch.git
|
||||
cd Finch
|
||||
nix-shell
|
||||
cmake -S . -B build -G Ninja
|
||||
ninja -C build
|
||||
bootstrap/build.sh
|
||||
```
|
||||
|
||||
Jeśli ostatnia linijka skończy się bez słowa `error`, Finch jest gotowy.
|
||||
|
|
|
|||
|
|
@ -63,77 +63,40 @@ i komunikaty błędów, które mówią, jak problem naprawić.
|
|||
|
||||
## 2. Instalacja
|
||||
|
||||
Finch działa na **Linuksie** (x86-64 i ARM64), **macOS** (Apple Silicon i Intel) i **Windowsie** (x86-64),
|
||||
i jest budowany z **LLVM 21**. Każde [wydanie](https://github.com/Nexoniarz/Finch/releases) ma gotowy
|
||||
`finch` dla Windowsa, Linuksa x86-64, Linuksa ARM64 i macOS ARM64.
|
||||
Kompilator Fincha jest napisany w Finchu (zobacz [przewodnik dla inżynierów](dla-inzynierow.md)). Działa na **Linuksie**
|
||||
(x86-64 i ARM64) i buduje programy dla **Linuksa, Windowsa i macOS**. Potrzebuje **clanga 21** i **libclang** (LLVM 21),
|
||||
żeby czytać nagłówki C i kompilować to, co wygeneruje.
|
||||
|
||||
### Windows
|
||||
Kompilator nie działa jeszcze na macOS ani Windowsie: potrzebuje ziarna zrobionego z nagłówkami tego systemu
|
||||
([bootstrap/README.md](../../bootstrap/README.md) tłumaczy dlaczego). Do tego czasu programy na Windows i macOS buduj z Linuksa
|
||||
przez `--target` (niżej) albo użyj starszego kompilatora w C++ z gałęzi `before-bootstrap`.
|
||||
|
||||
1. Pobierz **`finch-windows-x64.zip`** z [wydań](https://github.com/Nexoniarz/Finch/releases) i rozpakuj,
|
||||
np. do `C:\finch`. W środku są `finch.exe` i `libclang.dll`.
|
||||
2. Zainstaluj **LLVM 21** (`LLVM-21.x.x-win64.exe` z [wydań LLVM](https://github.com/llvm/llvm-project/releases))
|
||||
i zaznacz *Add LLVM to the system PATH*. Finch używa jego `clang` do linkowania programów.
|
||||
3. Zainstaluj **Visual Studio Build Tools 2022** z pakietem *Desktop development with C++*: dostarcza biblioteki
|
||||
Windowsa, z którymi linkowany jest każdy program.
|
||||
4. Dodaj `C:\finch` do PATH, otwórz nowy terminal i wpisz `finch version`.
|
||||
### Opcja A: gotowa wersja (Linux)
|
||||
|
||||
Programy to zwykłe pliki `.exe`. Żeby zbudować Fincha ze źródeł na Windowsie, idź za `.github/workflows/ci.yml`
|
||||
(Visual Studio 2022 + pakiet `clang+llvm-21.x-x86_64-pc-windows-msvc` z wydań LLVM).
|
||||
Pobierz `finch-linux-x64.tar.gz` albo `finch-linux-arm64.tar.gz` z [wydań](https://github.com/Nexoniarz/Finch/releases)
|
||||
i rozpakuj. Zostaw `runtime/` i `std/` obok pliku `finch` (albo zainstaluj, niżej). Potrzebny jest też `clang` 21
|
||||
z biblioteką libclang:
|
||||
|
||||
### macOS
|
||||
| Dystrybucja | Pakiety |
|
||||
|---|---|
|
||||
| Debian / Ubuntu | `clang-21 libclang-21-dev` z [apt.llvm.org](https://apt.llvm.org), `pkg-config` |
|
||||
| Fedora | `clang clang-devel pkgconf` |
|
||||
| Arch | `clang pkgconf` |
|
||||
| Nix | `nix-shell` w repozytorium daje wszystko |
|
||||
|
||||
```sh
|
||||
brew install llvm@21 # LLVM dla Fincha; programy linkuje clang od Apple
|
||||
```
|
||||
|
||||
Potem rozpakuj **`finch-macos-arm64.tar.gz`** z wydań (korzysta z `llvm@21` z Homebrew)
|
||||
albo zbuduj go sam (narzędzia wiersza poleceń Xcode: `xcode-select --install`):
|
||||
|
||||
```sh
|
||||
git clone https://github.com/Nexoniarz/Finch.git && cd Finch
|
||||
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_DIR="$(brew --prefix llvm@21)/lib/cmake/llvm"
|
||||
ninja -C build
|
||||
./build/finch version
|
||||
```
|
||||
|
||||
Frameworki Apple linkuje się przez `link "Cocoa.framework"` (`-framework Cocoa`), a ich nagłówki importuje
|
||||
się normalnie: `import "OpenGL/gl.h"`.
|
||||
|
||||
### Linux
|
||||
|
||||
Gotowe `finch-linux-x64.tar.gz` / `finch-linux-arm64.tar.gz` potrzebują bibliotek LLVM 21
|
||||
(Debian/Ubuntu: `libllvm21 libclang1-21` z [apt.llvm.org](https://apt.llvm.org)) i kompilatora C (`cc`).
|
||||
Samodzielne budowanie wygląda tak samo na x86-64 i ARM64 (Raspberry Pi 4/5, Graviton, …).
|
||||
Z innymi wersjami LLVM Finch prawdopodobnie się nie skompiluje, bo API C++ LLVM zmienia się między wydaniami.
|
||||
|
||||
### Opcja A: Nix (zalecana, nic nie instalujesz ręcznie)
|
||||
### Opcja B: zbuduj sam
|
||||
|
||||
```sh
|
||||
git clone https://github.com/Nexoniarz/Finch.git
|
||||
cd Finch
|
||||
nix-shell # pobiera LLVM, libclang, clang, cmake, ninja, pkg-config
|
||||
cmake -S . -B build -G Ninja
|
||||
ninja -C build
|
||||
./build/finch version # finch 2.4.0 (LLVM 21.x)
|
||||
nix-shell # clang, libclang, pkg-config (albo zainstaluj z dystrybucji)
|
||||
bootstrap/build.sh # build/finch
|
||||
./build/finch version
|
||||
```
|
||||
|
||||
### Opcja B: pakiety z twojej dystrybucji
|
||||
|
||||
Potrzebujesz: kompilatora C/C++, CMake ≥ 3.20, Ninja (albo Make), plików deweloperskich LLVM 21
|
||||
i libclang 21, a opcjonalnie `pkg-config`.
|
||||
|
||||
| Dystrybucja | Pakiety (nazwy mogą się nieco różnić zależnie od wersji) |
|
||||
|---|---|
|
||||
| Debian / Ubuntu | `build-essential cmake ninja-build pkg-config llvm-21-dev libclang-21-dev` |
|
||||
| Fedora | `gcc-c++ cmake ninja-build pkgconf llvm-devel clang-devel` |
|
||||
| Arch | `base-devel cmake ninja pkgconf llvm clang` |
|
||||
|
||||
Ta opcja nie była testowana. Jeśli CMake nie znajduje LLVM, wskaż mu katalog:
|
||||
|
||||
```sh
|
||||
cmake -S . -B build -G Ninja -DLLVM_DIR=/usr/lib/llvm-21/lib/cmake/llvm
|
||||
ninja -C build
|
||||
```
|
||||
`bootstrap/build.sh` kompiluje ziarno (`bootstrap/<system>.ll`, własny LLVM IR kompilatora) do pierwszego kompilatora,
|
||||
buduje nim `src/`, buduje `src/` jeszcze raz wynikiem i sprawdza, że oba są identyczne. Jeśli libclang nie leży tam, gdzie
|
||||
szuka linker: `FINCH_LIBCLANG="-L/usr/lib/llvm-21/lib -lclang-21" bootstrap/build.sh`.
|
||||
|
||||
### Budowanie na inny system
|
||||
|
||||
|
|
@ -159,13 +122,14 @@ Na Niksie te kompilatory to `pkgsCross.mingwW64.buildPackages.gcc` i
|
|||
### Dodanie `finch` do PATH (opcjonalnie)
|
||||
|
||||
```sh
|
||||
sudo cp build/finch /usr/local/bin/
|
||||
sudo bootstrap/install.sh # /usr/local/bin/finch oraz /usr/local/share/finch/{runtime,std}
|
||||
bootstrap/install.sh ~/.local # albo do własnego katalogu
|
||||
finch version
|
||||
```
|
||||
|
||||
Podczas pracy Finch potrzebuje kompilatora C (`cc`). Używa go do linkowania programów i jednorazowo
|
||||
do zbudowania swojej małej biblioteki uruchomieniowej, którą trzyma w `~/.cache/finch`.
|
||||
Inny kompilator wskażesz zmienną `CC`.
|
||||
Podczas działania Finch potrzebuje `clanga` (kompiluje IR każdego programu i go linkuje). Mała biblioteka uruchomieniowa
|
||||
budowana jest raz i trzymana w `~/.cache/finch`. `FINCH_CC` wskazuje inny kompilator do linkowania; `FINCH_PATH` dodaje
|
||||
katalogi, w których szukać modułów.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -941,28 +905,27 @@ CodeView, który czyta debugger Visual Studio i WinDbg.
|
|||
|
||||
```
|
||||
Finch/
|
||||
├── src/ kompilator (C++)
|
||||
├── runtime/ finch_rt.c: mała biblioteka uruchomieniowa (teksty, tablice, wejście, pliki)
|
||||
├── boot/ kompilator Fincha napisany w Finchu (zobacz przewodnik dla inżynierów)
|
||||
├── src/ kompilator, w Finchu (lekser, parser, gen: LLVM IR jako tekst, cimport: libclang, lsp, main ...)
|
||||
├── std/ biblioteka standardowa, w Finchu: json, path, time, proc
|
||||
├── runtime/ finch_rt.c: mała biblioteka uruchomieniowa (teksty, tablice, mapy, wejście, pliki)
|
||||
├── bootstrap/ build.sh, install.sh i ziarna (własny IR kompilatora, po jednym na system)
|
||||
├── examples/ hello, tour, types, structs, todo, guess, c_import, window, opengl, vulkan, raylib, llvm
|
||||
├── tests/
|
||||
│ ├── run/ programy + dokładny wynik (.out) i wejście (.in)
|
||||
│ ├── fail/ programy, które muszą się nie udać, z oczekiwanym błędem w 1. linijce
|
||||
│ ├── run/ new/ programy + dokładny wynik (.out) i wejście (.in)
|
||||
│ ├── fail/ new/fail/ programy, które muszą się nie udać, z oczekiwanym błędem w 1. linijce
|
||||
│ ├── run.sh uruchamia testy (MEMCHECK=1 sprawdza też pamięć valgrindem)
|
||||
│ └── boot.sh buduje kompilator samohostujący nim samym i porównuje
|
||||
│ ├── cross.sh każdy test zbudowany na Windows / ARM64 i uruchomiony w Wine / QEMU
|
||||
│ └── lsp_test.py serwer języka, obsługiwany jak przez edytor
|
||||
├── editors/ rozszerzenie VS Code (vscode/), podświetlanie i konfiguracja LSP dla Kate (kate/)
|
||||
├── docs/ ta dokumentacja (en, pl), łącznie ze ściągą
|
||||
├── shell.nix środowisko deweloperskie Nix
|
||||
└── CMakeLists.txt
|
||||
└── shell.nix środowisko deweloperskie Nix
|
||||
```
|
||||
|
||||
```sh
|
||||
tests/run.sh # → 74 passed, 0 failed
|
||||
tests/run.sh # programy, odmowy, buildy z -g, biblioteka współdzielona, serwer języka
|
||||
MEMCHECK=1 tests/run.sh # to samo pod valgrindem: bez wycieków i złych dostępów do pamięci
|
||||
tests/boot.sh # sprawdzenie samohostowania (wymaga clanga)
|
||||
tests/cross.sh windows # każdy test zbudowany na Windowsa i uruchomiony w Wine
|
||||
tests/cross.sh arm64 # każdy test zbudowany na Linuksa ARM64 i uruchomiony w QEMU
|
||||
python3 tests/lsp_test.py # serwer języka
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Reference in a new issue