Menulis gem

Gem yang tercantum pada rubygems.org sesungguhnya dibuat dengan peralatan yang sama seperti yang menyertai Ruby. Topik ini membangun satu gem kecil bernama paket-salam dari awal, mulai dari struktur direktori dan berkas gemspec, pembangunan berkas .gem dengan gem build, pemasangan dari berkas lokal, hingga gambaran alur publikasinya ke katalog. Setelah topik ini dituntaskan, siklus hidup sebuah gem dari kode sumber hingga terpasang dapat diikuti tanpa alat tambahan.

Struktur direktori gem#

Gem paling ringkas terdiri atas dua bagian, yaitu kode pustaka pada direktori lib dan satu berkas gemspec yang memuat metadata. Nama berkas titik masuk mengikuti nama gem, sehingga gem bernama paket-salam menyimpan kode utamanya pada lib/paket-salam.rb dan dapat dimuat dengan require “paket-salam”.

paket-salam/
├── lib/
│   └── paket-salam.rb
└── paket-salam.gemspec

Kedua berkas pada struktur tersebut dibuat pada direktori kerja, dimulai dari kode pustakanya.

# titik masuk gem paket-salam
module PaketSalam
  VERSION = "0.1.0"

  def self.halo(nama)
    "Salam, #{nama}!"
  end
end

Modul PaketSalam menjadi namespace yang menampung seluruh konstanta dan metode gem, sehingga nama yang didefinisikannya tidak bertabrakan dengan kode penggunanya. Metode modul halo menghasilkan kalimat sapaan dari satu argumen, dan konstanta VERSION menyimpan nomor versi gem yang juga dituliskan pada gemspec.

Berkas gemspec#

Gemspec adalah berkas Ruby yang memanggil Gem::Specification.new dan mengisi metadata gem pada bloknya. Metadata inilah yang dibaca RubyGems saat gem dibangun maupun dipasang, sehingga identitas gem sepenuhnya ditentukan di sini.

# paket-salam.gemspec: metadata gem paket-salam untuk RubyGems
Gem::Specification.new do |spec|
  spec.name = "paket-salam"
  spec.version = "0.1.0"
  spec.authors = ["Citra"]
  spec.summary = "Gem kecil untuk menghasilkan kalimat sapaan"
  spec.license = "MIT"
  spec.files = Dir["lib/**/*.rb"]
  spec.required_ruby_version = ">= 3.0"
end

Setiap bidang pada gemspec di atas menjawab satu pertanyaan tentang gem tersebut, sebagaimana dirangkum tabel berikut.

Bidang files diisi dengan pola Dir["lib/**/*.rb"] alih-alih daftar nama yang ditulis manual, sehingga berkas pustaka baru di dalam lib ikut terbawa tanpa mengubah gemspec. Bidang required_ruby_version menjaga gem agar tidak dipasang pada interpreter yang lebih tua dari yang dituntut kodenya.

Membangun berkas .gem#

Perintah gem build mengemas gemspec beserta berkas-berkas yang tercantum pada bidang files menjadi satu berkas .gem.

# membangun gem dari gemspec pada direktori saat ini
gem build paket-salam.gemspec

WARNING:  no homepage specified
WARNING:  See https://guides.rubygems.org/specification-reference/ for help
  Successfully built RubyGem
  Name: paket-salam
  Version: 0.1.0
  File: paket-salam-0.1.0.gem

Keluaran di atas memuat dua bagian. Baris WARNING adalah peringatan atas bidang opsional yang belum diisi, yaitu homepage, dan peringatan semacam ini tidak menghentikan pembangunan. Empat baris berikutnya melaporkan hasilnya, yaitu satu berkas bernama paket-salam-0.1.0.gem. Penamaan berkas itu mengikuti pola nama-versi.gem dari isi gemspec, sehingga setiap versi menghasilkan berkas yang berbeda namanya.

Peringatan pada tahap pembangunan layak dianggap sebagai daftar periksa gratis dari RubyGems. Bidang seperti homepage dan metadata yang lebih lengkap tidak mengubah cara gem berjalan, tetapi memengaruhi cara gem dibaca calon penggunanya pada katalog. Summary dan description yang jelas menentukan seberapa mudah gem dipahami dari hasil pencarian, sedangkan authors dan email memberi jalur bagi laporan masalah. Mengisi bidang-bidang itu sejak gem pertama membentuk kebiasaan yang berguna ketika gem berikutnya benar-benar diterbitkan untuk umum.

