// -*- mode:doc; -*- // vim: set syntax=asciidoc: === Integration of Cargo-based packages Cargo is the package manager for the Rust programming language. It allows the user to build programs or libraries written in Rust, but it also downloads and manages their dependencies, to ensure repeatable builds. Cargo packages are called "crates". [[cargo-package-tutorial]] ==== Cargo-based package's +Config.in+ file The +Config.in+ file of Cargo-based package 'foo' should contain: --------------------------- 01: config BR2_PACKAGE_FOO 02: bool "foo" 03: depends on BR2_PACKAGE_HOST_RUSTC_TARGET_ARCH_SUPPORTS 04: select BR2_PACKAGE_HOST_RUSTC 05: help 06: This is a comment that explains what foo is. 07: 08: http://foosoftware.org/foo/ --------------------------- ==== Cargo-based package's +.mk+ file Buildroot does not (yet) provide a dedicated package infrastructure for Cargo-based packages. So, we will explain how to write a +.mk+ file for such a package. Let's start with an example: ------------------------------ 01: ################################################################################ 02: # 03: # foo 04: # 05: ################################################################################ 06: 07: FOO_VERSION = 1.0 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz 09: FOO_SITE = http://www.foosoftware.org/download 10: FOO_LICENSE = GPL-3.0+ 11: FOO_LICENSE_FILES = COPYING 12: 13: FOO_DEPENDENCIES = host-rustc 14: 15: FOO_CARGO_ENV = CARGO_HOME=$(HOST_DIR)/share/cargo 16: 17: FOO_BIN_DIR = target/$(RUSTC_TARGET_NAME)/$(FOO_CARGO_MODE) 18: 19: FOO_CARGO_OPTS = \ 20: $(if $(BR2_ENABLE_DEBUG),,--release) \ 21: --target=$(RUSTC_TARGET_NAME) \ 22: --manifest-path=$(@D)/Cargo.toml 23: 24: define FOO_BUILD_CMDS 25: $(TARGET_MAKE_ENV) $(FOO_CARGO_ENV) \ 26: cargo build $(FOO_CARGO_OPTS) 27: endef 28: 29: define FOO_INSTALL_TARGET_CMDS 30: $(INSTALL) -D -m 0755 $(@D)/$(FOO_BIN_DIR)/foo \ 31: $(TARGET_DIR)/usr/bin/foo 32: endef 33: 34: $(eval $(generic-package)) -------------------------------- The Makefile starts with the definition of the standard variables for package declaration (lines 7 to 11). As seen in line 34, it is based on the xref:generic-package-tutorial[+generic-package+ infrastructure]. So, it defines the variables required by this particular infrastructure, where Cargo is invoked: * +FOO_BUILD_CMDS+: Cargo is invoked to perform the build. The options required to configure the cross-compilation of the package are passed via +FOO_CONF_OPTS+. * +FOO_INSTALL_TARGET_CMDS+: The binary executable generated is installed on the target. In order to have Cargo available for the build, +FOO_DEPENDENCIES+ needs to contain +host-cargo+. To sum it up, to add a new Cargo-based package, the Makefile example can be copied verbatim then edited to replace all occurences of +FOO+ with the uppercase name of the new package and update the values of the standard variables. ==== About Dependencies Management A crate can depend on other libraries from crates.io or git repositories, listed in its Cargo.toml file. Before starting a build, Cargo usually downloads automatically them. This step can also be performed independently, via the +cargo fetch+ command. Cargo maintains a local cache of the registry index and of git checkouts of the crates, whose location is given by +$CARGO_HOME+. As seen in the package Makefile example at line 15, this environment variable is set to +$(HOST_DIR)/share/cargo+. This dependency download mechanism is not convenient when performing an offline build, as Cargo will fail to fetch the dependencies. In that case, it is advised to generate a tarball of the dependencies using the +cargo vendor+ and add it to +FOO_EXTRA_DOWNLOADS+.