CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Roster is a GNOME application written in Python using GTK 4 and libadwaita. The project follows GNOME application conventions and uses the Meson build system.

Application ID: cz.bugsy.roster
Build System: Meson
Runtime: GNOME Platform (org.gnome.Platform)
UI Framework: GTK 4 + libadwaita (Adw)
Language: Python 3
License: GPL-3.0-or-later

Build Commands

Native Build

# Configure the build (from project root)
meson setup builddir

# Build the project
meson compile -C builddir

# Install locally
meson install -C builddir

# Run tests
meson test -C builddir

# Clean build directory
rm -rf builddir

Running the Application

The application uses libsoup3 (from GNOME Platform) for HTTP requests - no external dependencies required.

Development with Flatpak

The project includes a Flatpak manifest (cz.bugsy.roster.json) for building and running the application in a sandboxed environment:

# Build with GNOME Builder (recommended for GNOME apps)
# Or use flatpak-builder directly:
flatpak-builder --user --install --force-clean build-dir cz.bugsy.roster.json

Architecture

Application Structure

The application follows the standard GNOME/Adwaita application pattern:

RosterApplication (main.py): Singleton application class inheriting from Adw.Application
- Manages application lifecycle and actions (quit, about, preferences)
- Sets up keyboard shortcuts (e.g., Ctrl+Q for quit)
- Creates and presents the main window
RosterWindow (window.py): Main application window inheriting from Adw.ApplicationWindow
- Defined as a GTK template class using @Gtk.Template decorator
- UI layout loaded from window.ui via GResources

Resource Management

UI files are packaged into a GResource bundle:

Defined in src/roster.gresource.xml
Resource base path: /cz/vesp/roster
UI files are preprocessed with xml-stripblanks

File Organization

src/
  __init__.py         # Package marker
  main.py             # Application class and entry point
  window.py           # Main window class
  window.ui           # Main window UI definition (GTK Builder XML)
  shortcuts-dialog.ui # Keyboard shortcuts dialog
  roster.in           # Launcher script template (configured by Meson)
  roster.gresource.xml # GResource bundle definition

data/
  cz.bugsy.roster.desktop.in      # Desktop entry (i18n template)
  cz.bugsy.roster.metainfo.xml.in # AppStream metadata (i18n template)
  cz.bugsy.roster.gschema.xml     # GSettings schema
  cz.bugsy.roster.service.in      # D-Bus service file (configured by Meson)
  icons/                         # Application icons

po/
  # Translation files (gettext)

Key Patterns

UI Templates: Window classes use @Gtk.Template decorator with resource_path pointing to .ui files in GResources. Child widgets are accessed via Gtk.Template.Child().
Actions: Application actions are created with the create_action() helper method, which sets up actions and optional keyboard shortcuts.
Internationalization: Uses gettext with domain "roster". Template files (.in) are processed through i18n.merge_file() during build.
Configuration Data: Meson substitutes variables in .in files using configuration_data() (e.g., paths, version).
Module Installation: Python modules are installed to {datadir}/roster/roster/ and the launcher script is configured with the correct Python interpreter path.

Adding New Python Modules

When adding new .py files to src/:

Add the filename to roster_sources list in src/meson.build
Import in main.py or other modules as needed

Adding New UI Files

When adding new .ui files:

Place in src/ directory
Add <file> entry to src/roster.gresource.xml
Use @Gtk.Template(resource_path='/cz/bugsy/roster/filename.ui') in the corresponding Python class

GSettings Schema

Settings are defined in data/cz.bugsy.roster.gschema.xml. After modifying:

Schema is validated during meson test
Compiled automatically during installation via gnome.post_install()

4.2 KiB Raw Permalink Blame History