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
|
# 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,
|
saqut tokens file:fib.sqt → token stream, JSON
|
||||||
AST, sembol tablosu, optimizasyonun öncesi/sonrası ve IR — hepsi ayrı ayrı
|
saqut ast file:fib.sqt → full AST, JSON
|
||||||
incelenebilir. Dil, bu aletin üzerinde çalıştığı küçük, prosedürel bir
|
saqut ast file:fib.sqt --optimized → constant-folded + DCE'd AST
|
||||||
örnektir; vitrin değil, alet.
|
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)
|
You can pipe `saqut ast` into your own tool.
|
||||||
- **Lexer** — karakter seviyesi tarama, konum takibi.
|
You can hand the optimized AST diff to a review script.
|
||||||
- **Tokenizer** — token üretimi (6 token tipi), yorum satırı desteği.
|
A stranger with no access to source could write an LSP from `saqut symbols` output alone.
|
||||||
- **Pratt parser** — ifade (Pratt) + statement (recursive descent) ayrıştırma.
|
That is the test saQut is designed to pass.
|
||||||
- **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)
|
## The language looks like this
|
||||||
|
|
||||||
Prosedürel, **C ailesi sözdizimi**, **value semantics**. İlk ifade doğrudan bir
|
```c
|
||||||
işlem/tanım olabilir; zorunlu class/`main` boilerplate'i yoktur (Java'nın aksine).
|
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** |
|
| `saqut tokens file:src.sqt` | Token stream with positions |
|
||||||
| Closure | **Yok** |
|
| `saqut ast file:src.sqt` | Full AST as JSON |
|
||||||
| Generic | **Yok** |
|
| `saqut ast file:src.sqt --optimized` | AST after constant folding + dead-code elimination |
|
||||||
| Kullanıcıya açık pointer (`*` / `&`) | **Yok** — derleyici/runtime içeride pointer'ı serbestçe kullanır |
|
| `saqut symbols file:src.sqt` | Symbol table dump |
|
||||||
| `struct` | **Var** |
|
| `saqut ir file:src.sqt` | IR instruction dump |
|
||||||
| Tipli fonksiyonlar (dönüş + parametre) | **Var** |
|
| `saqut run file:src.sqt` | Compile and run via bytecode VM |
|
||||||
| 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
|
Every output is designed to be piped, diffed, or consumed by other tools.
|
||||||
(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
|
## Pipeline
|
||||||
|
|
||||||
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
|
Source
|
||||||
│ lexer
|
│ Lexer + Tokenizer
|
||||||
▼
|
▼
|
||||||
TOKEN'LAR ────────────── saqut tokens
|
Tokens ──────────────────── saqut tokens
|
||||||
│ parser (Pratt + recursive descent)
|
│ Pratt parser + recursive descent
|
||||||
▼
|
▼
|
||||||
AST ──────────────────── saqut ast
|
AST ─────────────────────── saqut ast
|
||||||
│ sembol toplama (iki geçişli) ┐
|
│ Symbol collector (two-pass)
|
||||||
▼ │
|
|
||||||
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) ┐
|
Symbol Table ────────────── saqut symbols
|
||||||
│ bytecode VM / yorumlayıcı döngü │ BACKEND
|
│ Type checker + structural validator
|
||||||
▼ │ (çalıştırma + FFI seam)
|
▼
|
||||||
ÇALIŞTIRMA / ÇIKTI ───── saqut run ┘
|
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).
|
The optimizer works on a **clone** of the AST — the original is preserved.
|
||||||
- **"Hangi çekirdek, hangi cihaz, ne zaman, hangi çıktı formatı"** runtime/backend
|
Constant folding and DCE run in a fixpoint loop until nothing changes.
|
||||||
meselesidir — frontend'e yüklenmez.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## CLI (mevcut + planlanan)
|
## What works right now
|
||||||
|
|
||||||
```
|
| Stage | Status |
|
||||||
# --- ç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 |
|
| Lexer / Tokenizer | ✅ |
|
||||||
| `docs/adr-frontend-analiz.md` | ADR-006…019: frontend, analiz/optimizasyon, çalıştırma modeli, FFI, interface, bellek |
|
| Pratt parser | ✅ |
|
||||||
| `docs/roadmap-frontend.md` | Faz-faz uygulama planı (sembol tablosu → fibonacci) |
|
| AST + JSON serialization | ✅ |
|
||||||
| `docs/transkript-frontend-tasarim.md` | Tasarım oturumunun transkripti |
|
| Symbol table (two-pass collector) | ✅ |
|
||||||
| `examples/fibonacci.sqt` | Geçerli referans program (semantik + kod üretimi fixture'ı) |
|
| Type checker | ✅ |
|
||||||
| `examples/parser-stress/` | Yalnızca parser'ı zorlayan, **geçerli olmayan** fixture'lar |
|
| 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
|
**Glass:** every compilation stage is a stable, queryable output — tokens, AST, symbols, IR — all separately inspectable and pipeable.
|
||||||
dikey dilim** çalıştır (kaynak → IR → çalıştır; tamsayı aritmetiği + değişken +
|
**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.
|
||||||
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
|
The long version is in [`docs/architecture.md`](docs/architecture.md).
|
||||||
çok** karmaşıklıktır.
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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