>_ ash

Contribuir · compilar · depurar

Guía para desarrolladores

Una guía práctica para configurar un pago, elegir objetivos, comprender los creadores de versiones, diagnosticar registros de tiempo de ejecución y probar instalaciones de paquetes nativos en máquinas virtuales Tart.

Configurar la cadena de herramientas del desarrollador

El proyecto utiliza Go para CLI y broker, además de cadenas de herramientas de complementos nativos y herramientas de calidad de sitio. En MacOS,make configutiliza cerveza casera; en Debian o Ubuntu usa apt. Instala Go, Node.js/npm, Python,uv, Rust/Cargo y las herramientas de seguridad y pelusa del proyecto. El módulo Go del repositorio especifica la versión de Go esperada por la compilación.

make config

Los instaladores de macOS también utilizan las herramientas de línea de comandos Xcode de Apple. Empaquetado de Linux.deby.rpmlos artefactos requieren Ruby,fpmy utilidades de empaquetado RPM. El script de instalación instala los requisitos previos comunes, pero es posible que aún se necesiten herramientas de empaquetado específicas de la plataforma para las versiones de lanzamiento.

Para obtener detalles sobre la configuración inicial y las expectativas de contribución, consulteCONTRIBUYENDO.md.

Flujo de trabajo de desarrollo diario

Para un cambio de código normal, ejecute las pruebas enfocadas mientras itera, luego ejecute las puertas de prueba y pelusa requeridas por el repositorio antes de terminar:

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

La mayoría de los objetivos hacen usoscripts/dev/run-quiet.sh: pasos exitosos imprime uno concisooklínea, mientras que los pasos fallidos imprimen su salida capturada. Prefije un objetivo conV=1para transmitir su salida completa mientras se ejecuta:

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

V=1controla el envoltorio silencioso de Make. esta separado deASH_VERBOSE, que permite realizar diagnósticos en tiempo de ejecución en elAshprograma.

Hacer referencia objetivo

make pre-push
Ejecuta comprobaciones estáticas, análisis de seguridad y dependencias, detección de secretos y pruebas en los commits exactos que se van a enviar. make config instala el hook del repositorio. Los hooks locales se pueden omitir y no son una comprobación impuesta por el servidor.
make lint
Comprueba los catálogos de localización, la sintaxis del shell para el instalador del sitio, el flujo de trabajo YAML, el formato/pelusa de Python, Markdown, el complemento pelusa y Go pelusa.
make test
Crea y prueba complementos nativos, luego los ejecutago test ./....
make verify-ci
Ejecuta la puerta pre-push antes de crear la etiqueta nightly. La CI de artefactos activada por etiquetas no repite las comprobaciones del código fuente.
make verify
Ejecuta todo el control de calidad local: pelusa, pruebas, pruebas de carrera, cobertura, veterinario, análisis estático, seguridad, escaneos secretos, fuzzing y puntos de referencia.
make test-race
Ejecuta pruebas de Go con el detector de carreras.
make test-cover
escribecoverage.outy compara el total conCOVERAGE_MIN(60% por defecto).
make test-fuzz
Ejecuta pruebas de fuzz de aplicaciones paraFUZZ_TIME(10 segundos por defecto).
make security
Ejecuta gosec, govulncheck y auditorías de dependencias de npm, Cargo y Python.
make build
Ejecuta lint y prueba, compila e instala complementos nativos y compilaashmásash-brokerbajo~/.local/bin.
make install
Ejecuta pruebas, pelusa,gosecy la compilación/instalación del complemento, compila ambos binarios y luego ejecutaash install --shell bash --shell-integration --overwrite. Úselo cuando desee actualizar la integración local de Bash.
make plugins-build,plugins-test,plugins-lint
Cree, pruebe o elimine cada complemento eninternal/app/ash_bootstrap/plugins_src.make plugins-cleanelimina el resultado de la compilación del complemento local.
make site-locales
Genera páginas traducidas y actualiza el mapa del sitio. Usarmake site-locales SITE_LOCALES="zh-TW lb_LU"para seleccionar configuraciones regionales.

make allcorreverifyy luegoinstall. Las recetas de destino completas y las variables anulables se encuentran en laArchivo Make.

Constructores de complementos

Los complementos son ejecutables independientes con un contrato independiente del idioma. El complemento Makefiles selecciona la cadena de herramientas de cada complemento; Las compilaciones locales se dirigen al host de forma predeterminada. Pase de versiones de lanzamientoPLUGIN_TARGET_GOOSyPLUGIN_TARGET_GOARCHpor lo que Rust y otros binarios de complementos que no son de Go coinciden con el artefacto de lanzamiento.

