From eb17e06e8b9f72268b0d920463ad169a72cf359d Mon Sep 17 00:00:00 2001 From: Antonin Godard Date: Wed, 9 Oct 2024 09:41:01 +0200 Subject: [PATCH] ref-manual: add new retain class and variables Document the new `retain` class with its configuration variables in the variable index. (From yocto-docs rev: b62f1be5dada0fb760ff7e0806b16225f7261560) Signed-off-by: Antonin Godard Signed-off-by: Richard Purdie --- documentation/ref-manual/classes.rst | 17 +++++++++++++ documentation/ref-manual/variables.rst | 35 ++++++++++++++++++++++++++ 2 files changed, 52 insertions(+) diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 46d77d0e55..9f6e427253 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -2728,6 +2728,23 @@ commit, and log. From the information, report files using a JSON format are created and stored in ``${``\ :term:`LOG_DIR`\ ``}/error-report``. +.. _ref-classes-retain: + +``retain`` +========== + +The :ref:`ref-classes-retain` class can be used to create a tarball of the work +directory for a recipe when one of its tasks fails, or any other nominated +directories. It is useful in cases where the environment in which builds are run +is ephemeral or otherwise inaccessible for examination during debugging. + +To enable, add the following to your configuration:: + + INHERIT += "retain" + +The class can be disabled for specific recipes using the :term:`RETAIN_ENABLED` +variable. + .. _ref-classes-rm-work: ``rm_work`` diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index dd97a63c0d..853e50cf9f 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -7137,6 +7137,41 @@ system and gives an overview of their function and contents. If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set for the same recipe, the :term:`REQUIRED_VERSION` value applies. + :term:`RETAIN_DIRS_ALWAYS` + When inheriting the :ref:`ref-classes-retain` class, this variable holds + space-separated recipe-specific directories to always save in a tarball + whether the recipe build has failed or not. + + :term:`RETAIN_DIRS_FAILURE` + When inheriting the :ref:`ref-classes-retain` class, this variable holds + space-separated recipe-specific directories to save in a tarball on + failure of the recipe's build. + + :term:`RETAIN_DIRS_GLOBAL_ALWAYS` + When inheriting the :ref:`ref-classes-retain` class, this variable holds + space-separated directories that are not specific to a recipe to save in a + tarball whether the build has failed or not. + + :term:`RETAIN_DIRS_GLOBAL_FAILURE` + When inheriting the :ref:`ref-classes-retain` class, this variable holds + space-separated directories that are not specific to a recipe to save in a + tarball on build failure. + + :term:`RETAIN_ENABLED` + Disables the creation of a tarball of the work directory done by the + :ref:`ref-classes-retain` class. Can be set to specific recipes to disable + the class when the class was inherited globally with :term:`INHERIT`. + + :term:`RETAIN_OUTDIR` + When inheriting the :ref:`ref-classes-retain` class, this variable + specifies the directory where to save the tarball of the work directory. + The default directory is ``${TMPDIR}/retain``. + + :term:`RETAIN_TARBALL_SUFFIX` + When inheriting the :ref:`ref-classes-retain` class, this variable + specifies the suffix of the tarball of the work directory. The default + suffix is ``${DATETIME}.tar.gz``. + :term:`RM_WORK_EXCLUDE` With :ref:`ref-classes-rm-work` enabled, this variable specifies a list of recipes whose work directories should not be removed.