Files
qt-migration-legatus/qt6-after/qt6-migrated-legatus/README.md
T
berrux-dev 2f82acd7e0 Fix coverage paths: report and artifacts use host paths, not /repo
- new_docker_build.sh: the coverage log now prints the host-side report
  location (<pipeline-root>/coverage/<project>/<os>); after genhtml, the
  container mount prefix is rewritten to the host path in coverage.info
  (SF: lines), the html path labels/cmd_line and coverage_summary.txt.
  The rewrite is plain text replacement after genhtml because genhtml
  must run in the container, where the sources exist under the mount
  root (lcov --substitute rewrites before the extract filter and would
  leave genhtml unable to read the sources).
- README.md: document the host-path rewrite and the root ownership of
  the artifacts.
2026-11-20 10:47:25 +01:00

352 lines
15 KiB
Markdown

# qt6-migrated-legatus — build and run, step by step
Build guide for the Qt6-migrated legatus tree on the **Release 2**
branch. Everything runs inside a prebuilt Docker image; the host only
needs Docker.
## Scope
`new_docker_build.sh` builds the Release 2 scope in four
groups (all ON by default, toggle with `--groupN` / `--no-groupN`):
| Group | Area | Contents |
|---|---|---|
| GROUP1 (AP4) | DDS middleware | `ddscore`, `ddsftccore`, `ddsfts`, `ddsgen`, `ddsQoS`, `ddsconnector` (+ `ddscore_unit_test`, `ddsqos_unit_test`) |
| GROUP3 (AP3) | Lts services + core stack | NGL library stack (NGLLogger, nglcoreapplication, nglcompression, …), Lts/Common libraries (LtsCoordinate, LtsCoordTrans, LtsSession, LtsLicence, …), TetraIF modules (CoPrtCnv, LogView, PrtCnv) and all their test executables |
| GROUP5 (AP9) | Viewer / tools | `ddsview`, `LogViewer`, `sqlbrowser` (+ `logviewer_unit_test`, `sqlbrowser_unit_test`) |
| GROUP6 (AP9) | Generators | `ngl_codegen` |
**61 targets** in total, built one by one
(`cmake --build ../build --target <t> -j$(nproc)`).
Entries at the tree root:
- `new_docker_build.sh` — build driver (compile, ctest, DEB packaging)
- `rpmbuild/make_rpm_ubuntu26_release2.py` — in-tree DEB package producer (self-contained)
- `Dockerfile` — the image recipe (single source of truth); the driver builds the image from it when the image is missing or when `--no-prebuilt-image` forces a rebuild (also bundled into the `qt6-release-build-pipeline` DEB)
- `rti_license.dat` — RTI Connext DDS license, required by the DDS group (GROUP1)
- `jenkins-ci-rme/` — in-tree copy of the Jenkins CI flow (see its own `README.md`; still wired to the legacy driver, see Step 5)
- `../build/` — build tree, created by the driver **next to the tree** (`qt6-after/build`), never inside it (git-ignored scratch area)
Toolchain inside the image: **Ubuntu 26.04, GCC 15.2.0, Qt 6.10.2**
(`/opt/Qt/6.10.2/gcc_64`), C++17 (set by the root `CMakeLists.txt`),
**Ninja**, `RelWithDebInfo`. The DDS group requires `rti_license.dat`
(checked in at the tree root); the driver exports `RTI_LICENSE` inside
the container.
## Prerequisites
1. **Docker** available on the host.
2. A `.envrc` in this directory defining `MIGRATE_PIPELINE_ROOT` — the
**pipeline root**, i.e. the directory that *contains*
`qt-migration-legatus/`. The driver mounts it at `/repo` in the
container (overridable with `--docker-mount-root`) and works in
`/repo/qt-migration-legatus/qt6-after/qt6-migrated-legatus`, so
running the driver as-is satisfies this. The build tree then lives
at `/repo/qt-migration-legatus/qt6-after/build` in the container,
which is `../build` next to the tree on the host.
`MIGRATE_PIPELINE_ROOT` resolution (highest precedence first):
exported environment variable → `.envrc` in this directory → the
script's own location.
The driver refuses to start if `.envrc` is missing, if
`MIGRATE_PIPELINE_ROOT` is unset or the directory does not exist, or if
`rti_license.dat` is missing while GROUP1 is ON.
All commands below are run **from this directory**
(`qt6-migrated-legatus/`).
## Step 1 — Build the prebuilt Docker image (once)
```bash
./new_docker_build.sh --docker-image legatus-qt6:1.0
```
`--docker-image` selects the prebuilt-image mode: if the named image
does not exist yet, the driver builds it automatically from the
in-tree `./Dockerfile` (Ubuntu 26.04 base, apt deps, Qt 6.10.2 via
`aqtinstall`, KDReports from source) and continues with the build.
`--no-prebuilt-image` forces a (re)build of the image from
`./Dockerfile` before running.
The default image name is `legatus-qt6:1.0`. This driver
has no `--build-prebuilt-image` / `--delete-prebuilt-image` options —
manage the image with plain `docker` if needed.
## Step 2 — Build the Release 2 scope
```bash
./new_docker_build.sh --docker-image legatus-qt6:1.0 \
> build.log 2>&1
```
What the driver does:
1. Validates the environment (`.envrc`, `MIGRATE_PIPELINE_ROOT`,
`rti_license.dat` for GROUP1) and starts a container with
`-v ${MIGRATE_PIPELINE_ROOT}:/repo` and working directory
`/repo/qt-migration-legatus/qt6-after/qt6-migrated-legatus`.
2. Inside the container, it wipes and reconfigures the build tree next
to the source tree:
```bash
rm -rf ../build && mkdir -p ../build
cmake -B ../build -G Ninja \
-DBUILD_TESTING=ON \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DCMAKE_PREFIX_PATH=/opt/Qt/6.10.2/gcc_64 \
-DCMAKE_CXX_FLAGS="-DRTI_LINUX -DRTI_UNIX" \
-DCMAKE_C_FLAGS="-DRTI_LINUX -DRTI_UNIX" \
-DBUILD_RTI=ON \
-DBUILD_GROUP1=ON -DBUILD_GROUP3=ON -DBUILD_GROUP5=ON -DBUILD_GROUP6=ON \
# + packaging/coverage pass-through variables (see Troubleshooting)
```
3. Builds the 61 group targets in order (GROUP1 → GROUP3 → GROUP5 →
GROUP6).
4. Runs **ctest** (see Step 3).
Output to inspect after the run:
- `../build/bin/` — executables (apps: `ddsview`, `LogView`,
`LogViewer`, `PrtCnv`, `sqlbrowser`, `ngl_codegen`, …)
- `../build/bin/unit-test/` — the 22 test executables
- `../build/lib/` — shared libraries
To rebuild incrementally without a fresh tree, run the build directly
in an interactive container against the existing `../build/`:
```bash
docker run --rm -it -v /path/to/pipeline-root:/repo legatus-qt6:1.0 \
bash -c 'cd /repo/qt-migration-legatus/qt6-after/build \
&& cmake --build . -j$(nproc)'
```
## Run an executable directly
To run a built executable interactively — e.g. the GUI apps under
`../build/bin/` (`ddsview`, `LogViewer`, `sqlbrowser`) against your
local display — start a shell inside the container with X11 forwarding:
```bash
docker run --rm -it \
-e DISPLAY \
-e LC_ALL=C.UTF-8 \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v /path/to/pipeline-root:/repo \
legatus-qt6:1.0 \
bash -c 'cd /repo/qt-migration-legatus/qt6-after/build && exec bash'
```
## Step 3 — Run the tests
### 3.1 ctest (automatic)
The driver runs ctest after the compile (skip with `--no-ctest`): it
`cd`s into `../build`, sets `QT_QPA_PLATFORM=offscreen` and prepends
the system Qt plugin dir to `QT_PLUGIN_PATH`
(`/usr/lib/x86_64-linux-gnu/qt6/plugins` — where the system
`libkf6texttemplate-dev` package installs `ktexttemplate_defaulttags`,
needed by `GrantleeParserSmoke`; the `/opt/Qt` install does not search
it), then runs `ctest --output-on-failure -j$(nproc)`.
A failing test does not fail the driver run (it logs and continues).
Expected baseline — **22 tests, all passed**:
| # | Test | Area |
|---|---|---|
| 1 | `coprtcnv_unit_test` | TetraIF/CoPrtCnv — telegrams, fragmentation |
| 2 | `logview_unit_test` | TetraIF/LogView — `IntegerCalculator` |
| 3 | `prtcnv_unit_test` | TetraIF/PrtCnv — fragmented-telegram handling |
| 4 | `wms_json_ds_unit_test` | Z/wms_json_ds |
| 5 | `nglcoreapplication_unit_test` | Z/nglcoreapplication |
| 6 | `nglsettings_unit_test` | Z/nglsettings |
| 7 | `NGLToolsQtSmoke` | Z/ngltools — Qt smoke (binary `ngltools_qt_smoke`) |
| 8 | `ngltools_unit_test` | Z/ngltools |
| 9 | `test_nglpdfwidget` | Z/nglwidgets — PDF widget |
| 10 | `ngllogger_unit_test` | Z/NGLLogger |
| 11 | `logviewer_unit_test` | Lts/LogViewer |
| 12 | `sqlbrowser_unit_test` | Lts/SQLBrowser |
| 13 | `ddsqos_unit_test` | Lts/DDS/QosProfile |
| 14 | `ddscore_unit_test` | Lts/DDS core |
| 15 | `GrantleeParserSmoke` | Lts/Common/CodeGen — KTextTemplate parsing (binary `grantlee_parser_smoke`) |
| 16 | `codegen_unit_test` | Lts/Common/CodeGen |
| 17 | `commandlineparser_unit_test` | Lts/Common — command-line parser |
| 18 | `lts_coord_trans_unit_test` | Lts/Common/LtsCoordTrans |
| 19 | `ltscoordinate_unit_test` | Lts/Common/LtsCoordinate |
| 20 | `aes_crypt_test` | Lts/Common/LtsLicence — AES |
| 21 | `ltssession_unit_test` | Lts/LtsSession |
| 22 | `utils_test` | Lts/Common/LtsUtils |
### 3.2 Run a test executable directly
GUI-free tests need the offscreen Qt platform in a headless container:
```bash
docker run --rm -it -v /path/to/pipeline-root:/repo legatus-qt6:1.0 \
bash -c 'export QT_QPA_PLATFORM=offscreen
export QT_PLUGIN_PATH=/usr/lib/x86_64-linux-gnu/qt6/plugins
cd /repo/qt-migration-legatus/qt6-after/build
./bin/unit-test/utils_test # LtsUtils: byte access, strings, …
./bin/unit-test/coprtcnv_unit_test
# or everything registered:
ctest --output-on-failure'
```
Each QtTest binary accepts a single slot name to run just one test,
e.g. `./bin/unit-test/utils_test byteAccess`.
Note: ctest reads the absolute paths embedded in the build tree at
configure time — run it against `../build` with the **same mount
prefix** the configure used (the driver mounts the pipeline root at
`/repo`).
## Step 4 — Produce the release DEB packages
```bash
./new_docker_build.sh --docker-image legatus-qt6:1.0 \
--run-jenkins-builder \
> /path/to/build.log 2>&1
```
(Export `PROJECT`, `LTS_VERSION`, `BUILD_NUMBER`, `BUILD_TAG`,
`GUEZ_MODE` *before* the command if you want non-default package
metadata — command-prefix variables are not expanded in the same
command's arguments.)
The driver compiles the scope, runs ctest, then stages the tree (tar)
into `<pipeline-root>/deb_stage/` and runs the in-tree
`rpmbuild/make_rpm_ubuntu26_release2.py` (`-c LTS`, IPO + unity build,
`BUILD_RTI=ON`, all 61 targets), which produces 5 DEBs in
`<pipeline-root>/rpms/<project>/<os-version>/`:
| DEB | Contents |
|---|---|
| `qt6-release-runtime_*` | runtime libraries + the release-scope executables |
| `qt6-release-sources_*` | release-scope sources |
| `qt6-release-ctest-runtime_*` | test executables |
| `qt6-release-ctest-sources_*` | test sources |
| `qt6-release-build-pipeline_*` | the in-tree pipeline files (driver, `Dockerfile`, `CMakeLists.txt`, `rpmbuild/`, `jenkins-ci-rme/`) |
A copy of the DEBs is also placed in `<pipeline-root>/packages-out/`
(same-file skip guarded by device:inode).
Note: `--package-output-dir` is currently passed through to CMake as an
unused variable — the DEB locations above are fixed under the pipeline
root, not at `--package-output-dir`.
Verify a package:
```bash
dpkg -c "<pipeline-root>/rpms/guez/26.04/qt6-release-ctest-runtime_1.0-1_amd64.deb" \
| grep unit_test
```
## Step 5 — CI / Jenkins flow (optional)
The in-tree `jenkins-ci-rme/` directory contains the full Jenkins
pipeline (`Jenkinsfile`, builder, publisher) adapted to this tree; the
in-tree flow calls `new_docker_build.sh` (the Release 2 driver). See
`jenkins-ci-rme/README.md` for the pipeline details.
## Step 6 — Code coverage (lcov)
`--run-coverage` builds the whole Release 2 scope instrumented
(`-O0 -g --coverage`, overriding the RelWithDebInfo flags), runs the
ctest suite and collects an lcov report inside the container
(lcov + genhtml ship in the `legatus-qt6:1.0` image):
```bash
./new_docker_build.sh --run-coverage
```
The report is written to
`<pipeline-root>/coverage/<PROJECT>/<OS_VERSION>/` (default:
`coverage/guez/26.04/`), next to `qt-migration-legatus/` and outside
the tree:
- `html/index.html` — browser report (line + branch coverage)
- `coverage.info` — lcov tracefile, filtered to `qt-migration-legatus/*`
- `coverage_summary.txt` — totals (line / branch hit rate)
Source paths inside `coverage.info` and the html report are rewritten
to host paths at the end of the collection (the container mount prefix
is replaced by the pipeline root), so the report works directly on the
host. Note: the files are created by root inside the container — read
them as-is, or `chown` the directory on the host to edit/move it.
`--coverage-output-dir DIR` moves the report; `DIR` must be an absolute
path under the pipeline root (relative values are ignored and the
default above is used). The option is mutually exclusive with
`--run-jenkins-builder`.
## Options reference
`./new_docker_build.sh --help` prints the full option list.
The main ones:
| Option | Default | Purpose |
|---|---|---|
| `--group1` / `--no-group1` | ON | DDS middleware group (AP4) |
| `--group3` / `--no-group3` | ON | Lts services + core stack (AP3) |
| `--group5` / `--no-group5` | ON | Viewer tools (AP9) |
| `--group6` / `--no-group6` | ON | Generators (AP9) |
| `--no-ctest` | — | skip the ctest step |
| `--tests-only` | — | see Known quirks |
| `--use-prebuilt-image` / `--no-prebuilt-image` | on | use the image (build from `./Dockerfile` if missing) / force a rebuild from `./Dockerfile` |
| `--docker-image IMAGE` | `legatus-qt6:1.0` | image to use (auto-built if missing) |
| `--cmake_build_flags FLAGS` | — | extra `-D` flags appended to the configure |
| `--docker-mount-root PATH` | `/repo` | container-side mount root |
| `--run-jenkins-builder` | off | produce the DEB packages (Step 4) |
| `--package-output-dir DIR` | `./packages-out` | pass-through (see Step 4 note) |
| `--lts-version / --project / --build-number / --build-tag` | `1.0` / `guez` / `1` / `manual-build` | package metadata |
| `--run-coverage` | off | instrument with `-O0 --coverage`, run ctest, collect the lcov report (Step 6); mutually exclusive with `--run-jenkins-builder` |
| `--coverage-output-dir DIR` | `<pipeline-root>/coverage/<project>/<os>` | report dir — only absolute paths under the pipeline root are honored (Step 6) |
Environment overrides: `BUILD_GROUP1/3/5/6`, `RUN_CTEST`, `TESTS_ONLY`,
`USE_PREBUILT_IMAGE`, `DOCKER_IMAGE`, `CMAKE_BUILD_FLAGS`,
`DOCKER_MOUNT_ROOT`, `GUEZ_MODE`, `RUN_JENKINS_BUILDER`,
`PACKAGE_OUTPUT_DIR`, `LTS_VERSION`, `PROJECT`, `BUILD_NUMBER`,
`BUILD_TAG`, `RUN_COVERAGE`, `COVERAGE_OUTPUT_DIR`,
`MIGRATE_PIPELINE_ROOT`.
## Troubleshooting
- **"Manually-specified variables were not used"** at configure —
expected. The driver passes packaging/coverage variables
(`BUILD_GROUP1/3/5/6`, `RUN_JENKINS_BUILDER`, `PACKAGE_OUTPUT_DIR`,
`PROJECT`, `BUILD_NUMBER`, `BUILD_TAG`, `RUN_COVERAGE`,
`COVERAGE_OUTPUT_DIR`) that no `CMakeLists.txt` reads yet.
`BUILD_RTI` **is** consumed.
- **"no Qt platform plugin could be initialized"** when running a test
binary by hand → `export QT_QPA_PLATFORM=offscreen` (plus the
`QT_PLUGIN_PATH` from Step 3).
- **`GrantleeParserSmoke`: `ktexttemplate_defaulttags` not found** →
run ctest/tests with the system plugin dir prepended (Step 3).
- **Coverage build fails to link with `undefined reference` to
`DTC::GenericDtcSC<...>::readAlive(...)` etc.** — a call to a pure
virtual function only links at `-O1` and above (GCC rewrites it to
`__cxa_pure_virtual`); at `-O0` the raw symbol stays undefined. This
was triggered by the one-line forwarders in
`Lts/DDS/DTC/generic_dtc.h`, which have been removed: the concrete
classes in `generic_dtc_impl.h` implement every method `final`, so
the forwarders were dead code (and a latent infinite recursion).
- **Stale build tree** → the driver always recreates `../build/`; for
manual builds delete `../build/` and rerun Step 2 if CMake behaves
oddly.
- **ctest "No tests were found"** → the pipeline root was mounted at a
different path than the configure used; the build tree embeds
absolute paths.
- **Wrong pipeline root** → the driver mounts `MIGRATE_PIPELINE_ROOT`
at `/repo`; it must be the directory that *contains*
`qt-migration-legatus/`, not the tree itself.
- **`rti_license.dat not found`** → GROUP1 (DDS) requires the license;
it is checked in at the tree root (or place it at the pipeline root).
## Known quirks
- `--tests-only` is documented in `--help` as "run only ctest, skip all
build groups", but the current implementation only skips the ctest
step; the group builds still run.