Skip to content

Commit 8c5a0ec

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

File tree

1 file changed

+139
-23
lines changed

1 file changed

+139
-23
lines changed

‎cargo/README.md‎

Lines changed: 139 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -15,39 +15,155 @@ 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+
67+
# Example using meson buildsystem
68+
69+
- name: my_app
70+
buildsystem: meson
71+
build-options:
72+
append-path: /usr/lib/sdk/rust-stable/bin
73+
env:
74+
CARGO_NET_OFFLINE: 'true'
75+
sources:
76+
- type: archive
77+
url: https://github.com/my_app/my_app.git
78+
tag: "v0.1.1"
79+
commit "0284b00219cee734e3f6ee2cd6be2bd8004c3cf2"
80+
- cargo-sources.json
2181
```
22-
python3 ./flatpak-cargo-generator.py ./quickstart/Cargo.lock -o cargo-sources.json
82+
83+
Rust and cargo is provided by the Flatpak extension
84+
`org.freedesktop.Sdk.Extension.rust-stable`. To install it run:
85+
86+
```sh
87+
flatpak install flathub org.freedesktop.Sdk.Extension.rust-stable//$branch
2388
```
2489

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-
}
90+
The `$branch` must match the `runtime-version` of `org.freedesktop.Sdk`.
91+
For example `24.08`. GNOME and KDE runtimes are based on
92+
`org.freedesktop.Sdk`. The correct branch of the Rust extension to
93+
install for a given GNOME or KDE runtime version can be found using:
94+
95+
```sh
96+
flatpak info -m org.kde.Sdk | grep -A 5 "org.freedesktop.Sdk.Extension" | grep -E "^version"
4497
```
4598

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

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

49109
For a complete example see the quickstart project.
50110

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

53169
1. Install Poetry v2 https://python-poetry.org/docs/#installation

0 commit comments

Comments
 (0)