Forem: fromthearchitect

Building GNOME Apps with Rust, Part 3: Your First App"

fromthearchitect — Mon, 04 May 2026 13:43:25 +0000

This is Part 3 of a series that takes a GNOME application from an empty directory to acceptance into GNOME Circle. Part 2 covered GObject's type system — properties, signals, and the inner/outer type pattern. Now we'll use everything we learned to build a real application.

From theory to a running window

In Part 2 we built a GObject subclass by hand — a Feed model with properties and signals, no GTK in sight. That was deliberate. Understanding GObject's inner/outer type split, the ObjectSubclass trait, and the mod imp pattern is the foundation that everything else rests on.

Now we're going to see those same patterns in context. By the end of this post, you'll have a running GTK4 + libadwaita application with a header bar, a menu, keyboard shortcuts, and a properly structured project that's ready for Flatpak packaging. And you won't have written most of it by hand — GNOME Builder will generate it for you. Our job is to understand what it generated and why.

Creating the project in GNOME Builder

Open GNOME Builder and click Create New Project. Fill in the dialog like this:

Project Name: gazette
Application ID: io.github.fromthearchitect.gazette
Location: wherever you keep your projects
Language: Rust
License: GPL-3.0-or-later
Version Control: enabled
Template: GNOME Application

Click Create Project.

A note on application IDs

The application ID is a reverse domain name that uniquely identifies your app across the entire Linux desktop. It's used for the D-Bus service name, the GSettings schema path, the desktop file name, the icon name, and the Flatpak bundle ID. Everything keys off this single string.

The convention is to use a domain you control. If you're publishing to a GitHub organisation, io.github.yourorg.yourapp is the standard pattern. If you own a domain, use it: dev.fromthearchitect.gazette would also work. The important thing is that this ID is globally unique and stable — changing it later means renaming dozens of files and updating every reference.

Hit Run

Before we look at any code, hit the Run button (the play icon in the header bar) or press Ctrl+F5. Builder will configure the Flatpak environment, download the SDK if needed, compile the Rust code, bundle the resources, and launch the application.

The first build takes a while — Cargo is downloading and compiling every dependency inside the Flatpak sandbox. Subsequent builds are much faster thanks to caching.

When it finishes, you'll see this:

A window. A header bar with a title. A hamburger menu with Preferences, Keyboard Shortcuts, and About entries. A "Hello, World!" label in the centre. That's your application.

It doesn't look like much yet, but there's a surprising amount happening behind the scenes. Let's look at what Builder actually created.

The project structure

Here's what Builder generated:

gazette/
├── Cargo.toml
├── COPYING
├── meson.build
├── io.github.fromthearchitect.gazette.json
├── data/
│   ├── meson.build
│   ├── icons/
│   │   ├── meson.build
│   │   ├── hicolor/scalable/apps/
│   │   │   └── io.github.fromthearchitect.gazette.svg
│   │   └── hicolor/symbolic/apps/
│   │       └── io.github.fromthearchitect.gazette-symbolic.svg
│   ├── io.github.fromthearchitect.gazette.desktop.in
│   ├── io.github.fromthearchitect.gazette.gschema.xml
│   ├── io.github.fromthearchitect.gazette.metainfo.xml.in
│   └── io.github.fromthearchitect.gazette.service.in
├── po/
│   ├── LINGUAS
│   ├── POTFILES.in
│   └── meson.build
└── src/
    ├── meson.build
    ├── main.rs
    ├── application.rs
    ├── config.rs.in
    ├── window.rs
    ├── window.ui
    ├── shortcuts-dialog.ui
    └── gazette.gresource.xml

That's a lot of files for "Hello, World!" — and every single one of them is there for a reason. Here's what's in each group.

The Rust source code

main.rs — the entry point

mod application;
mod config;
mod window;

use self::application::GazetteApplication;
use self::window::GazetteWindow;

use config::{GETTEXT_PACKAGE, LOCALEDIR, PKGDATADIR};
use gettextrs::{bind_textdomain_codeset, bindtextdomain, textdomain};
use gtk::{gio, glib};
use gtk::prelude::*;

fn main() -> glib::ExitCode {
    // Set up gettext translations
    bindtextdomain(GETTEXT_PACKAGE, LOCALEDIR)
        .expect("Unable to bind the text domain");
    bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8")
        .expect("Unable to set the text domain encoding");
    textdomain(GETTEXT_PACKAGE)
        .expect("Unable to switch to the text domain");

    // Load resources
    let resources = gio::Resource::load(
        PKGDATADIR.to_owned() + "/gazette.gresource"
    ).expect("Could not load resources");
    gio::resources_register(&resources);

    let app = GazetteApplication::new(
        "io.github.fromthearchitect.gazette",
        &gio::ApplicationFlags::empty(),
    );

    app.run()
}

Three things happen here before the application starts:

Gettext initialisation. This wires up the translation system so that strings marked as translatable in the UI files and source code can be looked up in the user's language. Even if you never translate your app, the plumbing needs to be in place.
Resource loading. The compiled GResource bundle (containing the UI templates, icons, and other assets) is loaded from disk and registered globally. After this call, any code can access bundled files by their resource path — for example, /io/github/fromthearchitect/gazette/window.ui.
Application creation and run. GazetteApplication::new() creates our application object, and app.run() hands control to the GLib main loop. The main loop processes events — user input, window management, D-Bus messages — until the application quits.

The config module isn't a regular Rust file — it's generated at build time by Meson from a template. More on that shortly.

application.rs — the GtkApplication subclass

This is where you'll recognise the GObject patterns from Part 2:

use gettextrs::gettext;
use adw::prelude::*;
use adw::subclass::prelude::*;
use gtk::{gio, glib};

use crate::config::VERSION;
use crate::GazetteWindow;

mod imp {
    use super::*;

    #[derive(Debug, Default)]
    pub struct GazetteApplication {}

    #[glib::object_subclass]
    impl ObjectSubclass for GazetteApplication {
        const NAME: &'static str = "GazetteApplication";
        type Type = super::GazetteApplication;
        type ParentType = adw::Application;
    }

    impl ObjectImpl for GazetteApplication {
        fn constructed(&self) {
            self.parent_constructed();
            let obj = self.obj();
            obj.setup_gactions();
            obj.set_accels_for_action("app.quit", &["<control>q"]);
        }
    }

    impl ApplicationImpl for GazetteApplication {
        fn activate(&self) {
            let application = self.obj();
            let window = application.active_window().unwrap_or_else(|| {
                let window = GazetteWindow::new(&*application);
                window.upcast()
            });
            window.present();
        }
    }

    impl GtkApplicationImpl for GazetteApplication {}
    impl AdwApplicationImpl for GazetteApplication {}
}

glib::wrapper! {
    pub struct GazetteApplication(ObjectSubclass<imp::GazetteApplication>)
        @extends gio::Application, gtk::Application, adw::Application,
        @implements gio::ActionGroup, gio::ActionMap;
}

Same pattern as Part 2's Feed: an inner type in mod imp that holds the state, ObjectSubclass to register it with GObject, and a glib::wrapper! macro to create the outer type. The difference is what we're subclassing — adw::Application instead of glib::Object — and the trait implementations that come with it.

ObjectImpl::constructed is called once when the application is first created. It's the place to set up actions and keyboard shortcuts. This is analogous to a constructor, but in GObject-land, construction happens in phases — constructed runs after all properties have been set.

ApplicationImpl::activate is the most important callback. It's called when the application is launched (or when the user tries to open a second instance). The pattern here is standard: check if there's already a window, create one if there isn't, and present it. This is how GNOME apps implement single-instance behaviour — the platform enforces one running instance per application ID, and subsequent launches just activate the existing one.

The impl GtkApplicationImpl and impl AdwApplicationImpl lines are empty but required. They tell the GObject type system that we're implementing the full trait chain from gio::Application through gtk::Application to adw::Application. If you leave one out, you'll get a compile error.

Further down in the file, there's the actions setup and the About dialog:

impl GazetteApplication {
    pub fn new(application_id: &str, flags: &gio::ApplicationFlags) -> Self {
        glib::Object::builder()
            .property("application-id", application_id)
            .property("flags", flags)
            .property("resource-base-path",
                       "/io/github/fromthearchitect/gazette")
            .build()
    }

    fn setup_gactions(&self) {
        let quit_action = gio::ActionEntry::builder("quit")
            .activate(move |app: &Self, _, _| app.quit())
            .build();
        let about_action = gio::ActionEntry::builder("about")
            .activate(move |app: &Self, _, _| app.show_about())
            .build();
        self.add_action_entries([quit_action, about_action]);
    }

