Dev Modülü

Bu beceri bu depo içinde çalışan LLM'ler için yazılmıştır. En hızlı, en güvenilir iç döngüye odaklanır:

• Zig bağlamalarını gerektiğinde yeniden derle
• Deponun düzenlenmiş test çalıştırıcısını çalıştır (ato dev test --llm, ham test çıktısı değil)
• Oluşturulan test raporlarını kullan (artifacts/test-report.json, artifacts/test-report.html, artifacts/test-report.llm.json)
• ConfigFlag'ları doğru şekilde keşfet ve kullan (ve depo genelinde envanterini tut)

Hızlı Başlangıç

source .venv/bin/activate

ato dev compile
ato dev test --llm -k solver
ato dev test --llm --view HEAD --open
ato dev test --reuse --baseline HEAD~1
ato dev flags

İlgili Dosyalar

• CLI komutları: src/atopile/cli/dev.py
  • ato dev compile (import faebryk.core.zig aracılığıyla Zig derlemesini tetikler)
  • ato dev test --llm (test/runner/main.py dosyasını argümanlarla çalıştırır; baseline/CI rapor yardımcılarını destekler)
• Zig build-on-import yapışkanı: src/faebryk/core/zig/__init__.py (ZIG_NORECOMPILE, ZIG_RELEASEMODE)
• Config flagları yardımcı programı: src/faebryk/libs/util.py (ConfigFlag, ConfigFlagInt, …)
• Test çalıştırıcısı + raporlar: test/runner/main.py (artifacts/test-report.json, artifacts/test-report.html, artifacts/test-report.llm.json)
• CI artefaktsı tanımı: .github/workflows/pytest.yml (test-report.json, test-report.html)

Bağımlılar (Çağrı Siteleri)

• CI/CD: dev komutları GitHub Actions workflow'ları için birincil arayüzdür.
• Yerel Geliştirme: Geliştiriciler Zig kodunu değiştirdikten sonra ato dev compile kullanırlar.

Nasıl Çalışılır / Geliştirilir / Test Edilir

Temel Komutlar

