Zenn
📦

wasm-package-toolsの紹介

2024/12/20に公開
Tips
WebAssembly
OCI
ghcr
tech

WebAssemblyコンポーネントや（Wasmコンポーネント）、WebAssembly Interface Type（WIT）によるインターフェース定義などは、「パッケージ」という形でパッケージレジストリーに登録できます。パッケージレジストリーに登録することで、作成したWasmコンポーネントやインターフェース定義を配布できます。

パッケージの作成や、レジストリーへの登録を行うためのツールの1つにwasm-package-tools（wkg）があります。この記事ではwkgの使い方と、いくつかのTIPsを紹介します。

パッケージとは

パッケージはWasmコンポーネントなどを流通するためのプロトコルWargで定義されている用語で、レジストリーに登録できるものされています。なおパッケージには次の3種類があります：

  • コンポーネント
  • WIT
  • ライブラリー

レジストリーとは

パッケージを登録するためのサービスです。wkgでは次の2種類のレジストリーが利用できます：

  • Wargレジストリー
  • OCIレジストリー

WargレジストリーはWargを実装したレジストリーです。一方、OCIレジストリーはOpen Container Initiativeで定義されているコンテナーイメージなどを配布する仕様を実装したレジストリーです（詳細はコンテナ・レジストリの概要という文書をご覧ください）。

WITパッケージの作成方法

wkgはWasmコンポーネントをパッケージのファイルフォーマットとして利用します。つまりWITファイルをレジストリーに登録するためには、WITファイルをWasmコンポーネントに変換する必要があります。この変換にwkg wit buildコマンドを利用します：

% wkg wit build
WIT package written to chikoski:advent-of-spin@0.2.0.wasm

このコマンドは、実行時に前提条件があります：

  • WITファイルはwitという名前のサブフォルダー内に保存されていること
  • WITファイルにはパッケージ宣言が含まれていること
  • パッケージ名にはバージョン番号が含まれていること

例えば次のような構造をしている場合、project フォルダーを作業ディレクトリーに設定し、上記のコマンドを実行します。

project
├── src
│  └── lib.rs
└── wit
   └── world.wit

--wit-dirでWITファイルが存在するフォルダーを指定できます。例えばwitフォルダー内でパッケージをビルドする場合は、次のように.を指定します：

% wkg wit build --wit-dir .
WIT package written to chikoski:advent-of-spin@0.2.0.wasm

作成されるWasmファイルの名前は、パッケージ名から自動的に決定されます。上記の例の場合、world.witのパッケージ宣言は次のようになっています。そのため、Wasmファイルのファイル名はchikoski:advent-of-spin@0.2.0.wasmとなります。

package chikoski:advent-of-spin@0.2.0;

Wargレジストリーへのパッケージの登録

wkg publishコマンドでパッケージを登録します：

% wkg publish chikoski:advent-of-spin@0.2.0.wasm

標準ではwarg loginコマンドで取得した認証情報を利用します。wa.devへのログイン方法は「Hello, world! with Wasm Component（ライブラリー編）」という記事をご覧ください。

上記のコマンドを実行して、私はWITパッケージをwa.devに登録しました。登録されたパッケージはこちらで閲覧できます。

OCIレジストリーへのパッケージ登録

OCIレジストリーへのパッケージ登録にはwkg oci pushコマンドを利用します。次の例では、上述のWITパッケージをGitHub Container Registry（GHCR）に登録しています：

% wkg oci push ghcr.io/chikoski/advent-of-spin@0.2.0 chikoski:advent-of-spin@0.2.0.wasm

登録されると、このようなページがGHCR上に作成されます。

Docker Hubに登録する場合

Docker Desktopなどでログインしておけば、wkgはその認証情報を利用してパッケージを登録します。

GHCRに登録する場合

GCHRに登録する場合は、認証情報を次のいずれかの手段で指定します：

  • コマンドラインオプション
  • 環境変数
  • 設定ファイル

コマンドラインオプションで指定する場合は、次のように-uオプションと-pオプションを利用します：

% wkg oci push -u user_name -p your_access_token ghcr.io/chikoski/advent-of-spin@0.2.0 chikoski:advent-of-spin@0.2.0.wasm

環境変数の場合は、WKG_OCI_USERNAMEとWKG_OCI_PASSWORDにユーザー名とアクセストークンの値を設定します：

export WKG_OCI_USERNAME=user_name
export WKG_OCI_PASSWORD=your_access_token

設定ファイルの場合、次のように認証情報を記述します。

[registry."ghcr.io"]
auth = { username = "user name", password = "your access token" }

上記の内容を標準の設定ファイルに追記します。標準の設定ファイルは次の場所に存在します：

プラットフォーム 場所
Linux /home/<username>/.config
macOS /home/<username>/.config
Windows C:\Users\<username>\AppData\Roaming

環境変数EDITORが設定されている場合、wkg config -eコマンドを実行することで標準の設定ファイルを編集できます：

% export EDITOR=code # 標準のエディターをVSCodeに設定
% wkg config -e # 設定ファイルがVSCodeで開かれます

まとめ

  • wkgコマンドを使ってレジストリーにパッケージを登録できます
  • wkg wit buildコマンドを利用してWITパッケージを作成できます
  • OCIレポジトリーに登録したWasmコンポーネントをDockerで実行することはできません

最後の点が惜しいところかなと思います。いずれ直接実行できるようになるかとは思いますが、それまではwkg oci pullコマンドを使ってWasmファイルをダウンロードした上でDockerファイルを作成し、Dockerイメージを作成することが必要となりそうです。

Discussion