13. Proje, modül ve şablonlar

Tek dosyalık denemeden gerçek bir projeye geçiş.

kabalang yeni — sekiz şablon

kabalang yeni <ad> --konsol       # uçbirim uygulaması (--cli ile aynı)
kabalang yeni <ad> --gui          # pencereli uygulama (ana.kbl + ana.ui)
kabalang yeni <ad> --servis       # systemd servisi (daemon)
kabalang yeni <ad> --web          # HTTP sunucusu (HTML sunar)
kabalang yeni <ad> --api          # REST/JSON API (durum kodlu, HTML yok)
kabalang yeni <ad> --kapp         # KabaOS uygulaması (izin beyanı + .desktop)
kabalang yeni <ad> --kutuphane    # yeniden kullanılabilir paylaşımlı kütüphane
kabalang yeni <ad> --yalin        # sistem programlama: işletim sistemi olmadan donanımda koşar
kabalang yeni <ad> --sinama       # sınama projesi (birim + testler + kapsam)

Bayrak yazılmazsa --gui varsayılır.

Her şablon ayrıca kaba.proje (manifest) ve .kateproject (Kod Düzenleyici proje tanımı) yazar.

⚠️ --kutuphane şablonu bugün test dosyası üretmez. Sınama yazmaya hazır bir iskelet istiyorsanız --sinama kullanın.

Şablonlar gerçekten çalıştırılarak sınanır: konsol ve kütüphane koşturulur, servis başlatılıp SIGTERM ile kapatılır, web sunucusuna gerçek HTTP isteği atılır, sınama projesi kapsam eşiğiyle ölçülür.

Başlamak:

kabalang yeni gunluk_izleyici --servis
cd gunluk_izleyici
kabalang calistir ana.kbl        # ya da: kabalang dev  (değişince yeniden derler)

kaba.proje manifesti

{
    "proje_adi": "gunluk_izleyici",
    "surum": "1.0.0",
    "hedef_tur": "servis",
    "ana_dosya": "ana.kbl",
    "kaynaklar": ["ana.kbl"],
    "bagimliliklar": []
}

Modüller — kodu dosyalara bölmek

Bir .kbl dosyasını kullan "yol.kbl" ile içe aktarırsınız. İsim alanı dosya adından gelir: kutuphane/hesap.kbl → hesap.topla(...).

Önce modül:

```kabalang dosya:kutuphane/hesap.kbl

Yeniden kullanılabilir modül

yapi Kayit: islem = "" sonuc = 0

fonksiyon topla(a, b): don a + b

fonksiyon kayit_olustur(islem, sonuc): k = Kayit() k.islem = islem k.sonuc = sonuc don k

fonksiyon ozet(kayitlar): don "toplam " + metin(kayitlar.uzunluk()) + " kayıt"

Sonra kullanan program:

```kabalang
kullan "kutuphane/hesap.kbl"
kullan "kutuphane/hesap.kbl" olarak h        # takma ad

k1 = hesap.kayit_olustur("2+3", hesap.topla(2, 3))
k2 = h.kayit_olustur("4+4", h.topla(4, 4))

dogrula(k1.sonuc == 5, "modülden yapı döndü")
dogrula(k2.sonuc == 8, "takma adla aynı modül")

# ⚠️ Yapı listesi ÖNCE kurulur; `hesap.ozet([k1])` gibi yerinde yazılan
#    yapı listesi bugün DERLENMEZ (ölçüldü).
kayitlar = []
kayitlar.ekle(k1)
kayitlar.ekle(k2)

dogrula(hesap.ozet(kayitlar) == "toplam 2 kayıt", "modül fonksiyonu liste aldı")
yazdir("modül tamam")

⚠️ kullan kaba.sistem (tırnaksız, nokta ile) standart kütüphane modülüdür; kullan "dosya.kbl" (tırnaklı) kendi dosyanızdır. İkisi ayrı şeydir.

Testler

kabalang sinav, projede test_*.kbl ya da *_test.kbl adlı dosyaları bulur, derler ve çalıştırır. dogrula yanlışsa program 1 ile çıkar ve test düşer:

```kabalang dosya:kutuphane/hesap.kbl fonksiyon topla(a, b): don a + b

```kabalang
kullan "kutuphane/hesap.kbl"

dogrula(hesap.topla(2, 3) == 5, "topla")
dogrula(hesap.topla(-1, 1) == 0, "negatif")
yazdir("testler geçti")

kabalang sinav            # bütün test dosyaları
kabalang sinav test_hesap.kbl

