>_ ash

Contribuir · construir · depurar

Guia do desenvolvedor

Um guia prático para configurar um checkout, escolher alvos Make, entender os construtores de lançamento, diagnosticar logs de tempo de execução e testar instalações de pacotes nativos em VMs Tart.

Configure o conjunto de ferramentas do desenvolvedor

O projeto usa Go para CLI e corretor, além de conjuntos de ferramentas de plug-ins nativos e ferramentas de qualidade de site. No macOS,make configusa Homebrew; no Debian ou Ubuntu ele usa o apt. Ele instala Go, Node.js/npm, Python,uv, Rust/Cargo e as ferramentas de segurança e fiapos do projeto. O módulo Go do repositório especifica a versão Go esperada pela compilação.

make config

Os instaladores do macOS também usam as ferramentas de linha de comando Xcode da Apple. Empacotando Linux.debe.rpmartefatos requer Ruby,fpme utilitários de empacotamento RPM. O script de configuração instala os pré-requisitos comuns, mas ferramentas de empacotamento específicas da plataforma ainda podem ser necessárias para compilações de lançamento.

Para detalhes de configuração inicial e expectativas de contribuição, consulteCONTRIBUINDO.md.

Fluxo de trabalho diário de desenvolvimento

Para uma alteração normal do código, execute os testes focados durante a iteração e, em seguida, execute o lint e as portas de teste necessários do repositório antes de terminar:

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

A maioria faz com que os alvos usemscripts/dev/run-quiet.sh: etapas bem-sucedidas imprimem uma concisaoklinha, enquanto as etapas com falha imprimem sua saída capturada. Prefixar um alvo comV=1para transmitir sua saída completa enquanto é executado:

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

V=1controla o invólucro silencioso do Make. É separado deASH_VERBOSE, que permite diagnósticos em tempo de execução noAshprograma.

Fazer referência de destino

make pre-push
Executa verificações estáticas, análise de segurança e dependências, detecção de segredos e testes nos commits exatos enviados. make config instala o hook do repositório. Hooks locais podem ser ignorados e não são uma verificação imposta pelo servidor.
make lint
Verifica catálogos de localização, sintaxe de shell para o instalador do site, fluxo de trabalho YAML, lint/formato Python, Markdown, plugin lint e Go lint.
make test
Constrói e testa plug-ins nativos e depois executago test ./....
make verify-ci
Executa a verificação pre-push antes de criar a tag nightly. A CI de artefatos acionada pela tag não repete as verificações do código-fonte.
make verify
Executa todo o portão de qualidade local: lint, testes, testes de corrida, cobertura, veterinário, análise estática, segurança, varreduras secretas, difusão e benchmarks.
make test-race
Executa testes Go com o detector de corrida.
make test-cover
Escrevecoverage.oute compara o totalCOVERAGE_MIN(60% por padrão).
make test-fuzz
Executa testes fuzz de aplicativos paraFUZZ_TIME(10 segundos por padrão).
make security
Executa gosec, govulncheck e auditorias de dependências npm, Cargo e Python.
make build
Executa lint e testes, cria e instala plug-ins nativos e criaashmaisash-brokersob~/.local/bin.
make install
Executa testes, lint,gosec, e compilação/instalação do plugin, cria ambos os binários e, em seguida, executaash install --shell bash --shell-integration --overwrite. Use-o quando pretender atualizar a integração local do Bash.
make plugins-build,plugins-test,plugins-lint
Crie, teste ou lint cada plugin eminternal/app/ash_bootstrap/plugins_src.make plugins-cleanremove a saída de compilação do plugin local.
make site-locales
Gera páginas traduzidas e atualiza o mapa do site. Usarmake site-locales SITE_LOCALES="zh-TW lb_LU"para selecionar localidades.

make allcorreverifye entãoinstall. As receitas de destino completas e as variáveis ​​substituíveis estão noMakefile.

Construtores de plug-ins

Plugins são executáveis ​​independentes com um contrato independente de idioma. O plugin Makefiles seleciona o conjunto de ferramentas de cada plugin; compilações locais têm como alvo o host por padrão. Passe de versões de lançamentoPLUGIN_TARGET_GOOSePLUGIN_TARGET_GOARCHentão Rust e outros binários de plugins não-Go correspondem ao artefato de lançamento.

Usarmake plugins-buildpara construí-los embin/plugins,make plugins-testpara executar seus testes emake plugins-installpara copiá-los para o diretório do plugin do usuário. Veja ocontrato de plugin nativoantes de adicionar ou alterar um plugin.

Liberar construtores e artefatos

Após as verificações de qualidade, o GitHub executa make release-artifacts no Linux. Um trabalho Ubuntu compila os arquivos macOS Intel e Apple Silicon para o Homebrew, sem executores macOS nem instaladores .pkg. Os destinos macOS excluem todos os plugins Rust, incluindo flip_a_coin, mesmo em compilações locais. Linux e FreeBSD mantêm os plugins Rust.

A CI valida o conteúdo dos arquivos macOS e as arquiteturas Mach-O sem executar seus binários. Linux e FreeBSD mantêm testes de execução dos arquivos extraídos; pacotes e integrações do shell não são instalados. Para compilar macOS no Linux: make release-artifacts RELEASE_TARGET_OSES=darwin RELEASE_TARGET_ARCHES="amd64 arm64" RELEASE_MACOS_PKG=0 RELEASE_VERSION=v1.2.3. make release ainda cria um .pkg local no macOS sem enviar os binários locais à CI.

Para compilações de artefatos locais, especifique explicitamente o sistema operacional, a arquitetura e a versão de destino:

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

release-artifactscria e valida os formatos suportados para esse destino. Os padrões são SO host (auto) e ambosamd64 arm64; A publicação do FreeBSD é limitada aamd64. Artefatos desaparecemdist/release. Para uma única compilação binária/plugin, usemake release-build-one RELEASE_GOOS=linux RELEASE_ARCH=arm64 RELEASE_VERSION=v1.2.3.

make versionexecuta as verificações de versão e cria artefatos sem publicá-los. Em contraste,make releaseé um fluxo de trabalho de publicação: requer macOS, uma árvore de trabalho limpa e identidade Git configurada, gera notas de lançamento, cria/envia referências de lançamento e observa o fluxo de trabalho do GitHub. Seu canal padrão é beta; selecione estável ou noturno comCHANNEL=stableouCHANNEL=nightly. As notas de versão geradas exigemASH_AI_ENDPOINTeASH_AI_MODEL, a menos que as notas sejam fornecidas comRELEASE_NOTES_INPUT.

Leia oliberar fluxo de trabalhoeguia de segredos de lançamentoantes de publicar.

Registro de tempo de execução detalhado

ASH_VERBOSEpermite o registro de depuração JSON estruturado e imprime um painel de execução antesAshsaídas. Os valores aceitos são1,y,yes,true,on, edebug, sem distinção entre maiúsculas e minúsculas. O painel resume os tempos dos estágios, a contagem de chamadas de ferramentas, os totais de tokens quando disponíveis e o total em tempo 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"

QuandoASH_LOG_FILEestiver definido, registros de log JSON detalhados serão gravados nesse caminho; o diretório pai é criado conforme necessário.ASH_LOG_MAX_BYTEScontrola a rotação e o padrão é1048576bytes (1 MiB). Sem um arquivo de log explícito, a saída de depuração usa o gravador de diagnóstico do processo. Mantenha os registros privados e revise-os antes de compartilhá-los.

Isso é diferente do Make'sV=1: usarV=1para ver a saída do comando build/test eASH_VERBOSE=1para diagnosticar umAshinvocação de tempo de execução.

Encontre a origem de um registro de log

Cada chamada de registro Ash possui um campo EID exclusivo. Copie o EID do registro JSON e pesquise seu literal na fonte Go para encontrar o site da chamada:

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

Por exemplo, uma chamada de origem registra a mensagem e o EID juntamente com o contexto estruturado. Os EIDs são identificadores estáveis ​​para locais de registro: não os traduza, renomeie ou reutilize. O registrador de depuração e seu comportamento de rotação são implementados eminterno/app/debuglog.go.

Testar instalações de pacotes nativos com vm.sh

