コマンドラインビルド

Studio はコマンドラインからプロジェクトをビルドし、終了コードを返します。この実行ではウィンドウを開かず、ビルドログは標準出力に書き出され、成果物はBuild for distribution（配布用にビルド）ダイアログが生成するものと同じです。

1 回の実行で 1 つのビルドを生成します。バリアント 1 つ、プラットフォーム 1 つ、フォーマット 1 つです。2 つ目のターゲットが必要な場合は、もう一度実行します。

narraleaf-studio --build /projects/my-game

このコマンドは Studio 自身の実行ファイルです。

• Windows: インストールディレクトリの NarraLeaf Studio.exe
• macOS: NarraLeaf Studio.app/Contents/MacOS/NarraLeaf Studio
• Linux: 展開先ディレクトリの narraleaf-studio

以下の例では narraleaf-studio と書きます。

オプション

--オプション 値 と --オプション=値 のどちらの書き方も受け付けます。--build-arch はデスクトップのターゲットにのみ適用されます。--build を伴わないビルドオプションは拒否されます。

デスクトップと Web のフォーマットは zip、dir、およびそのプラットフォームのインストーラー（Windows は nsis、macOS は dmg、Linux は appimage）です。Android は apk または aab、iOS は ipa を生成します。各システムで作れるデスクトップのフォーマットはビルドマシンの条件にまとめています。

終了コード

3 で終わった実行は、プロジェクトが変わるまで再試行しても同じ結果になります。

ビルドレポート

--build-report は、何も開かずに終わった場合を含め、すべての結果について JSON ファイルを書き出します。

narraleaf-studio --build /projects/my-game --build-report /artifacts/report.json

このファイルには、結果と終了コード、解決されたプロジェクトとビルド要求、ビルド前チェックの全結果、成果物とそのサイズ、コード署名の有無とその認証情報の出どころ、そしてタイムスタンプ付きのビルドログ全体が記録されます。

ビルド前チェック

コマンドラインビルドは、ダイアログと同じチェックを実行します。ブロッキングの項目があるとコード 3 で中止し、チェック結果はすべてレポートとログに残ります。

Check before building（ビルド前に検査）がオンの間は、ビルドがプロジェクトの検査も実行し、レベルに書かれたとおりにビルドを止めます。

コード署名を付けられるターゲットで認証情報が設定されていない場合、ビルドは中止します。署名のない成果物を受け入れる場合は --build-allow-unsigned を付けます。

ビルド用のプロファイル

1 つのプロファイルにつき、同時に動く Studio は 1 つです。同じプロファイルで Studio を開いたままビルドを開始すると、コード 4 で中止します。

--build-user-data-dir は、この実行に専用のプロファイルを与えます。

narraleaf-studio --build /projects/my-game --build-user-data-dir /var/lib/narraleaf-agent/profile

新しいプロファイルには署名の認証情報も、Studio で設定した内容もありません。ビルドに必要な認証情報は --build-signing で、設定は --build-setting で渡します。

署名の認証情報

ビルドダイアログのSigning（署名）セクションから取り込んだ認証情報は、そのプロファイルのコマンドラインビルドすべてで使われます。オプションは不要です。

--build-signing は、その 1 回の実行のためだけに認証情報を渡します。ファイルに書かれたプラットフォームに適用され、プロジェクト側の選択より優先され、プロファイルには取り込まれません。

narraleaf-studio --build /projects/my-game --build-signing /run/secrets/signing.json

{
  "windows": { "kind": "windows-pfx", "file": "certs/app.pfx", "passwordEnv": "PFX_PASSWORD" },
  "macos": {
    "kind": "macos-apple",
    "p12File": "certs/developer-id.p12",
    "p12PasswordEnv": "P12_PASSWORD",
    "notaryKeyFile": "certs/notary.p8",
    "notaryKeyId": "ABCD1234",
    "notaryIssuerId": "6a0e1111-2222-3333-4444-555566667777"
  }
}

各項目はプラットフォーム名をキーにします。windows、macos、linux、android、ios です。ファイルのパスは、認証情報ファイルが置かれたフォルダを基準に解決されます。

macOS の 2 つの kind は、notaryKeyFile、notaryKeyId、notaryIssuerId を伴う場合に公証を行います。この 3 つは必ず揃えて指定します。

パスワードのフィールドはいずれも <フィールド>Env に置き換えられます。値は、そのパスワードを保持する環境変数の名前です。passwordEnv、p12PasswordEnv、storePasswordEnv、keyPasswordEnv が使えます。同じフィールドに両方の書き方を指定すると拒否されます。

ビルド設定

--build-setting は、その 1 回の実行のために設定を渡します。

narraleaf-studio --build /projects/my-game \
  --build-setting build.electronMirror=https://mirror.example/electron/

このオプションは繰り返し指定でき、build. で始まる設定のみを受け付けます。値が空の場合は公式のソースを使います。ログにはその実行が受け取った設定の名前だけが出ます。値は出力されず、レポートにも書き込まれません。

3 つのダウンロードミラーは Settings → Network（設定 → ネットワーク）の設定です。build.electronMirror は Electron download mirror（Electron のダウンロードミラー）、build.electronBuilderBinariesMirror は Build tooling mirror（ビルドツールのミラー）、build.zigMirror は Compiler toolchain mirror（コンパイラーツールチェーンのミラー）です。どれも既定の No mirror（ミラーを使わない）、Mirror in China（中国のミラー）、または自分で入力するアドレスから選べます。ダウンロードに失敗してビルドが止まったときは、これらの設定の場所が示されます。

プロジェクトの検査

--lint は、Problems（問題）パネルと同じプロジェクトの検査を画面なしで実行し、終了コードを返します。ビルドは生成しません。

narraleaf-studio --lint /projects/my-game --lint-report /artifacts/lint.json

--lint-plugin は --lint-plugin=名前 の書き方だけを受け付けます。--lint と --build は 1 つのコマンドラインに同時に指定できず、--lint を伴わない --lint-* オプションは拒否されます。

検査はプロジェクト自身の設定に従います。Off（オフ）にしたルールは飛ばされ、各指摘にはそのルールに設定したレベルが付きます。プロジェクトにエラーがあるとき、または Stop the build on（ビルドを止める条件）が Warnings and errors（警告とエラー）で警告があるとき、実行はコード 1 で終わります。軽微な警告と情報で失敗することはありません。コード 0 は検査を通ったことを表し、コード 2 と 4 の意味はビルドと同じです。

各指摘は、場所、メッセージ、ルール id を含む 1 行としてログに出ます。軽微な警告は info レベルで出ます。

--lint-report は、すべての結果について JSON ファイルを書き出し、結果、終了コード、Studio のバージョン、ログ全体を記録します。検査が実行された場合、その lint ブロックには次のものが入ります。

軽微な警告の severity は "minor" で、counts.minor に数えられます。

ビルドマシンの条件

すべてのターゲットは Windows でも macOS でもビルドできますが、作れるデスクトップのフォーマットは実行中のシステムによって決まります。ダイアログと同じです。

Windows 上では、macOS と Linux のパッケージはアーカイブに直接書き込まれます。Windows のフォルダは macOS アプリを構成するリンクも、Linux のプログラムに必要な権限も保持できず、ディスクイメージは macOS でしか作れないためです。ビルドマシンで作れないフォーマットは、プロジェクトを開く前に拒否されます。

Windows でビルドした macOS アプリには証明書の署名を付けられません。プレイヤーは初回起動時にシステム設定 → プライバシーとセキュリティでこのまま開くを選びます。署名のない Mac アプリを開くときと同じです。証明書による署名と公証には、引き続き Mac が必要です。

ビルドマシンにディスプレイは不要で、ログイン済みのデスクトップセッションも要りません。リモートシェルがあれば足ります。

あるプラットフォームの初回ビルドでは、そのプラットフォームに必要なファイルをダウンロードするため、以降の実行より時間がかかります。

ダイアログとその他のビルド設定については、実行とパッケージ化を参照してください。