プラットフォームに関する注意事項 - iOS

デプロイ

Qt for iOSアプリケーションの開発、ビルド、実行、デバッグはすべて、macOS上のQt Creator を使用して行うことができます。ツールチェーンはAppleのXcodeによって提供されており、iOS向けプロジェクトでqmakeまたはCMakeを実行すると、初期のアプリケーション設定が含まれたXcodeプロジェクトファイル（.xcodeproj）が生成されます。Qt Creator には、iOSプラットフォーム固有の設定をすべて管理するためのインターフェースが用意されていないため、Xcode上で直接設定を調整する必要がある場合があります。AppleのApp Storeへの公開申請を行う前には、アプリケーションが正しく構成されていることを確認することが特に重要です。

アプリケーションバンドル

iOSアプリケーションは通常、自己完結型のアプリケーションバンドルとして配布されます。アプリケーションバンドルには、アプリケーションの実行ファイルに加え、Qtライブラリ、プラグイン、翻訳、およびアプリケーションが必要とするその他のリソースなどの依存関係が含まれています。

CMake を使用してアプリケーションをアプリケーションバンドルとしてビルドするには、実行可能ファイルターゲットの MACOSX_BUNDLE プロパティを次のように設定します：

qt_add_executable(MyApp)
if(APPLE)
    set_target_properties(MyApp PROPERTIES MACOSX_BUNDLE TRUE)
endif()

qmake では、バンドルがデフォルト設定となっています。これを無効にするには、プロジェクトファイル（.pro ）で `CONFIG -= app_bundle ` を設定してください。

情報プロパティリストファイル

iOS および macOS における情報プロパティリストファイル (Info.plist) は、アプリケーションバンドルの設定に使用されます。これらの設定項目には以下が含まれます：

アプリケーションの表示名と識別子
必要なデバイスの機能
サポートされるユーザーインターフェースの向き
アイコンおよび起動画像

詳細については、iOS Developer Libraryの「Information Property List File」に関するドキュメントを参照してください。

CMake を使用した Info.plist

CMakeでは、ターゲットのMACOSX_BUNDLE プロパティがTRUE に設定されている場合、デフォルトのInfo.plist ファイルを生成します。残念ながら、そのファイルはiOSプロジェクトには適していません。

その代わりに、プロジェクトでは`qt_add_executable` を使用できます。これにより、iOS プロジェクトに適したデフォルト値を持つ `Info.plist ` ファイルが自動的に生成されます。

カスタム `Info.plist` を指定するには、以下に示すようにターゲットのプロパティ `MACOSX_BUNDLE_INFO_PLIST ` を設定します。これにより、`qt_add_executable` による自動ファイル生成が無効になり、代わりにプロジェクトで提供された `Info.plist ` ファイルに対して CMake のネイティブ処理が適用されます。

qt_add_executable(app)
if(IOS)
    set_target_properties(app
        PROPERTIES MACOSX_BUNDLE_INFO_PLIST "${CMAKE_CURRENT_SOURCE_DIR}/ios/Info.plist")
endif()

CMake によって行われるテンプレート置換に対して、どのターゲットプロパティや変数を指定できるかについては、CMake の MACOSX_BUNDLE_INFO_PLIST のドキュメントを参照してください。

QMake を使用した Info.plist

qmake を実行すると、適切なデフォルト値が設定された `Info.plist ` ファイルが生成されます。

次回qmakeを実行した際に上書きされないようにするため、生成されたInfo.plistを独自のコピーと置き換えることをお勧めします。.proファイル内でQMAKE_INFO_PLIST変数を使用して、カスタム情報プロパティリストを定義することができます。

ios {
    QMAKE_INFO_PLIST = ios/Info.plist
}

アプリケーションのアセット

Qtリソースにバンドルできないファイルについては、qmake変数 `QMAKE_BUNDLE_DATA` を使用することで、アプリケーションバンドルにコピーするファイルのセットを指定できます。例：

