123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109 |
- // -*- 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+.
|