플랫폼 참고 사항 - iOS

배포

iOS용 Qt 애플리케이션의 개발, 빌드, 실행 및 디버깅은 모두 macOS의 Qt Creator 를 사용하여 수행할 수 있습니다. 툴체인은 Apple의 Xcode에서 제공되며, iOS를 대상으로 하는 프로젝트에서 qmake 또는 CMake를 실행하면 초기 애플리케이션 설정이 포함된 Xcode 프로젝트 파일(.xcodeproj)이 생성됩니다. Qt Creator 는 iOS 플랫폼에 특화된 모든 설정을 관리할 수 있는 인터페이스를 제공하지 않으므로, 때로는 Xcode에서 직접 설정을 조정해야 할 수도 있습니다. 애플 앱 스토어에 애플리케이션을 제출하기 전에 애플리케이션이 올바르게 구성되었는지 확인하는 것이 특히 중요합니다.

애플리케이션 번들

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 개발자 라이브러리의 ‘정보 속성 목록 파일(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_BUNDLE_DATA qmake 변수를 사용하여 애플리케이션 번들로 복사할 파일 집합을 지정할 수 있습니다. 예를 들어:

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부터는 1024x1024 픽셀 크기의 이미지 하나만 있으면 됩니다. Xcode가 이 이미지를 바탕으로 필요한 모든 아이콘을 생성해 줍니다. 또한 자산 카탈로그에서 이미지를 수동으로 지정할 수도 있습니다.

지정할 수 있는 아이콘에 대한 자세한 목록은 아이콘 파일에서 확인할 수 있습니다.

파일 이름은 중요하지 않지만, 실제 픽셀 크기는 중요합니다. 범용 iOS 애플리케이션을 지원하려면 다음 이미지가 필요합니다:

AppIcon60x60@2x.png: 120 x 120 (iPhone용)
AppIcon76x76@2x~ipad.png: 152 x 152 (iPad용)
AppIcon167x167.png: 167x167 (iPad Pro용)
AppIcon1024x1024.png: 1024 x 1024 (App Store용)

iTunes에서 앱을 미리 볼 수 있도록 하려면 애드혹 배포 시 애플리케이션 번들에 다음 파일 이름도 포함해야 합니다:

iTunesArtwork 512x512
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()

런치 이미지

런치 스크린 대신 런치 이미지(PNG 파일)를 지정할 수도 있습니다.

참고: 런치 이미지는 iOS 13.0부터 지원이 중단되었으므로사용을 권장하지 않습니다. 대신 런치 화면으로 전환하는 것을 고려해 보세요.

런치 이미지는 애플리케이션 번들로 복사해야 하며, ` Info.plist ` 파일에서 ` UILaunchImages ` 키를 사용하여 해당 이름을 설정해야 합니다.

다음과 같은 이미지를 준비해야 합니다:

LaunchImage-iOS7-568h@2x.png: 640 x 1136
LaunchImage-iOS7-Landscape.png: 1024 x 768
LaunchImage-iOS7-Landscape@2x.png: 2048 x 1536
LaunchImage-iOS7-Portrait.png: 768 x 1024
LaunchImage-iOS7-Portrait@2x.png: 1536 x 2048
LaunchImage-iOS7@2x.png: 640 x 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 버전 범위에 대한 지원 여부를 표시하는 데 관련된 주요 개념은 다음과 같습니다:

배포 대상(Deployment target )은 애플리케이션이 지원하는 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 mkspec은 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 값을 표준으로 사용하므로 Info.plist 파일에 배포 대상 값과 일치하는 LSMinimumSystemVersion 항목을 추가해야 합니다.

Qt가 요구하는 것보다 낮은 배포 대상 값을 지정하면, Qt가 지원하는 버전보다 오래된 버전에서 실행될 때 애플리케이션이 Qt 라이브러리 어딘가에서 거의 확실하게 충돌할 것입니다. 따라서 실제 빌드 시스템 코드가 실제로 필요한 최소 OS 버전을 반영하고 있는지 확인하십시오.

Apple App Store에 게시하기

Qt for iOS 애플리케이션이 App Store에 게시할 준비가 되었는지 확인하는 방법은 ‘애플리케이션 제출’ 섹션에 설명된 대로 진행할 수 있습니다. 애플리케이션을 제출하려면 Xcode 또는 Application Loader(Xcode와 함께 설치됨)를 사용할 수 있습니다. Qt Creator 는 Xcode 프로젝트 구성의 모든 설정을 관리할 수 있는 인터페이스를 제공하지 않습니다.

애플리케이션은 지원 대상으로 지정된 iOS 버전 및 기기에서 테스트해야 합니다. Qt 애플리케이션의 최소 배포 대상은 Qt 버전에 따라 다릅니다. 자세한 내용은 지원되는 구성을 참조하십시오.

실제 게시 과정에는 배포 인증서 및 프로비저닝 프로파일 생성, 애플리케이션의 서명된 아카이브 생성, 그리고 이에 대한 일련의 유효성 검사 테스트 실행이 포함됩니다.

자세한 내용은 iOS 개발자 라이브러리의 ‘앱 배포 가이드’를 참조하십시오.

심볼 가시성 경고

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.