>_ ash

Kontribusi · build · debug

Panduan pengembang

Panduan praktis untuk menyiapkan checkout, memilih Buat target, memahami pembuat rilis, mendiagnosis log runtime, dan menguji instalasi paket asli di VM Tart.

Siapkan rantai alat pengembang

Proyek ini menggunakan Go untuk CLI dan broker, ditambah rantai alat plugin asli dan alat kualitas situs. Di macOS,make configmenggunakan minuman rumahan; di Debian atau Ubuntu menggunakan apt. Ini menginstal Go, Node.js/npm, Python,uv, Rust/Cargo, serta serat dan alat keamanan proyek. Modul Go pada repositori menentukan versi Go yang diharapkan oleh build.

make config

Penginstal macOS pengemasan juga menggunakan Alat Baris Perintah Xcode Apple. Pengemasan Linux.debDan.rpmartefak membutuhkan Ruby,fpm, dan utilitas pengemasan RPM. Skrip penyiapan menginstal prasyarat umum, namun alat pengemasan khusus platform mungkin masih diperlukan untuk build rilis.

Untuk detail penyiapan pertama kali dan ekspektasi kontribusi, lihatKONTRIBUSI.md.

Alur kerja pengembangan sehari-hari

Untuk perubahan kode normal, jalankan pengujian terfokus saat melakukan iterasi, lalu jalankan lint dan gerbang pengujian yang diperlukan repositori sebelum menyelesaikan:

go test ./internal/app -run 'TestName'
make check-static
make check-security
make test

Kebanyakan membuat target digunakanscripts/dev/run-quiet.sh: langkah sukses cetak satu ringkasokbaris, sementara langkah yang gagal mencetak keluaran yang diambil. Awali target denganV=1untuk mengalirkan keluaran lengkapnya saat dijalankan:

make V=1 lint
make V=1 test
make V=1 verify

V=1kontrol Buat pembungkus yang tenang. Itu terpisah dariASH_VERBOSE, yang mengaktifkan diagnostik runtime diAshprogram.

Buat referensi target

make pre-push
Menjalankan pemeriksaan statis, pemindaian keamanan dan dependensi, pemindaian rahasia, serta pengujian pada commit yang benar-benar akan dikirim. make config memasang hook repositori. Hook lokal dapat dilewati dan bukan pemeriksaan yang diwajibkan server.
make lint
Memeriksa katalog pelokalan, sintaksis shell untuk penginstal situs, alur kerja YAML, lint/format Python, Markdown, lint plugin, dan Go lint.
make test
Membangun dan menguji plugin asli, lalu menjalankannyago test ./....
make verify-ci
Menjalankan pemeriksaan pre-push sebelum membuat tag nightly. CI artefak yang dipicu tag tidak mengulangi pemeriksaan kode sumber.
make verify
Menjalankan gerbang kualitas lokal secara lengkap: lint, pengujian, pengujian balapan, cakupan, dokter hewan, analisis statis, keamanan, pemindaian rahasia, fuzzing, dan tolok ukur.
make test-race
Menjalankan pengujian Go dengan detektor balapan.
make test-cover
Menuliscoverage.outdan memeriksa totalnyaCOVERAGE_MIN(60% secara default).
make test-fuzz
Menjalankan pengujian fuzz aplikasi untukFUZZ_TIME(10 detik secara default).
make security
Menjalankan gosec, govulncheck, serta audit dependensi npm, Cargo, dan Python.
make build
Menjalankan lint dan menguji, membuat dan menginstal plugin asli, serta buildashplusash-brokerdi bawah~/.local/bin.
make install
Menjalankan pengujian, serat,gosec, dan plugin build/install, buat kedua biner, lalu jalankanash install --shell bash --shell-integration --overwrite. Gunakan saat Anda ingin memperbarui integrasi Bash lokal.
make plugins-build,plugins-test,plugins-lint
Bangun, uji, atau lint setiap plugin di bawahinternal/app/ash_bootstrap/plugins_src.make plugins-cleanmenghapus keluaran pembuatan plugin lokal.
make site-locales
Menghasilkan halaman yang diterjemahkan dan menyegarkan peta situs. Menggunakanmake site-locales SITE_LOCALES="zh-TW lb_LU"untuk memilih lokal.

make allberjalanverifykemudianinstall. Resep target lengkap dan variabel yang dapat diganti ada difile make.

Pembuat plugin

Plugin adalah executable mandiri dengan kontrak yang tidak bergantung pada bahasa. Plugin Makefiles memilih rantai alat setiap plugin; build lokal menargetkan host secara default. Rilis build lulusPLUGIN_TARGET_GOOSDanPLUGIN_TARGET_GOARCHjadi Rust dan biner plugin non-Go lainnya cocok dengan artefak rilis.

Menggunakanmake plugins-builduntuk membangunnyabin/plugins,make plugins-testuntuk menjalankan tes mereka, danmake plugins-installuntuk menyalinnya ke direktori plugin pengguna. Lihatkontrak plugin aslisebelum menambahkan atau mengubah plugin.

