The click that still does nothing real

Select This Week in GNOME, then select Hacker News. The placeholder swaps in the new name and URL — everything the app knows about that feed, and none of what’s actually in it. Every Feed in the sidebar has a uri pointing at a real RSS or Atom document on the actual internet, and nothing in the codebase has ever asked one of them what’s there.

The obvious fix — fetch the URL when feed-selected fires — is one line of code and the wrong line of code. GTK doesn’t have a spare thread lying around to do that on, and the thread it does have is busy.

By the end of this post, selecting Hacker News in the sidebar prints real headlines to the terminal, fetched over the network, without the window so much as flickering. We’ll build a Tokio runtime alongside GTK’s own, give Feed somewhere to put what it fetches, and draw a hard line neither executor is allowed to cross.

The freeze

Wire the obvious fix into the feed-selected handler first, so you can watch it fail:

obj.connect_closure(
    "feed-selected",
    false,
    glib::closure_local!(move |_window: &super::GazetteWindow, feed: Feed| {
        // Don't do this.
        std::thread::sleep(std::time::Duration::from_secs(2));
        eprintln!("fetched (fake): {}", feed.name());
    }),
);

std::thread::sleep stands in for “network request in flight.” Run the app and click a feed. For two seconds the window stops responding to anything — no hover states, no resize, no cursor blink, nothing repaints. Click a different feed while the first is still “fetching” and the click doesn’t register until the sleep ends; it queues up invisibly and the window only notices you clicked at all once the first one finishes.

If you have GTK Inspector open (GTK_DEBUG=interactive, or Ctrl+Shift+I) while you try this, its own live views stall for the same two seconds — Inspector needs the app’s main loop to be responsive to answer its own queries, so a frozen loop is invisible to Inspector too. Worth knowing the next time you’re not sure whether your code froze or something else did.

Revert the handler to the logging-only version from Part 5 before continuing. The freeze was the demonstration, not a step you keep.

One main loop, nothing else runs until you give it back

GTK schedules everything through a single glib::MainContext, running cooperatively on a single thread: one job finishes before the next one starts. When you clicked a feed a moment ago, the redraw that should have shown the hover state, the cursor update, the eventual repaint once the click registered — all of it queued behind your feed-selected handler, waiting for std::thread::sleep to let go of the only thread any of it can run on.

That’s a deliberate tradeoff. Exactly one thread ever touches a widget, so there’s no locking, no data races, no Mutex<Widget>. The price is that the one thread has to keep coming back. Block it — a sleep, a synchronous file read, a blocking network call, anything — and every other queued job waits behind you.

This is also why “just spawn a thread and do it there” isn’t a fix, only a different failure. Almost every GTK/GObject type is !Send: the bindings won’t even let you move a Feed or a widget handle across a thread boundary — it’s a compile error, not a runtime one. GObject’s own machinery assumes single-threaded access and doesn’t defend against concurrent calls from a second thread. A background thread can compute a result, but it can’t hand that result to a widget directly. Something still has to get the result back onto the one thread allowed to touch GTK state.

Two executors, one job each

The pattern that resolves this has a name because the shape recurs in every GTK app that talks to a network: two executors, each with a rule it never breaks.

The GLib main loop owns every widget, every GObject, every signal, and it must never block.

Tokio owns anything that can block — the network request here, file I/O or database queries later. It runs on its own thread pool, and it never touches a widget or a GObject directly. That’s its rule.

The two only meet at one seam: a future running on the GLib main context can .await a handle to work Tokio is doing, and when that work finishes, execution resumes back on the main context with the result now sitting there as a plain value. Nothing crosses except that value — no Feed, no gtk::Label, nothing GTK owns ever travels to a Tokio thread, and no raw socket or blocking read ever runs on the GLib thread. The rest of this post is standing up both executors and building that one seam.

Standing up the second executor

Add the dependencies:

tokio = { version = "1.53.1", features = ["rt-multi-thread", "net", "time"] }
feed-rs = "2.4.0"
reqwest = { version = "0.12", default-features = false, features = ["rustls-tls"] }

rt-multi-thread gives the runtime its worker threads; net and time give it the I/O and timer drivers reqwest — and any future tokio::time::sleep — actually needs. That matters more than it looks like it should: reqwest also depends on tokio and pulls in net/time itself, and Cargo unifies features across the whole dependency graph. Leave them off tokio’s own line and the project still compiles today, by accident of what else happens to be in Cargo.toml. It breaks the day reqwest changes its feature list, or the day someone copies this dependency line into a project with no reqwest in it.

reqwest with default-features = false and rustls-tls pulls in a pure-Rust TLS stack instead of linking against the system’s OpenSSL — one less thing the Flatpak manifest needs to account for. The 0.12 pin is deliberate too: 0.13 renamed that feature to rustls and made it the default backend, which would leave the line above redundant rather than wrong, but 0.12 is what this post was written and tested against, and mixing versions is a worse trap than an old pin.

The runtime itself is built once, in main(), before the GTK application exists:

// The second executor. Built before the GTK application and dropped
// after it exits, so it outlives every fetch that borrows its handle —
// the GLib main loop is the other executor, and it never blocks
// waiting on this one.
let tokio_runtime = tokio::runtime::Builder::new_multi_thread()
    .worker_threads(2)
    .thread_name("gazette-fetch")
    .enable_all()
    .build()
    .expect("failed to build Tokio runtime");

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

let exit_code = app.run();

// `tokio_runtime` would drop here anyway at end of scope; the explicit
// drop just documents the ordering. `Runtime::drop` blocks this thread
// until every worker stops and abandons whatever tasks haven't
// finished — abrupt, not a cooperative cancel — which is still better
// than a fetch outliving the window that would have consumed it.
drop(tokio_runtime);
exit_code

app.run() blocks until the GTK application quits — that’s the GLib main loop, occupying this thread for the entire life of the app. The Tokio runtime doesn’t need this thread; Builder::new_multi_thread spins up its own worker threads (two of them here, named for easy identification in a debugger) and hands back a Runtime you only need to keep alive, not sit inside. tokio_runtime.handle().clone() is the thing that actually travels: a cheap, cloneable reference that can schedule work onto the runtime from any thread, including the GLib main thread.

One trap worth flagging on its own: forgetting .enable_all() fails silently until the first real request. A Builder without it produces a runtime with no I/O or timer driver — a different gap from the missing Cargo features above, this one is about whether a correctly-compiled runtime instance turns its drivers on. It builds fine, main() runs fine, the window opens fine, and the first time a spawned task tries to do the thing a runtime is for — reqwest::get or tokio::time::sleep — it panics with a message about no I/O driver running. The bug is invisible until the exact code path that needs the missing driver executes, which is exactly the fetch path this post is building.

That Handle needs a home the rest of the app can reach. GazetteApplication already owns everything else global to a running instance, so it owns this too — the same OnceCell shape Part 5 used for feeds: OnceCell<gio::ListStore> on the window: set once, read forever after.

#[derive(Debug, Default)]
pub struct GazetteApplication {
    // The second executor. Built once in `main()`, before the GTK
    // application runs, and outlives every fetch that borrows it.
    pub tokio: OnceCell<tokio::runtime::Handle>,
}

impl GazetteApplication {
    pub fn new(
        application_id: &str,
        flags: &gio::ApplicationFlags,
        tokio: tokio::runtime::Handle,
    ) -> Self {
        let app: Self = glib::Object::builder()
            .property("application-id", application_id)
            .property("flags", flags)
            .property("resource-base-path", "/io/github/fromthearchitect/gazette")
            .build();
        app.imp()
            .tokio
            .set(tokio)
            .expect("tokio handle set once at construction");
        app
    }

    /// The shared Tokio runtime handle — the executor every network fetch
    /// runs on. Available from any `GazetteWindow` via its `application()`.
    pub fn tokio_handle(&self) -> tokio::runtime::Handle {
        self.imp().tokio.get().expect("tokio handle set").clone()
    }
}

build() returns a fully constructed object. If GazetteApplication ever grows a constructed() that reaches for tokio_handle(), it will find the cell empty — constructed() runs during build(), before the line that sets tokio ever executes. Today’s code escapes that trap by timing rather than by ordering: nothing that needs the handle runs until GTK calls activate, and activate doesn’t fire until app.run(), long after new has returned with tokio set. Any window can reach the runtime through window.application(), downcast to GazetteApplication, and call tokio_handle().

Fetching, off the main thread

The fetch itself lives in a new file, src/fetch.rs, deliberately separate from feed.rs:

use std::fmt;

/// A single parsed entry from a feed. Plain data — not a GObject. It's
/// built on the Tokio runtime and only crosses onto the GLib main context
/// as a value, via `Feed::set_items`.
#[derive(Debug, Clone)]
pub struct FeedItem {
    pub title: String,
    pub link: String,
    pub summary: Option<String>,
}

#[derive(Debug)]
pub enum FetchError {
    Request(reqwest::Error),
    Parse(feed_rs::parser::ParseFeedError),
}

