1// -*- mode:doc; -*-
2// vim: set syntax=asciidoc:
3
4=== Infrastructure for Cargo-based packages
5
6Cargo is the package manager for the Rust programming language. It allows the
7user to build programs or libraries written in Rust, but it also downloads and
8manages their dependencies, to ensure repeatable builds. Cargo packages are
9called "crates".
10
11[[cargo-package-tutorial]]
12
13==== +cargo-package+ tutorial
14
15The +Config.in+ file of Cargo-based package 'foo' should contain:
16
17---------------------------
1801: config BR2_PACKAGE_FOO
1902: 	bool "foo"
2003: 	depends on BR2_PACKAGE_HOST_RUSTC_TARGET_ARCH_SUPPORTS
2104: 	select BR2_PACKAGE_HOST_RUSTC
2205: 	help
2306: 	  This is a comment that explains what foo is.
2407:
2508: 	  http://foosoftware.org/foo/
26---------------------------
27
28And the +.mk+ file for this package should contain:
29
30------------------------------
3101: ################################################################################
3202: #
3303: # foo
3404: #
3505: ################################################################################
3606:
3707: FOO_VERSION = 1.0
3808: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
3909: FOO_SITE = http://www.foosoftware.org/download
4010: FOO_LICENSE = GPL-3.0+
4111: FOO_LICENSE_FILES = COPYING
4212:
4313: $(eval $(cargo-package))
44--------------------------------
45
46The Makefile starts with the definition of the standard variables for
47package declaration (lines 7 to 11).
48
49As seen in line 13, it is based on the +cargo-package+
50infrastructure. Cargo will be invoked automatically by this
51infrastructure to build and install the package.
52
53It is still possible to define custom build commands or install
54commands (i.e.  with FOO_BUILD_CMDS and FOO_INSTALL_TARGET_CMDS).
55Those will then replace the commands from the cargo infrastructure.
56
57==== +cargo-package+ reference
58
59The main macros for the Cargo package infrastructure are
60+cargo-package+ for target packages and +host-cargo-package+ for host
61packages.
62
63Just like the generic infrastructure, the Cargo infrastructure works
64by defining a number of variables before calling the +cargo-package+
65or +host-cargo-package+ macros.
66
67First, all the package metadata information variables that exist in
68the generic infrastructure also exist in the Cargo infrastructure:
69+FOO_VERSION+, +FOO_SOURCE+, +FOO_PATCH+, +FOO_SITE+,
70+FOO_DEPENDENCIES+, +FOO_LICENSE+, +FOO_LICENSE_FILES+, etc.
71
72A few additional variables, specific to the Cargo infrastructure, can
73also be defined. Many of them are only useful in very specific cases,
74typical packages will therefore only use a few of them.
75
76* +FOO_SUBDIR+ may contain the name of a subdirectory inside the package
77  that contains the Cargo.toml file. This is useful, if for example, it
78  is not at the root of the tree extracted by the tarball. If
79  +HOST_FOO_SUBDIR+ is not specified, it defaults to +FOO_SUBDIR+.
80
81* +FOO_CARGO_ENV+ can be used to pass additional variables in the
82  environment of +cargo+ invocations. It used at both build and
83  installation time
84
85* +FOO_CARGO_BUILD_OPTS+ can be used to pass additional options to
86  +cargo+ at build time.
87
88* +FOO_CARGO_INSTALL_OPTS+ can be used to pass additional options to
89  +cargo+ at install time.
90
91A crate can depend on other libraries from crates.io or git
92repositories, listed in its +Cargo.toml+ file. Buildroot automatically
93takes care of downloading such dependencies as part of the download
94step of packages that use the +cargo-package+ infrastructure. Such
95dependencies are then kept together with the package source code in
96the tarball cached in Buildroot's +DL_DIR+, and therefore the hash of
97the package's tarball includes such dependencies.
98
99This mechanism ensures that any change in the dependencies will be
100detected, and allows the build to be performed completely offline.
101