    fn show_about(&self) {
        let window = self.active_window().unwrap();
        let about = adw::AboutDialog::builder()
            .application_name("Gazette")
            .application_icon("io.github.fromthearchitect.gazette")
            .developer_name("Unknown")
            .version(VERSION)
            .developers(vec!["Unknown"])
            .translator_credits(&gettext("translator-credits"))
            .copyright("© 2026 Unknown")
            .build();

        about.present(Some(&window));
    }
}

Notice the placeholder values — developer_name("Unknown"), developers(vec!["Unknown"]), copyright("© 2026 Unknown"). Builder generates these as placeholders. Replace them with your actual name before publishing your app.

GActions are GNOME's action system. Instead of connecting button clicks directly to functions, you define named actions (app.quit, app.about) and connect UI elements to those names. The menu items in the UI template reference app.about — the action system routes that to show_about(). This decoupling means you can trigger the same action from a menu, a keyboard shortcut, a command-line argument, or a D-Bus message.

The resource-base-path property tells the application where to look for automatically loaded resources. When we set it to /io/github/fromthearchitect/gazette, the application will automatically load the shortcuts dialog from that path without us doing anything extra.

window.rs — the application window

use gtk::prelude::*;
use adw::subclass::prelude::*;
use gtk::{gio, glib};

mod imp {
    use super::*;

    #[derive(Debug, Default, gtk::CompositeTemplate)]
    #[template(resource = "/io/github/fromthearchitect/gazette/window.ui")]
    pub struct GazetteWindow {
        #[template_child]
        pub label: TemplateChild<gtk::Label>,
    }

    #[glib::object_subclass]
    impl ObjectSubclass for GazetteWindow {
        const NAME: &'static str = "GazetteWindow";
        type Type = super::GazetteWindow;
        type ParentType = adw::ApplicationWindow;

        fn class_init(klass: &mut Self::Class) {
            klass.bind_template();
        }

        fn instance_init(obj: &glib::subclass::InitializingObject<Self>) {
            obj.init_template();
        }
    }

    impl ObjectImpl for GazetteWindow {}
    impl WidgetImpl for GazetteWindow {}
    impl WindowImpl for GazetteWindow {}
    impl ApplicationWindowImpl for GazetteWindow {}
    impl AdwApplicationWindowImpl for GazetteWindow {}
}

glib::wrapper! {
    pub struct GazetteWindow(ObjectSubclass<imp::GazetteWindow>)
        @extends gtk::Widget, gtk::Window, gtk::ApplicationWindow,
                 adw::ApplicationWindow,
        @implements gio::ActionGroup, gio::ActionMap;
}

impl GazetteWindow {
    pub fn new<P: IsA<gtk::Application>>(application: &P) -> Self {
        glib::Object::builder()
            .property("application", application)
            .build()
    }
}

The @implements list above is truncated for readability — the actual generated code also includes gtk::Accessible, gtk::Buildable, gtk::ConstraintTarget, gtk::Native, gtk::Root, gtk::ShortcutManager. See the source on the part-3 branch for the full version.

This introduces two new concepts: composite templates and the widget trait chain.

#[derive(gtk::CompositeTemplate)] connects this Rust struct to a UI definition file. The #[template(resource = "...")] attribute tells GTK where to find the template, and #[template_child] fields create typed references to named widgets in that template. Here, self.label gives us direct access to the GtkLabel widget with id="label" defined in the UI file.

The class_init and instance_init functions bind the template at the class level (once) and initialise it for each instance. This is boilerplate that every composite template widget needs.

The trait chain — WidgetImpl, WindowImpl, ApplicationWindowImpl, AdwApplicationWindowImpl — reflects the GTK class hierarchy. AdwApplicationWindow extends gtk::ApplicationWindow, which extends gtk::Window, which extends gtk::Widget. Each level of the hierarchy can override behaviour. For now, all these implementations are empty, but they must be present.

The UI template

window.ui

<?xml version="1.0" encoding="UTF-8"?>
<interface>
  <requires lib="gtk" version="4.0"/>
  <requires lib="Adw" version="1.0"/>
  <template class="GazetteWindow" parent="AdwApplicationWindow">
    <property name="title" translatable="yes">Gazette</property>
    <property name="default-width">800</property>
    <property name="default-height">600</property>
    <property name="content">
      <object class="AdwToolbarView">
        <child type="top">
          <object class="AdwHeaderBar">
            <child type="end">
              <object class="GtkMenuButton">
                <property name="primary">True</property>
                <property name="icon-name">open-menu-symbolic</property>
                <property name="tooltip-text"
                          translatable="yes">Main Menu</property>
                <property name="menu-model">primary_menu</property>
              </object>
            </child>
          </object>
        </child>
        <property name="content">
          <object class="GtkLabel" id="label">
            <property name="label"
                      translatable="yes">Hello, World!</property>
            <style>
              <class name="title-1"/>
            </style>
          </object>
        </property>
      </object>
    </property>
  </template>
  <menu id="primary_menu">
    <section>
      <item>
        <attribute name="label"
                   translatable="yes">_Preferences</attribute>
        <attribute name="action">app.preferences</attribute>
      </item>
      <item>
        <attribute name="label"
                   translatable="yes">_Keyboard Shortcuts</attribute>
        <attribute name="action">app.shortcuts</attribute>
      </item>
      <item>
        <attribute name="label"
                   translatable="yes">_About Gazette</attribute>
        <attribute name="action">app.about</attribute>
      </item>
    </section>
  </menu>
</interface>

This is GTK's XML-based UI definition format.

The <template> element defines a composite template — it's bound to the GazetteWindow class we defined in Rust. The parent attribute must match the ParentType in our ObjectSubclass implementation.

The widget hierarchy is:

AdwToolbarView — a libadwaita container that manages header bars and content areas
- AdwHeaderBar (top) — the standard GNOME header bar with the window title and controls
- GtkMenuButton — the hamburger menu button in the top-right corner
- GtkLabel (content) — our "Hello, World!" text

The <menu> element defines the hamburger menu model. Each item has a label (the _ prefix marks the keyboard accelerator character) and an action name. The app.about entry maps back to the action we defined in application.rs. The app.preferences action isn't connected yet — clicking it does nothing. The app.shortcuts action, however, already works: GTK automatically loads shortcuts-dialog.ui from the resource base path we set in application.rs. We'll wire up preferences in a later post.

The translatable="yes" attribute on strings marks them for extraction by gettext. Even if you don't plan to translate your app initially, marking strings as translatable from the start saves you from a painful retrofit later.

In Part 4, we'll convert this XML template to Blueprint, which is dramatically more readable. But it's worth understanding the XML format first, since Blueprint compiles to it — and when things go wrong, the error messages reference XML structures.

The build system

GNOME apps don't use Cargo as the top-level build system. They use Meson. Cargo still compiles the Rust code, but Meson orchestrates everything else — and there's a lot of "everything else" in a GNOME app.

Root meson.build

project('gazette', 'rust',
          version: '0.1.0',
    meson_version: '>= 1.0.0',
  default_options: [ 'warning_level=2', 'werror=false', ],
)

i18n = import('i18n')
gnome = import('gnome')

subdir('data')
subdir('src')
subdir('po')

gnome.post_install(
     glib_compile_schemas: true,
    gtk_update_icon_cache: true,
  update_desktop_database: true,
)

The root build file declares the project, imports the i18n and gnome Meson modules, and includes three subdirectories. The post_install block runs after installation to compile GSettings schemas, update the icon cache, and refresh the desktop file database. These are standard GNOME post-install steps — without them, your app's icon won't appear in the application launcher and your settings won't be accessible.

src/meson.build — where Rust meets Meson

pkgdatadir = get_option('prefix') / get_option('datadir') / meson.project_name()
gnome = import('gnome')

gnome.compile_resources('gazette',
  'gazette.gresource.xml',
  gresource_bundle: true,
  install: true,
  install_dir: pkgdatadir,
)

conf = configuration_data()
conf.set_quoted('VERSION', meson.project_version())
conf.set_quoted('GETTEXT_PACKAGE', 'gazette')
conf.set_quoted('LOCALEDIR', get_option('prefix') / get_option('localedir'))
conf.set_quoted('PKGDATADIR', pkgdatadir)

configure_file(
    input: 'config.rs.in',
    output: 'config.rs',
    configuration: conf
)

Here's what it handles:

