KDE on Rebel Zhang のブログ

GammaRay を使って QtWidgets アプリケーション内の機能の実装箇所を見つける

rebel1725@tilde.club (Rebel Zhang) — Sun, 09 Aug 2026 20:49:33 +0800

フリーソフトウェアの自由 1 と自由 3 を実践したり、フリーソフトウェアコミュニティに貢献したりするには、ある機能に関連するソースコードを変更して、ソフトウェアに別の動作をさせる必要があります。しかし、私たちはプロジェクトに慣れていないため、変更すべきソースコードがどこにあるのか分からないことがよくあります。grep -R <some-user-facing-string> . を試してみてうまく見つかることもありますが、うまくいかない場合もあります（前回の記事を参照）。そのような場合には、高度なソフトウェア内省ツールが必要です。Qt で開発されたソフトウェアには、GammaRay という強力なユーティリティがあります。

GammaRay を使うには、まずインストールする必要があります。ディストリビューションの公式リポジトリからインストールしたソフトウェアを内省したい場合は、GammaRay もそこからインストールしてください。

# apt install gammaray

KDE アプリケーションの開発に kde-builder を使っている場合は、~/.config/kde-builder.yaml に次の行を追加します。

project gammaray:
  repository: https://github.com/KDAB/GammaRay.git

そして、作業ディレクトリにビルドします。

$ kde-builder gammaray

GammaRay を使うには、内省したいアプリケーションを起動しておく必要があります。次に GammaRay を起動し、一覧からアプリケーションを選びます。

例として、Gwenview のスライドショーのロジックを見つけてみましょう。Gwenview を開き、画像を開くと、メニューに Start Slideshow オプションが表示されます。

Widgets の一覧を一つずつ見ていくと、0x13bda470 が内省したいメニューであり、その中に Start Slideshow オプションが含まれていることが分かります。

そして、Connections タブに toggle_slideshow QAction があるのが見えます。

grep なら、そのような QAction がどこにあるのかを教えてくれます。

~/kde/src/gwenview$ grep -R toggle_slideshow
app/fullscreencontent.cpp:    addAction(QStringLiteral("toggle_slideshow"));
app/gwenviewui.rc:        <Action name="toggle_slideshow" />
app/mainwindow.cpp:        mToggleSlideShowAction = view->addAction(QStringLiteral("toggle_slideshow"), q, &MainWindow::toggleSlideShow);

お気に入りの IDE、たとえば Qt Creator でプロジェクトを開き、app/mainwindow.cpp 内の文字列を検索してください。ここで toggle_slideshow が見つかります。

        mToggleSlideShowAction = view->addAction(QStringLiteral("toggle_slideshow"), q, &MainWindow::toggleSlideShow);
        q->updateSlideShowAction();
        connect(mSlideShow, &SlideShow::stateChanged, q, &MainWindow::updateSlideShowAction);

次に toggleSlideShow を検索すると、この関数にたどり着きます。

void MainWindow::toggleSlideShow()
{
    if (d->mSlideShow->isRunning()) {
        d->mSlideShow->pause();
    } else {
        if (!d->mViewAction->isChecked()) {
            d->mViewAction->trigger();
        }
        if (!d->mFullScreenAction->isChecked()) {
            d->mFullScreenAction->trigger();
        }
        QList<QUrl> list;
        for (int pos = 0; pos < d->mDirModel->rowCount(); ++pos) {
            QModelIndex index = d->mDirModel->index(pos, 0);
            KFileItem item = d->mDirModel->itemForIndex(index);
            MimeTypeUtils::Kind kind = MimeTypeUtils::fileItemKind(item);
            switch (kind) {
            case MimeTypeUtils::KIND_SVG_IMAGE:
            case MimeTypeUtils::KIND_RASTER_IMAGE:
            case MimeTypeUtils::KIND_VIDEO:
                list << item.url();
                break;
            default:
                break;
            }
        }
        d->mSlideShow->start(list);
    }
    updateSlideShowAction();
}

続けて mSlideShow を検索すると、ここにたどり着きます。

struct MainWindow::Private {
    ...
    SlideShow *mSlideShow = nullptr;
    ...
}

