Neste artigo, vamos configurar o ambiente necessário para começar a programar em Ruby, serão configuradas as ferramentas essenciais para o desenvolvimento em Ruby, incluindo o terminal e o gerenciador de versões asdf.

Apresentação

Neste artigo, vamos configurar o ambiente necessário para começar a programar em Ruby, uma das linguagens mais elegantes e legíveis da atualidade.

A diferença deste guia é que vamos usar o asdf, um gerenciador de versões universal que permite controlar não apenas o Ruby, mas também Node.js, Python, Go e dezenas de outras ferramentas, tudo em um único lugar.

Serão explicados os passos para:

  • Entender o que é o asdf e por que usá-lo
  • Configurar o WSL (Windows Subsystem for Linux) no Windows
  • Instalar o asdf no Ubuntu/WSL e macOS
  • Instalar e gerenciar versões do Ruby
  • Configurar o VS Code como editor de código
  • Fazer o primeiro teste prático

Assim como nos artigos anteriores, tudo será apresentado com explicações passo a passo, comandos em destaque e orientações específicas para quem usa leitores de tela.

Glossário rápido (sem mistério)

  • Terminal: programa onde digitamos comandos. No Windows (com WSL) usaremos o terminal do Ubuntu; no macOS, o app Terminal.
  • Shell: o “intérprete” que entende os comandos. Os mais comuns são o Bash (no Ubuntu/WSL) e o Zsh (no macOS). Neste guia, no Ubuntu/WSL vamos usar apenas Bash.
  • WSL: sigla de Windows Subsystem for Linux. Ele coloca um Linux (Ubuntu) dentro do Windows, sem máquina virtual.
  • asdf: ferramenta que instala e alterna versões de linguagens (Ruby, Node, Python…).
  • Homebrew: gerenciador de pacotes do macOS (instala programas pelo terminal).
  • VS Code: editor de código onde vamos escrever e ler arquivos mais pra frente (neste artigo, só instalamos as extensões).

O que é o asdf

O asdf é um gerenciador de versões universal (em inglês, “version manager”). Ele permite instalar e alternar entre diferentes versões de linguagens de programação e ferramentas de desenvolvimento.

Por que usar o asdf?

  • Gerencia múltiplas linguagens: Em vez de usar um gerenciador diferente para cada linguagem (rbenv para Ruby, nvm para Node.js, pyenv para Python), o asdf gerencia tudo.
  • Fácil de usar: Comandos simples e consistentes para todas as linguagens.
  • Controle por projeto: Você pode definir versões diferentes de Ruby para cada projeto, através de um arquivo chamado .tool-versions.
  • Comunidade ativa: Centenas de plugins disponíveis para diferentes ferramentas.

Como funciona

O asdf usa plugins para cada linguagem ou ferramenta. Para Ruby, você instala o plugin do Ruby, e depois pode instalar quantas versões quiser:

# Instalar o plugin do Ruby
asdf plugin add ruby

# Instalar uma versão específica
asdf install ruby 3.3.0

# Definir como versão global (padrão)
asdf global ruby 3.3.0

Configurando o WSL no Windows

O WSL (Windows Subsystem for Linux) permite rodar um ambiente Linux completo dentro do Windows. Isso é essencial para programar em Ruby, pois a maioria das ferramentas e bibliotecas foram criadas pensando em sistemas Unix/Linux.

Por que usar o WSL?

  • Compatibilidade: Muitas gems (bibliotecas Ruby) funcionam melhor no Linux.
  • Ferramentas: Você terá acesso a todas as ferramentas de linha de comando do Linux.
  • Aprendizado: É o mesmo ambiente usado em servidores de produção (que são os lugares onde as aplicações ficam online para serem acessadas).

Passo a passo para instalar o WSL

1) Verificar requisitos:

  • Windows 10 versão 2004 ou superior (Build 19041 ou superior), ou Windows 11.
  • Para verificar, pressione Windows + R, digite winver e pressione Enter.

2) Habilitar o WSL:

