💧

CLI Version Manager の aqua が Windows をサポート

2022/06/23に公開

CLI

CLI ツールを YAML でバージョン管理できるツール aqua を開発しています。

https://aquaproj.github.io/

https://zenn.dev/topics/aquaclivm

aqua が v1.12.0 から Windows をサポートしたので、そのことについて書きたいと思います。

公式ドキュメント

インストール・設定

使い方は基本的に macOS や Linux と変わりませんが、設定方法などが微妙に異なる部分もあるので説明していきます。

Install

GitHub Releases から asset をダウンロードして PATH 配下にバイナリを配置してください。

AQUA_ROOT_DIR

デフォルトで aqua がツールをインストールするディレクトリは
macOS, Linux では ${XDG_DATA_HOME:-$HOME/.local/share}/aquaproj-aqua ですが、
Windows では $HOME/AppData/Local/aquaproj-aqua です。

環境変数 AQUA_ROOT_DIR で変更できます。

PATH

PATH は Git Bash と Command Prompt, PowerShell で違います。

Command Prompt, PowerShell: AQUA_ROOT_DIR/bat
Git Bash: AQUA_ROOT_DIR/bin

AQUA_GLOBAL_CONFIG

Git Bash と Command Prompt, PowerShell で区切り文字が違います。これは PATH と同様です。

Command Prompt, PowerShell: ;
Git Bash: :

AQUA_GLOBAL_CONFIG では相対パスではなく絶対パスを指定してください。でないと設定ファイルを読み込めない場合があります。

Standard Registry のバージョン

Standard Registry は v2.28.1 以降(基本は最新)を推奨しています。
古いバージョンだと Windows だと上手く動かない場合があると思います。

Windows の設定

開発者モードは無効でも動きます。
また Terminal を管理者として実行しなくても動きます。

Windows Security の設定

aqua でインストールしたツールが Security Softare によって削除されたりする場合があります。
そういう場合、 AQUA_ROOT_DIR を除外すると削除されたりすることはないはずです。

Git Bash では `Enable experimental support for pseudo consoles` にチェックをつける

Git Bash で aqua g によるインタラクティブなツールの検索が動かない場合、
Git for Windows を再インストールして Enable experimental support for pseudo consoles にチェックをつけるか、別のターミナルエミュレータを使うと良いようです。

以下は GitHub CLI に関するエラーログですが、 aqua でも当てはまると思います。

You appear to be running in MinTTY without pseudo terminal support.

MinTTY is the terminal emulator that comes by default with Git
for Windows. It has known issues with gh's ability to prompt a
user for input.

There are a few workarounds to make gh work with MinTTY:

Reinstall Git for Windows, checking "Enable experimental support for pseudo consoles".

Use a different terminal emulator with Git for Windows like Windows Terminal.
You can run "C:\Program Files\Git\bin\bash.exe" from any terminal emulator to continue
using all of the tooling in Git For Windows without MinTTY.

Prefix invocations of gh with winpty, eg: "winpty gh auth login".
NOTE: this can lead to some UI bugs.

検証環境

以下の環境で検証を行っています。

Amazon Workspaces Standard with Windows 10 (Server 2019 based) (PCoIP)
GitHub Actions windows-latest (参考)

自分は普段 macOS で開発していて Windows マシンは持っていないので Amazon Workspaces で Windows のデスクトップ環境を用意しました。お手軽に用意できて便利ですね。

以下の Terminal を使って確認しています。

Command Prompt
PowerShell
Git Bash

上記のような環境で出来る限りの検証は行っていますが、 Windows Support は macOS や Linux と比べるとまだ信頼性が低いです。
自分は普段 Windows は使っていないのでバグってても気づきにくいですし、 Windows に関する知識も不足しています。

なのでバグっぽい挙動を見つけたら教えてもらえると助かります。
Windows ユーザーの方のフィードバックをお待ちしています。

ツールのサポート状況

これは aqua の問題ではないですが、インストール対象のツールが Windows をサポートしていないケースは結構あります。
aqua にはサポートしていないプラットフォームではツールのインストールをスキップする仕組みがあります。

