[RFC PATCH 0/3] Add helper and documentation for rust packaging

[Quirin Gylstorff]

From: Quirin Gylstorff <quirin.g...@siemens.com>


This adds based on https://rust-team.pages.debian.net/book/ some
documentation add a generator to package rust crates.

The generator is the same as used by Debian but we don't use the
approach from debcargo-conf as `debcargo cargo` executes the following
steps add once:
- fetch source
- generate orig tarball
- generate debian folder

As this is not compatible with the concepts of bitbake recipes we use
the http fetcher and the by `debcargo` generated debian folder. This
approach is intended to build crates stored in a registry(e.g. crates.io).

The crates package generated by this script should be package upstream
to avoid maintaining them forever.

Crates not in a registry need to manually packaged.

Quirin Gylstorff (3):
Add script to generate a recipe for cargo.io crates
Add example of a rust hello world as isar recipe
user_manual: add rust section

doc/user_manual.md | 66 ++++++++++++++
.../recipes-app/rust-hello-isar/files/rules | 27 ++++++
.../files/rust-hello-isar/Cargo.toml | 6 ++
.../files/rust-hello-isar/src/main.rs | 3 +
.../rust-hello-isar/rust-hello-isar_0.1.bb | 22 +++++
scripts/generate_cargo_crate.sh | 85 +++++++++++++++++++
6 files changed, 209 insertions(+)
create mode 100755 meta-isar/recipes-app/rust-hello-isar/files/rules
create mode 100644 meta-isar/recipes-app/rust-hello-isar/files/rust-hello-isar/Cargo.toml
create mode 100644 meta-isar/recipes-app/rust-hello-isar/files/rust-hello-isar/src/main.rs
create mode 100644 meta-isar/recipes-app/rust-hello-isar/rust-hello-isar_0.1.bb
create mode 100755 scripts/generate_cargo_crate.sh

--
2.53.0

[Quirin Gylstorff]

From: Quirin Gylstorff <quirin.g...@siemens.com>

This script allows to create a recipe for building rust crates which
are not part of Debian. It uses for this `debcargo package` and follows
the process defined in https://rust-team.pages.debian.net/book.

Signed-off-by: Quirin Gylstorff <quirin.g...@siemens.com>
---
scripts/generate_cargo_crate.sh | 85 +++++++++++++++++++++++++++++++++
1 file changed, 85 insertions(+)
create mode 100755 scripts/generate_cargo_crate.sh

