Skip to content

Commit ea9bfa2

Browse files
bbhttbbhtt
committed
cargo: Improve the documentation
1 parent 8568d78 commit ea9bfa2

File tree

1 file changed

+151
-23
lines changed

1 file changed

+151
-23
lines changed

‎cargo/README.md‎

Lines changed: 151 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -15,42 +15,170 @@ Generated manifests are supported by flatpak-builder 1.2.x or newer.
1515

1616
## Usage
1717

18-
Poetry users: first activate your virtualenv by running `poetry shell`.
18+
1. Install poetry v2 https://python-poetry.org/docs/#installation
19+
2. Run `poetry env activate` inside the `cargo` folder
20+
3. `python3 flatpak-cargo-generator.py /path/to/Cargo.lock -o cargo-sources.json`
1921

20-
Convert the locked dependencies by Cargo into a format flatpak-builder can understand:
22+
The generated cargo manifest file `cargo-sources.json` should be added
23+
to the Flatpak manifest inside `sources`. An example of a complete
24+
Flatpak manifest for a Rust project is provided below.
25+
26+
```yaml
27+
app-id: com.example.my_rust_app
28+
# Replace with target runtime
29+
runtime: org.freedesktop.Platform
30+
# Replace with latest runtime version
31+
runtime-version: "24.08"
32+
sdk: org.freedesktop.Sdk
33+
sdk-extensions:
34+
- org.freedesktop.Sdk.Extension.rust-stable
35+
command: my_app
36+
finish-args:
37+
- --device=dri
38+
- --share=ipc
39+
- --socket=wayland
40+
- --socket=fallback-x11
41+
modules:
42+
43+
# Example using simple buildsystem
44+
45+
- name: my_app
46+
buildsystem: simple
47+
build-options:
48+
append-path: /usr/lib/sdk/rust-stable/bin
49+
env:
50+
CARGO_HOME: /run/build/my_app/cargo
51+
CARGO_NET_OFFLINE: 'true'
52+
build-commands:
53+
- cargo --offline fetch --manifest-path Cargo.toml --verbose
54+
- cargo build --offline --release --all-features
55+
- install -Dm0755 target/release/my_app ${FLATPAK_DEST}/bin/my_app
56+
- install -Dm0644 logo.svg ${FLATPAK_DEST}/share/icons/hicolor/scalable/apps/${FLATPAK_ID}.svg
57+
- install -Dm0644 ${FLATPAK_ID}.desktop ${FLATPAK_DEST}/share/applications/${FLATPAK_ID}.desktop
58+
- install -Dm0644 ${FLATPAK_ID}.metainfo.xml ${FLATPAK_DEST}/share/metainfo/${FLATPAK_ID}.metainfo.xml
59+
sources:
60+
- type: archive
61+
url: https://github.com/my_app/my_app.git
62+
tag: "v0.1.1"
63+
commit "0284b00219cee734e3f6ee2cd6be2bd8004c3cf2"
64+
- cargo-sources.json
65+
66+
# Example using meson buildsystem
67+
# Here it is assumed that all cargo commands are handled inside
68+
# 'meson.build' and 'CARGO_HOME' is set inside 'meson.build'
69+
70+
- name: my_app
71+
buildsystem: meson
72+
build-options:
73+
append-path: /usr/lib/sdk/rust-stable/bin
74+
env:
75+
CARGO_NET_OFFLINE: 'true'
76+
sources:
77+
- type: archive
78+
url: https://github.com/my_app/my_app.git
79+
tag: "v0.1.1"
80+
commit "0284b00219cee734e3f6ee2cd6be2bd8004c3cf2"
81+
- cargo-sources.json
2182
```
22-
python3 ./flatpak-cargo-generator.py ./quickstart/Cargo.lock -o cargo-sources.json
83+
84+
Rust and cargo is provided by the Flatpak extension
85+
`org.freedesktop.Sdk.Extension.rust-stable`. To install it run:
86+
87+
```sh
88+
flatpak install flathub org.freedesktop.Sdk.Extension.rust-stable//$branch
2389
```
2490