Rilis pembangun dan artefak

Setelah pemeriksaan kualitas, GitHub menjalankan make release-artifacts di Linux. Satu tugas Ubuntu mengompilasi silang arsip macOS Intel dan Apple Silicon untuk Homebrew, tanpa runner macOS atau pemasang .pkg. Target macOS mengecualikan semua plugin Rust, termasuk flip_a_coin, juga pada build lokal. Linux dan FreeBSD tetap menyertakan plugin Rust.

CI memvalidasi isi arsip macOS dan arsitektur Mach-O tanpa menjalankan binernya. Linux dan FreeBSD tetap menguji eksekusi arsip yang diekstrak; paket dan integrasi shell tidak dipasang. Untuk membangun macOS di Linux: make release-artifacts RELEASE_TARGET_OSES=darwin RELEASE_TARGET_ARCHES="amd64 arm64" RELEASE_MACOS_PKG=0 RELEASE_VERSION=v1.2.3. make release tetap membuat .pkg lokal di macOS tanpa mengirim biner lokal ke CI.

Untuk pembuatan artefak lokal, tentukan OS target, arsitektur, dan versi secara eksplisit:

make release-artifacts \
  RELEASE_TARGET_OSES=linux \
  RELEASE_TARGET_ARCHES="arm64 amd64" \
  RELEASE_VERSION=v1.2.3

release-artifactsmembangun dan memvalidasi format yang didukung untuk target tersebut. Standarnya adalah OS host (auto) dan keduanyaamd64 arm64; Penerbitan FreeBSD terbatas padaamd64. Artefak tenggelamdist/release. Untuk build biner/plugin tunggal, gunakanmake release-build-one RELEASE_GOOS=linux RELEASE_ARCH=arm64 RELEASE_VERSION=v1.2.3.

make versionmenjalankan pemeriksaan rilis dan membuat artefak tanpa memublikasikannya. Sebaliknya,make releaseadalah alur kerja penerbitan: memerlukan macOS, pohon kerja yang bersih dan identitas Git yang dikonfigurasi, membuat catatan rilis, membuat/mendorong referensi rilis, dan mengawasi alur kerja GitHub. Saluran defaultnya adalah beta; pilih stabil atau malam denganCHANNEL=stableatauCHANNEL=nightly. Catatan rilis yang dihasilkan memerlukanASH_AI_ENDPOINTDanASH_AI_MODEL, kecuali catatan disertakanRELEASE_NOTES_INPUT.

Bacarilis alur kerjaDanrilis panduan rahasiasebelum diterbitkan.

Pencatatan waktu proses yang panjang

ASH_VERBOSEmengaktifkan logging debug JSON terstruktur dan mencetak dasbor eksekusi sebelumnyaAshkeluar. Nilai yang diterima adalah1,y,yes,true,on, Dandebug, tidak peka huruf besar-kecil. Dasbor merangkum waktu tahapan, jumlah panggilan alat, total token bila tersedia, dan total waktu nyata.

ASH_VERBOSE=1 ash "investigate this error"

ASH_VERBOSE=1 \
ASH_LOG_FILE="$HOME/.local/state/ash/debug.jsonl" \
ASH_LOG_MAX_BYTES=10485760 \
ash "investigate this error"

KapanASH_LOG_FILEdiatur, catatan log JSON verbose ditulis ke jalur itu; direktori induk dibuat sesuai kebutuhan.ASH_LOG_MAX_BYTESmengontrol rotasi dan default ke1048576byte (1 MiB). Tanpa file log eksplisit, keluaran debug menggunakan penulis diagnostik proses. Jaga kerahasiaan log dan tinjau sebelum membagikannya.

Hal ini berbeda dengan MakeV=1: menggunakanV=1untuk melihat keluaran perintah build/test danASH_VERBOSE=1untuk mendiagnosis suatuAshpemanggilan waktu proses.

Temukan sumber catatan log

Setiap panggilan logging Ash memiliki kolom EID yang unik. Salin EID dari data JSON dan cari literalnya di sumber Go untuk menemukan situs panggilan:

rg '"EID", "EpbG2YtZ"' internal/

Misalnya, panggilan sumber mencatat pesan dan EID bersama dengan konteks terstruktur. EID adalah pengidentifikasi stabil untuk lokasi log: jangan terjemahkan, ganti nama, atau gunakan kembali. Debug logger dan perilaku rotasinya diimplementasikaninternal/aplikasi/debuglog.go.

Uji penginstalan paket asli dengan vm.sh

scripts/vm.sh mendeteksi OS host dan memilih backend VM: Tart di Apple Silicon macOS, atau QEMU/KVM di x86_64 Linux. Kedua backend dapat menguji APT di Ubuntu/Debian dan DNF di Fedora/Rocky Linux. Tart di macOS juga dapat menguji paket MacOS Homebrew; Host Linux tidak dapat menjalankan macOS guest sehingga tidak dapat menguji jalur tersebut.