• ato dev compile: native uzantıları derle (graph/typegraph/sexp bağlamaları).
• ato dev test --llm: düzenlenmiş test çalıştırıcısını çalıştırır (varsayılan olarak -p test -p src); destekler:
  • -k filtresi (-- -k ... de geçiş argümanları aracılığıyla çalışır)
  • --baseline karşılaştırmaları (commit hash'i veya HEAD~N stili)
  • --view / --open GitHub Actions'tan test-report.html artefaktını getir ve aç (gerekli: gh CLI)
  • --ci CI marker ifadesini uygula (not not_in_ci and not regression and not slow)
  • --direct -k <testname> tek testi test/runtest.py aracılığıyla çalıştır (dar kapsamlı tek-test döngüleri)

Test Raporları (JSON gerçek kaynağı)

Yerel test çalıştırmaları yazar:

• artifacts/test-report.json (tek gerçek kaynağı; sonuçlar/süreler/hafıza/baseline karşılaştırma durumu + stdout/stderr/loglar/traceback'ler; bkz. tests[].output_full)
• artifacts/test-report.html (insan panosu; JSON'dan türetilmiş; FBRK_TEST_GENERATE_HTML=1 tarafından kontrol edilir)
• artifacts/test-report.llm.json (LLM-dostu; JSON'dan türetilmiş; ANSI kodları kaldırılmış loglar)

CI her iki artefaktı da yükler (bkz. .github/workflows/pytest.yml):

• test-report.json
• test-report.html

LLM hata ayıklaması için notlar:

• Ham çıktı yerine artifacts/test-report.json veya artifacts/test-report.llm.json tercih edin; bunlar yapılandırılmış başarısızlıklar, loglar, baseline karşılaştırma ve koleksiyon hatalarını içerir.
• HTML, uzun çalışan testleri, worker çökmelerini ve test başına çıktıyı hızlıca taramak için en iyisidir.

Uzak/baseline davranışı:

• ato dev test --llm --baseline <commit> CI test-report.json artefaktını baseline olarak kullanır (gerekli: gh CLI).
• ato dev test --llm --view <commit> --open şu anda yalnızca HTML artefaktını getirir/açar; JSON için gh run download aracılığıyla test-report.json artefaktını indirin.
• ato dev test --reuse --baseline <commit> testleri yeniden çalıştırmadan baseline'a karşı JSON/HTML/LLM'yi yeniden oluşturur.
• ato dev test --keep-open testler bittikten sonra canlı rapor sunucusunu çalışır durumda tutar.

Kullanışlı test-çalıştırıcı ortam değişkenleri (bkz. test/runner/main.py):

• FBRK_TEST_REPORT_INTERVAL (saniye; rapor yenileme hızı)
• FBRK_TEST_LONG_THRESHOLD (saniye; "uzun test" eşiği)
• FBRK_TEST_WORKERS (0 = cpu sayısı, negatif işçi sayısını ölçeklendirir)
• FBRK_TEST_GENERATE_HTML (1/0)
• FBRK_TEST_PERIODIC_HTML (1/0)
• FBRK_TEST_OUTPUT_MAX_BYTES (HTML tarafından kullanılan önizleme çıktısını kısalt; tests[].output_full tam kalır)
• FBRK_TEST_OUTPUT_TRUNCATE_MODE (head veya tail)
• FBRK_TEST_BIND_HOST (orchestrator bağlama host'u; varsayılan 0.0.0.0)
• FBRK_TEST_REPORT_HOST (yazdırılan rapor URL'sinde kullanılan host; varsayılan bağlama host'u)
• FBRK_TEST_PERF_THRESHOLD_PERCENT (varsayılan 0.30)
• FBRK_TEST_PERF_MIN_TIME_DIFF_S (varsayılan 1.0)
• FBRK_TEST_PERF_MIN_MEMORY_DIFF_MB (varsayılan 50.0)

LLM hızlı kullanımı:

• artifacts/test-report.llm.json her zaman oluşturulur (ANSI kaldırılmış, tam testler + loglar).
• ato dev test --llm özlü bir özet + şema + jq ipuçları yazdırır (yalnızca stdout).
• jq tarifleri raporun içinde llm.jq_recipes altında gömülüdür.
• Auto-LLM: ato dev test claude-code/codex-cli/cursor altında çalıştırırken özeti otomatik olarak etkinleştirir.
• FBRK_TEST_LLM=1 veya FBRK_TEST_LLM=0 aracılığıyla açın/kapatın.

ConfigFlags (nasıl kullanılır + nasıl envanter tutulur)

ConfigFlag deponun "ortam değişkenine göre aç-kapat" mekanizmasıdır. Ortam değişkeni adı ConfigFlag(...) parametresinin ilk argümanıdır.

Kullanım:

export SOME_FLAG=1

Depo içindeki tüm ConfigFlags'ları envanter tutun (manuel bir liste tutmaya çalışmak yerine tercih edilir):

ato dev flags

Tam resmi elde etmek istediğinizde ato dev flags kullanmayı tercih edin (türler/varsayılanlar/açıklamalar + çağrı sitesi sayıları bir yerde).

Sık sık kullanacağınız yüksek etkili flaglar:

• Zig derlemesi: ZIG_NORECOMPILE, ZIG_RELEASEMODE
• Çözer hata ayıklaması: SLOG, SVERBOSE_TABLE, SPRINT_START, SMAX_ITERATIONS, SSHOW_SS_IS
• Loglar: COLOR_LOGS, LOG_TIME, LOG_FILEINFO

Geliştirme İş Akışı

1. Zig Değişiklikleri: src/faebryk/core/zig/src/ altındaki dosyaları düzenle -> ato dev compile çalıştır.
2. Profilleme: Bir şey yavaşsa, flamegraph veya istatistik oluşturmak için ato dev profile <command> kullan.

Test

• Ana test giriş noktası: ato dev test --llm.
• CLI davranışını değiştirirseniz, komut yüzeyini uygulayan test/ altına test ekleyin/ayarlayın.

En İyi Uygulamalar

• ConfigFlags Kullan: Deneysel özellikler veya ayrıntılı hata ayıklama için kodu açıklama satırına çevirmek yerine ConfigFlag kullan.
• Sık sık derle: Zig hataları Python araçları tarafından yakalanmayacaktır.