VS CodeでZigを安定して動作させる方法をようやく見つけたので、誰かの手間が少しでも省ければと思い、自分のセットアップを共有します。

うまく動く解決策にたどり着くまでは、Zigのバージョン不一致の問題に何度も悩まされたり、VS CodeがZigのセマンティクスをまったく認識できず、単純な自動補完にフォールバックしてしまったりしていました。

プロジェクトごとに異なるZigバージョンを管理する

Zigはまだ安定版の1.0リリースに到達していません。Zigで書かれたソフトウェアに取り組む場合、そのプロジェクトに対応するバージョンのZigコンパイラを使う必要があります。

複数のプロジェクトを掛け持ちするなら、同じシステム上で異なるバージョンのZigを使い分けられる仕組みが必要です。

Zigのバージョン管理で最も人気があるのはZig Version Managerのようですが、私は試したことがないので、VS Codeとの相性がどうなのかはわかりません。

私は個人的に、Nixの開発用シェルを使ってプロジェクトごとにZigのバージョンを管理しているので、以下ではその方法を紹介します。

問題：VS CodeがZLSを見つけられない

Zigプロジェクトを開くと、VS Codeが親切にもZig Language Serverを有効にするか尋ねてきますが、「はい」を選ぶと次のようなエラーメッセージが表示されます。

問題は、Nixの開発環境を起動する前にVS Codeを立ち上げてしまうことで、ZigのVS CodeプラグインがローカルのZigコンパイラやZig Language Serverのバイナリであるzlsの場所を見つけられないことです。

解決策：direnvのVS Code拡張を使う

追記（2025-02-14）：Nixに依存しない、よりシンプルな解決策があります。

当初は、開発用シェルに入るたびにNix flakeがVS Codeの設定を自動的に書き換えるという、ちょっと奇抜な方法を考えました。こうすれば、VS Codeは常にZigとZLSのバイナリへの最新のパスを保持できます。

その後、fasterthanlimeの記事を読んで、シンプルな解決策があることを知りました。

direnvのVS Code拡張を使えば、ZigのパスをVS Codeと簡単に同期できます。おかげで、Remote SSHを使ったVS Code開発でもこの方法が使えます。

私の完全な動作するセットアップ

以下で解決策を解説しますが、説明は不要ですぐに使いたいという方のために、簡単にコピーできるテンプレートを以下に用意しています。

flake.nix

ここで中心的な役割を担っているのが、私のNix flakeです。

{
  description = "Zig development environment";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
    flake-utils.url = "github:numtide/flake-utils";
    zig-overlay.url = "github:mitchellh/zig-overlay";
    # Keep in sync with zigVersion below.
    zls-overlay.url = "github:zigtools/zls/0.13.0";
  };

  outputs = {
    self,
    nixpkgs,
    flake-utils,
    ...
  } @ inputs:
    flake-utils.lib.eachSystem (builtins.attrNames inputs.zig-overlay.packages) (system: let
      pkgs = import nixpkgs {
        inherit system;
        overlays = [
          (final: prev: {
            zigpkgs = inputs.zig-overlay.packages.${prev.system};
          })
        ];
      };
      zigVersion = "0.13.0";
      zig = pkgs.zigpkgs.${zigVersion};
      zls = inputs.zls-overlay.packages.${system}.zls.overrideAttrs (old: {
        nativeBuildInputs = [zig];
      });
    in {
      devShells.default = pkgs.mkShell {
        packages = with pkgs; [
          zig
          zls
        ];

        shellHook = ''
          echo 'zls' "$(zls --version)"
          echo 'zig' "$(zig version)"
        '';
      };
    });
}

flake.nixをダウンロード

このNix flakeは、ZigコンパイラとZig Language Server（ZLS）を含む開発用シェルを作成します。

ここではZigのバージョンを0.13.0に設定していますが、任意のタグ付きリリースに変更できます。開発中のプレリリース版のZigを使いたい場合は、2箇所ある0.13.0をどちらもmasterに書き換えてください。