impl fmt::Display for FetchError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            FetchError::Request(e) => write!(f, "request failed: {e}"),
            FetchError::Parse(e) => write!(f, "couldn't parse feed: {e}"),
        }
    }
}

/// Fetches and parses a feed at `uri`. Runs entirely on the Tokio runtime —
/// nothing in this function, or anything it calls, touches a widget or a
/// GObject. That's what makes it safe to run off the GLib main thread.
pub async fn fetch_feed(uri: &str) -> Result<Vec<FeedItem>, FetchError> {
    let response = reqwest::get(uri)
        .await
        .map_err(FetchError::Request)?
        .error_for_status()
        .map_err(FetchError::Request)?;

    let bytes = response.bytes().await.map_err(FetchError::Request)?;

    let parsed = feed_rs::parser::parse(&bytes[..]).map_err(FetchError::Parse)?;

    Ok(parsed
        .entries
        .into_iter()
        .map(|entry| FeedItem {
            title: entry
                .title
                .map(|text| text.content)
                .unwrap_or_else(|| "Untitled".to_string()),
            link: entry
                .links
                .first()
                .map(|link| link.href.clone())
                .unwrap_or_default(),
            summary: entry.summary.map(|text| text.content),
        })
        .collect())
}

FeedItem is a plain struct rather than a glib::wrapper! type, and that matters: constructing a GObject means calling into GObject’s type system, and this function has no business doing that from a Tokio worker thread. fetch_feed produces data; something back on the main thread decides what GObject, if any, that data becomes.

error_for_status() matters more than it looks. Without it, reqwest::get resolves Ok for a 404, a 500, or a hosting provider’s error interstitial — the HTTP request itself succeeded even though the content is a lie. Skip the check and feed_rs::parser::parse gets handed an HTML error page instead of a feed, fails to parse it, and the caller sees FetchError::Parse for what was actually a request-level failure. Checking status before reading the body is what keeps Request meaning “didn’t get a real feed body at all” — whether the cause is DNS, a timeout, or a 404 — and Parse meaning “got a body and it wasn’t a feed.”

feed_rs::parser::parse takes anything implementing std::io::Read (a byte slice qualifies) and returns entries regardless of whether the source was RSS or Atom. Gazette’s four sample feeds are a mix of both — This Week in GNOME and From the Architect are Atom, LWN and the Hacker News mirror are RSS — and fetch_feed doesn’t need to know or care which. That format detection is feed-rs’s job, done once, before any of Gazette’s code sees an entry.

One thing worth knowing, not fixing here: reqwest::get is a convenience function that builds a fresh Client — and with it, a fresh connection pool and TLS session — on every call. Fine for a post about the boundary between two executors, wasteful in code that fetches the same handful of feeds over and over. Building a Client once and sharing it alongside the Tokio handle is a refinement for a later post, once persistence is in the picture.

Crossing back

The feed-selected handler is where the two executors actually meet:

obj.connect_closure(
    "feed-selected",
    false,
    glib::closure_local!(move |window: &super::GazetteWindow, feed: Feed| {
        eprintln!("feed selected: {} ({})", feed.name(), feed.uri());

        // The GLib executor owns `feed` and `window`; the Tokio
        // executor (below) only ever sees the URI string it needs
        // to fetch. Neither side touches the other's objects
        // directly — the `.await` on the join handle is the only
        // crossing.
        let tokio_handle = window
            .application()
            .and_downcast::<crate::application::GazetteApplication>()
            .expect("window has a GazetteApplication")
            .tokio_handle();
        let uri = feed.uri();

        glib::MainContext::default().spawn_local(async move {
            let result = tokio_handle
                .spawn(async move { crate::fetch::fetch_feed(&uri).await })
                .await;

            match result {
                Ok(Ok(items)) => feed.set_items(items),
                Ok(Err(fetch_err)) => {
                    eprintln!("fetch failed for {}: {fetch_err}", feed.name());
                }
                Err(join_err) => {
                    eprintln!(
                        "fetch task for {} did not complete: {join_err}",
                        feed.name()
                    );
                }
            }
        });
    }),
);

Read it from the outside in. glib::MainContext::default().spawn_local(async move { ... }) schedules the outer future on the GLib main context — the same executor that owns every widget — running it cooperatively alongside everything else, exactly like a signal handler. Because it’s confined to the main context, it’s allowed to hold feed and eventually call feed.set_items(...). That’s still executor-one territory.

Inside it, tokio_handle.spawn(async move { crate::fetch::fetch_feed(&uri).await }) hands the actual work to executor two. Handle::spawn returns immediately with a JoinHandle; it doesn’t block the caller, which is the entire point of calling it from the main thread. .awaiting that JoinHandle is where the outer future pauses: control genuinely returns to the GLib main loop, which goes on painting, handling input, and dispatching other signals while Tokio’s worker threads do the fetch. When the Tokio task finishes, the main loop resumes this specific future exactly where it left off, back on the main thread, with result now holding a value.

Why Ok(Ok(items)) and not just Ok(items)? Two different things can go wrong, and they’re wrapped separately. The outer Result comes from JoinHandle itself — its Err means the spawned task panicked or was cancelled, a Tokio-level failure that has nothing to do with feeds. The inner Result is fetch_feed’s own Result<Vec<FeedItem>, FetchError>, a normal, expected outcome of trying to fetch something over a network that might be down. Matching both layers explicitly is what forces you to decide what each one means, rather than letting ? collapse them into a single generic failure.

And a specific footgun: tokio::spawn(...), the free function, panics here — tokio_handle.spawn(...) doesn’t. The free function only works from inside a future that’s already running on a Tokio runtime. Called from the GLib main thread, which isn’t inside any Tokio runtime, it panics; the exact wording has changed across Tokio versions, but it always amounts to “no runtime found in this context.” Handle::spawn, called on the Handle cloned out in main(), is explicitly designed to work from any thread, runtime or not — that’s the entire reason GazetteApplication stores a Handle instead of a Runtime. If you ever see that panic, you’ve reached for the free function where you needed the handle.

Run the app now. Click Hacker News: after a brief pause — a real network round trip, with the window still live under your cursor — real headlines appear on stderr. Click LWN.net Headlines before the first fetch has printed anything, and both proceed independently.

Feed remembers what it fetched

set_items is doing real work in that handler, and Feed needs somewhere to put what it’s given:

use crate::fetch::FeedItem;

#[derive(Debug, Default, Properties)]
#[properties(wrapper_type = super::Feed)]
pub struct Feed {
    #[property(get, set)]
    pub name: RefCell<String>,
    #[property(get, set)]
    pub uri: RefCell<String>,
    #[property(get, set)]
    pub unread_count: Cell<u32>,

    // Plain data, not a property: `Vec<FeedItem>` has no `glib::Value`
    // mapping, and nothing outside this module needs to bind to it
    // directly. `items()` and `set_items()` are the accessors.
    pub items: RefCell<Vec<FeedItem>>,
}

impl Feed {
    pub fn items(&self) -> Vec<FeedItem> {
        self.imp().items.borrow().clone()
    }

    /// Replaces this feed's items and emits `items-updated`. The count
    /// crossing over from a real fetch is what makes `unread-count` real
    /// too, rather than the placeholder zero every sample feed starts with.
    pub fn set_items(&self, items: Vec<FeedItem>) {
        self.set_unread_count(items.len() as u32);
        self.imp().items.replace(items);
        self.emit_by_name::<()>("items-updated", &[]);
    }
}

items isn’t a #[property]: a Vec<FeedItem> has no glib::Value representation the way a String or a u32 does, and nothing outside Feed needs to bind a widget to the raw list. It’s a RefCell for the same reason selected_feed was one back in Part 5 — a value that changes over the object’s life, read from one place (items()), written from one place (set_items()).

The items-updated signal was declared back in Part 2, on a Feed that never actually got new items, then Part 5 dropped it entirely to avoid emitting ceremony for nothing. It comes back here on the same impl block that already derives Feed’s properties — with one change from Part 2’s sketch:

#[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").build()])
    }
}

Part 2’s version carried a u32 payload — the new item count, passed directly on the signal. This one carries nothing. Feed has an unread-count property now, so a listener that wants the count can just read feed.unread_count() instead of catching it off the emission. A signal that announces something changed and lets listeners go look is easier to evolve than one that ships a payload every listener has to keep accepting — that’s the shape the rest of this post builds on.

#[glib::derived_properties] has to stay on this impl, even though signals() has nothing to do with properties: it’s what generates properties(), property(), and set_property() from the #[property] fields on the struct above. Drop it while adding signals() and every #[property] accessor Feed already has — name(), uri(), set_unread_count() — silently stops working.

What’s different now is that set_items is the only thing that ever emits items-updated, and it’s only ever called with data that actually came off the network. set_unread_count runs first, before the emit, and the count that shows up in the sidebar is the number of items this fetch found.

That’s a narrower claim than “unread,” on purpose. Every fetch sets unread-count to the total item count, not the count of items the user hasn’t seen. Refetch a feed after reading everything in it and the badge goes straight back up to the full number. unread_count is standing in for a property Gazette doesn’t have the machinery to compute correctly yet — real read-tracking needs per-item state, which doesn’t exist until this series adds persistence. Until then, read the name as aspirational, not as a bug you need to chase.

