Skip to content

Y1-Effy/Packer

BranchesTags

Repository files navigation

SetupRunner

SetupRunner は、Windows 向けのセットアップ配布パッケージ作成・実行ツールです。 GUI プロトタイプは、非プログラマ向けにローカルインストーラーや配置するファイルを取り込み、配布先で実行する単一の SetupPackage.exe を生成する導線を中心にしています。 CLI 実行エンジンは recipe.json に書いた手順を読み込み、EXE/MSI インストーラーの実行、マシン環境変数の設定、マシン PATH への追加、ファイルやフォルダーのコピー、SHA-256 ハッシュ確認、実行ログの出力を行います。 CLI では指定フォルダーから配布用 zip を作成し、同梱ファイルを検証するための manifest.json も生成できます。

これは最小構成の MVP です。GUI 操作の記録、画像認識、ダウンロード、コード署名、GUI installer、自動更新などは含めていません。 v0.1.0 では GUI 本体を Windows x64 向け self-contained zip として配布でき、配布版 GUI だけで SetupPackage.exe を生成できます。 実 installer を使う本番前確認は fresh VM または検証環境で行い、通常実行では管理者権限や UAC 昇格が必要になる操作があります。 変更点は CHANGELOG.md、release notes は docs/release-notes-v0.1.0.md を参照してください。

必要なもの

配布版 GUI を起動して作成設定を編集・保存し、SetupPackage.exe を生成する場合:

  • Windows
  • GUI 本体を起動するための .NET Runtime の別途インストールは不要です。GUI 本体は Windows x64 向け self-contained zip として配布します。

リポジトリから開発・検証する場合、または standalone generation assets を含まない開発ビルドで互換生成経路を使う場合:

  • .NET 8 SDK
  • pwsh.exe
  • SetupRunner.sln を含むこのリポジトリ一式

生成した SetupPackage.exe を配布先 PC で通常実行する場合:

  • Windows
  • GUI で 標準版 (64-bit) / self-contained win-x64 を選んで生成した SetupPackage.exe は、配布先 PC に .NET Runtime の別途インストールは不要です。
  • GUI で 軽量版 / framework-dependent を選んで生成した SetupPackage.exe は、配布先 PC に .NET 8 Runtime が必要です。
  • システム設定を変更するための管理者権限。未昇格時は UAC 昇格を要求することがあります。

配布版 GUI を使う

GUI 本体の v0.1.0 Windows x64 zip は次の配布物です。

dist/
  SetupRunner.Gui-v0.1.0-win-x64.zip

zip を展開して、同梱されている SetupRunner.Gui.exe を起動します。

SetupRunner.Gui-v0.1.0-win-x64/
  SetupRunner.Gui.exe
  README.txt

この zip は SetupRunner GUI 本体の配布物です。配布先 PC へ渡す SetupPackage.exe とは別物です。 GUI 本体には code signing、GUI installer、automatic update は含まれていません。

配布版 GUI はリポジトリ外から起動して、作成設定の新規作成、編集、保存、再読み込み、最近使った作成設定の利用、SetupPackage.exe 生成を行えます。 取り込んだインストーラーや配置ファイルなどの作業データは %LOCALAPPDATA%\SetupRunner\Projects\ 配下に保存されます。 最近使った作成設定は %LOCALAPPDATA%\SetupRunner\gui-recent-settings.json、生成履歴は %LOCALAPPDATA%\SetupRunner\gui-build-history.json、生成後確認や SetupPackage.exe 実行ログは %LOCALAPPDATA%\SetupRunner\logs を使います。 通常操作で GUI を展開したフォルダーへ作業データやログを書き出す前提ではありません。

配布版 GUI には standalone generation assets が埋め込まれているため、zip 展開物だけで SetupPackage.exe 生成が完結します。 生成される SetupPackage.exe は、選択した配布形式によって配布先 PC の必要条件が変わります。標準版 (64-bit) / self-contained win-x64 は .NET Runtime 不要、軽量版 / framework-dependent は配布先 PC に .NET 8 Runtime が必要です。

