More than 1 year has passed since last update.

複数のランタイムバージョンをプロジェクト単位で管理できる asdf の紹介

Last updated at 2023-05-19Posted at 2023-05-19

はじめに

この資料は asdf について公式ドキュメンをもとに紹介するものです。
誤訳や解釈の間違いが含まれている可能性があることに注意してください。
これから利用する方々の助けになれば幸いです。

asdf について

asdf は、python や Go などのプログラミング言語に加え、awscli や terraform などの様々なツールのランタイムバージョンをプロジェクト単位で管理できるCLIツールです。使用する言語のプラグインをインストールするだけで、複数のランタイムバージョンを単一のCLIツールで管理できるようになります。

特徴

anyenv よりも高速に動作します。
一つのCLIで多言語対応できます。
すべての言語を管理するための一貫したコマンドを提供。
単一のグローバル設定ファイルにより、デフォルトを一カ所に保持
プロジェクトごとに .tool-versions 設定ファイルを1つだけ用意する
既存の設定ファイルである .node-version, .nvmrc, .ruby-version をサポートし、簡単に移行できる。
ディレクトリを移動すると自動的にランタイムバージョンが切り替わります。
シンプルなプラグインシステムにより、お好みの言語へのサポートを追加できます。
一般的なシェル（Bash、Zsh、Fish、Elvish）で利用可能なシェル補完機能

asdf の動作概要

asdf を理解するために、まず基本的な項目について説明します。

PATHを理解する

python や pip などのコマンドを実行すると、オペレーティングシステムはディレクトリのリストを検索して、その名前の実行ファイルを探します。このディレクトリのリストは、環境変数 PATH に格納され、リスト内の各ディレクトリはコロン（:）で区切られています：

/usr/local/bin:/usr/bin:/bin

PATH 内のディレクトリは左から右に検索されるため、リストの先頭にあるディレクトリにある実行ファイルが一致すれば、末尾にある他の実行ファイルよりも優先されます。この例では、まず /usr/local/bin ディレクトリが検索され、次に /usr/bin、そして /bin が検索されます。

shimsを理解する

asdf は $PATH の前に shims のディレクトリを挿入することで動作します：

$ASDF_DIR/shims:/usr/local/bin:/usr/bin:/bin

asdf はプラグインとよばれるツールを通じてインストールされたすべての言語やツールのランタイムバージョンをこのディレクトリに shim として維持しています。

shims はシンプルで軽量な実行スクリプトで、プラグインを追加したときに自動的に追加されます。
例えば python3 を実行すると、OSは次のような処理を行います：

python3 という名前の実行バイナリを PATH から探す。
PATH の検索順序により $ASDF_DIR/shims/python3 が最初に見つかる
$ASDF_DIR/shims/python3 を実行する
- 正常にランタイムパスが取得できれば、exec でプロセスをリプレースする。

ランタイムのバージョン選択を理解する

shimを実行するとき、asdf は以下の情報を順番で読み込んで、どのバージョンのランタイムを使用するかを決定します：

環境変数 ASDF_${TOOL}_VERION (指定されている場合)
asdf shell コマンドで現在のシェルセッションで環境変数が設定されます。
カレントディレクトリのアプリケーション固有の .tool-versions ファイル。 (存在する場合)
asdf local コマンドでカレントディレクトリの .tool-versions ファイルを変更することができます。
ファイルシステムのルートに到達するまで、各親ディレクトリを検索して最初に見つかった .tool-versions ファイル。 (存在する場合)
グローバルな ~/.tool-versions ファイル。
このファイルは asdf global コマンドで変更することができます。
グローバルバージョンファイルが存在しない場合、asdf は system の Python を使用したいものとみなします。

特別なバージョン名 "system" は、shims の PATH エントリの後側の PATH で見つかるあらゆるランタイムを使用することを意味します。つまり、asdf shims が PATH になかった場合に実行されるランタイムです。

例えば macOS を使っていて、OS にバンドルされた Python 3.9.6 と Homebrew にインストールされた Python 3.9.12 と 3.10.2 がある場合、asdf にとってはこれはまだ単一の system バージョンであり、PATH で最初に指定した実行ファイル名で存在するものが実行されます。

つまり、shimは指定されているバージョンが system の場合、PATH上のさらに他のものにもフォールスルーします。これにより、システム上の他の場所にインストールされた任意のプログラムを使用することができます。

asdfが提供するランタイムのインストール先

asdf は、プラグインを通して言語やツールのランタイムをインストールします。デフォルトでは、次のディレクトリに配置されます。

$ASDF_DIR/installs/<PLUGIN_NAME>/<VERSION>

anyenv のアンインストール

類似プロジェクトの anyenv を使用していない場合は、このセクションをスキップしてください。

既に anyenv を使用している場合は、まず削除しておくと混乱が少なくなります。

PATHから呼び出せないようにする（共通）

シェルの設定ファイル（~/.<SHELL>rc など）からPATHを設定した行を削除してください。

<SHELL> は　bash や zsh に置き換えてください。

export PATH="$HOME/.anyenv/bin:$PATH"

anyenv を初期化している行を削除してください。

eval "$(anyenv init -)"

homebrew 経由でインストールした場合

anyenv 自体を削除したくない場合は、スキップしてかまいません。

$ brew uninstall anyenv

GitHub をクローンしてインストールした場合

anyenv 自体を削除したくない場合は、スキップしてかまいません。

$ rm -rf ~/.anyenv

アンインストールをチェック

シェルを再起動して次のコマンドでアンインストールをチェックしてください。

$ exec $SHELL -l
$ which anyenv
anyenv not found

インストール

asdf 本体のインストールgithub リポジトリをクローンするだけです。

$ git clone https://github.com/asdf-vm/asdf.git ~/.asdf

使用しているシェルにより呼び出すファイルが異なります。

bash, zsh, posix shell

