Paket Nimble

Berkas .nimble, manajemen dependensi, dan publikasi paket.

Daftar isi

Paket adalah unit distribusi kode Nim yang dapat dibangun, diuji, dan dipasang sebagai satu kesatuan. Topik ini membahas berkas .nimble sebagai resep paket, alur kerja harian dengan perintah nimble untuk memvalidasi, membangun, dan menguji paket lokal, pengelolaan dependensi, sampai publikasi paket ke katalog resmi. Bahan pembahasannya adalah paket penghitungkata yang memuat satu pustaka kecil beserta ujinya.

Anatomi berkas .nimble#

Berkas .nimble adalah berkas konfigurasi berformat NimScript yang berada di akar folder paket. Nama paket diambil dari nama berkasnya, sehingga berkas penghitungkata.nimble mendefinisikan paket bernama penghitungkata. Bidang version, author, description, dan license menjelaskan identitas paket, sedangkan srcDir menyatakan folder kode sumber dan bin mendaftar biner yang dihasilkan saat paket dibangun. Deklarasi requires menetapkan dependensi, termasuk versi Nim minimum, dan nimble menolak membangun paket bila syarat tersebut tidak terpenuhi.

nim penghitungkata.nimble

# Package

version       = "0.2.0"
author        = "Ali"
description   = "Penghitung kata untuk teks berbahasa Indonesia"
license       = "MIT"
srcDir        = "src"
bin           = @["penghitungkata"]


# Dependencies

requires "nim >= 2.0.0"

Bidang srcDir menjadi wajib ketika kode sumber ditempatkan di folder src. Panduan resmi Nimble menyatakan bahwa berkas .nimble harus memuat arahan srcDir = "src" untuk penataan seperti itu, karena nimble menambahkan folder tersebut ke jalur pencarian modul saat kompilasi. Tanpa arahannya, modul di folder src tidak ditemukan meskipun berkasnya ada, sebagaimana dibahas pada bagian Kesalahan umum.

Berkas sumber dan struktur folder#

Struktur folder paket dibagi menjadi sumber dan uji. Folder src memuat modul paket, sedangkan folder tests memuat berkas uji berawalan huruf t. Susunan lengkapnya adalah sebagai berikut.

text

penghitungkata/
├── penghitungkata.nimble
├── src/
│   └── penghitungkata.nim
└── tests/
    └── tpenghitungkata.nim

Modul paket memuat proc jumlahKata yang diekspor dengan tanda bintang, sehingga dapat diimpor oleh berkas uji maupun program lain yang memasang paket ini. Bagian when isMainModule hanya dieksekusi ketika berkas dikompilasi sebagai program utama, bukan ketika diimpor, sehingga satu berkas yang sama berfungsi sebagai pustaka dan sebagai antarmuka baris perintah yang menghitung kata dari masukan standar.

nim src/penghitungkata.nim

proc jumlahKata*(teks: string): int =
  ## Menghitung banyak kata yang dipisahkan spasi, tab, atau baris baru.
  result = 0
  var dalamKata = false
  for c in teks:
    if c in {' ', '\t', '\n'}:
      dalamKata = false
    elif not dalamKata:
      dalamKata = true
      inc result

when isMainModule:
  import std/strutils
  let teks = readAll(stdin)
  echo teks.splitWhitespace().len

Berkas uji mengimpor paket dengan nama pendeknya tanpa folder src, karena nimble yang mengatur jalurnya. Penamaan berawalan huruf t bukan kebiasaan sembarangan, melainkan pola yang dicari tugas test bawaan nimble.

nim tests/tpenghitungkata.nim

import std/unittest
import penghitungkata

suite "penghitung kata":
  test "teks biasa":
    check jumlahKata("satu dua tiga") == 3

  test "spasi berlebih":
    check jumlahKata("  satu   dua  ") == 2

  test "baris baru juga pemisah":
    check jumlahKata("satu\ndua\ntiga") == 3

Memvalidasi, membangun, dan menguji paket#

Perintah nimble check memeriksa keabsahan paket, yaitu berkas .nimble yang dapat diurai beserta dependensinya. Keluaran penuhnya memuat beberapa baris Info yang berisi jalur instalasi Nim, sehingga hanya baris terakhirnya yang ditampilkan di sini.

bash

# periksa keabsahan definisi paket
nimble check 2>&1 | tail -n 1

text Keluaran

  Success:  The package "penghitungkata" is valid.

Perintah nimble build mengompilasi seluruh biner yang tercantum pada bidang bin dan meletakkan hasilnya di akar folder paket. Baris Info pada keluarannya dipotong dengan alasan yang sama.

bash

# bangun seluruh biner yang tercantum pada bidang bin
nimble build 2>&1 | tail -n 1

text Keluaran

   Building penghitungkata/penghitungkata using c backend

Biner hasil build dapat dijalankan langsung dari akar paket, atau dibangun dan dijalankan sekaligus dengan nimble run penghitungkata sebagaimana dijelaskan panduan resmi untuk biner pada bidang bin. Perintah nimble test menjalankan tugas test bawaan, yaitu mengompilasi dan mengeksekusi seluruh berkas di folder tests yang namanya berawalan huruf t. Keluaran uji program dicetak nimble dengan awalan Nim Output, sedangkan baris Info dan Compiling yang memuat jalur mesin dipotong dari contoh berikut.

bash

