@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/lambda-capture-this.md

@@ -0,0 +1,135 @@
+# Lambda `[=, this]` capture: C++20→C++17 deprecation
+
+## Problem
+
+In C++20 (which Qt6 projects commonly use), `[=, this]` is a valid lambda capture that means "capture by copy, but also explicitly capture `this` by pointer". This is a deprecation reversal — C++17 deprecated `[=]` implicit `this` capture, and C++20 re-allowed explicit `[=, this]`.
+
+When compiling with C++17 (required by OHOS NDK), `[=, this]` is a **hard compile error**:
+
+```
+error: 'this' cannot be captured explicitly when the capture default is '='
+    [=, this]() { ... }
+              ^
+```
+
+This is NOT a Qt API issue — it's a **C++ standard version issue**. The OHOS NDK mandates C++17, so any code using C++20 lambda capture syntax must be downgraded.
+
+## Context Decision
+
+1. If code uses **`[=, this]`** (most common) → Strategy A (use `[=]` on OHOS)
+2. If code uses **`[=, *this]`** (capture `this` by copy, C++20 only) → Strategy B (replace with explicit captures)
+3. If code uses **`[=, this, ...]`** with additional captures → Strategy C (restructure capture)
+
+## Strategy A: Replace `[=, this]` with `[=]` (when: C++20 explicit this capture)
+
+On C++17, `[=]` already implicitly captures `this` by pointer. The `[=, this]` form was introduced in C++20 to be explicit about it. On OHOS (C++17), simply use `[=]`.
+
+### Before
+```cpp
+connect(ui->actionOpen, &QAction::triggered, this, [=, this]() {
+    openFile();
+});
+```
+
+### After
+```cpp
+connect(ui->actionOpen, &QAction::triggered, this,
+#ifdef __OHOS__
+    [=]()
+#else
+    [=, this]()
+#endif
+    {
+        openFile();
+    });
+```
+
+**Important**: This is purely a compile fix. At runtime, `[=]` and `[=, this]` behave identically — `this` is captured by pointer in both cases. The difference is only in the syntax the compiler accepts.
+
+### Batch Pattern
+
+When a file has many `[=, this]` occurrences (e.g., MainWindow.cpp with 15+ occurrences), the `#ifdef` pattern becomes very verbose. An alternative is a file-level macro:
+
+```cpp
+#ifdef __OHOS__
+#define LAMBDA_CAPTURE [=]
+#else
+#define LAMBDA_CAPTURE [=, this]
+#endif
+
+// Then in the file:
+connect(ui->actionOpen, &QAction::triggered, this, LAMBDA_CAPTURE() {
+    openFile();
+});
+```
+
+⚠️ This macro approach is less readable and should only be used when there are 5+ occurrences in a single file. For 1-4 occurrences, prefer the `#ifdef` pattern.
+
+## Strategy B: Replace `[=, *this]` (when: C++20 capture this by copy)
+
+`[*this]` captures a copy of the object (C++20 feature, not available in C++17). Must replace with explicit member copies or pointer capture.
+
+### Before
+```cpp
+connect(sender, &Sender::done, this, [=, *this]() {
+    qDebug() << name << "completed"; // 'name' is a member
+});
+```
+
+### After
+```cpp
+#ifdef __OHOS__
+    const QString nameCopy = name; // capture needed members by value
+    connect(sender, &Sender::done, this, [=, nameCopy]() {
+        qDebug() << nameCopy << "completed";
+    });
+#else
+    connect(sender, &Sender::done, this, [=, *this]() {
+        qDebug() << name << "completed";
+    });
+#endif
+```
+
+## Strategy C: Restructure `[=, this, x, y]` (when: additional explicit captures)
+
+If the lambda has additional explicit captures alongside `[=, this]`, restructure for C++17:
+
+### Before
+```cpp
+connect(sender, &Sender::done, this, [=, this, value]() {
+    process(value, memberVar);
+});
+```
+
+### After
+```cpp
+#ifdef __OHOS__
+    connect(sender, &Sender::done, this, [=, value]() {
+        process(value, memberVar);
+    });
+#else
+    connect(sender, &Sender::done, this, [=, this, value]() {
+        process(value, memberVar);
+    });
+#endif
+```
+
+Note: On OHOS, `[=, value]` already implicitly captures `this`, so the behavior is the same.
+
+## Common Mistakes
+
+- ❌ Do NOT use `[=, this]` unconditionally on OHOS — it is a hard compile error in C++17, not a warning.
+- ❌ Do NOT change `[=, this]` to `[this]` — that drops the by-value capture of other variables. Use `[=]` to preserve the by-value default.
+- ❌ Do NOT use `[&, this]` — while technically valid (same as `[&]`), it changes capture semantics from copy to reference, which can cause dangling references in asynchronous contexts.
+- ❌ Do NOT forget to handle lambdas in header files — if a `.h` file has inline methods with `[=, this]`, those need the same fix.
+- ❌ Do NOT confuse this with `[this]` (only captures `this`, no by-value copy of locals) — `[=, this]` captures everything by copy plus `this` by pointer, which on C++17 is just `[=]`.
+
+## Related Symbols
+
+- `CMAKE_CXX_STANDARD` — set to 17 for OHOS (see `cpp17-standard.md`)
+- `[=]` — C++17 default capture that implicitly includes `this`
+- `[=, *this]` — C++20 capture-by-copy, even more incompatible with C++17
+
+## Frequency
+
+This is one of the **most common** Qt6→Qt5 build failures in codebases that use `connect()` with lambda slots. Expect 10-20 occurrences in a typical MainWindow.cpp. The `check-compat` scanner covers `[=, this]` as an `auto-replace` pattern.

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/lexilla-static.md