シェル設定ファイルに以下を追加します。
- bash: ~/.bashrc
- zsh：~/.zshrc
- posix shell：~/.profile

export ASDF_DIR=$HOME/.asdf
source $ASDF_DIR/asdf.sh

PowerShell
シェル設定ファイルに以下を追加します。
- powershell: ~/.config/powershell/profile.ps1

    . "$HOME/.asdf/asdf.ps1"

シェル自動補完

Bash と Zsh では自動補完をさせることができます。
シェル設定ファイルに以下を追加します。

bash： ~/.bashrc

. "$HOME/.asdf/completions/asdf.bash"

zsh： ~/.zshrc

fpath=(${ASDF_DIR}/completions $fpath)
autoload -Uz compinit && compinit

依存パッケージをシステムに追加

プラグインを利用するために依存するパッケージをインストールする必要があります。

Ubuntu / Debian
```
apt install dirmngr gpg curl gawk
```

CentOS / Rocky Linux / AlmaLinux

yum install gnupg2 curl gawk
# あるいは
dnf install gnupg2 curl gawk

macOS
```
brew install gpg gawk
```

設定

asdf の設定は ~/.asdfrc ファイルを作成することで変更することができます。

anyenvのような別のバージョン管理ツールを使用していた場合には、legacy_version_file を yes で設定しておくことをおすすめします。

legacy_version_file
yes に設定すると、この機能をサポートしているプラグインが、他のバージョン管理ツールで使用されているバージョンファイルを読み取るようになります。
.python-version など
デフォルト： no
use_release_candidates
asdf update コマンドが最新のセマンティックバージョンではなく、最新のリリースのバージョンにアップグレードするようになります。
デフォルト： no
always_keep_download
yes に設定すると、asdf install がダウンロードしたソースコードやバイナリを常に保持するようになります。no に設定すると、asdf installがダウンロードしたソースコードやバイナリは、インストールが成功した後に削除されます。
デフォルト： no
plugin_repository_last_check_duration
asdfプラグインのリポジトリの最終チェック時間が設定されます。
asdf plugin add , asdf plugin list all コマンドが実行されたとき、リポジトリを更新するために最終更新時間をチェックします。ゼロ（0）に設定されていると、毎回asdfプラグインのリポジトリを更新します。
デフォルト： 60min

環境変数

ASDF_CONFIG_FILE
設定ファイルのパスを指定する
デフォルト： ~/.asdfrc
ASDF_DEFAULT_TOOL_VERSIONS_FILENAME
パッケージの情報の設定ファイルの名前を変更する
基本的には変更しないことが推奨されている
デフォルト： .tool-versions
ASDF_DIR
asdf のスクリプトを保存するディレクトリのパスを指定
デフォルト： ~/.asdf
ASDF_DATA_DIR
asdf のプラグインやパッケージを保存するディレクトリのパスを指定
デフォルト： ~/.asdf

使用方法

ヘルプ表示

引数を与えずに実行するとヘルプメッセージが表示されます。

$ asdf

asdfで言語やツールのバージョン管理を行うためには、まず始めに各言語やツールに対応したプラグインをインストールする必要があります。

プラグインの一覧

プラグインは次のコマンドで一覧できます。

$ asdf plugin list all

代表的なものをリストアップします。

$ asdf plugin list all | egrep "node|deno|python|ruby"
deno                          https://github.com/asdf-community/asdf-deno.git
nodejs                        https://github.com/asdf-vm/asdf-nodejs.git
python                        https://github.com/danhper/asdf-python.git
ruby                          https://github.com/asdf-vm/asdf-ruby.git

実は、これは ~/.asdf/repository/plugins の内容を参照しているだけなので、直接このディレクトリを参照しても利用可能なプラグインを知ることができます。

$ cat  ~/.asdf/repository/plugins/python
repository = https://github.com/danhper/asdf-python.git

プラグインを追加

例えば python プラグインを追加する場合は、次のようになります。

$ asdf plugin add python

インストール済みのプラグインを参照

インストール済みのプラグインは次のコマンドで参照することができます。

$ asdf plugin list
python
  No versions installed

ランタイムをインストール

インストール可能なバージョンを一覧したいときは、次のようにコマンドを実行します。

$ asdf list all python

最新バージョンの　python をインストールするためには、次のようにコマンドを実行します。

$ asdf install python latet

インストール可能なバージョンな最新バージョンを確認するときは、次のように実行します。

出力はこの資料作成時でのバージョンです。

$ asdf latest python
3.11.3

$ asdf latest python 3.10
3.10.11

$ asdf latest python miniforge
miniforge3-22.11.1-4

インストール可能なバージョンを一覧から特定のバージョンを指定してインストールすることができます。

$ asdf install python miniforge3-22.11.1-4

