From 9b15cee841416b7081f9816fa4e16726e0e524d3 Mon Sep 17 00:00:00 2001 From: Torsten Wierschin Date: Thu, 16 Jul 2026 08:40:13 +0200 Subject: [PATCH] Add migration helpers: migrate_module.sh and MIGRATION_CHECKLIST.md\n\nProvide a repeatable migration script and checklist to standardize adding modules (./Lts, ./...) for Qt6/C++20 migration.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- migration/MIGRATION_CHECKLIST.md | 41 ++++++++++++++++++++++++++++++++ migration/migrate_module.sh | 32 +++++++++++++++++++++++++ 2 files changed, 73 insertions(+) create mode 100644 migration/MIGRATION_CHECKLIST.md create mode 100755 migration/migrate_module.sh diff --git a/migration/MIGRATION_CHECKLIST.md b/migration/MIGRATION_CHECKLIST.md new file mode 100644 index 000000000..797169ce0 --- /dev/null +++ b/migration/MIGRATION_CHECKLIST.md @@ -0,0 +1,41 @@ +Migration checklist and template + +Purpose +This document standardizes the per-module migration steps to Qt6/C++20 and the minimal CMake/Docker changes required so new folders (./Lts, ./...) can be migrated repeatedly and reproducibly. + +Preconditions +- app/Dockerfile and app/run_docker.sh are present and produce a Qt6 dev image with these tools: cmake (>=3.20), ninja, clang/gcc with C++20, pkg-config, libpoppler-qt6-dev, python3 + aqtinstall, and dependencies needed for Log4Qt. +- cmake/ contains helper modules created during earlier migration (Qt6-first shim, NGLMacros.cmake, FindPopplerQt5.cmake). + +Per-module migration steps (template) +1) Add module to repo (new folder under ./): keep sources in place. +2) Create or adapt CMakeLists.txt for module: + - Add a top-level target and use `find_package(Qt6 REQUIRED COMPONENTS Widgets Core Gui)` or the project's required Qt modules. + - Use project-wide cmake/NGLMacros.cmake helper macros to set AUTOUIC/AUTOMOC/AUTORCC compatibility. + - If the module uses Poppler, rely on cmake/FindPopplerQt5.cmake so existing find_package(PopplerQt5) calls remain valid. + - Set C++ standard: target_compile_features(${proj} PUBLIC cxx_std_20) or -DCMAKE_CXX_STANDARD=20 in configure. +3) Source edits checklist (common fixes): + - qAsConst -> std::as_const + - QLibraryInfo::location(...) -> QLibraryInfo::path(...) + - QVariant::type() usages: replace logging with typeName()/metaType() or use var.metaType() + - QDateTime(..., Qt::UTC) -> QTimeZone::utc() + - Replace Qt key operator+ with operator| for QKeyCombination/QKeySequence + - qChecksum(...): use QByteArrayView overload + - Poppler: prefer poppler-qt6 API adjustments (unique_ptr release or adopt ownership as needed) + - Replace QMouseEvent::localPos() with position() where necessary +4) Add resources (.qrc) into target via qt_add_resources when building with Qt6. +5) Tests: add GoogleTest scaffolding under tests/gtest for module-specific unit tests. +6) CMake: keep old find_package(PopplerQt5) calls — cmake/FindPopplerQt5.cmake will map to poppler-qt6. +7) Local verification: run migration/migrate_module.sh and inspect output in ./build. Fix compile/test failures iteratively. +8) Commit: small, focused commits per change group (CMake, API fixes, tests). Add Co-authored-by trailer if requested. + +Automation / CI suggestions +- Create a GitHub Actions job (or CI) that runs ./final-migration/run_final_migration.sh to verify the whole tree after each merge. +- Optionally enable a migration pipeline job that accepts a module path and runs migration/migrate_module.sh (use matrix for multiple modules). +- Consider adding clang-tidy/clang-format step with a strict ruleset after migration completes. + +Notes +- Keep build/ ignored and out of Git. Use tags/releases for stable snapshots. +- If a module depends on third-party libs, add detection or build steps into app/Dockerfile or cmake/Find* helpers. + +Use the included migration/migrate_module.sh to run and test each migration iteration reproducibly in Docker. \ No newline at end of file diff --git a/migration/migrate_module.sh b/migration/migrate_module.sh new file mode 100755 index 000000000..4faf98e07 --- /dev/null +++ b/migration/migrate_module.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +set -euo pipefail + +# migration/migrate_module.sh +# Usage: ./migration/migrate_module.sh [--jobs N] +# Runs a reproducible configure/build/test of the specified module inside the app docker + +MODULE_PATH=${1:-} +if [[ -z "$MODULE_PATH" ]]; then + echo "Usage: $0 [--jobs N]" + exit 1 +fi + +JOBS=4 +shift || true +while [[ $# -gt 0 ]]; do + case "$1" in + --jobs) JOBS="$2"; shift 2;; + -j*) JOBS="${1#-j}"; shift;; + *) echo "Unknown arg: $1"; exit 1;; + esac +done + +# Ensure path is relative to repo root +MODULE_ABS="/repo/$(realpath --relative-to=$(pwd) "$MODULE_PATH")" + +# Use app/run_docker.sh to run the migration inside the prepared Qt6 image +# The container will configure just the requested module in a clean build directory. + +./app/run_docker.sh ../sandbox -- bash -lc "set -euo pipefail && export LD_LIBRARY_PATH=/opt/Qt/6.8.3/gcc_64/lib:\${LD_LIBRARY_PATH:-} && export QT_QPA_PLATFORM=offscreen && rm -rf /repo/build && mkdir -p /repo/build && cd /repo/build && \ cmake -S /repo -B /repo/build -G Ninja -DCMAKE_PREFIX_PATH=/opt/Qt/6.8.3/gcc_64 -DCMAKE_CXX_STANDARD=20 -DMIGRATE_MODULE=${MODULE_PATH} -DBUILD_TESTING=ON && \ cmake --build /repo/build -- -j${JOBS} && ctest --test-dir /repo/build --output-on-failure" + +echo "Migration run for module ${MODULE_PATH} finished. Check ./build for logs and artifacts."