Compiles GResources. The gazette.gresource.xml manifest lists the UI files and other assets that should be bundled. Meson compiles them into a single binary blob (gazette.gresource) and installs it alongside the binary.
Generates config.rs. The config.rs.in template contains placeholders like @VERSION@ and @PKGDATADIR@. Meson replaces them with real values at build time. This is how the Rust code knows where to find its installed resources — the paths are baked in at compile time.
Invokes Cargo. Further down in the file, Meson runs cargo build with the right flags and copies the resulting binary to the install location.

gazette.gresource.xml

<?xml version="1.0" encoding="UTF-8"?>
<gresources>
  <gresource prefix="/io/github/fromthearchitect/gazette">
    <file preprocess="xml-stripblanks">window.ui</file>
    <file preprocess="xml-stripblanks">shortcuts-dialog.ui</file>
  </gresource>
</gresources>

This manifest lists every file that should be compiled into the GResource bundle. The prefix attribute defines the virtual path — when our window template asks for /io/github/fromthearchitect/gazette/window.ui, it's loading from this bundle, not from the filesystem. The xml-stripblanks flag tells Meson to strip whitespace from the XML before bundling. It makes no real difference for an app this size, but it's standard practice and every GNOME app does it.

Whenever you add a new UI file, icon, or CSS stylesheet, it needs to be listed here.

Desktop integration files

The data/ directory contains files that integrate your application with the Linux desktop. None of these are specific to GNOME or GTK — they're freedesktop.org standards used across all Linux desktop environments.

Desktop file

[Desktop Entry]
Name=Gazette
Exec=gazette
Icon=io.github.fromthearchitect.gazette
Terminal=false
Type=Application
Categories=Utility;
Keywords=GTK;
StartupNotify=true
DBusActivatable=true

This tells the desktop environment how to launch your app, what icon to display, and what category to put it in. The .in suffix on the source file means Meson processes it through gettext to produce translated versions.

DBusActivatable=true means the app can be launched via D-Bus, which enables the single-instance behaviour we saw in application.rs.

GSettings schema

<schemalist gettext-domain="gazette">
  <schema id="io.github.fromthearchitect.gazette"
          path="/io/github/fromthearchitect/gazette/">
  </schema>
</schemalist>

GSettings is GNOME's configuration system — think of it as a typed key-value store for application preferences. The schema is empty now, but when we add user preferences (feed refresh interval, dark mode preference, etc.), this is where we'll define them.

AppStream metadata

The metainfo file is what Flathub and GNOME Software actually read when they display your app. Get it wrong and your app looks abandoned regardless of how polished the code is. Builder generated a placeholder — we'll fill it in properly when we prepare for Flathub submission in Part 9.

D-Bus service file

[D-BUS Service]
Name=io.github.fromthearchitect.gazette
Exec=@bindir@/gazette --gapplication-service

This tells D-Bus how to activate your application on demand. The @bindir@ placeholder is replaced by Meson at build time with the actual installation path.

The Flatpak manifest

{
    "id" : "io.github.fromthearchitect.gazette",
    "runtime" : "org.gnome.Platform",
    "runtime-version" : "48",
    "sdk" : "org.gnome.Sdk",
    "sdk-extensions" : [
        "org.freedesktop.Sdk.Extension.rust-stable"
    ],
    "command" : "gazette",
    "finish-args" : [
        "--share=network",
        "--share=ipc",
        "--socket=fallback-x11",
        "--device=dri",
        "--socket=wayland"
    ],
    ...
}

This defines how to build and sandbox the application as a Flatpak. The key fields:

runtime and runtime-version: The GNOME platform libraries your app links against at runtime. Version 48 corresponds to GNOME 48.
sdk: The matching SDK used at build time, which includes header files and development tools.
sdk-extensions: Additional SDK components — here, the Rust toolchain.
finish-args: The sandbox permissions your app needs. Network access, Wayland display, GPU acceleration. Every permission you add here needs to be justified when you submit to Flathub. You might wonder why an RSS reader needs --device=dri — GTK4 uses GPU-accelerated rendering by default, so it's a legitimate permission for virtually any GTK4 app.

Upgrading to the GNOME 50 platform

Builder generated this project against GNOME 48 — that's what the current template targets. But in Part 1, we installed the GNOME 50 SDK. Let's upgrade the Rust crates and Flatpak runtime to match.

Three files need changes:

1. Cargo.toml — Rust crate versions

The generated Cargo.toml uses gtk4 0.9 and libadwaita 0.7:

[dependencies]
gettext-rs = { version = "0.7", features = ["gettext-system"] }
gtk = { version = "0.9", package = "gtk4", features = ["gnome_47"] }

[dependencies.adw]
package = "libadwaita"
version = "0.7"
features = ["v1_6"]

Update it to the latest versions:

[dependencies]
gettext-rs = { version = "0.7", features = ["gettext-system"] }
gtk = { version = "0.11", package = "gtk4", features = ["gnome_50"] }
adw = { version = "0.9", package = "libadwaita", features = ["v1_9"] }

The version numbers here are the Rust crate versions, not the GTK version. gtk4 crate 0.11 wraps GTK 4.18, and libadwaita crate 0.9 wraps libadwaita 1.9. The gnome_50 feature flag is a convenience flag that enables all the version-specific API features matching the GNOME 50 SDK — it saves you from having to figure out which individual v4_xx flags correspond to which GNOME release.

2. Flatpak manifest — runtime version

In io.github.fromthearchitect.gazette.json, update the runtime version:

{
    "runtime-version" : "50",
}

This tells Flatpak to use the GNOME 50 runtime and SDK when building and running your app.

3. Rebuild

Hit Run in Builder again. Builder will download the GNOME 50 SDK if it's not already installed, rebuild the project against the new dependencies, and launch the app. If everything compiles and runs — and it should, since we haven't used any version-specific APIs yet — you're on the latest platform.

This kind of version bump is something you'll do roughly every six months as GNOME releases new platform versions. Getting comfortable with it now means it's routine rather than stressful later.

What we have so far

The thing that takes longest to internalise when you start GNOME development is how much of this is not GTK. The desktop file, the D-Bus service, the AppStream metadata, GSettings — these are platform concerns, not application concerns. Builder stitches them all together, but you need to know what they are and why they exist, or you'll never debug a broken Flatpak submission.

The application ID is the load-bearing string across all of it. It ties the desktop file to the D-Bus service to the GSettings schema to the Flatpak bundle. Getting this scaffolding right by hand would take hours of cross-referencing documentation. Builder gives it to you in thirty seconds.

What comes next

We've got a running app, but the UI is still "Hello, World!". Before we start building the actual RSS reader interface, we need a better way to describe user interfaces than raw XML.

In Part 4, we'll introduce Blueprint — a markup language that compiles to GTK's UI XML but is dramatically more readable. We'll convert the generated window template to Blueprint, build the initial Gazette layout with a sidebar and content pane, and start making it look like a real application.

The source code at the end of this post lives on the part-3 branch of fromthearchitect/gnome-rust-gazette. Subsequent posts in this series build on the same repo, with a branch per part.

Making a Dumb Fridge Smart

fromthearchitect — Sun, 03 May 2026 11:20:00 +0000

There's about $400 of meat, milk, and miscellaneous condiments in my kitchen fridge at any given time. It runs 24/7, makes a quiet humming noise, and gives no indication when something's wrong until you open the door three days later and recoil. The freezer compartment is worse: a slow failure can defrost everything before you notice the puddle.

I already had a TP-Link P110 smart plug on the fridge — originally for energy monitoring, because I'm on a spot-priced electricity tariff and I like knowing what each appliance costs me. But the same wattage stream that tells you "the fridge used 1.4 kWh today" tells you almost everything you need to know about whether the fridge is healthy.

The signal

The P110 reports sensor.fridge_current_consumption in watts, updating every ~5 seconds (the current tplink integration default). A typical fridge has two power states:

Standby — 1 to 3 W. Everything dark, compressor off, just the controller and a sensor or two.
Compressor running — 50 to 200 W, depending on age and ambient temperature.

If you imagine that as a graph, you get a square wave: long flats near zero, periodic blocks at ~120 W, repeating every 30–60 minutes. Almost everything interesting about the fridge — door open, seal failing, mechanical struggle, total failure — shows up as a deformation of that square wave.

The first thing to build is a binary sensor that tracks compressor on/off.

Step one: detecting the compressor cycle (with hysteresis)

The naive version is "compressor is on if watts > 30." This breaks immediately, because the wattage can hover within a few watts of any threshold you pick, flapping the sensor on and off ten times a second. You need hysteresis: a high threshold to turn on, a lower threshold to turn off.

