From 79007d04fc5f43749ef9a878682bc6c488e6340e 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: 7d715d62c32ab81d26bf1ff82f79ad2c4a2e3f85) Signed-off-by: Richard Purdie CC: Yoann Congal Signed-off-by: Richard Purdie --- documentation/contributor-guide/recipe-style-guide.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'documentation/contributor-guide') 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