harmonydeployqt.qdoc

Go to the documentation of this file.

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
    \page harmonyos-deploy-qt-tool.html
    \brief An overview of the harmonydeployqt tool and how to use it.
    \title The harmonydeployqt Tool
 
    \target harmonydeployqt
 
    \note Qt for HarmonyOS is in technology preview and may change in future
    releases.
 
    Packaging a Qt application for HarmonyOS involves many steps, so Qt comes
    with a tool that handles the work for you. Building the CMake
    \c {<target>_make_hap} target runs \c harmonydeployqt automatically, so you
    normally do not invoke it manually. The overall packaging and deployment
    process is described in \l{Building and Deploying Qt Applications for
    HarmonyOS}.
 
    \section1 How it works
 
    Like \l{The androiddeployqt Tool}{androiddeployqt}, \c harmonydeployqt
    collects everything the application needs to run and assembles a deployable
    package:
 
    \list
        \li It gathers the application's shared library, the HarmonyOS platform
            plugin (\c libqohos.so), the required Qt modules and plugins, and,
            for Qt Quick applications, the QML modules.
        \li It places these into a HarmonyOS application template together with
            the metadata and permissions declared through the
            \l{Qt for HarmonyOS CMake API}.
        \li It invokes the OpenHarmony \c hvigor build tool to assemble the
            final HarmonyOS Ability Package (HAP).
    \endlist
 
    The settings that drive this process are passed to the tool in a JSON
    configuration file, which the CMake build generates for you.
 
    \section1 Command-line arguments
 
    The only required argument is \c {--input}. The list below is also available
    by passing \c {--help} to \c harmonydeployqt.
 
    \table
    \header
        \li Argument
        \li Description
    \row
        \li \c {--input <file>}
        \li JSON configuration file describing the application and the Qt
            installation to deploy. Required.
    \row
        \li \c {--output <dir>}
        \li Output directory for the generated HarmonyOS project.
    \row
        \li \c {--hvigor <path>}
        \li Path to the \c hvigorw script used to build the HAP. Can also be set
            with the \c QT_HARMONYOS_HVIGOR environment variable.
    \row
        \li \c {--install}
        \li Install the resulting HAP to a connected device using \c hdc.
    \row
        \li \c {--release}
        \li Build the release configuration. The default is debug.
    \row
        \li \c {--no-build}
        \li Generate the HarmonyOS project but skip building the HAP.
    \row
        \li \c {--test-bundle}
        \li Enable test bundle mode, which bundles all test binaries into a
            single HAP.
    \row
        \li \c {--verbose}
        \li Enable verbose output.
    \row
        \li \c {--depfile <path>}
        \li Write a dependency file for the build system to the given path.
    \row
        \li \c {--depfile-base <dir>}
        \li Base directory used for relative paths in the dependency file.
    \row
        \li \c {--help}
        \li Display the list of available arguments.
    \endtable
 
    \section1 Signing the HAP
 
    A HAP must be signed before it can be installed on a device. You can provide
    the signing material either through command-line arguments or through
    the matching environment variables. When both are given, the command-line
    argument wins for that individual field.
 
    \table
    \header
        \li Argument
        \li Environment variable
        \li Description
    \row
        \li \c {--signing-cert-path <p>}
        \li \c QT_HARMONYOS_SIGNING_CERT_PATH
        \li Path to the \c .cer certificate file.
    \row
        \li \c {--signing-profile <p>}
        \li \c QT_HARMONYOS_SIGNING_PROFILE
        \li Path to the \c .p7b provisioning profile.
    \row
        \li \c {--signing-store-file <p>}
        \li \c QT_HARMONYOS_SIGNING_STORE_FILE
        \li Path to the \c .p12 keystore.
    \row
        \li \c {--signing-key-alias <a>}
        \li \c QT_HARMONYOS_SIGNING_KEY_ALIAS
        \li Key alias inside the keystore.
    \row
        \li \c {--signing-key-password <s>}
        \li \c QT_HARMONYOS_SIGNING_KEY_PASSWORD
        \li Key password, encrypted by \c hvigor.
    \row
        \li \c {--signing-store-password <s>}
        \li \c QT_HARMONYOS_SIGNING_STORE_PASSWORD
        \li Keystore password, encrypted by \c hvigor.
    \row
        \li \c {--signing-plain-key-password <s>}
        \li \c QT_HARMONYOS_SIGNING_PLAIN_KEY_PASSWORD
        \li Key password, in plain text.
    \row
        \li \c {--signing-plain-store-password <s>}
        \li \c QT_HARMONYOS_SIGNING_PLAIN_STORE_PASSWORD
        \li Keystore password, in plain text.
    \row
        \li \c {--signing-alg <alg>}
        \li \c QT_HARMONYOS_SIGNING_ALG
        \li Signature algorithm. Defaults to \c SHA256withECDSA.
    \endtable
 
    Signing is all-or-nothing: if any signing input is set, all six required
    values (the certificate, profile, keystore, key alias, key password, and
    keystore password) must be present, otherwise \c harmonydeployqt fails. With
    none of them set, the HAP is left unsigned.
 
    Pass each password in one form only, and both in the same form.
 
    With encrypted passwords, \c harmonydeployqt writes the signing material
    into the \c signingConfigs of the generated \c build-profile.json5, and
    \c hvigor signs the HAP. \c hvigor can only decrypt passwords that were
    encrypted against the material directory it finds, such as the ones DevEco
    Studio writes into \c build-profile.json5.
 
    With plain passwords, \c harmonydeployqt signs the HAP with
    \c hap-sign-tool from the HarmonyOS SDK, after \c hvigor has packaged it.
    This does not depend on DevEco Studio. The tool is looked up under the SDK
    root, or at \c QT_HARMONYOS_HAP_SIGN_TOOL if that is set. It needs a Java
    runtime, taken from \c QT_HARMONYOS_JAVA, from \c JAVA_HOME, or from
    \c PATH.
 
    \note Plain passwords are passed to \c hap-sign-tool on its command line,
    which is the only input mode it supports in a non-interactive build. They
    are visible to other processes on the machine while it runs.
 
    \section1 Running the application
 
    Install and run the resulting HAP on a connected HarmonyOS device or on the
    emulator. The most convenient way to deploy and debug is to open the
    generated project in
    \l{https://developer.huawei.com/consumer/en/deveco-studio/}{DevEco Studio}
    and use its run and debug tooling.
 
    For more information about packaging and deploying a Qt application for
    HarmonyOS, see \l{Building and Deploying Qt Applications for HarmonyOS}.
*/