Home Assistant ships a binary_sensor platform called threshold that does upper/lower bounds with hysteresis in three lines of YAML. It's the obvious tool for this job, and for a long time it was what I would have reached for. I don't anymore, for three reasons.

It can't have a unique_id. platform: threshold predates the entity registry and was never updated to support it. That means the entity it produces lives outside the registry — you can't rename it from the UI, can't apply labels, can't hide it from a dashboard cleanly, and tools like Spook that operate on registry entities can't see it. In a config where every other YAML-defined entity is registry-managed, having one or two threshold sensors floating outside that system is a constant small irritation.

It can't propagate unavailable. When the source sensor goes unavailable, platform: threshold evaluates against a missing value and the result is unhelpful — usually it sticks at its last state. A template sensor with an explicit availability: block bubbles the unknown state through, which is what every downstream alert and history-stats sensor actually wants.

The hysteresis you can express is limited. platform: threshold gives you one upper bound and one lower bound. The self-referential template pattern lets the thresholds be anything you can compute — different in summer vs. winter, different by time of day, different depending on whether another appliance is also drawing power. You almost never need that flexibility, but on the day you do, you don't have to rewrite the sensor.

So instead I use a template: binary_sensor that references its own state. It's six more lines than the threshold version. For a sensor I'm going to depend on for years, that's a trade I'll happily make every time.

template:
  - binary_sensor:
      - name: "Fridge Compressor Running"
        unique_id: 2236e0fe-63a0-4d11-b6a0-c0efd94d5f69
        device_class: running
        availability: >
          {{ states('sensor.fridge_current_consumption')
             not in ['unknown', 'unavailable', 'none'] }}
        state: >
          {% set w = states('sensor.fridge_current_consumption') | float(0) %}
          {% if is_state('binary_sensor.fridge_compressor_running', 'on') %}
            {{ w > 10 }}
          {% else %}
            {{ w > 20 }}
          {% endif %}

The availability block matters: if the smart plug loses Wi-Fi or the integration glitches, states(...) returns 'unavailable', and | float(0) would silently turn that into "compressor is off" — exactly the wrong story to tell. Marking the sensor itself unavailable when its source is unavailable propagates the unknown state through everything downstream instead of papering over it with zeros.

The state block self-references: binary_sensor.fridge_compressor_running reads its own current state to decide which threshold to apply. The HA template engine is fine with this — it just uses the previous state from before this evaluation. On startup, with no prior state to read, the template falls through to the "currently off" branch and uses the higher 20 W threshold — the safe direction to fail.

This binary sensor is the foundation. Everything that follows is built on it.

Step two: rolling-window aggregations

Two history_stats sensors derive the shape:

sensor:
  - platform: history_stats
    name: "Fridge Compressor Duty 6h"
    entity_id: binary_sensor.fridge_compressor_running
    state: "on"
    type: ratio
    duration: { hours: 6 }
    end: "{{ now() }}"

  - platform: history_stats
    name: "Fridge Compressor Cycle 6h"
    entity_id: binary_sensor.fridge_compressor_running
    state: "on"
    type: count
    duration: { hours: 6 }
    end: "{{ now() }}"

type: ratio gives me a percentage: "the compressor was on 32 % of the last six hours." type: count gives me a cycle count: "the compressor turned on 8 times in the last six hours." Together, those two numbers describe the shape of the duty cycle — and the shape is what the alerts key off.

history_stats and statistics sensors reload via homeassistant.reload_all (or their own history_stats.reload / statistics.reload services) most of the time. I've occasionally hit cases where a brand-new sensor wouldn't appear in the entity registry until after a full HA restart — if reload_all returns success but the entity never shows up, that's the next thing to try.

Step three: the three alerts

All three are binary_sensor entities with device_class: problem, which makes them render as "OK / Problem" in the UI. The convention I use across the house is: the binary sensor is the signal, a separate automation is the action. Notification logic, cooldowns, channel routing — all of that lives in automations subscribed to these entities, and the alert sensors themselves stay declarative.

Alert 1: Fridge offline

- name: "Alert: Fridge offline"
  device_class: problem
  delay_on: "00:02:00"
  state: >
    {{ states('switch.fridge') in ['off', 'unavailable', 'unknown', 'none'] }}

Either the smart plug lost comms, or the fridge lost mains power. The two-minute delay_on filters out the brief blips that happen when the broker reconnects or the plug reboots itself.

Alert 2: Fridge stuck on

- name: "Alert: Fridge stuck on"
  device_class: problem
  state: >
    {% set duty = states('sensor.fridge_compressor_duty_6h') | float(0) %}
    {% set cyc  = states('sensor.fridge_compressor_cycle_6h') | int(0) %}
    {{ duty > 85 and cyc < 3 }}

This is the interesting one. A healthy fridge cycles: maybe 8–15 times in 6 hours, with the compressor on perhaps 25–40 % of the time. High duty plus low cycle count is a specific failure shape — the compressor is running almost continuously without ever satisfying the thermostat. That's either a thermostat fault, a refrigerant problem, or a seal so bad the compressor can't keep up. Distinguishing it from "it's just a hot day" is exactly what the cycle-count condition does: a hot-day fridge still cycles, just more often.

Alert 3: Fridge door open

template:
  - trigger:
      - platform: state
        entity_id: binary_sensor.fridge_compressor_running
        to: "on"
        for: "00:45:00"
        id: alert_on
      - platform: state
        entity_id: binary_sensor.fridge_compressor_running
        to: "off"
        id: alert_off
    binary_sensor:
      - name: "Alert: Fridge door open"
        device_class: problem
        state: "{{ trigger.id == 'alert_on' }}"

A single compressor run longer than 45 minutes almost always means the door is ajar — the compressor can't pull the temperature down because warm air keeps coming in.

This one is structured as a trigger-based template binary sensor, not a regular state-based one with delay_on. Two reasons:

delay_on leaves the sensor in unknown if its template evaluates true at HA startup, until the next state change. A trigger-based sensor has a clean state machine.
Templates that look at last_changed and now() don't re-evaluate on a clock — they only re-evaluate when one of the entities they reference changes state. A trigger-based template wakes up on a time-bounded state change (to: "on" for: "00:45:00"), which is exactly the right shape for "this condition has been true continuously for X."

This pattern shows up everywhere once you start looking for it: laundry left running, garage door open, lights on with no motion. Memorise it.

Bonus: the alerts gave me cost tracking for free

