Qt for HarmonyOS/user development guide/how to deply qml app

From Qt Wiki
Jump to navigation Jump to search

English 中文

QML Application Deployment Guide for HarmonyOS

Introduction

This document describes how to deploy Qt QML-based applications to HarmonyOS devices. HarmonyOS has specific requirements for QML application deployment, requiring different types of files to be placed in designated directory structures. This guide will detail the deployment steps and methods, and provide best practices for QML deployment.

Deployment Architecture Overview

When deploying QML applications in HarmonyOS, you need to follow this file organization structure: 

HarmonyOS Template Project Root Directory
├── entry
│   ├── libs
│   │   └── arm64-v8a
│   │       ├── Qt-related .so files
│   │       ├── Application .so files
│   │       └── qml/ (maintaining original directory structure for .so files)
│   └── src
│       └── main
│           └── resources
│               └── resfile
│                   └── qml/ (maintaining original directory structure for non-.so files)

Manual Deployment Steps

1. Preparation

First, ensure you have:

  • Qt installation directory (containing Qt libraries compiled for HarmonyOS)
  • Target HarmonyOS application project directory

2. Create Necessary Directory Structure

Manually create the following directory structure in the application project directory: 

# Create directories for .so files
mkdir -p entry/libs/arm64-v8a/qml

# Create directories for QML resource files
mkdir -p entry/src/main/resources/resfile/qml

3. Copy Qt Core Library Files

Manually copy core library files from Qt installation directory to target directory: 

# Copy Qt core libraries to libs/arm64-v8a directory
cp <Qt Installation Directory>/lib/libQt5Core.so entry/libs/arm64-v8a/
cp <Qt Installation Directory>/lib/libQt5Gui.so entry/libs/arm64-v8a/
cp <Qt Installation Directory>/lib/libQt5Network.so entry/libs/arm64-v8a/
cp <Qt Installation Directory>/lib/libQt5Qml.so entry/libs/arm64-v8a/
cp <Qt Installation Directory>/lib/libQt5Quick.so entry/libs/arm64-v8a/
# Copy other required Qt libraries...

Find and copy all necessary Qt core library files (

.so

files). These files are typically located in the lib folder of the Qt installation directory.

4. Copy Qt Plugins

Maintain directory structure and copy Qt plugins to target directory: 

