cargo: Improve the documentation

Author: bbhtt

cargo/README.md

@@ -15,18 +15,23 @@ Generated manifests are supported by flatpak-builder 1.2.x or newer.
 
 ## Usage
 
-Poetry users: first activate your virtualenv by running `poetry shell`.
+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`
 
-Convert the locked dependencies by Cargo into a format flatpak-builder can understand:
-```
-python3 ./flatpak-cargo-generator.py ./quickstart/Cargo.lock -o cargo-sources.json
-```
+The generated cargo manifest file `cargo-sources.json` should be added
+to the Flatpak manifest like so:
 
-The output file should be added to the manifest like
 ```json
 {
     "name": "quickstart",
     "buildsystem": "simple",
+    "build-options": {
+        "append-path": "/usr/lib/sdk/rust-stable/bin",
+        "env": {
+            "CARGO_NET_OFFLINE": "true"
+        }
+    },
     "build-commands": [
         "install -Dm644 cargo/config .cargo/config.toml",
         "cargo --offline fetch --manifest-path Cargo.toml --verbose",
@@ -43,11 +48,125 @@ The output file should be added to the manifest like
 }
 ```
 
-Make sure to override CARGO_HOME env variable to point it to `/run/build/$module-name/cargo` where `$module-name` is the flatpak module name, `quickstart` in this example.
+An example of a complete Flatpak manifest for a Rust project is provided
+below.
+
+<details>
+<summary>Manifest</summary>
+
+```yaml
+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:
+  - name: my_app
+    buildsystem: simple
+    build-options:
+      append-path: /usr/lib/sdk/rust-stable/bin
+      env:
+        CARGO_HOME: /run/build/my_app/cargo
+    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
+```
+</details>
+
+
+Rust and cargo is provided by the Flatpak extension
+`org.freedesktop.Sdk.Extension.rust-stable`. To install it run:
+
+```sh
+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 or the config generated by `flatpak-cargo-generator` needs
+to be installed as `.cargo/config.toml` (the first line of `build-commands`).
 
 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' ]
+```
+
+But in this case, cargo cannot find the config generated by
+`flatpak-cargo-generator` causing it to try fetching 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 or symlink the generated config to `.cargo` in the
+Flatpak manifest like so:
+
+```json
+{
+    "name": "my_app",
+    "buildsystem": "meson",
+    "build-options": {
+        "append-path": "/usr/lib/sdk/rust-stable/bin",
+        "env": {
+            "CARGO_NET_OFFLINE": "true"
+        }
+    },
+    "sources": [
+        {
+            "type": "git",
+            "url": "https://github.com/ghost/my_app.git",
+            "tag": "v0.0.1"
+        },
+        "cargo-sources.json",
+        {
+            "type": "shell",
+            "commands": [
+                "mkdir -p .cargo",
+                "ln -s cargo/config .cargo/config.toml"
+            ]
+        }
+    ]
+}
+```
+
 ## Development
 
 1. Install Poetry v2 https://python-poetry.org/docs/#installation