Once you have a wattage stream and a binary "is it running" sensor, multiplying watts by the live spot price gives you instantaneous dollars per hour. (My $/kWh sensor comes from cabberley/amber2mqtt, a community bridge that polls Amber Electric's API and republishes 5-minute spot prices to my Mosquitto broker. The official Amber HA integration would do the same job, with minor entity-name changes.) Feed that into a Riemann-sum integration sensor and you have cumulative dollars. Wrap it in a utility_meter and you get daily and monthly totals that reset on schedule.

- platform: integration
  name: "Fridge Cost Total"
  source: sensor.fridge_cost_rate
  unit_time: h
  method: left   # left-Riemann: correct for step-function spot prices
  round: 4

utility_meter:
  fridge_cost_today:
    source: sensor.fridge_cost_total
    cycle: daily
  fridge_cost_month:
    source: sensor.fridge_cost_total
    cycle: monthly

The method: left matters: spot prices are step functions (they hold a value for 5 minutes, then jump), and left-Riemann sums them correctly. Trapezoidal would smear the jumps and give you slightly wrong numbers.

The fridge runs me about $3.20 a month at current prices.

What it has actually caught

In the months since deploying this:

The "fridge offline" alert fires occasionally when the IoT VLAN has a hiccup. Two-minute delay_on filters most of it; what remains is genuinely useful.
The "door open" alert has fired three times. All three were genuinely ajar doors.
"Stuck on" has not fired. My fridge is fine and the alert is correctly silent.

The point of monitoring isn't to generate notifications — it's to give you confidence that the absence of a notification means something.

The general pattern

This whole thing — power signal → derived running state → rolling windows → behaviour-shaped alerts — generalises. I have the same skeleton on the dishwasher, washing machine, and dryer, each with appliance-specific thresholds. Anything that draws meaningful power and has a "is it doing its job" question worth answering is a candidate.

The cost is one smart plug and a few hundred lines of YAML. The benefit is silent confidence that, when something does fail, you'll know within minutes — not when the smell hits you.

Setup notes: Home Assistant 2026.x, TP-Link P110 via the Kasa integration, MQTT broker for Amber Electric pricing data. Full YAML available on request.

Building GNOME Apps with Rust, Part 2: GObject in Rust — The Type System Explained

fromthearchitect — Sun, 12 Apr 2026 22:27:00 +0000

This is Part 2 of a series taking a GNOME app from an empty directory to GNOME Circle. Part 1 covered the why and the dev environment.

The app we're building

Throughout this series, we'll be building Gazette — an RSS reader. I picked it because it naturally exercises every pattern a non-trivial GNOME app needs: networking, data persistence, list/detail UI, adaptive layouts, settings, and state management. You don't need to build an RSS reader to follow along — the patterns are universal.

But before we touch GTK, before we create a window or a header bar, we need to understand the type system that everything in GNOME is built on — GObject. Every hour you spend on it before touching widgets will save you two hours of confusion when your property binding silently doesn't work or your signal callback never fires.

What is GObject and why should you care

Every widget in GTK is a GObject. That sounds like a detail you can safely skip. It isn't — it explains why property bindings work the way they do, why signals don't need explicit subscriber lists, and why half the confusion I see in gtk-rs questions comes from not knowing this layer exists.

GObject gives C what it was never designed to have: objects. You get inheritance, properties that can be observed and bound, a signal system for decoupled events, and reference counting. All achieved through C macros and conventions, which is exactly as readable as it sounds.

The challenge for Rust developers is that these two type systems have fundamentally different ideas about ownership. Rust doesn't have inheritance. GObject is built on it. Rust tracks lifetimes at compile time. GObject uses runtime reference counting. The gtk-rs bindings bridge this gap with a specific pattern — and once you've seen it once, you'll recognise it everywhere.

A simple GObject: the Feed model

We're going to create a Feed type — an RSS feed with a title, a URL, and an unread count. No widgets, no UI. Just a plain GObject that holds data, exposes properties, and emits a signal. This is the simplest way to see every piece of the pattern without distractions.

Setting up

cargo init gobject-example
cd gobject-example

[package]
name = "gobject-example"
version = "0.1.0"
edition = "2021"

[dependencies]
gtk = { package = "gtk4", version = "0.11" }

We only need gtk4 — it exposes glib and gio as gtk::glib and gtk::gio. No libadwaita for this.

The inner/outer type split

Every custom GObject in Rust is two types: an inner type that lives in mod imp and holds the actual state, and a lightweight outer type that's what your code actually touches. GObject owns the inner; the outer is just a reference-counted handle to it.

This split exists because both GObject and Rust want to own the data. GObject manages lifecycles through reference counting. Rust enforces ownership at compile time. The inner/outer pattern resolves the tension — GObject gets ownership of the inner type, and you get a cheaply-cloneable handle to pass around. If you've used Rc<RefCell<T>>, the mental model is similar — though GObject's ref count is atomic, so Arc<RefCell<T>> is closer to the truth. The atomicity is about safe counting, not thread-safe access; GTK objects still need to stay on the main thread.

The inner type

Create src/feed.rs:

mod imp {
    use std::cell::{Cell, RefCell};
    use std::sync::OnceLock;

    use glib::subclass::Signal;
    use glib::Properties;
    use gtk::glib;
    use gtk::prelude::*;
    use gtk::subclass::prelude::*;

    #[derive(Properties, Default)]
    #[properties(wrapper_type = super::Feed)]
    pub struct Feed {
        #[property(get, set)]
        title: RefCell<String>,

        #[property(get, set)]
        url: RefCell<String>,

        #[property(get, set)]
        unread_count: Cell<u32>,
    }

    #[glib::object_subclass]
    impl ObjectSubclass for Feed {
        const NAME: &'static str = "GazetteFeed";
        type Type = super::Feed;
    }

    #[glib::derived_properties]
    impl ObjectImpl for Feed {
        fn signals() -> &'static [Signal] {
            static SIGNALS: OnceLock<Vec<Signal>> = OnceLock::new();
            SIGNALS.get_or_init(|| {
                vec![Signal::builder("items-updated")
                    .param_types([u32::static_type()])
                    .build()]
            })
        }
    }
}

Let's unpack the important parts.

Properties and interior mutability. Each field marked #[property(get, set)] becomes a GObject property — accessible by string name, bindable, observable. The RefCell<String> and Cell<u32> types are required because GObject's API is &self everywhere, never &mut self. Use Cell<T> for Copy types, RefCell<T> for everything else.

ObjectSubclass. This registers the type with GObject. NAME must be globally unique — duplicates cause a runtime panic. We don't set ParentType because the default is glib::Object. When we get to widgets, we'll set it explicitly.

ObjectImpl and signals. The #[glib::derived_properties] attribute wires up the getters and setters. The signals method defines a custom items-updated signal that carries a u32. Signals are GObject's event system — listeners connect without the emitter knowing who's listening.

The outer type

Still in src/feed.rs, below mod imp:

use glib::Object;
use gtk::glib;
use gtk::prelude::*;

glib::wrapper! {
    pub struct Feed(ObjectSubclass<imp::Feed>);
}

impl Feed {
    pub fn new(title: &str, url: &str) -> Self {
        Object::builder()
            .property("title", title)
            .property("url", url)
            .build()
    }

    pub fn mark_items_updated(&self, new_count: u32) {
        self.set_unread_count(new_count);
        self.emit_by_name::<()>("items-updated", &[&new_count]);
    }
}

The glib::wrapper! macro generates a thin, reference-counted pointer to the inner type. Clone it freely — it just bumps the ref count.

GObjects are built through the builder pattern, setting properties by name. mark_items_updated deliberately sets the property and emits the signal as a single operation — in a real app, you don't want callers updating the count without notifying listeners.

Using it

In src/main.rs:

mod feed;

use feed::Feed;
use gtk::glib;
use gtk::prelude::*;

fn main() {
    let feed = Feed::new("GNOME Planet", "https://planet.gnome.org/atom.xml");

    // Read properties
    println!("Feed: {} ({})", feed.title(), feed.url());
    println!("Unread: {}", feed.unread_count());

    // Connect to the signal
    feed.connect_closure(
        "items-updated",
        false,
        glib::closure_local!(|_feed: &Feed, count: u32| {
            println!("Feed updated — {} new items", count);
        }),
    );

    // Connect to property change notifications
    feed.connect_notify(Some("unread-count"), |feed, _| {
        println!("Unread count changed to {}", feed.unread_count());
    });

    // Update the feed
    feed.mark_items_updated(5);

    // Property binding — one Feed mirroring another's unread count
    let mirror = Feed::new("Mirror", "https://example.com/feed.xml");
    feed.bind_property("unread-count", &mirror, "unread-count")
        .sync_create()
        .build();

    println!("Mirror unread: {}", mirror.unread_count()); // 5

    feed.mark_items_updated(12);
    println!("Mirror unread: {}", mirror.unread_count()); // 12
}

