diff mbox series

[v2] ref-manual: document Rust classes

Message ID 20230203101418.54074-1-michael.opdenacker@bootlin.com
State New
Headers show
Series [v2] ref-manual: document Rust classes | expand

Commit Message

Michael Opdenacker Feb. 3, 2023, 10:14 a.m. UTC
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 mbox series


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:
+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``
+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>`__
+This class inherits the :ref:`ref-classes-cargo_common` class.
+.. _ref-classes-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:
+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
+   require ${BPN}-crates.inc
+That's also something you can achieve by using the
+`cargo-bitbake <https://crates.io/crates/cargo-bitbake>`__ tool.
@@ -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:
+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:
+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: