Integração WSL (subsistema Windows para Linux)¶

WSL permite executar um ambiente Linux completo diretamente no Windows. Depois de configurada, a integração do shell STT funciona de forma idêntica aos guias Linux Bash ou Zsh — nenhuma adaptação específica do Windows é necessária para a função do shell em si.

Recomendado para: usuários do Windows que estão familiarizados com um terminal Linux ou que já possuem o WSL instalado para trabalho de desenvolvimento. WSL oferece a experiência mais fiel e o menor comprometimento de compatibilidade.

Pré-requisitos¶

Instale WSL (configuração única)¶

Abra o PowerShell ou CMD como administrador e execute:

wsl --install

Isso instala o WSL2 com Ubuntu por padrão. Reinicie sua máquina quando solicitado.

Para instalar uma distribuição específica:

wsl --install -d Ubuntu-24.04
# or
wsl --install -d Debian

Liste todas as distribuições disponíveis:

wsl --list --online

Verifique sua versão WSL¶

CODE_BLOCO_3

Certifique-se de que a coluna VERSION mostre 2. Se mostrar 1, atualize com:

wsl --list --verbose

Integração Shell dentro do WSL¶

Assim que o WSL estiver em execução, abra seu terminal Linux e siga o guia do shell do Linux para o seu shell preferido:

Concha	Guia
Bash (padrão WSL)	bash-integration.md
Zsh	zsh-integration.md
Peixe	fish-integration.md
Ksh	ksh-integration.md
POSIX sh / traço	posix-sh-integration.md

Para a configuração padrão do Ubuntu/Debian WSL com Bash, o caminho rápido é:

CODE_BLOCO_5

Considerações específicas da WSL¶

Acessando arquivos do Windows pelo WSL¶

Suas unidades do Windows estão montadas em /mnt/:

wsl --set-version <DistroName> 2

Se o seu projeto reside no sistema de arquivos do Windows (por exemplo, C:\Projects\stt), defina SL5NET_AURA_PROJECT_ROOT como:

nano ~/.bashrc
# Paste the function block from bash-integration.md
source ~/.bashrc

Adicione esta linha ao seu ~/.bashrc (ou o equivalente para o seu shell) acima da função s().

Dica de desempenho: Para melhor desempenho de E/S, mantenha os arquivos do projeto dentro do sistema de arquivos WSL (por exemplo, ~/projects/stt) em vez de /mnt/c/.... O acesso entre sistemas de arquivos entre WSL e Windows é significativamente mais lento.

Ambiente virtual Python dentro do WSL¶

Crie e use um ambiente virtual Linux padrão dentro do WSL:

/mnt/c/   # → C:\
/mnt/d/   # → D:\

O caminho PY_EXEC na função ($SL5NET_AURA_PROJECT_ROOT/.venv/bin/python3) funcionará corretamente como está.

Executando `s` no Terminal do Windows¶

Windows Terminal é a forma recomendada de usar WSL no Windows. Ele oferece suporte a várias guias, painéis e perfis para cada distribuição WSL. Instale-o na Microsoft Store ou via:

CODE_BLOCO_9

Defina sua distribuição WSL como o perfil padrão nas configurações do Terminal do Windows para uma experiência mais perfeita.

Docker sob demanda (Linux)¶

Para economizar recursos do sistema, você pode configurar o Docker para iniciar somente quando necessário (por exemplo, quando o Aura solicitar o banco de dados Trino), em vez de executar constantemente em segundo plano.

Execute os seguintes comandos para desabilitar o serviço contínuo em segundo plano e habilitar a “ativação de soquete”:

export SL5NET_AURA_PROJECT_ROOT="/mnt/c/Projects/stt"

Torne-o seguro para atualização (usuários Linux Arch/Manjaro): Às vezes, as atualizações de pacotes podem redefinir a configuração do soquete. Para evitar isso, crie uma substituição local persistente:

cd "$SL5NET_AURA_PROJECT_ROOT"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Certifique-se de que as seguintes linhas estejam presentes e sem comentários (remova o #), salve e saia:

winget install Microsoft.WindowsTerminal

Docker e Kiwix dentro do WSL¶

O script auxiliar Kiwix (kiwix-docker-start-if-not-running.sh) requer Docker. Instale o Docker Desktop para Windows e habilite a integração WSL 2:

Baixe e instale o Docker Desktop.
Em Docker Desktop → Configurações → Recursos → Integração WSL, habilite sua distribuição WSL.
Verifique dentro do WSL:

sudo systemctl disable docker.service
sudo systemctl enable docker.socket
sudo systemctl start docker.socket

Chamando a função WSL `s` do Windows (opcional)¶

Se quiser invocar o atalho s de uma janela CMD do Windows ou PowerShell sem abrir um terminal WSL, você pode envolvê-lo:

sudo systemctl edit docker.socket

[Install]
WantedBy=sockets.target

O sinalizador -i carrega um shell interativo para que seu ~/.bashrc (e a função s) seja obtido automaticamente.

Características¶

Compatibilidade total com Linux: Todas as ferramentas Unix (timeout, pgrep, mktemp, grep) funcionam nativamente — não são necessárias soluções alternativas.
Caminhos Dinâmicos: Encontra automaticamente a raiz do projeto através da variável SL5NET_AURA_PROJECT_ROOT definida na configuração do seu shell.
Auto-Restart: Se o backend estiver inativo, ele tenta executar o start_service e os serviços locais da Wikipedia (o Docker deve estar em execução).
Tempos limite inteligentes: primeiro tenta uma resposta rápida de 2 segundos e depois volta para um modo de processamento profundo de 70 segundos.