注意：
Anaconda Python (miniconda, miniforge 含む）をインストールした場合は、conda のbase環境がデフォルトで有効にならないようにしてください。
conda config --set auto_activate_base false

ランタイムののインストール

プラグインがあれば言語に限らずツールのバージョンも管理させることもできます。

例えば、Python のパッケージマネージャー　pdm をインストールする場合は、次のように実行します。

$ asdf plugin add pdm 
$ asdf install pdm latest

バージョンを参照する

asdf list を実行すると、インストールされている言語やツールを参照することができます。

$ asdf list
pdm
 *2.6.1
python
  3.10.11
 *3.11.3
  3.9.16
  miniforge3-22.11.1-4

ここでアスタリスク（*）がついているものが現在有効なバージョンです。

現在設定されてるバージョンを参照したい場合は、asdf current コマンドを実行します。

$ asdf current
neovim          0.9.0           /Users/goichiiisaka/.tool-versions
pdm             2.6.1           /Users/goichiiisaka/.tool-versions
python          3.10.11         ASDF_PYTHON_VERSION environment variable

バージョンの選択は、カレントディレクトリにある .tool-versions ファイルが参照されます。

pyenv などで使用していた .python-version ファイルもサポートしたい場合は、~/.asdfrc に以下を追加してください。

legacy_version_file = yes

バージョンを選択する

使用するランタイムのバージョンを選択する場合は、global , shell , local の3種類の方法があります。

コマンド	設定ファイル/環境変数	説明
global	~/.tool-versions	指定がない場合に使用するバージョンを設定
shell	ASDF_${TOOL}_VERION	使用している shell の時だけバージョンを変更したい場合
local	$PWD/.tool-versions	特定のディレクトリ内でだけバージョンを変更したい場合

例えば、プロジェクトのディレクトリにいるときだけ指定したPythonが有効になるようにする例です。

$ asdf local python 3.11.3

この他に、system という特別なバージョン指定ができます。このバージョンを指定した場合は、$ASDF_DIR/shms を $PATH から削除して見つかるランタイムが実行されます。

独自プラグインの作成

asdf にはコミュニティーによるバラエティーのある多数のプラグインが公開されています。もし希望のプラグインがない場合は簡単に作成することができます。

プラグインの実態は、言語/ツールのバージョン管理をサポートする実行可能なスクリプトを含むGitリポジトリです。これらのスクリプトは、asdf list-all <name> , asdf install <name> <version> などの機能をサポートする特定のコマンドを使用してasdfによって呼び出されます。

クイックスタート

独自のプラグインの作成を始めるには、2つのオプションがあります：

[asdf-vm/asdf-plugin-template](https://github.com/asdf-vm/asdf-plugin-template) リポジトリを使用して、デフォルトのスクリプトが実装されたプラグインのリポジトリをasdf-<tool_name>という名前で生成します。生成されたら、そのリポジトリをクローンし、setup.bash スクリプトを実行して、テンプレートをインタラクティブに更新します。
必要なスクリプトを実装していきます。

プラグインスクリプトの大原則

スクリプトは他のasdfコマンドを呼び出してはいけない。
シェルやツール/コマンドの依存関係を小さくする。
移植不可能なツールやコマンドフラグを避ける。
例えば、sort -V など。asdfコアで禁止されたコマンドのリストを参照してください。

プラグインスクリプト

asdfから呼び出し可能なスクリプトの全リストです。

スクリプト	説明
bin/list-all	インストール可能な全バージョンをリストアップする　（必須）
bin/download	指定したバージョンのソースコードまたはバイナリをダウンロードする (必須）
bin/install	指定されたバージョンをインストールする (必須)
bin/latest-stable	指定されたツールの最新の安定版をリストアップする (推奨）
bin/help.overview	プラグインとツールに関する一般的な説明を出力する
bin/help.deps	オペレーティング・システムごとの依存関係のリストを出力する
bin/help.config	プラグインまたはツールの設定情報を出力する
bin/help.links	プラグインまたはツールのリンクのリストを出力する
bin/list-bin-paths	shimを作成するためのバイナリを含むディレクトリへの相対パスのリスト
bin/exec-env	バイナリを実行するための環境を準備する
bin/exev-path	あるバージョンのツールの実行可能パスを出力する
bin/uninstall	特定のバージョンのツールをアンインストールする
bin/list-regacy-filenames	レガシーバージョンファイルのファイル名を出力する例: .ruby-version
bin/parse-legacy-file	レガシーバージョンファイル用のカスタムパーサー
bin/post-plugin-add	プラグインが追加された後に実行されるフック
bin/post-plugin-update	プラグインが更新された後に実行されるフック
bin/post-plugin-remove	プラグインが削除される前に実行するフック

スクリプトで使用される環境変数

すべてのスクリプトで使用される環境変数の全リストです。

環境変数	説明
ASDF_INSTALL_TYPE	`version` あるいは `ref`
ASDF_INSTALL_VERSION	ASDF_INSTALL_TYPE に応じた完全なバージョン
ASDF_INSTALL_PATH	ツールがインストールされるべき、またはインストールされている場所へのパス
ASDF_CONCURRENCY	ソースコードのコンパイル時に使用するコア数。 make -jの設定に便利
ASDF_DOWNLOAD_PATH	`bin/download` でダウンロードされたソースコードまたはバイナリがのパス。
ASDF_PLUGIN_PATH	プラグインがインストールされたパス
ASDF_PLUGIN_SOURCE_URL	プラグインのソースURL
ASDF_PLUGIN_PREV_REF	プラグインリポジトリの以前の git-ref
ASDF_PLUGIN_POST_REF	プラグインリポジトリの更新された git-ref
ASDF_CMD_FILE	ソースされるファイルのフルパス

必須スクリプト

bin/list-all

説明
インストール可能な全バージョンをリストアップします。
出力形式
スペースで区切られたバージョンのリストを文字列で出力する必要があります。例えば、以下のようになります：
```
1.0.1 1.0.2 1.3.0 1.4
```
最も新しいバージョンが最後になるようにする。

asdf coreは各バージョンを1行で表示するため、いくつかのバージョンを画面外に押し出す可能性があります。
ソート
もしバージョンがウェブサイトのリリースページから引き出されるのであれば、提供された順序のままにしておくことをお勧めします。もし逆順の場合は、tac を通すことで十分です。

どうしてもソートが必要な場合、sort -V は移植性に欠けるので、次のいずれかをお勧めします：
- Git のソート機能を使う (Git >= v2.18.0 が必要です)
- 独自のソート方法を書く（sed, sort & awkが必要です）
スクリプトで使用可能な環境変数

このスクリプトには環境変数がありません。
このスクリプトを呼び出すコマンド
- asdf list all <name> [version]
- asdf list all nodejs
  このスクリプトが返したすべてのバージョンを1行に1つずつリストアップする。
- asdf list all nodejs 18
  このスクリプトが返したすべてのバージョンを1行ずつリストアップし、18で始まるバージョンにマッチするフィルターを適用します。
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}/bin/list-all"
```

bin/download

説明
ツールの特定のバージョンのソースコードまたはバイナリを指定された場所にダウンロードします。
実装の詳細
- スクリプトは、環境変数 ASDF_DOWNLOAD_PATH で指定されたディレクトリに、解凍されたソースコードまたはバイナリのみが配置される必要があります。
- 失敗した場合、ASDF_DOWNLOAD_PATH にファイルは配置されないはずです。
- 成功した場合は、終了コード 0 で終了します。
- 失敗した場合は、0 以外の終了コードで終了する必要があります。
レガシープラグイン
****このスクリプトはすべてのプラグインに必須ですが、このスクリプトが導入される以前のレガシープラグインではオプションになります。
スクリプトで使用可能な環境変数
- ASDF_INSTALL_TYPE
  version または ref
- ASDF_INSTALL_VERSION
  ASDF_INSTALL_TYPE=version の場合、完全なバージョン番号。
  ASDF_INSTALL_TYPE=ref の場合、Git ref (tag/commit/branch)。
- ASDF_INSTALL_PATH
  ツールがインストールされている、またはインストールされるべき場所へのパス。
- ASDF_DOWNLOAD_PATH
  ソースコードまたはバイナリがダウンロードされた場所へのパスです。
このスクリプトを呼び出すコマンド
- asdf install <tool> [version]
- asdf install <tool> latest[:version]
- asdf install nodejs 18.0.0
  Node.jsバージョン18.0.0のソースコードまたはバイナリをダウンロードし、環境変数ASDF_DOWNLOAD_PATH ディレクトリに配置します。
  そして、bin/install スクリプトを実行します。
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}"/bin/download
```

bin/install

説明
ツールの特定バージョンを指定した場所にインストールします。
実装の詳細
- スクリプトは、指定されたバージョンを環境変数 ASDF_INSTALL_PATH で定義されているパスにインストールする必要があります。
- Shimは、$ASDF_INSTALL_PATH/bin にあるすべてのファイルに対してデフォルトで作成されます。この動作は、オプションの bin/list-bin-paths スクリプトでカスタマイズすることができます。
- 成功した場合は、終了コード 0 で終了します。
- 失敗した場合は、0 以外の終了コードで終了する必要があります。
- TOCTOU (Time-of-Check-to-Time-of-Use) 問題を避けるために、ツールのビルドとインストールが成功したとみなされると、スクリプトが ASDF_INSTALL_PATH にファイルを置くことを確認します。
レガシープラグイン
bin/download スクリプトがない場合、このスクリプトは指定されたバージョンをダウンロードし、インストールする必要があります。
asdfコアの0.7._より前のバージョンと0.8._より新しいバージョンとの互換性のために、環境変数 ASDF_DOWNLOAD_PATH が存在するかどうかを確認します。もし設定されていれば、bin/download スクリプトがすでにそのバージョンをダウンロードしたと仮定し、そうでなければ bin/install スクリプトでソースコードをダウンロードします。
スクリプトで使用可能な環境変数
- ASDF_INSTALL_TYPE
  version または ref
- ASDF_INSTALL_VERSION
  - ASDF_INSTALL_TYPE=version の場合、完全なバージョン番号。
  - ASDF_INSTALL_TYPE=ref の場合、Git ref (tag/commit/branch)。
- ASDF_INSTALL_PATH
  ツールがインストールされている、またはインストールされるべき場所へのパス。
- ASDF_CONCURRENCY
  ソースコードをコンパイルするときに使用するコア数。
  make -j のようなフラグを設定するのに便利です。
- ASDF_DOWNLOAD_PATH
  ソースコードまたはバイナリがダウンロードされた場所へのパスです。
このスクリプトを呼び出すコマンド
- asdf install
- asdf install <tool>
- asdf install <tool> [version]
- asdf install <tool> latest[:version]
- asdf install nodejs 18.0.0
  Node.jsバージョン18.0.0を、環境変数ASDF_INSTALL_PATH ディレクトリに配置します。
asdfコアからの呼び出し
パラメータは提供されません。
```
${plugin_path}"/bin/install
```

オプションのスクリプト

bin/latest-stable

説明
ツールの最新の安定版を決定します。このスクリプトは推奨です。
このスクリプトが存在しない場合は、asdfコアは bin/list-all の末尾行を参照するため、好ましくない結果になるかもしれません。
実装の詳細
- このスクリプトは、ツールの最新の安定版を標準出力に出力する必要があります。
- 非安定版やリリース候補版は省略されるべきです。
- スクリプトの最初の引数として、フィルタクエリが提供されます。これは、バージョン番号やツールのプロバイダーによって出力をフィルタリングするために使用されます。
  例えば、asdf list all ruby の出力は、ruby プラグインにより jruby、rbx、trufflerubyなど、多くのプロバイダーからのRubyのバージョンをリストアップします。
  ユーザが提供するフィルタは、プラグインがsemver のバージョンやプロバイダをフィルタリングするために使用することができます。
```
> asdf latest ruby
3.2.2
> asdf latest ruby 2
2.7.8
> asdf latest ruby truffleruby
truffleruby+graalvm-22.3.1
```
- 成功した場合は、終了コード 0 で終了します。
- 失敗した場合は、0 以外の終了コードで終了する必要があります。
レガシープラグイン
bin/download スクリプトがない場合、このスクリプトは指定されたバージョンをダウンロードし、インストールする必要があります。
asdfコアの0.7._より前のバージョンと0.8._より新しいバージョンとの互換性のために、環境変数 ASDF_DOWNLOAD_PATH が存在するかどうかを確認します。もし設定されていれば、bin/download スクリプトがすでにそのバージョンをダウンロードしたと仮定し、そうでなければ bin/install スクリプトでソースコードをダウンロードします。
スクリプトで使用可能な環境変数
- ASDF_INSTALL_TYPE
  version または ref
- ASDF_INSTALL_VERSION
  ASDF_INSTALL_TYPE=version の場合、完全なバージョン番号。
  ASDF_INSTALL_TYPE=ref の場合、Git ref (tag/commit/branch)。
- ASDF_INSTALL_PATH
  ツールがインストールされている、またはインストールされるべき場所へのパス。
このスクリプトを呼び出すコマンド
- asdf global <tool> latest
  ールのグローバルバージョンを、そのツールの最新の安定バージョンに設定する。
- asdf local <name> latest
  ツールのローカルバージョンをそのツールの最新の安定バージョンに設定する。
- asdf install <tool> latest
  ツールの最新バージョンをインストールする。
- asdf latest <tool> [<version>]
  オプションのフィルターに基づいて、ツールの最新バージョンを出力する。
- asdf latest --all
  asdfが管理するすべてのツールの最新バージョンと、それらがインストールされているかどうかを出力する。
asdfコアからの呼び出し
このスクリプトは、単一の引数であるフィルタクエリを受け取る必要があります。
```
"${plugin_path}"/bin/latest-stable ""
"${plugin_path}"/bin/latest-stable "$query"
```

bin/help.overview

説明
プラグインと管理されているツールに関する一般的な説明を出力します。
実装の詳細
- このスクリプトは、プラグインのヘルプ出力を表示するために必要です。
- asdf coreが見出しを印刷するので、見出しを印刷する必要はありません。
- 出力は自由形式のテキストでもよいが、理想的には1つの短いパラグラフだけでです。
- コアのasdf-vmドキュメントですでにカバーされている情報を出力してはいけません。
- インストールされるオペレーティングシステムとツールのバージョンに合わせてください。
  オプションで設定された環境変数 ASDF_INSTALL_VERSION と ASDF_INSTALL_TYPE を使用します。
- 成功した場合は、終了コード 0 で終了します。
- 失敗した場合は、0 以外の終了コードで終了する必要があります。
スクリプトで使用可能な環境変数
- ASDF_INSTALL_TYPE
  version または ref
- ASDF_INSTALL_VERSION
  - ASDF_INSTALL_TYPE=version の場合、完全なバージョン番号。
  - ASDF_INSTALL_TYPE=ref の場合、Git ref (tag/commit/branch)。
- ASDF_INSTALL_PATH
  ツールがインストールされている、またはインストールされるべき場所へのパス。
このスクリプトを呼び出すコマンド
- asdf help <name> [<version>]
  プラグインやツールのドキュメントを出力する
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}"/bin/help.overview
```

bin/help.deps

説明
オペレーティングシステムに合わせた依存関係のリストを出力します。
1行に1つの依存関係を出力します。
```
git
curl
sed
```
実装の詳細
- このスクリプトは、その出力を考慮するために、bin/help.overview を必要とします。
- インストールされるオペレーティングシステムとツールのバージョンに合わせてください。
  オプションで設定された環境変数 ASDF_INSTALL_VERSION と ASDF_INSTALL_TYPE を使用します。
- 成功した場合は、終了コード 0 で終了します。
- 失敗した場合は、0 以外の終了コードで終了する必要があります。
スクリプトで使用可能な環境変数
- ASDF_INSTALL_TYPE
  version または ref
- ASDF_INSTALL_VERSION
  - ASDF_INSTALL_TYPE=version の場合、完全なバージョン番号。
  - ASDF_INSTALL_TYPE=ref の場合、Git ref (tag/commit/branch)。
- ASDF_INSTALL_PATH
  ツールがインストールされている、またはインストールされるべき場所へのパス。
このスクリプトを呼び出すコマンド
- asdf help <name> [<version>]
  プラグインやツールのドキュメントを出力する
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}"/bin/help.deps
```

bin/help.config

説明
プラグインやツールに必要な設定やオプションの設定を出力します。
例えば、ツールのインストールやコンパイルに必要な環境変数やその他のフラグを記述します。
実装の詳細
- このスクリプトは、その出力を考慮するために、bin/help.overview を必要とします。
- 出力は自由形式のテキストにすることができます
- インストールされるオペレーティングシステムとツールのバージョンに合わせてください。
  オプションで設定された環境変数 ASDF_INSTALL_VERSION と ASDF_INSTALL_TYPE を使用します。
- 成功した場合は、終了コード 0 で終了します。
- 失敗した場合は、0 以外の終了コードで終了する必要があります。
スクリプトで使用可能な環境変数
- ASDF_INSTALL_TYPE
  version または ref
- ASDF_INSTALL_VERSION
  - ASDF_INSTALL_TYPE=version の場合、完全なバージョン番号。
  - ASDF_INSTALL_TYPE=ref の場合、Git ref (tag/commit/branch)。
- ASDF_INSTALL_PATH
  ツールがインストールされている、またはインストールされるべき場所へのパス。
このスクリプトを呼び出すコマンド
- asdf help <name> [<version>]
  プラグインやツールのドキュメントを出力する
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}"/bin/help.config
```

bin/help.links

説明
プラグインやツールに関連するリンクのリストを出力します。
1行に1リンクです。
```
Git Repository:	https://github.com/vlang/v
Documentation:	https://vlang.io
```
実装の詳細
- このスクリプトは、その出力を考慮するために、bin/help.overview を必要とします。
- 1行に1リンクで出力する。
- s出力形式は以下のいずれかである必要があります。
  - <title>: <link>
  - <link> のみ
- インストールされるオペレーティングシステムとツールのバージョンに合わせてください。
  オプションで設定された環境変数 ASDF_INSTALL_VERSION と ASDF_INSTALL_TYPE を使用します。
- 成功した場合は、終了コード 0 で終了します。
- 失敗した場合は、0 以外の終了コードで終了する必要があります。
スクリプトで使用可能な環境変数
- ASDF_INSTALL_TYPE
  version または ref
- ASDF_INSTALL_VERSION
  - ASDF_INSTALL_TYPE=version の場合、完全なバージョン番号。
  - ASDF_INSTALL_TYPE=ref の場合、Git ref (tag/commit/branch)。
- ASDF_INSTALL_PATH
  ツールがインストールされている、またはインストールされるべき場所へのパス。
このスクリプトを呼び出すコマンド
- asdf help <name> [<version>]
  プラグインやツールのドキュメントを出力する
asdfコアからの呼び出し
パラメータは提供されません。
```
${plugin_path}"/bin/help.links
```

bin/list-bin-paths

説明
指定されたバージョンのツールの実行ファイルを含むディレクトリを一覧表示します。
実装の詳細
- このスクリプトが存在しない場合、asdfは "${ASDF_INSTALL_PATH}"/bin ディレクトリにあるバイナリを探し、それらのためのshimを作成します。
- 実行ファイルを含むパスをスペースで区切ったリストを出力する。
- パスは環境変数 ASDF_INSTALL_PATH からの相対パスである必要があります。
  出力例は以下の通りです：
```
bin tools veggies
```
- このスクリプトは、以下のファイルの shim を作成するようにasdfに対して指示します
- "${ASDF_INSTALL_PATH}"/bin
- "${ASDF_INSTALL_PATH}"/tools
- "${ASDF_INSTALL_PATH}"/veggies
スクリプトで使用可能な環境変数
- ASDF_INSTALL_TYPE
  version または ref
- ASDF_INSTALL_VERSION
  - ASDF_INSTALL_TYPE=version の場合、完全なバージョン番号。
  - ASDF_INSTALL_TYPE=ref の場合、Git ref (tag/commit/branch)。
- ASDF_INSTALL_PATH
  ツールがインストールされている、またはインストールされるべき場所へのパス。
このスクリプトを呼び出すコマンド
- asdf install <tool> [version]
  最初にバイナリの shim を作成する。
- asdf reshim <tool> <version>
  バイナリの shim を再作成する。
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}/bin/list-bin-paths"
```

bin/exec-env

説明
ツール用バイナリの shim を実行する前に、環境を整えます。
スクリプトで使用可能な環境変数
- ASDF_INSTALL_TYPE
  version または ref
- ASDF_INSTALL_VERSION
  - ASDF_INSTALL_TYPE=version の場合、完全なバージョン番号。
  - ASDF_INSTALL_TYPE=ref の場合、Git ref (tag/commit/branch)。
- ASDF_INSTALL_PATH
  ツールがインストールされている、またはインストールされるべき場所へのパス。
このスクリプトを呼び出すコマンド
- asdf which <command>
  実行ファイルへのパスを表示する
- asdf exec <command> [args...]
  現在のバージョンに対応したshimコマンドを実行する
- asdf env <command> [util]
  コマンドを実行する
  コマンド shim の実行に使用する環境内で util を実行する（デフォルトはenv）。
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}/bin/exec-env"
```

bin/exec-path

説明
指定されたバージョンのツールの実行可能パスを取得します
実装の詳細
- 相対的な実行可能パスを文字列で出力する必要があります。
- 条件付きでshimの指定した実行可能パスを上書きし、それ以外はshimの指定したデフォルトパスを返す必要があります。
```
Usage:
  plugin/bin/exec-path <install-path> <command> <executable-path>

