Nix Best Practices

Flake Structure

標準的な flake.nix の構造:

{
  description = "Project description";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs {
          inherit system;
        };
      in {
        devShells.default = pkgs.mkShell {
          buildInputs = with pkgs; [
            # packages here
          ];
        };
      });
}

Follows パターン (重複する Nixpkgs を避ける)

オーバーレイ入力を追加する場合、follows を使用して親の nixpkgs を共有し、複数バージョンのダウンロードを回避します:

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

  # オーバーレイは親の nixpkgs に従う
  some-overlay.url = "github:owner/some-overlay";
  some-overlay.inputs.nixpkgs.follows = "nixpkgs";

  # 中間の入力を通じて follows をチェーンする
  another-overlay.url = "github:owner/another-overlay";
  another-overlay.inputs.nixpkgs.follows = "some-overlay";
};

すべての入力は、直接使用しない場合でも outputs 関数に列挙する必要があります:

outputs = { self, nixpkgs, some-overlay, another-overlay, ... }:

オーバーレイの適用

オーバーレイは nixpkgs のパッケージを修正または追加します:

let
  pkgs = import nixpkgs {
    inherit system;
    overlays = [
      overlay1.overlays.default
      overlay2.overlays.default
      # インラインオーバーレイ
      (final: prev: {
        myPackage = prev.myPackage.override { ... };
      })
    ];
  };
in

Unfree パッケージの処理

オプション 1: nixpkgs-unfree (チームに推奨)

EULA ライセンスパッケージ用に numtide/nixpkgs-unfree を使用し、ユーザー設定が不要:

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  nixpkgs-unfree.url = "github:numtide/nixpkgs-unfree/nixos-unstable";
  nixpkgs-unfree.inputs.nixpkgs.follows = "nixpkgs";

  # Unfree オーバーレイは nixpkgs-unfree に従う
  proprietary-tool.url = "github:owner/proprietary-tool-overlay";
  proprietary-tool.inputs.nixpkgs.follows = "nixpkgs-unfree";
};

これにより、チェーンされます: proprietary-tool → nixpkgs-unfree → nixpkgs

オプション 2: ユーザー設定

ユーザーが ~/.config/nixpkgs/config.nix に追加:

{ allowUnfree = true; }

オプション 3: 特定パッケージ (Flake)

let
  pkgs = import nixpkgs {
    inherit system;
    config.allowUnfreePredicate = pkg: builtins.elem (lib.getName pkg) [
      "specific-package"
    ];
  };
in

注: flake.nix の config.allowUnfree は nix develop では機能しません - nixpkgs-unfree またはユーザー設定を使用してください。

バイナリオーバーレイリポジトリの作成

nixpkgs が機能が不足したコミュニティバージョンをビルドする場合 (オープンコアツールで一般的)、公式バイナリを取得するオーバーレイを作成します。

パターン (0xBigBoss/atlas-overlay、0xBigBoss/bun-overlay を参照)

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};

        version = "1.0.0";

        # プラットフォーム固有のバイナリ
        sources = {
          "x86_64-linux" = {
            url = "https://example.com/tool-linux-amd64-v${version}";
            sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
          };
          "aarch64-linux" = {
            url = "https://example.com/tool-linux-arm64-v${version}";
            sha256 = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";
          };
          "x86_64-darwin" = {
            url = "https://example.com/tool-darwin-amd64-v${version}";
            sha256 = "sha256-CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=";
          };
          "aarch64-darwin" = {
            url = "https://example.com/tool-darwin-arm64-v${version}";
            sha256 = "sha256-DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD=";
          };
        };

        source = sources.${system} or (throw "Unsupported system: ${system}");

        toolPackage = pkgs.stdenv.mkDerivation {
          pname = "tool";
          inherit version;

          src = pkgs.fetchurl {
            inherit (source) url sha256;
          };

          sourceRoot = ".";
          dontUnpack = true;

          installPhase = ''
            mkdir -p $out/bin
            cp $src $out/bin/tool
            chmod +x $out/bin/tool
          '';

          meta = with pkgs.lib; {
            description = "Tool description";
            homepage = "https://example.com";
            license = licenses.unfree;  # or appropriate license
            platforms = builtins.attrNames sources;
          };
        };
      in {
        packages.default = toolPackage;
        packages.tool = toolPackage;

        overlays.default = final: prev: {
          tool = toolPackage;
        };
      })
    // {
      overlays.default = final: prev: {
        tool = self.packages.${prev.system}.tool;
      };
    };
}