@@ -0,0 +1,116 @@
+# LEXILLA_STATIC: Statically link lexilla on OHOS
+
+## Problem
+
+OHOS app sandbox cannot dlopen() lexilla at runtime. By default, lexilla builds as a shared library that the Scintilla editor loads dynamically via dlopen. On OHOS this fails with "cannot open shared object" or sandbox permission errors. Must add `target_compile_definitions(... PUBLIC LEXILLA_STATIC)` to statically link lexilla's lexer table into the app. Apply to both the lexilla target and the app target.
+
+## Context Decision
+
+1. If **lexilla is already in the build as any library type** → Strategy A (add LEXILLA_STATIC compile definition to both lexilla and app targets)
+2. If **lexilla must also be changed to STATIC** → Strategy B (change library type + define LEXILLA_STATIC)
+3. If **lexilla is not yet in the build** → Strategy C (add lexilla as static from source)
+
+## Strategy A: Add LEXILLA_STATIC Definition (when: lexilla is already in the build — most common)
+
+In lexilla's CMakeLists.txt, add the compile definition under OHOS:
+
+### Before
+```cmake
+if(UNIX)
+    target_link_libraries(lexilla PUBLIC dl)
+endif()
+```
+
+### After
+```cmake
+if(OHOS)
+    target_compile_definitions(lexilla PUBLIC LEXILLA_STATIC)
+    target_compile_features(lexilla PUBLIC cxx_std_17)
+elseif(UNIX)
+    target_link_libraries(lexilla PUBLIC dl)
+endif()
+```
+
+In the app's CMakeLists.txt, add `__OHOS__` and `LEXILLA_STATIC` to the app target:
+
+### Before
+```cmake
+target_compile_definitions(NotepadNext
+    PRIVATE
+        APP_VERSION="${APP_VERSION}"
+)
+```
+
+### After
+```cmake
+target_compile_definitions(NotepadNext
+    PRIVATE
+        APP_VERSION="${APP_VERSION}"
+)
+
+if(OHOS)
+    target_compile_definitions(NotepadNext
+        PRIVATE
+            __OHOS__
+            LEXILLA_STATIC
+    )
+endif()
+```
+
+The `PUBLIC` visibility on lexilla's definition ensures that the app target also sees LEXILLA_STATIC at compile time when it links lexilla. However, adding it explicitly to the app target as well is a safety net — Scintilla's header checks this macro at compile time and both targets must agree.
+
+## Strategy B: Change Library Type + Define (when: lexilla must also be STATIC)
+
+If the project's lexilla is SHARED and must be changed to STATIC under OHOS:
+
+### Before
+```cmake
+add_library(lexilla SHARED ${LEXILLA_SOURCES})
+target_compile_definitions(lexilla PRIVATE LEXILLA_STATIC)
+```
+
+### After
+```cmake
+if(OHOS)
+    add_library(lexilla STATIC ${LEXILLA_SOURCES})
+    target_compile_definitions(lexilla PUBLIC LEXILLA_STATIC)
+else()
+    add_library(lexilla SHARED ${LEXILLA_SOURCES})
+    target_compile_definitions(lexilla PRIVATE LEXILLA_STATIC)
+endif()
+```
+
+## Strategy C: Add Lexilla as Static from Source (when: lexilla not in build yet)
+
+### Before
+```cmake
+# lexilla not included
+add_library(scintilla STATIC ${SCINTILLA_SOURCES})
+```
+
+### After
+```cmake
+if(OHOS)
+    add_library(lexilla STATIC ${LEXILLA_SOURCES})
+    target_compile_definitions(lexilla PUBLIC LEXILLA_STATIC)
+    add_library(scintilla STATIC ${SCINTILLA_SOURCES})
+    target_compile_definitions(scintilla PUBLIC LEXILLA_STATIC)
+    target_link_libraries(scintilla PUBLIC lexilla)
+else()
+    add_library(scintilla STATIC ${SCINTILLA_SOURCES})
+    target_link_libraries(scintilla PRIVATE lexilla)
+endif()
+```
+
+## Common Mistakes
+
+- ❌ Do NOT define LEXILLA_STATIC as PRIVATE on the lexilla target — Scintilla and the app both need to see it at compile time for the static dispatch tables to be generated.
+- ❌ Do NOT change lexilla to STATIC without also adding LEXILLA_STATIC as a compile definition — the library type alone doesn't prevent Scintilla from trying to dlopen at runtime.
+- ❌ Do NOT forget to update both lexilla's CMakeLists and the app's CMakeLists — defining LEXILLA_STATIC only on one side causes symbol mismatches.
+- ❌ Do NOT use Lexilla's default "link and dlopen" code path on OHOS — even if the .so is present, the sandbox blocks dlopen.
+
+## Related Symbols
+
+- `lexilla` — lexer library for Scintilla
+- `scintilla` — text editing component that consumes lexilla
+- `__OHOS__` — must be defined alongside LEXILLA_STATIC on the app target

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/missing-include.md