A consumer for items-updated

set_items emits; something has to be listening. Each sample feed gets a logging handler when the store is built, in constructed():

let store = gio::ListStore::new::<Feed>();
for (name, uri) in SAMPLE_FEEDS {
    let feed = Feed::new(name, uri);

    // Reacting to items-updated is a separate job from fetching
    // them — the fetch (wired below, on feed-selected) never
    // logs directly, it just calls `feed.set_items(...)`.
    feed.connect_closure(
        "items-updated",
        false,
        glib::closure_local!(move |feed: Feed| {
            let items = feed.items();
            eprintln!("{}: {} items", feed.name(), items.len());
            for item in items.iter().take(3) {
                eprintln!("  - {}", item.title);
            }
        }),
    );

    store.append(&feed);
}

Notice the fetch code in feed-selected never calls eprintln! on success. It just calls feed.set_items(items) and stops. Printing what arrived is this closure’s job, connected once per feed, entirely separate from the code that went and got the data. That’s the same lesson Part 5 landed with the placeholder binding and the feed-selected logger: fetching is one job, reacting to what was fetched is another, and the signal between them is what keeps neither one needing to know the other exists. A future persistence layer connects its own handler to items-updated later without touching a line of fetch.rs.

Sharp edges

A RefCell borrow held across an .await fails the same way a borrow held across a signal emit did in Part 5, just harder to spot. The failure shape: let items = self.items.borrow_mut(); some_future.await; inside a spawn_local block, where the code resumed after the .await — or a handler running on a different turn of the main loop, if the borrow escapes further — tries to borrow the same cell. Signal handlers run synchronously, so a Part 5-style borrow panic happens right where you’d look for it. An .await point hands control back to the main loop for an arbitrary amount of time: anything else the loop dispatches in between, including another handler that reaches for the same RefCell, can trigger the panic somewhere that looks nothing like the code that caused it. Keep borrows scoped tightly, and never hold one across an .await.

What happens if you click the same feed five times in a row? Five independent fetches run concurrently, each racing to call set_items on the same Feed when it finishes — last one to land wins, and items-updated fires five times for one selection. Harmless for a post about the executor boundary, but worth knowing before you go adding a refresh action, which makes hammering that shortcut the obvious next thing to try. A real fix would track the in-flight JoinHandle on Feed and abort or ignore a new request while one’s outstanding — outside this post’s scope, but that’s where the fix would go.

window.application() returns None before the window has one, and expect turns that into a panic. In practice this never fires here: GazetteWindow::new always takes an application, and nothing runs feed-selected before the window exists. The expect documents an invariant rather than checking one — this window always has an application by the time it can receive input. If you ever construct a GazetteWindow without one, a test most likely, this is where it breaks.

What we have so far

Selecting a feed now does real work. A Tokio runtime, built once alongside the GTK application and never touched by it directly, does the actual fetching and parsing, and the only thing that ever crosses back onto the GLib main thread is a Result full of plain data. Feed::items-updated fires for real for the first time since Part 2 declared it, driven by whatever feed-rs found at the far end of a real URL.

Nothing about this displays anywhere yet — the items live in a RefCell a logging handler reads, and the sidebar still shows nothing but a name and a count. The fetch mechanism this post built doesn’t need to change at all to support that; it already hands off a Vec<FeedItem> to whatever wants to render it.

What comes next

That’s the gap the next post closes: an article list for the selected feed, a content pane for the selected article, and the adaptive layout that collapses both into a single pane on a narrow window. The two-executor pattern from this post doesn’t change to support any of it.

Further out, unread_count and items want somewhere durable to live, so a refetch doesn’t erase read state and a restart doesn’t lose it either. That’s the persistence layer this series has been setting up for since the OnceCell and RefCell conventions in Part 5 — a real place for items-updated to write to, instead of a logging handler standing in for one.

The source code at the end of this post lives on the part-6 branch of fromthearchitect/gnome-rust-gazette.

If the GObject machinery in here feels unfamiliar — mod imp, properties, signals — Part 2 is the reference. This is where those patterns stop being theoretical.

The click that goes nowhere

Right now, clicking a sidebar row does nothing. GTK draws a selection highlight, the row picks up its hover state, and that’s it — our code never sees the click. The whole point of the sidebar is that it drives the content pane, and we haven’t wired that yet.

By the end of this post, selecting a row drives everything to its right. The shape I keep coming back to in GTK apps is a chain — model to list to selection to signal to content — and getting those links in the right order is half the work. The other half is interior mutability: where state lives, when RefCell earns its place, when OnceCell does, and why the Rc<RefCell<T>> reflex most of us carry over from non-GUI Rust almost never belongs in a mod imp-shaped app. I’ll take each one where it comes up rather than in the abstract.

Concretely, we’ll build a real Feed GObject with name and uri properties, swap that frozen sidebar row for a gio::ListStore<Feed> seeded with four real feeds, define a custom feed-selected(Feed) signal on the window, and make the content pane react — feed name as the title, URL as the description, the empty-state placeholder showing only when nothing’s selected. That feed-selected signal is the seam Part 6 plugs Tokio into: the synchronous handler we write here gets joined by an asynchronous fetch handler that lives entirely in another file, and designing for that boundary now is the quieter lesson of the post.

Feed, for real

Part 2 sketched a Feed GObject — a title, an items-updated signal, the whole mod imp apparatus. None of it landed in source. We got away with it because Parts 3 through 4 only needed widgets, not data. That ends here. Before we can have a sidebar that means something, we need a model for what the sidebar contains.

Create src/feed.rs:

use gtk::glib;
use gtk::glib::Properties;
use gtk::prelude::*;
use gtk::subclass::prelude::*;
use std::cell::RefCell;

mod imp {
    use super::*;

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

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

    #[glib::derived_properties]
    impl ObjectImpl for Feed {}
}

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

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

Three things stand out against that Part 2 sketch. I left the signals out: items-updated was the right instinct — feeds change when fresh content arrives — but with no fetching code yet, emitting it would be ceremony for nothing, so it comes back in Part 6 alongside the Tokio fetcher that gives it something to announce. The properties use #[derive(Properties)] paired with #[glib::derived_properties], which is the modern declaration form: the macro generates the properties(), set_property(), and property() boilerplate from the struct fields, where the older tutorials you’ll still find hand-roll glib::ParamSpecString::builder("name").build(). Identical runtime behaviour, dramatically less typing, one fewer place to fat-finger a property name. And each field sits in a RefCell because properties have to be settable through GObject’s runtime API — that demands interior mutability, and RefCell is the simplest answer for fields written occasionally and read everywhere.

One thing about that NAME constant: it’s the GObject type name registered with the runtime. Prefix it with the application — GazetteFeed, not just Feed — so it doesn’t collide with another library’s Feed type. Names are global; collisions abort the process at type registration. Once your app loads a Feed type, no other library in the same process can.

Wire the module into src/main.rs:

mod application;
mod config;
mod feed;
mod window;

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

Feed is now a real type the rest of the codebase can build on.

A list bound to a model

The sidebar in window.blp currently has one hard-coded row:

ListBox feed_list {
  selection-mode: single;
  styles ["navigation-sidebar"]

  ListBoxRow {
    child: Label {
      label: _("All Articles");
      halign: start;
      margin-start: 12;
      margin-end: 12;
      margin-top: 6;
      margin-bottom: 6;
    };
  }
}

That row is frozen in the markup. It can’t grow, shrink, or change without touching the .blp file. Real apps don’t work that way — feeds get added, removed, renamed. The markup needs to describe the shape of a row, and the runtime needs to produce one row per item in some collection. GTK has a name for this pattern: model/view binding.

Strip the inner ListBoxRow out. The new sidebar block:

content: ScrolledWindow {
  child: ListBox feed_list {
    selection-mode: single;
    styles ["navigation-sidebar"]
  };
};

Empty ListBox. The rows come from Rust now.

In src/window.rs, add the imports we’ll need and grow the imp struct:

use std::cell::{OnceCell, RefCell};

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

use crate::Feed;

const SAMPLE_FEEDS: &[(&str, &str)] = &[
    ("This Week in GNOME", "https://thisweek.gnome.org/index.xml"),
    ("LWN.net Headlines",  "https://lwn.net/headlines/newrss"),
    ("Hacker News",        "https://hnrss.org/frontpage"),
    ("From the Architect", "https://fromthearchitect.dev/index.xml"),
];

mod imp {
    use super::*;

    #[derive(Debug, Default, gtk::CompositeTemplate)]
    #[template(resource = "/io/github/fromthearchitect/gazette/window.ui")]
    pub struct GazetteWindow {
        #[template_child]
        pub split_view: TemplateChild<adw::NavigationSplitView>,
        #[template_child]
        pub feed_list: TemplateChild<gtk::ListBox>,
        #[template_child]
        pub placeholder: TemplateChild<adw::StatusPage>,

        pub feeds: OnceCell<gio::ListStore>,
        pub selected_feed: RefCell<Option<Feed>>,
    }

