🖥️

CoreDevice: devicectlの概要と使用例

2023/11/14に公開

Flutter

iOS

Xcode

tech

CoreDeviceとは

Xcode 15より導入された新しいデバイス通信スタックです。CoreDeviceは、以下のOSバージョン以降のデバイス接続・通信に利用できます。

iOS, iPadOS, tvOS 17 ~
watch OS 8.7.1 ~

Xcodeの"Devices and Simulators"ウインドウなどでも利用されています。”Core"とついていますが、アプリから利用できるSDKではありません。

このスタックのおかげで、MacとApple Watch Series 6以降では、iPhoneによる仲介せず、ワイヤレス接続してデバック実行できるようになりました。（XcodeまたはInstruments経由のみ)^[1]

余談: Flutter 3.13よりXcode 15でiOSのデバック実行ができない問題への解決策として、このCoreDevice/devicectlを使っています。（加えてXcodeでのDebug実行にAutomationも併用しています)

さらに、CoreDeviceで接続されたデバイスを管理・操作するためのdevicectlという新しいコマンドラインツールが追加されました。

`devicectl`

Core Device Device Control: a command line utility for exercising Core Device functionality.

CoreDeviceのためのコマンドラインツールです。Androidにおける adb に相当するツールというとわかりやすいかもしれません。ただ、管理対象は実デバイスのみです。

これまでMacと接続したデバイスを管理操作するにはlibimobiledevice^[2]というツールを使ってきましたが、今後はdevicectlを使うことになります

devicectlには、4つのメインコマンドがあります。

list
device
manage
diagnose

さらにそれらにサブコマンドがあり、全部でおよそ17種類のコマンドを実行できます。

以下に、それら全ての使用例を掲載しています。

ざっと利用例を閲覧したい方は、本ページの「目次」を参照してください。

`list` コマンド

デバイス一覧⭐️

xcrun devicectl list devices

DDI一覧⭐️

xcrun devicectl list preferredDDI

`device` コマンド

アプリコンテナのファイル一覧⭐️

xcrun devicectl device info files \
  --device 00112233-4455-6677-8899-AABBCCDDEEFF \
  --domain-type appDataContainer \
  --domain-identifier "com.example.myapp" \
  --username root

appDataContainerは固定値です。
--usernameにrootを設定します。
xcrun devicectl -v deviceとすると詳細なログが出ますが、一覧が見辛くなります。

--subdirectoryを指定すると、ディレクトリを制限できる

xcrun devicectl device info files \
  --device 00112233-4455-6677-8899-AABBCCDDEEFF \
  --domain-type appDataContainer \
  --domain-identifier "com.example.myapp" \
  --username root \
  --subdirectory "Documents"

アプリアイコン生成

xcrun devicectl device info appIcon \
  --device 00112233-4455-6677-8899-AABBCCDDEEFF
  --app-bundle-id  "com.example.MyApp"
  --allow-placeholder true \
  --width 512 --height 512 --scale 2 \
  --destination appIcon.png

appIconはなぜか"CGImage was nil when attempting to write to a
destination."エラーなって動きません。
- https://developer.apple.com/forums/thread/738793
macOS Sonoma 14.1, Xcode 15.0.1で動作確認済み

アプリ一覧⭐️

xcrun devicectl device info apps \
  --device 00112233-4455-6677-8899-AABBCCDDEEFF

ロック状態

xcrun devicectl device info lockState  \
  --device 00112233-4455-6677-8899-AABBCCDDEEFF

プロセス一覧

xcrun devicectl device info processes
  --device 00112233-4455-6677-8899-AABBCCDDEEFF

デバイス詳細

xcrun devicectl device info details
  --device 00112233-4455-6677-8899-AABBCCDDEEFF

ディスプレイ仕様

xcrun devicectl device info displays
  --device 00112233-4455-6677-8899-AABBCCDDEEFF

DDIサービス一覧

xcrun devicectl device info ddiServices \
  --device 00112233-4455-6677-8899-AABBCCDDEEFF

アプリコンテナからファイルコピー (from Device)⭐️

xcrun devicectl device copy from \
  --device 00112233-4455-6677-8899-AABBCCDDEEFF \
  --domain-type appDataContainer \
  --domain-identifier "com.example.myapp" \
  --user root \
  --source "Library/Caches/app.log" \
  --destination app.log

appDataContainerは固定値です。
Directoryを指定するとエラーになります(再帰的な取得ではできません）
--userにrootを設定します。
- copyコマンドは、--usernameではなく、--userになっていることに注意

アプリコンテナへファイルコピー (to Device)⭐️

xcrun devicectl device copy to \
  --device 00112233-4455-6677-8899-AABBCCDDEEFF \
  --domain-type appDataContainer \
  --domain-identifier "com.example.myapp" \
  --user root --source "test.db" \
  --destination "Documents/test.db"

appDataContainerは固定値です。
Directoryを指定するとエラーになります(再帰的な取得ではできません）
--userにrootを設定します。
- copyコマンドは、--usernameではなく、--userになっていることに注意

アプリのインストール・アンインストール⭐️

xcrun devicectl device install app \
  --device 00112233-4455-6677-8899-AABBCCDDEEFF \
  MyApp.app

.app bundleは、Xcodeでビルド後、Productsにあるアプリを右クリックで、"Show In
Finder"して表示されます。

xcrun devicectl device uninstall app \
  --device 00112233-4455-6677-8899-AABBCCDDEEFF \
  com.example.MyApp

device info appsでBundle Idを取得しましょう。

端末の再起動

xcrun devicectl device reboot \
  --device 00112233-4455-6677-8899-AABBCCDDEEFF

`manage` コマンド

デバイスのペア・アンペア

xcrun devicectl manage pair --device 00112233-4455-6677-8899-aabbccddeeff

unpairすると再度接続するためには、cableの抜き差しが必要です。
cable接続時にペアリングダイアログ（デバイスを信頼するかどうか)が出るので、pairの使い所がわかっていません。

`diagnose` コマンド

CoreDeviceのログ取得

xcrun devicectl diagnose --devices 00112233-4455-6677-8899-aabbccddeeff

--deviceではなく、--devicesで複数デバイスを指定できます。
SysdiagnoseではなくCoreDeviceのログです。

Tips

JSONでデータを出力する

上記の使用例において、--json-outputオプションを指定すると出力データを、JSON形式でで結果を出力することができます。

--json-outputはファイル出力がメインですが、-を指定することで標準出力に変換できます。例えばで、デバイスリストのJSONを取得できます。

$ xcrun devicectl list devices  -q --json-output -
{
  "info" : {
    "arguments" : [
      "devicectl",
      "list",
     ...
}

脚注