例えば 1xyz/pryrite 0.10.20 には Windows 用の asset がありません。

そこで次のような設定で Windows ではインストールがスキップされるようになっています。

次のような aqua.yaml を使って aqua i を実行した場合、 macOS や Linux では pryrite がインストールされますが、 Windows ではインストールされません(skip されるだけでコマンドは正常終了します)。

registries:
- type: standard
  ref: v3.0.0
packages:
- name: 1xyz/pryrite@0.10.20

Windows でツールがインストールされないなと思ったら、 Windows 用の asset が存在するか、インストールがスキップされるようになってないか確認してください。

シェルスクリプトは現状サポート対象外

シェルスクリプトで実装されたツールは現在サポート対象外になっています。

Windows だとシェルスクリプトの絶対パスを指定して Go の os/exec で実行しようとしても実行できないようです。
これは単に拡張子 .sh をつけても同じです。 shebang も効かないようです。
bash か何かシェルにシェルスクリプトを引数として渡せば実行できると思いますが、なんのシェルを指定するかは環境に依存する部分ですし、
どうするのが適当なのかよくわからないので、一旦未対応ということにしています。
適切な対応方法が決まれば対応するかもしれません。

Windows Support のための機能

Windows をサポートするために追加した機能を紹介します。

拡張子 `.exe` の自動補完

Windows では実行ファイルに拡張子 .exe がつくことが多いです。
ですが、 Registry の定義で一々 Windows 向けに .exe をつける設定を書くのは面倒(これは既存の 500 以上のツールに対する修正コストも含んだ話です)なので、自動で .exe を補完するようになっています。ただし、自動補完されないパターンもあるのでそういう場合は Registry の定義を修正して拡張子をつけるようにします。

ツールの中には拡張子がついてない状態で配布されているものもありますが、そのままだと Windows では実行できないはずです。

os/exec の Cmd.Start では os/exec#LookPath が呼ばれているのですが、拡張子がない場合自動で .exe などの拡張子を補完してファイルを探索するようになっています。
そのため、拡張子がない場合ファイルが見つからずにコマンドの実行に失敗します。
興味のある方は os/exec のコードを確認してください。

例えば argo-rollouts v1.2.1 を見ると kubectl-argo-rollouts-windows-amd64 となっていて拡張子がついていません。

なので aqua が自動でリネームして拡張子(デフォルトで .exe) をつけるようになっています。

シンボリックリンクと aqua-proxy の代わりにスクリプトを使う

macOS, Linux では上記の PATH のディレクトリに symbolic link を作成し、 aqua-proxy を仲介して aqua exec を実行し、ツールを実行します。

ツールを直接実行する代わりに aqua を仲介することでツールのバージョンを動的に変更しています。

Windows ではシンボリックリンクと aqua-proxy の代わりにスクリプトを PATH のディレクトリに生成します。これは Windows ではシンボリックリンクに関して以下のような問題があるからです。

シンボリックリンクを作成するには、開発者モードを有効にするか terminal を管理者として実行する必要がある
シンボリックリンクを複数経由してコマンドを実行する場合、 PowerShell だと正常に動作しないバグがある

そこで以下のようなスクリプトをツールごとに作成しています。

AQUA_ROOT/bat 配下 (BAT スクリプト)

@echo off
aqua exec -- <COMMAND> %* # <COMMAND> は生成時に置換

AQUA_ROOT/bin 配下 (シェルスクリプト)

#!/usr/bin/env bash
exec aqua exec -- $0 $@

中身は単純で aqua exec を呼んでいるだけですが、 aqua-proxy がやっていることはこれとほぼ変わりません。

さいごに

以上、 aqua の Windows サポートについて紹介しました。
何か問題などが見つかりましたら https://github.com/aquaproj/aqua/issues (可能な限り Issue Template を使ってください) で報告してもらえると助かります。
Windows をサポートすることでより多くの人、プロジェクト、チーム、組織で aqua が使われると幸いです。