Day’s GTK target presents a Linux desktop interface using GTK 4 and libadwaita. This reference covers its development libraries, packaging, and toolkit-specific behavior.

linux-gtk is a Tier 2 target. Install the development libraries required by the distribution and check the toolkit’s accessibility limitations before choosing it.

Getting started

GTK 4.10+, libadwaita 1.5+, and librsvg 2.52+ development files are required (Ubuntu 24.04 and Fedora 40 satisfy these):

sudo apt install libgtk-4-dev libadwaita-1-dev librsvg2-dev pkg-config   # Debian/Ubuntu
sudo dnf install gtk4-devel libadwaita-devel librsvg2-devel pkgconf     # Fedora

cargo install --git https://github.com/daybrite/day day-cli
day new app my-app --toolkit linux-gtk
cd my-app
day launch -t linux-gtk

Add libwebkitgtk-6.0-dev if you use the web view piece. Sound effects play through libpulse, which a desktop already has (system requirements). day doctor --toolkit gtk probes GTK 4, libadwaita, librsvg, glib-compile-resources, and the packaging tools (flatpak-builder, linuxdeploy, linuxdeploy-plugin-gtk); it does not check WebKitGTK.

day pack -t linux-gtk        # single-file .flatpak AND a portable .appimage

day pack produces both formats by default. The flatpak runtime supplies GTK itself (org.gnome.Platform), so that bundle carries only your app and its assets; A user installs it with flatpak install ./my-app-1.0-linux-gtk-x86_64.flatpak. The AppImage carries its own GTK, so a user marks it executable and runs it.

Caveats

  • libadwaita is required. The window, navigation, tabs, dialogs and animations are all Adwaita types; a plain-GTK build is not a supported configuration.
  • GtkVideo needs a GStreamer media toolkit in the GTK build. Distro packages ship one; Homebrew’s gtk4 does not, so the media piece shows GTK’s own “no media toolkit” error on macos-gtk.
  • Lottie and map have no GTK arm; each renders its placeholder. cover() presents as a topmost window-sized child (no transition, programmatic dismissal only).
  • The combo box uses GtkComboBoxText, deprecated in GTK 4.10 but kept because GTK has no editable replacement yet.
  • A progress node picks its widget at realize time: progress(f) becomes a GtkProgressBar and spinner() a GtkSpinner. A node that starts indeterminate will not turn into a bar on a later value change; use separate nodes if you need both.
  • Canvas text uses cairo’s toy text API, not Pango, so complex-script shaping inside a canvas is weaker than in a label.
  • GTK on macOS (macos-gtk) exists for development convenience only (Tier 4); day pack skips it, and the accessibility tree is absent (GTK’s a11y bridge is Linux-only). On Windows, build linux-gtk inside WSL 2.

What each piece becomes

The generated coverage matrix, checked in CI, covers every toolkit; this table adds links and notes.

Day pieceGTK widget
column / row / nav_stack / sectionGtkFixed (Day owns layout)
labelGtkLabel
buttonGtkButton
toggleGtkSwitch
sliderGtkScale
text_fieldGtkEntry
secure_fieldGtkEntry with visibility off
text_areaGtkTextView in a GtkScrolledWindow
picker().menu()GtkDropDown
picker().segmented()linked GtkToggleButtons
picker().inline()grouped GtkCheckButtons (GTK 4’s radio)
progress(f)GtkProgressBar
spinner()GtkSpinner
dividerGtkSeparator
scrollGtkScrolledWindow
listGtkListView (recycling, signal factory)
nav (split)GtkPaned
nav (stack)AdwNavigationView
nav_menuGtkListBox (.navigation-sidebar)
tabsAdwViewStack + linked toggle buttons
imageGtkPicture
vectorGtkPicture showing the raster cache PNG (.tint recolors the pixels)
cover()emulated: a topmost window-sized child (no transition, programmatic dismissal only)
canvasGtkDrawingArea (cairo)
dialogs / alerts / promptsAdwAlertDialog
file dialogsGtkFileDialog
menu bar / context menusGtkPopoverMenuBar / GtkPopoverMenu
external spinner()GtkSpinner
external combobox()GtkComboBoxText (with entry)
external search_field()GtkSearchEntry
external date_picker()GtkCalendar, in a GtkMenuButton popover when compact
external time_picker()linked GtkSpinButtons
external webview()WebKitWebView (WebKitGTK 6.0)
external media()GtkVideo

Text measurement builds a Pango layout on the label’s styled context rather than calling gtk_widget_measure, because a GtkFixed child’s size request would otherwise ratchet upward and never shrink.