最終更新: 2026-02-23

genpack.json5 仕様リファレンス

概要

genpack.json5 は genpack でビルドするシステムイメージの宣言的な定義ファイルです。各アーティファクトのルートディレクトリに配置し、パッケージ構成、Portage の設定、ユーザー・サービス定義、圧縮方式などを 1 ファイルに集約します。

フォーマットは JSON5 で、コメントや末尾カンマなどが使えます。genpack.json5 が存在しない場合は genpack.json にフォールバックしますが、両方が存在するとエラーになります。

最小構成

{
  packages: ["genpack/paravirt"]
}

name を省略するとディレクトリ名が自動的に使用されます（警告が出ます）。

フィールド一覧

基本フィールド

name

型: string
デフォルト: カレントディレクトリのベースネーム
説明: アーティファクトの名前。ビルド時に環境変数 ARTIFACT として scripts に渡され、出力ファイル名のデフォルトにも使われます。

profile

型: string | null
デフォルト: null
説明: genpack-overlay のプロファイル名。内部的に genpack-overlay:genpack/{arch}/ に連結されて Portage プロファイルとして設定されます。

代表的なプロファイル:

プロファイル	用途
`paravirt`	QEMU/KVM 仮想マシン向け（virtio, ゲストエージェント）
`baremetal`	物理マシン向け（BIOS/UEFI, デバイスドライバ）
`gnome/baremetal`	物理マシン + GNOME デスクトップ
`weston/paravirt`	仮想マシン + Wayland (Weston)

outfile

型: string
デフォルト: {name}-{arch}.squashfs
説明: 出力ファイル名。CLI の --outfile 引数でも上書き可能です。

compression

型: string
デフォルト: "gzip"
許容値: "gzip", "xz", "lzo", "none"
説明: SquashFS 圧縮アルゴリズム。"xz" はサイズが最小になりますが圧縮に時間がかかります。CLI の --compression 引数でも上書き可能です。

パッケージ関連

packages

型: string[]
デフォルト: []
説明: インストールするパッケージのリスト。Gentoo のパッケージアトム形式 (category/name) で指定します。

- プレフィックスを付けると、プロファイルやバリアントのマージ時にリストから除外できます:

{
  packages: [
    "genpack/paravirt",
    "app-misc/screen",
    "-app-misc/unwanted-package"  // マージ元から除外
  ]
}

buildtime_packages

型: string[]
デフォルト: []
説明: ビルド時のみ必要なパッケージ。Lower 層にはインストールされますが、Upper 層（最終イメージ）にはコピーされません。Go や CMake など、コンパイルに必要だが実行時には不要なパッケージに使います。

{
  buildtime_packages: ["dev-lang/go", "dev-build/cmake"]
}

binpkg_excludes

型: string | string[]
デフォルト: []
説明: バイナリパッケージキャッシュ (usepkg/buildpkg) から除外するパッケージ。カーネルなど、設定が異なるためバイナリキャッシュの共有が不適切なパッケージに使います。

Portage 設定

use

型: object
デフォルト: {}
説明: パッケージ別の USE フラグ設定。package.use に相当します。

キーはパッケージアトム（*/* でグローバル指定可）、値は文字列（スペース区切り）またはリストです:

{
  use: {
    "dev-lang/php": "+mysql +curl +gd +xml +zip",
    "media-libs/mesa": "wayland VIDEO_CARDS: virgl",
    "*/*": "python_targets_python3_12"
  }
}

CPU_FLAGS_X86:, VIDEO_CARDS:, AMDGPU_TARGETS:, APACHE2_MODULES: などの USE_EXPAND 変数もこのフィールドで設定します。

accept_keywords

型: object
デフォルト: {}
説明: パッケージ別の ACCEPT_KEYWORDS 設定。package.accept_keywords に相当します。

値が null の場合はキーワードなし（テスティング版を受け入れる標準的なパターン）:

{
  accept_keywords: {
    "dev-util/debootstrap": null,      // ~arch を受け入れ
    "app-misc/package": "~amd64",      // 特定キーワード
    "app-misc/other": ["~amd64", "**"] // 複数キーワード
  }
}