開発時のビルド

dotnet build SetupRunner.sln

開発時に repository から GUI プロトタイプを起動する場合は次を実行します。

dotnet run --project src/SetupRunner.Gui/SetupRunner.Gui.csproj

GUI は日本語表示で起動し、オプションメニューから English に切り替えられます。

GUI 本体の配布 zip

GUI 本体の v0.1.0 Windows x64 zip をリポジトリから作成する場合は次を実行します。

.\prototype\gui-distribution\build-dist.ps1

この script は self-contained single-file publish を行い、次を作ります。

dist/
  SetupRunner.Gui-v0.1.0-win-x64/
    SetupRunner.Gui.exe
    README.txt
  SetupRunner.Gui-v0.1.0-win-x64.zip

GUI 本体だけの single-file publish command を直接確認する場合は次を使います。この command だけでは standalone generation assets は埋め込まれないため、配布版 GUI zip と同等の SetupPackage.exe 生成経路を確認する場合は prototype\gui-distribution\build-dist.ps1 を使ってください。

dotnet publish src/SetupRunner.Gui/SetupRunner.Gui.csproj `
  -c Release -r win-x64 --self-contained true `
  -p:PublishSingleFile=true `
  -p:IncludeNativeLibrariesForSelfExtract=true `
  -p:DebugType=None -p:DebugSymbols=false

zip を展開して SetupRunner.Gui.exe を起動すると、GUI 本体を Windows 上で使えます。この GUI zip は authoring tool 本体の配布物であり、配布先 PC へ渡す SetupPackage.exe とは別物です。

v0.1.0 の published GUI は standalone generation assets を同梱しているため、repo 外から起動して作成設定の編集、保存、SetupPackage.exe 生成を行えます。standalone generation assets を含まない開発ビルドでは、互換性のため repository-local tooling を使う fallback 経路が残っています。

GUI の現在の中心機能:

  • 作成設定 を新規作成、保存、再編集できます。新規作成や読み込み後の編集・生成は、アプリが管理する現在の作成設定で進みます。
  • .exe / .msi インストーラーをファイル選択で取り込み、配布先PCでの実行方法を必要に応じて選べます。
  • 手動操作を案内するインストーラーは、インストーラー一覧行の 操作案内 からダイアログで編集できます。
  • 既に入っている場合に省略したいインストーラーは、一覧行の スキップ判定 からダイアログで設定できます。
  • ファイル配置 でファイルやフォルダーを取り込み、配布先PCでの配置先を登録できます。
  • 上部のコンパクトな 配布形式 選択から形式を選び、配布用 EXE を生成 で SetupPackage.exe を生成できます。
  • 処理結果 で検証や生成後確認を見て、生成履歴 から直近の生成結果を確認できます。

明示保存する場合は、互換性のため従来どおり JSON 形式で保存します。最近使った作成設定は %LOCALAPPDATA%\SetupRunner\gui-recent-settings.json に保存され、ファイルメニューから開けます。

通常の GUI 操作では入力フォルダーを選ばず、出力先フォルダーだけを選択します。ユーザーが選んだ出力先には原則として SetupPackage.exe だけが作られ、内部作業データは出力しません。生成中は現在のステップをヘッダーに表示し、編集系 UI を一時的に無効化します。長い生成処理は 生成をキャンセル で中断できます。

生成後は 処理結果 に 生成サマリー と詳細結果を表示し、出力先、配布形式、警告件数、生成後確認の結果を確認できます。生成自体が成功しても生成後確認に失敗した項目はエラーとして表示されます。生成履歴 タブには直近 10 件の生成履歴が保存され、履歴は %LOCALAPPDATA%\SetupRunner\gui-build-history.json に保存されます。ログを開く から %LOCALAPPDATA%\SetupRunner\logs を開けます。 GUI の操作手順は docs/gui-operation-manual.md にまとめています。 インストーラー実行、環境変数変更、PATH 変更、ファイルコピーは行いません。 GUI / CLI / self-extracting をまとめて確認する手順は docs/verification.md を参照してください。 過去の v0.1.0 リリース前確認記録は docs/archive/release-checklist-v0.1.0.md に残しています。

