From 7ffedb40a1bae3e287253c1348141fdcee0504a6 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Wed, 20 Sep 2023 15:59:54 +0100 Subject: contributor-guide/style-guide: Add a note about task idempotence (From yocto-docs rev: 681e6a0a4305057f7b96f5bef804391d8aff812b) Signed-off-by: Richard Purdie CC: Yoann Congal Signed-off-by: Steve Sakoman --- documentation/contributor-guide/recipe-style-guide.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst index 1a1c1c6ee2..b63172bd77 100644 --- a/documentation/contributor-guide/recipe-style-guide.rst +++ b/documentation/contributor-guide/recipe-style-guide.rst @@ -257,6 +257,20 @@ Tips and Guidelines for Writing Recipes and ``-nativesdk`` ones, whenever possible. This avoids having to maintain multiple recipe files at the same time. +- Recipes should have tasks which are idempotent, i.e. that executing a given task + multiple times shouldn't change the end result. The build environment is built upon + this assumption and breaking it can cause obscure build failures. + +- For idempotence when modifying files in tasks, it is usually best to: + + - copy a file ``X`` to ``X.orig`` (only if it doesn't exist already) + - then, copy ``X.orig`` back to ``X``, + - and, finally, modify ``X``. + + This ensures if rerun the task always has the same end result and the + original file can be preserved to reuse. It also guards against an + interrupted build corrupting the file. + Patch Upstream Status ===================== -- cgit v1.2.3-54-g00ecf