Skip to content

Latest commit

 

History

History

cargo

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
quickstart
quickstart
 
 
README.md
README.md
 
 
flatpak-cargo-generator.py
flatpak-cargo-generator.py
 
 
poetry.lock
poetry.lock
 
 
pyproject.toml
pyproject.toml
 
 

README.md

flatpak-cargo-generator

Tool to automatically generate flatpak-builder manifest json from a Cargo.lock.

Requirements

Poetry users can run poetry install and skip this.

Otherwise install Python 3.9+ with these modules:

  • tomlkit
  • aiohttp
  • (Optional) PyYAML>=6.0.2 for YAML output instead of JSON

Generated manifests are supported by flatpak-builder 1.2.x or newer.

Usage

  1. Install poetry v2 https://python-poetry.org/docs/#installation
  2. Run poetry env activate inside the cargo folder
  3. python3 flatpak-cargo-generator.py /path/to/Cargo.lock -o cargo-sources.json

The generated cargo manifest file cargo-sources.json should be added to the Flatpak manifest inside sources. An example of a complete Flatpak manifest for a Rust project is provided below.

app-id: com.example.my_rust_app
# Replace with target runtime
runtime: org.freedesktop.Platform
# Replace with latest runtime version
runtime-version: "24.08"
sdk: org.freedesktop.Sdk
sdk-extensions:
  - org.freedesktop.Sdk.Extension.rust-stable
command: my_app
finish-args:
  - --device=dri
  - --share=ipc
  - --socket=wayland
  - --socket=fallback-x11
modules:

  # Example using simple buildsystem
  
  - name: my_app
    buildsystem: simple
    build-options:
      append-path: /usr/lib/sdk/rust-stable/bin
      env:
        CARGO_HOME: /run/build/my_app/cargo
        CARGO_NET_OFFLINE: 'true'
    build-commands:
      - cargo --offline fetch --manifest-path Cargo.toml --verbose
      - cargo build --offline --release --all-features
      - install -Dm0755 target/release/my_app ${FLATPAK_DEST}/bin/my_app
      - install -Dm0644 logo.svg ${FLATPAK_DEST}/share/icons/hicolor/scalable/apps/${FLATPAK_ID}.svg
      - install -Dm0644 ${FLATPAK_ID}.desktop ${FLATPAK_DEST}/share/applications/${FLATPAK_ID}.desktop
      - install -Dm0644 ${FLATPAK_ID}.metainfo.xml ${FLATPAK_DEST}/share/metainfo/${FLATPAK_ID}.metainfo.xml
    sources:
      - type: archive
        url: https://github.com/my_app/my_app.git
        tag: "v0.1.1"
        commit "0284b00219cee734e3f6ee2cd6be2bd8004c3cf2"
      - cargo-sources.json

  # Example using meson buildsystem
  # Here it is assumed that all cargo commands are handled inside
  # 'meson.build' and 'CARGO_HOME' is set inside 'meson.build'

  - name: my_app
    buildsystem: meson
    build-options:
      append-path: /usr/lib/sdk/rust-stable/bin
      env:
        CARGO_NET_OFFLINE: 'true'
    sources:
      - type: archive
        url: https://github.com/my_app/my_app.git
        tag: "v0.1.1"
        commit "0284b00219cee734e3f6ee2cd6be2bd8004c3cf2"
      - cargo-sources.json

Rust and cargo is provided by the Flatpak extension org.freedesktop.Sdk.Extension.rust-stable. To install it run:

flatpak install flathub org.freedesktop.Sdk.Extension.rust-stable//$branch

The $branch must match the runtime-version of org.freedesktop.Sdk. For example 24.08. GNOME and KDE runtimes are based on org.freedesktop.Sdk. The correct branch of the Rust extension to install for a given GNOME or KDE runtime version can be found using:

flatpak info -m org.kde.Sdk | grep -A 5 "org.freedesktop.Sdk.Extension" | grep -E "^version"

append-path: /usr/lib/sdk/rust-stable/bin is used to add the location in the Flatpak extension where rust and cargo binaries are located to $PATH inside the build environment.

Either the CARGO_HOME environment variable needs to be set to /run/build/$module-name/cargo where $module-name is the flatpak module name (here my_app), or the config generated by flatpak-cargo-generator needs to be installed as .cargo/config.toml (see below).

For a complete example see the quickstart project.

CARGO_HOME is set by buildsystem

It is often common for example when using meson to set the CARGO_HOME environment variable like this in meson.build:

cargo_env = [ 'CARGO_HOME=' + meson.project_build_root() / 'cargo-home' ]

This causes cargo to not find the config generated by flatpak-cargo-generator and it tries to fetch some dependencies over the network making non-networked builds fail. This may happen if bare git dependencies are present in the upstream Cargo.toml. It will usually fail with can't checkout from '$git-url': you are in the offline mode.

In this case, copy the generated config to .cargo in the Flatpak manifest like below.

modules:

  # Example using meson, cmake, cmake-ninja buildsystems

  - name: my_app
    buildsystem: meson
    build-options:
      append-path: /usr/lib/sdk/rust-stable/bin
      env:
        CARGO_NET_OFFLINE: 'true'
    sources:
      - type: archive
        url: https://github.com/my_app/my_app.git
        tag: "v0.1.1"
        commit "0284b00219cee734e3f6ee2cd6be2bd8004c3cf2"
      - cargo-sources.json
      - type: shell
        commands:
          - mkdir -p .cargo
          - cp -vf cargo/config .cargo/config.toml

  # Example using simple buildsystem

  - name: my_app
    buildsystem: simple
    build-options:
      append-path: /usr/lib/sdk/rust-stable/bin
      env:
        CARGO_NET_OFFLINE: 'true'
    build-commands:
      - install -Dm0644 cargo/config .cargo/config.toml
      - cargo --offline fetch --manifest-path Cargo.toml --verbose
      - cargo build --offline --release --all-features
      - [...]

Development

  1. Install Poetry v2 https://python-poetry.org/docs/#installation
  2. poetry install --with dev
  3. Format and lint: poetry run ruff format && poetry run ruff check --fix --exit-non-zero-on-fix
  4. Type check: poetry run mypy .

Alternatives

An alternative instead of using this script to generate sources, is to create a vendored tarball which has all the cargo modules inside it along with the source code. See cargo-vendor. Such tarballs can be automatically produced and released from CI. An advantage to this approach is that new releases can be easily automated whereas using this script requires updating the generated manifest on each new release.