persyaratan host macOS

Gunakan Apple Silicon Mac yang menjalankan macOS 13 atau lebih baru, dengan Tart terinstal, akses jaringan ke image VM dan repositori Ash, serta ruang disk yang cukup untuk VM. Instal Tart dengan Homebrew jika diperlukan:

brew install openai/tools/tart

Prasyarat host Linux

Gunakan host Linux x86_64 dengan virtualisasi perangkat keras yang diaktifkan dan akun pengguna yang dapat membaca dan menulis/dev/kvm(umumnya dengan bergabung dengankvmgrup dan masuk lagi). Instal QEMU/KVM, cloud-image-utils untukcloud-localds, curl, alat klien OpenSSH, dan Python 3. Contoh perintah paket:

# Debian or Ubuntu
sudo apt-get install qemu-system-x86 qemu-utils cloud-image-utils curl openssh-client python3

# Fedora or Rocky Linux
sudo dnf install qemu-kvm qemu-img cloud-utils curl openssh-clients python3

Backend Linux meluncurkan image cloud x86_64 Ubuntu, Debian, Fedora, atau Rocky dengan QEMU/KVM dan cloud-init. Ia menggunakan jaringan mode pengguna QEMU dengan SSH yang diteruskan ke localhost; tidak diperlukan pengaturan jaringan libvirt. Itu tidak menjalankan tamu macOS, tidak menguji Homebrew di macOS, dan saat ini memerlukan host Linux x86_64. Arch dan FreeBSD bukan target yang didukung.

Jalankan tes paket

Mode otomatis adalah default dan menghapus VM setelah pengujian. Platform default mengikuti host: macOS memilihmacos, Linux memilihubuntu. Pilih platform dan mode lain yang didukung secara eksplisit. Saluran paket defaultnya adalahbeta; menggunakan--channel nightly,--channel beta, atau--channel releaseuntuk memilih satu.--channel stableadalah alias untukrelease.

scripts/vm.sh --platform macos --mode interactive
scripts/vm.sh --platform ubuntu --channel nightly --mode automated
scripts/vm.sh --platform debian --mode interactive
scripts/vm.sh --platform fedora --mode automated
scripts/vm.sh --platform rocky --mode interactive

Mode interaktif membuat VM yang terinstal tetap berjalan untuk pengujian manual. Di macOS, jalankan perintah tart exec -it yang dicetak di terminal untuk membuka shell tamu. Keluar dari shell itu membuat VM tetap berjalan; mematikan tamu atau menghentikannya dari tuan rumah. Untuk menghentikan dan menghapus VM Tart yang disimpan, gunakan:

tart stop VM_NAME && tart delete VM_NAME

Di Linux, skrip mencetak perintah SSH dan perintah stop; hentikan VM dan hapus statusnya dengan:

scripts/vm.sh --stop VM_NAME

Mode otomatis menjalankan pemeriksaan asap instalasi dan pengaturan shell, lalu menghentikan dan menghapus VM. Gambar dasar yang diunduh tetap disimpan dalam cache. Gambar tart dapat diubah denganASH_TEST_VM_IMAGE; URL cloud-image Linux dapat diganti denganASH_TEST_QEMU_IMAGE. Gambar Linux di-cache di bawah${XDG_CACHE_HOME:-~/.cache}/ash/vm-images, dan disk VM interaktif serta kunci SSH disimpan di bawah${XDG_STATE_HOME:-~/.local/state}/ash/vm. MengaturASH_TEST_VM_CACHE_DIRatauASH_TEST_VM_STATE_DIRuntuk mengubah lokasi tersebut.

Agar tamu dapat terhubung ke layanan AI yang sama dengan host, ekspor yang diperlukanASH_AI_*variabel sebelum menjalankan skrip, misalnyaASH_AI_ENDPOINT,ASH_AI_MODEL, dan, bila diperlukan,ASH_AI_AUTH_TOKEN. Nilai yang diekspor diteruskan ke tamu; variabel shell yang tidak diekspor tidak. VM interaktif mempertahankan kredensial ini di profil tamu dengan mode0600; Disk VM Linux tidak dienkripsi, jadi lindungi direktori status dan hentikan/hapus VM setelah selesai.

Melihatscripts/vm.sh --helpuntuk prasyarat backend saat ini, platform yang didukung, dan opsi.

Panduan sumber proyek

  • Panduan berkontribusi— penyiapan, pengujian, ekspektasi rilis, dan catatan CI.
  • Arsitektur— tata letak proyek dan subsistem runtime.
  • BACA SAYA— produk, instalasi, konfigurasi, dan referensi lingkungan.
  • file make— resep target resmi dan variabel build.
  • Alur kerja GitHub— CI, pembuat platform, dan otomatisasi penerbitan.