25-
The output file should be added to the manifest like
26-
```json
27-
{
28-
"name": "quickstart",
29-
"buildsystem": "simple",
30-
"build-commands": [
31-
"install -Dm644 cargo/config .cargo/config.toml",
32-
"cargo --offline fetch --manifest-path Cargo.toml --verbose",
33-
"cargo --offline build --release --verbose",
34-
"install -Dm755 ./target/release/quickstart -t /app/bin/"
35-
],
36-
"sources": [
37-
{
38-
"type": "dir",
39-
"path": "."
40-
},
41-
"cargo-sources.json"
42-
]
43-
}
91+
The `$branch` must match the `runtime-version` of `org.freedesktop.Sdk`.
92+
For example `24.08`. GNOME and KDE runtimes are based on
93+
`org.freedesktop.Sdk`. The correct branch of the Rust extension to
94+
install for a given GNOME or KDE runtime version can be found using:
95+
96+
```sh
97+
flatpak info -m org.kde.Sdk | grep -A 5 "org.freedesktop.Sdk.Extension" | grep -E "^version"
4498
```
4599

46-
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.
100+
`append-path: /usr/lib/sdk/rust-stable/bin` is used to add the location
101+
in the Flatpak extension where rust and cargo binaries are located to
102+
`$PATH` inside the build environment.
47103

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

49110
For a complete example see the quickstart project.
50111

112+
## `CARGO_HOME` is set by buildsystem
113+
114+
It is often common for example when using meson to set the `CARGO_HOME`
115+
environment variable like this in `meson.build`:
116+
117+
```meson
118+
cargo_env = [ 'CARGO_HOME=' + meson.project_build_root() / 'cargo-home' ]
119+
```
120+
121+
This causes cargo to not find the config generated by
122+
`flatpak-cargo-generator` and it tries to fetch some dependencies over
123+
the network making non-networked builds fail. This may happen if bare
124+
git dependencies are present in the upstream `Cargo.toml`. It will
125+
usually fail with
126+
`can't checkout from '$git-url': you are in the offline mode`.
127+
128+
In this case, copy the generated config to `.cargo` in the Flatpak
129+
manifest like below.
130+
131+
```yaml
132+
modules:
133+
134+
# Example using meson, cmake, cmake-ninja buildsystems
135+
136+
- name: my_app
137+
buildsystem: meson
138+
build-options:
139+
append-path: /usr/lib/sdk/rust-stable/bin
140+
env:
141+
CARGO_NET_OFFLINE: 'true'
142+
sources:
143+
- type: archive
144+
url: https://github.com/my_app/my_app.git
145+
tag: "v0.1.1"
146+
commit "0284b00219cee734e3f6ee2cd6be2bd8004c3cf2"
147+
- cargo-sources.json
148+
- type: shell
149+
commands:
150+
- mkdir -p .cargo
151+
- cp -vf cargo/config .cargo/config.toml
152+
153+
# Example using simple buildsystem
154+
155+
- name: my_app
156+
buildsystem: simple
157+
build-options:
158+
append-path: /usr/lib/sdk/rust-stable/bin
159+
env:
160+
CARGO_NET_OFFLINE: 'true'
161+
build-commands:
162+
- install -Dm0644 cargo/config .cargo/config.toml
163+
- cargo --offline fetch --manifest-path Cargo.toml --verbose
164+
- cargo build --offline --release --all-features
165+
- [...]
166+
```
167+
51168
## Development
52169

53170
1. Install Poetry v2 https://python-poetry.org/docs/#installation
54171
2. `poetry install --with dev`
55172
3. Format and lint: `poetry run ruff format && poetry run ruff check --fix --exit-non-zero-on-fix`
56173
4. Type check: `poetry run mypy .`
174+
175+
176+
## Alternatives
177+
178+
An alternative instead of using this script to generate sources, is to
179+
create a vendored tarball which has all the cargo modules inside it
180+
along with the source code. See [cargo-vendor](https://doc.rust-lang.org/cargo/commands/cargo-vendor.html).
181+
Such tarballs can be automatically produced and released from CI. An
182+
advantage to this approach is that new releases can be easily automated
183+
whereas using this script requires updating the generated manifest on
184+
each new release.

0 commit comments

Comments
 (0)