docs: README yeniden yazıldı — GitHub vitrin formatı, mimari referans docs/architecture.md'ye taşındı
This commit is contained in:
saqut
parent
3267b56903
commit
d534410874
|
|
@ -0,0 +1,225 @@
|
|||
# saQut — Mimari Referans
|
||||
|
||||
**Programlanabilir, incelenebilir bir derleyici — bir "alet çantası" (toolbox).**
|
||||
|
||||
saQut'un asıl varlık sebebi dilin kendisinden çok, **derleme sürecinin her
|
||||
aşamasının dışarıdan görülebilir ve müdahale edilebilir olmasıdır.** Token'lar,
|
||||
AST, sembol tablosu, optimizasyonun öncesi/sonrası ve IR — hepsi ayrı ayrı
|
||||
incelenebilir. Dil, bu aletin üzerinde çalıştığı küçük, prosedürel bir
|
||||
örnektir; vitrin değil, alet.
|
||||
|
||||
Uygulama dili **C++**'tır (header-only eğilimli, bkz. `docs/fikirler.md` ADR-003).
|
||||
|
||||
---
|
||||
|
||||
## Şu an ne çalışıyor, ne çalışmıyor
|
||||
|
||||
Belgeler **planlanan** ile **yapılan**ı net ayırır. Bugünkü gerçek durum:
|
||||
|
||||
### ✅ Çalışıyor (built)
|
||||
- **Lexer** — karakter seviyesi tarama, konum takibi.
|
||||
- **Tokenizer** — token üretimi (6 token tipi), yorum satırı desteği.
|
||||
- **Pratt parser** — ifade (Pratt) + statement (recursive descent) ayrıştırma.
|
||||
- **AST** — fonksiyon, blok, değişken tanımı, if/for/while/do-while/return,
|
||||
ifade node'ları.
|
||||
- **AST'nin JSON serileştirmesi** — `saqut ast` ile incelenebilir.
|
||||
- **CLI komut yapısı** — `tokens`, `ast`, `symbols`, `run` iskeletleri.
|
||||
- **Kaynak konum takibi** (SourceLocation) — offset → (satır, sütun).
|
||||
- **Minimal IR deneyi** — basit aritmetiği düşürür (örn. `1 + (7/3)` → kısa
|
||||
doğrusal komut dizisi). Henüz tam bir backend değil, bir deneydir.
|
||||
|
||||
### 🚧 Henüz yok (planned)
|
||||
- Sembol tablosu
|
||||
- Semantik analiz
|
||||
- Tip sistemi
|
||||
- Diagnostic (hata raporlama) motoru
|
||||
- Optimizasyon
|
||||
- IR + bytecode VM ile çalıştırma
|
||||
|
||||
> `feature/frontend-analysis` dalı şu an yalnızca bu yapılmamış işin **tasarım
|
||||
> belgelerini** içerir, kodunu değil.
|
||||
|
||||
**Birinci kilometre taşı ("bitti" tanımı):** derleyici **fibonacci'yi**
|
||||
(recursive + iterative) ve basit matematik/döngü programlarını **derleyip
|
||||
çalıştırabilmeli.** Referans program: `examples/fibonacci.sqt`.
|
||||
|
||||
---
|
||||
|
||||
## Dil kimliği (kilitli)
|
||||
|
||||
Prosedürel, **C ailesi sözdizimi**, **value semantics**. İlk ifade doğrudan bir
|
||||
işlem/tanım olabilir; zorunlu class/`main` boilerplate'i yoktur (Java'nın aksine).
|
||||
|
||||
| Özellik | Karar |
|
||||
|---|---|
|
||||
| Class / OOP / kalıtım | **Yok** |
|
||||
| Closure | **Yok** |
|
||||
| Generic | **Yok** |
|
||||
| Kullanıcıya açık pointer (`*` / `&`) | **Yok** — derleyici/runtime içeride pointer'ı serbestçe kullanır |
|
||||
| `struct` | **Var** |
|
||||
| Tipli fonksiyonlar (dönüş + parametre) | **Var** |
|
||||
| Array (`int[]`) | **Var** |
|
||||
| `interface` | **Ertelendi** (v0 değil — gerekçe ADR-018) |
|
||||
| `auto` / tip çıkarımı | **Yok** |
|
||||
| Gizli int↔float dönüşümü | **Yok** (tek istisna: sabit folding) |
|
||||
|
||||
Gerekçe: prosedürel tasarım semantik karmaşıklığı en aza indirir ve hedeflerle
|
||||
(fibonacci, matematik, sıralama, ayrıştırma) örtüşür. Standart C'de `class`
|
||||
yoktur (o C++'tır); C, struct + fonksiyonun yettiğini kanıtlar.
|
||||
|
||||
---
|
||||
|
||||
## Çalıştırma modeli (kilitli): IR + bytecode VM
|
||||
|
||||
saQut, kendi **IR**'sine derler ve bu IR'yi bir **yorumlayıcı döngü (bytecode
|
||||
VM)** ile çalıştırır.
|
||||
|
||||
- **Tree-walker DEĞİL** (çok yavaş).
|
||||
- **Gerçek makine-kodu JIT DEĞİL.** Makine kodu üretimi (register allocation,
|
||||
ABI/çağırma sözleşmeleri, çalıştırılabilir `mmap` bellek) **kapsam dışıdır** —
|
||||
tek faydası ham hızdır ve hız burada öncelik değildir. Öncelikler
|
||||
**determinizm** ve **incelenebilirliktir**; bytecode VM ikisini de doğrudan
|
||||
sağlar.
|
||||
- **Bellek bu modelde kolaydır:** host (C++) heap'i kullanılır; v0 için özel
|
||||
runtime allocator gerekmez.
|
||||
- **C'ye transpile, geçerli bir İKİNCİ backend olarak ileride kalır** (frontend
|
||||
backend-bağımsızdır — middle-end ayrımının amacı budur, ADR-006). İleride
|
||||
makine kodu istenirse elle code generator yazmak yerine **libgccjit / LLVM'e
|
||||
bağlanılır** — ama bu çok uzak gelecektir.
|
||||
|
||||
> Eski belge/konuşmalarda geçen "JIT" terimi yanlış yönlendiricidir; doğru
|
||||
> çerçeve **IR + VM**'dir.
|
||||
|
||||
---
|
||||
|
||||
## Tasarım felsefesi — neden saQut farklı?
|
||||
|
||||
saQut "daha iyi bir dil" iddiasında değil. Farkı, **derleyiciyi bir platform**
|
||||
olarak ele almasında. İki taahhüt üstüne kuruludur:
|
||||
|
||||
**1. Cam (gör + sorgula + içine müdahale et).** Her aşama — token, AST, sembol
|
||||
tablosu, tip, IR — kararlı, makine-okur ve **çift yönlü** bir arayüzden
|
||||
erişilebilir olmalıdır. Sadece "dök ve göster" değil: kendi AST'ini verip tip
|
||||
kontrolü isteyebilmeli, IR verip çalıştırabilmelisin. **Turnusol testi:** bir
|
||||
yabancı, yalnızca `saqut ast` + `saqut symbols` çıktısından, bizden habersiz bir
|
||||
LSP yazabiliyor mu? Cevap "evet" ise platform gerçektir.
|
||||
|
||||
**2. Kafes (deterministik + yetenek-güvenli çalıştırma).** Pointer yok, value
|
||||
semantics, scope-tabanlı bellek ve **tek dış-dünya kapısı olan FFI seam**
|
||||
(ADR-016) sayesinde saQut kodu, host'un açıkça izin verdiği fonksiyonlar dışında
|
||||
dünyaya dokunamaz. Bytecode VM deterministiktir (ADR-015): aynı girdi → aynı
|
||||
çıktı → aynı çalışma. "Sadelik" diye tasarlanan bu kararlar aslında bir
|
||||
**yetenek-güvenliği (capability sandbox)** kurar — güvenilmeyen veya
|
||||
AI-üretimi kodu güvenle çalıştırmak için biçilmiş kaftan.
|
||||
|
||||
**Bu ikisinin ödülü — kayıt & tekrar (record-replay).** 🚧 *(vizyon, v0 değil;
|
||||
bkz. issue #94.)* Belirsizliğin tek kaynağı (kullanıcı girdisi, zaman, IO,
|
||||
GC/thread kararları) FFI kapısından geçtiği için, mükemmel tekrar oynatma için
|
||||
**her değişkeni her adımda kaydetmek gerekmez** — yalnızca kapıdan geçen değerler
|
||||
kaydedilir, gerisi VM deterministik olarak yeniden çalıştırılarak üretilir. Boyut
|
||||
gigabayttan kilobayta düşer. Replay modunda FFI çağrıları gerçekten çalışmaz,
|
||||
kaydedilmiş değeri döndürür (dosyayı tekrar silmez, sunucuya tekrar istek atmaz).
|
||||
Böylece "benim makinemde çalışıyor, müşteride patlıyor" sorunu: müşteri bir dump
|
||||
yollar, sen çöküşü adım adım, aynı verilerle geri sararsın.
|
||||
|
||||
> Log, önceden sormayı akıl ettiğin sorulara cevap verir; **tekrar-oynatma,
|
||||
> çöküşten *sonra* aklına gelen sorulara.** Zaman-yolculuğu hata ayıklama ayrı
|
||||
> bir altyapı değildir — cam sorgularına bir **zaman koordinatı** eklemektir.
|
||||
|
||||
⚠️ Bu ödülün bedeli v0'da ödenir: **determinizm kutsaldır ve her belirsizlik
|
||||
kaynağı kayıt-altına-alınabilir tek kapıdan geçmelidir.** Sonradan eklenemez;
|
||||
baştan korunur.
|
||||
|
||||
---
|
||||
|
||||
## Mimari hatlar
|
||||
|
||||
```
|
||||
KAYNAK KOD
|
||||
│ lexer
|
||||
▼
|
||||
TOKEN'LAR ────────────── saqut tokens
|
||||
│ parser (Pratt + recursive descent)
|
||||
▼
|
||||
AST ──────────────────── saqut ast
|
||||
│ sembol toplama (iki geçişli) ┐
|
||||
▼ │
|
||||
SEMBOL TABLOSU ───────── saqut symbols │ FRONTEND
|
||||
│ semantik analiz (annotation) │ (yapı + anlam)
|
||||
▼ │
|
||||
ANNOTATE EDİLMİŞ AST ─── saqut ast ┘
|
||||
│ optimizasyon (opsiyonel, klon üstünde) ── MIDDLE-END
|
||||
▼
|
||||
IR ───────────────────── (planlanan) ┐
|
||||
│ bytecode VM / yorumlayıcı döngü │ BACKEND
|
||||
▼ │ (çalıştırma + FFI seam)
|
||||
ÇALIŞTIRMA / ÇIKTI ───── saqut run ┘
|
||||
```
|
||||
|
||||
- **Frontend** yapıyı ve anlamı modeller (tip, scope, dataflow).
|
||||
- **"Hangi çekirdek, hangi cihaz, ne zaman, hangi çıktı formatı"** runtime/backend
|
||||
meselesidir — frontend'e yüklenmez.
|
||||
|
||||
---
|
||||
|
||||
## CLI (mevcut + planlanan)
|
||||
|
||||
```
|
||||
# --- çalışıyor ---
|
||||
saqut tokens file:kaynak.sqt # token listesi
|
||||
saqut ast file:kaynak.sqt # AST (JSON)
|
||||
saqut symbols file:kaynak.sqt # sembol tablosu (iskelet)
|
||||
|
||||
# --- planlanan ---
|
||||
saqut run file:kaynak.sqt # IR üret + bytecode VM ile çalıştır
|
||||
saqut ast file:kaynak.sqt --optimized # klon, optimize edilmiş AST (öncesi/sonrası)
|
||||
saqut transpile file:kaynak.sqt -o prog.c # ikinci backend (ileride)
|
||||
```
|
||||
|
||||
Tasarım gereği her aşamanın çıktısı erken bir noktada dosyalanabilir/loglanabilir
|
||||
(programlanabilir derleyici). Token, ham AST, optimize AST ve IR ayrı ayrı
|
||||
kaydedilebilir.
|
||||
|
||||
---
|
||||
|
||||
## Batteries / stdlib — kuzey yıldızı, ertelendi
|
||||
|
||||
Gerçek bir genel sürüm pil ile gelmeli (sıralama, sıkıştırma, kripto,
|
||||
JSON/XML/HTML ayrıştırma). Ama bu **bugünün işi ve v0.1 değildir.**
|
||||
|
||||
Mimari çerçeve (monolit korkusunu önler): derleyici pilleri çekirdeğine
|
||||
gömmez. Bunun yerine **küçük bir gerçek builtin kümesi** (`print`, temel
|
||||
zorunlular) + **gerisi kütüphane/FFI** ile gelir. "Batteries" sorunu aslında
|
||||
bir **sınır (FFI/link seam) sorunudur**, "zlib'i yeniden yaz" sorunu değil.
|
||||
Sınır bir kez çizilir, piller üstünde sonsuza dek birikir.
|
||||
|
||||
- **JSON/XML/HTML ayrıştırıcıları saQut'un kendisinde yazılabilir** (string +
|
||||
struct + fonksiyon + kontrol akışı yeter). İlk gerçek demo programları.
|
||||
- **Sıkıştırma/kripto:** denenmiş C kütüphanelerine FFI ile bağlan. **Kripto
|
||||
asla elle yazılmaz.**
|
||||
- **Bugüne tek yansıması:** IR/runtime tasarlanırken **bilinçli bir FFI seam**
|
||||
("host fonksiyonu çağır" deliği) bırakılır. `print` bunu zaten zorlar — bunu
|
||||
kaza değil, **kasıtlı bir mekanizma** yapıyoruz (ADR-016).
|
||||
|
||||
---
|
||||
|
||||
## Belge haritası
|
||||
|
||||
| Belge | İçerik |
|
||||
|---|---|
|
||||
| `docs/fikirler.md` | ADR-001…005: backend stratejisi, parser, header-only, token, IR |
|
||||
| `docs/adr-frontend-analiz.md` | ADR-006…019: frontend, analiz/optimizasyon, çalıştırma modeli, FFI, interface, bellek |
|
||||
| `docs/roadmap-frontend.md` | Faz-faz uygulama planı (sembol tablosu → fibonacci) |
|
||||
| `docs/transkript-frontend-tasarim.md` | Tasarım oturumunun transkripti |
|
||||
| `examples/fibonacci.sqt` | Geçerli referans program (semantik + kod üretimi fixture'ı) |
|
||||
| `examples/parser-stress/` | Yalnızca parser'ı zorlayan, **geçerli olmayan** fixture'lar |
|
||||
|
||||
---
|
||||
|
||||
## İlke
|
||||
|
||||
Bir şey çalışmadan önce çerçeve inşa etmekten kaçın. Önce **uçtan uca tek bir
|
||||
dikey dilim** çalıştır (kaynak → IR → çalıştır; tamsayı aritmetiği + değişken +
|
||||
kontrol akışı + tek bir `print`). Modülerlik bir kuzey yıldızıdır, v0.1
|
||||
gereksinimi değil; ihtiyaç doğmadan eklenen her soyutlama **daha az değil, daha
|
||||
çok** karmaşıklıktır.
|
||||
340
readme.md
340
readme.md
|
|
@ -1,225 +1,185 @@
|
|||
# saQut
|
||||
|
||||
**Programlanabilir, incelenebilir bir derleyici — bir "alet çantası" (toolbox).**
|
||||
> **A compiler built as a toolbox, not a black box —**
|
||||
> every internal phase is a first-class, inspectable output.
|
||||
|
||||
saQut'un asıl varlık sebebi dilin kendisinden çok, **derleme sürecinin her
|
||||
aşamasının dışarıdan görülebilir ve müdahale edilebilir olmasıdır.** Token'lar,
|
||||
AST, sembol tablosu, optimizasyonun öncesi/sonrası ve IR — hepsi ayrı ayrı
|
||||
incelenebilir. Dil, bu aletin üzerinde çalıştığı küçük, prosedürel bir
|
||||
örnektir; vitrin değil, alet.
|
||||
```
|
||||
saqut tokens file:fib.sqt → token stream, JSON
|
||||
saqut ast file:fib.sqt → full AST, JSON
|
||||
saqut ast file:fib.sqt --optimized → constant-folded + DCE'd AST
|
||||
saqut run file:fib.sqt → execute via IR + bytecode VM
|
||||
```
|
||||
|
||||
Uygulama dili **C++**'tır (header-only eğilimli, bkz. `docs/fikirler.md` ADR-003).
|
||||
Most compilers are black boxes. saQut is a **glass box.**
|
||||
|
||||
---
|
||||
|
||||
## Şu an ne çalışıyor, ne çalışmıyor
|
||||
## What is it?
|
||||
|
||||
Belgeler **planlanan** ile **yapılan**ı net ayırır. Bugünkü gerçek durum:
|
||||
saQut is a **procedural language compiler** written in C++.
|
||||
The language is small and C-flavoured on purpose — it is a vehicle, not the product.
|
||||
The product is **a compilation pipeline where every stage is named, queryable, and machine-readable.**
|
||||
|
||||
### ✅ Çalışıyor (built)
|
||||
- **Lexer** — karakter seviyesi tarama, konum takibi.
|
||||
- **Tokenizer** — token üretimi (6 token tipi), yorum satırı desteği.
|
||||
- **Pratt parser** — ifade (Pratt) + statement (recursive descent) ayrıştırma.
|
||||
- **AST** — fonksiyon, blok, değişken tanımı, if/for/while/do-while/return,
|
||||
ifade node'ları.
|
||||
- **AST'nin JSON serileştirmesi** — `saqut ast` ile incelenebilir.
|
||||
- **CLI komut yapısı** — `tokens`, `ast`, `symbols`, `run` iskeletleri.
|
||||
- **Kaynak konum takibi** (SourceLocation) — offset → (satır, sütun).
|
||||
- **Minimal IR deneyi** — basit aritmetiği düşürür (örn. `1 + (7/3)` → kısa
|
||||
doğrusal komut dizisi). Henüz tam bir backend değil, bir deneydir.
|
||||
|
||||
### 🚧 Henüz yok (planned)
|
||||
- Sembol tablosu
|
||||
- Semantik analiz
|
||||
- Tip sistemi
|
||||
- Diagnostic (hata raporlama) motoru
|
||||
- Optimizasyon
|
||||
- IR + bytecode VM ile çalıştırma
|
||||
|
||||
> `feature/frontend-analysis` dalı şu an yalnızca bu yapılmamış işin **tasarım
|
||||
> belgelerini** içerir, kodunu değil.
|
||||
|
||||
**Birinci kilometre taşı ("bitti" tanımı):** derleyici **fibonacci'yi**
|
||||
(recursive + iterative) ve basit matematik/döngü programlarını **derleyip
|
||||
çalıştırabilmeli.** Referans program: `examples/fibonacci.sqt`.
|
||||
You can pipe `saqut ast` into your own tool.
|
||||
You can hand the optimized AST diff to a review script.
|
||||
A stranger with no access to source could write an LSP from `saqut symbols` output alone.
|
||||
That is the test saQut is designed to pass.
|
||||
|
||||
---
|
||||
|
||||
## Dil kimliği (kilitli)
|
||||
## The language looks like this
|
||||
|
||||
Prosedürel, **C ailesi sözdizimi**, **value semantics**. İlk ifade doğrudan bir
|
||||
işlem/tanım olabilir; zorunlu class/`main` boilerplate'i yoktur (Java'nın aksine).
|
||||
```c
|
||||
int fibonacci(int n) {
|
||||
if (n <= 1) {
|
||||
return n;
|
||||
}
|
||||
return fibonacci(n - 1) + fibonacci(n - 2);
|
||||
}
|
||||
|
||||
| Özellik | Karar |
|
||||
int fibonacciIterative(int n) {
|
||||
int first = 0;
|
||||
int second = 1;
|
||||
for (int i = 0; i < n; i = i + 1) {
|
||||
int next = first + second;
|
||||
first = second;
|
||||
second = next;
|
||||
}
|
||||
return first;
|
||||
}
|
||||
|
||||
int main() {
|
||||
int n = 10;
|
||||
print(fibonacci(n));
|
||||
print(fibonacciIterative(n));
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
- No mandatory `class` / `main` boilerplate
|
||||
- Typed functions, `struct`, `int[]` arrays
|
||||
- `int`, `float`, `bool`, `string` literal types
|
||||
- Value semantics — no user-visible pointers
|
||||
- Single FFI seam (`callhost`) — the only door to the outside world
|
||||
|
||||
**Deliberately absent:** OOP, closures, generics, implicit int↔float coercion, `auto`.
|
||||
|
||||
---
|
||||
|
||||
## Build
|
||||
|
||||
**Requirements:** C++17, CMake ≥ 3.16, Ninja
|
||||
|
||||
```bash
|
||||
git clone https://github.com/abdussamedulutas/saqut
|
||||
cd saqut
|
||||
cmake -B build -G Ninja
|
||||
cmake --build build
|
||||
```
|
||||
|
||||
Binary lands at `build/saqut`.
|
||||
|
||||
**Tested on:** Linux (x86-64, Manjaro). macOS and Windows untested but no platform-specific code.
|
||||
|
||||
---
|
||||
|
||||
## CLI
|
||||
|
||||
| Command | What you get |
|
||||
|---|---|
|
||||
| Class / OOP / kalıtım | **Yok** |
|
||||
| Closure | **Yok** |
|
||||
| Generic | **Yok** |
|
||||
| Kullanıcıya açık pointer (`*` / `&`) | **Yok** — derleyici/runtime içeride pointer'ı serbestçe kullanır |
|
||||
| `struct` | **Var** |
|
||||
| Tipli fonksiyonlar (dönüş + parametre) | **Var** |
|
||||
| Array (`int[]`) | **Var** |
|
||||
| `interface` | **Ertelendi** (v0 değil — gerekçe ADR-018) |
|
||||
| `auto` / tip çıkarımı | **Yok** |
|
||||
| Gizli int↔float dönüşümü | **Yok** (tek istisna: sabit folding) |
|
||||
| `saqut tokens file:src.sqt` | Token stream with positions |
|
||||
| `saqut ast file:src.sqt` | Full AST as JSON |
|
||||
| `saqut ast file:src.sqt --optimized` | AST after constant folding + dead-code elimination |
|
||||
| `saqut symbols file:src.sqt` | Symbol table dump |
|
||||
| `saqut ir file:src.sqt` | IR instruction dump |
|
||||
| `saqut run file:src.sqt` | Compile and run via bytecode VM |
|
||||
|
||||
Gerekçe: prosedürel tasarım semantik karmaşıklığı en aza indirir ve hedeflerle
|
||||
(fibonacci, matematik, sıralama, ayrıştırma) örtüşür. Standart C'de `class`
|
||||
yoktur (o C++'tır); C, struct + fonksiyonun yettiğini kanıtlar.
|
||||
Every output is designed to be piped, diffed, or consumed by other tools.
|
||||
|
||||
---
|
||||
|
||||
## Çalıştırma modeli (kilitli): IR + bytecode VM
|
||||
|
||||
saQut, kendi **IR**'sine derler ve bu IR'yi bir **yorumlayıcı döngü (bytecode
|
||||
VM)** ile çalıştırır.
|
||||
|
||||
- **Tree-walker DEĞİL** (çok yavaş).
|
||||
- **Gerçek makine-kodu JIT DEĞİL.** Makine kodu üretimi (register allocation,
|
||||
ABI/çağırma sözleşmeleri, çalıştırılabilir `mmap` bellek) **kapsam dışıdır** —
|
||||
tek faydası ham hızdır ve hız burada öncelik değildir. Öncelikler
|
||||
**determinizm** ve **incelenebilirliktir**; bytecode VM ikisini de doğrudan
|
||||
sağlar.
|
||||
- **Bellek bu modelde kolaydır:** host (C++) heap'i kullanılır; v0 için özel
|
||||
runtime allocator gerekmez.
|
||||
- **C'ye transpile, geçerli bir İKİNCİ backend olarak ileride kalır** (frontend
|
||||
backend-bağımsızdır — middle-end ayrımının amacı budur, ADR-006). İleride
|
||||
makine kodu istenirse elle code generator yazmak yerine **libgccjit / LLVM'e
|
||||
bağlanılır** — ama bu çok uzak gelecektir.
|
||||
|
||||
> Eski belge/konuşmalarda geçen "JIT" terimi yanlış yönlendiricidir; doğru
|
||||
> çerçeve **IR + VM**'dir.
|
||||
|
||||
---
|
||||
|
||||
## Tasarım felsefesi — neden saQut farklı?
|
||||
|
||||
saQut "daha iyi bir dil" iddiasında değil. Farkı, **derleyiciyi bir platform**
|
||||
olarak ele almasında. İki taahhüt üstüne kuruludur:
|
||||
|
||||
**1. Cam (gör + sorgula + içine müdahale et).** Her aşama — token, AST, sembol
|
||||
tablosu, tip, IR — kararlı, makine-okur ve **çift yönlü** bir arayüzden
|
||||
erişilebilir olmalıdır. Sadece "dök ve göster" değil: kendi AST'ini verip tip
|
||||
kontrolü isteyebilmeli, IR verip çalıştırabilmelisin. **Turnusol testi:** bir
|
||||
yabancı, yalnızca `saqut ast` + `saqut symbols` çıktısından, bizden habersiz bir
|
||||
LSP yazabiliyor mu? Cevap "evet" ise platform gerçektir.
|
||||
|
||||
**2. Kafes (deterministik + yetenek-güvenli çalıştırma).** Pointer yok, value
|
||||
semantics, scope-tabanlı bellek ve **tek dış-dünya kapısı olan FFI seam**
|
||||
(ADR-016) sayesinde saQut kodu, host'un açıkça izin verdiği fonksiyonlar dışında
|
||||
dünyaya dokunamaz. Bytecode VM deterministiktir (ADR-015): aynı girdi → aynı
|
||||
çıktı → aynı çalışma. "Sadelik" diye tasarlanan bu kararlar aslında bir
|
||||
**yetenek-güvenliği (capability sandbox)** kurar — güvenilmeyen veya
|
||||
AI-üretimi kodu güvenle çalıştırmak için biçilmiş kaftan.
|
||||
|
||||
**Bu ikisinin ödülü — kayıt & tekrar (record-replay).** 🚧 *(vizyon, v0 değil;
|
||||
bkz. issue #94.)* Belirsizliğin tek kaynağı (kullanıcı girdisi, zaman, IO,
|
||||
GC/thread kararları) FFI kapısından geçtiği için, mükemmel tekrar oynatma için
|
||||
**her değişkeni her adımda kaydetmek gerekmez** — yalnızca kapıdan geçen değerler
|
||||
kaydedilir, gerisi VM deterministik olarak yeniden çalıştırılarak üretilir. Boyut
|
||||
gigabayttan kilobayta düşer. Replay modunda FFI çağrıları gerçekten çalışmaz,
|
||||
kaydedilmiş değeri döndürür (dosyayı tekrar silmez, sunucuya tekrar istek atmaz).
|
||||
Böylece "benim makinemde çalışıyor, müşteride patlıyor" sorunu: müşteri bir dump
|
||||
yollar, sen çöküşü adım adım, aynı verilerle geri sararsın.
|
||||
|
||||
> Log, önceden sormayı akıl ettiğin sorulara cevap verir; **tekrar-oynatma,
|
||||
> çöküşten *sonra* aklına gelen sorulara.** Zaman-yolculuğu hata ayıklama ayrı
|
||||
> bir altyapı değildir — cam sorgularına bir **zaman koordinatı** eklemektir.
|
||||
|
||||
⚠️ Bu ödülün bedeli v0'da ödenir: **determinizm kutsaldır ve her belirsizlik
|
||||
kaynağı kayıt-altına-alınabilir tek kapıdan geçmelidir.** Sonradan eklenemez;
|
||||
baştan korunur.
|
||||
|
||||
---
|
||||
|
||||
## Mimari hatlar
|
||||
## Pipeline
|
||||
|
||||
```
|
||||
KAYNAK KOD
|
||||
│ lexer
|
||||
Source
|
||||
│ Lexer + Tokenizer
|
||||
▼
|
||||
TOKEN'LAR ────────────── saqut tokens
|
||||
│ parser (Pratt + recursive descent)
|
||||
Tokens ──────────────────── saqut tokens
|
||||
│ Pratt parser + recursive descent
|
||||
▼
|
||||
AST ──────────────────── saqut ast
|
||||
│ sembol toplama (iki geçişli) ┐
|
||||
▼ │
|
||||
SEMBOL TABLOSU ───────── saqut symbols │ FRONTEND
|
||||
│ semantik analiz (annotation) │ (yapı + anlam)
|
||||
▼ │
|
||||
ANNOTATE EDİLMİŞ AST ─── saqut ast ┘
|
||||
│ optimizasyon (opsiyonel, klon üstünde) ── MIDDLE-END
|
||||
AST ─────────────────────── saqut ast
|
||||
│ Symbol collector (two-pass)
|
||||
▼
|
||||
IR ───────────────────── (planlanan) ┐
|
||||
│ bytecode VM / yorumlayıcı döngü │ BACKEND
|
||||
▼ │ (çalıştırma + FFI seam)
|
||||
ÇALIŞTIRMA / ÇIKTI ───── saqut run ┘
|
||||
Symbol Table ────────────── saqut symbols
|
||||
│ Type checker + structural validator
|
||||
▼
|
||||
Annotated AST
|
||||
│ Optimization Manager (clone — original untouched)
|
||||
│ ├─ Constant Folding pass
|
||||
│ └─ Dead Code Elimination pass
|
||||
▼
|
||||
Optimized AST ───────────── saqut ast --optimized
|
||||
│ IR Generator
|
||||
▼
|
||||
IR ──────────────────────── saqut ir
|
||||
│ Bytecode VM (interpreter loop)
|
||||
▼
|
||||
Output ──────────────────── saqut run
|
||||
```
|
||||
|
||||
- **Frontend** yapıyı ve anlamı modeller (tip, scope, dataflow).
|
||||
- **"Hangi çekirdek, hangi cihaz, ne zaman, hangi çıktı formatı"** runtime/backend
|
||||
meselesidir — frontend'e yüklenmez.
|
||||
The optimizer works on a **clone** of the AST — the original is preserved.
|
||||
Constant folding and DCE run in a fixpoint loop until nothing changes.
|
||||
|
||||
---
|
||||
|
||||
## CLI (mevcut + planlanan)
|
||||
## What works right now
|
||||
|
||||
```
|
||||
# --- çalışıyor ---
|
||||
saqut tokens file:kaynak.sqt # token listesi
|
||||
saqut ast file:kaynak.sqt # AST (JSON)
|
||||
saqut symbols file:kaynak.sqt # sembol tablosu (iskelet)
|
||||
|
||||
# --- planlanan ---
|
||||
saqut run file:kaynak.sqt # IR üret + bytecode VM ile çalıştır
|
||||
saqut ast file:kaynak.sqt --optimized # klon, optimize edilmiş AST (öncesi/sonrası)
|
||||
saqut transpile file:kaynak.sqt -o prog.c # ikinci backend (ileride)
|
||||
```
|
||||
|
||||
Tasarım gereği her aşamanın çıktısı erken bir noktada dosyalanabilir/loglanabilir
|
||||
(programlanabilir derleyici). Token, ham AST, optimize AST ve IR ayrı ayrı
|
||||
kaydedilebilir.
|
||||
|
||||
---
|
||||
|
||||
## Batteries / stdlib — kuzey yıldızı, ertelendi
|
||||
|
||||
Gerçek bir genel sürüm pil ile gelmeli (sıralama, sıkıştırma, kripto,
|
||||
JSON/XML/HTML ayrıştırma). Ama bu **bugünün işi ve v0.1 değildir.**
|
||||
|
||||
Mimari çerçeve (monolit korkusunu önler): derleyici pilleri çekirdeğine
|
||||
gömmez. Bunun yerine **küçük bir gerçek builtin kümesi** (`print`, temel
|
||||
zorunlular) + **gerisi kütüphane/FFI** ile gelir. "Batteries" sorunu aslında
|
||||
bir **sınır (FFI/link seam) sorunudur**, "zlib'i yeniden yaz" sorunu değil.
|
||||
Sınır bir kez çizilir, piller üstünde sonsuza dek birikir.
|
||||
|
||||
- **JSON/XML/HTML ayrıştırıcıları saQut'un kendisinde yazılabilir** (string +
|
||||
struct + fonksiyon + kontrol akışı yeter). İlk gerçek demo programları.
|
||||
- **Sıkıştırma/kripto:** denenmiş C kütüphanelerine FFI ile bağlan. **Kripto
|
||||
asla elle yazılmaz.**
|
||||
- **Bugüne tek yansıması:** IR/runtime tasarlanırken **bilinçli bir FFI seam**
|
||||
("host fonksiyonu çağır" deliği) bırakılır. `print` bunu zaten zorlar — bunu
|
||||
kaza değil, **kasıtlı bir mekanizma** yapıyoruz (ADR-016).
|
||||
|
||||
---
|
||||
|
||||
## Belge haritası
|
||||
|
||||
| Belge | İçerik |
|
||||
| Stage | Status |
|
||||
|---|---|
|
||||
| `docs/fikirler.md` | ADR-001…005: backend stratejisi, parser, header-only, token, IR |
|
||||
| `docs/adr-frontend-analiz.md` | ADR-006…019: frontend, analiz/optimizasyon, çalıştırma modeli, FFI, interface, bellek |
|
||||
| `docs/roadmap-frontend.md` | Faz-faz uygulama planı (sembol tablosu → fibonacci) |
|
||||
| `docs/transkript-frontend-tasarim.md` | Tasarım oturumunun transkripti |
|
||||
| `examples/fibonacci.sqt` | Geçerli referans program (semantik + kod üretimi fixture'ı) |
|
||||
| `examples/parser-stress/` | Yalnızca parser'ı zorlayan, **geçerli olmayan** fixture'lar |
|
||||
| Lexer / Tokenizer | ✅ |
|
||||
| Pratt parser | ✅ |
|
||||
| AST + JSON serialization | ✅ |
|
||||
| Symbol table (two-pass collector) | ✅ |
|
||||
| Type checker | ✅ |
|
||||
| Structural validator | ✅ |
|
||||
| Constant folding (int, bool, logical, unary) | ✅ |
|
||||
| Dead code elimination | ✅ |
|
||||
| IR generator + bytecode VM | ✅ |
|
||||
| `saqut run` executes fibonacci | ✅ |
|
||||
| `string` type | ✅ |
|
||||
| `struct` | 🚧 |
|
||||
| `int[]` arrays | 🚧 |
|
||||
| Standard library / FFI beyond `print` | 🚧 |
|
||||
|
||||
---
|
||||
|
||||
## İlke
|
||||
## Philosophy in two sentences
|
||||
|
||||
Bir şey çalışmadan önce çerçeve inşa etmekten kaçın. Önce **uçtan uca tek bir
|
||||
dikey dilim** çalıştır (kaynak → IR → çalıştır; tamsayı aritmetiği + değişken +
|
||||
kontrol akışı + tek bir `print`). Modülerlik bir kuzey yıldızıdır, v0.1
|
||||
gereksinimi değil; ihtiyaç doğmadan eklenen her soyutlama **daha az değil, daha
|
||||
çok** karmaşıklıktır.
|
||||
**Glass:** every compilation stage is a stable, queryable output — tokens, AST, symbols, IR — all separately inspectable and pipeable.
|
||||
**Cage:** no user pointers, value semantics, single FFI door — the VM is deterministic, which makes record-replay and time-travel debugging a natural extension, not an afterthought.
|
||||
|
||||
The long version is in [`docs/architecture.md`](docs/architecture.md).
|
||||
|
||||
---
|
||||
|
||||
## Design records
|
||||
|
||||
Architectural decisions live in `docs/`:
|
||||
|
||||
| File | Coverage |
|
||||
|---|---|
|
||||
| [`docs/fikirler.md`](docs/fikirler.md) | ADR-001–005: backend strategy, parser, header-only, token, IR |
|
||||
| [`docs/adr-frontend-analiz.md`](docs/adr-frontend-analiz.md) | ADR-006–019: analysis, optimization, execution model, FFI, memory |
|
||||
| [`docs/roadmap-frontend.md`](docs/roadmap-frontend.md) | Phase-by-phase implementation plan |
|
||||
| [`docs/architecture.md`](docs/architecture.md) | Full architecture reference (Turkish) |
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
Source-available, commercial use restricted.
|
||||
Free for: personal use, learning, writing and running saQut programs, internal tooling.
|
||||
Requires permission for: hosting as a service, embedding sub-components commercially, redistributing as a product.
|
||||
|
||||
See [`LICENSE.md`](LICENSE.md) for the full terms.
|
||||
Commercial licensing: saqutsoftware+gitea@gmail.com
|
||||
|
|
|
|||
Loading…
Reference in New Issue