Example Call:
  ~/.asdf/plugins/foo/bin/exec-path "~/.asdf/installs/foo/1.0" "foo" "bin/foo"

Output:
  bin/foox
```
スクリプトで使用可能な環境変数
- ASDF_INSTALL_TYPE
  version または ref
- ASDF_INSTALL_VERSION
  - ASDF_INSTALL_TYPE=version の場合、完全なバージョン番号。
  - ASDF_INSTALL_TYPE=ref の場合、Git ref (tag/commit/branch)。
- ASDF_INSTALL_PATH
  ツールがインストールされている、またはインストールされるべき場所へのパス。
このスクリプトを呼び出すコマンド
- asdf which <command>
  実行ファイルへのパスを表示する
- asdf exec <command> [args...]
  現在のバージョンに対応したshimコマンドを実行する
- asdf env <command> [util]
  コマンドを実行する
  コマンドシムの実行に使用する環境内で util を実行する（デフォルトは env）。

asdfコアからの呼び出し
パラメータは提供されません。

"${plugin_path}/bin/exec-path" "$install_path" "$cmd" "$relative_path"

bin/uninstall

説明
提供されているバージョンのツールをアンインストールする。
出力形式
このスクリプトの出力は，ユーザにとって適切なように stdout または stderr に送られる必要があります。
コアでの後続の実行によって出力が読み取られることはありません。。
スクリプトで使用可能な環境変数

このスクリプトには、環境変数は用意されていません。
このスクリプトを呼び出すコマンド
- asdf list all <name> <version>
- asdf uninstall nodejs 18.15.0
  nodejsのバージョン18.15.0をアンインストールし、npm i -gでグローバルにインストールされたものを含むすべての shim を削除する。
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}/bin/uninstall"
```