@@ -0,0 +1,84 @@
+# Missing transitive includes: Qt6→Qt5 include dependency change
+
+## Problem
+
+Qt6 restructured header inclusion hierarchies — many headers that were transitively included in Qt6 are NOT included in Qt5. When compiling for OHOS (Qt 5.15.17), code that relied on transitive includes produces "incomplete type" or "undeclared identifier" errors.
+
+This is **NOT caught by `check-compat`** — the scanner checks symbol names, not include dependencies. These errors only surface during `build-so`.
+
+## Common Missing Includes
+
+| Missing include | Used symbol | Why it was transitively included in Qt6 | Error pattern |
+|----------------|------------|----------------------------------------|---------------|
+| `<QDebug>` | `qWarning() <<`, `qInfo() <<` | Included via `<QApplication>`, `<QGuiApplication>` | `incomplete type 'QDebug'`, `ambiguous operator<<` |
+| `<QUrl>` | `QUrl::fromLocalFile()`, `url.toString()` | Included via `<QDesktopServices>`, `<QNetworkRequest>` | `use of undeclared identifier 'QUrl'` |
+| `<QAction>` | `QAction` (in menus) | Included via `<QMenu>` in Qt6 | `use of undeclared identifier 'QAction'` |
+| `<QPluginLoader>` | `QPluginLoader` | Included via `<QCoreApplication>` in Qt6 | `unknown type name 'QPluginLoader'` |
+| `<QRegularExpression>` | `QRegularExpression` | Included via `<QString>` in Qt6 | `use of undeclared identifier 'QRegularExpression'` |
+
+## Strategy A: Add unconditional `#include` (when: header exists in both Qt5 and Qt6)
+
+If the header exists in both Qt5 and Qt6 (most do), just add it unconditionally. Extra includes are harmless.
+
+### Before
+```cpp
+#include <QMenu>
+#include <QStatusBar>
+
+// ... later
+QAction *act = menu->addAction("Open");
+```
+
+### After
+```cpp
+#include <QMenu>
+#include <QStatusBar>
+#include <QAction>  // Qt5: not transitively included via QMenu
+
+// ... later
+QAction *act = menu->addAction("Open");
+```
+
+### Quick Reference: Most Common Missing Includes
+
+```cpp
+#include <QDebug>    // for qWarning() <<, qInfo() <<, qDebug() <<
+#include <QUrl>      // for QUrl, url.toString()
+#include <QAction>   // for QAction (in menus/toolbar code)
+```
+
+## Strategy B: Add guarded `#include` (when: header is OHOS-specific or you want to be explicit)
+
+For includes that are only needed because of OHOS code paths (e.g., you added `#include <QUrl>` only because your OHOS branch uses `QUrl::toString()`):
+
+### After
+```cpp
+#ifdef __OHOS__
+#include <QUrl>
+#endif
+```
+
+## Strategy C: Discovery pattern (when: you hit "incomplete type" or "undeclared identifier" for a Qt type)
+
+When build-so fails with an error about a Qt type that you know exists:
+
+1. Identify the type name from the error message (e.g., `QUrl`)
+2. Check if the corresponding `#include <QUrl>` is present in the file
+3. If missing, add it — the type is real but wasn't transitively included
+4. If present, check if the include is guarded by `#ifdef` that may be excluding it
+
+## Common Mistakes
+
+- ❌ Do NOT add `#include <QtDebug>` — that's a Qt6-only convenience header. Use `<QDebug>`.
+- ❌ Do NOT add includes inside `#ifdef __OHOS__` when they're needed by all platforms — Qt5 desktop also benefits from explicit includes (they just happened to work transitively before).
+- ❌ Do NOT assume the error is about a missing symbol definition — "incomplete type" errors mean the compiler has seen a forward declaration but not the full definition, which is an include issue.
+
+## Related Symbols
+
+- `<QDebug>` — the single most common missing include; see `qdebug-include.md` for detailed analysis
+- `<QUrl>` — commonly needed in OHOS code paths that use QOpenHarmonyAbility
+- `check-compat` — cannot detect this class of issues; they only surface during compilation
+
+## Detection
+
+This pattern is **only discoverable during `build-so`**, not during `check-compat`. When fixing a build error, always check if the root cause is a missing include before assuming it's an API difference.

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/moc-exclude-sync.md