# jalankan seluruh uji paket lewat tugas test bawaan
nimble test 2>&1 | grep -vE "Info:|Compiling"

text Keluaran

 Nim Output [Suite] penghitung kata
        ...   [OK] teks biasa
        ...   [OK] spasi berlebih
        ...   [OK] baris baru juga pemisah
   Success: Execution finished
   Success: All tests passed

Dengan tiga perintah tersebut, siklus kerja harian menjadi pendek. Suntingan kode diikuti nimble test, keabsahan definisi diperiksa sebelum rilis, dan biner siap uji selalu dapat diregenerasi dari definisi paket tanpa skrip tambahan.

Mengelola dependensi#

Dependensi dinyatakan pada bidang requires dengan operator versi yang ditetapkan dokumentasi resmi. Operator == memasang versi persis, operator ^= memasang versi paling tinggi yang masih kompatibel menurut semver, yaitu penomoran versi semantik berformat mayor.minor.perbaikan, operator ~= memasang versi paling tinggi dengan menaikkan digit terakhir, dan akhiran #head memakai ujung terkini repositorinya.

nim Contoh: bentuk deklarasi dependensi

requires "nim >= 2.0.0"
requires "contohpaket == 0.4.0"
requires "paketlain#head"

Paket eksternal dipasang dengan nimble install, yang mengunduh paket dari katalog resmi ke folder instalasi nimbleDir yang secara bawaan berada di ~/.nimble. Perintah berikut memerlukan akses jaringan sehingga tidak dapat dieksekusi di lingkungan penulisan, dan kelakuannya dirujuk dari panduan resmi Nimble.

bash

# tidak-dijalankan
# pengunduhan paket eksternal memerlukan jaringan ke katalog paket
nimble install contohpaket

Untuk menyunting paket dependensi secara langsung, nimble menyediakan perintah nimble develop yang mengklon paket untuk pengembangan dan mencatat klon tersebut pada berkas .develop, sehingga suntingan pada klon langsung dipakai tanpa instalasi ulang. Pola ini lazim dipakai ketika perbaikan pada pustaka dan pemakainya dikerjakan bersamaan dalam satu rangkaian suntingan.

Publikasi paket#

Paket yang siap dipakai orang lain dapat didaftarkan ke daftar paket resmi, yaitu berkas packages.json pada repositori nim-lang/packages, sedangkan penelusuran katalognya dilakukan lewat situs nimble.directory. Panduan resmi menyebut dua jalur pendaftaran. Jalur manual dilakukan dengan memfork repositori daftar paket, menambahkan entri paket pada packages.json, lalu mengirim permintaan tarik. Jalur semi-otomatis memakai perintah nimble publish, yang meminta akun GitHub dengan personal access token, yaitu token akses pribadi yang disimpan nimble pada foldernya.

bash

# tidak-dijalankan
# publikasi mengirim permintaan tarik ke repositori daftar paket lewat GitHub
nimble publish

Pendaftaran hanya perlu dilakukan satu kali per paket. Penaikan version pada berkas .nimble tidak menuntut pendaftaran ulang, karena pemakai yang mengunduh ulang paket akan memperoleh versi terbarunya dari sumber yang sama.

Kesalahan umum#

Kesalahan pertama berupa mengganti nama berkas .nimble dan menyangka nama paketnya tetap. Nama berkas itulah nama paketnya, sehingga berkas yang diganti menjadi namalain.nimble divalidasi sebagai paket bernama namalain, dan pemakai yang mengharapkan nama lama tidak menemukannya. Perbaikannya adalah menjaga kesamaan nama berkas .nimble dengan nama modul di folder src.

Kesalahan kedua berupa lupa arahan srcDir = "src". Pemeriksaan nimble check tetap menyatakan paket valid karena strukturnya sah, tetapi nimble test berhenti dengan pesan Error: cannot open file: penghitungkata karena modul di folder src tidak masuk jalur pencarian. Menambahkan arahan srcDir pada berkas .nimble adalah perbaikannya, bukan memindahkan modul keluar dari folder src.

Kesalahan ketiga berupa menuntut versi yang tidak tersedia. Deklarasi requires "nim >= 9.0.0" pada lingkungan ber-Nim 2.4 menggagalkan build dengan pesan penyelesaian versi, yaitu Dependency resolution failed: ... version solving failed, karena tidak ada versi yang cocok. Perbaikannya adalah menurunkan syarat versi ke batas yang benar-benar diperlukan paket.

Ringkasan#

Berkas .nimble mendefinisikan paket, dengan nama yang diambil dari nama berkasnya, ditambah bidang identitas, srcDir, bin, dan requires.
Siklus harian berupa nimble check untuk validasi, nimble build untuk menghasilkan biner pada bidang bin, dan nimble test untuk menjalankan seluruh berkas tests/t*.nim.
Dependensi dinyatakan dengan operator ==, ^=, ~=, atau akhiran #head, lalu dipasang ke nimbleDir dengan nimble install, sedangkan suntingan langsung memakai nimble develop.
Publikasi dilakukan sekali per paket, baik manual melalui permintaan tarik ke nim-lang/packages maupun semi-otomatis dengan nimble publish yang memerlukan token GitHub.

Referensi#

Nimble User Guide — nim-lang — Panduan utama Nimble: pemasangan, konfigurasi, dan alur kerja paket.
How to create a Nimble package — nim-lang — Bidang berkas .nimble, tugas test bawaan, operator versi, dan proses publikasi paket.