= upstream-cargo build profile =

Packages which use Rust libraries may, where the maintainer finds it useful, support the `upstream-cargo` build profile.

== Packages for which the build profile is (or should be) supported ==

Packages whose maintainer wishes to adopt a hybrid workflow, where development of the Debian package is sometimes conducted using Rust dependencies from Debian, and sometimes using Rust dependencies from the upstream Rust ecosystem (`crates.io`), may support this profile and annotate their `Build-Depends` appropriately.

This is only relevant for packages which `Build-Depend` on Rust libraries, `librust-*-dev`.  And, not Rust library packages themselves: only packages whose `.deb`s contain the output of running a Rust compiler (or similar).

Support for this profile should only be added to a source package pursuant to a specific decision by that package's maintainer, that it is useful for that package.

== Effect ==

Rust library packages (Rust "crates") will not be looked for in `/usr/share/cargo/registry` (as is usually populated by Debian Rust libraries).  Instead, the dependencies will be obtained from the upstream repository `crates.io`.

This will usually cause the build to make network accesses.

Packages that support this profile must provide `Cargo.lock` file(s) and use exclusively those versions of the dependencies, during the build.  (Otherwise running a build with this profile might download and incorporate unexpected, unaudited, and uncontrolled, updates from the upstream repository.)  Updates to the `Cargo.lock` must be made separately (probably, using upstream tooling directly).

The resulting built binary packages ''should'' behave equivalently to the normal ones (without the `upstream-cargo` profile, i.e. using the dependencies from Debian).  Failure to behave equivalently would be a bug, caused by Rust libraries not adhering to the usual semver rules.  "Equivalently" is not defined, and, in general, no particular level of similarity may be relied on.

The set of generated binary packages shouldn't change.

The build profile does not affect the versions of the Rust toolchain used: these will be installed via the build dependencies on (eg) `rustc` (which should not be annotated with `upstream-cargo`).  Then the actual compiler etc. will be found from `PATH` in the usual way.

== Annotated build dependencies ==

In a package whose maintainer chooses to work this way, every build-dependency on a Rust library `librust-*-dev` will be annotated with `<!upstream-cargo>`.  It does not make sense to annotate only some of the Rust library dependencies.  (Other build deps involving Rust, eg `rustc`, or packages containing programs written in Rust, must not be so annotated.)

Debian Rust packaging tooling will not automatically annotate build-dependencies.  Adding this profile annotation to every Rust package would be significant bloat.  So the annotated build dependencies must be maintained ad-hoc.

== Implementation ==

Currently, there is no support for this profile in Debian cargo tooling; the profile must be handled by ad-hoc arrangements in `debian/rules`.

== Future possibilities ==

1. Debian Rust tooling could notice this build profile, and implement the during-build parts automatically.  This would simplify the packages  which wish to implement the profile.  It would also assist a user who wishes to apply the profile to a naive package (but the user would still have to bypass the Rust library build dependencies, since would remain un-annotated and therefore unconditional in the `.dsc`).

2. Some general arrangement could be made to arrange that this build profile automatically disables all `librust-*-dev` build deps.  This would make this profile be automatically supported by every applicable package, without bloating the sources databases.  Whether to do this, what precisely to do, and where this should be implemented, are open questiohns.

Also, similar arrangements may make sense for other non-Debian package managers (eg the various language-specific package managers).  These should have their own build profiles, each named after the relevant package manager.

== References ==

Original discussion on debian-devel: https://lists.debian.org/debian-devel/2022/12/msg00111.html et seq