0.13.0の重複をなくして一箇所で定義できるように何度か試してみましたが、Nix言語のスキルが足りず方法がわかりませんでした。もし解決策をご存知の方がいれば、ぜひ教えてください。

.envrc

私の解決策では、プロジェクトディレクトリにいる間はdirenvを使ってNixの開発用シェルを起動するようにしています。設定はとてもシンプルです。

use_flake

.vscode/extensions.json

VS CodeとZigを連携させるには、2つのVS Code拡張が必要です。

{
  "recommendations": ["mkhl.direnv", "ziglang.vscode-zig"]
}

extensions.jsonをダウンロード

1つ目は公式のZig VS Code拡張です。

2つ目は、一見わかりにくいかもしれませんがdirenvのVS Code拡張で、これによりVS CodeがNix開発用シェル内のパスを認識できるようになります。

.vscode/settings.json

最後に、VS CodeにZig Language Serverを使うよう指示するための設定が1つだけ必要です。

{
  "zig.zls.enabled": "on"
}

settings.jsonをダウンロード

テンプレートをコピーする

自分のセットアップを簡単に再現できるよう、Nix flakeのテンプレートを作成しました。

要件

• Nix（私は2.24.12を使用）
  • flakesを有効化したもの
• direnv（私は2.35.0を使用）
• VS Code（私は1.96.4を使用）

Zig + VS Code用Nix flakeテンプレート

Nix flakeテンプレートを作成しました。Zig + VS Codeの解決策をまとめています。次のコマンドを実行すれば利用できます。

nix flake init \
  --template git+https://codeberg.org/mtlynch/zig-vscode-flake.git

nix flake initを実行した後、direnv allowを実行すると、zigとzlsが利用可能になったことが表示されるはずです。

$ direnv allow
...
direnv: nix-direnv: Renewed cache
Alejandra 3.0.0
zls 0.13.0
zig 0.13.0

最後に、VS Codeで「Extensions: Show Recommended Extensions」を開き、推奨された拡張機能をインストールしてください。

ここまでできれば、zig initを実行して新しいプロジェクトを作成し、ZigのVS Code拡張がZigと正しく連携していることを確認できるはずです。

Zigのバージョンを変更する

私のflakeは、執筆時点で最新リリースであるZig 0.13.0に設定されています。

別のタグ付きリリースを使いたい場合は、0.13.0を別のバージョンに置き換えてください。

EXISTING_ZIG_VERSION='0.13.0' # Set to whatever the version in the flake.nix is.
NEW_ZIG_VERSION='0.12.0'      # Set to your desired Zig version.

最先端のプレリリース版のZigを使いたい場合は、バージョンをmasterに設定してください。

NEW_ZIG_VERSION='master'      # Set if you want bleeding edge Zig.

flake.nixファイルでZigのバージョンを更新したら、次のコマンドを実行して変更を適用してください。

sed \
  --in-place \
  "s/${EXISTING_ZIG_VERSION}/${NEW_ZIG_VERSION}/g" \
  flake.nix && \
  nix flake update zig zls-overlay && \
  nix develop

変更を反映させるには、VS Codeを再読み込みするだけでなく、再起動する必要があるかもしれません。

追記：Nixを使わない、よりシンプルな解決策

Zig VS Code拡張の開発者の一人がこの投稿に返信し、拡張機能だけでZigのバージョンを管理できるはずだと教えてくれました。

Zig VS Code拡張でZigのインストールを管理できるとは知らなかったので、試してみました。VS Code拡張経由でZigをインストールするには、VS Codeのコマンドパレットを開いて次を選択します。

• Zig Setup: Install Zig

次に、使いたいZigのバージョンを選べば動作するはずです。私はsettings.jsonを手動で設定し、VS Codeを再読み込みする必要がありました。

私はNixの開発用シェルが気に入っているので今後も使い続けますが、シンプルなセットアップを求めているなら、Zig VS Code拡張にZigのインストールを任せた方がよいでしょう。