Qt5 migration

.agents/build-static-qt5.toml

@@ -0,0 +1,38 @@
+name = "build-static-qt5"
+description = "Run and monitor the long static Qt 5 build, then report completion or failure."
+
+model = "gpt-5.4-mini"
+model_reasoning_effort = "low"
+
+developer_instructions = """
+You are a narrow build runner for this repository.
+
+Your only job is to run the requested static Qt 5 helper flow.
+
+Allowed local commands are:
+- ./build-qt5-static.sh --runtime docker --debug --clean
+- ./build-qt5-static.sh --runtime docker --debug --qt-only --clean
+- ./build-qt5-static.sh --runtime docker --debug --qtwebkit-only
+
+Use the full debug clean flow unless the caller explicitly asks for a scoped
+Qt-only or QtWebKit-only build. Do not add release-build flags; release builds
+are validated by CI.
+
+Monitor the command until it completes or fails. Do not edit files, refactor code,
+inspect unrelated project state, or run unrelated commands.
+
+Use the repository's sanctioned helper-script flow only. Do not run host-local or
+ad hoc qmake, make, cmake, ninja, compiler, or produced-binary commands.
+
+The clean debug Qt run is intentional when Qt patches changed: it avoids stale
+generated Qt source trees. Do not combine --qtwebkit-only with --clean because
+that scope requires an existing Qt install.
+
+When the build finishes, hand the result back to the top-level caller with:
+- whether the build completed successfully or failed
+- the exit status, if available
+- the most relevant final output
+- the first clear error message or failing step, if the build failed
+
+Keep the report concise and factual.
+"""

.clang-tidy

@@ -0,0 +1,19 @@
+Checks: >
+  -*,
+  clang-analyzer-*,
+  bugprone-assignment-in-if-condition,
+  bugprone-branch-clone,
+  bugprone-copy-constructor-init,
+  bugprone-inaccurate-erase,
+  bugprone-macro-parentheses,
+  bugprone-sizeof-expression,
+  bugprone-string-constructor,
+  modernize-redundant-void-arg,
+  modernize-use-bool-literals,
+  modernize-use-nullptr,
+  readability-duplicate-include,
+  readability-misleading-indentation,
+  readability-redundant-control-flow,
+  readability-simplify-boolean-expr,
+  readability-static-accessed-through-instance
+HeaderFilterRegex: '(^|.*/)src/.*'

.github/workflows/qt5-static.yml