mask

型: string[]
デフォルト: []
説明: パッケージマスク。package.mask に相当します。特定バージョン以上をブロックするなどの用途に使います。

{
  mask: [">=dev-db/mysql-8"]
}

license

型: object
デフォルト: {}
説明: パッケージ別のライセンス受け入れ設定。package.license に相当します。

{
  license: {
    "sys-kernel/linux-firmware": "linux-fw-redistributable",
    "www-client/google-chrome": "google-chrome"
  }
}

env

型: object
デフォルト: {}
説明: パッケージ別の環境設定。package.env に相当します。Portage の env/ ディレクトリ内の設定ファイル名を指定します。

{
  env: {
    "sci-libs/pytorch": "torch_cuda.conf"
  }
}

ユーザーとグループ

users

型: (string | object)[]
デフォルト: []
説明: Upper 層で作成するユーザー。文字列（ユーザー名のみ）またはオブジェクトで指定します。

{
  users: [
    "simpleuser",
    {
      name: "advanceduser",
      uid: 1000,
      home: "/home/advanceduser",
      shell: "/bin/bash",
      initial_group: "users",
      additional_groups: ["wheel", "video", "audio"],
      create_home: true,
      empty_password: true
    }
  ]
}

オブジェクト形式のプロパティ:

プロパティ	型	デフォルト	説明
`name`	string	(必須)	ユーザー名
`uid`	integer	(自動)	ユーザー ID
`comment`	string		GECOS フィールド
`home`	string		ホームディレクトリ
`shell`	string		ログインシェル
`initial_group`	string		プライマリグループ
`additional_groups`	string \| string[]		追加グループ
`create_home`	boolean	true	ホームディレクトリを作成するか
`empty_password`	boolean	false	空パスワードを許可するか

groups

型: (string | object)[]
デフォルト: []
説明: Upper 層で作成するグループ。

{
  groups: [
    "customgroup",
    { name: "groupwithgid", gid: 1002 }
  ]
}

サービスとセットアップ

services

型: string[]
デフォルト: []
説明: 有効化する systemd サービス。テンプレートユニットやタイマーユニットも指定可能です。

{
  services: [
    "sshd",
    "apache2",
    "fstrim.timer",
    "[email protected]"
  ]
}

setup_commands

型: string[]
デフォルト: []
説明: Upper 層の構築後に nspawn コンテナ内で実行されるシェルコマンド。ファイルの編集、権限の変更など、パッケージインストールやファイルコピーだけでは対応できないカスタマイズに使います。

{
  setup_commands: [
    "sed -i 's/-D SSL //' /etc/conf.d/apache2",
    "mkdir -p /var/www/localhost/htdocs"
  ]
}

ビルド設定

lower-layer-capacity

型: integer (GiB 単位)
デフォルト: 128
説明: Lower 層のディスクイメージサイズ（GiB）。パッケージ数が非常に多い場合に増やします。

independent_binpkgs

型: boolean
デフォルト: false
説明: 共有バイナリパッケージキャッシュの代わりに、アーティファクト固有のバイナリパッケージを使用するかどうか。CLI の --independent-binpkgs でも指定可能です。

circulardep_breaker

型: object
デフォルト: (なし)
説明: Gentoo の循環依存を解決するための特殊設定。一部のパッケージ（freetype ↔ harfbuzz など）は互いに依存しているため、最初に制限された USE フラグでインストールしてから通常ビルドを行います。

{
  circulardep_breaker: {
    packages: ["media-libs/freetype", "media-libs/harfbuzz"],
    use: "-truetype -harfbuzz"
  }
}

packages に指定したパッケージが use で指定した USE フラグ付きで先にインストールされ、その後の通常ビルドで正しいフラグで再ビルドされます。

条件付き設定

arch

型: object
デフォルト: {}
説明: アーキテクチャ固有の設定オーバーライド。キーはアーキテクチャ名（| で複数指定可）、値はマージされるフィールドのオブジェクトです。

現在のマシンのアーキテクチャ (uname -m) と一致するキーの設定のみがマージされます。