bin/list-legacy-filenames

説明
指定されたバージョンを決定するためのレガシーな設定ファイル名をリストアップします。
実装の詳細
- スペースで区切られたファイル名のリストを出力する必要があります。
  出力例は以下の通りです：
```
.ruby-version .rvmrc
```
- ~/.asdfrc で legacy_version_file オプションを有効にしている場合のみ適用されます。
スクリプトで使用可能な環境変数
- ASDF_INSTALL_TYPE
  version または ref
- ASDF_INSTALL_VERSION
  - ASDF_INSTALL_TYPE=version の場合、完全なバージョン番号。
  - ASDF_INSTALL_TYPE=ref の場合、Git ref (tag/commit/branch)。
- ASDF_INSTALL_PATH
  ツールがインストールされている、またはインストールされるべき場所へのパス。
このスクリプトを呼び出すコマンド

ツールのバージョンを読み込むすべてのコマンド。
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}/bin/list-legacy-filenames"
```

bin/parse-legacy-file

説明
asdfが見つけたレガシーファイルを解析して、ツールのバージョンを割り出します。
JavaScript の package.json や Golangs の go.mod のようなファイルからバージョン番号を抽出するのに便利です。
実装の詳細
- このスクリプトが存在しない場合、asdfは単にレガシーファイルをcatしてバージョンを決定します。
- 決定論的で、常に同じ正確なバージョンを返す必要があります。
  同じレガシーファイルを解析したときに、常に同じ正確なバージョンを返す必要があります。
  これは、マシンに何がインストールされているか、レガシーバージョンが有効か完全かに関係なく、常に同じ正確なバージョンを返す必要があります。
  レガシーファイルの形式によっては、適切でない場合があります。
- バージョンを1行で出力する必要があります。
```
1.2.3
```
- ~/.asdfrc で legacy_version_file オプションを有効にしている場合のみ適用されます。
スクリプトで使用可能な環境変数

このスクリプトが呼び出される前に、特に環境変数が設定されることはありません。
このスクリプトを呼び出すコマンド

ツールのバージョンを読み込むすべてのコマンド。
asdfコアからの呼び出し
このスクリプトは、レガシーファイルの内容を読み込むためのパスという単一の引数を受け取る必要があります。
```
"${plugin_path}/bin/parse-legacy-file" "$file_path"
```

bin/post-plugin-add

説明
asdf plugin add <tool> でプラグインがasdfに追加された後、このコールバックスクリプトが実行されます。
関連するコマンドフックも参照してください：
- pre_asdf_plugin_add
- pre_asdf_plugin_add_${plugin_name}
- post_asdf_plugin_add
- post_asdf_plugin_add_${plugin_name}
スクリプトで使用可能な環境変数
- ASDF_PLUGIN_PATH
  プラグインがインストールされたパス
- ASDF_PLUGIN_SOURCE_URL
  プラグインソースのURL。
  ローカルディレクトリのパスを指定することができる。
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}/bin/post-plugin-add"
```

