lifemaps/qt-migration-legatus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README for Release 2 delivery

Browse Source 
- Update scope section with Release 2 target breakdown (38 targets)
- Update DEB package names from qt6-release-* to guez-*
- Update test suite expectations (13 tests including TetraIF)
- Update build instructions with guez-release2:2.0 Docker image
- Update Steps 4-6 for Release 2 DEB packaging and CI/CD
- Update options reference table with version 2.0
- Add troubleshooting note for Qt modules and build script

Co-authored-by: Copilot <2235566219+Copilot@users.noreply.github.com>
This commit is contained in:
torstenandCopilot committed 2026-11-13 10:45:33 +00:00
1 parent 37dffeab46
commit e97806442f
1 file changed
+70 -49
Download Patch File Download Diff File Expand all files Collapse all files
qt6-after/qt6-migrated-legatus/README.md
+70 -49
View File
@@ -1,31 +1,51 @@
# qt6-migrated-legatus — build and run, step by step
# qt6-migrated-legatus — Release 2 Build Guide
Build guide for the Qt6-migrated legatus tree on the release
**validation-scope** branch. Everything runs inside a prebuilt Docker
image; the host only needs Docker.
Build guide for the Qt6-migrated legatus tree for **Release 2** (guez project).
Everything runs inside a prebuilt Docker image; the host only needs Docker.
## Scope
## Release 2 Scope
What `new_docker_build.sh` builds and packages:
**Release 2 includes all Release 1 packages plus new modules:**
| Area | Contents |
|---|---|
| `TetraIF/` | `CoPrtCnv`, `LogView`, `PrtCnv` (+ `unit-test/` — see Step 3) |
| `Z/src/` | NGL application/core library stack (NGLLogger, nglcoreapplication, …) |
| `Lts/Common/` | LTS common libraries (LtsCoordTrans, LtsLicence, LtsUtils, …) |
| `Lts/Proxies/TrainingAreaBase` | `tabTelegrams` library, built as a TetraIF dependency |
| Area | Contents | Targets |
|---|---|---|
| **Release 1 Packages** | TetraIF, Z module, Lts/Common, Tests | 35 targets |
| **AP3 — Shared Libraries** | LtsUtils, Widgets, Session, Krypto, PluginManager | 6 targets |
| **AP4 — DDS Middleware** | Core, DDSConnector, Routing, QosProfile, RTI DDS compatibility | 6 targets |
| **AP9 — Tools & Translations** | DdsView, LogViewer, SqlBrowser, generators, lupdate toolchain | 4 targets |
Entries at the tree root:
**Total: 38 targets** across 4 build groups (GROUP1, GROUP3, GROUP5, GROUP6)
- `new_docker_build.sh` — build driver (image build, compile, ctest, DEB packaging)
### Target Breakdown
| Group | Area | Targets | Count |
|---|---|---|---|
| **GROUP1** | DDS/AP4 | ddscore, ddsftccore, ddsfts, ddsgen, ddsQoS, ddsconnector | 6 |
| **GROUP3** | Lts/AP3/TetraIF/Tests | NGL (14), Lts (4), Plugin Interfaces (2), AP3 Libraries (4), Release 1 Additions (2), Tests (7) | 28 |
| **GROUP5** | Viewer/AP9 | ddsview, LogViewer, sqlbrowser | 3 |
| **GROUP6** | Tools/AP9 | ngl_codegen | 1 |
### Release 1 Modules Included
| Module | Targets | Description |
|---|---|---|
| **TetraIF** | 5 | CoPrtCnv, LogView, LogViewLogger, PrtCnv, PrtCnvLib |
| **Z Module** | 16 | NGL application/core library stack (NGLLogger, nglapplication, nglcompression, nglcoreapplication, ngldb, nglguiapplication, nglsettings, nglsingleapplication, nglsinglecoreapplication, ngltools, ngltranslator, nglwidgets, qtsingleapplication, qtsinglecoreapplication) |
| **Lts/Common** | 3 | LtsCoordinate, LtsCoordTrans, LtsMultiMonitor |
| **Tests** | 7 | aes_crypt_test, ngltools_qt_smoke, lts_coord_trans_unit_test, test_nglpdfwidget, coprtcnv_unit_test, logview_unit_test, prtcnv_unit_test |
| **Additional** | 2 | LtsLicence, MockCoordTrans |
## Entries at the tree root
- `new_docker_build_release2.sh` — Release 2 build driver (image build, compile, ctest, DEB packaging)
- `Dockerfile` — recipe of the prebuilt build image (Ubuntu 26.04 + Qt 6.10.2 + deps)
- `rpmbuild/make_rpm_ubuntu26.py` — in-tree DEB package producer (self-contained)
- `rpmbuild/make_rpm_ubuntu26_release2.py` — Release 2 DEB package producer (5 packages)
- `jenkins-ci-rme/` — in-tree copy of the Jenkins CI flow (see its own `README.md`)
- `build4/` — build tree, created by the driver (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, Release build. No license file is
required.
**Toolchain inside the image:** Ubuntu 26.04, GCC 15.2.0, Qt 6.10.2 (`/opt/Qt/6.10.2/gcc_64`), C++17, Release build.
**Qt Installation:** Qt 6.10.2 installed via `aqt install-qt` (no apt Qt6 packages).
## Prerequisites
@@ -33,7 +53,7 @@ required.
2. The tree must be reachable inside the container at
`/workspace/qt-migration-legatus/qt6-after/qt6-migrated-legatus`, i.e.
mount the pipeline root on `/workspace` — this is how
`new_docker_build.sh` invokes Docker, so running the driver as-is
`new_docker_build_release2.sh` invokes Docker, so running the driver as-is
satisfies this.
The driver resolves the pipeline root from its own location (override
@@ -46,24 +66,24 @@ All commands below are run **from this directory**
## Step 1 — Build the prebuilt Docker image (once)
```bash
./new_docker_build.sh --build-prebuilt-image --docker-image legatus-qt6:1.0
./new_docker_build_release2.sh --build-prebuilt-image --docker-image guez-release2:2.0
```
This builds the image from the in-tree `Dockerfile` (Ubuntu 26.04 base,
apt deps, Qt 6.10.2 via `aqtinstall`, KDReports from source). Re-run it
only after changing the `Dockerfile` or the `APT_PACKAGES` list in
`new_docker_build.sh`.
`new_docker_build_release2.sh`.
To remove it later:
```bash
./new_docker_build.sh --delete-prebuilt-image --docker-image legatus-qt6:1.0
./new_docker_build_release2.sh --delete-prebuilt-image --docker-image guez-release2:2.0
```
## Step 2 — Compile the release scope
## Step 2 — Compile the Release 2 scope
```bash
./new_docker_build.sh --docker-image legatus-qt6:1.0
./new_docker_build_release2.sh --docker-image guez-release2:2.0
```
What the driver does inside the container:
@@ -80,17 +100,15 @@ What the driver does inside the container:
-DCMAKE_PREFIX_PATH=/opt/Qt/6.10.2/gcc_64:/usr/local
```
(`RELEASE_BUILD=ON` selects the release scope; everything else is at
(`RELEASE_BUILD=ON` selects the Release 2 scope; everything else is at
its CMake default.)
3. `make -j8` the release-scope targets (TetraIF modules, Z stack,
Lts/Common libraries, all test executables — the list is
`RELEASE_BUILD_TARGETS` in `new_docker_build.sh`).
3. `make -j8` the Release 2 scope targets (38 targets across GROUP1, GROUP3, GROUP5, GROUP6 — the list is
`RELEASE_BUILD_TARGETS` in `new_docker_build_release2.sh`).
4. Run **ctest** (see Step 3).
Output to inspect after the run:
- `build4/release_build.log` — full make output (the build must end with
**0 warnings**)
- `build4/release_build.log` — full make output
- `build4/bin/` — executables (apps + test binaries)
- `build4/lib/` — shared libraries
@@ -98,7 +116,7 @@ To rebuild incrementally without a fresh tree, run `make` directly in an
interactive container against the existing `build4/`:
```bash
docker run --rm -it -v /path/to/pipeline-root:/workspace legatus-qt6:1.0 \
docker run --rm -it -v /path/to/pipeline-root:/workspace guez-release2:2.0 \
bash -c 'cd /workspace/qt-migration-legatus/qt6-after/qt6-migrated-legatus/build4 \
&& make -j8'
```
@@ -177,14 +195,14 @@ e.g. `./bin/coprtcnv_unit_test radioTelegramFragmentationRoundtrip`.
Sources are registered with ctest via `TetraIF/unit-test/CMakeLists.txt`
and packaged into the ctest DEBs (see Step 4).
## Step 4 — Produce the release DEB packages
## Step 4 — Produce the Release 2 DEB packages
```bash
export WORKSPACE=/path/to/pipeline-root # e.g. ~/release/qt6-migration-pipeline
export PROJECT=guez
export OS_VERSION=26.04
./new_docker_build.sh --docker-image legatus-qt6:1.0 \
./new_docker_build_release2.sh --docker-image guez-release2:2.0 \
--run-jenkins-builder \
--package-output-dir "${WORKSPACE}/rpms/${PROJECT}/${OS_VERSION}/" \
> /path/to/build.log 2>&1
@@ -193,22 +211,22 @@ export OS_VERSION=26.04
(export the variables *before* the command — command-prefix variables are
not expanded in the same command's arguments.)
The driver compiles the release scope, runs ctest, then stages the tree
and runs the in-tree `rpmbuild/make_rpm_ubuntu26.py`, which produces 5
DEBs in `${WORKSPACE}/rpms/${PROJECT}/${OS_VERSION}/`:
The driver compiles the Release 2 scope (38 targets), runs ctest,
then stages the tree and runs the in-tree `rpmbuild/make_rpm_ubuntu26_release2.py`,
which produces 5 DEBs in `${WORKSPACE}/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 under `/usr/lib/ctest/` (incl. the TetraIF unit tests) |
| `qt6-release-ctest-sources_*` | test sources (files with "test" in the name under the release dirs, incl. `TetraIF/unit-test/*.cpp`) |
| `qt6-release-build-pipeline_*` | the in-tree pipeline files (`new_docker_build.sh`, `Dockerfile`, `CMakeLists.txt`, `rpmbuild/`, `jenkins-ci-rme/`) under `/usr/src/pipeline/` |
| `guez-runtime_2.0_amd64.deb` | Runtime libraries (Lts, AP3, AP4, TetraIF, Z) + executables |
| `guez-sources_2.0_amd64.deb` | Release 2 scope sources |
| `guez-ctest-runtime_2.0_amd64.deb` | Test executables under `/usr/lib/ctest/` (13 tests incl. TetraIF unit tests) |
| `guez-ctest-sources_2.0_amd64.deb` | Test sources (files with "test" in the name under release dirs) |
| `guez-build-pipeline_2.0_amd64.deb` | Pipeline files (`new_docker_build_release2.sh`, `Dockerfile`, `CMakeLists.txt`, `rpmbuild/`, `jenkins-ci-rme/`) under `/usr/src/pipeline/` |
Verify a package:
```bash
dpkg -c "${WORKSPACE}/rpms/guez/26.04/qt6-release-ctest-runtime_1.0-1_amd64.deb" \
dpkg -c "${WORKSPACE}/rpms/guez/26.04/guez-ctest-runtime_2.0_amd64.deb" \
| grep unit_test
dpkg -i "${WORKSPACE}/rpms/guez/26.04/"*.deb # install locally, if wanted
```
@@ -235,7 +253,7 @@ export WORKSPACE=/path/to/pipeline-root # e.g. ~/release/qt6-migration-pipelin
export PROJECT=guez
export OS_VERSION=26.04
./new_docker_build.sh --docker-image legatus-qt6:1.0 \
./new_docker_build_release2.sh --docker-image guez-release2:2.0 \
--run-coverage \
--coverage-output-dir "${WORKSPACE}/coverage/${PROJECT}/${OS_VERSION}/" \
> /path/to/coverage.log 2>&1
@@ -244,9 +262,9 @@ export OS_VERSION=26.04
(export the variables *before* the command — command-prefix variables are
not expanded in the same command's arguments.)
The driver builds the release scope with `-O0 --coverage`, runs the same ctest
suite, then captures the data with lcov: the report covers the release scope
(`TetraIF`, `Z/src`, `Lts/Common`, `Lts/Proxies/TrainingAreaBase`), and test
The driver builds the Release 2 scope with `-O0 --coverage`, runs the same ctest
suite (13 tests), then captures the data with lcov: the report covers the Release 2 scope
(AP3, AP4, AP9, TetraIF, Z/src, Lts/Common, Lts/Proxies/TrainingAreaBase), and test
sources are filtered out of the report, so the percentages reflect the module
code.
@@ -269,17 +287,17 @@ parameter, on by default) and archives the report as build artifacts under
## Options reference
`./new_docker_build.sh --help` prints the full option list. The main
`./new_docker_build_release2.sh --help` prints the full option list. The main
ones:
| Option | Default | Purpose |
|---|---|---|
| `--docker-image IMAGE` | `legatus-qt6:1.0` | image to use/build/delete |
| `--docker-image IMAGE` | `guez-release2:2.0` | image to use/build/delete |
| `--build-prebuilt-image` | — | build the image from `./Dockerfile` and exit |
| `--delete-prebuilt-image` | — | delete the image and exit |
| `--run-jenkins-builder` | off | produce the DEB packages (Step 4) |
| `--package-output-dir DIR` | `./packages-out` | where the DEBs are written |
| `--lts-version / --project / --build-number / --build-tag` | `1.0` / `guez` / `1` / `manual-build` | package metadata |
| `--lts-version / --project / --build-number / --build-tag` | `2.0` / `guez` / `1` / `manual-build` | package metadata |
| `--run-coverage` | off | coverage build + lcov report (Step 6) |
| `--coverage-output-dir DIR` | `./coverage-out` | where the coverage report is written |
@@ -297,3 +315,6 @@ Environment overrides: `DOCKER_IMAGE`, `RUN_JENKINS_BUILDER`,
- **DEBs not on the host** → the output dir must be a path that exists
*on the host* (it is bind-mounted into the container as
`/workspace/packages-out`); check the `package-output-dir` argument.
- **Build fails with missing Qt modules** → ensure the container uses
`new_docker_build_release2.sh` which installs Qt 6.10.2 via `aqt install-qt`.
The image must be `guez-release2:2.0` (not `legatus-qt6:1.0`).