Usarmake plugins-buildpara construirlos enbin/plugins,make plugins-testpara ejecutar sus pruebas, ymake plugins-installpara copiarlos en el directorio de complementos del usuario. Ver elcontrato de complemento nativoantes de agregar o cambiar un complemento.

Lanzar constructores y artefactos

Tras los controles de calidad, GitHub ejecuta make release-artifacts en Linux. Un trabajo Ubuntu compila los archivos macOS de Intel y Apple Silicon para Homebrew, sin ejecutores macOS ni instaladores .pkg. Los destinos macOS excluyen todos los complementos Rust, incluido flip_a_coin, incluso en compilaciones locales. Linux y FreeBSD conservan los complementos Rust.

CI valida el contenido de los archivos macOS y las arquitecturas Mach-O, pero no ejecuta sus binarios. Linux y FreeBSD conservan pruebas de ejecución de los archivos extraídos; no se instalan paquetes ni se configura la integración del shell. Para compilar macOS en Linux: make release-artifacts RELEASE_TARGET_OSES=darwin RELEASE_TARGET_ARCHES="amd64 arm64" RELEASE_MACOS_PKG=0 RELEASE_VERSION=v1.2.3. make release sigue creando un .pkg local en macOS y no transfiere los binarios locales a CI.

Para compilaciones de artefactos locales, especifique explícitamente el sistema operativo, la arquitectura y la versión de destino:

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

release-artifactsconstruye y valida los formatos admitidos para ese destino. Los valores predeterminados son el sistema operativo host (auto) y ambosamd64 arm64; La publicación de FreeBSD está limitada aamd64. Los artefactos se hundendist/release. Para una única compilación binaria/complemento, utilicemake release-build-one RELEASE_GOOS=linux RELEASE_ARCH=arm64 RELEASE_VERSION=v1.2.3.

make versionejecuta las comprobaciones de lanzamiento y crea artefactos sin publicarlos. En contraste,make releasees un flujo de trabajo de publicación: requiere macOS, un árbol de trabajo limpio y una identidad Git configurada, genera notas de la versión, crea/impulsa referencias de versiones y observa el flujo de trabajo de GitHub. Su canal predeterminado es beta; seleccione estable o nocturno conCHANNEL=stableoCHANNEL=nightly. Las notas de la versión generadas requierenASH_AI_ENDPOINTyASH_AI_MODEL, a menos que se proporcionen notas conRELEASE_NOTES_INPUT.

Lea elflujo de trabajo de lanzamientoyguía de liberación de secretosantes de publicar.

Registro detallado en tiempo de ejecución

ASH_VERBOSEpermite el registro de depuración JSON estructurado e imprime un panel de ejecución antesAshsalidas. Los valores aceptados son1,y,yes,true,on, ydebug, sin distinguir entre mayúsculas y minúsculas. El panel resume los tiempos de las etapas, el recuento de llamadas a herramientas, los totales de tokens cuando estén disponibles y el tiempo total en tiempo real.

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"

CuandoASH_LOG_FILEestá configurado, los registros de registro JSON detallados se escriben en esa ruta; el directorio principal se crea según sea necesario.ASH_LOG_MAX_BYTEScontrola la rotación y por defecto1048576bytes (1 MiB). Sin un archivo de registro explícito, la salida de depuración utiliza el escritor de diagnóstico de procesos. Mantenga los registros privados y revíselos antes de compartirlos.

Esto es distinto del de Make.V=1: usarV=1para ver el resultado del comando de compilación/prueba yASH_VERBOSE=1para diagnosticar unAshinvocación en tiempo de ejecución.

Encontrar el origen de un registro

Cada llamada de registro Ash tiene un campo EID único. Copie el EID del registro JSON y busque su literal en la fuente Go para encontrar el sitio de la llamada:

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

Por ejemplo, una llamada de origen registra el mensaje y el EID junto con el contexto estructurado. Los EID son identificadores estables para ubicaciones de registros: no los traduzca, les cambie el nombre ni los reutilice. El registrador de depuración y su comportamiento de rotación se implementan eninterno/app/debuglog.go.

Probar las instalaciones del paquete nativo con vm.sh