Daha iyi iddialar için kaba.sinama vardır (kusurlar birikir, beklenen ve bulunan yazılır): bkz. 8. Standart kütüphane.

Kapsam ölçümü

kabalang sinav --kapsam           # hangi satırlar koşmadı?
kabalang sinav --kapsam --esik 80 # %80'in altındaysa çıkış kodu 1

Çıktı doğrudan KabaLang satırlarını gösterir:

📊 Kapsam (KabaLang satırları)
  test_hesap.kbl  %75.0 (9/12 satır)
    kapsanmayan satır: 5, 8, 9
    hiç çağrılmamış fonksiyon: eski_yardimci

  Toplam: %75.0 (9/12)

⚠️ "Hiç çağrılmamış fonksiyon" ayrıca raporlanır — ve bu önemlidir. Hiç çağrılmayan bir fonksiyon, satır sayımında görünmez; yalnız satırlara bakan bir rapor, bütün bir fonksiyon sınanmamışken %100 yazardı. Bu yüzden kapsam raporu çağrılmamış fonksiyonları adıyla ayrıca listeler ve yüzdeye katar (yukarıdaki örnekte %90 yerine doğru değer olan %75).

⚠️ Kapsam koşusu eniyileme kapalı derlenir. Eniyileme açıkken satırlar birleşir ya da kaldırılır; satır bazlı sayım yanıltıcı olur.

⚠️ Yüzde tek başına bir şey söylemez. Bu yüzden kapsanmayan satır numaraları da yazılır: insanlar yüzdeyi kovalarken kritik dalın sınanmadan kalması, ölçmemekten kötüdür.

Sınama projesi — kabalang yeni <ad> --sinama

Sınama yazmaya hazır iskelet. Diğer şablonlarda asıl ürün uygulamadır ve test yanında durur; burada asıl ürün sınama düzeninin kendisidir.

kabalang yeni notdefteri --sinama
cd notdefteri
kabalang sinav                      # 2 dosya, 16 iddia
kabalang sinav --kapsam --esik 90   # kapsam eşiğin altındaysa çıkış kodu 1

notdefteri/
  kaynak/notlar.kbl     sınanan birim (test dosyaları `kullan` ile çağırır)
  test_notlar.kbl       ana davranış iddiaları
  test_sinir.kbl        sınır durumları (eşik değerleri, boş liste)
  ana.kbl               elle denemek için küçük demo
  kaba.proje            hedef_tur = "sinama", hedefi `tur: "test"`
  .kateproject          varsayılan görev "Testler" (+ "Kapsam", "Kıyasla")

Şablon dogrula değil kaba.sinama kullanır ve iddia ailesinin tamamını (esit · esit_degil · dogru · yanlis · yaklasik · icerir · ozet) gösterir.

⚠️ Kutudan çıkınca kapsam %100'dür (50/50 satır, ölçüldü). Kapsamı düşük bir sınama şablonu --esiki ilk günden kırmızı yakar ve kullanıcı eşiği düşürerek "çözer" — eşik o gün anlamını kaybeder.

⚠️ Yeni bir fonksiyon eklerken sınamasını da ekleyin. Hiç çağrılmayan fonksiyon kapsam raporunda adıyla çıkar, yüzde düşer ve --esik kapıyı kapatır.

Kıyaslama — kabalang kiyasla

Başarım ölçümü. Sınamanın "doğru mu" sorusuna karşılık, kıyaslamanın sorusu "ne kadar hızlı" — ve asıl işi basılan sayının bir anlamı olduğunu kanıtlamaktır.

kabalang kiyasla ana.kbl                       # çalışma süresi
kabalang kiyasla ana.kbl --derleme             # derlenme süresi
kabalang kiyasla ana.kbl --tur 15 --isinma 3
kabalang kiyasla ana.kbl --json taban.json     # taban bırak
kabalang kiyasla ana.kbl --karsilastir taban.json --esik-yuzde 10