    // ... ObjectSubclass impl unchanged
}

Two new fields. In the window’s ObjectImpl::constructed, populate the store and bind it:

impl ObjectImpl for GazetteWindow {
    fn constructed(&self) {
        self.parent_constructed();

        let store = gio::ListStore::new::<Feed>();
        for (name, uri) in SAMPLE_FEEDS {
            store.append(&Feed::new(name, uri));
        }
        self.feeds.set(store.clone()).expect("feeds set once");

        self.feed_list.bind_model(Some(&store), |item| {
            let feed = item.downcast_ref::<Feed>().expect("item is a Feed");
            gtk::Label::builder()
                .label(feed.name())
                .halign(gtk::Align::Start)
                .margin_start(12)
                .margin_end(12)
                .margin_top(6)
                .margin_bottom(6)
                .build()
                .upcast()
        });
    }
}

bind_model takes the store and a closure, and it accepts our store because gio::ListStore implements gio::ListModel — it binds against that trait, not the concrete type. That indirection is the part I actually care about: it’s what lets me wrap the store in a sort or filter model later without rewriting this call, which is exactly the refactor Gazette grows into once feeds need ordering. The mechanics from there are unremarkable — gtk::ListBox runs the closure once per item at bind time, then again whenever the model’s items-changed signal reports an add or change, and because the closure returns a bare gtk::Widget, ListBox wraps it in a GtkListBoxRow so we never construct one ourselves.

Run the app. The sidebar now shows four feeds — This Week in GNOME, LWN.net Headlines, Hacker News, From the Architect — and you can click between them. Selection still doesn’t do anything, but the rows are real.

One trap worth flagging — and a clarification about what that generic actually buys you. gio::ListStore::new::<Feed>() parameterises the store on the Rust side, and that’s worth doing: it keeps the typed API honest and documents what the store holds. But it’s a Rust-side convenience, not a hard runtime guarantee — at the GObject level the store holds plain glib::Object. So items coming back out of it — through item(), or through the ListModel interface a sort or filter model would hand you — still arrive as glib::Object and need the explicit and_downcast::<Feed>() you’ll see in the selection handler shortly. Parameterise with your concrete type, but treat it as intent and documentation, not as enforcement at the model boundary.

Where state lives

The imp struct now carries two things that aren’t template children: feeds and selected_feed. This is the right place for them. State on a GObject lives in the inner imp struct, never on the outer wrapper.

The reason is structural. GazetteWindow — the outer type — is a thin handle. glib::wrapper! makes it a transparent newtype around a refcounted pointer. Add a field to the outer type and you’ve added a field that won’t be shared between clones of the handle, won’t be visible across closures, and won’t survive being passed back through GTK’s C API. None of those failure modes is loud; the code compiles, the field exists, you set it, and then a second handle to the “same” window can’t see what you wrote.

The inner imp::GazetteWindow, by contrast, is the actual heap-allocated object. There’s exactly one of it per window, all handles point to it, and any code holding a handle can reach into it via obj.imp(). State you want every part of the app to agree on goes there.

This is one of the framework’s rules rather than something you can derive from first principles, and I learned it the slow way — by adding a field to the outer type, setting it, and then losing an afternoon to state that silently wasn’t shared between two handles to the “same” window. Memorise it — state lives in imp — and a surprising number of the architectural questions you might have about a GTK Rust app stop being questions.

Which cell?

feeds: OnceCell<gio::ListStore> and selected_feed: RefCell<Option<Feed>> — two different cells for two different lifetimes, and the difference is the whole point. The feeds store is built once in constructed() and read forever after, never replaced; that’s exactly what OnceCell is for, and its set returning Err when it’s already been set means the code asserts that contract for me instead of trusting me to remember it. The selected_feed changes every time the user picks a different row, so it needs the ongoing mutability RefCell gives. (A third category needs no cell at all: values the GObject machinery sets once at construction — template children, derived properties — that your own code never touches again.)

RefCell adds a runtime borrow check: borrow() and borrow_mut() panic if you take incompatible borrows at once. In this domain that’s exactly what I want — GTK callbacks run on the main thread one at a time, so the panic only fires when my code has gone re-entrant in a way I didn’t notice, and the first time it happened to me it pointed straight at a bug class I’d otherwise have spent an afternoon bisecting.

Notice the gio::ListStore itself isn’t wrapped in RefCell, even though we mutate it constantly with store.append(...). ListStore is a GObject, and GObjects do their own reference counting and stay mutable through their GObject API without needing Rust-side cells. Wrapping it would compile but be redundant — you’d be borrow-checking access to a pointer.

My rule of thumb, after enough of these: template children and properties are naked fields with the right macro attribute; anything that owns a GObject — a gio::ListStore, another widget — is a naked field or an OnceCell, never a RefCell; a Rust value that genuinely mutates gets a RefCell, or a Cell if it’s Copy; and a value set once and read everywhere gets a OnceCell. Once that split is reflexive, most of the “which wrapper goes here?” questions stop being questions.

Wiring selection, and the clone! macro

The rows render but selecting them does nothing. Wire selection up:

let obj = self.obj();
self.feed_list.connect_row_selected(glib::clone!(
    #[weak] obj,
    move |_, row| {
        let feed = row
            .and_then(|row| row.index().try_into().ok())
            .and_then(|i: u32| obj.imp().feeds.get().unwrap().item(i))
            .and_downcast::<Feed>();

        obj.imp().selected_feed.replace(feed.clone());

        if let Some(feed) = feed {
            obj.emit_by_name::<()>("feed-selected", &[&feed]);
        }
    }
));

(We define the feed-selected signal in the next section. Pretend it exists for a moment.)

The glib::clone! macro is doing a lot of work. Without it, the equivalent is:

let obj_weak = obj.downgrade();
self.feed_list.connect_row_selected(move |_, row| {
    let Some(obj) = obj_weak.upgrade() else { return };
    // ... rest of the closure ...
});

The macro hides the downgrade() / upgrade() dance. The #[weak] attribute means the closure holds a weak reference to obj: it doesn’t keep the window alive. When the closure runs, the macro tries to upgrade the weak reference; if the window is gone, the closure returns early.

The alternative is #[strong], which captures by clone, incrementing the refcount. You almost never want that for a closure connected to one of the window’s own widgets, because it builds a reference cycle:

• The window owns the widget.
• The widget owns the signal handler (the closure).
• The closure now strongly owns the window.

The window can’t drop because the widget’s closure points to it; the widget can’t drop because the window owns it; the closure can’t drop because the widget holds it. Your app appears to leak windows on close. #[weak] breaks the cycle — the closure points weakly back at the window, and when the window’s last strong reference is released, the chain unwinds cleanly.

This is the most common GTK Rust memory leak I run into, and it hides well: most apps have one window for their whole lifetime, so nothing looks wrong until you write a multi-window app — or, in my case, a test that spun windows up and tore them down in a loop, where the slowly climbing memory finally gave it away. The fix is always the same: weak the captures into widget-connected closures.

(One bit of translation if you’re reading older code: the clone!(@weak obj => move |...| {...}) syntax was deprecated in glib 0.20. The #[weak] attribute form is the current spelling. They behave identically.)

A custom signal on GazetteWindow

The selection handler emits feed-selected, but we haven’t defined it. Adding a custom signal is the same pattern as Part 2’s Feed::items-updated, plugged into the window instead of the model.

In mod imp in src/window.rs, give ObjectImpl a signals() method:

use std::sync::OnceLock;
use glib::subclass::Signal;

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

    fn constructed(&self) {
        self.parent_constructed();
        // ... store setup, bind_model, connect_row_selected ...
    }
}

signals() is a static method GObject calls once, when the type is first registered, to learn what signals it defines. The OnceLock cache is conventional — GObject doesn’t require it, but it means the vec! allocation only runs once. (Note this is std::sync::OnceLock, the thread-safe one: a static has to be Sync, so the single-threaded std::cell::OnceCell we reached for in the imp fields wouldn’t compile here — same family, different guarantees.) Our signal is named "feed-selected" and carries one parameter, a Feed.

That’s enough to make the emit_by_name call in the selection handler legal. But a signal with no listeners does nothing — so let’s give it a consumer. The handler decides what to do when a feed is selected: update the placeholder.

let obj = self.obj();
obj.connect_closure(
    "feed-selected",
    false,
    glib::closure_local!(
        #[weak] obj,
        move |_window: &super::GazetteWindow, feed: Feed| {
            let imp = obj.imp();
            imp.placeholder.set_icon_name(Some("rss-symbolic"));
            imp.placeholder.set_title(&feed.name());
            imp.placeholder.set_description(Some(&feed.uri()));
        }
    ),
);

A few new pieces:

• connect_closure is the lower-level form of signal connection. We need it because the signal is custom — there’s no auto-generated connect_feed_selected method, so we connect by name.
• glib::closure_local! wraps the Rust closure in a glib::Closure the GObject system can store. It’s the bridge between Rust closures and GObject’s signal machinery, and it accepts the same #[weak] / #[strong] attributes as clone!.
• false is the after flag — whether this handler runs before or after the other handlers connected to the signal. It’s easy to read it as “after the default handler,” but that’s a separate mechanism (the handler baked into the type definition); after only orders you against the other external connections. With a single handler it makes no difference; by convention, pass false unless you specifically need to run last.

