>_ ash

Contribute · build · debug

Entwécklerguide

E praktesche Guide fir e Kasse opzestellen, Ziler ze wielen, Verëffentlechungsbuilder ze verstoen, Runtime Logbicher ze diagnostéieren, an native Package Installatiounen an Tart VMs ze testen.

Setzt den Entwéckler Toolchain op

De Projet benotzt Go fir de CLI a Broker, plus gebierteg Plugin Toolchains a Site-Qualitéit Tools. Op macOS,make configbenotzt Homebrew; op Debian oder Ubuntu benotzt et apt. Et installéiert Go, Node.js/npm, Python,uv, Rust / Cargo, an de Projet's Lint a Sécherheetsinstrumenter. De Go Modul vum Repository spezifizéiert d'Go Versioun, déi vum Build erwaart gëtt.

make config

Packaging macOS Installateuren benotzt och Apple's Xcode Command Line Tools. Verpakung Linux.deban.rpmArtefakte brauche Ruby,fpm, an RPM Verpakung Utilities. De Setup-Skript installéiert déi gemeinsam Viraussetzungen, awer plattformspezifesch Verpackungstools kënnen nach ëmmer gebraucht ginn fir Release Builds.

Fir éischte Kéier Setup Detailer a Bäitrag Erwaardungen, kucktCONTRIBUTING.md.

Alldeeglech Entwécklung Workflow

Fir eng normal Code Ännerung, lafen déi fokusséiert Tester beim Iteréieren, lafen dann déi erfuerderlech Lint an Test Gates vum Repository virum Enn:

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

Déi meescht Maacht Ziler benotzenscripts/dev/run-quiet.sh: erfollegräich Schrëtt Drécken eng präzisokLinn, wärend gescheitert Schrëtt hir ageholl Ausgang drécken. Präfix engem Zil matV=1fir säi komplette Output ze streamen wéi se leeft:

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

V=1kontrolléiert Make's roueg wrapper. Et ass getrennt vunASH_VERBOSE, déi Runtime Diagnostik amAshProgramm.

Zilreferenz maachen

make pre-push
Féiert statesch Kontrollen, Sécherheets- an Ofhängegkeetsscannen, Geheimnisserkennung an Tester op de geneeë Commiten aus, déi geschéckt ginn. make config installéiert de Repository-Hook. Lokal Hooks kënnen ëmgaange ginn a sinn net vum Server erzwongen.
make lint
Kontrolléiert Lokaliséierungskataloge, Shell Syntax fir de Site Installateur, Workflow YAML, Python Lint / Format, Markdown, Plugin Lint, a Go Lint.
make test
Baut a testt gebierteg Plugins, leeft danngo test ./....
make verify-ci
Féiert d'Pre-Push-Kontroll virun der Erstellung vum Nightly-Tag aus. D'Tag-getriggert Artefakt-CI widderhëlt keng Quellcodekontrollen.
make verify
Leeft déi voll lokal Qualitéitspaart: Lint, Tester, Race Tester, Ofdeckung, Veterinär, statesch Analyse, Sécherheet, Geheimscannen, Fuzzing, a Benchmarks.
make test-race
Leeft Go Tester mam Renndetektor.
make test-cover
Schreiftcoverage.outa kontrolléiert den Total géintCOVERAGE_MIN(60% par défaut).
make test-fuzz
Leeft Applikatioun Fuzz Tester firFUZZ_TIME(Standard 10 Sekonnen).
make security
Féiert gosec, govulncheck an npm-, Cargo- a Python-Ofhängegkeetsauditen aus.
make build
Leeft Lint an Tester, baut an installéiert gebierteg Plugins, a bautashplussash-brokerënner~/.local/bin.
make install
Fuert Tester, Lëntgen,gosec, a Plugin bauen / installéieren, baut béid Binären, da leeftash install --shell bash --shell-integration --overwrite. Benotzt et wann Dir wëllt déi lokal Bash Integratioun aktualiséieren.
make plugins-build,plugins-test,plugins-lint
Bauen, testen oder lint all Plugin ënnerinternal/app/ash_bootstrap/plugins_src.make plugins-cleanläscht de lokalen Plugin Build Output.
make site-locales
Generéiert iwwersat Säiten an erfrëscht de Sitemap. Benotztmake site-locales SITE_LOCALES="zh-TW lb_LU"locales auswielen.

make allleeftverifyan danninstall. Déi komplett Zil Rezepter an overridable Verännerlechen sinn an derMaacht Datei.

Plugin Builder

Plugins si Standalone ausführbar mat engem Sproochonofhängege Kontrakt. De Plugin Makefiles wielt all Plugin Toolchain; lokal Builds zielen den Host par défaut. Fräisetzung baut PassePLUGIN_TARGET_GOOSanPLUGIN_TARGET_GOARCHalso Rust an aner Net-Go Plugin Binären passen dem Release Artefakt.