@@ -0,0 +1,258 @@
+name: Qt5 Static
+
+on:
+  push:
+    branches:
+      - "**"
+    tags:
+      - "**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+env:
+  BUILD_TYPE: release
+  QT_VERSION: 5.15.17
+  QTWEBKIT_VERSION: "2022-09-07"
+  TOOLCHAIN_PLATFORM: ubuntu-20.04-x86_64
+
+jobs:
+  qt5:
+    name: Build Qt5 static
+    runs-on: ubuntu-24.04
+    timeout-minutes: 720
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Check Qt version consistency
+        run: |
+          set -euo pipefail
+
+          workflow_qt_version="${QT_VERSION}"
+          # shellcheck disable=SC1091
+          source toolchains/qt5-static/common.sh
+          if [[ "${QT_VERSION}" != "${workflow_qt_version}" ]]; then
+            echo "error: workflow QT_VERSION=${workflow_qt_version} does not match common.sh QT_VERSION=${QT_VERSION}" >&2
+            exit 1
+          fi
+
+      - name: Cache Qt5 build
+        id: qt5-cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/install
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/logs
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/build-manifest.txt
+          key: qt5-static-${{ runner.os }}-${{ env.BUILD_TYPE }}-${{ hashFiles('toolchains/qt5-static/Dockerfile', 'toolchains/qt5-static/qt5-static-build-entrypoint.sh', 'toolchains/qt5-static/sources-qt.lock', 'toolchains/qt5-static/patches/qt/*.patch') }}
+
+      - name: Cache source archives
+        if: steps.qt5-cache.outputs.cache-hit != 'true'
+        uses: actions/cache@v4
+        with:
+          path: artifacts/src-cache
+          key: qt5-static-sources-${{ hashFiles('toolchains/qt5-static/sources.lock', 'toolchains/qt5-static/sources-qt.lock', 'toolchains/qt5-static/sources-qtwebkit.lock') }}
+
+      - name: Build static Qt5
+        if: steps.qt5-cache.outputs.cache-hit != 'true'
+        run: ./build-qt5-static.sh --runtime docker --qt-only
+
+  qtwebkit:
+    name: Build QtWebKit
+    runs-on: ubuntu-24.04
+    needs: qt5
+    timeout-minutes: 720
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Cache QtWebKit build
+        id: qtwebkit-cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/install
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/logs
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/build-manifest.txt
+          key: qtwebkit-static-${{ runner.os }}-${{ env.BUILD_TYPE }}-${{ hashFiles('toolchains/qt5-static/Dockerfile', 'toolchains/qt5-static/qt5-static-build-entrypoint.sh', 'toolchains/qt5-static/sources-qt.lock', 'toolchains/qt5-static/patches/qt/*.patch', 'toolchains/qt5-static/sources-qtwebkit.lock', 'toolchains/qt5-static/patches/qtwebkit/*.patch') }}
+
+      - name: Cache source archives
+        if: steps.qtwebkit-cache.outputs.cache-hit != 'true'
+        uses: actions/cache@v4
+        with:
+          path: artifacts/src-cache
+          key: qt5-static-sources-${{ hashFiles('toolchains/qt5-static/sources.lock', 'toolchains/qt5-static/sources-qt.lock', 'toolchains/qt5-static/sources-qtwebkit.lock') }}
+
+      - name: Restore Qt5 build
+        if: steps.qtwebkit-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/install
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/logs
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/build-manifest.txt
+          key: qt5-static-${{ runner.os }}-${{ env.BUILD_TYPE }}-${{ hashFiles('toolchains/qt5-static/Dockerfile', 'toolchains/qt5-static/qt5-static-build-entrypoint.sh', 'toolchains/qt5-static/sources-qt.lock', 'toolchains/qt5-static/patches/qt/*.patch') }}
+
+      - name: Build CI container image
+        run: docker build -f toolchains/qt5-static/Dockerfile -t qtweb-qt5-static:${QT_VERSION} .
+
+      - name: Build static QtWebKit
+        if: steps.qtwebkit-cache.outputs.cache-hit != 'true'
+        run: ./build-qt5-static.sh --runtime docker --qtwebkit-only
+
+      - name: Build QtWebKit smoke test
+        run: ./smoke-tests/qtwebkit-smoke/smoke-build-docker.sh
+
+      # - name: Runtime test QtWebKit app
+      #   run: ./run-smoke.sh --runtime-check about:blank
+
+      - name: Check QtWebKit shared dependencies
+        run: ./run-smoke.sh --check
+
+  qtweb:
+    name: Build QtWeb
+    runs-on: ubuntu-24.04
+    needs: qtwebkit
+    timeout-minutes: 120
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Restore QtWebKit build
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/install
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/logs
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/build-manifest.txt
+          key: qtwebkit-static-${{ runner.os }}-${{ env.BUILD_TYPE }}-${{ hashFiles('toolchains/qt5-static/Dockerfile', 'toolchains/qt5-static/qt5-static-build-entrypoint.sh', 'toolchains/qt5-static/sources-qt.lock', 'toolchains/qt5-static/patches/qt/*.patch', 'toolchains/qt5-static/sources-qtwebkit.lock', 'toolchains/qt5-static/patches/qtwebkit/*.patch') }}
+
+      - name: Build CI container image
+        run: docker build -f toolchains/qt5-static/Dockerfile -t qtweb-qt5-static:${QT_VERSION} .
+
+      - name: Build QtWeb
+        run: ./build-browser-docker.sh
+
+      # - name: Runtime test QtWeb
+      #   run: ./run-browser.sh --runtime-check about:blank
+
+      - name: Check QtWeb shared dependencies
+        run: ./run-browser.sh --check
+
+  publish-qt-toolchain:
+    name: Publish Qt5 toolchain
+    runs-on: ubuntu-24.04
+    needs: qt5
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Restore Qt5 build
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/install
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/logs
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/build-manifest.txt
+          key: qt5-static-${{ runner.os }}-${{ env.BUILD_TYPE }}-${{ hashFiles('toolchains/qt5-static/Dockerfile', 'toolchains/qt5-static/qt5-static-build-entrypoint.sh', 'toolchains/qt5-static/sources-qt.lock', 'toolchains/qt5-static/patches/qt/*.patch') }}
+
+      - name: Package Qt5 toolchain
+        run: |
+          set -euo pipefail
+
+          toolchain_dir="artifacts/qt5-static-${QT_VERSION}-${BUILD_TYPE}"
+          asset="qt5-static-${QT_VERSION}-${BUILD_TYPE}-${TOOLCHAIN_PLATFORM}.tar.zst"
+
+          test -d "${toolchain_dir}/install"
+          test -f "${toolchain_dir}/build-manifest.txt"
+
+          tar --zstd -cf "${asset}" \
+            -C "${toolchain_dir}" \
+            install \
+            build-manifest.txt
+
+      - name: Upload workflow artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}-${{ env.TOOLCHAIN_PLATFORM }}
+          path: qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}-${{ env.TOOLCHAIN_PLATFORM }}.tar.zst
+
+      - name: Upload release asset
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          asset="qt5-static-${QT_VERSION}-${BUILD_TYPE}-${TOOLCHAIN_PLATFORM}.tar.zst"
+
+          if ! gh release view "${GITHUB_REF_NAME}" >/dev/null 2>&1; then
+            gh release create "${GITHUB_REF_NAME}" \
+              --title "${GITHUB_REF_NAME}" \
+              --notes "Static Qt5 and QtWebKit toolchains."
+          fi
+
+          gh release upload "${GITHUB_REF_NAME}" "${asset}" --clobber
+
+  publish-qtwebkit-toolchain:
+    name: Publish QtWebKit toolchain
+    runs-on: ubuntu-24.04
+    needs:
+      - qtwebkit
+      - publish-qt-toolchain
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Restore QtWebKit build
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/install
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/logs
+            artifacts/qt5-static-${{ env.QT_VERSION }}-${{ env.BUILD_TYPE }}/build-manifest.txt
+          key: qtwebkit-static-${{ runner.os }}-${{ env.BUILD_TYPE }}-${{ hashFiles('toolchains/qt5-static/Dockerfile', 'toolchains/qt5-static/qt5-static-build-entrypoint.sh', 'toolchains/qt5-static/sources-qt.lock', 'toolchains/qt5-static/patches/qt/*.patch', 'toolchains/qt5-static/sources-qtwebkit.lock', 'toolchains/qt5-static/patches/qtwebkit/*.patch') }}
+
+      - name: Package QtWebKit toolchain
+        run: |
+          set -euo pipefail
+
+          toolchain_dir="artifacts/qt5-static-${QT_VERSION}-${BUILD_TYPE}"
+          asset="qt5-static-${QT_VERSION}-qtwebkit-${QTWEBKIT_VERSION}-${BUILD_TYPE}-${TOOLCHAIN_PLATFORM}.tar.zst"
+
+          test -d "${toolchain_dir}/install"
+          test -f "${toolchain_dir}/build-manifest.txt"
+
+          tar --zstd -cf "${asset}" \
+            -C "${toolchain_dir}" \
+            install \
+            build-manifest.txt
+
+      - name: Upload workflow artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: qt5-static-${{ env.QT_VERSION }}-qtwebkit-${{ env.QTWEBKIT_VERSION }}-${{ env.BUILD_TYPE }}-${{ env.TOOLCHAIN_PLATFORM }}
+          path: qt5-static-${{ env.QT_VERSION }}-qtwebkit-${{ env.QTWEBKIT_VERSION }}-${{ env.BUILD_TYPE }}-${{ env.TOOLCHAIN_PLATFORM }}.tar.zst
+
+      - name: Upload release asset
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          asset="qt5-static-${QT_VERSION}-qtwebkit-${QTWEBKIT_VERSION}-${BUILD_TYPE}-${TOOLCHAIN_PLATFORM}.tar.zst"
+
+          gh release upload "${GITHUB_REF_NAME}" "${asset}" --clobber