Two handlers now exist on feed-selected: the implicit one in connect_row_selected that emits it, and the explicit one in connect_closure that consumes it. Neither side names the other; the signal is all they share.

Run the app. Click This Week in GNOME; the content pane updates to show the feed name as the title and the URL as the description. Click Hacker News; it switches. Selection has meaning now.

When Rc<RefCell<T>> isn’t the answer

The instinct, especially coming from non-GUI Rust, is to reach for Rc<RefCell<T>> whenever two closures need to share mutable state — it’s the canonical answer to “shared mutable state without locks,” and my first couple of GTK apps were quietly littered with it.

Suppose both connect_row_selected and the feed-selected handler wanted to read the currently-selected Feed. The wrong instinct produces this:

// Don't do this.
let selected = std::rc::Rc::new(std::cell::RefCell::new(None::<Feed>));

let selected_clone = selected.clone();
self.feed_list.connect_row_selected(move |_, row| {
    *selected_clone.borrow_mut() = /* derive feed from row */ None;
});

let selected_clone = selected.clone();
obj.connect_closure("feed-selected", false, glib::closure_local!(
    move |_window: &super::GazetteWindow, _feed: Feed| {
        let _current = selected_clone.borrow();
        // ...
    }
));

This compiles, runs, and is reasonable Rust outside the GTK context. Inside it, the state belongs in imp:

self.feed_list.connect_row_selected(glib::clone!(
    #[weak] obj,
    move |_, row| {
        let feed = /* derive feed from row */;
        obj.imp().selected_feed.replace(feed);
    }
));

Both closures already reach the same selected_feed through obj.imp(). There’s no need for an additional Rc — GObject’s reference counting is the Rc. There’s no need for a separate RefCell — the field is already in one on the imp struct.

The rule of thumb: any time you find yourself typing Rc<RefCell<T>> inside an imp block, stop. The state you’re trying to share lives on the imp; closures reach it through obj.imp(); the GObject lifecycle handles the sharing. It can be appropriate at the edges of a system — prototyping a small example without a wrapping GObject — but inside a real GObject-based architecture, it’s a smell.

Binding the view to state

The placeholder updates imperatively inside the feed-selected handler — three set_* calls per selection. bind_property promises to replace that with a declarative link, and the tempting move is to drop it straight into the handler:

// Tempting, and wrong.
feed.bind_property("name", &*imp.placeholder, "title")
    .sync_create()
    .build();

This compiles and looks right — select a feed, the title updates — and I shipped exactly this shape once and didn’t notice for weeks. The catch is that the handler runs once per selection, so every click builds a fresh glib::Binding and nothing tears down the previous one. Click between four feeds and the placeholder’s title now has four live bindings pointing at it, each holding a reference to a feed. They stay quiet only because a feed’s name never changes after creation — and the moment it does, which is exactly what Part 6’s fetcher will make happen, every stale binding fires and an unselected feed can overwrite the selected one’s title. A binding built in a per-event handler is a leak with a delay on it.

The fix isn’t to manage the binding’s lifetime by hand. It’s to notice what the placeholder actually is: a pure function of which feed is selected. That’s state, and we have a rule for state — it lives in imp. Promote selected_feed from a plain field to a GObject property, and the placeholder can bind to it once, for the life of the window.

Add the Properties derive to the window’s imp struct and annotate the field:

#[derive(Debug, Default, gtk::CompositeTemplate, glib::Properties)]
#[properties(wrapper_type = super::GazetteWindow)]
#[template(resource = "/io/github/fromthearchitect/gazette/window.ui")]
pub struct GazetteWindow {
    #[template_child]
    pub split_view: TemplateChild<adw::NavigationSplitView>,
    #[template_child]
    pub feed_list: TemplateChild<gtk::ListBox>,
    #[template_child]
    pub placeholder: TemplateChild<adw::StatusPage>,

    pub feeds: OnceCell<gio::ListStore>,
    #[property(get, set, nullable)]
    pub selected_feed: RefCell<Option<Feed>>,
}

Add #[glib::derived_properties] above the window’s impl ObjectImpl block — the same pairing Feed already uses. nullable is what lets the property hold None: nothing is selected at startup, and the user can clear the selection later.

The selection handler now sets the property instead of replacing the cell directly. Going through the generated setter is what emits notify::selected-feed, and that notification drives the binding:

self.feed_list.connect_row_selected(glib::clone!(
    #[weak] obj,
    move |_, row| {
        let feed = row
            .and_then(|row| row.index().try_into().ok())
            .and_then(|i: u32| obj.imp().feeds.get().unwrap().item(i))
            .and_downcast::<Feed>();

        obj.set_selected_feed(feed.as_ref());

        if let Some(feed) = feed {
            obj.emit_by_name::<()>("feed-selected", &[&feed]);
        }
    }
));

Then bind the placeholder to the property once, in constructed:

obj.bind_property("selected-feed", &*self.placeholder, "title")
    .transform_to(|_, feed: Option<Feed>| {
        Some(feed.map_or_else(
            || "No Feed Selected".to_string(),
            |feed| feed.name(),
        ))
    })
    .sync_create()
    .build();

obj.bind_property("selected-feed", &*self.placeholder, "description")
    .transform_to(|_, feed: Option<Feed>| {
        Some(feed.map_or_else(
            || "Select a feed from the sidebar to see its articles.".to_string(),
            |feed| feed.uri(),
        ))
    })
    .sync_create()
    .build();

transform_to runs whenever the source changes, mapping the selected Feed to a string for the target. The None arm matters as much as the Some arm: when the selection clears, the binding restores the empty-state text — the placeholder handles deselection for free, with no code in the handler. sync_create() copies the current value (None at startup) the moment the binding is built, which is why the placeholder reads “No Feed Selected” before anything is clicked.

With the placeholder now driven by the property, the feed-selected placeholder handler has nothing left to do — delete it. And that deletion sharpens the point about routing through a signal. Reflecting state in the UI — the title just following the selection — is a binding’s job: declarative, set up once. Acting on a change — fetching the feed, logging, anything with a side effect — is a signal’s job, and feed-selected stays exactly for that. The placeholder was never really a signal consumer; it was a view of state, and now it’s wired that way.

So what does listen to feed-selected now? For the moment, a logger — proof the seam works:

obj.connect_closure(
    "feed-selected",
    false,
    glib::closure_local!(
        move |_window: &super::GazetteWindow, feed: Feed| {
            eprintln!("feed selected: {} ({})", feed.name(), feed.uri());
        }
    ),
);

Run, click feeds, watch the terminal. Two independent things now happen on every selection: the placeholder updates through the property binding, and the log prints through the signal handler — and neither is wired to the other. Part 6 connects a second handler to the same signal, an async fetcher that reads the feed’s URL, and it slots in without the binding or this logger ever knowing it arrived.

Sharp edges

A few things that bite, all on the GObject-runtime seam where Rust’s compile-time guarantees stop and GObject’s runtime conventions begin.

Signal names aren’t checked

emit_by_name::<()>("feed-selected", ...) compiles fine if you typo the name. It fails at runtime when the type system can’t find a signal by that exact string, and panics with a message about a name lookup miss. There’s no compile-time check. The remedies: care, integration tests that exercise every signal path, or const-ing the name in one place and using it in both signals() and the emit sites.

connect_row_selected fires with None on deselection

When the selection clears — programmatically, or because something else takes focus — row is None. Code that always assumes a feed exists goes quietly wrong. Branch on row early; the Option is part of the API for a reason.

Borrow panics inside signal handlers

If you hold a RefCell borrow across a signal emission and a handler for that signal tries to borrow the same cell, you panic — signal handlers run synchronously, so the emit doesn’t return until they’re done. The shape that triggers it: let mut state = self.thing.borrow_mut(); followed immediately by obj.emit_by_name::<()>(...), still inside that borrow. The fix is to scope the borrow tightly so it ends before you emit. (The derived property setters are safe here: each scopes its own borrow_mut, writes, and returns before GObject emits notify.)

Kebab-case at the GObject level, snake_case in Rust

A struct field selected_feed becomes the property selected-feed in bind_property and friends, with accessors selected_feed() / set_selected_feed(...) on the Rust side. The derive macro does the conversion. Mistype the kebab-case form — bind_property("selected_feed", ...) — and the binding fails to find a property by that name. Not silently: GLib prints a g_warning to stderr and the binding does nothing.

What we have so far

Selecting a feed does something. The structure model → list → selection → signal → content is in place, and four real RSS feeds populate the sidebar at startup. The state we added — feeds: OnceCell<gio::ListStore>, selected_feed as a nullable property — lives in imp, where the GObject machinery already manages sharing across closures and lifetimes. Rc<RefCell<T>> doesn’t appear anywhere in this codebase, and probably won’t.