自己展開版の配布物を作る場合は、既定では sample/ を埋め込み元として次を実行します。

.\prototype\self-extracting\build-dist.ps1

別の source を埋め込みたい場合は -Source を使えます。

.\prototype\self-extracting\build-dist.ps1 -Source sample-real
.\prototype\self-extracting\build-dist.ps1 -Source sample-real -SelfContained

使い方

実インストーラーを使った本番実行の確認手順は docs/manual-install-test.md を参照してください。

GUI で配布用 EXE を作る

この節の 配布用 EXE は GUI 本体の zip ではなく、GUI が作る SetupPackage.exe を指します。

通常の作成作業は次の流れです。

  1. ファイル > 新規作成設定 で作成設定を作ります。
  2. インストーラーを追加... から配布先PCで実行するインストーラーを取り込みます。
  3. 必要なら 実行方法 を選びます。手動操作の案内は対象行の 操作案内 から、既に入っている場合の省略条件は スキップ判定 から編集します。
  4. 追加ファイルがある場合は ファイル配置 でファイルまたはフォルダーを取り込み、配布先PCの配置先 を入力します。
  5. 上部の 配布形式 を選び、配布用 EXE を生成 を押します。標準版 (64-bit) は配布先 PC に .NET Runtime の別途インストールが不要で、軽量版 は配布先 PC に .NET 8 Runtime が必要です。
  6. 出力先フォルダーを選び、完了後に 処理結果 と 生成履歴 を確認します。

選択した素材はアプリ管理下の作業フォルダーへ取り込まれ、通常操作に必要なファイル確認情報は自動で扱われます。あとで再編集したい場合は、作成設定を保存 で従来互換の JSON 形式として保存し、次回は 作成設定を開く... または 最近使った作成設定 から開きます。保存先には作成設定だけを書き出すため、参照先の素材が見つからない場合は保存後または次回読み込み後の 処理結果 にエラーとして表示されます。

配布用 EXE を生成 では出力先フォルダーだけを選びます。通常導線で入力フォルダーを手で選ぶ必要はなく、出力先には原則として SetupPackage.exe だけが作られます。

CLI で zip パッケージを作る

recipe.json、installers/、files/ を置いたフォルダーを zip にまとめます。 これは CLI や自動検証で使う source directory 形式の作成手順です。GUI の通常導線では、ユーザーが事前に installers/ や files/ を手で整える前提ではありません。 このとき recipe.json を validate と同じ基準で先に検証し、成功した場合だけ manifest.json を自動生成して zip の中にも同梱します。 無効な recipe、存在しない参照ファイル、SHA-256 不一致、未対応 installer 形式がある場合、pack は配布物を作成せず失敗します。

dotnet run --project src/SetupRunner/SetupRunner.csproj -- pack --source sample --output dist/sample.zip

ビルド済みの実行ファイルを使う場合は、次のように実行します。

SetupRunner.exe pack --source sample --output dist/sample.zip

作成される zip は、zip 直下に入力フォルダー名のフォルダーを持ちます。

sample.zip
  sample/
    recipe.json
    manifest.json
    installers/
    files/

セットアップを実行する

まずは validate で recipe.json の JSON Schema、manifest.json、同梱ファイル、SHA-256 の妥当性を確認します。

dotnet run --project src/SetupRunner/SetupRunner.csproj -- validate --recipe sample/recipe.json

次に --dry-run を付けて、実際には変更せず実行直前の処理内容を確認します。

dotnet run --project src/SetupRunner/SetupRunner.csproj -- --recipe sample/recipe.json --dry-run

ビルド済みの実行ファイルを使う場合は、次のように実行します。

SetupRunner.exe --recipe C:\path\to\recipe.json
SetupRunner.exe validate --recipe C:\path\to\recipe.json
SetupRunner.exe --recipe C:\path\to\recipe.json --dry-run

自動展開版の SetupPackage.exe では、次のように確認できます。

SetupPackage.exe --validate
SetupPackage.exe --dry-run

