If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/therecipe/qt shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 3 active contributors
• LGPL-3.0 licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 89% of recent commits
• ⚠ LGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live therecipe/qt repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/therecipe/qt.

What it runs against: a local clone of therecipe/qt — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in therecipe/qt | Confirms the artifact applies here, not a fork | | 2 | License is still LGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 824 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of therecipe/qt. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/therecipe/qt.git
#   cd qt
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of therecipe/qt and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "therecipe/qt(\\.git)?\\b" \\
  && ok "origin remote is therecipe/qt" \\
  || miss "origin remote is not therecipe/qt (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(LGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"LGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is LGPL-3.0" \\
  || miss "license drift — was LGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 824 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~794d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/therecipe/qt"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

therecipe/qt is a Go language binding for Qt that allows developers to write cross-platform GUI applications entirely in Go instead of C++, with automatic code generation via qtmoc and qtrcc tools. It provides direct access to nearly all Qt classes and functions while handling the C++/Go interoperability layer transparently, enabling deployment to Windows, macOS, Linux, Android, iOS, WebAssembly, and embedded platforms from a single Go codebase. Modular monorepo structure: top-level directories (core/, gui/, bluetooth/, charts/, etc.) contain Go bindings for each Qt module, with cmd/ subdirectory holding CLI tools (qtsetup, qtdeploy, qtmoc, qtrcc); internal/binding/converter/ handles C++↔Go code generation; platform-specific logic isolated in androidextras/, felgo/, flutter/ and cmd/env/. Each module's .go file is paired with corresponding .cpp/.h files for C++ integration.

Go developers who need to build rich desktop and mobile GUI applications without learning C++, as well as teams deploying Qt applications across multiple platforms (Windows/macOS/Linux/Android/iOS) who want to leverage Go's simplicity, fast compilation, and existing Go ecosystem instead of maintaining C++ codebases.

Actively developed and production-ready: the repository shows comprehensive platform support (Windows, macOS, Linux, Android, iOS with platform-specific code in cmd/env/), includes CI/CD (azure-pipelines.yml), and has established tooling (qtsetup, qtmoc, qtrcc, qtdeploy commands). However, the project is maintained by a core team rather than having massive community adoption, so some edge cases may exist.

Standard open source risks apply.

The repository maintains active support across multiple platforms with platform-specific code generation (cmd/env for Darwin/Linux/Windows, androidextras for Android). Azure Pipelines CI is configured. The codebase includes experimental support for WebAssembly/JavaScript binding (flutter/embedder, entry companion project) and Flutter integration, suggesting exploration of expanding beyond traditional Qt desktop.

Clone and install the default version (requires Go already installed): git clone https://github.com/therecipe/qt && cd qt && export GO111MODULE=off && go get -v ./cmd/... && $(go env GOPATH)/bin/qtsetup test && $(go env GOPATH)/bin/qtsetup -test=false (on macOS/Linux; Windows has set GO111MODULE=off and %v\bin\ instead of $(go env GOPATH)/bin/).

Daily commands: After qtsetup completes: create a Go file with qt.NewQApplication() and qt.NewQMainWindow(), build with go build, and run the binary. For deployment: use qtdeploy build (after qtsetup) which invokes internal cross-compilation logic. See cmd/qtdeploy/main.go for deployment orchestration.

• cmd/qtsetup/main.go: Entry point for initial environment setup and validation; orchestrates detection of Qt installation and configuration across platforms.
• internal/binding/converter/body_input_cpp.go: Core code generator that converts C++ Qt method signatures to Go bindings; critical for automatic API exposure.
• cmd/qtmoc/main.go: Implements the Qt moc (meta-object compiler) equivalent in Go; preprocessor that generates boilerplate for signal/slot connections.
• cmd/qtdeploy/main.go: Handles cross-platform application deployment and bundling; translates Go binaries into distributable Qt applications per target OS.
• core/core.go: Base module that all other Qt module bindings depend on; defines fundamental types and FFI primitives for the entire binding.
• gui/gui.go: Qt GUI module bindings (windows, widgets, events); one of the most-used modules for building UIs.
• cmd/env/: Platform-specific environment detection (darwin_amd64.go, linux_amd64.go, windows_amd64.go); ensures correct Qt paths and compiler flags per OS.

For binding new Qt classes: study internal/binding/converter/body_input_.go (C++→Go) and body_output_.go (Go→C++) to understand the code generation pattern; add stubs in the appropriate Qt module directory (e.g., gui/gui.go for GUI classes); run qtmoc to regenerate bindings. For platform support: platform-specific code lives in cmd/env/.go and androidextras/. For tooling: CLI commands are in cmd/qt/main.go.