# Copy all plugin directories and files, maintaining directory structure
cp -r <Qt Installation Directory>/plugins/* entry/libs/arm64-v8a/

5. Handle QML Module Files

QML module files require special handling, categorized by file type:

A. Handle QML Module .so Files

Traverse the qml directory in Qt installation directory, copy all .so files to libs/arm64-v8a/qml directory, maintaining original directory structure: 

# Check qml folder in Qt installation directory
# Manually create corresponding directory structure
# Copy .so files

For example, for <Qt Installation Directory>/qml/QtQuick/Controls/libqtquickcontrolsplugin.so: 

# Create target directory
mkdir -p entry/libs/arm64-v8a/qml/QtQuick/Controls
# Copy .so file
cp <Qt Installation Directory>/qml/QtQuick/Controls/libqtquickcontrolsplugin.so entry/libs/arm64-v8a/qml/QtQuick/Controls/

B. Handle QML Module Non-.so Files

Traverse the same qml directory in Qt installation directory, copy all non-.so files to resources/resfile/qml directory, maintaining original directory structure: 

# Check the same qml folder
# Manually create corresponding directory structure
# Copy all non-.so files (such as .qml, .js, etc.)

For example, for <Qt Installation Directory>/qml/QtQuick/Controls/Button.qml: 

# Create target directory
mkdir -p entry/src/main/resources/resfile/qml/QtQuick/Controls
# Copy non-.so files
cp <Qt Installation Directory>/qml/QtQuick/Controls/Button.qml entry/src/main/resources/resfile/qml/QtQuick/Controls/

6. Complete Manual Deployment Example

Assuming we need to deploy the QtQuick.Controls module, manual steps are as follows: 

QT_INSTALL_DIR=/home/user/qt/qt-5.12.12-harmonyos-arm

# 1. Find all files for this module in Qt installation directory
find <Qt Installation Directory>/qml/QtQuick/Controls -type f

# 2. Create corresponding directory structure
mkdir -p entry/libs/arm64-v8a/qml/QtQuick/Controls
mkdir -p entry/src/main/resources/resfile/qml/QtQuick/Controls

# 3. Copy .so files
find <Qt Installation Directory>/qml/QtQuick/Controls -name "*.so" | while read sofile; do
    # Get relative path
    relpath=$(echo $sofile | sed "s|$QT_INSTALL_DIR/qml/||")
    # Copy to target location
    mkdir -p $(dirname "entry/libs/arm64-v8a/qml/$relpath")
    cp "$sofile" "entry/libs/arm64-v8a/qml/$relpath"
done

# 4. Copy non-.so files
find <Qt Installation Directory>/qml/QtQuick/Controls -type f ! -name "*.so" | while read file; do
    # Get relative path
    relpath=$(echo $file | sed "s|$QT_INSTALL_DIR/qml/||")
    # Copy to target location
    mkdir -p $(dirname "entry/src/main/resources/resfile/qml/$relpath")
    cp "$file" "entry/src/main/resources/resfile/qml/$relpath"
done

QML Deployment Details

1. Dynamic Library Files (.so) Handling Principles

For QML applications, the following library files need to be manually deployed according to rules:

  • Qt Core Libraries: Such as libQt5Core.so, libQt5Gui.so, etc., these files should be placed in entry/libs/arm64-v8a directory
  • Qt Plugins: All plugin files should maintain their directory structure and be placed in entry/libs/arm64-v8a directory
  • QML Module .so Files: All QML-related .so files should maintain their directory structure and be placed in entry/libs/arm64-v8a/qml directory

2. Non-.so Files Handling Principles

For non-.so files in QML modules (such as .qml files, .js files, and other resources), they should maintain their directory structure and be placed in entry/src/main/resources/resfile/qml directory.

Best Practices

Manual Deployment Checklist

  • Core Library Files Check: Ensure all required Qt core libraries have been copied to entry/libs/arm64-v8a/ directory
  • Directory Structure Check: Ensure QML module directory structure is consistent in both target locations
  • File Classification Check: Ensure .so files and non-.so files are correctly classified into their respective directories

Application Development Recommendations

  • Correct QML Module References: Ensure correct module references in QML code. HarmonyOS will search for QML modules based on directory structure:
import QtQuick 2.12
import QtQuick.Controls 2.12
  • Resource Path Usage: When referencing resources in QML code, use relative paths, such as:
Image {
    source: "images/button.png"  // Path relative to current QML file
}
  • Plugin Dependency Check: If using third-party QML plugins, ensure related .so files and resource files are placed according to the above rules

Common Problem Solutions

QML Module Not Found

Check if the corresponding module's .so files and resource files have been correctly copied, maintaining directory structure unchanged

Application Crashes

Check if all required library files have been copied, especially libraries that specific modules depend on

Resource Files Not Visible

Confirm if non-.so files are correctly placed in entry/src/main/resources/resfile/qml directory

Custom QML Module Deployment

If you have developed custom QML modules, follow the same deployment rules as system QML modules:

  • Place module .so files in libs/arm64-v8a/qml/YourModuleName/ directory
  • Place module QML files, resource files, etc. in resources/resfile/qml/YourModuleName/ directory

For example, if you have a module named "MyCustomModule": 

libs/arm64-v8a/qml/MyCustomModule/libmycustommodule.so
resources/resfile/qml/MyCustomModule/MyComponent.qml
resources/resfile/qml/MyCustomModule/qmldir

Summary

Manual deployment of QML applications to HarmonyOS requires careful handling of file classification and directory structure. Although manual deployment is tedious, it helps developers better understand HarmonyOS QML application deployment requirements. Correct deployment ensures applications run properly on HarmonyOS devices.

Developers should pay special attention to correctly separating .so files and non-.so files into different directories while maintaining consistent directory structure. By following the manual deployment steps in this document, QML applications can be successfully deployed to the HarmonyOS platform.

Retrieved from "https://wiki.qt.io/index.php?title=Qt_for_HarmonyOS/user_development_guide/how_to_deply_qml_app&oldid=44804"