{
  arch: {
    x86_64: {
      packages: ["app-misc/x86-specific"],
      use: {
        "media-video/ffmpeg": "CPU_FLAGS_X86: avx avx2 sse4_2"
      }
    },
    aarch64: {
      accept_keywords: {
        "app-emulation/qemu-guest-agent": null
      }
    }
  }
}

マージ可能なフィールド: packages, buildtime_packages, accept_keywords, use, mask, license, env, binpkg_excludes, setup_commands, services

variants

型: object
デフォルト: {}
説明: 名前付きバリアント設定。同一アーティファクトから異なる構成のイメージを生成するために使います。CLI の --variant 引数で選択します。

{
  packages: ["genpack/gnome"],
  services: ["gdm"],
  variants: {
    paravirt: {
      // packages は上位定義とマージされる
      packages: ["-x11-drivers/nvidia-drivers"],
      use: {
        "media-libs/mesa": "VIDEO_CARDS: virgl"
      }
    },
    cuda: {
      packages: ["x11-drivers/nvidia-drivers"],
      use: {
        "sci-libs/pytorch": "CUDA_TARGETS: sm_89"
      }
    }
  }
}

バリアント内では name, profile, outfile を含む大半のトップレベルフィールドをオーバーライドまたはマージできます。さらにバリアント内に arch を含めることもできます。

default_variant

型: string | null
デフォルト: null
説明: CLI で --variant を指定しなかった場合に使用されるデフォルトバリアント名。指定されたバリアントが variants に存在しない場合はエラーになります。

マージの仕組み

genpack.json5 の設定は以下の順序でマージされます:

ベース設定: トップレベルのフィールド
アーキテクチャ固有: arch 内の該当アーキテクチャの設定をマージ
バリアント: variants 内の選択されたバリアントの設定をマージ（バリアント内の arch も処理される）

マージ時のリスト型フィールドの動作:

packages: - プレフィックス付きの要素は既存リストから除外。それ以外は重複なく追加
buildtime_packages, mask, services: 重複なく追加
accept_keywords, use, license, env: キー単位で上書き

非推奨フィールド名

以下のハイフン区切りの名前は非推奨で、使用するとエラーになります:

非推奨名	現行の名前
`buildtime-packages`	`buildtime_packages`
`binpkg-exclude`	`binpkg_excludes`
`circulardep-breaker`	`circulardep_breaker`

ユーザーオブジェクト内では互換性のためハイフン区切りも受け付けます:

create-home → create_home
initial-group → initial_group
additional-groups → additional_groups
empty-password → empty_password

完全な構成例

{
  // 基本情報
  name: "nextcloud",
  profile: "paravirt",
  compression: "xz",

  // パッケージ
  packages: [
    "genpack/paravirt",
    "www-apps/nextcloud",
    "dev-db/mysql",
    "dev-lang/php",
    "net-misc/redis",
    "www-servers/apache"
  ],
  buildtime_packages: [
    "app-arch/rpm2targz"
  ],
  binpkg_excludes: ["sys-kernel/gentoo-kernel"],

  // Portage 設定
  use: {
    "dev-lang/php": "mysql curl gd xml zip",
    "www-servers/apache": "APACHE2_MODULES: http2 proxy proxy_fcgi"
  },
  accept_keywords: {
    "net-vpn/frp": null
  },
  license: {
    "net-analyzer/fping": "fping",
    "dev-db/redis": "SSPL-1"
  },

  // ユーザーとサービス
  users: [
    { name: "nextcloud", uid: 1000 }
  ],
  services: ["apache2", "mysqld", "redis"],

  // セットアップ
  setup_commands: [
    "sed -i 's/-D SSL //' /etc/conf.d/apache2"
  ],

  // バリアント
  variants: {
    selftestable: {
      profile: "weston/paravirt",
      packages: ["www-client/google-chrome"],
      users: [
        { name: "user", uid: 1000, empty_password: true }
      ]
    }
  }
}

ソースリファレンス

このドキュメントは以下のリポジトリのスナップショットに基づいて作成されました:

更新履歴

2026-02-23 — genpack ドキュメントサイトを公開

すべての更新履歴を見る