これで d->mSlideShow の型が SlideShow * であることが分かります。SlideShow という文字列にマウスを重ねると、その型が lib/slideshow.h で提供されていることが分かります。

では、lib/slideshow.cpp と lib/slideshow.h を開いて、作業を進めましょう。

フリーソフトウェアコミュニティへの私の最初の一歩（既存プロジェクト）

rebel1725@tilde.club (Rebel Zhang) — Sun, 02 Aug 2026 23:18:30 +0800

ここ数日、私はフリーソフトウェアコミュニティから受けてきた恩恵に比べると、コミュニティへははるかに少ない貢献しかできていませんでした。これまでの貢献も、小さくてシンプルな個人プロジェクトや、コード以外の貢献（たとえばいくつかの翻訳、Debian Screenshots への数枚のスクリーンショットのアップロード、そして Free Software Chinese Site への記事執筆）に限られていました。この1年ほどで、私は C/C++、Qt、アセンブリ、そして少しの Rust を学びました。そろそろ、フリーソフトウェアコミュニティとフリーソフトウェア運動のために、意味のあることをする時だと思っています。

免責事項：これはガイドではありません！私は自分自身の経験を共有するためだけにこの記事を書いています。フリーソフトウェアコミュニティへの貢献方法をより詳しく知るには、関連する文書を参照し、専門家に相談してください。

KDE を選んだ理由

当初は postmarketOS への貢献を考えていました。しかし、自分のスキルが必要とされる水準にまったく届いていないと感じたため、比較的簡単なものから始めることにしました。私は C++ と Qt の方により親しみがあるので、コミュニティへの最初の貢献先として KDE を選びました。

気持ち

私のソースコード読解力はあまり高くありません。2025 年の初めごろ、PDF Arranger のソースコードを読もうとして、気分が悪くなるほど圧倒されました。

しかし、リバースエンジニアリングを学ぶという経験を通じて、アセンブリコードを読む必要があったおかげで、高水準言語のソースコードを読む力も向上しました。そのため、実際の環境で自分のスキルを鍛えるためにも、きちんとしたフリーソフトウェアへの貢献を試してみるべきだと思いました。

ソースツリーを開く前は少し緊張していて、PDF Arranger のソースを読んだときのように、またソースコードに圧倒されるのではないかと不安でした。しかし、友人の Integral の励ましのおかげで、その一歩を踏み出す勇気を持てました。

ツール

KDE が推奨する開発環境のひとつは、最新版の Fedora KDE です。私は Qubes OS を使っているので、スタンドアロンの HVM をすぐに立ち上げ、その中ですべての作業を行うのがとても簡単です。

その後、KDE 開発者向けの公式ドキュメントに従って kde-builder を設定しました。

作業

KDE の公式 Bugzilla にあるバグ一覧をざっと確認しました。とても簡単に修正できそうなバグに気づきましたが、ソースコードを取得してバイナリをビルドしたあと、最新バージョンの Ark では自分の環境でそのバグを再現できないことが分かりました。

そこで再びバグ一覧に戻ると、別のバグが目に留まりました。それはとても単純そうに見えました。バグ報告に書かれていたシステム環境とソフトウェアのバージョンは私と同じで（Fedora KDE、26.04）、Fedora の公式リポジトリで提供されているアプリケーションでも再現できました。それを確認したあと、ソースコードを取得してビルドしました。

~/kde/build/konsole/bin/konsole というバイナリに対して GDB を起動しました。バグ報告に記載されていた文字列（calt,liga,ss03, ss07,ss09）を入力欄に貼り付けると、コンソールに次の出力が表示されました。

The tag name must be exactly 4 characters long!

LLM と何度かやり取りした結果、GDB の Python スクリプトを使って、この警告を出力しているソースコード上の行を見つける方法を思いつきました。

python
import gdb

TARGET = b"The tag name must be exactly 4 characters long!"

class FilteredWrite(gdb.Breakpoint):
    def stop(self):
        fd = int(gdb.parse_and_eval("$rdi"))
        if fd not in (1, 2):
            return False

        buf = int(gdb.parse_and_eval("$rsi"))
        count = int(gdb.parse_and_eval("$rdx"))

        try:
            data = gdb.selected_inferior().read_memory(buf, count).tobytes()
        except gdb.MemoryError:
            return False

        if TARGET in data:
            gdb.write("\n=== matched output ===\n")
            gdb.write(data.decode("utf-8", "replace") + "\n")
            gdb.execute("bt full")
            return True

        return False