ios {
    fontFiles.files = $$files(fonts/*.ttf)
    fontFiles.path = fonts
    QMAKE_BUNDLE_DATA += fontFiles
}

CMake を使用する場合、次のようにして同じ処理を行うことができます:

qt_add_executable(app)
file(GLOB_RECURSE font_files CONFIGURE_DEPENDS "fonts/*.ttf")
if(IOS AND font_files)
    target_sources(app PRIVATE ${font_files})
    set_source_files_properties(
        ${font_files}
        PROPERTIES MACOSX_PACKAGE_LOCATION Resources/fonts)
endif()

画像リソースについては、Xcodeのアセットカタログを利用するという別の方法もあります。これは、qmakeを使用して次のように追加できます：

ios {
    QMAKE_ASSET_CATALOGS += ios/Assets.xcassets
}

CMake を使用する場合：

qt_add_executable(app)
set(asset_catalog_path "ios/Assets.xcassets")
target_sources(app PRIVATE "${asset_catalog_path}")
set_source_files_properties(
    ${asset_catalog_path}
    PROPERTIES MACOSX_PACKAGE_LOCATION Resources)

アイコン

Xcode 13以降では、アイコンをアセットカタログのアイコンセット（通常はAppIcon という名前）に追加する必要があります。そうすることで、XcodeがInfo.plist ファイルに正しいキーと値を自動的に更新し、必要なアイコンファイルをアプリケーションバンドルに直接コピーしてくれます。

Xcode 14以降では、1024×1024ピクセルサイズの画像が1つだけ必要となります。Xcodeが、その画像から必要なすべてのアイコンを生成します。また、アセットカタログ内で画像を手動で指定することも可能です。

指定可能なアイコンの詳細な一覧は、「アイコンファイル」で確認できます。

ファイル名は重要ではありませんが、実際のピクセルサイズは重要です。ユニバーサル iOS アプリケーションをサポートするには、以下の画像が必要です：

AppIcon60x60@2x.png: 120 x 120（iPhone用）
AppIcon76x76@2x~ipad.png: 152 x 152（iPad用）
AppIcon167x167.png: 167×167（iPad Pro用）
AppIcon1024x1024.png: 1024 x 1024（App Store用）

アドホック配布の場合、iTunesでアプリケーションを表示するには、アプリケーションバンドルに以下のファイル名を含める必要があります：

iTunesArtwork 512×512
iTunesArtwork@2x 1024x1024

アイコンを追加する最も簡単な方法は、Xcodeのドキュメント「アセットカタログとセットの作成」の手順に従うことです。

CMake を使用してプロジェクトをビルドする際は、Xcode によってアプリアイコンが確実に生成されるよう、以下の Xcode 属性を指定する必要があります。

set_target_properties(app_target_name PROPERTIES
    XCODE_ATTRIBUTE_ASSETCATALOG_COMPILER_APPICON_NAME AppIcon)

以下は、Xcode 14用のAssets.xcassets/AppIcon.appiconset/Contents.json ファイルの例です：

{
  "images" : [
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "20x20"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "20x20"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "29x29"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "29x29"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "38x38"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "38x38"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "40x40"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "40x40"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "60x60"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "60x60"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "64x64"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "64x64"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "68x68"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "76x76"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "83.5x83.5"
    },
    {
      "filename" : "AppIcon1024x1024.png",
      "idiom" : "universal",
      "platform" : "ios",
      "size" : "1024x1024"
    }
  ],
  "info" : {
    "author" : "xcode",
    "version" : 1
  }
}

起動画面と起動画像

起動画面

すべての iOS アプリは、アプリの起動中に表示される起動画面を用意する必要があります。起動画面は、インターフェースビルダーの `.xib ` ファイル（ストーリーボードファイルとも呼ばれます）です。詳細については、「アプリの起動画面の指定」を参照してください。

起動画面のサポートは、iOS 9.0から導入されました。

qmake と CMake の両方は、「LaunchScreen.storyboard 」という名前のデフォルトの起動画面を生成します。

カスタム起動画面を指定するには、そのファイルをアプリケーションバンドルにコピーし、Info.plist ファイル内でUILaunchStoryboardName キーをその起動画面の名前に設定する必要があります。

Qt では、Qt 6.4 以降で CMake によるカスタム起動画面が、Qt 6.0 以降で qmake によるカスタム起動画面がサポートされています。

起動ファイルの名前を `Launch.storyboard` とする場合、次のように `Info.plist ` に追加できます。

<key>UILaunchStoryboardName</key>
<string>Launch</string>

qmake を使用して起動画面をアプリケーションバンドルにコピーするには、プロジェクトの .pro ファイルに以下のコードスニペットを使用します:

ios {
    QMAKE_IOS_LAUNCH_SCREEN = $$PWD/Launch.storyboard
}

CMake を使用する場合：

qt_add_executable(app)
if(IOS)
    set_target_properties(app PROPERTIES
        QT_IOS_LAUNCH_SCREEN "${CMAKE_CURRENT_SOURCE_DIR}/Launch.storyboard")
endif()

Launch Images

起動画面の代わりに、起動画像（PNGファイル）を指定することも可能です。

注：起動画像の使用は 推奨されません。iOS 13.0以降、そのサポートは非推奨となっているためです。代わりに起動画面への切り替えをご検討ください。

起動画像はアプリケーションバンドルにコピーする必要があり、その名前はInfo.plist ファイル内でUILaunchImages キーを使用して設定する必要があります。

以下の画像を準備する必要があります：

LaunchImage-iOS7-568h@2x.png：640 x 1136
LaunchImage-iOS7-Landscape.png: 1024 × 768
LaunchImage-iOS7-Landscape@2x.png：2048 × 1536
LaunchImage-iOS7-Portrait.png: 768 x 1024
LaunchImage-iOS7-Portrait@2x.png：1536 x 2048
LaunchImage-iOS7@2x.png：640 × 960

これらの画像は、次のようにInfo.plist に追加できます：

<key>UILaunchImages</key>
<array>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 568}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 480}</string>
    </dict>
</array>
<key>UILaunchImages~ipad</key>
<array>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7-Landscape</string>
        <key>UILaunchImageOrientation</key>
        <string>Landscape</string>
        <key>UILaunchImageSize</key>
        <string>{768, 1024}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7-Portrait</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{768, 1024}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 568}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 480}</string>
    </dict>
</array>

qmake を使用して起動画像をアプリケーションバンドルにコピーするには、プロジェクトの .pro ファイルに以下のコードスニペットを追加してください：

ios {
    app_launch_images.files = $$files($$PWD/ios/LaunchImage*.png)
    QMAKE_BUNDLE_DATA += app_launch_images
}

CMake の場合：

qt_add_executable(app)
file(GLOB_RECURSE launch_images CONFIGURE_DEPENDS "ios/LaunchImage*.png")
if(IOS AND launch_images)
    target_sources(app PRIVATE ${launch_images})
    set_source_files_properties(
        ${launch_images}
        PROPERTIES MACOSX_PACKAGE_LOCATION Resources)
endif()

注：以前の バージョンのiOSでは、Info.plist 内のUILaunchImageFile キーを使用して単一のランチャーイメージを指定することが可能でしたが、iOS 10.0以降、この機能は非推奨となっています。

ネイティブの画像ピッカー

Info.plist ファイルにNSPhotoLibraryUsageDescription のエントリが含まれている場合、qmake はネイティブ画像ピッカーへのアクセスを可能にする追加のプラグインを自動的に組み込みます。

CMake の場合、qt_import_plugins を使用してネイティブ画像ピッカーを手動でリンクしてください：

qt_import_plugins(app INCLUDE Qt6::QIosOptionalPlugin_NSPhotoLibraryPlugin)

QFileDialog 内のディレクトリが次のように設定されている場合：

QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last();

あるいは、QML内のFileDialog にあるcurrentFolder が次のように設定されている場合：

shortcuts.pictures

これにより、ユーザーのフォトアルバムにアクセスできるネイティブの画像ピッカーが表示されます。

サポートされている iOS バージョンの指定

Appleのプラットフォームには、アプリケーションがサポートするOSバージョンを示す組み込みの仕組みがあります。これにより、古いバージョンのプラットフォームでは、アプリがクラッシュしてスタックトレースを表示するのではなく、ユーザーにOSのアップデートを促す使いやすいエラーメッセージが自動的に表示されます。

特定のOSバージョンの範囲に対するサポートを表明する際に重要な概念は、以下の通りです。

「デプロイメントターゲット」は、アプリケーションがサポートするmacOSまたはiOSの「ハードミニマムバージョン」を指定します。
SDKバージョンは、アプリケーションがサポートするmacOSまたはiOSの「ソフトマックス」バージョンを指定します。

Appleプラットフォーム向けのアプリケーションを開発する際は、常に開発時点で利用可能な最新のXcodeおよび最新のSDKを使用する必要があります。iOSなどの一部のプラットフォームでは、これに従わないと実際にApp Storeからの掲載が拒否されます。したがって、SDKバージョンは常にデプロイメントターゲット以上となります。

Appleプラットフォーム向けのアプリケーションを開発する際は、デプロイメントターゲットを設定する必要があります。Xcodeツールチェーン内のさまざまなビルドツール（コンパイラやリンカなど）には、この値を設定するためのフラグが用意されています。デプロイメントターゲットの値を設定することで、アプリケーションが少なくともそのバージョン以上で動作し、それより以前のOSバージョンでは動作しないことを明示的に宣言することになります。その後、システムAPIの使用が宣言内容と一致していることを確認するのは開発者の責任となります。コンパイラは宣言内容を認識しているため、その遵守を支援することができます。

SDKバージョンは、アプリケーションが互換性を持つOSの「ソフトな上限バージョン」と見なされます。つまり、アプリケーションが特定のSDKでビルドされた場合、OSがバイナリのロードコマンドをチェックし、古いOSとの下位互換性をエミュレートするため、より新しいOSバージョン上でもそのSDKの挙動を引き続き使用することになります。たとえば、アプリケーションが macOS 10.12 SDK を使用してビルドされた場合、10.13 以降であっても 10.12 の動作を引き続き使用します。

しかし、Mach-Oバイナリは本質的に前方互換性を持っています。例えば、iOS 9 SDKでビルドされたアプリケーションはiOS 10でも問題なく動作しますが、そのアプリケーションが新しいSDKに対して再コンパイルされるまでは、新しいリリースで特定の機能に対して行われた動作の変更が反映されない可能性があります。

最小OSバージョンは、コンパイラおよびリンカーのフラグを指定してMach-Oバイナリに埋め込むことで、システムに通知できます。さらに、アプリケーションのアプリバンドルには、LSMinimumSystemVersion キーを設定する必要があります。この値は、コンパイラおよびリンカーに渡された値と一致している必要があります。これにより、macOSでは、クラッシュダイアログが表示される代わりに、アプリケーションが新しいバージョンのOSを必要としていることを示す、ユーザーフレンドリーなエラーダイアログがOSによって表示されるようになります。また、「LSMinimumSystemVersion 」は、App Storeが必須のOSバージョンを表示するために使用するキーでもあり、コンパイラやリンカーのフラグはここには影響しません。

ほとんどの場合、Qtアプリケーションは問題なく動作します。たとえば、qmakeでは、Qtのmkspecsによって、QMAKE_IOS_DEPLOYMENT_TARGET またはQMAKE_MACOSX_DEPLOYMENT_TARGETが、Qt自体がサポートする最小バージョンに設定されます。同様に、Qbs では、Qt モジュールがcpp.minimumIosVersion 、cpp.minimumMacosVersion 、cpp.minimumTvosVersion 、またはcpp.minimumWatchosVersion を、Qt 自体がサポートする最小バージョンに設定します。

ただし、ターゲットバージョンを手動で設定する場合は注意が必要です。Qtが要求する値よりも高い値に設定し、独自のInfo.plist ファイルを指定する場合、OSはLSMinimumSystemVersion の値を基準として扱うため、デプロイメントターゲットの値と一致するLSMinimumSystemVersion エントリをInfo.plist に追加する必要があります。

Qtが要求する値よりも低いデプロイメントターゲット値を指定すると、Qtがサポートするバージョンより古いOS上でアプリケーションを実行した際、ほぼ確実にQtライブラリのどこかでクラッシュします。したがって、実際のビルドシステムのコードが、実際に必要とされるOSの最小バージョンを反映していることを確認してください。

Apple App Store への公開

Qt for iOS アプリケーションが App Store への公開準備ができているかどうかを確認するには、「アプリケーションの提出」に記載されている手順に従ってください。アプリケーションを提出するには、Xcode または Application Loader（Xcode とともにインストールされます）を使用できます。Qt Creator には、Xcode プロジェクト設定のすべての設定を管理するためのインターフェースは用意されていません。

アプリケーションは、サポート対象となっている iOS バージョンおよびデバイス上でテストする必要があります。Qt アプリケーションの最小デプロイメントターゲットは、Qt のバージョンによって異なります。詳細については、「サポートされている構成」を参照してください。

実際の公開プロセスには、配布用証明書とプロビジョニングプロファイルの作成、アプリケーションの署名済みアーカイブの作成、および一連の検証テストの実行が含まれます。

詳細については、iOS Developer Library の「App Distribution Guide」を参照してください。

シンボルの可視性に関する警告

C++ ライブラリのリンクにおいて、関数やオブジェクトはシンボルと呼ばれます。シンボルの可視性には、default またはhidden のいずれかがあります。

パフォーマンス上の理由から、Qtや他の多くのライブラリは、デフォルトでhidden の可視性を使用してソースをコンパイルし、ユーザープロジェクトで使用されることを意図しているシンボルのみにdefault の可視性を付与します。

残念ながら、あるライブラリがhidden の可視性でコンパイルされ、ユーザープロジェクトのアプリケーションやライブラリがdefault の可視性でコンパイルされている場合、Appleのリンカーが警告を発することがあります。

プロジェクト開発者がこの警告を抑制したい場合は、自身のプロジェクトコードもhidden の可視性でビルドする必要があります。

CMakeでは、CMakeLists.txt に以下のコードを追加することでこれを実現できます：

set(CMAKE_CXX_VISIBILITY_PRESET hidden)

qmake では、.pro ファイルに以下のコードを追加することで実現できます:

CONFIG+=hide_symbols

プロジェクトでライブラリをビルドする場合、別のライブラリやアプリケーションで使用されることを意図したライブラリ内のシンボルについては、default として明示的にマークする必要があります。例えば、そのような関数やクラスに `Q_DECL_EXPORT` を付与することで実現できます。

CMake における製品のアーカイブに関する問題

CMakeの不具合により、iOSアプリケーションを含むプロダクトアーカイブの作成に失敗する場合があります。

この現象は、Xcodeの「Product」→「Archive」メニュー項目を使用してアーカイブを作成しようとした場合と、コマンドラインで `xcodebuild -archivePath` を実行してアーカイブを作成しようとした場合の両方で発生する可能性があります。

エラーメッセージには、未定義のシンボルや存在しないファイルパスが記載されている場合があります。

この問題を回避するには、アーカイブの作成を試みる前に、必ずプロジェクトの `Release ` バージョンをビルドしてください。

CMake Xcodeプロジェクトによって作成されたxcarchiveにdSYMバンドルが含まれていない

XcodeのバグおよびCMakeの特定の制限により、CMakeで生成されたXcodeプロジェクトでは、Xcodeのアーカイブ処理中に、アプリケーションのdSYM バンドルがxcarchive に組み込まれなくなります。

Qt では、dSYM バンドルをxcarchive に含めるための回避策（オプトイン方式）を提供していますが、これにはトレードオフが伴います。つまり、以下の CMake 機能は正しく動作しなくなります：

$<TARGET_FILE:app> ジェネレータ式が、アプリのバイナリに到達しない無効なパスに展開される可能性がある
CMAKE_RUNTIME_OUTPUT_DIRECTORY 変数およびそれに関連するRUNTIME_OUTPUT_DIRECTORY ターゲットのプロパティは、設定されていても無視される
その他の未知の問題

上記の問題を軽減するには、以下の方法があります：

xcarchive を作成する際のみこの回避策を有効にし、プロジェクト開発中は有効にしない
実行ファイルやライブラリは、プロジェクトのルートディレクトリにのみ追加し、add_subdirectory の呼び出し内には追加しないようにしてください。

この回避策を有効にするには、プロジェクトを次のオプションで設定してください：

cmake . -DQT_USE_RISKY_DSYM_ARCHIVING_WORKAROUND=ON

または、qt_add_executable やqt_add_library を呼び出す前に、プロジェクト内で変数を設定してください：

set(QT_USE_RISKY_DSYM_ARCHIVING_WORKAROUND ON)

...

qt_add_executable(app)

ソースからのビルド HarmonyOS向けQt

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.