Files
qt-migration-legatus/qt6-after/qt6-migrated-legatus/README.md
T
berrux-dev b18ac87565 Document the Release 2 driver in the README and tidy DDS/Plugins
- Rewrite README.md around new_docker_build_release2.sh: Release 2
  scope (4 build groups, 61 targets), Ninja/RelWithDebInfo configure,
  the 22-test ctest baseline, DEB production via
  rpmbuild/make_rpm_ubuntu26_release2.py, options reference,
  troubleshooting and known quirks (the legacy validation-scope driver
  is no longer documented as the main flow).
- Remove leftover blank lines and stale explanatory comments in
  Lts/DDS/Generic (dynamic_data_reader.h, generic_base.h),
  Lts/DDS/QosProfile (DDS_DefaultQos.cpp/.h, CMakeLists.txt) and
  Lts/Plugins/CMakeLists.txt.
2026-11-17 20:14:47 +01:00

325 lines
14 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_release2.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_release2.sh` — build driver (compile, ctest, DEB packaging)
- `rpmbuild/make_rpm_ubuntu26_release2.py` — in-tree DEB package producer (self-contained)
- `Dockerfile` — image recipe kept for the legacy validation-scope driver and for the `qt6-release-build-pipeline` DEB; the Release 2 driver carries the same recipe built in and builds the image automatically when it is missing
- `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_release2.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 its
built-in recipe (Ubuntu 26.04 base, apt deps, Qt 6.10.2 via
`aqtinstall`, KDReports from source) and continues with the build.
The default image name is `qt6-migrated-legatus-release2`. 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_release2.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_release2.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.
**Note:** it is still wired to the legacy `new_docker_build.sh`
driver and has not been switched to `new_docker_build_release2.sh`
yet. See `jenkins-ci-rme/README.md` for the pipeline details.
## Step 6 — Code coverage (lcov)
`--run-coverage` is available and is mutually exclusive with
`--run-jenkins-builder`. In the current tree it only passes
`-DRUN_COVERAGE=ON` / `-DCOVERAGE_OUTPUT_DIR` to the configure — those
variables are not consumed by any `CMakeLists.txt` yet, so no lcov
data is collected. The option is kept for the (still to be wired)
coverage step.
## Options reference
`./new_docker_build_release2.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` | off | prebuilt image mode (`--docker-image` turns it on) |
| `--docker-image IMAGE` | `qt6-migrated-legatus-release2` | 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 | coverage flag pass-through (Step 6) |
| `--coverage-output-dir DIR` | `./coverage-out` | pass-through (see 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).
- **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.
- The legacy driver `new_docker_build.sh` (validation scope) is kept in
the tree and is still used by `jenkins-ci-rme/`; its in-tree
`Dockerfile` recipe does not include `libbz2-dev` (BZip2), which the
Release 2 driver's built-in recipe does.