Benotztmake plugins-buildfir se anzebauenbin/plugins,make plugins-testhir Tester ze lafen, anmake plugins-installfir se an de Benotzer Plugin Verzeechnes ze kopéieren. Kuckt degebierteg Plugin Kontraktier e Plugin derbäigesat oder geännert gëtt.

Fräisetzung Builder an artifacts

No de Qualitéitskontrolle leeft make release-artifacts op Linux. Een Ubuntu-Job baut d'macOS-Archive fir Intel an Apple Silicon fir Homebrew, ouni macOS-Runner oder .pkg-Installateuren. macOS-Ziler schléissen all Rust-Plugins aus, och flip_a_coin a lokal Builds. Linux a FreeBSD behalen d'Rust-Plugins.

CI kontrolléiert den Inhalt vun de macOS-Archiven an d'Mach-O-Architekturen, féiert d'Binärdateien awer net aus. Linux a FreeBSD behalen d'Lafzäittester vun den ausgepaakten Archiven; Packagen a Shell-Integratioune ginn net installéiert. Fir macOS op Linux ze bauen: make release-artifacts RELEASE_TARGET_OSES=darwin RELEASE_TARGET_ARCHES="amd64 arm64" RELEASE_MACOS_PKG=0 RELEASE_VERSION=v1.2.3. make release erstellt nach ëmmer e lokale .pkg op macOS, ouni lokal Binärdateien un CI ze schécken.

Fir lokal Artefakt Builds, spezifizéiert d'Zil OS, d'Architektur an d'Versioun explizit:

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

release-artifactsbaut a validéiert d'Formater déi fir dat Zil ënnerstëtzt ginn. D'Defaults sinn Host OS (auto) a béidamd64 arm64; FreeBSD Verëffentlechung ass limitéiert opamd64. Artefakte ginn ënnerdist/release. Fir eng eenzeg binär / Plugin bauen, benotzenmake release-build-one RELEASE_GOOS=linux RELEASE_ARCH=arm64 RELEASE_VERSION=v1.2.3.

make versionleeft d'Verëffentlechungskontrollen a baut Artefakte ouni se ze publizéieren. Am Géigesaz,make releaseass e Verëffentlechungs-Workflow: et erfuerdert macOS, e propperen Aarbechtsbaum a konfiguréiert Git Identitéit, generéiert Verëffentlechungsnotizen, erstellt / dréckt Verëffentlechungsreferenzen, a kuckt de GitHub Workflow. Säi Standardkanal ass Beta; wielt stabil oder Nightly matCHANNEL=stableoderCHANNEL=nightly. Generéiert Verëffentlechungsnotizen erfuerderlechASH_AI_ENDPOINTanASH_AI_MODEL, ausser Notizen sinn mat geliwwertRELEASE_NOTES_INPUT.

Liest deFräisetzung WorkflowanFräisetzung Geheimnisser Guidevirun der Verëffentlechung.

Verbose Runtime Logbuch

ASH_VERBOSEaktivéiert strukturéiert JSON Debug Logging a dréckt en Ausféierungsdashboard virAsherausgoen. Akzeptéiert Wäerter sinn1,y,yes,true,on,an andebug, case-onsensibel. D'Dashboard resüméiert d'Bühn Timings, Tool-Call Zuel, Tokentotalen wann verfügbar, a Gesamt Echtzäit.

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"

WéiniASH_LOG_FILEgesat ass, verbose JSON Log records ginn op dee Wee geschriwwe; den Elterenverzeichnis gëtt erstallt wéi néideg.ASH_LOG_MAX_BYTESkontrolléiert Rotatioun an Default op1048576bytes (1 MiB). Ouni eng explizit Logdatei benotzt Debug-Output de Prozessdiagnostesche Schrëftsteller. Halt d'Logbicher privat a iwwerpréift se ier Dir deelt.

Dëst ass ënnerscheet vu Make'sV=1: benotzenV=1ze gesinn bauen / Test Kommando Ausgang anASH_VERBOSE=1ze diagnostizéieren anAshRuntime Opruff.

Fannt d'Quell vun engem Logbuch

All Ash Logbuch huet en eenzegaartegt EID Feld. Kopéiert d'EID vum JSON-Rekord a sicht no sengem wuertwiertlechen an der Go Quell fir den Uruff Site ze fannen:

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

Zum Beispill registréiert e Quellruff de Message an d'EID zesumme mam strukturéierte Kontext. EIDs si stabil Identifizéierer fir Logplazen: iwwersetzen, ëmbenennen oder nei benotzen se net. Den Debug Logger a säi Rotatiounsverhalen ginn anintern/app/debuglog.go.

Test native Package installéiert mat vm.sh