📏 KabaLang Kıyaslama — ÇALIŞMA

  Ortam sağlaması (ölçümden ÖNCE):
    · disk /tmp: 4.7 GB boş (%69 dolu)
    · yük: 0.31 / 12 çekirdek
    · CPU yöneticisi (governor): performance

  Isınma (9 tur, atıldı): 48.64 ms → 48.25 ms → …
    (3 blok × blok başına 3 ısınma — her blok kendi ısınmasıyla başlar)
  Ölçüm: 12 tur
    medyan      : 48.12 ms
    en iyi/kötü : 47.48 ms / 49.46 ms
    yayılım     : ±%0.73  (MAD/medyan)
    gürültü tabanı: ±%0.79  (aynı ikilinin AYRI ISITILAN blokları)
    karar bandı : ±%1.52  (yayılım + sürüklenme)

    boş taban   : 3.28 ms  (aynı araç zinciriyle derlenmiş `x = 0` programı)
    NET İŞ      : 44.84 ms  (%93.2)
    ✓ ölçülebilir: net iş, gürültünün 45.9 katı (en az 3× istenir)

  çıktı damgası: d7334d236c906a48  (12 turun 12'inde aynı)

Neden bu kadar kapı var — ölçülmüş tuzaklar

⚠️ "Bir hız sınaması düştü" ≠ "kod yavaşladı". Disk dolduğunda derleme önbelleği yazılamaz ve her derleme belirgin biçimde yavaşlar; sebep kod değil disktir. Bu yüzden kiyasla ölçümden önce diske, derleme önbelleğine, yüke ve CPU yöneticisine bakar (çıktıda önbellek satırı da görünür); disk doluysa ölçüm hiç başlamaz.

⚠️ Ölçüm önbelleğin sıcak olup olmamasına aşırı duyarlı. Isınma turları bunu soğurur; araç ayrıca ilk ısınma turu belirgin yavaşsa "önbellek soğuktu" der. Gizlenmiş bir soğuk önbellek, yarınki ölçümle karşılaştırmayı sessizce bozar.

⚠️ Gürültü tahmin edilmez, ölçülür. "±%5 olsun" bir tahmindir. Doğrusu aynı ikiliyi birden çok kez koşturmak ve değişen neyse onu gürültü saymaktır. Turlar, her biri kendi ısınmasıyla başlayan bloklara bölünür; bloklar arası medyan farkı gürültü tabanıdır. Karar bandının altındaki her "hızlandı/yavaşladı" iddiası karar verilemez sayılır.

⚠️ Sayı, hiçbir şey ölçmüyorken de güven verebilir. 12,40 ms yazan bir ölçümün 12,30 ms'si süreç başlatma olabilir; o programda yapılan hiçbir iyileştirme sayıya yansımaz. Araç bu yüzden aynı araç zinciriyle derlenmiş boş bir programı da ölçer ve farkı NET İŞ olarak yazar. Net iş gürültünün 3 katına ulaşmıyorsa sayı basmayı reddeder (çıkış kodu 1). --tur arttırmak bunu düzeltmez: sorun turların azlığı değil, ölçülen işin yokluğudur.

⚠️ İşi silerek hızlanmak, hızlanmanın en kolay yoludur. Çıktı damgası (stdout sha256) her turda karşılaştırılır; turlar arasında değişirse ölçüm düşer. Tabanla karşılaştırırken damgalar tutmuyorsa iki farklı iş kıyaslanıyordur ve karşılaştırma reddedilir. Programın çıktısı yoksa --bekle METIN ile bir çıktı şartı koyun.

⚠️ Çöken programın süresi yoktur. Her turda çıkış kodu denetlenir; sıfır değilse ölçüm düşer — çöken program hızlı çöker.

⚠️ Taban ile karşılaştırma, aynı dünyada alınmış olmayı ister. Derleyici sürümü, işlemci, mimari ve CPU yöneticisi değişmişse rapor bunu söyler. Makinenin yükü de öyle: ölçüldü — bir tabanın boş makinede (yük 0,4/12), karşılaştırmasının meşgul makinede (2,4/12) alındığı bir turda program gerçekten %5,06 yavaş koştu ve araç "YAVAŞLADI" dedi. Sayı doğruydu, atıf yanlıştı: yavaşlatan kod değil makineydi. Araç artık yük farkını da bildirir.

⚠️ Bant geniş çıkıyorsa sayı değil ölçüm koşulları sorunludur. Meşgul bir makinede ve küçük bir iş yükünde bant %10'u aşabilir; bu, ölçümün o an ancak %20 üstü farkları görebildiği anlamına gelir. Araç bunu yazar ve ne yapılacağını söyler (makineyi boşalt · --turu arttır · işi büyüt).

Kod kalitesi araçları

kabalang kontrol ana.kbl          # denetçi: kullanılmayan değişken, yazım hatası...
kabalang kontrol ana.kbl --tam    # daha geniş denetim
kabalang bicimlendir ana.kbl      # standart girinti
kabalang izle ana.kbl             # değişince kendiliğinden yeniden derle

Dağıtım

⚠️ Aynı kaynak her derlemede bit bit aynı ikiliyi üretir (tekrarlanabilir derleme). İmzalı paket ve CI güveninin ön şartı budur.

Sonraki adım

14. Anahtar sözcük başvurusu · 15. Tuzaklar