ContextQMD
Back to Char

Distribution

apps/web/content/docs/developers/11.distribution.mdx

latest6.5 KB
Original Source

Flatpak Packaging for Char

This document describes how to build Char as a Flatpak and submit it to Flathub.

Overview

Char uses the "build from source" strategy for Flatpak packaging, which is the preferred approach for Flathub. This means the entire application is built inside the Flatpak sandbox using vendored dependencies.

Prerequisites

Install the required tools:

bash
# Install Flatpak and flatpak-builder
sudo apt install flatpak flatpak-builder

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

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

# Install SDK extensions for Rust and Node
flatpak install flathub org.freedesktop.Sdk.Extension.rust-stable//24.08
flatpak install flathub org.freedesktop.Sdk.Extension.node22//24.08

Install the flatpak-builder-tools for generating vendored dependencies:

bash
# Clone flatpak-builder-tools
git clone https://github.com/nickvidal/flatpak-builder-tools.git

# For Node/pnpm dependencies
pip install aiohttp toml

# For Cargo dependencies
pip install toml

Generating vendored dependencies

Before building the Flatpak, you need to generate JSON files containing all vendored dependencies. These files allow the build to proceed offline, which is required by Flathub.

Generate pnpm dependencies

From the repository root:

bash
# Generate pnpm-sources.json
python3 flatpak-builder-tools/node/flatpak-node-generator.py pnpm \
  -o apps/desktop/flatpak/pnpm-sources.json \
  pnpm-lock.yaml

Generate Cargo dependencies

From the repository root:

bash
# Generate cargo-sources.json
python3 flatpak-builder-tools/cargo/flatpak-cargo-generator.py \
  -d Cargo.lock \
  -o apps/desktop/flatpak/cargo-sources.json

Building locally

Once the vendored dependency files are generated, you can build the Flatpak locally:

bash
# Build and install to user Flatpak
flatpak-builder --user --install --force-clean \
  flatpak-build-dir \
  apps/desktop/flatpak/com.hyprnote.Char.yml

Running the Flatpak

After building and installing:

bash
flatpak run com.hyprnote.Char

Debugging

To debug inside the Flatpak sandbox:

bash
# Open a shell inside the sandbox
flatpak run --devel --command=sh com.hyprnote.Char

# Inside the sandbox, you can inspect /app and run the binary directly
ls /app/bin/
/app/bin/hyprnote

Flathub submission

Preparation checklist

Before submitting to Flathub, ensure:

  • The manifest builds successfully with flatpak-builder
  • The app runs correctly via flatpak run com.hyprnote.Char
  • All vendored dependencies are up to date
  • The metainfo.xml file has valid screenshots and descriptions
  • The desktop file has correct categories and keywords

Submission process

  1. Fork the flathub/flathub repository on GitHub

  2. Clone your fork and checkout the new-pr branch:

    bash
    git clone --branch=new-pr [email protected]:YOUR_USERNAME/flathub.git
cd flathub

  3. Create a new branch for your app:

    bash
    git checkout -b com.hyprnote.Char

  4. Create the app directory and copy files:

    bash
    mkdir com.hyprnote.Char
cp /path/to/hyprnote/apps/desktop/flatpak/com.hyprnote.Char.yml com.hyprnote.Char/
cp /path/to/hyprnote/apps/desktop/flatpak/com.hyprnote.Char.desktop com.hyprnote.Char/
cp /path/to/hyprnote/apps/desktop/flatpak/com.hyprnote.Char.metainfo.xml com.hyprnote.Char/
cp /path/to/hyprnote/apps/desktop/flatpak/pnpm-sources.json com.hyprnote.Char/
cp /path/to/hyprnote/apps/desktop/flatpak/cargo-sources.json com.hyprnote.Char/

  5. Update the manifest to use a git source instead of a local directory:

    yaml
    sources:
  - type: git
    url: https://github.com/fastrepl/char.git
    tag: desktop_vX.Y.Z  # Use the release tag
    commit: abc123...     # Include the commit hash

  6. Commit and push:

    bash
    git add .
git commit -m "Add com.hyprnote.Char"
git push origin com.hyprnote.Char

  7. Open a pull request from your branch to the new-pr branch of flathub/flathub

  8. Respond to review comments from Flathub maintainers

After approval

Once approved:

  • Flathub creates a dedicated repository: flathub/com.hyprnote.Char
  • You are invited as a maintainer
  • Future updates are done by pushing to that repository

Updating the Flatpak

When releasing a new version:

  1. Update the version in com.hyprnote.Char.metainfo.xml
  2. Regenerate vendored dependencies if dependencies changed
  3. Update the git source tag/commit in the Flathub manifest
  4. Push changes to the Flathub app repository

File structure

apps/desktop/
  flatpak/
    com.hyprnote.Char.yml        # Flatpak manifest
    com.hyprnote.Char.desktop    # Desktop entry file
    com.hyprnote.Char.metainfo.xml  # AppStream metadata
    pnpm-sources.json                # Vendored pnpm dependencies (generated)
    cargo-sources.json               # Vendored Cargo dependencies (generated)
  src-tauri/
    tauri.conf.flatpak.json          # Tauri config for Flatpak (updater disabled)

Permissions

The Flatpak manifest includes the following permissions:

  • Display: Wayland and X11 fallback for GUI
  • Audio: PulseAudio for microphone and speaker capture
  • Network: For cloud AI services and calendar sync
  • Notifications: For meeting reminders and alerts
  • System Tray: For background operation indicator
  • Filesystem: Access to Documents and Downloads folders

Troubleshooting

Build fails with missing dependencies

Regenerate the vendored dependency files:

bash
python3 flatpak-builder-tools/node/flatpak-node-generator.py pnpm -o apps/desktop/flatpak/pnpm-sources.json pnpm-lock.yaml
python3 flatpak-builder-tools/cargo/flatpak-cargo-generator.py -d Cargo.lock -o apps/desktop/flatpak/cargo-sources.json

Audio not working

Ensure PulseAudio is running on your system. The Flatpak uses --socket=pulseaudio for audio access.

System tray icon not showing

Some desktop environments require additional configuration for StatusNotifier support. The manifest includes --talk-name=org.kde.StatusNotifierWatcher for tray icon support.

References