suzuki-shunsuke commented 2 years ago

https://github.com/suzuki-shunsuke/issue/issues/80

aqua という CLI ツールを YAML でバージョン管理できるツールを開発しています。似たようなユースケースで使われる有名なツールとして asdf があります。

https://asdf-vm.com/

そこで

aqua と asdf の違い
どっちを使えばいいのか
なぜ aqua を作ったのか

といったことを書いていきたいと思います。

ただし、自分は asdf にはあまり詳しくありません。以前より存在は知っていましたが、使ってはいませんし、最近 aqua と比較するためにちょっと触っているくらいです。

また、自分は aqua の開発者であるため、どうしても aqua に偏った比較をするでしょう。「使うのが簡単」とか「学習コストが低い」といった客観的に比較しにくい部分もあります。

asdf は間違いなく人気のあるツールで、非常に様々なツールに対応しています。当初自分は Python や Ruby, Node.js といった様々な言語に対応したツールくらいに思ってましたが、言語に限らず様々なツールに対応していることに驚きました。また、 asdf には aqua にはない機能もあります。

自分は aqua が asdf より単純に優れているとは思っていません。逆に asdf のほうが aqua よりも優れているとも思っていません。

玉虫色なことを言うと、皆さんのユースケースに合ったほうを使えばいいのではないかと思います。

更にいうと、どちらか一方しか使えないということはなく、併用することももちろん可能です。同じツールであればどちらか一方で管理したほうが良いとは思いますが、片方をメインで使い、メインのほうが対応していないツールはもう片方を使うのは全然ありでしょう。

共通する部分

ツールをグローバルにインストールできる
ツールを特定のプロジェクト用にインストールできる
設定ファイルでツールとそのバージョンを管理できる
plugin 機構があり、様々なツールに対応できる
- aqua の場合、 Registry という機能がある
GitHub Actions がある

asdf の introduction を読むと、やりたいことは割と親しいなと感じます。

you can check in to your project's Git repository to share with your team, ensuring everyone is using the exact same versions of tools.

チームで設定を共有し、同じバージョンを使うようにしたいということですね。

違い

plugin 機構

asdf の plugin に対し、 aqua には Registry があります。この 2 つは、本体とは独立して機能を拡張できる(様々なツールに対応できる) という共通点がある一方、仕組み的には結構違います。

asdf の plugin はツールごとにリポジトリを作成するのに対し、 aqua の Registry は 1 つで複数のツールに対応できます。 asdf では plugin ごとに決められたシェルスクリプトを作成することで、自由度高くツールのインストールが可能であり、様々なツールに対応できます。一方、 aqua のツールのインストールはかなり限定的なため、 aqua では対応できないツールも少なからずあります。

ツールを download する
ツールを unarchive する

aqua で対応できないツールを使いたい場合、 asdf のような他のツールを検討するしかないでしょう。

ただし、これだけでインストール可能なツールもかなり多く存在します。 Go で作られたツールは GitHub Releases で公開されていることが多く、こういったツールは aqua で簡単に対応できます。インストール方法を限定している代わり、簡潔に記述できるとも言えます。シェルスクリプトをゴニョゴニョ書く必要はありません。

また、任意のスクリプトを実行できるのはセキュリティ的な懸念もありますが、 aqua ではそのようなことはできないので、ツールをインストール時に悪意のあるコードが実行されるようなことはありません。 asdf の plugin には security policy https://github.com/asdf-vm/asdf-plugins#security があり、 security に関しても気を配ってますし、不必要に不安を煽るつもりはありませんが、仕組み的に防ぐことは難しいでしょう。

分散か中央集権か

asdf はサードパーティの plugin が数多く存在します。一方で aqua では Standard Registry という中央集権的な Registry で管理されています。

Standard Registry に追加するツールは、 star 数や人気とかで選別といったことは全くしてなく、だれも知らないようなツールでも install さえちゃんとできれば追加できます。気軽に PR を投げてください。サードパーティの Registry を作ることは可能ですし、会社の Private Repository で Private な Registry を作成し、 private なツールを配布すると言った使い方は十分に考えられます。しかし OSS のツールに関しては Standard Registry で管理したほうが aqua user にとって都合が良いと思っています。サードパーティの Registry を作る場合、ユーザーがその Registry の存在を知り、 aqua.yaml に追加する必要があります。 Standard Registry に追加すればその必要はありません。