scripts/vm.sh detecta o sistema operacional host e seleciona um back-end da VM: Tart no Apple Silicon macOS ou QEMU/KVM no x86_64 Linux. Ambos os backends podem testar APT no Ubuntu/Debian e DNF no Fedora/Rocky Linux. Tart no macOS também pode testar o pacote macOS Homebrew; Os hosts Linux não podem executar convidados macOS e, portanto, não podem testar esse caminho.

Pré-requisitos do host macOS

Use um Apple Silicon Mac executando macOS 13 ou posterior, com Tart instalado, acesso de rede à imagem da VM e ao repositório Ash e espaço em disco suficiente para a VM. Instale o Tart com Homebrew se necessário:

brew install openai/tools/tart

Pré-requisitos de host Linux

Use um host Linux x86_64 com virtualização de hardware habilitada e uma conta de usuário que possa ler e gravar/dev/kvm(normalmente juntando-se aokvmgrupo e fazendo login novamente). Instale QEMU/KVM, utilitários de imagem em nuvem paracloud-localds, curl, ferramentas de cliente OpenSSH e Python 3. Exemplo de comandos de pacote:

# 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

O back-end do Linux lança imagens de nuvem x86_64 Ubuntu, Debian, Fedora ou Rocky com QEMU/KVM e cloud-init. Ele usa rede em modo de usuário QEMU com SSH encaminhado para localhost; nenhuma configuração de rede libvirt é necessária. Ele não executa convidados do macOS, não testa o Homebrew no macOS e atualmente requer um host Linux x86_64. Arch e FreeBSD não são alvos suportados.

Execute um teste de pacote

O modo automatizado é o padrão e remove a VM após o teste. A plataforma padrão segue o host: o macOS selecionamacos, Linux selecionaubuntu. Escolha explicitamente outra plataforma e modo suportados. O padrão do canal do pacote ébeta; usar--channel nightly,--channel beta, ou--channel releasepara selecionar um.--channel stableé um apelido 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

O modo interativo deixa a VM instalada em execução para testes manuais. No macOS, execute o comando impresso tart exec -it em um terminal para abrir um shell convidado. Sair desse shell deixa a VM em execução; desligue o convidado ou interrompa-o no host. Para parar e excluir uma VM Tart retida, use:

tart stop VM_NAME && tart delete VM_NAME

No Linux, o script imprime um comando SSH e um comando stop; pare a VM e remova seu estado com:

scripts/vm.sh --stop VM_NAME

O modo automatizado executa verificações de fumaça de instalação e configuração do shell e, em seguida, interrompe e remove a VM. As imagens base baixadas permanecem em cache. As imagens da torta podem ser alteradas comASH_TEST_VM_IMAGE; URLs de imagem em nuvem do Linux podem ser substituídos porASH_TEST_QEMU_IMAGE. As imagens do Linux são armazenadas em cache em${XDG_CACHE_HOME:-~/.cache}/ash/vm-images, e os discos VM interativos e as chaves SSH são mantidos sob${XDG_STATE_HOME:-~/.local/state}/ash/vm. DefinirASH_TEST_VM_CACHE_DIRouASH_TEST_VM_STATE_DIRpara alterar esses locais.

Para permitir que o convidado se conecte ao mesmo serviço de IA que o host, exporte o necessárioASH_AI_*variáveis ​​antes de executar o script, por exemploASH_AI_ENDPOINT,ASH_AI_MODELe, quando necessário,ASH_AI_AUTH_TOKEN. Os valores exportados são encaminhados ao hóspede; variáveis ​​​​de shell não exportadas não são. As VMs interativas retêm essas credenciais no perfil de convidado com modo0600; Os discos VM do Linux não são criptografados, portanto, proteja o diretório de estado e pare/remova a VM quando terminar.

Verscripts/vm.sh --helppara os pré-requisitos de back-end atuais, plataformas suportadas e opções.

Guias de origem do projeto

  • Guia de contribuição— configuração, testes, expectativas de lançamento e notas de CI.
  • Arquitetura— layout do projeto e subsistemas de tempo de execução.
  • LEIA-ME— referência de produto, instalação, configuração e ambiente.
  • Makefile- controlar receitas de destino e variáveis ​​de construção.
  • Fluxos de trabalho do GitHub— CI, construtores de plataforma e automação de publicação.