| Message ID | 20230920145954.1055731-1-richard.purdie@linuxfoundation.org |
|---|---|
| State | New |
| Headers | show |
| Series | contributor-guide/style-guide: Add a note about task idempotence | expand |
Hi, On 9/20/23 16:59, Richard Purdie wrote: > Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org> > --- > documentation/contributor-guide/recipe-style-guide.rst | 10 ++++++++++ > 1 file changed, 10 insertions(+) > > diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst > index 1a1c1c6ee..040536058 100644 > --- a/documentation/contributor-guide/recipe-style-guide.rst > +++ b/documentation/contributor-guide/recipe-style-guide.rst > @@ -257,6 +257,16 @@ 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 it is usually best to copy a file 'X' to > + 'X.orig' only if it already doesn't exist before copying 'X.orig' to 'X' and > + modifying 'X'. This ensures if rerun the task always has the same end result I have a hard time parsing this phrase :-/ How about : For idempotence, when modifying files, 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'. (Not being a native speaker, I've no idea if this is really better T_T) > + and the original file can be preserved to reuse. It also guards against an > + interrupted build corrupting the file. > + > Patch Upstream Status > ===================== > Regards,
diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst index 1a1c1c6ee..040536058 100644 --- a/documentation/contributor-guide/recipe-style-guide.rst +++ b/documentation/contributor-guide/recipe-style-guide.rst @@ -257,6 +257,16 @@ 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 it is usually best to copy a file 'X' to + 'X.orig' only if it already doesn't exist before copying 'X.orig' to 'X' and + modifying '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 =====================
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org> --- documentation/contributor-guide/recipe-style-guide.rst | 10 ++++++++++ 1 file changed, 10 insertions(+)