SetupPackage.exe は起動時に、temp フォルダーへ書き出した埋め込み SetupRunner.exe と package.zip の SHA-256 を検証してから後続処理へ進みます。 通常実行では temp 展開より前に SetupPackage.exe 自身が管理者権限を確認し、必要なら runas で自分自身を昇格し直します。--version / --validate / --dry-run は昇格不要です。

オプション:

  • --recipe <path>: recipe.json のパスを指定します。省略した場合は recipe.json を使います。
  • validate: recipe.json と同梱ファイルの妥当性を確認し、成功時に実行計画を表示します。
  • --dry-run: JSON Schema と manifest 検証後、インストーラー実行やシステム変更をせず、実行予定をログに出します。
  • --log-dir <path>: setup-YYYYMMDD-HHMMSS.log を出力するディレクトリを指定します。省略した場合は従来どおりカレントディレクトリ配下の logs を使います。
  • pack: パッケージ作成モードで起動します。
  • --source <path>: pack で zip にまとめる入力フォルダーを指定します。
  • --output <path>: pack で作成する zip の出力先を指定します。
  • --version: バージョンとビルドメタデータを表示します。
  • --help: ヘルプを表示します。

管理者権限で起動されていない場合、SetupRunner は Windows の runas を使って管理者権限で起動し直します。

recipe.json の書き方

recipe.json の中に書いた相対パスは、recipe.json が置かれているフォルダーからの相対パスとして扱われます。 絶対パスを書いた場合は、そのまま使われます。

{
  "$schema": "../docs/schema/recipe.schema.json",
  "installers": [
    {
      "path": "installers/example.exe",
      "arguments": "/quiet /norestart",
      "sha256": "PUT_SHA256_HERE",
      "expectedExitCodes": [0, 3010],
      "detection": {
        "fileExists": "C:\\Program Files\\Example\\example.exe"
      }
    },
    {
      "path": "installers/manual-example.exe",
      "executionMode": "guidedManual",
      "guidance": {
        "title": "Manual example installer",
        "steps": [
          "Follow the installer prompts.",
          "Finish the installer, then return to SetupRunner."
        ],
        "notes": "Use the default options unless instructed otherwise."
      }
    }
  ],
  "environmentVariables": [
    {
      "name": "MY_TOOL_HOME",
      "value": "C:\\Tools\\MyTool"
    }
  ],
  "pathEntries": [
    "C:\\Tools\\MyTool\\bin"
  ],
  "copies": [
    {
      "source": "files/config.json",
      "destination": "C:\\ProgramData\\MyTool\\config.json",
      "sha256": "PUT_SHA256_HERE"
    },
    {
      "source": "files/templates",
      "destination": "C:\\ProgramData\\MyTool\\templates"
    }
  ]
}

本番実行する前に、PUT_SHA256_HERE を実際の SHA-256 ハッシュに置き換えてください。 ハッシュ確認が不要なファイルは、sha256 の行を削除しても構いません。 expectedExitCodes には成功扱いする installer の終了コードを指定できます。省略した場合は [0] として扱われます。 たとえば [0, 3010] と書くと、3010 のような「成功したが再起動が必要」を表す終了コードも許容できます。 detection.fileExists を指定すると、installer 実行前にそのファイルの存在を確認し、存在する場合はその installer を skip します。 executionMode は automatic または guidedManual を指定できます。省略した場合は従来互換で automatic として扱われます。 guidedManual では guidance.title と 1 件以上の guidance.steps が必須です。guidance.notes は任意です。

JSON Schema

recipe.json の JSON Schema は docs/schema/recipe.schema.json にあります。 手書きで編集する場合は、recipe.json の $schema にこのファイルへのパスを書くと、VS Code などのエディターで補完や形式チェックを使えます。

SetupRunner validate は同じ schema を使って、未知のプロパティ、必須項目、空文字、SHA-256 の形式を確認します。detection を書く場合は、空でない fileExists が必須です。guidedManual を指定した installer では、空でない guidance.title と空でない guidance.steps[] が必須です。guidance は guidedManual 専用で、automatic または executionMode 省略の installer に書くと schema 検証で失敗します。environmentVariables[].value は空文字も許可されます。 Schema 検証に失敗した場合は、原因箇所を JSON Pointer 付きで表示します。