bin/post-plugin-update

説明
asdf plugin update <tool> [<git-ref>] で asdf が更新されたプラグインをダウンロードした後に、このコールバックスクリプトが実行されます。
関連するコマンドフックも参照してください：
- pre_asdf_plugin_update
- pre_asdf_plugin_update_${plugin_name}
- post_asdf_plugin_update
- post_asdf_plugin_update_${plugin_name}
スクリプトで使用可能な環境変数
- ASDF_PLUGIN_PATH
  プラグインがインストールされたパス
- ASDF_PLUGIN_PREV_REF
  プラグインの以前の git-ref。
- ASDF_PLUGIN_POST_REF
  プラグインの更新された git-ref。
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}/bin/post-plugin-update"
```

bin/post-plugin-remove

説明
asdf plugin remove <tool> で asdf がプラグインを削除した後に、このコールバックスクリプトが実行されます。
関連するコマンドフックも参照してください：
- pre_asdf_plugin_remove
- pre_asdf_plugin_remove_${plugin_name}
- post_asdf_plugin_remove
- post_asdf_plugin_remove_${plugin_name}
スクリプトで使用可能な環境変数
- ASDF_PLUGIN_PATH
  プラグインがインストールされたパス
asdfコアからの呼び出し
パラメータは提供されません。
```
"${plugin_path}/bin/post-plugin-remove"
```

asdf CLIコマンドの拡張

プラグインは lib/commands/command*.bash スクリプトや実行ファイルを提供することで新しい asdf コマンドを定義することが可能で、プラグイン名をサブコマンドとして使用することで asdf コマンドラインインターフェイスから呼び出すことができる。

たとえば、fooプラグインで次のようになっているとすると：

foo/
  lib/commands/
    command.bash
    command-bat.bash
    command-bat-man.bash
    command-help.bash

ユーザーが実行できるようになります。

$ asdf foo         
# $ASDF_DATA_DIR/plugins/foo/lib/commands/command.bash を実行するのと同じ

$ asdf foo bar     
# $ASDF_DATA_DIR/plugins/foo/lib/commands/command.bash bar を実行するのと同じ

$ asdf foo help    
# $ASDF_DATA_DIR/plugins/foo/lib/commands/command-help.bash を実行するのと同じ

$ asdf foo bat man 
# $ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat-man.bash を実行するのと同じ

$ asdf foo bat baz 
# $ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat.bash baz を実行するのと同じ

プラグインの作者はこの機能を利用して、自分のツールに関連するユーティリティを提供したり、asdf自体の新しいコマンドを拡張しただけのプラグインを作成することもできます。

スクリプトに実行権限が設定されている場合、スクリプトはasdfの実行を置き換えて実行されます。(exec によるプロセスオーバーライド）

実行権限が設定されていない場合、asdfはスクリプトをBashスクリプトとしてソースします。

環境変数 ASDF_CMD_FILE は、ソースされるファイルのフルパスに解決されます。

haxe　はこの機能を使用するプラグインの素晴らしい例です。これは、Haxeの実行ファイルが実行ディレクトリからの相対パスでダイナミックライブラリを見つけることを期待する問題を修正するために、asdf haxe neko-dylibs-link を提供します。

この機能を使用した場合は、プラグインのREADMEにasdf拡張コマンドについても必ず記載してください。

プラグインのテスト

asdfには、プラグインをテストするためのplugin-testコマンドが含まれています。

asdf plugin test <plugin_name> <plugin_url>  
  [--asdf-tool-version <version>] 
  [--asdf-plugin-gitref <git_ref>] [test_command...]

<plugin_name>と<plugin_url> は必須です。
オプションの --asdf-tool-version <version> を指定すると、そのバージョンでツールがインストールされます。
デフォルト： asdf latest <plugin-name>
オプション --asdf-plugin-gitref <git_ref> を指定すると、プラグイン自体がそのコミット/ブランチ/タグでチェックアウトされます。
これは、プラグインのCIでプルリクエストをテストするのに便利です。
オプションの引数 test_command... は、インストールしたツールが正しく動作することを確認するために実行するコマンドです。
典型的には、<tool> --version または <tool> --help です。
例えば、NodeJSプラグインをテストするために、以下を実行することができます。
```
$ URL=https://github.com/asdf-vm/asdf-nodejs.git 
asdf plugin test nodejs $URL node --version
```

GitHub アクション

asdf-vm/actions リポジトリでは、GitHubでホストされているプラグインをテストするためのGitHub Actionを提供しています。

サンプルの .github/workflows/test.yaml Actions ワークフローを示します。

name: Test
on:
  push:
    branches:
      - main
  pull_request:

jobs:
  plugin_test:
    name: asdf plugin test
    strategy:
      matrix:
        os:
          - ubuntu-latest
          - macos-latest
    runs-on: ${{ matrix.os }}
    steps:
      - name: asdf_plugin_test
        uses: asdf-vm/actions/plugin-test@v2
        with:
          command: "<MY_TOOL> --version"

TravisCI設定

travis.yml ファイルのサンプルです。

必要に応じてカスタマイズしてください。

language: c
script: asdf plugin test <MY_TOOL> $TRAVIS_BUILD_DIR '<MY_TOOL> --version'
before_script:
  - git clone https://github.com/asdf-vm/asdf.git asdf
  - . asdf/asdf.sh
os:
  - linux
  - osx

注意：
他のCIを使用する場合、プラグインの位置への相対パスを渡す必要がある場合があります。
asdf plugin test <tool_name> <path> '<tool_command> --version'

APIレート制限

bin/list-all や bin/latest-stable のように、コマンドが外部 API へのアクセスに依存している場合、自動テスト中にレート制限が発生することがあります。これを軽減するには、環境変数で認証トークンを提供するコードパスがあることを確認します。

例えば:

cmd="curl --silent"
if [ -n "$GITHUB_API_TOKEN" ]; then
 cmd="$cmd -H 'Authorization: token $GITHUB_API_TOKEN'"
fi

cmd="$cmd $releases_path"

GITHUB_API_TOKEN

GITHUB_API_TOKEN を利用するには、public_repo にのみアクセスできる新しいパーソナルトークンを作成します。

そして、これをCIパイプラインの環境変数に追加します。

警告
認証トークンをコードリポジトリで公開しないでください。

プラグインショートネームインデックス

備考：
推奨されるプラグインのインストール方法は、直接URLでインストールする方法です：
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs

git_urlが提供されていない場合、asdf はショートネームインデックス(Shortname Index) リポジトリを使用して使用する正確なgit_urlを決定します。

そのリポジトリの指示に従って、プラグインをShortname Indexに追加することができます。

参考資料

オフィシャルサイト:
- https://asdf-vm.com/
StackOverflow タグ： asdf-vm
- https://stackoverflow.com/questions/tagged/asdf-vm
asdf のヘルプメッセージ

% asdf --help
version: v0.11.3-684f4f0

MANAGE PLUGINS
asdf plugin add <name> [<git-url>]      Add a plugin from the plugin repo OR,
                                        add a Git repo as a plugin by
                                        specifying the name and repo url
asdf plugin list [--urls] [--refs]      List installed plugins. Optionally show
                                        git urls and git-ref
asdf plugin list all                    List plugins registered on asdf-plugins
                                        repository with URLs
asdf plugin remove <name>               Remove plugin and package versions
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


MANAGE PACKAGES
asdf current                            Display current version set or being
                                        used for all packages
asdf current <name>                     Display current version set or being
                                        used for package
asdf global <name> <version>            Set the package global version
asdf global <name> latest[:<version>]   Set the package global version to the
                                        latest provided version
asdf help <name> [<version>]            Output documentation for plugin and tool
asdf install                            Install all the package versions listed
                                        in the .tool-versions file
asdf install <name>                     Install one tool at the version
                                        specified in the .tool-versions file
asdf install <name> <version>           Install a specific version of a package
asdf install <name> latest[:<version>]  Install the latest stable version of a
                                        package, or with optional version,
                                        install the latest stable version that
                                        begins with the given string
asdf latest <name> [<version>]          Show latest stable version of a package
asdf latest --all                       Show latest stable version of all the
                                        packages and if they are installed
asdf list <name> [version]              List installed versions of a package and
                                        optionally filter the versions
asdf list all <name> [<version>]        List all versions of a package and
                                        optionally filter the returned versions
asdf local <name> <version>             Set the package local version
asdf local <name> latest[:<version>]    Set the package local version to the
                                        latest provided version
asdf shell <name> <version>             Set the package version to
                                        `ASDF_${LANG}_VERSION` in the current shell
asdf uninstall <name> <version>         Remove a specific version of a package
asdf where <name> [<version>]           Display install path for an installed
                                        or current version
asdf which <command>                    Display the path to an executable


UTILS
asdf exec <command> [args...]           Executes the command shim for current version
asdf env <command> [util]               Runs util (default: `env`) inside the
                                        environment used for command shim execution.
asdf info                               Print OS, Shell and ASDF debug information.
asdf reshim <name> <version>            Recreate shims for version of a package
asdf shim-versions <command>            List the plugins and versions that
                                        provide a command
asdf update                             Update asdf to the latest stable release
asdf update --head                      Update asdf to the latest on the master branch

RESOURCES
GitHub: https://github.com/asdf-vm/asdf
Docs:   https://asdf-vm.com

"Late but latest"
-- Rajinikanth

ライセンス
- MIT license

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up