FilteredWrite("write")

GDB セッションのあと、この警告は kwidgetsaddons の kfontchooser.cpp から出されていることを確認しました。また、この警告を発生させている関数も見つけました。

void KFontChooserPrivate::slotFeaturesChanged(const QString &features)
{
    m_selectedFont.clearFeatures();

    if (features.isEmpty()) {
        return;
    }

    const QStringList rawFeaturesList = features.split(QLatin1Char(','), Qt::SkipEmptyParts);
    for (const QString &feature : rawFeaturesList) {
        auto f = QStringView(feature).trimmed();
        if (f.isEmpty()) {
            continue;
        }
        QList<QStringView> parts = f.split(QStringLiteral("="), Qt::SkipEmptyParts);
        if (parts.length() == 2) {
            const auto tag = QFont::Tag::fromString(parts[0]);
            bool ok = false;
            const int number = parts[1].toInt(&ok);
            if (tag.has_value() && ok) {
                m_selectedFont.setFeature(tag.value(), number);
            }
        } else if (f.size() <= 4) {
            const auto tag = QFont::Tag::fromString(feature);
            if (tag.has_value()) {
                m_selectedFont.setFeature(tag.value(), 1);
            }
        }
    }

    Q_EMIT q->fontSelected(m_selectedFont);
}

分割結果がトリミングされていることに気づきました。

auto f = QStringView(feature).trimmed();

しかし、元の、トリミングされていない文字列がそのまま tag として使われていました。

const auto tag = QFont::Tag::fromString(feature);

これは開発者のミスだと思われます。問題を修正するには、トリミングされていない文字列をトリミング済みのものに置き換えるだけで十分です。

const auto tag = QFont::Tag::fromString(f);

その後はブランチを作成し、そのブランチに変更をコミットして、マージリクエストを送る段階でした。しかし、Git の経験が限られていたため、次のような問題に遭遇しました。

warning: redirecting to https://invent.kde.org/rebellfs/kwidgetsaddons.git/
Enumerating objects: 21973, done.
Counting objects: 100% (21973/21973), done.
Delta compression using up to 4 threads
Compressing objects: 100% (2790/2790), done.
Writing objects: 100% (21973/21973), 41.17 MiB | ... KiB/s, done.
Total 21973 (delta 13428), reused 21374 (delta 12884), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (13428/13428), done.
remote: Audit failure - Commit 046e4bb16e60b66070ee4a00c368ca6924db3a08 - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit 046e4bb16e60b66070ee4a00c368ca6924db3a08 - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit c8c7ab3d0e7ca825bbb01d58de005d4d589b12cc - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit c8c7ab3d0e7ca825bbb01d58de005d4d589b12cc - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit 62e5736a1f4afc2d24ef2c4d643a98bc60e6d6cd - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit 62e5736a1f4afc2d24ef2c4d643a98bc60e6d6cd - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit f317243c63620acec15a46c412502e73b9a04e2a - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit f317243c63620acec15a46c412502e73b9a04e2a - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Push declined - commits failed audit
remote: Should the audit failures above mention issues regarding your name, please ensure that your Git username has been set to your full name.
remote: Please see https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup for more details on ensuring Git has been fully configured.
remote: In the event that your full name has been set and is shown above as being rejected, please file a Sysadmin ticket at https://go.kde.org/systickets
To https://invent.kde.org/rebellfs/kwidgetsaddons
! [remote rejected]     work/rebel1725/fix523757 -> work/rebel1725/fix523757 (pre-receive hook declined)
error: failed to push some refs to 'https://invent.kde.org/rebellfs/kwidgetsaddons'

最終的には、これは単一ファイルの些細な変更にすぎなかったため、ブラウザ経由でこの修正を提出しました。

結論

今日、私はフリーソフトウェアコミュニティへの最初の貢献を果たし、新たにフリーソフトウェアの貢献者にもなりました。今後は、もっと多く貢献し、自分の技術をさらに磨き、コミュニティとフリーソフトウェア運動により役立てるようになりたいと思っています。