diff --git a/scripts/generate_cargo_crate.sh b/scripts/generate_cargo_crate.sh
new file mode 100755
index 00000000..759bbc9e
--- /dev/null
+++ b/scripts/generate_cargo_crate.sh
@@ -0,0 +1,85 @@
+#!/bin/bash
+# This software is a part of ISAR.
+# Copyright (C) 2026 Siemens AG
+
+usage() {
+ echo "This script generates a scaffold for rust crates from crates.io."
+ echo "It uses debcargo to download and generate the debian folder."
+ echo "USAGE: $0 <CRATE_NAME> [CRATE_VERSION]"
+}
+
+if [ $# -eq 0 ]; then
+ usage
+ exit 1
+fi
+case $1 in
+ -h|--help)
+ usage
+ exit 0
+ ;;
+ *)
+ true
+ ;;
+esac
+
+package_name=$1
+package_version=
+if [ $# -gt 1 ]; then
+ package_version=$2
+fi
+
+export NAME="isar-users isar"
+
+for dep in jq debcargo curl; do
+ if ! command -v "$dep" ;then
+ echo "Could not find tool dependency $dep !"
+ exit 1
+ fi
+done
+
+source_name="rust-$package_name"
+mkdir -p "$source_name/files"
+# generate in the current directory to avoid the following
+# debcargo error:
+# Invalid cross-device link (os error 18)
+TMP_DIR=$(mktemp -d -p .)
+pushd "$source_name" || exit 1
+debcargo package "$package_name" "$package_version" --directory "$TMP_DIR"
+cp -r "${TMP_DIR}"/debian files/
+if [ -z "$package_version" ]; then
+ package_version=$(grep -oP "X-Cargo-Crate-Version:\K.*" "${TMP_DIR}"/debian/control | tr -d "[:blank:]")
+fi
+rm -rf "$TMP_DIR"
+tarball_checksum="$(curl --silent "https://crates.io/api/v1/crates/${package_name}/${package_version}" | jq ".version.checksum" )"
+if [ "${tarball_checksum}" = "null" ] ; then
+ echo "$package_name in $package_version could not be found in crates.io"
+ exit 1
+fi
+cat << EOF >> "${source_name}_${package_version}".bb
+inherit dpkg
+
+SRC_URI = "https://crates.io/api/v1/crates/${package_name}/\${PV}/download;downloadfilename=${PN}_${PV}.tar.gz"
+SRC_URI += "file://debian"
+
+SRC_URI[sha256sum] = ${tarball_checksum}
+
+S = "\${WORKDIR}/${package_name}-\${PV}"
+
+# In most cases we want to package a library crate from crates.io
+PROVIDES += "librust-${package_name}-dev"
+
+do_prepare_build() {
+ cp -r \${WORKDIR}/debian \${S}/
+ cd \${WORKDIR}
+ tar cJf \${PN}_\${PV}.orig.tar.xz \${TAR_REPRO_OPTS} ${package_name}-\${PV}
+}
+EOF
+
+
+popd || exit 1
+
+echo "Finished generating isar scaffold for package $package_name in version $package_version"
+echo ""
+echo "Next steps:"
+echo " - Check if the package builds and add the necessary patches, e.g. relax dependencies to the debian folder."
+echo " - Also add the package to Debian by following https://rust-team.pages.debian.net/book/"
--
2.53.0

[Quirin Gylstorff]

From: Quirin Gylstorff <quirin.g...@siemens.com>

Signed-off-by: Quirin Gylstorff <quirin.g...@siemens.com>
---

.../recipes-app/rust-hello-isar/files/rules | 27 +++++++++++++++++++
.../files/rust-hello-isar/Cargo.toml | 6 +++++
.../files/rust-hello-isar/src/main.rs | 3 +++
.../rust-hello-isar/rust-hello-isar_0.1.bb | 22 +++++++++++++++
4 files changed, 58 insertions(+)

create mode 100755 meta-isar/recipes-app/rust-hello-isar/files/rules
create mode 100644 meta-isar/recipes-app/rust-hello-isar/files/rust-hello-isar/Cargo.toml
create mode 100644 meta-isar/recipes-app/rust-hello-isar/files/rust-hello-isar/src/main.rs
create mode 100644 meta-isar/recipes-app/rust-hello-isar/rust-hello-isar_0.1.bb

diff --git a/meta-isar/recipes-app/rust-hello-isar/files/rules b/meta-isar/recipes-app/rust-hello-isar/files/rules
new file mode 100755
index 00000000..213cc876
--- /dev/null
+++ b/meta-isar/recipes-app/rust-hello-isar/files/rules
@@ -0,0 +1,27 @@
+#!/usr/bin/make -f
+
+export DEB_BUILD_MAINT_OPTIONS = hardening=+all
+DPKG_EXPORT_BUILDFLAGS = 1
+include /usr/share/dpkg/default.mk
+include /usr/share/rustc/architecture.mk
+export DEB_HOST_RUST_TYPE
+export PATH:=/usr/share/cargo/bin:$(PATH)
+export CARGO=/usr/share/cargo/bin/cargo
+export CARGO_HOME=$(CURDIR)/debian/cargo_home
+export CARGO_REGISTRY=$(CURDIR)/debian/cargo_registry
+export DEB_CARGO_CRATE=$(DEB_SOURCE)_$(DEB_VERSION_UPSTREAM)
+
+%:
+ dh $@ --buildsystem=cargo
+
+execute_after_dh_auto_clean:
+ $(CARGO) clean
+ rm -rf $(CARGO_HOME)
+ rm -rf $(CARGO_REGISTRY)
+ rm -f debian/cargo-checksum.json
+
+execute_before_dh_auto_configure:
+ $(CARGO) prepare-debian $(CARGO_REGISTRY) --link-from-system
+ rm -f Cargo.lock
+ touch debian/cargo-checksum.json
+
diff --git a/meta-isar/recipes-app/rust-hello-isar/files/rust-hello-isar/Cargo.toml b/meta-isar/recipes-app/rust-hello-isar/files/rust-hello-isar/Cargo.toml
new file mode 100644
index 00000000..f761691e
--- /dev/null
+++ b/meta-isar/recipes-app/rust-hello-isar/files/rust-hello-isar/Cargo.toml
@@ -0,0 +1,6 @@
+[package]
+name = "rust-hello-isar"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
diff --git a/meta-isar/recipes-app/rust-hello-isar/files/rust-hello-isar/src/main.rs b/meta-isar/recipes-app/rust-hello-isar/files/rust-hello-isar/src/main.rs
new file mode 100644
index 00000000..50469bdf
--- /dev/null
+++ b/meta-isar/recipes-app/rust-hello-isar/files/rust-hello-isar/src/main.rs
@@ -0,0 +1,3 @@
+fn main() {
+ println!("Hello, isar!");
+}
diff --git a/meta-isar/recipes-app/rust-hello-isar/rust-hello-isar_0.1.bb b/meta-isar/recipes-app/rust-hello-isar/rust-hello-isar_0.1.bb
new file mode 100644
index 00000000..2d57b8c8
--- /dev/null
+++ b/meta-isar/recipes-app/rust-hello-isar/rust-hello-isar_0.1.bb
@@ -0,0 +1,22 @@
+# Sample application
+#

+# This software is a part of ISAR.
+# Copyright (C) 2026 Siemens AG
+

+inherit dpkg
+
+DESCRIPTION = "Hello world example for Rust"
+MAINTAINER = "isar-users <isar-...@googlegroups.com>"
+
+SRC_URI = "file://${PN} \
+ file://rules"
+
+DEBIAN_BUILD_DEPENDS += "dh-cargo"
+
+S = "${WORKDIR}/${PN}"
+
+do_prepare_build() {
+ deb_debianize
+ install -m 644 ${WORKDIR}/rules ${S}/debian/rules
+}
+
--
2.53.0

[Quirin Gylstorff]

From: Quirin Gylstorff <quirin.g...@siemens.com>

Signed-off-by: Quirin Gylstorff <quirin.g...@siemens.com>
---

doc/user_manual.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 66 insertions(+)

diff --git a/doc/user_manual.md b/doc/user_manual.md
index 7520854b..75f72355 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -20,6 +20,7 @@ Copyright (C) 2016-2019, ilbers GmbH
- [Customize and configure image](#customize-and-configure-image)
- [Create a Custom Image Recipe](#create-a-custom-image-recipe)
- [Add a Custom Application](#add-a-custom-application)
+ - [Rust in ISAR Builds](#rust-in-isar-builds)
- [Build statistics collection](#build-statistics-collection)
- [Isar Cross-compilation](#isar-cross-compilation)
- [Examining and debugging package generation inside their schroot rootfs](#examining-and-debugging-package-generation-inside-their-schroot-rootfs)
@@ -1039,6 +1040,71 @@ be installed via `IMAGE_INSTALL`. Have a look at `prebuilt-deb`.

---

+## Rust in ISAR Builds
+
+This is a collection of recipes and links on how to
+package rust crates.
+
+This document takes most of its input from https://rust-team.pages.debian.net/book
+which contains the practices of the Debian rust team.
+
+### Crates on crates.io
+
+We provide a generator in `scripts/generate_cargo_crate.sh` which
+generates the scaffold for these crates. This follows more or less
+the approach of Debian with https://salsa.debian.org/rust-team/debcargo-conf.
+
+The user steps necessary are the following:
+
+1. Generate the package by calling:
+`scripts/generate_cargo_crate.sh <CRATE_NAME> [CRATE_VERSION]`.
+
+2. Patch to build with the current Debian release, e.g. relax the dependencies
+in `Cargo.toml`
+
+
+### Crates not on crates.io
+
+There is currently no generator and it is recommended to follow the traditional
+packaging approach, see also https://rust-team.pages.debian.net/book/process-workspace.html#general-setup.
+
+A working rules file could look like this:
+```

+```
+This example works for a cargo application and cannot be reused by other components
+as the file `debian/cargo-checksum.json` is empty.
+
+An example for the initial cargo crate can be found at `meta-isar/recipes-app/rust-hello-isar/`.
+
+---
+
## Build statistics collection

While isar is building the system, build statistics is collected in
--
2.53.0

[Jan Kiszka]

Maybe leave a comment like this behind:

# Created by generate_cargo_crate.sh.
# SPDX-License-Identifier: MIT-0

That license is like the MIT, except that it comes without the
attribution paragraph, thus allows re-licensing without hassles.

Jan

--
Siemens AG, Foundational Technologies
Linux Expert Center

[Jan Kiszka]

On 23.03.26 11:52, 'Quirin Gylstorff' via isar-users wrote:
> From: Quirin Gylstorff <quirin.g...@siemens.com>
>

Was the recipe generated as well, just augmented afterwards? :)

Jan

[Quirin Gylstorff]

On 3/23/26 12:21 PM, Jan Kiszka wrote:
> On 23.03.26 11:52, 'Quirin Gylstorff' via isar-users wrote:
>> From: Quirin Gylstorff <quirin.g...@siemens.com>
>>
>
> Was the recipe generated as well, just augmented afterwards? :)

No that was written manually. I was thinking about adding a generator
but that should be discussed.

Quirin

[Quirin Gylstorff]

On 3/23/26 1:03 PM, 'Quirin Gylstorff' via isar-users wrote:
>
>
> On 3/23/26 12:21 PM, Jan Kiszka wrote:
>> On 23.03.26 11:52, 'Quirin Gylstorff' via isar-users wrote:
>>> From: Quirin Gylstorff <quirin.g...@siemens.com>
>>>
>>
>> Was the recipe generated as well, just augmented afterwards? :)
>
> No that was written manually. I was thinking about adding a generator
> but that should be discussed.

With an additional use case the next point of discussion would be not to
use a bash script and build something more extensible.

Quirin

[MOESSBAUER, Felix]

On Mon, 2026-03-23 at 11:52 +0100, 'Quirin Gylstorff' via isar-users
wrote:

Please also add fake proxies to ensure nothing is pulled directly from
upstream. Or is this already taken by debcargo?

You probably want ${BPN}

> +           file://rules"
> +
> +DEBIAN_BUILD_DEPENDS += "dh-cargo"
> +
> +S = "${WORKDIR}/${PN}"

Same here.

Felix

> +
> +do_prepare_build() {
> +    deb_debianize
> +    install  -m 644 ${WORKDIR}/rules ${S}/debian/rules
> +}
> +
> --
> 2.53.0
>

> --
> You received this message because you are subscribed to the Google Groups "isar-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to isar-users+...@googlegroups.com.
> To view this discussion visit https://groups.google.com/d/msgid/isar-users/20260323105332.2721282-3-Quirin.Gylstorff%40siemens.com.

--
Siemens AG
Linux Expert Center
Friedrich-Ludwig-Bauer-Str. 3
85748 Garching, Germany

[Quirin Gylstorff]

The build uses a wrapper around
cargo(https://salsa.debian.org/rust-team/rust/-/blob/debian/sid/debian/bin/cargo?ref_type=heads)
which replaces crates.io with the local registry. In my opinion the
Proxy should not be necessary.

Good catch will fix in the next version.

Quirin