harmonydeployqt 도구
참고: HarmonyOS용Qt는 기술 미리보기 단계에 있으며 향후 릴리스에서 변경될 수 있습니다.
HarmonyOS용 Qt 애플리케이션을 패키징하는 과정에는 여러 단계가 포함되므로, Qt에는 이 작업을 대신 처리해 주는 도구가 함께 제공됩니다. CMake <target>_make_hap 타깃을 빌드하면 harmonydeployqt 가 자동으로 실행되므로, 일반적으로 수동으로 호출할 필요는 없습니다. 전체적인 패키징 및 배포 과정은 ‘HarmonyOS용 Qt 애플리케이션 빌드 및 배포’에서 설명되어 있습니다.
작동 원리
androiddeployqt와 마찬가지로, harmonydeployqt 는 애플리케이션 실행에 필요한 모든 요소를 수집하여 배포 가능한 패키지를 생성합니다:
- 애플리케이션의 공유 라이브러리, HarmonyOS 플랫폼 플러그인(
libqohos.so), 필요한 Qt 모듈 및 플러그인, 그리고 Qt Quick 애플리케이션의 경우 QML 모듈을 수집합니다. - 이 모든 구성 요소를 Qt for HarmonyOS CMake API를 통해 선언된 메타데이터 및 권한과 함께 HarmonyOS 애플리케이션 템플릿에 배치합니다.
- OpenHarmony
hvigor빌드 도구를 호출하여 최종 HarmonyOS Ability Package(HAP)를 생성합니다.
이 프로세스를 구동하는 설정은 JSON 구성 파일을 통해 도구로 전달되며, 이 파일은 CMake 빌드가 자동으로 생성합니다.
명령줄 인수
유일한 필수 인수는 ` --input`입니다. 아래 목록은 ` harmonydeployqt`에 ` --help `을 전달하여도 확인할 수 있습니다.
| 인수 | 설명 |
|---|---|
--input <file> | 배포할 애플리케이션 및 Qt 설치 정보를 기술한 JSON 구성 파일입니다. 필수입니다. |
--output <dir> | 생성된 HarmonyOS 프로젝트의 출력 디렉터리. |
--hvigor <path> | HAP를 빌드하는 데 사용되는 ` hvigorw ` 스크립트의 경로입니다. ` QT_HARMONYOS_HVIGOR ` 환경 변수를 사용하여 설정할 수도 있습니다. |
--install | hdc 를 사용하여 생성된 HAP를 연결된 기기에 설치합니다. |
--release | 릴리스 구성을 빌드합니다. 기본값은 디버그입니다. |
--no-build | HarmonyOS 프로젝트를 생성하되 HAP 빌드는 건너뜁니다. |
--test-bundle | 모든 테스트 바이너리를 단일 HAP로 묶는 테스트 번들 모드를 활성화합니다. |
--verbose | 상세 출력을 활성화합니다. |
--depfile <path> | 빌드 시스템용 의존성 파일을 지정된 경로에 작성합니다. |
--depfile-base <dir> | 의존성 파일 내 상대 경로에 사용되는 기준 디렉터리입니다. |
--help | 사용 가능한 인자 목록을 표시합니다. |
HAP 서명
HAP를 기기에 설치하려면 먼저 서명해야 합니다. 서명 자료는 명령줄 인수를 통해 제공하거나 해당 환경 변수를 설정하여 제공할 수 있습니다. 둘 다 지정된 경우, 해당 필드에 대해서는 명령줄 인수가 우선 적용됩니다.
| 인수 | 환경 변수 | 설명 |
|---|---|---|
--signing-cert-path <p> | QT_HARMONYOS_SIGNING_CERT_PATH | .cer 인증서 파일의 경로. |
--signing-profile <p> | QT_HARMONYOS_SIGNING_PROFILE | .p7b 프로비저닝 프로파일의 경로. |
--signing-store-file <p> | QT_HARMONYOS_SIGNING_STORE_FILE | .p12 키 저장소의 경로. |
--signing-key-alias <a> | QT_HARMONYOS_SIGNING_KEY_ALIAS | 키 저장소 내의 키 별칭. |
--signing-key-password <s> | QT_HARMONYOS_SIGNING_KEY_PASSWORD | 암호화된 키의 암호. |
--signing-store-password <s> | QT_HARMONYOS_SIGNING_STORE_PASSWORD | 암호화된 키스토어 암호. |
--signing-alg <alg> | QT_HARMONYOS_SIGNING_ALG | 서명 알고리즘. 기본값은 SHA256withECDSA 입니다. |
비밀번호는 일반 텍스트가 아닌 hvigor-encrypted 블롭이어야 합니다. 서명은 ‘전부 또는 전무’ 방식입니다. 서명 입력값이 하나라도 설정된 경우, 필수 6가지 값(인증서, 프로필, 키스토어, 키 별칭, 키 비밀번호, 키스토어 비밀번호)이 모두 존재해야 합니다. 그렇지 않으면 HAP는 서명되지 않은 상태로 남습니다.
애플리케이션 실행
생성된 HAP를 연결된 HarmonyOS 기기나 에뮬레이터에 설치하고 실행합니다. 배포 및 디버깅을 하는 가장 편리한 방법은 DevEco Studio에서 생성된 프로젝트를 열고, 해당 실행 및 디버깅 도구를 사용하는 것입니다.
HarmonyOS용 Qt 애플리케이션의 패키징 및 배포에 대한 자세한 내용은 ‘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.