Memasang dan menguji gem dari berkas lokal#

Berkas .gem yang baru dibangun dapat dipasang langsung dari berkasnya tanpa menghubungi katalog mana pun.

# memasang gem dari berkas .gem lokal tanpa dokumentasi
gem install ./paket-salam-0.1.0.gem --no-document

Successfully installed paket-salam-0.1.0
1 gem installed

# memeriksa gem yang baru dipasang
gem list paket-salam

paket-salam (0.1.0)

Setelah terpasang, gem buatan sendiri berstatus sama seperti gem yang diunduh dari katalog, sehingga require “paket-salam” menemukannya dari direktori mana pun.

# uji-paket.rb: memakai gem buatan sendiri sebagaimana gem lain
require "paket-salam"

puts PaketSalam.halo("Dunia")
puts "Versi gem: #{PaketSalam::VERSION}"

Salam, Dunia!
Versi gem: 0.1.0

# menjalankan program uji dari direktori kerja
ruby uji-paket.rb

Salam, Dunia!
Versi gem: 0.1.0

Perhatikan bahwa program uji menggunakan require dan bukan require_relative, karena gem dimuat dari pemasangannya, bukan dari direktori lib yang ada di sebelahnya. Konsekuensinya, suntingan pada lib/paket-salam.rb tidak terbaca oleh require sebelum gem dibangun dan dipasang ulang dengan gem build serta gem install.

Gambaran alur publikasi#

Gem sampai ke tangan pengguna lain melalui rubygems.org dengan alur yang pendek. Akun dibuat pada situsnya, kredensial disetel pada mesin kerja, lalu perintah gem push mengunggah berkas .gem hasil gem build ke katalog. Setelah terbit, gem dapat dipasang oleh siapa pun dengan perintah gem install paket-salam tanpa berkas lokal apa pun, dan gem tersebut muncul pada hasil pencarian rubygems.org berikut summary-nya.

Satu nomor versi hanya boleh diterbitkan sekali, sehingga koreksi apa pun menuntut kenaikan versi sebelum gem build dan gem push diulang. Kebiasaan ini membuat berkas .gem pada katalog selalu identik dengan sumbernya dan membuat laporan bug (cacat pada program) dapat ditudingkan ke versi tertentu. Dengan disiplin itu pula, angka 0.1.0 pada gem latihan ini tepat menyatakan statusnya, yaitu versi awal yang masih berpeluang mengalami perubahan besar.

# tidak-dijalankan
# mengunggah gem memerlukan akun rubygems.org beserta kredensialnya
gem push paket-salam-0.1.0.gem

Karena aturan tersebut, pengujian sebelum publikasi dilakukan pada berkas lokal sebagaimana dijelaskan pada bagian sebelumnya, dan gem push hanya dijalankan ketika versi yang akan terbit benar-benar siap. Alur lengkapnya berulang untuk setiap versi, yaitu sunting kode, naikkan version, bangun dengan gem build, uji dari berkas lokal, lalu unggah dengan gem push.

Ringkasan#

• Gem paling ringkas terdiri atas kode pada lib dan satu berkas gemspec yang memuat name, version, authors, summary, files, dan required_ruby_version.
• gem build mengemas gemspec beserta berkas pada bidang files menjadi satu berkas .gem bernama nama-versi.gem.
• gem install ./nama-versi.gem memasang gem dari berkas lokal sehingga require “nama” bekerja seperti pada gem katalog.
• Publikasi ke rubygems.org menggunakan gem push, dan versi yang sudah terbit tidak dapat ditimpa sehingga perbaikan menggunakan nomor versi baru.

Referensi#

• Make your own gem — RubyGems Guides — Panduan resmi menulis gem dari struktur, gemspec, gem build, hingga gem push.
• Specification Reference — RubyGems Guides — Daftar lengkap bidang gemspec beserta aturan isinya.
• Publishing your gem — RubyGems Guides — Langkah resmi mengunggah gem ke rubygems.org.