My Zig Configuration for VS Code

2025-02-13

Michael Lynch

VS CodeのZig設定

ようやく、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と同期できます。この方法なら、VS CodeでRemote SSH開発を使う場合にも動作します。

完全に動作する私の解決策

ここでは私の解決策について説明しますが、説明を読み飛ばしてそのまま使いたい場合は、下にコピーしやすいテンプレートを用意しています。

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のプレリリース版、つまり開発版を使うには、0.13.0の2か所をmasterに変更してください。

0.13.0の重複をなくして定義を1か所にまとめる方法をいくつか試しましたが、Nix言語の知識が足りず、方法を見つけられませんでした。解決策がある方は、ぜひ教えてください。

.envrc

私の解決策では、プロジェクトディレクトリにいる間は常にNixの開発シェルを起動するためにdirenvを使います。定義は簡単です。

use_flake

.vscode/extensions.json

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

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

extensions.jsonをダウンロード

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

もう1つの、少し分かりにくい方が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）
- flakeを有効にしてあること
direnv（私が使っているのは2.35.0）
VS Code（私が使っているのは1.96.4）

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

私のZig + VS Codeの解決策をまとめたNix flakeテンプレートを作りました。次のコマンドを実行すれば使えます。

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と正常に連携して動作するはずです。

すべてが正常に動作していれば、`src/main.zig`に言語オーバーレイが表示され、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拡張機能の開発者の1人がこの記事に返信を寄せ、Zigのバージョンは拡張機能だけで管理できるはずだと教えてくれました。

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

Zig Setup: Install Zig

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

私はNixの開発シェルが気に入っているので、これからも自分のものを使い続けます。ただ、シンプルな構成だけを求めるなら、Zigのインストール管理はZig VS Code拡張機能に任せた方がよいでしょう。