Ruby Academy · Aula

Estrutura de uma gem

Arquivos e gemspec.

Estrutura de uma gem é uma aula grátis de Ruby Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Ruby Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Ruby Academy inclui 4 aulas no total.

O que é uma gema?

Uma gema é uma biblioteca ou aplicação Ruby empacotada que pode ser instalada, versionada e compartilhada por meio do RubyGems. Quase toda ferramenta Ruby que você utiliza é uma gema.

Uma gema reúne código, metadados e dependências.
Os metadados ficam em um arquivo de especificação da gema.
Ferramentas como bundler e gem gerenciam gemas.

Gerando uma estrutura inicial

A maneira mais rápida de começar é usar bundle gem mygem. Esse comando cria a estrutura padrão de diretórios, um arquivo de especificação da gema, uma pasta de testes, um arquivo README e uma licença. Depois, você preenche o código.

A estrutura padrão

Uma gema típica chamada mygem tem a seguinte estrutura:

lib/mygem.rb é o arquivo de entrada.
lib/mygem/ contém arquivos de código-fonte adicionais.
lib/mygem/version.rb contém a constante de versão.
mygem.gemspec contém os metadados.
test/ ou spec/ contém os testes.
README.md e um arquivo de licença.

O arquivo de entrada

lib/mygem.rb é carregado quando alguém executa require 'mygem'. Geralmente, ele carrega o arquivo de versão e o restante da biblioteca, além de definir o módulo de nível superior.

module Mygem
  def self.greet(name)
    "Hello, " + name
  end
end

puts Mygem.greet("world")

O arquivo de versão

Manter a versão em seu próprio arquivo permite que tanto o arquivo de especificação da gema quanto o código a leiam. A convenção é usar uma constante VERSION dentro do módulo da gema.

module Mygem
  VERSION = "0.1.0"
end

puts "Current version: " + Mygem::VERSION

O que é um arquivo de especificação da gema?

O arquivo de especificação da gema é um arquivo Ruby que descreve a gema: seu nome, versão, autor, resumo, arquivos e dependências. O RubyGems o lê para criar e publicar o pacote.

Ele contém Ruby comum, portanto você pode calcular valores, mas mantenha-o simples e declarativo.

Um arquivo de especificação mínimo

Os campos principais são nome, versão, autores, resumo e arquivos. Veja a estrutura, escrita como Ruby simples que você poderia colocar em mygem.gemspec.

require "ostruct"

spec = OpenStruct.new
spec.name = "mygem"
spec.version = "0.1.0"
spec.authors = ["Your Name"]
spec.summary = "A tiny example gem"

puts spec.name + " " + spec.version

Listando arquivos

O arquivo de especificação da gema deve declarar quais arquivos serão incluídos na gema. Muitos desses arquivos de especificação pedem ao git a lista de arquivos rastreados para que nada seja esquecido:

spec.files = Dir['lib/**/*.rb'] + ['README.md']

Apenas os arquivos listados são empacotados; portanto, esquecer um arquivo resulta em uma instalação quebrada.

Declarando dependências

Dois tipos de dependências são incluídos no arquivo de especificação da gema:

add_dependency para necessidades de execução que os usuários precisam instalar.
add_development_dependency para ferramentas usadas apenas durante o desenvolvimento, como estruturas de testes.

Use restrições de versão, como '~> 1.2', para manter a compatibilidade.

Versão obrigatória do Ruby

Defina spec.required_ruby_version para que usuários com uma versão muito antiga do Ruby recebam um erro claro em vez de uma falha confusa. Preencha também homepage, license e metadata para criar uma gema bem elaborada.

required = ">= 3.0.0"
current = RUBY_VERSION
puts "Requires Ruby " + required
puts "Running Ruby " + current

Criando a gema

Quando o arquivo de especificação da gema estiver pronto, gem build mygem.gemspec produzirá um arquivo .gem. Você pode instalá-lo localmente com gem install ./mygem-0.1.0.gem para testá-lo antes de publicar.

Verificação rápida

Teste sua compreensão da estrutura de uma gema.

Recapitulação: estrutura de uma gema

Você aprendeu como uma gema é organizada:

bundle gem cria a estrutura inicial.
lib/mygem.rb é o ponto de entrada.
A versão fica em seu próprio arquivo.
O arquivo de especificação da gema contém metadados, arquivos e dependências.
gem build empacota a gema.

Em seguida, vamos organizar o código propriamente dito dentro da gema.

Perguntas Frequentes

A aula “Estrutura de uma gem” é grátis?

Sim — o texto completo de “Estrutura de uma gem” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Ruby Academy, atualize para CoddyKit PRO. O curso de Ruby Academy inclui 4 aulas no total.

O que vou aprender em “Estrutura de uma gem”?

Arquivos e gemspec. Você pratica Ruby Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Ruby Academy?

Nenhuma experiência prévia é necessária. Ruby Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Estrutura de uma gem”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Ruby Academy?

Sim. Cada aula de Ruby Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Ruby Academy