SHA256 ハッシュの取得

nix-prefetch-url https://example.com/tool-linux-amd64-v1.0.0
# base32 形式のハッシュを返します、SRI 形式に変換:
nix hash to-sri --type sha256 <base32-hash>

または SRI を直接使用:

nix-prefetch-url --type sha256 https://example.com/tool-linux-amd64-v1.0.0

Dev Shell パターン

基本的なシェル

devShells.default = pkgs.mkShell {
  buildInputs = with pkgs; [
    nodejs
    python3
  ];

  shellHook = ''
    echo "Dev environment ready"
  '';
};

環境変数付き

devShells.default = pkgs.mkShell {
  buildInputs = with pkgs; [ postgresql ];

  # シェルエントリ時に設定
  DATABASE_URL = "postgres://localhost/dev";

  # または動的な値のため shellHook で
  shellHook = ''
    export PROJECT_ROOT="$(pwd)"
  '';
};

ネイティブ依存関係 (C ライブラリ)

devShells.default = pkgs.mkShell {
  buildInputs = with pkgs; [
    openssl
    postgresql
  ];

  # ヘッダーとライブラリを公開
  shellHook = ''
    export C_INCLUDE_PATH="${pkgs.openssl.dev}/include:$C_INCLUDE_PATH"
    export LIBRARY_PATH="${pkgs.openssl.out}/lib:$LIBRARY_PATH"
    export PKG_CONFIG_PATH="${pkgs.openssl.dev}/lib/pkgconfig:$PKG_CONFIG_PATH"
  '';
};

Direnv 統合

flake プロジェクト用の .envrc:

use flake

nixpkgs-unfree なしで unfree パッケージの場合:

export NIXPKGS_ALLOW_UNFREE=1
use flake --impure

よく使うコマンド

# すべての入力を更新
nix flake update

# 特定の入力を更新
nix flake update some-input

# flake の有効性を確認
nix flake check

# flake メタデータを表示
nix flake metadata

# dev シェルを開く
nix develop

# dev シェル内でコマンドを実行
nix develop -c <command>

# パッケージをビルド
nix build .#packageName

# パッケージを実行
nix run .#packageName

トラブルシューティング

"unexpected argument" エラー

すべての入力は outputs 関数に列挙する必要があります:

# 間違い
outputs = { self, nixpkgs }: ...

# 正しい (さらに入力がある場合)
outputs = { self, nixpkgs, other-input, ... }: ...

nix develop での Unfree パッケージエラー

flake.nix の config.allowUnfree は nix develop に伝播しません。以下を使用:

1. nixpkgs-unfree 入力 (推奨)
2. ユーザーの ~/.config/nixpkgs/config.nix
3. NIXPKGS_ALLOW_UNFREE=1 nix develop --impure

重複する Nixpkgs ダウンロード

follows を使用して入力を単一の nixpkgs ソースにチェーンします。

オーバーレイが適用されない

nixpkgs をインポートする際、オーバーレイが overlays リストにあることを確認:

pkgs = import nixpkgs {
  inherit system;
  overlays = [ my-overlay.overlays.default ];
};

ハッシュ不一致

nix-prefetch-url で再取得し、ハッシュを更新します。ハッシュは、アップストリームが同じ URL でバイナリを更新すると変更されます。