Abra o PowerShell como Administrador. Para fazer isso:

  • Pressione Windows, digite “PowerShell”
  • Quando o NVDA anunciar “Windows PowerShell, aplicativo”, pressione Ctrl + Shift + Enter para abrir como administrador
  • Confirme o UAC (Controle de Conta de Usuário) pressionando Alt + S (Sim)

No PowerShell, execute:

wsl --install

Este comando faz várias coisas:

  • Habilita os recursos necessários do Windows
  • Baixa o kernel do Linux
  • Instala o Ubuntu como distribuição padrão

3) Reiniciar o computador:

Após a instalação, reinicie o Windows. Pressione Windows + X, depois U duas vezes para reiniciar.

4) Configurar o Ubuntu:

Após reiniciar, o Ubuntu será aberto automaticamente pedindo para você criar um usuário:

  • Digite um nome de usuário (só letras minúsculas e números, sem espaços)
  • Pressione Enter
  • Digite uma senha (o cursor não vai se mover, é normal por segurança)
  • Pressione Enter
  • Digite a senha novamente
  • Pressione Enter

5) Atualizar o sistema:

Com o Ubuntu configurado, execute:

sudo apt update && sudo apt upgrade -y

Digite sua senha quando solicitado e aguarde a atualização terminar.

Abrindo o WSL no futuro

Para abrir o Ubuntu novamente:

  • Pressione Windows
  • Digite “Ubuntu”
  • Pressione Enter

Ou use o Windows Terminal (recomendado):

  • Pressione Windows
  • Digite “Terminal”
  • Pressione Enter
  • No Terminal, pressione Ctrl + Shift + 2 para abrir uma aba do Ubuntu

Dicas de acessibilidade para NVDA no WSL

  • O NVDA lê bem o terminal do Ubuntu no WSL
  • Use NVDA + Seta para Baixo para ativar o modo de foco e ouvir as saídas dos comandos
  • Use Insert + Seta para Cima para revisar a linha anterior
  • O histórico de comandos é acessado com Seta para Cima e Seta para Baixo

Instalando asdf no Ubuntu/WSL

Agora vamos instalar o asdf no Ubuntu (ou no WSL com Ubuntu).

1) Instalar dependências

sudo apt update
sudo apt install -y curl git build-essential autoconf bison libssl-dev zlib1g-dev libreadline-dev libyaml-dev libffi-dev libgdbm-dev

Estas dependências são necessárias para:

  • curl e git: são ferramentas para baixar o asdf e os plugins. O curl é usado para fazer requisições web, ou seja, baixar arquivos da internet ou conteúdos de APIs. Já o git é usado para clonar repositórios de código e gerenciar versões em projetos de software. Usando essas ferramentas, o asdf pode facilmente baixar e instalar os plugins e versões das linguagens que você deseja usar.

  • build-essential: é como o um kit de ferramentas necessário para compilar (montar) programas a partir do código-fonte. Muitas linguagens, incluindo o Ruby, precisam ser compiladas para funcionar corretamente no seu sistema. O build-essential inclui o compilador GCC, make e outras ferramentas essenciais para esse processo.

  • libssl-dev e zlib1g-dev: essas são bibliotecas necessárias para o Ruby funcionar corretamente, especialmente para lidar com conexões seguras (SSL) e compressão de dados (zlib). Isso garante que o Ruby possa usar recursos importantes para segurança e manipulação de dados.

  • autoconf e bison: ferramentas usadas no processo de construção (build) de softwares a partir do código‑fonte. O autoconf ajuda a gerar o script configure que detecta recursos do seu sistema, e o bison é um gerador de analisadores sintáticos (parser). Ao compilar o Ruby, essas ferramentas garantem que a configuração e a geração de partes do código aconteçam corretamente.

  • libreadline-dev: fornece recursos de edição de linha no terminal (histórico, setas e atalhos), usados por ferramentas como o irb (console interativo do Ruby). Sem o Readline, a experiência no console fica limitada.

  • libyaml-dev: biblioteca necessária para o suporte a YAML no Ruby (gem/stdlib psych). Muitos projetos Ruby usam YAML para configuração; esta biblioteca habilita a extensão nativa correspondente.

  • libffi-dev: implementa a Foreign Function Interface, permitindo que extensões Ruby e gems chamem código nativo (C/C++). É usada por bibliotecas da própria stdlib (como fiddle) e por várias gems.

  • libgdbm-dev: biblioteca de banco de dados simples (GDBM) utilizada pelo módulo dbm da biblioteca padrão do Ruby. Alguns projetos e scripts se apoiam nesse backend; instalar a versão de desenvolvimento permite compilar a extensão correspondente.

