Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ ui/stage 3D stage: scene graph, joints, meshes, STL, materials, view — n
ui/backend/recording records draw calls — the test harness — no Qt

ui/backend/qt QtCanvas, QtPaintedWidget, QtTheme — Qt6 Widgets
ui/backend/qt/update release check, verified download, installer, issue log — Qt6 Network
```

Still to come: `ui/model` (FormSpec, TableModel), `ui/sim`,
Expand Down
23 changes: 23 additions & 0 deletions doc/portability.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,29 @@ Qt code.
| `AxisTriad` | QML: x, y and z axes as red, green and blue cylinders |
| `StatusBadge` | QML: a toned label over the 3-D view, announced as an alert |

### Updates and issue reports — `ui/backend/qt/update`

`ui.backend.qt.update` lets a desktop tool update itself from its GitHub releases and open a prefilled
issue. It is built with the Qt backend and links Qt Core and Network only, no Widgets, so a tool draws its own
banner and dialogs. Nothing in it names a product: the caller passes the release feed URL, its user agent,
its current version, its issue page and its log file name. It is Qt-only because it is HTTP, files, processes and
JSON, which Qt already does on every desktop platform the tools ship on.

| Component | What it does |
|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `ReleaseVersion` | Parses and orders `vMAJOR.MINOR.PATCH` tags |
| `ReleaseFeed` | Reads a GitHub "latest release": its version, page, every asset downloadable over HTTPS with its SHA-256, and the installer for this platform |
| `UpdateChecker` | Fetches the feed and says whether a newer release exists |
| `UpdateDownloader` | Downloads an installer next to a `.part` file, checks its size and SHA-256, and refuses an asset without a published checksum or with a path |
| `UpdateInstallation` | Tells a packaged install from a portable one and builds the command that installs an update (`apt-get` through `pkexec`, or the NSIS setup) |
| `UpdateInstaller` | Runs that command and reports whether the tool must exit first |
| `UpdateSession` | Offer, download, install, cancel and dismiss as one state machine; `SetBlocked` holds the install back while the tool is busy with hardware |
| `IssueLog` | A rotating log file plus the recent lines in memory, optionally capturing Qt's own messages |
| `IssueReport` | Builds the new-issue URL with the product, version, platform and recent log, trimmed to fit a URL |
Comment on lines +81 to +91

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MegaLinter] reported by reviewdog 🐶

Suggested change
| Component | What it does |
|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `ReleaseVersion` | Parses and orders `vMAJOR.MINOR.PATCH` tags |
| `ReleaseFeed` | Reads a GitHub "latest release": its version, page, every asset downloadable over HTTPS with its SHA-256, and the installer for this platform |
| `UpdateChecker` | Fetches the feed and says whether a newer release exists |
| `UpdateDownloader` | Downloads an installer next to a `.part` file, checks its size and SHA-256, and refuses an asset without a published checksum or with a path |
| `UpdateInstallation` | Tells a packaged install from a portable one and builds the command that installs an update (`apt-get` through `pkexec`, or the NSIS setup) |
| `UpdateInstaller` | Runs that command and reports whether the tool must exit first |
| `UpdateSession` | Offer, download, install, cancel and dismiss as one state machine; `SetBlocked` holds the install back while the tool is busy with hardware |
| `IssueLog` | A rotating log file plus the recent lines in memory, optionally capturing Qt's own messages |
| `IssueReport` | Builds the new-issue URL with the product, version, platform and recent log, trimmed to fit a URL |
| Component | What it does |
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| `ReleaseVersion` | Parses and orders `vMAJOR.MINOR.PATCH` tags |
| `ReleaseFeed` | Reads a GitHub "latest release": its version, page, every asset downloadable over HTTPS with its SHA-256, and the installer for this platform |
| `UpdateChecker` | Fetches the feed and says whether a newer release exists |
| `UpdateDownloader` | Downloads an installer next to a `.part` file, checks its size and SHA-256, and refuses an asset without a published checksum or with a path |
| `UpdateInstallation` | Tells a packaged install from a portable one and builds the command that installs an update (`apt-get` through `pkexec`, or the NSIS setup) |
| `UpdateInstaller` | Runs that command and reports whether the tool must exit first |
| `UpdateSession` | Offer, download, install, cancel and dismiss as one state machine; `SetBlocked` holds the install back while the tool is busy with hardware |
| `IssueLog` | A rotating log file plus the recent lines in memory, optionally capturing Qt's own messages |
| `IssueReport` | Builds the new-issue URL with the product, version, platform and recent log, trimmed to fit a URL |


The installer asset is found by its name's suffix: `-linux-x86_64.deb` on Linux and `-windows-x86_64-setup.exe`
on Windows, so a release attaches one of each per tool.

## What degrades rather than breaks

Some input has no equivalent on a touch-first backend. `InputHandler` gives every event an empty
Expand Down
1 change: 1 addition & 0 deletions ui/backend/qt/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,4 @@ ui_add_library(ui.backend.qt QT
)

add_subdirectory(test)
add_subdirectory(update)
28 changes: 28 additions & 0 deletions ui/backend/qt/update/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
find_package(Qt6 6.2 REQUIRED COMPONENTS Core Network)

ui_add_library(ui.backend.qt.update QT
SOURCES
IssueLog.cpp
IssueLog.hpp
IssueReport.cpp
IssueReport.hpp
ReleaseFeed.cpp
ReleaseFeed.hpp
ReleaseVersion.cpp
ReleaseVersion.hpp
UpdateChecker.cpp
UpdateChecker.hpp
UpdateDownloader.cpp
UpdateDownloader.hpp
UpdateInstallation.cpp
UpdateInstallation.hpp
UpdateInstaller.cpp
UpdateInstaller.hpp
UpdateSession.cpp
UpdateSession.hpp
LINK
Qt6::Core
Qt6::Network
)

add_subdirectory(test)
167 changes: 167 additions & 0 deletions ui/backend/qt/update/IssueLog.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
#include "ui/backend/qt/update/IssueLog.hpp"
#include <QDateTime>
#include <QDir>
#include <algorithm>
#include <atomic>

namespace ui::backend::qt::update
{
namespace
{
struct Capture
{
std::atomic<IssueLog*> log{ nullptr };
QtMessageHandler previousHandler{ nullptr };
};

Capture& CaptureState()
{
constinit static Capture capture;
return capture;
}

bool& WritingOnThisThread()
{
constinit thread_local bool writing{ false };
return writing;
}

void ForwardQtMessage(QtMsgType type, const QMessageLogContext& context, const QString& message)
{
const auto& capture = CaptureState();
auto* log = capture.log.load();
if (log != nullptr && !WritingOnThisThread() && type != QtDebugMsg && type != QtInfoMsg)
log->Write(type == QtWarningMsg ? IssueSeverity::warning : IssueSeverity::error, "Qt: " + message);

if (capture.previousHandler != nullptr)
capture.previousHandler(type, context, message);
}
}

QString ToString(IssueSeverity severity)
{
switch (severity)
{
case IssueSeverity::warning:
return "WARN ";
case IssueSeverity::error:
return "ERROR";
default:
return "INFO ";
}
}

IssueLog::IssueLog(const Config& config)
: config(config)
{
this->config.keptFiles = std::max(this->config.keptFiles, 1);
QDir{}.mkpath(config.directory);
Open();
}

IssueLog::~IssueLog()
{
if (capturing)
{
auto& capture = CaptureState();
capture.log = nullptr;
qInstallMessageHandler(capture.previousHandler);
capture.previousHandler = nullptr;
}
}

void IssueLog::Write(IssueSeverity severity, const QString& message)
{
auto line = QString("%1 [%2] %3")
.arg(QDateTime::currentDateTimeUtc().toString(Qt::ISODateWithMs), ToString(severity), message.simplified());

std::scoped_lock lock{ mutex };
WritingOnThisThread() = true;
Remember(line);

if (file.isOpen())
RotateIfNeeded();

if (file.isOpen())
{
file.write(line.append('\n').toUtf8());
file.flush();
}

WritingOnThisThread() = false;
}

bool IssueLog::IsWritable() const
{
return file.isOpen();
}

QString IssueLog::FilePath() const
{
return RotatedPath(0);
}

QString IssueLog::Directory() const
{
return config.directory;
}

QStringList IssueLog::RecentLines(std::size_t count) const
{
std::scoped_lock lock{ mutex };
QStringList lines;
const auto skip = recent.size() > count ? recent.size() - count : 0;
for (auto it = recent.begin() + static_cast<std::ptrdiff_t>(skip); it != recent.end(); ++it)
lines.append(*it);
return lines;
}

void IssueLog::CaptureQtMessages()
{
auto& capture = CaptureState();
if (capturing || capture.log.load() != nullptr)
return;

capturing = true;
capture.previousHandler = qInstallMessageHandler(ForwardQtMessage);
capture.log = this;
}

QString IssueLog::RotatedPath(int index) const
{
const auto name = index == 0 ? QString("%1.log").arg(config.baseName) : QString("%1.%2.log").arg(config.baseName).arg(index);
return QDir{ config.directory }.filePath(name);
}

void IssueLog::Open()
{
file.setFileName(FilePath());
if (OpenForAppend())
RotateIfNeeded();
}

bool IssueLog::OpenForAppend()
{
return file.open(QIODevice::WriteOnly | QIODevice::Append | QIODevice::Text);
}

void IssueLog::RotateIfNeeded()
{
if (file.size() < config.maxFileBytes)
return;

file.close();
QFile::remove(RotatedPath(config.keptFiles - 1));
for (int index = config.keptFiles - 2; index >= 0; --index)
QFile::rename(RotatedPath(index), RotatedPath(index + 1));

OpenForAppend();
}

void IssueLog::Remember(const QString& line)
{
recent.push_back(line);
while (recent.size() > config.recentCapacity)
recent.pop_front();
}
}
62 changes: 62 additions & 0 deletions ui/backend/qt/update/IssueLog.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
#pragma once

#include <QFile>
#include <QString>
#include <QStringList>
#include <QtGlobal>
#include <cstddef>
#include <deque>
#include <mutex>

namespace ui::backend::qt::update
{
enum class IssueSeverity
{
info,
warning,
error
};

class IssueLog
{
public:
struct Config
{
QString directory;
QString baseName{ "application" };
qint64 maxFileBytes{ 1024 * 1024 };
int keptFiles{ 3 };
std::size_t recentCapacity{ 200 };
};

explicit IssueLog(const Config& config);
~IssueLog();

IssueLog(const IssueLog&) = delete;
IssueLog& operator=(const IssueLog&) = delete;

void Write(IssueSeverity severity, const QString& message);

bool IsWritable() const;
QString FilePath() const;
QString Directory() const;
QStringList RecentLines(std::size_t count) const;

void CaptureQtMessages();

private:
QString RotatedPath(int index) const;
void Open();
bool OpenForAppend();
void RotateIfNeeded();
void Remember(const QString& line);

Config config;
QFile file;
std::deque<QString> recent;
mutable std::mutex mutex;
bool capturing{ false };
};

QString ToString(IssueSeverity severity);
}
72 changes: 72 additions & 0 deletions ui/backend/qt/update/IssueReport.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
#include "ui/backend/qt/update/IssueReport.hpp"
#include <QDir>
#include <QSysInfo>
#include <QUrlQuery>

namespace ui::backend::qt::update
{
namespace
{
QString IssueBody(const IssueEnvironment& environment, const QStringList& logLines)
{
auto body = QString("### What happened?\n\n"
"<!-- What did you do, what did you expect, and what happened instead? -->\n\n"
"### Environment\n\n"
"| | |\n|---|---|\n"
"| %1 | %2 |\n"
"| Operating system | %3 |\n"
"| Architecture | %4 |\n"
"| Qt | %5 |\n\n")
.arg(environment.product.displayName, environment.applicationVersion, environment.operatingSystem, environment.cpuArchitecture, environment.qtVersion);

body += "### Recent log\n\n```text\n";
body += logLines.isEmpty() ? QString("(no entries)") : logLines.join('\n');
body += "\n```\n";