The feed-selected signal is a deliberate seam. The placeholder doesn’t even use it — selection state flows through a property binding instead, because reflecting state and reacting to events are different jobs. The signal is for reacting: right now a single logging handler listens.

What comes next

That logging handler is a placeholder for the real one. Part 6 — Fetching Feeds — connects an asynchronous fetcher to feed-selected: it hits each feed’s URL, parses the RSS or Atom response, and emits the items-updated signal we deferred back at the top of this post as articles arrive.

That fetcher needs a runtime GTK doesn’t have. Part 6 explains why GTK is single-threaded around a single main loop, why blocking that loop freezes the window, and how the two-executor pattern lets Tokio do network work without ever touching a widget on the wrong thread. The seam we built here is what it plugs into.

The source code at the end of this post lives on the part-5 branch of fromthearchitect/gnome-rust-gazette.

If you’re new to this stack and wondering why GTK and libadwaita are separate libraries, why GObject’s type system feels like 1990s C, or why Flatpak ships its own runtime alongside your app, there’s a short companion piece on the history of the stack. Skim it for context or skip it for code.

The XML problem

At the end of Part 3, we had a working app. A header bar, a hamburger menu, a “Hello, World!” label, and a window.ui file that looked like this:

<?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>
        ...

Read that aloud. Notice how much of it is structural noise — <object class="...">, <property name="...">, opening and closing tags wrapping single values. The actual information — “there’s a header bar with a menu button on the right” — is buried under a layer of XML scaffolding. And we haven’t even built any UI yet.

This isn’t a fixable problem in XML. It’s how XML works. So GNOME has a different answer.

Blueprint

Blueprint is a markup language built for GTK. It compiles to the same .ui XML GTK has always loaded — the runtime artefact is identical — but the file you actually write looks like real code:

using Gtk 4.0;
using Adw 1;

template $GazetteWindow : Adw.ApplicationWindow {
  title: _("Gazette");
  default-width: 800;
  default-height: 600;

  content: Adw.ToolbarView {
    [top]
    Adw.HeaderBar {
      [end]
      MenuButton {
        primary: true;
        icon-name: "open-menu-symbolic";
        tooltip-text: _("Main Menu");
        menu-model: primary_menu;
      }
    }

    content: Label label {
      label: _("Hello, World!");

      styles ["title-1"]
    };
  };
}

menu primary_menu {
  section {
    item {
      label: _("_Preferences");
      action: "app.preferences";
    }
    item {
      label: _("_Keyboard Shortcuts");
      action: "app.shortcuts";
    }
    item {
      label: _("_About Gazette");
      action: "app.about";
    }
  }
}

Same widget tree. Same template binding. Same translatable strings. About a third the line count, and you can actually scan the structure without your eyes glazing over.

Two bits of syntax are worth knowing up front. The $ on $GazetteWindow is there because it’s a user-defined type — the compiler can’t validate it against a .gir, so the $ is your acknowledgement that you know what you’re doing. Built-in types like Adw.ApplicationWindow never need it. And [top], [end] are child types, equivalent to <child type="top"> in XML, placed immediately before the child they apply to. The rest — using for namespace imports, _("...") for translatable strings, styles ["..."] for CSS classes — you can pick up by porting.

Wiring Blueprint into the build

Blueprint is a separate compiler, not a built-in GTK feature. Before we change any UI, we need to teach Meson how to invoke it and update the GResource manifest to bundle the generated .ui files instead of the original ones.

Is blueprint-compiler available?

blueprint-compiler ships in the GNOME 50 SDK (which we upgraded to at the end of Part 3), so inside the Flatpak build sandbox we don’t need to install anything. If you’re targeting an older runtime where it isn’t included, you’d add it as a module in the Flatpak manifest:

"modules" : [
    {
        "name" : "blueprint-compiler",
        "buildsystem" : "meson",
        "cleanup" : ["*"],
        "sources" : [
            {
                "type" : "git",
                "url" : "https://gitlab.gnome.org/GNOME/blueprint-compiler.git",
                "tag" : "v0.20.4"
            }
        ]
    },
    {
        "name" : "gazette",
        ...
    }
]

For us on GNOME 50, that block isn’t necessary. Just confirming the binary exists is enough.

Updating src/meson.build

Open src/meson.build. We need to add a custom_target that runs blueprint-compiler batch-compile over our .blp files and produces matching .ui files in the build directory. Then we point the existing gnome.compile_resources call at those generated files via a dependency.

Here’s the relevant addition, sitting just above the existing compile_resources call:

blueprints = custom_target('blueprints',
  input: files(
    'window.blp',
    'shortcuts-dialog.blp',
  ),
  output: '.',
  command: [
    find_program('blueprint-compiler'),
    'batch-compile',
    '@OUTPUT@',
    '@CURRENT_SOURCE_DIR@',
    '@INPUT@',
  ],
)

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

The dependencies: blueprints line is what ties the two together. Without it, Meson might try to compile resources before Blueprint has produced the .ui files, and you’ll get a mystifying “file not found” error mid-build.

gazette.gresource.xml is unchanged

The resource manifest still references window.ui and shortcuts-dialog.ui. It doesn’t mention .blp at all — and that’s the part that catches people.

<?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>

That’s because gnome.compile_resources looks for the listed files first in the source directory, then in the build directory — and our custom_target writes the generated .ui files into the build directory at exactly the right relative path. The Rust code referencing /io/github/fromthearchitect/gazette/window.ui doesn’t know or care that the file went through a Blueprint compile step on the way in.

This is the bit I want you to internalise: Blueprint is purely a build-time concern. The runtime artefact is identical. If anything goes wrong at runtime, it’s a GTK problem, not a Blueprint problem — and the error messages will reference XML structures because that’s what GTK sees.

Updating POTFILES.in

Open po/POTFILES.in. Builder’s scaffold lists one source file alongside the desktop integration files:

data/io.github.fromthearchitect.gazette.desktop.in
data/io.github.fromthearchitect.gazette.metainfo.xml.in
data/io.github.fromthearchitect.gazette.gschema.xml
src/window.ui

Two changes. First, point at window.blp instead of window.ui. Second, add shortcuts-dialog.blp — Builder doesn’t list it, but the strings in there need extracting too:

data/io.github.fromthearchitect.gazette.desktop.in
data/io.github.fromthearchitect.gazette.metainfo.xml.in
data/io.github.fromthearchitect.gazette.gschema.xml
src/shortcuts-dialog.blp
src/window.blp

Why point at the .blp files rather than the generated .ui files? Gettext extracts strings by parsing source files for known patterns — _("...") in Blueprint, translatable="yes" in XML, gettext!() in Rust, etc. If POTFILES.in lists the generated .ui files, extraction will work, but the line numbers in your .po files will reference auto-generated paths in the build directory that change between builds. Pointing at the .blp source means translators see meaningful filenames and stable line numbers.

The Meson i18n module’s xgettext invocation already scans for _(...) and C_(...) calls regardless of file type, so listing .blp files works without any Blueprint-specific extractor.

Porting the existing UI files

Now the actual conversion. Two files: window.ui and shortcuts-dialog.ui.

If you had dozens of files to convert, you’d run blueprint-compiler port from the project root and it would scan the project, generate .blp versions of every .ui file, and update the references for you. We’ve got two files, so it’s just as quick to do it by hand and learn the syntax in the process.

window.blp

Delete src/window.ui. Create src/window.blp:

using Gtk 4.0;
using Adw 1;

template $GazetteWindow : Adw.ApplicationWindow {
  title: _("Gazette");
  default-width: 800;
  default-height: 600;

  content: Adw.ToolbarView {
    [top]
    Adw.HeaderBar {
      [end]
      MenuButton {
        primary: true;
        icon-name: "open-menu-symbolic";
        tooltip-text: _("Main Menu");
        menu-model: primary_menu;
      }
    }

    content: Label label {
      label: _("Hello, World!");

      styles ["title-1"]
    };
  };
}

menu primary_menu {
  section {
    item {
      label: _("_Preferences");
      action: "app.preferences";
    }
    item {
      label: _("_Keyboard Shortcuts");
      action: "app.shortcuts";
    }
    item {
      label: _("_About Gazette");
      action: "app.about";
    }
  }
}

Compare against the original XML if you want — every property, child, and string carries across one-to-one.

The one thing worth pointing out is Label label. In Blueprint, when you want to give a widget an ID (so the Rust side can grab it as a TemplateChild), you put the ID after the type, with no id: keyword. It feels weird at first if you’re coming from XML’s <object class="GtkLabel" id="label">, but it’s consistent with how the rest of the language treats names.

shortcuts-dialog.blp

Builder’s template for shortcuts-dialog.ui is built around Gtk.ShortcutsWindow, which was deprecated in GTK 4.18; libadwaita 1.8 shipped a successor, Adw.ShortcutsDialog. Since Part 3 put us on GNOME 50 (libadwaita 1.9), we’ll port to the modern widget while we’re already in the file.

Delete src/shortcuts-dialog.ui and create src/shortcuts-dialog.blp:

using Gtk 4.0;
using Adw 1;

