Publishing your Rust app as a flatpak

Ship your app easily to users

Creating a Flatpak

Traditionally in the Rust ecosystem you would build and install a Rust program from crates.io with cargo install or install a binary directly with cargo-binstall, but desktop applications consist of more files than just a binary.

We have already prepared the project to use CMake on top of Cargo to install those additional files to their appropriate places so Linux distributions can package your application more easily, and that also makes it ready to package as a flatpak.

Create a new flatpak manifest file org.kde.simplemdviewer.json in the root directory of the project:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
  "command": "simplemdviewer",
  "desktop-file-name-suffix": " (Nightly)",
  "finish-args": [
    "--share=ipc",
    "--device=dri",
    "--socket=fallback-x11",
    "--socket=wayland"
  ],
  "id": "org.kde.simplemdviewer",
  "modules": [
    {
      "buildsystem": "cmake",
      "name": "simplemdviewer",
      "sources": [
        "cargo-sources.json",
        {
          "type": "dir",
          "path": "."
        },
        {
          "type": "shell",
          "commands": [
            "mkdir -p .cargo",
            "cp -vf cargo/config .cargo/config.toml"
          ]
        }
      ]
    }
  ],
  "sdk-extensions": [
    "org.freedesktop.Sdk.Extension.rust-stable"
  ],
  "build-options": {
    "append-path": "/usr/lib/sdk/rust-stable/bin"
  },
  "runtime": "org.kde.Platform",
  "runtime-version": "6.9",
  "sdk": "org.kde.Sdk"
}

The most notable additions to the manifest are the rust-stable Sdk (development) extension, and the build option to append Rust binaries like Cargo and rustc, needed for building our application:

31
32
33
34
35
36
  "sdk-extensions": [
    "org.freedesktop.Sdk.Extension.rust-stable"
  ],
  "build-options": {
    "append-path": "/usr/lib/sdk/rust-stable/bin"
  },

Flatpak performs a local offline build of the project, so the traditional cargo build step cannot fetch crates from crates.io while building the project. To accomodate for that, we need to use flatpak-cargo-generator.

Download and use flatpak-cargo-generator.py to prepare all the dependency crates:

wget https://raw.githubusercontent.com/flatpak/flatpak-builder-tools/refs/heads/master/cargo/flatpak-cargo-generator.py
python3 flatpak-cargo-generator.py Cargo.lock -o cargo-sources.json

You might need to manually install python3-aiohttp and python3-toml from your distribution to run the script.

This will make the dependencies available in the flatpak manifest as a separate source. We need three sources in total: the cargo dependencies, the actual project in the current directory, and additional shell commands to put the Cargo configuration file in the right place to build inside a flatpak:

15
16
17
18
19
20
21
22
23
24
25
26
27
28
      "sources": [
        "cargo-sources.json",
        {
          "type": "dir",
          "path": "."
        },
        {
          "type": "shell",
          "commands": [
            "mkdir -p .cargo",
            "cp -vf cargo/config .cargo/config.toml"
          ]
        }
      ]

Building and running

Install org.kde.Sdk and org.kde.Platform, version 6.9, from Flathub:

flatpak install org.kde.Platform/x86_64/6.9 org.kde.Sdk/x86_64/6.9

To attempt a first build of the flatpak, run:

flatpak-builder --force-clean flatpak-build-dir org.kde.simplemdviewer.json

Tip

You can add the flag --install-deps-from flathub to flatpak-builder to make it download the Sdk, Platform and Baseapp for you instead of installing them manually.

If you installed Flathub as a user repository, you will need to add the --user flag to install the runtime. Otherwise you might see the error "Flatpak system operation Deploy not allowed for user".

flatpak-builder --user --force-clean --install-deps-from flathub flatpak-build-dir org.kde.simplemdviewer.json

If you use the --user flag, you will also need to pass this flag when installing the flatpak.

Test the flatpak build:

flatpak-builder --run flatpak-build-dir org.kde.simplemdviewer.json simplemdviewer

Build a distributable nightly flatpak bundle:

flatpak-builder --repo simplemdviewer-master --force-clean --ccache flatpak-build-dir org.kde.simplemdviewer.json
flatpak build-bundle simplemdviewer-master simplemdviewer.flatpak org.kde.simplemdviewer

Now we can either distribute the simplemdviewer.flatpak directly to the users, or submit the application to a flatpak repository, like the most popular repository, Flathub. See the App Submission Guidelines.

Other improvements you can make to your application:

Signing the source archive with a detached signature.
Providing copyright and licensing information for each file with REUSE.
Learn more about building flatpak apps with our Flatpak Tutorial and the official documentation.
Consider making it an official KDE Application, building Flatpak nightlies using KDE infrastructure.
Follow the Flathub Quality Guidelines to refine the presentation of your application on Flathub.

Happy hacking.