scripts/vm.sh detecta el sistema operativo host y selecciona un backend de VM: Tart en Apple Silicon macOS o QEMU/KVM en Linux x86_64. Ambos backends pueden probar APT en Ubuntu/Debian y DNF en Fedora/Rocky Linux. Tart en macOS también puede probar el paquete macOS Homebrew; Los hosts Linux no pueden ejecutar invitados macOS y, por lo tanto, no pueden probar esa ruta.

Requisitos previos del host macOS

Utilice una Apple Silicon Mac que ejecute macOS 13 o posterior, con Tart instalado, acceso de red a la imagen de la VM y al repositorio Ash y suficiente espacio en disco para la VM. Instale Tart con Homebrew si es necesario:

brew install openai/tools/tart

Requisitos previos del host Linux

Utilice un host Linux x86_64 con virtualización de hardware habilitada y una cuenta de usuario que pueda leer y escribir/dev/kvm(comúnmente uniéndose alkvmgrupo e iniciar sesión nuevamente). Instale QEMU/KVM, cloud-image-utils paracloud-localds, curl, herramientas cliente OpenSSH y Python 3. Comandos de paquete de ejemplo:

# 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

El backend de Linux lanza imágenes de nube x86_64 de Ubuntu, Debian, Fedora o Rocky con QEMU/KVM y cloud-init. Utiliza redes en modo de usuario QEMU con SSH reenviado a localhost; no se necesita configuración de red libvirt. No ejecuta invitados macOS, no prueba Homebrew en macOS y actualmente requiere un host Linux x86_64. Arch y FreeBSD no son objetivos compatibles.

Ejecute una prueba de paquete

El modo automatizado es el predeterminado y elimina la VM después de la prueba. La plataforma predeterminada sigue al host: macOS seleccionamacos, Linux seleccionaubuntu. Elija explícitamente otra plataforma y modo compatibles. El canal del paquete por defecto esbeta; usar--channel nightly,--channel beta, o--channel releasepara seleccionar uno.--channel stablees un alias pararelease.

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

El modo interactivo deja la máquina virtual instalada ejecutándose para realizar pruebas manuales. En macOS, ejecute el comando impreso tart exec -it en una terminal para abrir un shell invitado. Al salir de ese shell, la máquina virtual se ejecuta; cerrar al invitado o detenerlo desde el anfitrión. Para detener y eliminar una Tart VM retenida, utilice:

tart stop VM_NAME && tart delete VM_NAME

En Linux, el script imprime un comando SSH y un comando de parada; detenga la VM y elimine su estado con:

scripts/vm.sh --stop VM_NAME

El modo automatizado ejecuta comprobaciones de humo de instalación y configuración del shell, luego detiene y elimina la VM. Las imágenes base descargadas permanecen en caché. Las imágenes de tarta se pueden cambiar conASH_TEST_VM_IMAGE; Las URL de imágenes en la nube de Linux se pueden anular conASH_TEST_QEMU_IMAGE. Las imágenes de Linux se almacenan en caché en${XDG_CACHE_HOME:-~/.cache}/ash/vm-imagesy los discos de VM interactivos y las claves SSH se mantienen bajo${XDG_STATE_HOME:-~/.local/state}/ash/vm. ColocarASH_TEST_VM_CACHE_DIRoASH_TEST_VM_STATE_DIRpara cambiar esas ubicaciones.

Para permitir que el invitado se conecte al mismo servicio de IA que el anfitrión, exporte los datos necesariosASH_AI_*variables antes de ejecutar el script, por ejemploASH_AI_ENDPOINT,ASH_AI_MODELy, cuando sea necesario,ASH_AI_AUTH_TOKEN. Los valores exportados se reenvían al huésped; las variables de shell no exportadas no lo son. Las máquinas virtuales interactivas conservan estas credenciales en el perfil de invitado con el modo0600; Los discos de la máquina virtual Linux no están cifrados, por lo tanto, proteja el directorio de estado y detenga o elimine la máquina virtual cuando haya terminado.

Verscripts/vm.sh --helppara conocer los requisitos previos actuales del backend, las plataformas compatibles y las opciones.

Guías de fuentes del proyecto

  • Guía contribuyente– configuración, pruebas, expectativas de lanzamiento y notas de CI.
  • Arquitectura— diseño del proyecto y subsistemas de ejecución.
  • LÉAME— referencia de producto, instalación, configuración y entorno.
  • Archivo Make- recetas de destino autorizadas y variables de compilación.
  • Flujos de trabajo de GitHub– CI, creadores de plataformas y automatización de publicaciones.