Package OpenFastTrace 4.9.0 for Debian

.github/workflows/build.yml

@@ -0,0 +1,120 @@
+name: Build Debian package
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build Debian source and binary packages
+    runs-on: ubuntu-26.04
+    permissions:
+      contents: read
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install Debian build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes \
+            appstream \
+            build-essential \
+            curl \
+            debhelper \
+            devscripts \
+            dpkg-dev \
+            imagemagick \
+            maven \
+            openjdk-17-jdk-headless \
+            pandoc \
+            shellcheck \
+            wget
+
+      - name: Configure Maven toolchain
+        run: |
+          jdk_home="$(dirname "$(dirname "$(readlink -f "$(command -v javac)")")")"
+          mkdir --parents "$HOME/.m2"
+          cat > "$HOME/.m2/toolchains.xml" <<EOF
+          <?xml version="1.0" encoding="UTF-8"?>
+          <toolchains>
+            <toolchain>
+              <type>jdk</type>
+              <provides>
+                <version>17</version>
+              </provides>
+              <configuration>
+                <jdkHome>$jdk_home</jdkHome>
+              </configuration>
+            </toolchain>
+          </toolchains>
+          EOF
+
+      - name: Read package version
+        run: echo "VERSION=$(dpkg-parsechangelog --show-field Version | sed 's/-[^-]*$//')" >> "$GITHUB_ENV"
+
+      - name: Create source package
+        run: ./create-source-package.sh "$VERSION"
+
+      - name: Create binary package
+        run: ./create-binary-package.sh "$VERSION"
+
+      - name: Smoke test installed package
+        run: |
+          sudo apt-get install --yes "./out/openfasttrace_${VERSION}-1_all.deb"
+          help_output="$(oft --help)"
+          printf '%s\n' "$help_output" | grep --extended-regexp --quiet \
+            '^OpenFastTrace [0-9]+\.[0-9]+\.[0-9]+$'
+          printf '%s\n' "$help_output" | grep --extended-regexp --quiet \
+            '^Usage:$'
+          printf '%s\n' "$help_output" | grep --extended-regexp --quiet \
+            '^  oft command \[option \.\.\.\] \[<input file or directory> \.\.\.\]$'
+          printf '%s\n' "$help_output" | grep --extended-regexp --quiet \
+            '^Commands:$'
+
+      - name: Generate SHA-256 checksums
+        run: |
+          (
+            cd out
+            sha256sum \
+              "openfasttrace_${VERSION}.orig.tar.gz" \
+              "openfasttrace_${VERSION}-1.debian.tar.xz" \
+              "openfasttrace_${VERSION}-1.dsc" \
+              "openfasttrace_${VERSION}-1_all.deb"
+          ) > out/SHA256SUMS
+
+      - name: Upload source package
+        uses: actions/upload-artifact@v7
+        with:
+          name: openfasttrace-source-package
+          path: |
+            out/openfasttrace_*.orig.tar.gz
+            out/openfasttrace_*.debian.tar.xz
+            out/openfasttrace_*.dsc
+          if-no-files-found: error
+
+      - name: Upload binary package
+        uses: actions/upload-artifact@v7
+        with:
+          name: openfasttrace-binary-package
+          path: out/openfasttrace_*_all.deb
+          if-no-files-found: error
+
+      - name: Upload SHA-256 checksums
+        uses: actions/upload-artifact@v7
+        with:
+          name: openfasttrace-checksums
+          path: out/SHA256SUMS
+          if-no-files-found: error

.github/workflows/release.yml