ツール側に変更があったり(リポジトリの owner が変わったり、 asset の名前が変わったり)、 aqua の update に伴い Registry に修正が必要になったりしたら、 Registry をメンテする必要がありますが、 Standard Registry に追加しておけばそれを任せることができます。サードパーティだとメンテされずに放置されるリスクもあり、 Standard Registry であってもないとは言えませんが、 aqua というプロダクトが生き続ける限り、恐らく大丈夫だと思います。 Standard Registry ではツールの更新を Renovate で検知して CI を実行することで、ツールの更新に伴い Registry が壊れるのを防いでいます。 aqua の update に伴い Registry に修正が必要な場合、 Standard Registry のように一つのリポジトリに集約しているモデルだと、リポジトリが分散しているモデルに比べ、対応が遥かに容易です。

ユーザーが自由にサードパーティの plugin を作るモデルの場合、本体の開発者はそれらをメンテしなくて良いので楽ですし、健全とも言えますが、 plugin によって品質がマチマチだったりメンテされなくなったりということも往往にあります。

学習コスト

aqua と asdf で共通するモチベーションとして、複数人で同じバージョンを使うようにするというのがあります。 aqua や asdf に限らず、チーム・プロジェクトにツールを導入すると言った場合、学習コストの低さは重要です。みんながそのツールを使うモチベーションが高いわけではないし、全員が英語のドキュメントをすらすら読めるとも限りません。

aqua のコマンドはシンプルで、他にもコマンドは幾つかありますが、多くの人は aqua i [-l] だけで良いはずです。導入はかなり容易なのではないかと思っています。

一方で知名度が高いほうが導入しやすいのは当然で、 asdf を知らない人であっても、ここまで人気のあるツールであれば導入しやすいでしょう。

本体のインストール

本体(aqua と asdf) のインストールはどちらも簡単で、態々比較するほどのものでもないですが、違いはあります。

asdf はシェルスクリプトで実装されており、 .bashrc などで読み込む必要があります。そのためシェルごとに細かくガイドが分かれていて、正直わかりにくいと感じるのと、毎回スクリプトをロードしないといけないというのは、チームや組織に asdf を広めると言った場合にハードルになることも考えられます(asdf ほど知名度のあるツールであれば問題にならないかもしれませんが)。 aqua は Go で実装されており、 PATH を追加すればよいだけです。

suzuki-shunsuke commented 2 years ago

本体の install (Homebrew)

https://asdf-vm.com/guide/getting-started.html

asdf

$ brew install asdf

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

aqua

$ brew install aquaproj/aqua/aqua

export PATH=~/.aqua/bin:$PATH

suzuki-shunsuke commented 2 years ago

Node.js の Install

asdf

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

Plugin によっては別のツールに依存するケースもあります。 aqua では依存は生じません。

$ brew install gpg gawk

.tool-versions を用意します。

nodejs 17.1.0

install コマンドを実行します

$ asdf install

aqua

aqua.yaml を用意します。

registries:
- type: standard
  ref: v0.10.18 # renovate: depName=aquaproj/aqua-registry

packages:
- name: nodejs/node@17.1.0

.tool-versions よりは冗長とは言えますが、だいぶ簡潔だとは思います。

install コマンドを実行します。

$ aqua i -l

plugin をインストールする必要がない分、簡単と言えます。

個人的にはやはり plugin を install しないといけないのがネックだなと感じます。あるリポジトリにある .tool-versions をみて、必要な plugin を install しないといけません。 plugin の URL も調べる必要があります。はじめて asdf 使うような人からすると、どうやるの？ってなってしまいます。

例えば Make task を作って plugin をインストールするようにするとか工夫しようはあると思いますが、そういうのが必要になってしまうのがネックかなと思います。

suzuki-shunsuke commented 2 years ago

ツールの検索

asdf

List plugins registered on asdf-plugins repository with URLs

$ asdf plugin list all

aqua

aqua g というコマンドで interactive に検索できます。 Registry はローカルにダウンロードされているので、非常に高速に動きます。

$ aqua g

suzuki-shunsuke commented 2 years ago

AWS CLI のインストール

asdf では AWS CLI 用の Plugin が存在しますが、 aqua の Standard Registry にはありません。というより aqua の仕組み上 AWS CLI は恐らくサポートできません。 asdf 便利ですね。

suzuki-shunsuke commented 2 years ago

tfcmt のインストール

aqua では tfcmt が Standard Registry にあるので、簡単にインストールできますが、 2021-12-09 現在、 asdf の tfcmt 用の plugin は恐らくないでしょう(ちゃんと調べてないけど)。このようにツールの対応状況はそれぞれ違います。ただし、 OSS であれば aqua で対応できるものは恐らく asdf でも plugin を作れば対応できるでしょう。