@@ -0,0 +1,93 @@
+# moc-Exclude Sync: Exclude .h When Excluding .cpp
+
+## Problem
+
+When excluding source files from a CMake target using `list(FILTER srcs EXCLUDE REGEX ...)`, the corresponding header files must also be excluded from the headers list. If only the `.cpp` is excluded but the `.h` remains, AUTOMOC will still process the header and generate `moc_*.cpp` code that references symbols defined in the excluded `.cpp`, causing linker errors:
+
+```
+ld.lld: error: undefined symbol: HelpDialog::~HelpDialog()
+>>> referenced by mocs_compilation.cpp
+>>>               gui/CMakeFiles/cppcheck-gui.dir/cppcheck-gui_autogen/mocs_compilation.cpp.o:(vtable for HelpDialog)
+```
+
+This typically happens when excluding a dialog/module that depends on a Qt component unavailable in the OHOS SDK (e.g., Qt5 Help module's `qcollectiongenerator` not available in cross-compile).
+
+## Context Decision
+
+- If the excluded module has its own `.h`, `.cpp`, and `.ui` files → **Strategy A**.
+- If the module is deeply entangled with other code (included from many places) → **Strategy B**.
+
+## Strategy A: Exclude All Module Files from CMake (recommended)
+
+Exclude the `.h`, `.cpp`, and `.ui` files together. This prevents AUTOMOC from generating code for the excluded class.
+
+### Before
+```cmake
+file(GLOB hdrs "*.h")
+file(GLOB srcs "*.cpp")
+file(GLOB uis  "*.ui")
+
+# Only exclude the .cpp — WRONG!
+if(OHOS)
+    list(FILTER srcs EXCLUDE REGEX "helpdialog\\.cpp$")
+endif()
+```
+
+### After
+```cmake
+file(GLOB hdrs "*.h")
+file(GLOB srcs "*.cpp")
+file(GLOB uis  "*.ui")
+
+# Exclude .h, .cpp, AND .ui together
+if(OHOS)
+    list(FILTER hdrs EXCLUDE REGEX "helpdialog\\.h$")
+    list(FILTER srcs EXCLUDE REGEX "helpdialog\\.cpp$")
+    list(FILTER uis  EXCLUDE REGEX "helpdialog\\.ui$")
+endif()
+```
+
+**Why `.ui` too?** The `.ui` file generates `ui_helpdialog.h` via `qt5_wrap_ui`. If it's not excluded, the generated UI header will reference `HelpDialog` and may cause additional compilation issues.
+
+## Strategy B: Guard #include of Excluded Headers
+
+If the excluded header is included from other source files (not just by the excluded `.cpp`), you need to guard those includes too.
+
+### Before
+```cpp
+#include "helpdialog.h"  // unconditionally included
+```
+
+### After
+```cpp
+#ifndef __OHOS__
+#include "helpdialog.h"
+#endif
+```
+
+And guard any usage:
+```cpp
+void MainWindow::openOnlineHelp()
+{
+#ifndef __OHOS__
+    auto *helpDialog = new HelpDialog;
+    helpDialog->showMaximized();
+#endif
+}
+```
+
+**Note**: If you exclude the `.h` from CMake (Strategy A), you MUST also add `#ifndef __OHOS__` guards on any `#include "helpdialog.h"` in other files. Otherwise, the compiler won't find the header at all (it's not in the project anymore), and you'll get a different error: `fatal error: 'helpdialog.h' file not found`.
+
+## Common Mistakes
+
+- ❌ Don't exclude only the `.cpp` — AUTOMOC processes `.h` files independently of `.cpp` files. The `Q_OBJECT` macro in the `.h` triggers moc code generation regardless of whether the `.cpp` is in the build.
+- ❌ Don't forget to guard `#include "excluded.h"` in other source files after excluding the `.h` from CMake.
+- ❌ Don't try to work around this by adding `set_source_files_properties(helpdialog.h PROPERTIES SKIP_AUTOMOC ON)` — while technically possible, it's fragile and doesn't scale. The `list(FILTER ... EXCLUDE ...)` approach is cleaner.
+- ❌ Don't forget the `.ui` file — it generates a `ui_*.h` header that may also need exclusion.
+- ❌ Don't exclude the `.h` but leave the `Q_DECLARE_METATYPE(ExcludedType)` in a still-compiled header — this creates a different kind of linker error (see `qdeclare-metatype-incomplete.md`).
+
+## Related Symbols
+
+- `AUTOMOC` — CMake property that auto-generates moc files for Q_OBJECT classes
+- `list(FILTER ... EXCLUDE ...)` — CMake command to remove items from a list
+- `Q_OBJECT` — macro that triggers moc code generation

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/movetotrash.md