GO111MODULE=off is required in the install instructions (non-standard for modern Go projects, indicates legacy module handling); qt setup must be run before building any Qt application and alters global Go environment variables; cross-compilation requires matching Qt libraries for the target platform installed locally (e.g., to build for Android, the Android Qt SDK must be present on your machine); cgo requires a C++ compiler and Qt development headers, making initial setup heavily dependent on system packages (apt/brew/choco); the exact Qt version and location is detected by qtsetup and can fail silently if Qt is non-standard paths.

• cgo (C bindings for Go) — therecipe/qt's entire foundation: cgo enables Go to call C++ Qt functions directly; understanding cgo limitations (thread safety, memory management, pointer escaping) is essential for debugging crashes or performance issues in Qt Go applications.
• Code generation (qtmoc, qtrcc) — Qt's traditional moc preprocessor pattern is replicated in Go via qtmoc and qtrcc tools; knowing how these generate boilerplate (signal/slot connections, resource embedding) helps contributors extend the binding.
• Cross-compilation and deployment — qtdeploy orchestrates building Go+Qt for multiple target platforms from a single machine (e.g., compile for iOS from macOS); understanding this process is critical for platform-specific bugs and deployment failures.
• Signal/slot mechanism (Qt Signals and Slots) — Qt's foundational event-driven pattern (signals emit events, slots receive them) is central to all interactive GUI; the Go binding must translate this to idiomatic Go channels/callbacks, making it crucial for UI logic.
• Memory ownership and lifetime (parent-child relationships) — Qt uses parent-child object hierarchies for memory management (deleting parent auto-deletes children); Go's garbage collector doesn't understand this, requiring explicit lifetime management in the binding to prevent crashes.
• Platform abstraction layer (cmd/env/) — Different OS builds require different Qt paths, compiler flags, and SDKs; cmd/env/ contains the detection logic that qtsetup uses; understanding this is vital for supporting new platforms or fixing OS-specific build failures.
• WebAssembly/GopherJS interop — flutter/ and embedder.go hint at experimental JavaScript/WASM support using GopherJS; this requires understanding Go-to-JS transpilation, which is fundamentally different from native cgo and affects how bindings are generated.

• fyne/fyne — Alternative pure-Go GUI framework that avoids C++ FFI entirely; targets same use case (cross-platform Go desktop apps) but with different architecture tradeoffs.
• therecipe/flutter — Sister project from same author enabling Flutter/Dart bindings to Qt; represents parallel effort to support multiple languages on Qt foundation.
• therecipe/entry — JavaScript/TypeScript bindings to Qt from therecipe author; used for web-based Qt deployments via WebAssembly (referenced in README as live demo).
• golang/go — Upstream Go language; cgo and go.mod management are critical dependencies for therecipe/qt's entire build and deployment system.
• qt/qt5 — The Qt framework itself; therecipe/qt is a language binding layer on top of libQt5 C++ libraries that must be installed on the developer's machine.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add platform-specific CI workflows for Android and iOS deployment validation

The repo supports Android and iOS targets (see androidextras/ directory and cmd/qtdeploy), but azure-pipelines.yml only covers basic CI. There's no validation that Android/iOS builds actually succeed. Adding GitHub Actions for Android NDK compilation and iOS framework packaging would catch regressions early and help contributors test cross-platform builds locally.

• [ ] Create .github/workflows/android-build.yml to validate Android APK compilation using cmd/qtdeploy with sample androidextras code
• [ ] Create .github/workflows/ios-build.yml to validate iOS framework packaging for supported architectures
• [ ] Add validation step in workflows to test core/ and gui/ bindings compile for each target platform
• [ ] Document expected environment variables and SDK versions needed in CONTRIBUTING.md

Add comprehensive binding converter tests for internal/binding/converter/

The converter package (body_input_cpp.go, body_output_go.go, type.go, enum.go) is critical infrastructure for generating C++/Go bridge code, but there's no evidence of unit tests. This is high-risk code with no test coverage shown. Adding tests would prevent regressions when updating Qt bindings and help new contributors understand the converter logic.

• [ ] Create internal/binding/converter/converter_test.go with table-driven tests for Type.go (test basic types, pointers, enums)
• [ ] Add tests for body_input_cpp.go parameter conversion (validate C++ signature generation for Go function calls)
• [ ] Add tests for body_output_go.go return value conversion (validate Go signature generation from C++ returns)
• [ ] Add tests for enum.go to ensure enum constants are correctly mapped between Qt and Go

Create missing documentation for cmd/ tool flags and qt/internal binding generation architecture

The repo has 5 CLI tools (qtdeploy, qtmoc, qtrcc, qtsetup, qtminimal) in cmd/ but no documented flag reference. Additionally, the binding generation pipeline (internal/binding + converter) lacks architectural documentation. New contributors can't understand how to use these tools or extend the binding generator without reading source code.