2) Baixar e instalar o asdf

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0

Este comando baixa o asdf para a pasta ~/.asdf (o til significa “sua pasta pessoal”).

3) Configurar o Bash

Vamos usar apenas o Bash (shell padrão do Ubuntu/WSL na maioria dos casos). O arquivo de configuração do Bash fica na sua pasta pessoal e se chama ~/.bashrc.

Vamos editar esse arquivo com o editor de texto nano (ele abre no próprio terminal).

1) Abrir o arquivo no nano

nano ~/.bashrc

2) Ir até o final do arquivo

  • Use as setas do teclado para descer até a última linha.

3) Adicionar estas linhas exatamente como estão

source "$HOME/.asdf/asdf.sh"
source "$HOME/.asdf/completions/asdf.bash"

4) Salvar e sair do nano

  • Pressione Ctrl + O (de “Output”) para salvar.
  • O nano vai perguntar o nome do arquivo. Pressione Enter para confirmar.
  • Depois pressione Ctrl + X para sair do editor.

5) (Opcional) Compatibilidade com arquivos .ruby-version Alguns projetos trazem um arquivo chamado .ruby-version. Podemos pedir ao asdf para entender esse arquivo criando (ou editando) ~/.asdfrc:

nano ~/.asdfrc

No arquivo que abriu, digite esta linha, salve (Ctrl+O, Enter) e saia (Ctrl+X):

legacy_version_file = yes

4) Recarregar o Bash

Para aplicar as mudanças, feche e abra o terminal novamente.

Se preferir, recarregue o arquivo de configuração com:

source ~/.bashrc

Alternativa (faz o Bash reiniciar):

exec bash

5) Verificar a instalação

asdf --version

Você deve ver algo como: v0.14.0

Instalando asdf no macOS

No macOS, vamos instalar o asdf usando o Homebrew.

1) Instalar o asdf via Homebrew

brew install asdf

2) Configurar o shell (Zsh)

No macOS o shell padrão é o Zsh. Vamos adicionar o asdf à configuração do Zsh.

Opção A — usando editor (recomendado):

nano ~/.zshrc

No final do arquivo, cole esta linha, salve e saia do nano:

. $(brew --prefix asdf)/libexec/asdf.sh

Para permitir compatibilidade com arquivos como .ruby-version, adicione também (opcional):

echo 'legacy_version_file = yes' >> ~/.asdfrc

Opção B — usando comandos (atalho):

echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ~/.zshrc
echo 'legacy_version_file = yes' >> ~/.asdfrc

3) Recarregar o shell

source ~/.zshrc

Alternativa (faz o Zsh reiniciar):

exec zsh

4) Verificar a instalação

asdf --version

Dicas de acessibilidade para VoiceOver no macOS

  • O VoiceOver funciona bem com o Terminal do macOS
  • Use VO + Seta para Cima/Baixo para navegar entre as linhas do terminal
  • Para revisar a saída do último comando, use VO + A para começar a ler
  • O histórico de comandos é acessado com Seta para Cima e Seta para Baixo

Instalando Ruby com asdf

Agora que o asdf está instalado, vamos adicionar o plugin do Ruby e instalar a linguagem.

1) Adicionar o plugin do Ruby

asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git

Este comando adiciona o plugin oficial do Ruby ao asdf.

2) Ver versões disponíveis (opcional)

Para ver todas as versões disponíveis:

asdf list all ruby

Atenção: Este comando pode mostrar centenas de versões. Para ver apenas as 10 mais recentes:

asdf list all ruby | tail -20

3) Instalar a versão mais recente

