- Salah satu cara yang berguna bagi tim pengembang untuk mengumpulkan dan melestarikan pengetahuan organisasi adalah dengan terus menambah kumpulan snippet, skrip, atau workflow yang bermanfaat
- Karena itu, banyak repositori memiliki hal-hal seperti Makefile dan skrip bash
- Lalu bagaimana dengan hal-hal seperti memasang alat yang berguna di seluruh organisasi, membuat boilerplate code, atau menjalankan perintah AWS rumit yang tidak diingat siapa pun?
- Beberapa perusahaan seperti Slack atau Shopify memiliki CLI internal mereka sendiri
- Terminal modern Warp memiliki fitur untuk mendokumentasikan dan membagikan workflow
- CLI internal organisasi dapat dibuat dengan mudah. Sebagai contoh, dibuat CLI untuk perusahaan bernama acme
Persyaratan desain CLI
- Memiliki titik masuk umum untuk menjalankan perintah dari mana saja dengan
acme <command>
- Semua pengembang dapat menjalankan
acme <command> dari mana saja untuk memicu perintah tanpa perlu lebih dulu berpindah ke repositori tertentu
- Memungkinkan pengembang berkontribusi perintah baru dengan mudah
- Memungkinkan versi baru didistribusikan dengan mudah lewat
acme update
- Mendukung lintas platform (misalnya saat menjalankan
acme download something, gunakan curl di Linux dan Invoke-WebRequest di Windows)
- Memungkinkan melihat daftar perintah yang tersedia dan deskripsi singkatnya lewat
acme list
Memulai proyek dengan just
- just adalah alat yang mirip
make, tetapi dikhususkan untuk menjalankan perintah
- Mendukung lintas platform dan juga dapat menjalankan perintah yang spesifik per platform
- Opsi lain adalah
magic-cli milik Slack (sangat bagus untuk memulai jika Anda cukup akrab dengan Ruby) atau make
Menyiapkan proyek
- Pasang
just. Ikuti petunjuk di sini
- Buat folder
~/acme/cli dan tambahkan justfile berikut di root:
default:
just --list
# arch와 os 이름 표시
os-info:
echo "Arch: {{arch()}}"
echo "OS: {{os()}}"
- Dalam dokumentasi
just, perintah disebut sebagai "recipes"
- Jika menjalankan
just tanpa recipe, recipe pertama dalam justfile akan dijalankan. Biasanya menjadi pola umum untuk memberi nama recipe pertama sebagai "default"
$ just
just --list
Available recipes:
default
os-info # Show arch and os name
- Recipe default menjalankan
just list. Ini menampilkan daftar semua recipe beserta komentarnya
- Sebaiknya recipe default disembunyikan
- Saat recipe dijalankan, setiap perintah akan dicetak sebelum dieksekusi. Output ini bisa dihilangkan dengan prefiks
@. Mirip dengan Makefile
[private]
@default:
just --list
# arch와 os 이름 표시
@os-info:
echo "Arch: {{arch()}}"
echo "OS: {{os()}}"
Membuat alias acme
Menulis recipe baru
Recipe sederhana
Recipe spesifik platform
- Snippet yang mencakup alat seperti
systemd hanya ditampilkan jika pengembang memakai mesin Linux
- Gunakan atribut
[linux] agar recipe hanya ditampilkan di Linux
[linux]
@list-systemd-services:
systemctl list-units --type=service
Recipe lintas platform
Script recipe
- Anda bisa menyisipkan skrip lengkap ke dalam recipe
- Recipe yang dimulai dengan shebang(
#!) akan disimpan sebagai file terpisah lalu dijalankan
- Berguna ketika workflow membutuhkan logika yang sedikit lebih kompleks seperti penggunaan alur kontrol (if-else, loop), penyimpanan dan manipulasi variabel, dan sebagainya
# Say hello world in sh
hello-world-sh:
#!/usr/bin/env sh
hello='Yo'
echo "$hello from a shell script!"
- Ini berarti Anda bisa memanfaatkan bahasa pemrograman dengan kemampuan scripting yang kuat. Beberapa tugas bisa lebih mudah dilakukan di Python daripada Bash
# scale jpg image by 50%
[no-cd]
scale-jpg path:
#!/usr/bin/env python3
import PIL.Image
image = PIL.Image.open("{{path}}")
factor = 0.5
image = image.resize((round(image.width * factor), round(image.height * factor)))
image.save("{{path}}.s50.jpg")
- Tidak semua pengembang memasang Python di komputernya, dan sekalipun terpasang, belum tentu pillow sudah tersedia. Anda bisa menggunakan
nix untuk menjalankan skrip beserta dependensinya:
# scale jpg image by 50%
[no-cd]
scale-jpg path:
#! /usr/bin/env nix-shell
#! nix-shell -i python3 -p python3Packages.pillow
import PIL.Image
...
Mendistribusikan recipe
- Gunakan
git alih-alih membuat mekanisme distribusi sendiri
- Buat repositori di GitHub dan push apa yang sudah dibuat sejauh ini
$ git init
$ git commit -m "first commit"
$ git branch -M main
$ git remote add origin git@github.com:acme/cli.git
$ git push -u origin main
- Sekarang siapa pun yang memiliki akses ke repositori ini dapat membuat PR dan berkontribusi perubahan
- Otomatiskan
git pull dengan recipe acme update
# Update the Acme CLI
@update:
git fetch
git checkout main
Dokumentasi
- Keberhasilan alat internal sangat bergantung pada adopsi, dan panduan penggunaan yang baik sangat penting untuk membantu pengguna baru memasang dan menjelajahi alat tersebut
- Berikan panduan pemasangan dan penggunaan di
README
# Acme CLI
## Prerequisites
`just`: Install just [here](https://github.com/casey/just/blob/master/README.md#installation)
## Installation
Clone this repo:
...
Set up the `acme` alias:
...
## Usage
List all available recipes:
...
- Kini semua pengembang Acme Corp bisa menggunakannya!
- Posting pesan di Slack internal untuk mendorong semua orang mencobanya, dan masing-masing bisa menyumbangkan snippet mereka sendiri
Fitur tambahan
- Fitur completion adalah mekanisme yang memungkinkan penekanan tombol TAB untuk melengkapi subperintah, path file, opsi, dan sebagainya secara otomatis
- Sebagian besar shell menyediakan fitur ini, dan kebanyakan alat CLI utama menyediakan cara untuk memasang fitur completion
- Sebagian besar framework CLI utama seperti Click di Python, Cobra di Golang, dan clap di Rust dapat secara otomatis menghasilkan fitur completion
Just dapat menghasilkan completion dengan menjalankan just --completion <shell>.
1 komentar
Sepertinya sejak dulu perancangan DX internal perusahaan merupakan topik penting bagi platform engineering.