adding-packages-cargo.txt 3.7 KB

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