qt6-migration-pipeline/external-dependencies/deb-packages/README.md

# DEB Package Build Pipelines

This directory contains DEB package build configurations for all 8 external dependencies used in the Legatus project.

## Overview

All external dependencies are packaged as native DEB packages (format: 3.0 native) and stored in the internal SCM repository. During CI/CD, packages are installed via apt instead of copying files into Docker containers. This approach provides:

- **Reproducible builds**: Standard Ubuntu packaging with debhelper
- **Version management**: Semantic versioning with proper dependencies
- **Air-gapped support**: Packages stored in internal SCM repository at `http://remote-repo.sl.defence-elec.de:8081/repository/external-rpms/general/`
- **Compliance**: License files included in packages where required
- **Maintainability**: Standard Ubuntu package management tools
- **Clean Dockerfiles**: No COPY commands for proprietary dependencies

## Directory Structure

```
deb-packages/
├── README.md                       # This file
├── Jenkinsfile                     # Jenkins pipeline for building and uploading
├── avs/                            # AVS DEB package
│   ├── debian/                     # Debian control files
│   │   ├── control                 # Package metadata and dependencies
│   │   ├── rules                   # Build rules with override_dh_auto_install
│   │   ├── changelog               # Version history
│   │   └── source/
│   │       └── format              # Package format (3.0 native)
├── arcgis/                         # ArcGIS Runtime SDK DEB package
├── buildingmodels/                 # BuildingModels DEB package
├── geographiclib/                  # GeographicLib DEB package
├── schusstafel/                    # Schusstafel DEB package
├── dtentity/                       # dtEntity DEB package
├── rti-connext-dds/                # RTI Connext DDS DEB package (includes license)
└── tmsif/                          # tmsif DEB package
```

## Package Names

| Directory | DEB Package Name | Version | Description |
|-----------|------------------|---------|-------------|
| avs | `libavs-dev` | 1.0.0 | AVS library development files |
| arcgis | `libarcgis-dev` | 1.0.0 | ArcGIS Runtime SDK for Qt |
| buildingmodels | `libbuildingmodels-dev` | 1.0.0 | Building models library |
| geographiclib | `libgeographiclib-dev` | 1.0.0 | Geographic calculations library |
| schusstafel | `libschusstafel-dev` | 1.0.0 | Schusstafel library |
| dtentity | `libdtentity-dev` | 1.0.0 | dtEntity game engine |
| rti-connext-dds | `librti-connext-dds-7.7.0-dev` | 7.7.0 | RTI Connext DDS middleware (includes license) |
| tmsif | `libtmsif-dev` | 1.0.0 | TMSIF library |

## Building DEB Packages

### Prerequisites

- Ubuntu 26.04 build environment
- `devscripts` package
- `debhelper` (>= 12) package
- Build dependencies for each package (see `debian/control`)

### Manual Build

```bash
cd external-dependencies/deb-packages/geographiclib
debuild -us -uc -b
```

This creates a binary-only DEB package without signing in the parent directory.

### Build Scripts

**Build single package:**
```bash
cd external-dependencies/deb-packages
./build-package.sh geographiclib 1.0.0
```

**Build all packages:**
```bash
cd external-dependencies/deb-packages
./build-all-packages.sh
```

Build output is stored in `external-dependencies/deb-packages/output/`

### Jenkins Pipeline

Use the Jenkinsfile to build and upload packages:

```bash
# In Jenkins, select package name and version
# Pipeline will build and upload to SCM repository automatically
```

## Package Structure

### Control File Example (AVS)

```
Source: avs
Section: libs
Priority: optional
Maintainer: Legatus Team <legatus@defence-elec.de>
Build-Depends: debhelper (>= 12), qt6-base-dev, ...

Package: libavs-dev
Architecture: amd64
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: AVS library development files
   Development files and headers for the AVS library
   used in the Legatus project.
Vcs-Browser: https://internal-repo.sl.defence-elec.de
Vcs-Git: https://internal-repo.sl.defence-elec.de/git/avs.git
```

### Installation Path