scripts/vm.sh erkennt den Host OS a wielt e VM Backend: Tart op Apple Silicon macOS, oder QEMU/KVM op x86_64 Linux. Béid Backends kënnen APT op Ubuntu / Debian an DNF op Fedora / Rocky Linux testen. Tart op macOS kann och de macOS Homebrew Package testen; Linux Hosts kënnen net macOS Gäscht lafen an dofir kënnen dee Wee net testen.

macOS Host Viraussetzungen

Benotzt en Apple Silicon Mac deen macOS 13 oder méi spéit leeft, mat Tart installéiert, Netzzougang zum VM Bild an Ash Repository, a genuch Disk Space fir de VM. Installéiert Tart mat Homebrew wann néideg:

brew install openai/tools/tart

Linux Host Viraussetzunge

Benotzt en x86_64 Linux Host mat Hardwarevirtualiséierung aktivéiert an e Benotzerkont dee liesen a schreiwen kann/dev/kvm(allgemeng andeems Dir dekvmGrupp an erëm aloggen). Installéiert QEMU / KVM, Cloud-image-utils fircloud-localds, Curl, OpenSSH Client Tools a Python 3. Beispill Package Kommandoen:

# 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

De Linux Backend lancéiert x86_64 Ubuntu, Debian, Fedora oder Rocky Cloud Biller mat QEMU / KVM a Cloud-init. Et benotzt QEMU Benotzer-Modus Netzwierker mat SSH weidergeleet op localhost; kee libvirt Netzwierk Setup ass néideg. Et leeft net macOS Gäscht, testt net Homebrew op macOS, a erfuerdert de Moment en x86_64 Linux Host. Arch a FreeBSD sinn net ënnerstëtzt Ziler.

Fuert e Package Test

Automatiséierte Modus ass de Standard an läscht de VM nom Test. D'Standardplattform follegt dem Host: macOS wieltmacos, Linux wieltubuntu. Wielt eng aner ënnerstëtzt Plattform a Modus explizit. De Package Kanal ass Standard opbeta; benotzen--channel nightly,--channel beta, oder--channel releasefir een ze wielen.--channel stableass en Alias ​​​​firrelease.

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

Interaktive Modus léisst den installéierten VM fir manuell Testen lafen. Op macOS, fuert de gedréckte tart exec -it Kommando an engem Terminal fir eng Gaascht Shell opzemaachen. Ausgaang vun dëser Shell léisst de VM lafen; de Gaascht zoumaachen oder et vum Host stoppen. Fir en erhale Tart VM ze stoppen an ze läschen, benotzt:

tart stop VM_NAME && tart delete VM_NAME

Op Linux dréckt de Skript en SSH Kommando an e Stop Kommando; Stop de VM a läscht säin Zoustand mat:

scripts/vm.sh --stop VM_NAME

Automatiséierte Modus fiert d'Installatioun an d'Shell-Setup Rauchkontrollen, stoppt dann an läscht de VM. Erofgelueden Basisbiller bleiwen am cache. Tart Biller kënne geännert ginn matASH_TEST_VM_IMAGE; Linux Cloud-Bild URLen kënnen iwwerschriwwe ginnASH_TEST_QEMU_IMAGE. Linux Biller sinn ënner cache${XDG_CACHE_HOME:-~/.cache}/ash/vm-images, an interaktiv VM Disken an SSH Schlësselen ginn ënner gehal${XDG_STATE_HOME:-~/.local/state}/ash/vm. SetztASH_TEST_VM_CACHE_DIRoderASH_TEST_VM_STATE_DIRdës Plazen z'änneren.

Fir de Gaascht mam selwechten AI Service wéi den Host ze verbannen, exportéiert déi néidegASH_AI_*Variabelen ier Dir de Skript leeft, zum BeispillASH_AI_ENDPOINT,ASH_AI_MODELan, wann néideg,ASH_AI_AUTH_TOKEN. Exportéiert Wäerter ginn un de Gaascht weidergeleet; onexportéiert Shell Variablen sinn net. Interaktiv VMs behalen dës Umeldungsinformatiounen am Gaaschtprofil mat Modus0600; Linux VM Disks sinn net verschlësselte, also schützt de Staatsverzeichnis a stoppt / läscht de VM wann et fäerdeg ass.

Kucktscripts/vm.sh --helpfir déi aktuell Backend Viraussetzungen, ënnerstëtzt Plattformen, an Optiounen.

Projet Quell Guiden

  • Bäitrag Guide- Setup, Tester, Verëffentlechungserwaardungen, an CI Notizen.
  • Architektur- Projet Layout a Runtime Subsystemer.
  • VIRLIESEN- Produkt, Installatioun, Konfiguratioun an Ëmfeld Referenz.
  • Maacht Datei- autoritär Zilrezepter a Verännerlechen bauen.
  • GitHub Workflows- CI, Plattform Builder, a Verëffentlechungsautomatiséierung.