@@ -0,0 +1,50 @@
+# moveToTrash: Uncertain Behavior on OHOS
+
+## Problem
+
+QFile::moveToTrash() exists in Qt 5.15 but its behavior on OHOS is uncertain — the platform may not implement a trash/recycle concept, and the call may fail silently, do nothing, or return false. This leads to data loss if the user expects the file to be recoverable.
+
+## Context Decision
+
+If the application must guarantee file deletion semantics on OHOS, use QFile::remove() directly. If moveToTrash is called conditionally and failure is already handled, a simple guard may suffice.
+
+## Strategy A: Replace with QFile::remove() under #ifdef __OHOS__ (when: file must be deleted and no trash concept is acceptable)
+
+### Before
+```cpp
+#include <QFile>
+
+void deleteFile(const QString &path) {
+    if (!QFile::moveToTrash(path)) {
+        qWarning() << "Failed to move to trash:" << path;
+    }
+}
+```
+
+### After
+```cpp
+#include <QFile>
+
+void deleteFile(const QString &path) {
+#ifdef __OHOS__
+    if (!QFile::remove(path)) {
+        qWarning() << "Failed to remove:" << path;
+    }
+#else
+    if (!QFile::moveToTrash(path)) {
+        qWarning() << "Failed to move to trash:" << path;
+    }
+#endif
+}
+```
+
+## Common Mistakes
+
+- ❌ Don't call QFile::moveToTrash() on OHOS and assume the file is recoverable — it likely isn't, and the function may return false or do nothing.
+- ❌ Don't use QFile::remove() unconditionally — on desktop platforms users expect trash behavior where files can be recovered.
+- ❌ Don't forget to warn the user that deletion is permanent on OHOS — the UX expectation differs from desktop trash behavior.
+
+## Related Symbols
+
+- `QFile::remove` — permanent deletion fallback for OHOS
+- `QFile::moveToTrash` — desktop trash behavior (keep for non-OHOS)

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/ohextras.md