manifest.json

manifest.json は pack 実行時に自動生成されます。 通常のセットアップ実行時には、recipe.json と同じフォルダーにある manifest.json が必須です。

manifest.json には、manifest.json 自身を除くすべての同梱ファイルについて、次の情報が記録されます。

  • 相対パス
  • SHA-256
  • ファイルサイズ
  • 作成日時 UTC

SetupRunner は起動時に manifest.json を検証します。 検証に失敗した場合、インストーラー実行、環境変数変更、PATH 変更、ファイルコピーは一切開始しません。 --dry-run の場合も manifest 検証は省略されません。

モードごとの検証内容

  • 通常実行: JSON Schema と manifest を検証した後、インストーラー実行、環境変数変更、PATH 変更、ファイルコピーを行います。
  • --dry-run: JSON Schema と manifest を検証した後、実行予定を表示します。実際の変更処理は行いません。
  • validate: JSON Schema、manifest、参照ファイルの存在、recipe 内 SHA-256、実行計画を確認します。実際の変更処理は行いません。
  • detection がある installer は、validate の実行計画に条件と現在の存在判定が表示されます。
  • guided manual installer は、validate と --dry-run の実行計画に mode と guidance 概要が表示されます。
  • installers/ と files/ 配下に recipe から参照されていないファイルがある場合は警告します。現時点ではエラーではありません。

動作内容

  • 通常実行では、最初に JSON Schema と manifest.json を検証します。
  • 自動展開版の SetupPackage.exe は、書き出した埋め込み SetupRunner.exe と package.zip の SHA-256 を検証してから展開や実行を始めます。
  • manifest にないファイル、manifest にあるのに存在しないファイル、サイズや SHA-256 が一致しないファイルがある場合は停止します。
  • installers/ と files/ 配下の未参照ファイルは警告されますが、現時点では処理を停止しません。
  • インストーラーは recipe.json に書かれた順番で最初に実行されます。
  • installer に detection.fileExists があり、そのファイルが存在する場合、その installer は skip されてログに記録されます。
  • guidedManual installer では、title、steps、notes を console と log に表示して installer を起動し、終了後に Enter による手動完了確認を受けてから次へ進みます。通常実行では対話入力が必要で、標準入力が対話的でない場合は installer 起動前に停止します。
  • .exe は arguments に書いた引数付きで直接実行されます。
  • .msi は msiexec.exe /i "<path>" <arguments> として実行されます。
  • インストーラーの終了コードが expectedExitCodes に含まれていない場合、その時点で処理を停止します。未指定時は [0] として扱われます。
  • 環境変数はマシン環境変数として書き込まれます。
  • PATH への追加は、同じ値がまだ存在しない場合だけ行われます。
  • ファイルコピーでは、コピー前に SHA-256 ハッシュ確認を行えます。
  • フォルダーコピーでは、中のファイルやフォルダーを再帰的にコピーします。
  • ログは、実行時のカレントディレクトリ配下の logs/setup-YYYYMMDD-HHMMSS.log に出力されます。

サンプル構成

sample/
  recipe.json
  installers/
  files/

sample/ は、疑似 installer と guided manual の例を含む、安全な CLI / GUI / self-extracting 回帰確認用サンプルです。 sample-real/ は、ユーザーが自分で入手した実 installer をローカルに置いて確認するためのテンプレートです。実 installer 本体は Git に含めません。 実 installer を使った本番前確認は sample-real/ と docs/manual-install-test.md を使ってください。

About

非プログラマ向けの Windows セットアップ配布ツール。インストーラーや配置ファイルを取り込み、配布先で実行する単一の SetupPackage.exe を生成できる GUI と、recipe.json でインストーラー実行・環境変数/PATH 設定・ファイル配置・SHA-256 検証を行う CLI を提供します。

Resources

Readme

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages