xcrun simctl runtime matchでSDKとランタイムビルドのマッピングを確認・上書きする

xcrun simctl runtime matchは、XcodeがビルドやSwiftUIプレビュー、シミュレータ起動の際にどのランタイムビルドを使うかを確認・上書きするサブコマンドである。特にベータ版OSのように同じバージョンで複数のビルドが存在する場合、どのビルドを優先するかを制御できる。

SDKとランタイムのマッピングを確認する

listオプションで、選択中のXcodeにおけるSDKとランタイムビルドのマッピングを確認できる。

$ xcrun simctl runtime match list
== Evaluation Results ==
appletvos26.5:
    SDK Version: 26.5
    SDK Build: 23L470
    Platform: com.apple.platform.appletvos
    Chosen Runtime: 23L470
        User Override: (null)
        Preferred: (null)
        Default: 23L470

iphoneos26.5:
    SDK Version: 26.5.1
    SDK Build: 23F81a
    Platform: com.apple.platform.iphoneos
    Chosen Runtime: 23F81a
        User Override: (null)
        Preferred: (null)
        Default: 23F81a
...

Chosen Runtimeが実際に使われるランタイムビルドで、User Override（後述のmatch setによる上書き）、Preferred（Xcode同梱またはSDKと完全一致したビルド）、Defaultのうち優先順位の高いものが採用される。

詳細情報を表示する

-vオプションを付けると、既知のSDK一覧に加えて、SDKバージョンごとのビルド対応表（プリファードビルドマップ）が表示される。

$ xcrun simctl runtime match list -v
== Known SDKs ==
    appletvos26.5
    iphoneos26.5
    watchos26.5
    xros26.5

== Preferred Build Map ==
iphoneos17.5:
    21F77  -->  21F79
    21F5058d  -->  21F5058d
...

-j（--json）オプションでJSON形式でも出力できる。 xcrun simctl runtime listでインストール済みのiOSシミュレータランタイムを確認するの-j出力と同様、トップレベルは配列ではなくオブジェクトになっている（ただしキーはUUIDではなくSDK名である）。

$ xcrun simctl runtime match list -j

{
  "iphoneos26.5" : {
    "chosenRuntimeBuild" : "23F81a",
    "defaultBuild" : "23F81a",
    "platform" : "com.apple.platform.iphoneos",
    "sdkBuild" : "23F81a",
    "sdkVersion" : "26.5.1"
  },
  ...
}

マッピングを上書きする

setにSDKの正式名称とランタイムビルドを指定すると、そのSDKで使うランタイムビルドを上書きできる。

$ xcrun simctl runtime match set iphoneos26.5 23F81a

実行後にmatch listで確認すると、User Overrideにビルド番号が反映されている。

iphoneos26.5:
    ...
    Chosen Runtime: 23F81a
        User Override: 23F81a

上書きを解除する

--defaultを指定すると、上書きを解除して既定の動作に戻せる。

$ xcrun simctl runtime match set iphoneos26.5 --default

実行後はUser Overrideが(null)に戻り、match set実行前の状態に復元される。

存在しないビルドを指定してもエラーにならない

実際に試したところ、存在しないランタイムビルド番号（例えば99Z999z）をsetに指定してもエラーにはならず、そのままUser Override・Chosen Runtimeに反映されてしまった。

$ xcrun simctl runtime match set iphoneos26.5 99Z999z
$ xcrun simctl runtime match list
...
    Chosen Runtime: 99Z999z
        User Override: 99Z999z

ビルド番号の実在性はコマンド側でチェックされない。タイプミスに気づかないまま、ビルドやシミュレータ起動の失敗につながる可能性がある。 setの後は-jやlistで意図した値が反映されているか確認するとよい。

このような実験目的の上書きを試したら、確認が終わり次第すぐに--defaultで元に戻しておく。

$ xcrun simctl runtime match set iphoneos26.5 --default

SDKビルドを明示的に指定する

--sdkBuildオプションで、現在選択されているXcode以外のSDKビルドを明示的に指定できる。省略した場合は、現在選択されているXcodeのSDKビルドが使われる。

$ xcrun simctl runtime match set iphoneos26.5 23F81a --sdkBuild 23F81a

複数のXcodeを切り替えて使っている場合、対象のSDKビルドを明示することで、意図しないXcodeバージョンに対して設定してしまうミスを防げる。

活用例: ベータ版OSでのビルド固定

ベータ版OSでは、同じバージョンに複数のビルドが提供されることも珍しくない。そのためXcodeの自動選択と、手元の環境で使いたいビルドとの間で食い違いが起きやすい。 match setで明示的にビルドを固定しておけば、チーム内で同じランタイムビルドを使ってビルド・テストする環境を揃えられる。検証や固定が終わったら--defaultで元の状態に戻すのを忘れないようにする。