if (!environment.logFilePath.isEmpty())
body += QString("\nFull log: `%1` — attach it if more context helps.\n").arg(environment.logFilePath);

return body;
}

QString Encoded(const QString& text)
{
return QString::fromLatin1(QUrl::toPercentEncoding(text));
}

QUrl IssueUrl(const QUrl& newIssueUrl, const IssueEnvironment& environment, const QStringList& logLines)
{
QUrlQuery query;
query.addQueryItem("title", Encoded(QString("[%1] ").arg(environment.product.tag)));
query.addQueryItem("body", Encoded(IssueBody(environment, logLines)));

QUrl url{ newIssueUrl };
url.setQuery(query);
return url;
}
}

IssueEnvironment CurrentIssueEnvironment(const IssueProduct& product, const QString& applicationVersion, const QString& logFilePath)
{
auto shownPath = QDir::toNativeSeparators(logFilePath);
const auto home = QDir::toNativeSeparators(QDir::homePath());
if (!home.isEmpty() && shownPath.startsWith(home))
shownPath.replace(0, home.size(), "~");

return IssueEnvironment{ product, applicationVersion, QSysInfo::prettyProductName(), QSysInfo::currentCpuArchitecture(), QString::fromUtf8(qVersion()), shownPath };
}

QUrl BuildIssueUrl(const QUrl& newIssueUrl, const IssueEnvironment& environment, const QStringList& recentLog, int maxUrlLength)
{
auto lines = recentLog;
auto url = IssueUrl(newIssueUrl, environment, lines);

while (!lines.isEmpty() && url.toEncoded().size() > maxUrlLength)
{
lines.removeFirst();
url = IssueUrl(newIssueUrl, environment, lines);
}

return url;
}
}
Loading
Loading