Adw.ShortcutsDialog shortcuts_dialog {
  Adw.ShortcutsSection {
    title: C_("shortcut window", "General");

    Adw.ShortcutsItem {
      title: C_("shortcut window", "Show Shortcuts");
      action-name: "app.shortcuts";
    }

    Adw.ShortcutsItem {
      title: C_("shortcut window", "Quit");
      action-name: "app.quit";
    }
  }
}

C_("context", "string") is the Blueprint equivalent of XML’s <attribute name="label" translatable="yes" context="shortcut window"> — gettext context lets translators distinguish the same English word used in different UI contexts. Builder generates these for shortcut dialogs because “General” might translate differently depending on whether it’s a settings category or a shortcut group.

The other thing worth knowing about this file is the widget ID. shortcuts_dialog is what AdwApplication looks for: if a shortcuts-dialog.ui resource exists at the application’s resource base path and its root widget is an AdwShortcutsDialog with that ID, the application class automatically installs an app.shortcuts action that presents the dialog, plus a Ctrl+? accelerator. That’s why Part 3’s menu could reference app.shortcuts even though we never defined it ourselves.

The migration mapping, if you’re updating an older project: Gtk.ShortcutsWindow → Adw.ShortcutsDialog, Gtk.ShortcutsGroup → Adw.ShortcutsSection, Gtk.ShortcutsShortcut → Adw.ShortcutsItem. The old “view → section → group → shortcut” hierarchy collapsed to “section → item”. Two features didn’t survive the trip: gesture shortcuts and per-shortcut icons. If you needed those, you stay on the deprecated widget. We don’t, so we don’t.

Build it

Hit Run. If everything is wired correctly, the app builds and launches looking exactly like it did at the end of Part 3.

If you get build errors, the most common causes are:

• Forgot the dependencies: blueprints line — error references window.ui not found.
• Typo in a Blueprint file — the compiler error is good, but it points at line numbers in the .blp, not the generated XML.
• Old .ui file still on disk — if you copied the .blp instead of replacing the .ui, both exist and the resource bundle will pick up whichever Meson finds first.

A clean rebuild (Builder’s Build → Clean Build Output) clears up most of these.

Now we have a foundation. Let’s actually use it.

A “Hello, World!” label is fine for proving the pipeline works. It is not Gazette. Gazette needs a sidebar of feeds and an articles pane. On a phone, only one shows at a time.

Libadwaita has a widget for this exact pattern: Adw.NavigationSplitView. Side-by-side on a wide screen, single-pane navigation when collapsed — at least, once you wire up the breakpoint that tells it when to collapse. We’ll get to that.

Replace the contents of window.blp with this:

using Gtk 4.0;
using Adw 1;

template $GazetteWindow : Adw.ApplicationWindow {
  title: _("Gazette");
  default-width: 1000;
  default-height: 700;

  Adw.Breakpoint {
    condition ("max-width: 600sp")

    setters {
      split_view.collapsed: true;
    }
  }

  content: Adw.NavigationSplitView split_view {
    sidebar: Adw.NavigationPage {
      title: _("Feeds");

      child: Adw.ToolbarView {
        [top]
        Adw.HeaderBar {}

        content: ScrolledWindow {
          child: ListBox feed_list {
            selection-mode: single;

            styles ["navigation-sidebar"]

            ListBoxRow {
              child: Label {
                label: _("All Articles");
                halign: start;
                margin-start: 12;
                margin-end: 12;
                margin-top: 6;
                margin-bottom: 6;
              };
            }
          };
        };
      };
    };

    content: Adw.NavigationPage {
      title: _("Articles");

      child: Adw.ToolbarView {
        [top]
        Adw.HeaderBar {
          [end]
          MenuButton {
            primary: true;
            icon-name: "open-menu-symbolic";
            tooltip-text: _("Main Menu");
            menu-model: primary_menu;
          }
        }

        content: Adw.StatusPage placeholder {
          icon-name: "rss-symbolic";
          title: _("No Feed Selected");
          description: _("Select a feed from the sidebar to see its articles.");
        };
      };
    };
  };
}

menu primary_menu {
  section {
    item {
      label: _("_Preferences");
      action: "app.preferences";
    }
    item {
      label: _("_Keyboard Shortcuts");
      action: "app.shortcuts";
    }
    item {
      label: _("_About Gazette");
      action: "app.about";
    }
  }
}

The window is bigger by default — 1000x700 instead of 800x600 — to give two panes room to breathe. Adw.NavigationSplitView replaces the single Adw.ToolbarView, with a sidebar and a content, each holding an Adw.NavigationPage. Each pane gets its own Adw.ToolbarView and Adw.HeaderBar — the libadwaita pattern is that every pane owns its own chrome, so when the layout collapses on narrow screens each one has a working header bar with title and back button. The sidebar’s ListBox carries the navigation-sidebar style class for the standard look; the content pane shows an Adw.StatusPage empty state using rss-symbolic from adwaita-icon-theme. The hamburger menu has moved to the content pane’s header bar — that’s where it lives in most GNOME apps with this layout (Files, Music, Lollypop, Apostrophe).

The bit that catches people: Adw.NavigationSplitView doesn’t collapse on its own. Drop the window narrower without an Adw.Breakpoint and it just stays side-by-side, ignoring you. The breakpoint is what flips split_view.collapsed to true when the window narrows below 600 scaled pixels — adaptive behaviour is a property you set, not something the widget figures out. The sp unit (scaled pixels) means the threshold respects the user’s text scaling factor, so the layout collapses at the same effective width regardless of how big they’ve made their fonts.

Hit Run again.

The hamburger menu wires up unchanged — same app.shortcuts, app.about, and (still unimplemented) app.preferences actions Builder generated in Part 3:

And dragging the window narrower trips the breakpoint, collapsing the split view to single-pane navigation:

The Rust side

Open src/window.rs. Right now it has one TemplateChild for the label we just deleted:

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

Two things to update. First, the label field doesn’t refer to anything any more — there’s no Label label in the new window.blp. Second, we want typed handles to the new widgets so future posts can react to them.

Replace the struct with:

#[derive(Debug, Default, gtk::CompositeTemplate)]
#[template(resource = "/io/github/fromthearchitect/gazette/window.ui")]
pub struct GazetteWindow {
    #[template_child]
    pub split_view: TemplateChild<adw::NavigationSplitView>,
    #[template_child]
    pub feed_list: TemplateChild<gtk::ListBox>,
    #[template_child]
    pub placeholder: TemplateChild<adw::StatusPage>,
}

Note that the #[template(resource = ...)] path is unchanged. We didn’t rename the resource path when we switched to Blueprint — window.ui is still what gets bundled into the gresource at /io/github/fromthearchitect/gazette/window.ui, it’s just generated from window.blp now. Keeping the resource path stable is what lets the rest of the code be oblivious to the source format change.

Build and run. Same window, three new typed handles available for when we need them.

Sharp edges

Editor support

The official Blueprint compiler ships an LSP server. In GNOME Builder, support is built in — you get syntax highlighting, completion, and inline error markers automatically. In VS Code, install the Blueprint extension. In Neovim, configure nvim-lspconfig with blueprint_ls. The LSP knows about every property and signal of every widget — if you mistype defautl-width, you’ll see the squiggle before you save.

Error message lineage

When Blueprint fails to compile, the error references your .blp file with helpful line and column numbers. When GTK fails to load a .ui template at runtime — usually because you referenced a widget that doesn’t exist, or the parent doesn’t match the Rust ParentType — the error references the generated .ui file. The line numbers won’t match your .blp. That’s fine, the structure does, but it catches everyone the first time.

Blueprint can’t express everything

Blueprint covers the GTK Builder XML format completely, but a handful of edge cases require dropping back to either raw XML or runtime Rust code. The most common one I hit is custom GtkBuilder-loaded scriptable types where a property takes a complex serialised value. If you need it, you can mix .ui and .blp files in the same gresource — just list the .ui ones in the gazette.gresource.xml manifest and skip them in the Blueprint custom target.

Don’t commit the generated .ui files

The build directory holds the generated XML. Builder’s default .gitignore already excludes _build/, but if you set up a different build layout, double-check. Committing generated .ui files leads to merge conflicts every time someone tweaks a .blp.

What we have so far

A window.blp and shortcuts-dialog.blp instead of XML. A working sidebar + content layout that’s adaptive on small screens. Three typed widget handles in Rust waiting for behaviour. The same single-instance app, the same gresource path, the same menu, the same translations — but the file you actually edit when you want to change the UI now reads like a tree, not a tag soup.

What comes next

We have widgets. We don’t have any logic. Clicking a row in the sidebar does nothing. Adding a feed isn’t possible. There’s no state.

Part 5 is App Architecture Patterns — how to organise mutable state in a Rust GTK app without losing your mind. The big shape of it: GTK widgets aren’t Send, Rc<RefCell<T>> is everywhere, the clone! macro keeps closures sane, and async work lives on Tokio while UI work lives on the GLib main loop. We’ll set up the two-executor pattern and use it to wire the sidebar selection to the content pane via a real GObject signal.

