Run on HarmonyOS devices

To build an application and run it on a device:

1. Connect the device, as described in Connect HarmonyOS devices.
2. Set the HarmonyOS SDK location and the signing material in Preferences > SDKs > HarmonyOS, as described in Set up the HarmonyOS SDK and Sign HarmonyOS packages.
3. Activate the kit that has the device as its run device.
4. Select (Run).

Running deploys first, and the whole chain is harmonydeployqt, hvigor, hap-sign-tool, hdc install, and aa start. The run then stays alive as long as the application does, by following its hilog output. Stopping it force-stops the application.

Debug on a device

Select Debug > Start Debugging > Start Debugging of Startup Project. The application starts, a debug server starts inside it, Qt Creator attaches to that, and breakpoints resolve both in the application and in Qt.

Choose where to put a breakpoint with the attach in mind. The device refuses PTRACE_TRACEME, so nothing can be launched under the debugger and Qt Creator attaches to an application that is already running. Whatever main() reaches directly has therefore happened before the debugger gets there. Put the breakpoint somewhere the event loop reaches later, such as a slot or a destructor.

Frames in the system libraries stay nameless. Symbols are matched against local copies of what the process mapped, and there are none for the HarmonyOS framework.

Troubleshoot errors

A debug run fails without a message

A Qt Creator that did not shut down cleanly leaves an hdc port forwarding behind, and hdc refuses a second forwarding to the same remote port. List ports with hdc fport ls and remove the stale one with hdc fport rm <local> <remote>.

The application starts and quits at once

The application found no libraries to load. Check that Additional packages points at the prefix the third-party libraries are installed under, as described in Specify HarmonyOS deploy settings. The device reports this as an ArkTS TypeError that names nothing useful.

The application ignores a changed argument

aa start passes its parameters as arguments only when the process starts, so an application that is still running keeps the old ones. Stop it first.

Packaging fails, or the package is gone

Use command-line tools 6.1 or newer. Version 6.0.2 deletes the generated project directly after packaging, and takes the package with it.

The build fails with "cmake: not found"

The build directory outlived the Qt it was configured with. Reset the CMake configuration for the kit.

What is not possible

• Stopping in code that runs before the debugger attaches, such as a static initializer or the early part of main().
• Debugging an application that is not a Qt one. The debug server is shipped and started as part of the Qt application package, and there is no other foothold.