@@ -0,0 +1,86 @@
+name: Release Debian package
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: OpenFastTrace version to package and release
+        required: true
+        type: string
+        default: 4.9.0
+
+jobs:
+  release:
+    name: Create GitHub release
+    runs-on: ubuntu-26.04
+    permissions:
+      contents: write
+    concurrency:
+      group: ${{ github.workflow }}
+      cancel-in-progress: false
+    defaults:
+      run:
+        shell: bash
+    env:
+      VERSION: ${{ inputs.version }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Fail if not running on main branch
+        if: ${{ github.ref != 'refs/heads/main' }}
+        uses: actions/github-script@v9
+        with:
+          script: |
+            core.setFailed('Not running on main branch. Start this workflow from main.')
+
+      - name: Install Debian build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes \
+            appstream \
+            curl \
+            debhelper \
+            devscripts \
+            dpkg-dev \
+            imagemagick \
+            maven \
+            openjdk-17-jdk-headless \
+            pandoc \
+            shellcheck \
+            wget
+
+      - name: Create source package
+        run: ./create-source-package.sh "$VERSION"
+
+      - name: Create binary package
+        run: ./create-binary-package.sh "$VERSION"
+
+      - name: Generate SHA-256 checksums
+        run: |
+          (
+            cd out
+            sha256sum \
+              "openfasttrace_${VERSION}.orig.tar.gz" \
+              "openfasttrace_${VERSION}-1.debian.tar.xz" \
+              "openfasttrace_${VERSION}-1.dsc" \
+              "openfasttrace_${VERSION}-1_all.deb"
+          ) > out/SHA256SUMS
+
+      - name: Create GitHub release
+        run: |
+          gh release create "$VERSION" \
+            --target main \
+            --title "OpenFastTrace Debian package $VERSION" \
+            --generate-notes \
+            "out/openfasttrace_${VERSION}.orig.tar.gz" \
+            "out/openfasttrace_${VERSION}-1.debian.tar.xz" \
+            "out/openfasttrace_${VERSION}-1.dsc" \
+            "out/openfasttrace_${VERSION}-1_all.deb" \
+            out/SHA256SUMS
+        env:
+          GH_TOKEN: ${{ github.token }}

.gitignore

@@ -9,3 +9,15 @@ out/
 *.log
 *.tmp
 *.swp
+
+# Debian packaging intermediate files and build results
+/out/
+/openfasttrace-*.tar.gz
+/openfasttrace-*/
+/openfasttrace_*.orig.tar.gz
+/openfasttrace_*.debian.tar.xz
+/openfasttrace_*.diff.gz
+/openfasttrace_*.dsc
+/openfasttrace_*.buildinfo
+/openfasttrace_*.changes
+/openfasttrace_*.deb

check-preconditions.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+# check-preconditions.sh - Verifies the build environment for OpenFastTrace Debian Package
+# dsn~precondition-check~1, req~precondition-check~1
+
+set -e
+
+# Define required tools and their corresponding packages
+# Tools are checked for existence in PATH
+# [impl->dsn~build-tools~1]
+declare -A REQUIRED_TOOLS=(
+    ["dpkg-buildpackage"]="dpkg-dev"
+    ["dh"]="debhelper"
+    ["dch"]="devscripts"
+    ["curl"]="curl"
+    ["wget"]="wget"
+    ["shellcheck"]="shellcheck"
+    ["mvn"]="maven"
+    ["java"]="openjdk-17-jre-headless"
+    ["pandoc"]="pandoc"
+    ["appstreamcli"]="appstream"
+    ["convert"]="imagemagick"
+)
+readonly REQUIRED_TOOLS
+
+# [impl->dsn~precondition-check~1]
+check_tools() {
+    local missing_packages=()
+    local all_ok=true
+
+    echo "Checking for required tools..."
+    for tool in "${!REQUIRED_TOOLS[@]}"; do
+        if ! command -v "$tool" >/dev/null 2>&1; then
+            echo "  [FAIL] $tool is missing (provided by package: ${REQUIRED_TOOLS[$tool]})"
+            missing_packages+=("${REQUIRED_TOOLS[$tool]}")
+            all_ok=false
+        else
+            echo "  [ OK ] $tool is installed"
+        fi
+    done
+
+    if [ "$all_ok" = false ]; then
+        echo ""
+        echo "Error: Some required tools are missing."
+        echo "To install the missing packages, run:"
+        echo "  sudo apt-get update && sudo apt-get install -y ${missing_packages[*]}"
+        return 1
+    fi
+
+    echo ""
+    echo "All preconditions are met."
+    return 0
+}
+
+# [impl->dsn~precondition-check~1]
+main() {
+    check_tools
+}
+
+# Main execution
+main

create-binary-package.sh

@@ -0,0 +1,89 @@
+#!/bin/bash
+
+# create-binary-package.sh - Automates the creation of the Debian binary package
+# dsn~build-orchestration-scripts~1, dsn~build-reproducibility~1
+
+set -e
+
+readonly BUILD_DIR="out"
+
+# [impl->dsn~build-orchestration-scripts~1]
+verify_preconditions() {
+    ./check-preconditions.sh
+}
+
+# [impl->dsn~build-directory~1]
+ensure_build_dir() {
+    mkdir -p "$BUILD_DIR"
+}
+
+# [impl->dsn~version-input~1]
+validate_version() {
+    local -r version="$1"
+    if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+        echo "Error: Invalid version format '$version'. Expected <major>.<minor>.<fix>." >&2
+        return 1
+    fi
+}
+
+# [impl->dsn~build-orchestration-scripts~1]
+check_source_package_exists() {
+    local -r version="$1"
+    local -r dsc_file="$BUILD_DIR/openfasttrace_$version-1.dsc"
+    local -r orig_tarball="$BUILD_DIR/openfasttrace_$version.orig.tar.gz"
+    local -r debian_tarball="$BUILD_DIR/openfasttrace_$version-1.debian.tar.xz"
+
+    if [[ ! -f "$dsc_file" ]]; then
+        echo "Error: Source package control file not found at $dsc_file." >&2
+        echo "Please run ./create-source-package.sh $version first." >&2
+        return 1
+    fi
+
+    if [[ ! -f "$orig_tarball" || ! -f "$debian_tarball" ]]; then
+        echo "Error: Incomplete source package in $BUILD_DIR." >&2
+        return 1
+    fi
+}
+
+# [impl->dsn~build-orchestration-scripts~1]
+extract_source_package() {
+    local -r version="$1"
+    local -r dsc_file="openfasttrace_${version}-1.dsc"
+    local -r build_subdir="$BUILD_DIR/openfasttrace-$version"
+
+    echo "Cleaning up any existing build directory $build_subdir..."
+    rm -rf "$build_subdir"
+
+    echo "Extracting source package to $BUILD_DIR..."
+    (cd "$BUILD_DIR" && dpkg-source -x "$dsc_file")
+}
+
+# [impl->dsn~build-reproducibility~1]
+build_binary_package() {
+    local -r build_subdir="$BUILD_DIR/openfasttrace-$1"
+    echo "Building binary package (including HTML and manpage user guide)..."
+    (cd "$build_subdir" && dpkg-buildpackage -us -uc -b)
+}
+
+# [impl->dsn~build-orchestration-scripts~1]
+main() {
+    if [[ $# -ne 1 ]]; then
+        echo "Usage: $0 <version>" >&2
+        exit 1
+    fi
+
+    local -r version="$1"
+    validate_version "$version"
+
+    verify_preconditions
+    ensure_build_dir
+    check_source_package_exists "$version"
+    extract_source_package "$version"
+    build_binary_package "$version"
+
+    echo ""
+    echo "Binary package for version $version created successfully in $BUILD_DIR."
+    ls -l "$BUILD_DIR"/openfasttrace_"$version"-1_*.deb
+}
+
+main "$@"