[PATCH v2] ref-manual: document Rust classes

[PATCH v2] ref-manual: document Rust classes

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>

---

Changes in V2:

- Grammar fix: replace "an src" by "a src" (Richard Purdie)
- Document the cargo-update-recipe-crates class,
  thanks to information provided by Alex Kiernan
---
 documentation/ref-manual/classes.rst | 78 ++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 0cb507b500..b5443c0d0a 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -254,8 +254,68 @@ When inherited globally, prints statistics at the end of the build on
 sstate re-use. In order to function, this class requires the
 :ref:`ref-classes-buildstats` class be enabled.
 
+.. _ref-classes-cargo:
+
+``cargo``
+=========
+
+The :ref:`ref-classes-cargo` class allows to compile Rust language programs
+using `Cargo <https://doc.rust-lang.org/cargo/>`__. Cargo is Rust's package
+manager, allowing to fetch package dependencies and build your program.
+
+Using this class makes it very easy to build Rust programs. All you need
+is to use the :term:`SRC_URI` variable to point to a source repository
+which can be built by Cargo, typically one that was created by the
+``cargo new`` command, containing a ``Cargo.toml`` file and a ``src``
+subdirectory.
+
+You will find a simple example in the
+:oe_git:`rust-hello-world_git.bb </openembedded-core/tree/meta/recipes-extended/rust-example/rust-hello-world_git.bb>`
+recipe. A more complex example, with package dependencies, is the
+:oe_git:`uutils-coreutils </meta-openembedded/tree/meta-oe/recipes-core/uutils-coreutils>`
+recipe, which was generated by the `cargo-bitbake <https://crates.io/crates/cargo-bitbake>`__
+tool.
+
+This class inherits the :ref:`ref-classes-cargo_common` class.
+
+.. _ref-classes-cargo_common:
+
+``cargo_common``
+================
+
+The :ref:`ref-classes-cargo_common` class is an internal class
+that is not intended to be used directly.
+
+An exception is the "rust" recipe, to build the Rust compiler and runtime
+library, which is built by Cargo but cannot use the :ref:`ref-classes-cargo`
+class. This is why this class was introduced.
+
 .. _ref-classes-ccache:
 
+.. _ref-classes-cargo-update-recipe-crates:
+
+``cargo-update-recipe-crates``
+===============================
+
+The :ref:`ref-classes-cargo-update-recipe-crates` class allows
+recipe developers to update the list of Cargo crates in :term:`SRC_URI`
+by reading the ``Cargo.lock`` file in the source tree.
+
+To do so, create a recipe for your program, for example using
+:doc:`devtool </ref-manual/devtool-reference>`,
+make it inherit the :ref:`ref-classes-cargo` and
+:ref:`ref-classes-cargo-update-recipe-crates` and run::
+
+   bitbake -c update_crates recipe
+
+This creates a ``recipe-crates.inc`` file that you can include in your
+recipe::
+
+   require ${BPN}-crates.inc
+
+That's also something you can achieve by using the
+`cargo-bitbake <https://crates.io/crates/cargo-bitbake>`__ tool.
+
 ``ccache``
 ==========
 
@@ -2493,6 +2553,24 @@ For information on how root filesystem images are created, see the
 ":ref:`overview-manual/concepts:image generation`"
 section in the Yocto Project Overview and Concepts Manual.
 
+.. _ref-classes-rust:
+
+``rust``
+========
+
+The :ref:`ref-classes-rust` class is an internal class which is just used
+in the "rust" recipe, to build the Rust compiler and runtime
+library. Except for this recipe, it is not intended to be used directly.
+
+.. _ref-classes-rust-common:
+
+``rust-common``
+===============
+
+The :ref:`ref-classes-rust-common` class is an internal class to the
+:ref:`ref-classes-cargo_common` and :ref:`ref-classes-rust` classes and is not
+intended to be used directly.
+
 .. _ref-classes-sanity:
 
 ``sanity``
-- 
2.37.2