flatpak_dart

Typed Dart API for managing Flatpak applications on Linux. Drives libflatpak directly via a C++23 FFI bridge — no D-Bus client library, no subprocess spawning, no text parsing.

Features

Feature	API
List installed apps	client.listApplications()
App details	client.info(appId)
Install / update / uninstall	client.install(), .update(), .uninstall()
Transaction progress	tx.progress stream (percentage, bytes, status)
Batch transactions	client.transaction()..addInstall()..addUpdate()
Remote CRUD	client.remotes.add(), .modify(), .remove()
Remote browsing	client.remotes.listApps(name) stream
Subset filtering	client.remotes.modifySubset(name, RemoteSubset.verified)
Pre-install permissions	client.fetchRemoteMetadata(remote, ref)
Update monitoring	client.watchUpdates() (inotify, state-diffed)
Known remotes catalog	KnownRemotes.flathub, .fedora, .gnomeNightly, etc.

Architecture

Dart isolate
  |  FFI call (< 1 us)
  v
C++23 bridge (libflatpak C API)
  |  flatpak_installation_*()  — reads
  |  flatpak_transaction_run() — writes (serial worker queue)
  |  GFileMonitor              — update watch (inotify)
  v
Results posted to Dart via Dart_PostCObject_DL (kTypedData)
Payloads encoded with BEVE-Lite binary codec (glaze_meta.h)

Prerequisites

# Fedora
sudo dnf install flatpak-devel glib2-devel cmake ninja-build clang

# Ubuntu / Debian
sudo apt install libflatpak-dev libglib2.0-dev cmake ninja-build clang-19

Quick start

# Clone
git clone https://github.com/jwinarske/flatpak_dart.git
cd flatpak_dart

# Build the native library
./scripts/build_release.sh

# Install Dart dependencies
dart pub get

# Run an example
FLATPAK_NC_LIB=build-release/libflatpak_nc.so dart run example/example.dart

Usage

import 'package:flatpak_dart/flatpak_dart.dart';

void main() async {
  final client = FlatpakClient.user();

  // List installed apps
  for (final app in await client.listApplications()) {
    print('${app.ref.name} ${app.appDataVersion}');
  }

  // Install with progress
  final tx = client.install('flathub', 'app/org.gnome.Calculator/x86_64/stable');
  await for (final p in tx.progress) {
    print('${p.progressPercent}% ${p.progressLabel}');
  }
  await tx.result;

  // Pre-install permissions check
  final perms = await client.fetchRemoteMetadata(
      'flathub', 'app/org.gnome.Calculator/x86_64/stable');
  for (final e in perms.where((e) => e.section == 'Context')) {
    print('${e.key}: ${e.value}');
  }

  // Watch for changes (inotify)
  final monitor = client.watchUpdates();
  await for (final _ in monitor.events) {
    print('Installation changed!');
  }

  await client.close();
}

Remote management

final client = FlatpakClient.user();

// Add from known catalog
await client.remotes.add('flathub', KnownRemotes.flathub);
await client.remotes.add('flathub-floss', KnownRemotes.flathubFloss);

// Browse remote packages
await for (final ref in client.remotes.listApps('flathub')) {
  print('${ref.name}/${ref.arch}/${ref.branch}');
}

// Enable / disable
await client.remotes.disable('flathub-floss');
await client.remotes.enable('flathub-floss');

// Remove
await client.remotes.remove('flathub-floss');

Transaction concurrency

Transactions on the same installation are serialized by an internal worker queue (OSTree holds an exclusive repo lock). User and system installations have independent queues and run in parallel.

final user   = FlatpakClient.user();
final system = FlatpakClient.system();

// These run in parallel (different repo locks)
await Future.wait([
  user.install('flathub', 'app/org.gnome.Calculator/x86_64/stable').result,
  system.install('flathub', 'app/org.gnome.Maps/x86_64/stable').result,
]);

Known remotes

Constant	Remote	Notes
KnownRemotes.flathub	Flathub	Default, collection org.flathub.Stable
KnownRemotes.flathubVerified	Flathub	--subset=verified
KnownRemotes.flathubFloss	Flathub	--subset=floss
KnownRemotes.flathubVerifiedFloss	Flathub	--subset=verified_floss
KnownRemotes.flathubBeta	Flathub Beta	Pre-release channel
KnownRemotes.fedora	Fedora	OCI format (oci+https://)
KnownRemotes.elementaryOs	elementary	AppCenter
KnownRemotes.gnomeNightly	GNOME Nightly	Nightly builds
KnownRemotes.kdeRuntimeNightly	KDE Nightly	KDE runtime

Building the native library

The package includes a C++23 shared library that bridges Dart FFI to libflatpak.

# Release build
./scripts/build_release.sh

# ASAN + UBSan
./scripts/asan.sh

# clang-tidy
./scripts/clang_tidy.sh

# Coverage
./scripts/coverage.sh

Set FLATPAK_NC_LIB to the path of libflatpak_nc.so, or place it in one of the auto-detected paths (build-release/, build/, etc.).

Flutter example

A full Flutter Linux desktop app is included in example/flutter_remote_manager/:

cd example/flutter_remote_manager
flutter pub get
FLATPAK_NC_LIB=../../build-release/libflatpak_nc.so flutter run -d linux

Platform support

Platform	Support
Linux (x86_64, aarch64)	Full
macOS / Windows	Not supported (Flatpak is Linux-only)

Requires libflatpak >= 1.12 and Flatpak installed on the host.

License

MIT. See LICENSE.

Vendored headers are under their respective licenses. See THIRD_PARTY_LICENSES.