@@ -0,0 +1,84 @@
+# OhExtras: Required OHOS Qt5 platform module
+
+## Problem
+
+The OHOS Qt5 SDK provides the Qt5::OhExtras module containing QOpenHarmonyAbility, QOpenHarmonyWant, and QOhAppContext — the essential bridge between Qt widgets and the OHOS application lifecycle. Without OhExtras in both find_package(Qt5 COMPONENTS ...) and target_link_libraries(... Qt5::OhExtras), linking fails with undefined reference to QOpenHarmonyAbility and related symbols.
+
+## Context Decision
+
+1. If **project root CMakeLists.txt has find_package(Qt5 ...)** → Strategy A (add OhExtras component)
+2. If **target_link_libraries is missing Qt5::OhExtras** → Strategy B (add link target)
+3. If **third-party lib CMakeLists has its own find_package(Qt5 ...)** → Strategy C (do NOT add OhExtras there)
+
+## Strategy A: Add OhExtras to find_package (when: project root find_package missing OhExtras)
+
+### Before
+```cmake
+if(OHOS)
+    find_package(Qt5 REQUIRED COMPONENTS Core Gui Widgets Network PrintSupport)
+else()
+    find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets Network PrintSupport Core5Compat)
+endif()
+```
+
+### After
+```cmake
+if(OHOS)
+    find_package(Qt5 REQUIRED COMPONENTS Core Gui Widgets Network PrintSupport OhExtras)
+else()
+    find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets Network PrintSupport Core5Compat)
+endif()
+```
+
+## Strategy B: Add Qt5::OhExtras to target_link_libraries (when: link step missing OhExtras)
+
+### Before
+```cmake
+if(OHOS)
+    target_link_libraries(MyApp PRIVATE Qt5::Core Qt5::Widgets Qt5::Network Qt5::PrintSupport)
+else()
+    target_link_libraries(MyApp PRIVATE Qt6::Core Qt6::Widgets Qt6::Network Qt6::PrintSupport Qt6::Core5Compat)
+endif()
+```
+
+### After
+```cmake
+if(OHOS)
+    target_link_libraries(MyApp PRIVATE Qt5::Core Qt5::Widgets Qt5::Network Qt5::PrintSupport Qt5::OhExtras)
+else()
+    target_link_libraries(MyApp PRIVATE Qt6::Core Qt6::Widgets Qt6::Network Qt6::PrintSupport Qt6::Core5Compat)
+endif()
+```
+
+## Strategy C: Do NOT Add OhExtras to Third-party Libs (when: third-party CMakeLists)
+
+Third-party libraries (scintilla, lexilla, etc.) do not use OHOS-specific APIs and should NOT link OhExtras.
+
+### Before
+```cmake
+if(OHOS)
+    find_package(Qt5 COMPONENTS Core Widgets OhExtras REQUIRED)
+    target_link_libraries(scintilla PUBLIC Qt5::Core Qt5::Widgets Qt5::OhExtras)
+endif()
+```
+
+### After
+```cmake
+if(OHOS)
+    find_package(Qt5 COMPONENTS Core Widgets REQUIRED)
+    target_link_libraries(scintilla PUBLIC Qt5::Core Qt5::Widgets)
+endif()
+```
+
+## Common Mistakes
+
+- ❌ Do NOT forget to add OhExtras to BOTH find_package and target_link_libraries — adding it to only one will either fail at CMake configure time or at link time.
+- ❌ Do NOT add OhExtras to third-party library targets — they don't use QOpenHarmonyAbility and the extra link dependency is unnecessary.
+- ❌ Do NOT add OhExtras outside the OHOS branch — it does not exist in upstream Qt5 and will cause find_package to fail on non-OHOS builds.
+- ❌ Do NOT confuse OhExtras with a QPA plugin — OhExtras is a link-time module, while the QPA platform plugin is loaded at runtime.
+
+## Related Symbols
+
+- `QOpenHarmonyAbility` — OHOS app lifecycle bridge class
+- `QOpenHarmonyWant` — OHOS intent/want wrapper
+- `QOhAppContext` — OHOS application context accessor

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/packaging-cmake.md