# No macOS, garanta o uso do OpenSSL do Homebrew
if [[ "$(uname)" == "Darwin" ]]; then 
    export RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@3)"
fi

asdf install ruby latest

Este processo pode demorar alguns minutos, pois o Ruby será compilado (montado) do zero no seu computador. O asdf vai baixar o código-fonte e compilar especificamente para o seu sistema.

Para instalar uma versão específica, por exemplo a 3.3.0:

asdf install ruby 3.3.0

4) Definir a versão global (padrão)

asdf global ruby latest

Ou, se instalou uma versão específica:

asdf global ruby 3.3.0

5) Verificar a instalação

ruby -v
gem -v

Você deve ver a versão do Ruby e do gem (gerenciador de pacotes do Ruby).

6) Instalar o Bundler

O Bundler é o gerenciador de dependências do Ruby:

gem install bundler
gem update --system
asdf reshim ruby
bundle -v

Gerenciando versões por projeto

Uma das grandes vantagens do asdf é poder ter versões diferentes de Ruby para cada projeto.

Exemplo: Se você tem um projeto que precisa do Ruby 3.2.0, entre na pasta do projeto e execute:

cd ~/meu-projeto
asdf local ruby 3.2.0

Isso cria um arquivo .tool-versions na pasta do projeto, e sempre que você entrar nesta pasta, o asdf vai usar automaticamente o Ruby 3.2.0.

Comandos úteis do asdf

# Listar versões instaladas
asdf list ruby

# Listar todos os plugins instalados
asdf plugin list

# Atualizar o asdf
asdf update

# Atualizar todos os plugins
asdf plugin update --all

# Regenerar shims após instalar gems com executáveis
asdf reshim ruby

# Remover uma versão
asdf uninstall ruby 3.2.0

# Ver a versão atual em uso
asdf current ruby

Migrando do rbenv/RVM para o asdf

Se você já usava rbenv ou RVM, siga estes passos para migrar com segurança:

1) Desative a inicialização do gerenciador antigo no seu shell:

# Comente linhas do rbenv ou RVM no ~/.zshrc ou ~/.bashrc
sed -n '/rbenv\|rvm/p' ~/.zshrc 2>/dev/null

2) Ative o modo de compatibilidade de versões do asdf (lê .ruby-version):

echo 'legacy_version_file = yes' >> ~/.asdfrc

3) Dentro de cada projeto, converta para .tool-versions:

cd /caminho/do/seu/projeto
if [ -f .ruby-version ]; then asdf local ruby "$(cat .ruby-version)"; fi

4) Reinstale a versão de Ruby necessária via asdf e confira:

asdf install ruby
asdf current ruby

5) Reinstale gems quando necessário e regenere shims:

gem install bundler
bundle install  # quando houver Gemfile
asdf reshim ruby

Configurando o VS Code

Com o Ruby instalado, vamos preparar o VS Code para trabalhar com Ruby.

Extensões recomendadas

Extensões essenciais:

  • Ruby LSP (Shopify) — fornece recursos de linguagem (diagnósticos, autocompletar, navegação)
  • WSL (Microsoft) — se estiver no Windows usando WSL

Extensões opcionais mas úteis:

  • Ruby Test Explorer — para rodar testes
  • endwise — completa automaticamente blocos de código Ruby
  • GitHub Pull Requests and Issues — integração com GitHub

Como instalar extensões no VS Code

Usando a interface:

  1. Pressione Ctrl/Cmd + Shift + X para abrir a aba de extensões
  2. Digite “Ruby LSP” no campo de busca
  3. Pressione Enter e depois Tab até ouvir o botão “Instalar”
  4. Pressione Enter para instalar

Usando a paleta de comandos (mais acessível):

  1. Pressione Ctrl/Cmd + Shift + P
  2. Digite “Extensions: Install Extensions”
  3. Pressione Enter
  4. Digite “Ruby LSP”
  5. Pressione Enter e procure o botão Instalar com Tab

Configurando o VS Code para WSL (Windows)

Se você está no Windows usando WSL:

  1. Instale a extensão “WSL” no VS Code
  2. Pressione Ctrl + Shift + P
  3. Digite “WSL: Connect to WSL”
  4. Pressione Enter