.gitignore

@@ -3,6 +3,7 @@ src/qt/.*
 temp-src
 build
 artifacts
+.codex
 
 # C++ objects and libs
 
@@ -26,4 +27,4 @@ Makefile*
 build-*
 !build-browser-docker.sh
 !build-qt5-static.sh
-!toolchains/qt5-static/build-inside-container.sh
+!.agents/build-static-qt5.toml

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+  "files.watcherExclude": {
+    "**/artifacts/**": true,
+    "**/build-*/**": true,
+    "**/src/qt/**": true
+  },
+  "search.exclude": {
+    "**/artifacts/**": true,
+    "**/build-*/**": true,
+    "**/src/qt/**": true
+  }
+}

AGENTS.md

@@ -1,10 +1,37 @@
 # AGENTS.md
 
+## Code Style
+- Do not introduce one-off variables for simple values or small argument groups. Keep values inline at the use site unless a variable removes real duplication, clarifies non-obvious logic, or matches nearby style.
+- When individual shell command arguments need comments, prefer a single argument array with comments beside the relevant entries instead of separate helper variables for small flag groups.
+- In shell scripts, do not build command strings or use `eval`; use direct command calls or argument arrays so quoting and word splitting stay explicit.
+- Do not pass long inline shell programs to Docker with `bash -c`/`bash -lc`; put the container-side logic in a checked-in script and execute that script.
+- Do not add helper functions that are only called once unless they isolate a meaningful phase, cleanup/error boundary, or repeated validation pattern.
+- Treat `build.sh` as a legacy script: do not apply cleanup/style rewrites there unless the user explicitly asks to modernize that script.
+
 ## Build And Validation Policy
 - Do not run host-local or ad hoc builds in this repository.
 - Do not invoke `qmake`, `make`, `cmake`, `ninja`, or compiler commands directly on the host for validation or debugging.