@@ -0,0 +1,62 @@
+# Packaging.cmake: Guard desktop packaging under OHOS
+
+## Problem
+
+Desktop packaging (CPack, DMG, NSIS, windeployqt, macdeployqt) does not apply to OHOS. OHOS uses HAP packaging instead. Including Packaging.cmake unconditionally causes CMake configure failures when desktop-specific packaging commands or dependencies are unavailable on the OHOS cross-compile host.
+
+## Context Decision
+
+1. If **include(Packaging.cmake) is at project root** → Strategy A (guard the include)
+2. If **Packaging.cmake contains CPack/DEB/RPM/DMG/NSIS setup** → no additional action needed beyond guarding the include
+
+## Strategy A: Guard the Include (when: include(Packaging.cmake))
+
+Wrap the include in if(NOT OHOS). OHOS packaging is handled separately by the HAP build pipeline.
+
+### Before
+```cmake
+include(Packaging.cmake)
+```
+
+### After
+```cmake
+if(NOT OHOS)
+    include(Packaging.cmake)
+endif()
+```
+
+If Packaging.cmake also defines install() rules that are needed under OHOS (e.g., installing shared libraries), split them out:
+
+### Before
+```cmake
+# Packaging.cmake
+install(TARGETS MyApp RUNTIME DESTINATION bin)
+install(FILES ${QT_LIBS} DESTINATION lib)
+
+# Desktop packaging
+set(CPACK_GENERATOR "DEB;RPM;NSIS")
+include(CPack)
+```
+
+### After
+```cmake
+# CMakeLists.txt — install rules that apply everywhere
+install(TARGETS MyApp RUNTIME DESTINATION bin)
+
+# Desktop-only packaging
+if(NOT OHOS)
+    include(Packaging.cmake)
+endif()
+```
+
+## Common Mistakes
+
+- ❌ Do NOT try to use CPack for OHOS — HAP packaging is a completely different pipeline using hvigorw and AppSignTool.
+- ❌ Do NOT forget to guard include(Packaging.cmake) — it will fail when windeployqt or macdeployqt is not found.
+- ❌ Do NOT remove install() rules that install shared libraries — those may still be needed for the HAP's libs/ directory.
+
+## Related Symbols
+
+- `CPack` — desktop-only, not used on OHOS
+- `windeployqt` — Windows-only deployment tool
+- `macdeployqt` — macOS-only deployment tool