Agora o VS Code está rodando dentro do ambiente Linux do WSL, e você pode abrir pastas e arquivos do Ubuntu.

Ajustes úteis no VS Code

Terminal integrado:

  • Abra com Ctrl/Cmd + ` (crase)
  • O terminal vai usar automaticamente o Zsh ou Bash configurado

Acessibilidade:

  • Nas configurações, procure por “terminal accessible” e habilite a visualização acessível do terminal
  • Use Ctrl/Cmd + Shift + P e digite “Terminal: Focus Accessible Buffer” para revisar a saída do terminal com o leitor de tela

Formatação:

  • O Ruby LSP já fornece formatação básica
  • Para projetos que usam RuboCop (ferramenta de qualidade de código), instale a gem:
gem install rubocop

Testando o ambiente

Vamos garantir que tudo está funcionando corretamente.

1) Verificar versões instaladas

asdf current
ruby -v
gem -v
bundle -v

Você deve ver:

  • A versão do Ruby que instalou
  • A versão do gem
  • A versão do Bundler

2) Executar um comando Ruby (uma linha)

Sem criar arquivos, peça para o Ruby imprimir uma mensagem usando a opção -e (de “execute”):

ruby -e 'puts "Olá, Ruby!"'

Se der certo, o terminal mostrará:

Olá, Ruby!

3) Testar a troca de versões (opcional)

Para testar a capacidade do asdf de gerenciar múltiplas versões:

# Ver versão atual
asdf current ruby

# Instalar outra versão (opcional)
asdf install ruby 3.2.2

# Listar versões instaladas
asdf list ruby

# Trocar para a versão 3.2.2 apenas nesta sessão
asdf shell ruby 3.2.2

# Verificar
ruby -v

# Voltar para a versão global
asdf shell ruby latest
ruby -v

Problemas comuns e soluções

“command not found: asdf”

  • O asdf não foi adicionado ao shell. Revise o passo de configuração do shell e execute exec zsh ou exec bash.

“ruby: command not found”

  • Você instalou o Ruby mas não definiu uma versão global. Execute: asdf global ruby latest

“Permission denied” ao instalar gems

  • Nunca use sudo com asdf. Todas as instalações devem ser no seu usuário.

VS Code não reconhece o Ruby

  • No Windows/WSL: verifique se conectou ao WSL (extensão WSL instalada e conectada)
  • Reinstale a extensão Ruby LSP
  • Recarregue o VS Code: Ctrl/Cmd + Shift + P, digite “Reload Window”

Compilação do Ruby falha no Ubuntu/WSL

  • Instale mais dependências:
sudo apt install -y libyaml-dev libreadline-dev libffi-dev libgdbm-dev autoconf bison

Resumo

Neste artigo, você configurou um ambiente Ruby moderno e profissional usando o asdf:

O que foi feito:

  • ✅ Entendeu o que é o asdf e suas vantagens
  • ✅ Configurou o WSL no Windows (se aplicável)
  • ✅ Instalou o asdf no Ubuntu/WSL ou macOS
  • ✅ Instalou o Ruby usando o asdf
  • ✅ Configurou o VS Code com extensões para Ruby
  • ✅ Testou o ambiente

Isso prepara você para começar a desenvolver aplicações Ruby com um ambiente robusto e flexível! A partir de agora será iniciada a parte de criação de projetos e desenvolvimento prático em Ruby.

É importante deixar explícito que este artigo focou exclusivamente na configuração do ambiente de desenvolvimento em Ruby usando o asdf, sem abordar a criação de projetos ou o uso de Gemfiles. O objetivo foi garantir que você tenha uma base sólida para trabalhar com Ruby antes de avançar para etapas mais complexas de desenvolvimento.

Se ficaram dúvidas, ou se algum passo não funcionou como esperado, sinta-se à vontade para revisar as seções, buscar conteúdos adicionais nas documentações oficiais, como:

O importante é garantir que o ambiente esteja funcionando perfeitamente antes de avançar para a criação de projetos Ruby. Boa sorte e bons códigos!