Files
qt-migration-legatus/qt6-after/qt6-migrated-legatus/README.md
T
berrux-dev f1f2c5eec8 Move the coverage report into the build tree and document manual commands
- new_docker_build.sh: the default coverage report location is now
  qt6-after/build/coverage/<project>/<os>/ (inside the build tree,
  wiped with it on every run).
- README.md: new 'Manual commands (without the driver)' section with the
  exact image build, container start, from-zero cmake/ninja compile,
  ctest and instrumented lcov coverage pipeline; Step 6 and the options
  table updated to the new report location.
- Verified end to end: clean from-zero --run-coverage run, 22/22 tests,
  122 production files, host-side paths in all artifacts.
2026-11-20 11:19:21 +01:00

450 lines
19 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 inside the build tree (default:
`qt6-after/build/coverage/<PROJECT>/<OS_VERSION>/`, e.g.
`qt6-after/build/coverage/guez/26.04/`); like the build itself, it is
wiped at the start of every driver run:
- `html/index.html` — browser report (line + branch coverage)
- `coverage.info` — lcov tracefile: production code only. Test sources
(`unit-test/`, `UnitTests/`, `tests/`, `*unit_test*`) and generated
build artifacts (`qt6-after/build/` autogen/moc) are removed after the
extract step.
- `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`.
## Manual commands (without the driver)
Everything the driver does, by hand. `PIPELINE_ROOT` is the directory
that contains `qt-migration-legatus/` (the driver mounts it as `/repo`).
### 1. Build the image
```bash
cd qt-migration-legatus/qt6-after/qt6-migrated-legatus # the tree
docker build -t legatus-qt6:1.0 -f Dockerfile .
```
### 2. Start the container
```bash
PIPELINE_ROOT=/home/nkana/release_2/qt6-migration-pipeline
docker run --rm -it \
-v "${PIPELINE_ROOT}":/repo \
-w /repo/qt-migration-legatus/qt6-after/qt6-migrated-legatus \
legatus-qt6:1.0 /bin/bash
```
### 3. Compile from zero (inside the container)
```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 \
.
cmake --build ../build -j$(nproc)
```
(the driver builds the 61 Release 2 targets one by one instead of the
default `all` target, for finer progress logs and fail-fast — see the
`GROUP*_TARGETS` arrays in `new_docker_build.sh`)
### 4. Run the tests
```bash
cd ../build
export QT_QPA_PLATFORM=offscreen
export QT_PLUGIN_PATH="/usr/lib/x86_64-linux-gnu/qt6/plugins"
ctest --output-on-failure -j$(nproc)
```
### 5. Coverage (manual)
First reconfigure the build instrumented — add these four flags to the
cmake configure in step 3 (then `cmake --build ../build -j$(nproc)` and
run ctest as in step 4):
```bash
-DCMAKE_C_FLAGS_RELWITHDEBINFO="-O0 -g --coverage -DNDEBUG -fPIC" \
-DCMAKE_CXX_FLAGS_RELWITHDEBINFO="-O0 -g --coverage -DNDEBUG -fPIC" \
-DCMAKE_EXE_LINKER_FLAGS=--coverage \
-DCMAKE_SHARED_LINKER_FLAGS=--coverage \
```
Then collect, from the build directory (inside the container):
```bash
cd ../build
COV_DIR="$PWD/coverage/guez/26.04"
IGNORE="mismatch,unused,source,category,version,gcov,corrupt,unsupported,inconsistent,count"
rm -rf "$COV_DIR" && mkdir -p "$COV_DIR"
lcov --capture --directory . \
--output-file "$COV_DIR/coverage_raw.info" \
--rc branch_coverage=1 --ignore-errors="$IGNORE"
lcov --extract "$COV_DIR/coverage_raw.info" "/repo/qt-migration-legatus/*" \
--output-file "$COV_DIR/coverage.info" \
--rc branch_coverage=1 --ignore-errors="$IGNORE"
rm -f "$COV_DIR/coverage_raw.info"
lcov --remove "$COV_DIR/coverage.info" \
"*/qt6-after/build/*" "*/unit-test/*" "*/UnitTests/*" \
"*unit_test*" "*/tests/*" \
--output-file "$COV_DIR/_filtered.info" \
--rc branch_coverage=1 --ignore-errors="$IGNORE"
mv -f "$COV_DIR/_filtered.info" "$COV_DIR/coverage.info"
genhtml "$COV_DIR/coverage.info" --output-directory "$COV_DIR/html" \
--branch-coverage --title "Legatus Qt6 Release 2 - code coverage" \
--ignore-errors="$IGNORE"
lcov --summary "$COV_DIR/coverage.info" --rc branch_coverage=1 \
--ignore-errors="$IGNORE" > "$COV_DIR/coverage_summary.txt"
```
Note: by hand the report keeps the container paths (`/repo/...`); the
driver additionally rewrites them to the host `PIPELINE_ROOT` (Step 6).
## 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` | `qt6-after/build/coverage/<project>/<os>` | report dir (inside the build tree) — 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.