Using Rust in CRAN packages

[Simplified 2023-07-13, $Revision: 6279 $]

Packages wishing to use Rust code should either

• include the code in the package, or
• download a specific version from a secure and reliable site and check that the download is the expected code by some sort of checksum. The expected checksum needs to be embedded in the source package.

In either case, the authorship and copyright information for the Rust code must be included in the DESCRIPTION file. That includes any Rust sources included as dependencies (see the CRAN policy).

The package should declare

SystemRequirements: Cargo (Rust's package manager), rustc

as they can be packaged separately, and can have different versions. So state carefully any version requirement. (For example, in July 2023 the current Debian distributions included cargo 0.66.0 whereas some had Rustc 1.63.0 and some 1.66.0.) NB: additional version requirements can be imposed by bundled/downloaded ‘crates’. OSes do not necessarily keep cargo up to date (e.g. Ubuntu LTS versions are only updated on some architectures), so test before submission with at least a two-year-old version of cargo, and preferably one four or more years old.

The configure/configure.win script should check for the presence of commands cargo and rustc, and check their versions if required. This includes checking for system versions on the path and personal versions in ~/.cargo/bin (which are often not on the path). The Linux servers on the CRAN check farm use system versions, and Linux distributions are often slow to update these so version requirements need to be conservative.

If suitable cargo/rustc are not found, ask the user to install them, either on their Linux system by something like

dnf install cargo
apt-get install cargo rustc

or by using rustup from https://rustup.rs/ . The package should not attempt to install these for itself.

cargo build -j N defaults to the number of ‘logical CPUs’. This usually exceeds the maximum allowed in the CRAN policy, so needs to be set explicitly to N=1 or 2.

Please report the version of rustc used (as R does for C, C++ and Fortran compilers) in the installation log especially if compilation fails, so best reported before starting compilation (as R does).

Caveats:

Downloading should be avoided if at all possible. The package would become uninstallable if the Internet resources are temporarily or permanently unavailable, and CRAN packages are kept available for many years. CRAN does not regard github.com (which used to host the index of crates.io and still hosts most of the crates it indexes) as sufficiently reliable.

In most cases all the Rust software can be bundled into the package via cargo vendor. (Thanks to Hiroaki Yutani for providing an example of doing that in his string2path package, version 0.1.5 at the time of writing.) Please tar the included Rust sources using xz compression. If the bundle is too large to be included in the package sources, it could be hosted at a long-term secure site under the maintainer’s control.