-- Use the repository's sanctioned helper-script flows instead, such as `build-browser-docker.sh`, `build-qt5-static.sh`, and `smoke-run.sh`, when a build or runtime validation is explicitly required.
+- Use the repository's sanctioned helper-script flows instead, such as `build-browser-docker.sh`, `build-qt5-static.sh`, and `run-smoke.sh`, when a build or runtime validation is explicitly required.
+- For any `build-qt5-static.sh` request, including short requests like "clean rebuild", use the `.agents/build-static-qt5.toml` subagent instead of running the long build directly in the main agent.
 - If that sanctioned path is unavailable, blocked, or out of scope for the task, state that validation could not be run. Do not fall back to a local build.
 - Do not launch the built `QtWeb` binary or other produced executables as an agent.
-- Do not run `smoke-run.sh` or start GUI/runtime validation on the user's behalf unless the user explicitly asks for that exact execution.
+- Do not run `run-smoke.sh` or start GUI/runtime validation on the user's behalf unless the user explicitly asks for that exact execution.
+- Use `./run-smoke.sh --check` and `./run-browser.sh --check` to check existing Docker-built binaries for remaining shared dependencies.
 - When a build succeeds, report the output path or the command the user can run; leave execution to the user unless explicitly requested.
+
+## QtWeb Static Build Notes
+- Shared Qt build defaults live in `toolchains/qt5-static/common.sh`: Qt `5.15.17`, image tag `qtweb-qt5-static:5.15.17`.
+- Static-linking fixes must be applied in the Qt or QtWebKit build itself, such as configure inputs, source patches, or checked-in container-side build scripts. This keeps future Qt/QtWebKit upgrades honest: patches should fail early and be rebased deliberately instead of relying on post-build metadata rewrites or other broken hacks.
+- For local validation, check only debug builds to save time; release builds are validated by CI.
+- Use the `.agents/build-static-qt5.toml` subagent when running full or scoped `./build-qt5-static.sh` flows so long builds are monitored without unrelated edits or commands. The default clean rebuild command is `./build-qt5-static.sh --runtime docker --debug --clean`.
+- Use `./build-qt5-static.sh --runtime docker --qt-only` for the static Qt stage and `./build-qt5-static.sh --runtime docker --qtwebkit-only` for the QtWebKit stage.
+- Use `./build-browser-docker.sh` for the QtWeb browser stage; add `--analyze` only when clang-tidy analysis is explicitly requested.
+- Use `./smoke-tests/qtwebkit-smoke/smoke-build-docker.sh` for the QtWebKit smoke-test build.
+- Runtime checks are host-side wrappers and must only be run on explicit request: `./run-smoke.sh --runtime-check about:blank` or `./run-browser.sh --runtime-check about:blank`.
+- The CI workflow is `.github/workflows/qt5-static.yml`; its main order is `qt5` -> `qtwebkit` -> `qtweb`, followed by publish jobs.
+- For build failures, classify the first real error as configure-time, compile-time, link-time, runtime/smoke-test, CI resource exhaustion, or missing static dependency before editing scripts.
+
+## Documentation Policy
+- Keep `docs/migration-status.md` limited to behavior that is implemented in the repository.
+- Keep `docs/plan.md` limited to planned or pending work.
+- When implementing a planned change, update both docs in the same change: move completed points from `docs/plan.md` to `docs/migration-status.md` and remove stale planned items.

README.md

@@ -3,4 +3,4 @@ QtWeb
 
 QtWeb Internet Browser
 
-Build policy: do not use host-local or ad hoc builds for this repository. Use the repository helper scripts and containerized flows for build or validation work; if that path is unavailable, report validation as not run instead of falling back to local `qmake`/`make` commands. Agents should not launch the built `QtWeb` binary or other produced executables unless explicitly asked; they should report the path or command for the user to run instead.
+Build policy: do not use host-local or ad hoc builds for this repository. Use the repository helper scripts and containerized flows for build or validation work; if that path is unavailable, report validation as not run instead of falling back to local `qmake`/`make` commands. `./run-smoke.sh --check` and `./run-browser.sh --check` validate shared dependencies for existing Docker-built binaries. `./run-smoke.sh --runtime-check about:blank` and `./run-browser.sh --runtime-check about:blank` are the host-side runtime checks. Agents may only use `run-smoke.sh` and `run-browser.sh` for runtime checks; directly launching the built `QtWeb` binary or other produced executables is prohibited.