Feed: GNOME Planet (https://planet.gnome.org/atom.xml)
Unread: 0
Unread count changed to 5
Feed updated — 5 new items
Mirror unread: 5
Unread count changed to 12
Feed updated — 12 new items
Mirror unread: 12

No gtk::init() call — we're only using GLib objects here, no widgets, no event loop. Synchronous signal emission works fine without one; once you're dispatching across async boundaries, you'll need a running main loop.

Property binding is the one worth sitting with

Properties, signals, notifications — you wire those up manually. Binding is different. It's declarative: state a relationship once and the type system enforces it. When we build Gazette's UI, this is how we'll connect models to widgets — a property changes on a model and the bound widget updates automatically, no event handler code. The first time that happens, you stop thinking in callbacks. That's the shift.

The pattern, summarised

Every custom GObject in Rust follows this structure:

src/my_type.rs
├── mod imp {
│   ├── struct MyType { ... }           // State (with Cell/RefCell)
│   ├── impl ObjectSubclass for MyType  // Registration (NAME, Type, ParentType)
│   └── impl ObjectImpl for MyType      // Lifecycle (properties, signals)
│   └── impl WidgetImpl, etc.           // Parent traits (only for widgets)
│   }
├── glib::wrapper! { ... }             // Outer type declaration
└── impl MyType { ... }                // Public API

Yes, it's a lot of ceremony for a type that holds three fields. That's the price of entry — GObject was designed for C, and bridging two type systems isn't free. But the payoff is that every GObject you write after this one is the same shape. You stop thinking about the structure and start thinking about what the type actually does. The boilerplate becomes invisible by the third or fourth time.

Common mistakes

Forgetting interior mutability — title: String instead of title: RefCell<String> will fail at compile time. GObject gives you &self, never &mut self.

Duplicate NAME strings — runtime panic, not a compile error. Namespace them: GazetteFeed, not Feed.

Property name casing — GObject properties use kebab-case (unread-count), Rust methods use snake_case (unread_count()). When referencing by string — connect_notify, bind_property, Object::builder() — use kebab-case. Get it wrong and it silently fails.

Forgetting #[glib::derived_properties] — without it, the Properties derive generates Rust methods but the GObject type system doesn't know about them. Bindings and notifications won't work.

What comes next

Now that we understand GObject's type system — properties, signals, the inner/outer split — we're ready to apply it. In Part 3, we'll build Gazette's application skeleton: an adw::Application, an adw::ApplicationWindow, a header bar, and a Blueprint template. The GObject pattern is exactly the same; the trait chain is just longer.

The source code for this post is available on GitHub.

Building GNOME Apps with Rust, Part 1: Getting Started

fromthearchitect — Mon, 06 Apr 2026 22:11:23 +0000

This is Part 1 of a series that takes a GNOME application from an empty directory to acceptance into GNOME Circle. Each post is self-contained, but the series follows a single arc — and a real app — through every stage of the journey.

Why GNOME

If you're building a desktop Linux application in 2026, you've got choices. KDE Plasma has Kirigami. Elementary has Granite. You can reach for Electron, Tauri, or a dozen other cross-platform toolkits and call it a day.

I chose GNOME because of what it feels like to use. The GNOME desktop provides a clean, distraction-free approach to computing. Its consistency rivals early macOS — there's a feeling that everything is in its place. When I started building Moments, my photo management app, that consistency carried over into the development experience in a way I didn't expect. The GNOME Human Interface Guidelines aren't suggestions — they're a design language. Follow them and your app inherits a coherent visual identity, consistent interaction patterns, and accessibility support you didn't have to design yourself. Your header bar looks right. Your adaptive layout works the way users expect. Your keyboard navigation is correct.

That matters more than it sounds like it should. Users develop muscle memory around their environment. An app that respects that muscle memory earns trust immediately. An app that doesn't — even if it's technically superior — creates friction. GNOME gives you a head start on eliminating that friction, but only if you actually use the toolkit the way it's meant to be used.

The ecosystem is also unusually healthy for an open source desktop project. Flathub provides distribution. GNOME Circle provides recognition, infrastructure, and community. The tooling — Builder, Workbench, Cambalache — is actively maintained and improving. And the community, while not enormous, is engaged and welcoming in a way that larger ecosystems sometimes aren't.

Why Rust

GNOME has traditionally been a C ecosystem. GTK is written in C. GLib is written in C. The GObject type system — which underpins everything — is C's answer to object-oriented programming, complete with manual reference counting and a macro-heavy convention system that works remarkably well once you've internalised it.

You don't need to write C to build GNOME apps. The GObject Introspection system generates bindings for dozens of languages, and three in particular have strong GNOME stories: Python with PyGObject, Vala (a language designed specifically for GObject development), and Rust with gtk-rs.

I'm writing this series in Rust, and I think it's the right default choice for new GNOME apps in 2026.

The ecosystem has moved. Look at recent GNOME Circle apps — Fractal, Switcheroo, Hieroglyphic — the Rust cohort is growing fast. When you hit a problem building a Rust/GTK app, there's now a meaningful body of real-world code to reference. That wasn't true even two years ago.

The gtk-rs bindings are mature. The gtk4-rs and libadwaita-rs crates provide safe, idiomatic Rust wrappers around the full GTK4 and libadwaita API surface. They handle reference counting, type casting, and signal connections in a way that feels natural in Rust. These aren't thin C bindings with unsafe blocks everywhere — they're a genuine Rust API for building GTK applications.

Rust's strengths align with desktop app needs. Memory safety without garbage collection. Fearless concurrency. A type system that catches entire categories of bugs at compile time. These aren't just theoretical benefits — they show up in practice when you're managing complex UI state, handling async operations, and trying to ship software that doesn't crash.

The tooling works. rust-analyzer provides excellent IDE support. Cargo handles dependency management. The Flatpak SDK includes a full Rust toolchain. You can get from cargo init to a running Flatpak application without fighting your tools.

There are tradeoffs. Rust has a steeper learning curve than Python, and the GObject subclassing pattern in Rust adds a layer of complexity that doesn't exist in Python or Vala. Compile times are slower. Iteration speed — especially building inside Flatpak — is meaningfully worse than Python's edit-and-run loop. These are real costs, and I won't pretend otherwise. But the learning curve is a curve, not a wall, and this series will walk through every part of it.

Setting up the development environment

Before you write a single line of Rust or GTK code, you need three things: GNOME Builder, the Flatpak SDK, and a working understanding of why we're using Flatpak from day one.

Why Flatpak from the start

Most development guides have you install GTK libraries on your host system, write code against them, and worry about packaging later. This works — until it doesn't. The failure mode is specific and painful: you develop against GTK 4.18 on your host, everything works, you go to package the app for Flathub six months later, and discover that the GNOME SDK version you need to target ships GTK 4.16, and three APIs you depend on don't exist.

Building inside Flatpak from the beginning eliminates this entire class of problem. Your development environment matches your deployment environment. The libraries you link against are the libraries your users will have. The dependencies are explicit and reproducible. When you submit to Flathub, there are no surprises.

It's slightly more friction up front. It's dramatically less friction in total.

Install Flatpak and Flathub

If you're running Fedora, Flatpak is already configured. For other distributions:

# Install Flatpak (if not present)
sudo apt install flatpak    # Debian/Ubuntu
sudo pacman -S flatpak      # Arch

# Add the Flathub remote
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

Install the GNOME SDK

The GNOME SDK provides the full development environment — GTK4, libadwaita, GLib, and the Rust toolchain — inside a Flatpak runtime. You need both the runtime and the SDK, plus the Rust extension:

# Install the GNOME 50 SDK and runtime
flatpak install flathub org.gnome.Sdk//50 org.gnome.Platform//50

# Install the Rust extension for the SDK
flatpak install flathub org.freedesktop.Sdk.Extension.rust-stable//25.08

A note on version numbers: the GNOME SDK version (50, at time of writing) corresponds to the GNOME release. The Rust extension version (25.08) corresponds to the freedesktop SDK version that the GNOME SDK is built on. These version numbers will change — check the Flathub runtime page for current versions.

Install GNOME Builder

GNOME Builder is the IDE purpose-built for GNOME development. It understands Meson, Flatpak manifests, and the GNOME SDK. It can build your application inside the Flatpak sandbox, run it, and provide code intelligence — all without you manually configuring build environments.

flatpak install flathub org.gnome.Builder

Builder isn't the only option. You can use VS Code, Neovim, or any editor you prefer — I'll cover that setup in a later post on developer experience. But Builder eliminates the most configuration friction for getting started, and it's what I'd recommend for your first project.

Verify the toolchain

Open a terminal inside the Flatpak SDK environment to confirm everything is in place:

# Enter the SDK environment
flatpak run --command=bash org.gnome.Sdk//50

# Inside the SDK shell:
rustc --version
cargo --version
pkg-config --libs gtk4
pkg-config --libs libadwaita-1

You should see a recent stable Rust version and successful pkg-config output for both GTK4 and libadwaita. If any of these fail, the SDK or Rust extension didn't install correctly — reinstall them before continuing.

A note on host development

You can also develop on your host system by installing the GTK4 and libadwaita development packages directly:

# Fedora
sudo dnf install gtk4-devel libadwaita-devel

# Arch
sudo pacman -S gtk4 libadwaita

# Ubuntu/Debian (may lag behind on versions)
sudo apt install libgtk-4-dev libadwaita-1-dev

This gives you faster compile times and a tighter edit-compile-run loop, which matters during active development. Many Rust/GTK developers work this way day-to-day, using host-installed libraries for rapid iteration and Flatpak builds for testing and release.

The risk is version drift between your host libraries and the Flatpak SDK. If you go this route, check which GTK4 and libadwaita versions your host provides and compare them to the GNOME SDK you're targeting. As long as your host version is equal to or newer than the SDK version, you're fine. If it's older, you'll hit missing APIs.

My recommendation: start with Flatpak-only builds until you've got a working app, then add host builds as an optimisation once you understand the version boundaries.

The tools you will be using

Before we start writing code in Part 2, here's a brief orientation to the tools that'll appear throughout this series. You don't need deep knowledge of any of them yet — just awareness that they exist and what role they play.

Meson — The build system. GNOME apps use Meson, not Cargo, as the top-level build system. Cargo still builds your Rust code, but Meson orchestrates everything else: compiling GResources, installing desktop files, generating application metadata, and invoking Cargo as part of the build. Part 3 covers Meson in detail.

Blueprint — A markup language for defining GTK user interfaces. Blueprint compiles to the XML that GTK's GtkBuilder expects, but it's dramatically more readable. You can also build your entire UI in Rust code without Blueprint — we'll cover both approaches.

GResource — GNOME's system for bundling assets (UI templates, icons, CSS) into your application binary. Instead of loading files from disk at runtime, GResources get compiled into the binary and accessed by path. It's how GNOME apps ship self-contained.

Appstream — The metadata standard that app stores (including Flathub) use to display your app's name, description, screenshots, and release notes. You'll need to get this right for Flathub acceptance — Part 9 covers it.

Workbench — A playground app for experimenting with GTK widgets, CSS, and Blueprint templates. If you want to test a UI idea without rebuilding your whole app, Workbench is where you do it. Grab it from Flathub.

What we're building

Part 2 opens with introducing the app we'll build throughout this series. It won't be a toy counter or a TODO list — it'll be something with enough complexity to hit real architectural decisions, real packaging challenges, and real Flathub review feedback.

Every post will be self-contained enough that you can follow along building your own app. The problems we'll solve — state management, async operations, data persistence, adaptive layouts, packaging — are universal to any non-trivial GTK application. We're documenting the actual experience of taking a GNOME app from zero to Circle, including the parts that aren't in any documentation.

What comes next

Before we build a window, we need to understand the type system underneath it. Every widget, every signal, every property binding in GTK is built on GObject — and the way GObject maps to Rust is the single biggest conceptual hurdle for developers coming from other Rust backgrounds.

In Part 2, we'll build a simple data model from scratch and use it to understand GObject's inner/outer type pattern, properties, signals, and property bindings. No GTK widgets yet — just the foundation that makes everything else click once we start building the actual app in Part 3.

The AI Pair Programmer: Why the Human Loop Is About Partnership, Not Review

fromthearchitect — Sat, 28 Mar 2026 04:01:49 +0000

The current conversation is missing something

If you spend any time in developer circles right now, the conversation about AI coding tools tends to collapse into one of two camps. The first camp believes we are months away from AI replacing software developers entirely — that the role of the human is already vestigial, a temporary inconvenience on the road to full automation. The second camp pushes back hard, arguing that AI is little more than a sophisticated autocomplete — useful for boilerplate, dangerous if trusted, and nowhere near capable of producing anything a senior engineer couldn't do faster with a clear head and a good keyboard shortcut.

Both positions are wrong. Not subtly wrong — fundamentally wrong. And the gap between them is where something genuinely interesting is happening.

The developers who are getting the most out of AI coding tools are not the ones treating the AI as an oracle to be prompted, nor the ones dismissing it as a toy. They are the ones who have stumbled onto — or deliberately adopted — a different mental model entirely. One that has a name, a history, and a body of practice behind it. One that the software industry actually worked out decades ago, in a different context, for different reasons.

It's called pair programming. And it turns out it maps onto working with an LLM almost perfectly.

A brief primer on XP pair programming

Extreme Programming — XP — emerged in the late 1990s as a reaction to the bloated, process-heavy software development methodologies of the time. It was opinionated, practical, and in many ways ahead of its time. Among its practices, pair programming stood out as the one that generated the most scepticism from people who had never tried it, and the most loyalty from people who had.

The premise is simple: two developers, one keyboard, one screen. But the premise is also misleading, because it implies the value is in the typing — that you are getting two people's worth of keystrokes for the price of one. That is not what pair programming is about. In fact, that framing completely misses the point.

XP described two roles in a pairing session. The driver holds the keyboard and writes the code. The navigator holds the broader picture — watching for mistakes, thinking about what comes next, asking the question the driver is too focused to ask. Neither role is superior. Neither is passive. The navigator is not watching. The navigator is thinking, out loud, in dialogue with the driver. The value is in that continuous conversation — the shared context that builds between two people working through a problem together.

What pair programming actually produces is a tighter feedback loop than solo development. Mistakes get caught earlier. Dead ends get identified faster. The solution that emerges has been stress-tested in real time by two different minds approaching the problem from slightly different angles. The code is better not because two people wrote it, but because two people thought about it simultaneously.

This is why studies on pair programming consistently show that while it does take more developer hours per feature, it produces significantly fewer defects and requires less rework. The investment pays for itself. The conversation is the work.

The AI as pair programmer

Here is where the analogy earns its keep.

When most developers describe their workflow with an AI coding tool, they describe something that sounds like issuing instructions. They have a task. They describe it to the AI. The AI produces output. They evaluate the output, accept it or reject it, and move on. The human is a reviewer. The AI is a very fast junior developer who never gets tired and never takes offence.

That model works. It produces results. But it is leaving an enormous amount of value on the table.

The developers getting disproportionate results from AI tools are doing something subtly but importantly different. They are not issuing instructions — they are having a conversation. They bring the problem, not the solution. They share context before asking for code. They push back when something feels wrong, even if they cannot immediately articulate why. They ask the AI to explain its reasoning, then challenge that reasoning. They treat the session as a dialogue, not a transaction.

In XP terms, they are navigating. The AI is driving.

This is not a metaphor. The navigator role in pair programming is precisely about holding the bigger picture while the driver handles execution. It means knowing where you are trying to go, recognising when the current path is taking you somewhere else, and having the conversation that corrects course before you have written a thousand lines in the wrong direction. That is exactly what a skilled human brings to a session with an AI coding tool.

The AI, for its part, brings things that complement the navigator role almost perfectly. Breadth of knowledge across languages, frameworks, and patterns that no single human could match. Speed of execution that removes the friction between idea and implementation. Tireless willingness to explore alternatives, rewrite sections, and try a different approach without frustration or ego. And crucially — no stake in being right. An AI does not defend its previous output. Ask it to reconsider and it will.

What neither party brings alone is sufficient. The AI without a thoughtful navigator produces technically correct output that solves the wrong problem, or solves the right problem in a way that does not fit the broader system, or makes decisions that are locally sensible and globally incoherent. The human without the AI's execution speed and breadth spends too much time in the details, loses the thread of the bigger picture, and runs out of energy before the interesting problems get solved.

Together, the feedback loop tightens in exactly the way XP pair programming described. The conversation is still the work. It has just moved to a different medium.

What the human loop actually looks like

It is easy to describe the partnership in the abstract. It is more useful to describe what it actually looks like in practice — the specific moments where the human contribution is irreplaceable, and where the temptation to disengage is strongest.

Defining the problem before touching the keyboard

The single highest-leverage thing a human brings to an AI pairing session is a clear, well-considered problem definition. Not a feature request. Not a task. A genuine understanding of what you are trying to achieve and why, what constraints matter, and what success looks like.

This sounds obvious. It is surprisingly rare. The temptation with fast AI tools is to start immediately — to get something on screen quickly and iterate from there. Sometimes that works. More often, the cost of an underspecified problem shows up three hours later when you have a working implementation of the wrong thing.

The navigator's first job is to think before the driver starts moving. Spend time on the problem. Write it down. Share it with the AI not as a prompt but as a briefing. The quality of everything that follows is shaped by the quality of this moment.

Knowing when to push back

AI coding tools are confident. They produce output that looks authoritative, is well-structured, and compiles. This is both their greatest strength and their most significant risk. Technically correct output that solves the wrong problem is harder to catch than broken code, because nothing obviously fails.

The human navigator's most important skill is the ability to look at plausible output and ask whether it is actually right — not syntactically, but conceptually. Does this approach fit the broader architecture? Does this abstraction hold up under the cases we haven't discussed yet? Is this solving the problem we defined, or a simpler adjacent problem that is easier to solve?

Pushing back does not require being certain the AI is wrong. It requires being willing to have the conversation. Ask it to explain its reasoning. Ask whether there is an alternative approach. Ask what the tradeoffs are. The AI will engage with these questions genuinely, and more often than not the dialogue surfaces something important that the initial output missed.

Bringing taste the AI doesn't have

There are decisions in software development that are not technical. They are aesthetic, strategic, or deeply contextual — shaped by knowing your users, your constraints, your history, and your values. These decisions do not have correct answers that can be derived from training data.

What belongs in version one and what gets deferred? Which abstraction is clean enough to be worth the indirection? Does this interaction pattern feel right for the people who will use it? Is this the kind of code a contributor joining the project in six months will be able to understand?

These are navigator questions. The AI can inform them, offer perspectives, and flag tradeoffs — but it cannot answer them. The human is not in the loop for these decisions because the process requires it. The human is in the loop because the human is the only one who actually knows.

Recognising when the output is wrong

This is the hardest skill to describe and the most important to develop. It is the ability to read AI-generated output and feel that something is off — before you can articulate why. Before the tests fail. Before the architecture review. Before the bug report.

It is, in essence, experience. The same pattern recognition that a senior engineer develops over years of reading code, debugging systems, and watching abstractions fail in production. AI tools do not compress this. They make it more valuable, because the volume of output has increased while the need for judgment has not decreased.

The human who can generate a working implementation in an afternoon and also recognise which parts of it will hurt them in three months is in a fundamentally different position than the one who can only do the first.

Steering, not accepting

Perhaps the simplest way to describe the human loop is this: your job is not to evaluate what the AI gives you. Your job is to steer toward what you actually need.

Evaluation is passive. Steering is active. It means coming to the session with a direction in mind, holding that direction as the work progresses, and continuously asking whether the current path is still heading the right way. It means being willing to say "this is good, but it's not quite right" and continuing the conversation until it is. It means treating the first output as the beginning of a dialogue, not the end of one.

The developers who get the most out of AI tools are not the ones who are best at prompting. They are the ones who are best at knowing what they want — and staying in the conversation until they get it.

What this changes for independent open source development

Open source software has always had a talent distribution problem. The ideas are abundant. The developers who want to build are abundant. The time to build is not.

A motivated independent developer working evenings and weekends on a project they care about has historically been constrained not by ambition or skill, but by hours. A genuinely useful, well-architected application — something with multiple backends, proper data persistence, a thoughtful UI, comprehensive documentation, Flatpak packaging, CI/CD, and the hundred other things that separate a hobby project from something people can actually rely on — has traditionally taken years of sustained effort from a solo developer. Many projects never get there. They stall at the interesting-but-incomplete stage, maintained inconsistently, never quite reaching the quality bar that would attract users or contributors.

That constraint is loosening.

The AI pair programming model compresses the distance between idea and implementation in a way that changes the economics of independent open source development fundamentally. Not because the AI does the work — but because the conversation-driven development loop eliminates the specific kinds of friction that cause projects to stall. The boilerplate that nobody wants to write. The documentation that always gets deferred. The architectural decision that requires holding too many things in your head simultaneously. The test scaffolding that feels important but not urgent. These are exactly the tasks where AI assistance is most effective and most reliable.

What remains — and what the human navigator must still bring — is everything that cannot be generated. The decision about which problem is worth solving. The product sense that shapes a feature into something users will actually understand. The judgment that says this abstraction is clean and that one will hurt you in six months. The taste that knows what polished looks like, because you have used enough polished software to have internalised the standard.

This has an important implication. As the execution barrier drops, the bottleneck shifts. The scarce resource in open source software development is no longer time — it is judgment. Developers who bring genuine domain knowledge, strong product instincts, and the ability to recognise quality will produce disproportionate results. Developers who treat AI tools as a shortcut around thinking will produce more output, faster, with the same fundamental limitations they had before.

The other shift is in portfolio. The "one developer, one project" pattern that has characterised most independent open source work is giving way to something different. A developer with strong judgment and a productive AI partnership can now maintain multiple substantial projects simultaneously — not by spreading themselves thin, but by changing the nature of the work. The parts of software maintenance that consumed the most time — implementing well-understood features, writing documentation, managing boilerplate, scaffolding tests — are no longer the limiting factor. What remains is the interesting work. The work that required a human anyway.

For ecosystems like GNOME, where the quality bar for inclusion is genuinely high and the community of active developers is relatively small, this could be transformative. The gap between "interesting idea" and "production quality app" has historically been where most projects died. That gap is narrowing. The question is whether the developers entering the ecosystem with AI-assisted workflows bring the judgment to match the pace — and whether the ecosystem's review and mentorship structures can scale to meet the increased volume of serious submissions that will follow.

The opportunity is real. So is the responsibility that comes with it.

The risks worth naming honestly

Any argument for a new way of working that does not acknowledge its failure modes is not a balanced argument — it is advocacy. The AI pair programming model is genuinely powerful. It is also genuinely risky, in specific ways that are worth naming clearly.

The flood of mediocre output

The same forces that allow a thoughtful developer to ship a production-quality application in days also allow a less thoughtful developer to ship something that looks like a production-quality application in days. The difference is not always visible on the surface. The code compiles. The UI renders. The README is comprehensive. The architecture document exists.

What may be missing is the judgment that shaped the decisions underneath. An abstraction that seemed clean to the AI but will not survive contact with real usage. A data model that works for the happy path and fails at the edges. A feature set that was easy to generate but does not reflect what users actually need.

Open source ecosystems that rely on community review as their quality filter — Flathub, GNOME Circle, and others — will face increased volume as the execution barrier drops. The risk is not that reviewers will be fooled by AI-generated mediocrity. Experienced reviewers are good at finding the problems underneath a polished surface. The risk is that the volume of submissions outpaces the community's capacity to review them thoughtfully, and that the filter becomes less effective simply because it is overwhelmed.

This is not a reason to avoid AI-assisted development. It is a reason for the ecosystem to think ahead about how its quality gates scale.

Understanding what you have built

There is a specific failure mode in AI-assisted development that has no real equivalent in traditional solo development. It is possible to arrive at a working implementation without fully understanding it. The code is correct. The tests pass. The feature works. But the developer who accepted the output without interrogating it cannot explain why certain decisions were made, cannot predict how the system will behave under conditions that were not discussed, and cannot confidently modify it when requirements change.

This is not the AI's failure. It is the navigator's failure — a failure to stay in the conversation long enough to genuinely understand what was built and why. The fix is not to distrust AI output. It is to hold yourself to the same standard of understanding you would apply to code you wrote yourself. If you cannot explain a decision, ask until you can. If an abstraction feels opaque, explore it. The AI will not tire of the conversation. Use that.

The expertise illusion

AI tools are fluent. They produce confident, well-structured output across an enormous range of domains. This fluency can create the impression of expertise where expertise does not exist — in the AI's output and, more dangerously, in the developer's self-assessment.

A developer who has shipped several AI-assisted projects may have genuine expertise in the problems those projects solved — or they may have accumulated a portfolio of working code without accumulating the underlying understanding that expertise actually represents. The distinction matters when things go wrong. When a system behaves unexpectedly in production. When a security issue emerges in a dependency. When the architecture needs to change in a fundamental way. These are the moments that separate the developer who understands their system from the one who generated it.

The partnership model described in this post is specifically designed to develop genuine understanding alongside working software. The navigator who asks why, pushes back on decisions, and steers the conversation toward clarity is building expertise as they build the system. The developer who accepts output uncritically is not.

The temptation to move on

Fast tools create an appetite for speed. When you can scaffold a feature in an hour that would have taken a day, the temptation is to do ten features instead of one — to keep moving, keep building, keep generating. This is a real risk.

The parts of software development that AI does not accelerate — thinking carefully about the problem, sitting with an architectural decision before committing to it, getting feedback from real users before adding the next feature — are the parts that tend to get skipped when the rest of the loop feels fast. The navigator's discipline is not just about what to build. It is about when to stop building and think.

Pace is a tool. Used well, it lets you reach a quality threshold faster than was previously possible. Used poorly, it lets you reach the wrong destination faster than was previously possible.

The invitation

There is a version of working with AI coding tools that is transactional. You have a task. You describe it. You evaluate the output. You move on. It works, up to a point. It will continue to work, up to a point.

There is another version that is something closer to a genuine intellectual partnership. You bring the problem, the context, the taste, and the judgment. The AI brings the breadth, the speed, and the tireless willingness to explore. Together you have a conversation — the kind of conversation that pair programming has always held up as the ideal — and the work that emerges from that conversation is better than either party could produce alone.

The shift between these two versions is not about tools. It is not about prompting techniques or context window sizes or which model you are using. It is about how you show up to the session. Whether you come with a direction or just a task. Whether you interrogate the output or accept it. Whether you are willing to stay in the conversation until you genuinely understand what has been built and why.

The XP community figured out decades ago that the most productive unit in software development is not the individual developer working alone — it is two people thinking together. That insight did not age. It just found a new form.

Stop prompting. Start partnering. The results will surprise you.