suzuki-shunsuke commented 2 years ago

ツールに対応する plugin がない場合の対応

asdf であれば plugin を自作することになるでしょう。 Repository Template があるので割と簡単に作れるかもしれませんが、それでも OSS 一つ作るというのはそれなりに手間がかかるものです。幾つも作るとなれば尚更です。

検索できるようにするには https://github.com/asdf-vm/asdf-plugins に追加する必要もあるようです。

aqua であれば Standard Registry に issue か PR を作ることになります。リポジトリ作ったり、 CI 整備したりドキュメント書いたり、メンテしたりという手間がないですし楽でしょう。同じリポジトリの他のコードを参考(コピペ)すれば割と簡単に追加できるはずです。

suzuki-shunsuke commented 2 years ago

インストール可能なツールのバージョンを調べる

asdf であれば次のようなコマンドでバージョンをリストアップできます。

$ asdf list all nodejs

一方で aqua にはそのようなコマンドがありません。 GitHub で公開されているツールであれば技術的には可能(というか昔は aqua g でバージョンを選べる UI だった)ですが、それ以外だと難しいです(それ以外のケースはあまりない気もしますが)。

じゃぁその機能をつけるかというと、まだ慎重なスタンスです。本当に必要か、ないと困るか見極めたいです。

suzuki-shunsuke commented 2 years ago

plugin (registry) のバージョン管理

aqua は aqua.yaml で Registry のバージョンも固定することを強制しています。これは高い再現性を保証します。ツールのバージョンが同じでも、 Registry のバージョンが違えば結果が変わりうるからです。そして Renovate を使って簡単に継続的にアップデートできます。

一方で asdf にはそのような仕組みはないように思えます。 plugin の update 自体はコマンドでできるようです。

asdf plugin update <name> [<git-ref>]   Update a plugin to latest commit on
                                        default branch or a particular git-ref
asdf plugin update --all                Update all plugins to latest commit on
                                        default branch

suzuki-shunsuke commented 2 years ago

GitHub Actions での利用

aqua

aqua には 2 つの GitHub Actions があり、どちらを使っても簡単に aqua とツールをインストールできます。どちらを使えばよいかというと、 int128/aqua-action のほうが簡単に使えるかと思います。 2 つの違いは aqua-installer はあくまで aqua をインストールするだけであり、ツールの install は実行しません。 aqua-action は aqua i の実行とキャッシュ、及び ~/.aqua/bin を PATH に追加までしてくれます。

asdf

使い方がパット見わかりにくいのですが、こんな感じで plugin の install まで含めてやってくれました。

https://github.com/asdf-vm/actions/blob/master/install/action.yml

asdf はデフォルトで master っぽいのであまり安全とは言えませんね。

    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: asdf_install
        uses: asdf-vm/actions/install@v1
      - run: node -v

plugin の install は .tool-versions からツールの一覧を抽出してインストールを実行していました。これはつまり、 asdf では .tool-versions に定義されている plugin を自動で install してくれるようなコマンドはないということだと思われます。 https://github.com/asdf-vm/actions/blob/b797cb8027b273ade6b7701ba2b4ce5fd1d477cb/lib/plugins-add/index.ts#L45-L62

suzuki-shunsuke commented 2 years ago

Renovate

aqua は Renovate による継続的なアップデートを推奨しており、簡単に update できる Preset Config を提供しています。しかし、公式の Manager のサポートはありません。

asdf も公式の Manager のサポートはありません。ただし、 issue はあるようです。 https://github.com/renovatebot/renovate/issues/4051 Preset Config はありませんし、仕組み上難しいでしょう。

ちなみに Dependabot を既に使っている場合でも、 aqua.yaml や .tool-versions などに限定して Renovate と併用することは可能です。

suzuki-shunsuke commented 2 years ago

https://zenn.dev/shunsuke_suzuki/articles/compare-aqua-with-asdf

suzuki-shunsuke / issue

[Draft] aqua と asdf を比較する #82

共通する部分

違い

plugin 機構

分散か中央集権か

学習コスト

本体のインストール

本体の install (Homebrew)

asdf

aqua

Node.js の Install

asdf

aqua

ツールの検索

asdf

aqua

AWS CLI のインストール

tfcmt のインストール

ツールに対応する plugin がない場合の対応

インストール可能なツールのバージョンを調べる

plugin (registry) のバージョン管理

GitHub Actions での利用

aqua

asdf

Renovate