That’s the post where the patterns from Part 2 stop being theoretical.

The source code at the end of this post lives on the part-4 branch of fromthearchitect/gnome-rust-gazette.

By the end of Part 3 you had a running GTK 4 + libadwaita app with five trait implementations, a mod imp block, an adw::Application parent class, a meson.build next to your Cargo.toml, and a Flatpak manifest pinning a runtime version. None of those decisions arrived in 2026 fully formed. Each is a fossil of a specific argument that took years to settle.

This is the short version of those arguments. The platform you’re writing against is shaped by five fights — over licence, components, design, toolkit independence, and distribution — and once you’ve heard the fights, the conventions stop feeling arbitrary.

1. The licence fight (1996–2000)

In 1996 the dominant Unix GUI toolkit was Motif, owned by the Open Software Foundation and proprietary in a way that mattered: you couldn’t ship free software against it without commercial licensing. Spencer Kimball and Peter Mattis, two Berkeley undergrads writing the GIMP paint program, wrote their own toolkit instead and called it the GIMP Toolkit — GTK. Within a few years the toolkit had outgrown the paint program. It is now what most of the free desktop is built on.

The same year, Trolltech released Qt 1.0 and Matthias Ettrich announced KDE on top of it. Qt was technically excellent, but its licence wasn’t one the Free Software Foundation recognised until 2000. Between 1996 and 2000, a substantial part of the GNU community considered KDE non-free regardless of source availability.

In August 1997, Miguel de Icaza and Federico Mena announced GNOME — explicitly framed as a free-software desktop that didn’t depend on Qt. The technical justifications (component model, accessibility, language bindings) were in the announcement; the political one — you should not have to choose between a working desktop and a free-software stack — is what gave the project momentum. Qt was relicensed under the GPL in 2000 and the original objection mostly evaporated, but by then GNOME existed, had momentum, and had a 1.0 release on the way. The schism was permanent.

The through-line to your code: GNOME’s founding pressure was licence purity, not technical superiority. Builder defaults to GPL-3.0-or-later when it scaffolds a project. Flathub’s review process flags proprietary dependencies. Publishing through Flatpak rather than as a closed binary is implicit in every tutorial you’ll read. None of this is convention; it’s the residue of an argument from 1996.

2. The component dream that didn’t pan out (1999–2008)

GNOME 1.0 shipped in 1999 against GTK+ 1.2. The project’s name was the GNU Network Object Model Environment, and the network object model part was load-bearing. GNOME wasn’t supposed to be a window manager and a panel. It was supposed to be a full component architecture: applications built out of embeddable, scriptable, network-transparent objects living inside each other’s windows. The technology underneath was CORBA, and GNOME shipped its own implementation (ORBit) plus a higher-level component framework (Bonobo). The dream was that you’d embed a GNumeric spreadsheet inside an AbiWord document and edit it in place.

This wasn’t a GNOME-specific bet. The whole industry was on it: Microsoft’s COM and OLE, Sun’s Java RMI, a decade of conference talks predicting that desktop apps would be rebuilt as orchestrations of small composable objects messaging each other. It didn’t pan out. Components-via-IPC was the wrong abstraction at the application layer, and the lesson got learned the expensive way by everyone who’d bet on it.

The technology survived in a different shape. GLib 2.0 had shipped in 2002, and one of its contributions was to formalise GObject as a standalone type system — separable from GTK, and from the Bonobo component dream above it. That is the type system you’re working against in Part 2’s Feed and Part 3’s GazetteWindow. The shape of it — inner/outer split, vtables, manual reference counting, registration macros — is a 1990s C solution to the object-oriented programming problem. It feels strange in Rust because it predates Rust by fifteen years. D-Bus survived for the same reason: deliberately small where CORBA was deliberately general, and it’s how your single-instance behaviour works. GObject Introspection (2008) ships machine-readable type metadata alongside every GObject library, and it’s the only reason the Rust bindings can be auto-generated and stay current.

A lot of GNOME’s strangeness in 2026 is the residue of a 1990s bet that didn’t pay off. The bet itself is gone. The infrastructure built to support it survived, got refactored, and is now the foundation everything else stands on.

3. The GNOME 3 reset (2011)

GNOME 2 had been the standard Linux desktop for a decade by 2010 — a panel, a menu, a taskbar, icons on the desktop. Boring, in the best sense.

April 2011 broke that. GNOME 3.0 shipped with a complete reset of the user-visible desktop: a full-screen Activities overview, dynamic workspaces, no taskbar, no minimise button, no system tray, no desktop icons. The argument from the design team was that those affordances were artefacts of a 1990s desktop that no longer matched how people actually used computers. The revolt was real and loud — whole distributions refused to ship it, two forks (MATE preserving GNOME 2 verbatim, Cinnamon fixing the new shell) emerged within a year, and Linus Torvalds publicly switched to Xfce.

Here’s the part that’s harder to write in 2026 than in 2012: the design has aged well. The Activities overview, dynamic workspaces, the deliberate absence of customisation knobs, the bias toward defending users from a thousand small decisions — these were unpopular in 2011 because they were unfamiliar. macOS, Windows 11, ChromeOS, every mobile OS — all the design idioms now look more like GNOME 3 than they look like GNOME 2.

Every libadwaita widget you reach for is a descendant of that design ethos. Adw.ApplicationWindow instead of Gtk.Window, Adw.ToolbarView containing the header bar, the absence of a system-tray API, the deliberately limited theming surface — these aren’t arbitrary library decisions. They are the same opinionated-design argument from 2011, restated as code. Building Gazette to libadwaita conventions is, structurally, accepting GNOME 3’s premise. Fifteen years on, the premise has stopped being controversial.

4. GTK 4 and the libadwaita split (2020–2021)

GTK 4.0 shipped in December 2020 after roughly four years of development. The whole rendering pipeline had been rewritten — widgets emit declarative render nodes that GSK (the new GTK Scene Kit) compiles into GPU-accelerated draw operations. That’s why your Flatpak manifest from Part 3 has --device=dri even though you’re shipping an RSS reader. It’s not for graphics; it’s because GSK exists, and GSK wants the GPU.

The other GTK 4 change is harder to see but more consequential. The toolkit was deliberately positioned this time not to be the GNOME-only library any more. GTK 3 had dragged the GNOME aesthetic along with it wherever it went. GTK 4 strips the GNOME-specific visual identity out and leaves a place where it can be added back, optionally, as a separate library.

That library is libadwaita, first released in December 2021. Its release announcement put the bargain plainly: GTK should grow independently of GNOME at its own pace; other GTK consumers — Inkscape, elementary OS — should be first-class citizens rather than second-class baggage; libadwaita itself should be another library you can choose to link against if you want to make your application fit well into GNOME. The Adwaita stylesheet — GTK 3’s default look — moved out of GTK into libadwaita, and GTK 4 kept a renamed neutral copy.

Each adw:: import in application.rs and window.rs is a deliberate vote to be a GNOME app rather than a generic GTK one. Replace every adw:: symbol with its gtk:: equivalent and Gazette would still compile, still run, and still display a working window. It would just stop being a GNOME application. The line between the two is exactly the line GTK and libadwaita’s architects drew in 2020 and 2021, restated in your use statements.

5. Flatpak and the runtime model (2015–)

Before Flatpak, a GNOME application’s distribution problem was N × M × K. Forty-odd Linux distributions, each shipping a different GTK version, each on a different cadence, often two GNOME releases behind. When a user reported a bug you’d fixed eighteen months earlier, the answer was almost always which distro, which version, please file a bug with them. That isn’t a release model. It’s an apology.

Flatpak (originally xdg-app, started 2015 by Alex Larsson at Red Hat) ignores the host distribution’s library versions entirely. Bundle the application with the runtime it expects, run it in a sandbox via bubblewrap, mediate everything else through portals. If your app needs org.gnome.Platform 50, Flatpak ships it alongside your app and the user’s Debian or Fedora version is no longer your problem.

The runtime/SDK distinction in Part 3 is the literal embodiment of this model. org.gnome.Platform is what users get; org.gnome.Sdk is what you build against. Updating your manifest from "runtime-version": "48" to "50" isn’t a build-system quirk. It’s the act of saying I have tested this app against GNOME 50, here is what I’m shipping. The Flatpak manifest pinning a version, the --socket=wayland line, the --device=dri line — every one of those is a public commitment to a specific platform contract.

So

Each shape in your Part 3 project has a date and a reason now. The five trait implementations: GObject, formalised in 2002 because the 1990s component dream needed a separable type system. The mod imp block: that same 1990s C inheritance pattern restated as a Rust idiom. The adw::Application parent class: the 2020–2021 split between a deliberately neutral GTK 4 and a deliberately opinionated libadwaita, drawn in use statements. The meson.build next to Cargo.toml: the 2017–2019 migration that replaced autotools across the project. The Flatpak manifest: the 2015-onward distribution model that made same app, all distributions a viable promise.

History over. Part 4 is where the code resumes.

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:

1. 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.

2. 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.

3. 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:

1. 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.

2. 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.

3. 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.

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.

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.