• [ ] Create docs/cli-reference.md documenting each tool in cmd/ with examples: qtdeploy (deployment targets), qtmoc (Qt metacompiler), qtrcc (resource compilation), qtsetup (environment), qtminimal (minimal builds)
• [ ] Create docs/binding-generation.md explaining the flow: Qt docs → internal/binding/files/docs → converter → generated Go code with examples
• [ ] Add inline code examples showing how to use each cmd/ tool for common scenarios (e.g., 'Deploy Android app', 'Regenerate bindings for new Qt version')
• [ ] Link new docs from README.md in appropriate sections

• Add type safety tests for internal/binding/converter/: The converter package (body_input_cpp.go, body_output_cpp.go, body_input_go.go, body_output_go.go) has no visible unit tests in the repo file list; adding tests to verify C++↔Go type mapping correctness would catch regressions early.
• Document platform-specific build flags in cmd/env/: cmd/env/darwin_amd64.go, linux_amd64.go, and windows_amd64.go contain hardcoded Qt paths and compiler flags; creating a guide explaining how to modify these for non-standard Qt installations would help new contributors.
• Add example for bluetooth module: bluetooth/bluetooth.go exists but has no visible example in the file list (only examples/basic/widgets is mentioned in README); creating a minimal example showing Bluetooth device discovery would improve discoverability of this module.

• High · Outdated and Vulnerable Dependencies — go.mod. The go.mod file contains dependencies with known vulnerabilities from 2019. Specifically: golang.org/x/crypto v0.0.0-20190418165655-df01cb2cc480, golang.org/x/net v0.0.0-20190420063019-afa5a82059c6, and golang.org/x/sys v0.0.0-20190419153524-e8e3143a4f4a are severely outdated. These packages have multiple known CVEs including cryptographic vulnerabilities, network handling issues, and system-level exploits. Fix: Update all dependencies to their latest stable versions. Run 'go get -u' and 'go mod tidy'. Pay particular attention to golang.org/x/crypto which may contain cryptographic vulnerabilities.
• High · Unsafe Module Replacements — go.mod (lines with 'replace' directives). The go.mod file uses multiple 'replace' directives that redirect standard library modules to GitHub mirrors (github.com/golang/*). This introduces supply chain risk and makes the project vulnerable to compromised mirrors or man-in-the-middle attacks. These replacements bypass Go's official security infrastructure. Fix: Remove the replace directives unless there is a critical reason. Use official golang.org modules. If replacements are necessary, use local path references or pin to specific, verified commit hashes with integrity checks.
• High · Unverified Third-Party C/C++ Code — felgo/, flutter/, androidextras/, and other directories with .cpp/.h files. The repository contains numerous C++ and header files (.cpp, .h) for native Qt bindings without visible code review artifacts or security audit documentation. Files like felgo/felgo.cpp, flutter/embedder.h, and androidextras/androidextras_android.cpp represent native code that could contain memory safety issues, buffer overflows, or code injection vulnerabilities. Fix: Conduct thorough security audits of all native C++ code. Implement static analysis tools (clang-tidy, cppcheck). Consider using memory-safe alternatives where possible. Enable compiler warnings and address sanitizers during development.
• Medium · Outdated sirupsen/logrus Dependency — go.mod. The sirupsen/logrus v1.4.1 dependency from 2019 may contain known vulnerabilities and lacks security updates. While logrus is a logging library, compromised or vulnerable logging can lead to information disclosure or denial of service. Fix: Update sirupsen/logrus to the latest stable version (currently v1.9.x or later). Review changelog for any security-related fixes.
• Medium · Potential Dynamic Code Generation Security Risk — cmd/qtmoc/main.go, cmd/qtrcc/main.go, cmd/qtdeploy/main.go, internal/binding/converter/. The codebase includes code generation tools (cmd/qtmoc, cmd/qtrcc, cmd/qtdeploy) that process Qt metadata and generate Go/C++ binding code. These tools may be vulnerable to injection attacks if they process untrusted input without proper sanitization. Fix: Review code generation logic in the converter package for input validation. Ensure all user-controlled data is properly escaped/sanitized before code generation. Implement strict parsing with schema validation for metadata files.
• Medium · Missing Security Headers and Configuration in Azure Pipelines — azure-pipelines.yml. The azure-pipelines.yml file is present but not visible in the analysis. CI/CD pipelines often contain security-critical configurations. Without visibility, risks include exposed credentials in pipeline logs, insecure artifact handling, or missing security scanning steps. Fix: Review CI/CD pipeline configuration for: 1) Secrets management (use Azure Secrets, not hardcoded credentials), 2) Enable dependency scanning, 3) Add SAST tools (e.g., Snyk, Dependabot), 4) Implement artifact signing, 5) Use branch protection rules.
• Low · No Visible Security Policy or Vulnerability Disclosure Process — Repository root. The repository lacks visible security.txt, SECURITY.md, or vulnerability disclosure guidelines. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file documenting the vulnerability disclosure process.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.