All packages install to `/opt/{DependencyName}` directory structure:
- Installation root: `/opt/{DependencyName}/`
- Headers: `/opt/{DependencyName}/include/`
- Libraries: `/opt/{DependencyName}/lib/`
- CMake configs: `/opt/{DependencyName}/cmake/`
- Licenses: `/opt/{DependencyName}/` (RTI) or `/usr/share/doc/<package>/copyright`

## Uploading to SCM Repository

### Jenkins Pipeline

The Jenkinsfile automates building and uploading:

```groovy
// Parameters:
// - PACKAGE_NAME: avs, arcgis, buildingmodels, etc.
// - PACKAGE_VERSION: 1.0.0
// - SCM_URL: http://remote-repo.sl.defence-elec.de:8081/repository/external-rpms/general/
// - CREDENTIALS_ID: Jenkins credentials ID for SCM authentication

pipeline {
    agent any
    parameters {
        choice(name: 'PACKAGE_NAME', choices: ['avs', 'arcgis', 'buildingmodels', 'geographiclib', 'schusstafel', 'dtentity', 'rti-connext-dds', 'tmsif'])
        string(name: 'PACKAGE_VERSION', defaultValue: '1.0.0')
    }
    stages {
        stage('Build') {
            steps {
                sh "cd external-dependencies/deb-packages/\${PACKAGE_NAME} && debuild -us -uc -b"
            }
        }
        stage('Upload') {
            steps {
                sh "curl -u \${SCM_CREDENTIALS} --upload-file ../lib\${PACKAGE_NAME}-dev_\${PACKAGE_VERSION}_amd64.deb \${SCM_URL}"
            }
        }
    }
}
```

### Manual Upload

```bash
curl -u <username>:<password> \
  --upload-file libavs-dev_1.0.0_amd64.deb \
  http://remote-repo.sl.defence-elec.de:8081/repository/external-rpms/general/
```

## License Handling

### RTI Connext DDS

The RTI package includes the commercial license file:
- `rti_license.dat` included in DEB package at `/opt/rti_connext_dds-7.7.0/rti_license.dat`
- DEB package installs to `/opt/rti_connext_dds-7.7.0/`
- FlexLM license validated at runtime

### ArcGIS Runtime SDK

- Map-specific licenses embedded in .ini files
- Licenses included in DEB package
- Located in `/opt/ArcGIS/MapsSDK_Qt_300.0.0/`

### AVS & tmsif

- Customer lifetime license contracts
- No license files required in DEB package
- License contracts maintained separately by customer

### Other Packages

- Open source or internal licenses
- Standard copyright file in `/usr/share/doc/<package>/copyright`

## Verification

After installation, verify packages:

```bash
# Check installed packages
dpkg -l | grep libavs-dev

# List installed files
dpkg -L libavs-dev

# Check package info
apt-cache show libavs-dev

# Verify installation path
ls -la /opt/AVS/

# Verify dependencies
ldd /opt/AVS/lib/libavs.so
```


## Usage in Dockerfiles

Example Dockerfile using DEB packages from SCM:

```dockerfile
FROM ubuntu:26.04

# Configure APT repository for internal SCM
RUN echo "deb [trusted=yes] http://remote-repo.sl.defence-elec.de:8081/repository/external-rpms/general/ /" > /etc/apt/sources.list.d/scm.list

# Install all external dependencies
RUN apt-get update && apt-get install -y \
    libavs-dev \
    libarcgis-dev \
    libbuildingmodels-dev \
    libgeographiclib-dev \
    libschusstafel-dev \
    libdtentity-dev \
    librti-connext-dds-7.7.0-dev \
    libtmsif-dev \
    && rm -rf /var/lib/apt/lists/*

# Verify installation
RUN ls -la /opt/AVS /opt/ArcGIS /opt/RTI
```

## Security Considerations

- **Include license files** in DEB packages where required (RTI, ArcGIS)
- **Sign packages** with internal signing key before distribution
- **Verify checksums** after upload to repository
- **Maintain chain of custody** for proprietary packages
- **Use HTTPS** for SCM repository access in production

## References

- [Ubuntu Packaging Guide](https://ubuntu.com/server/docs/packaging)
- [Debian New Maintainers' Guide](https://www.debian.org/doc/manuals/maint-guide/)
- [Internal SCM Repository](https://internal-repo.sl.defence-elec.de/#browse/browse:external-rpms:general)
- [Main README](../README.md)