ワルブリックス株式会社

genpack documentation

genpack.json5 仕様リファレンス

Gentoo Linux をベースに、不変システムイメージを宣言的に生成・配布・起動するための自社開発ツールチェーンの資料です。

概要

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

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

最小構成

{
  packages: ["genpack/paravirt"]
}

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

フィールド一覧

基本フィールド

name

profile

代表的なプロファイル:

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

outfile

compression

パッケージ関連

packages

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

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

buildtime_packages

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

binpkg_excludes

Portage 設定

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

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

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

mask

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

license

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

env

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

ユーザーとグループ

users

{
  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

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

サービスとセットアップ

services

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

setup_commands

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

ビルド設定

lower-layer-capacity

independent_binpkgs

circulardep_breaker

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

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

条件付き設定

arch

現在のマシンのアーキテクチャ (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

{
  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

マージの仕組み

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

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

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

非推奨フィールド名

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

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

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

完全な構成例

{
  // 基本情報
  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 }
      ]
    }
  }
}

ソースリファレンス

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

当社代表のデスクトップ(※)を常時ライブ配信中

※ライブ配信専用PC

OSSの検証や自社用ツールの開発といった公開できる作業に限り、 ライブ配信専用PC上で行っています。常時配信ですのでいつでもお気軽にチャットメッセージ(公開)を残していって下さい。

代表のデスクトップライブ配信のイメージイラスト YouTubeで見る