9612 2016-05-09 23:17:13 +0000 functions used in recipes and recipe examples (like bb.utils.contains) not documented. 2026-10-23 08:13:48 +0000 1 1 9 Documentation Mega Manual mega-manual 2.2 x86 Multiple IN PROGRESS REVIEW Medium enhancement 6.2 M4 9725 1 brian.avery antonin.godard bluelightning mathieu.dubois-briand michael.opdenacker mshah randy.macleod richard.purdie sgw srifenbark tim.orling --- --- Yes (doc changes required) oldest_to_newest 62058 0 brian.avery 2016-05-09 23:17:13 +0000 Some useful functions like bb.utils.contains are used in recipes, and appear in the mega-manual in a number of examples in that manual. Unfortunately the methods for the class and what the args are are not documented afaik. What we say: --- 26.148. utils.bbclass¶ The utils class provides some useful Python functions that are typically used in inline Python expressions (e.g. ${@...}). One example use is for bb.utils.contains(). This class is enabled by default because it is inherited by the base class. --- Seems like these should be documented especially if we are using them as examples in the manual. 62137 1 bluelightning 2016-05-12 04:01:37 +0000 Looks like what we do have is a bit confused anyway. bb.utils is not the same thing as utils.bbclass (though there is some functional overlap). 62345 2 srifenbark 2016-05-19 17:32:54 +0000 Paul, What do you suggest we do for the utils.bbclass description? (http://www.yoctoproject.org/docs/2.1/mega-manual/mega-manual.html#ref-classes-utils) Here is an occurrence also - http://www.yoctoproject.org/docs/2.1/mega-manual/mega-manual.html#var-TUNE_ASARGS And here - http://www.yoctoproject.org/docs/2.1/mega-manual/mega-manual.html#var-TUNE_LDARGS Scott 62371 3 brian.avery 2016-05-20 17:21:39 +0000 We should probably document all the functions used outside of the utils file including arguments and return values. For ones commonly used in (contains, for instance) meta/bbclass files we should collocate the example with the definition of the function and arguments. 62689 4 srifenbark 2016-06-06 21:55:50 +0000 So we want to document all functions in the class? I am not sure what you mean by document "all functions outside of the utils file". 62719 5 brian.avery 2016-06-07 19:51:04 +0000 What I meant by "used outside" of the utils file is that some of the functions in the utils file are class functions not meant to be used in recipes/classes. The other functions, which amount to the utils API, are. The API functions used in the outside recipes or bbclass files should be documented. Functions like: contains lockfile unlockfile prunedir explode_dep_versions2 join_deps explode_deps mkdirheir copyfile The above were from a quick grep/scan script and are probably not complete... 62723 6 bluelightning 2016-06-07 20:57:08 +0000 If any of the functions we want documented don't have docstrings in the source then we need to fix that before sending over to Scott, just so he has something to work with. 62724 7 joshuagloe 2016-06-07 21:01:57 +0000 Of Brian's list the only one missing a docstring is prunedir, though that does have a non-docstring comment explaining what it does. 62725 8 joshuagloe 2016-06-07 21:06:59 +0000 (In reply to comment #7) > Of Brian's list the only one missing a docstring is prunedir, though that > does have a non-docstring comment explaining what it does. That's not true, explode_versions and explode_dep_versions don't have docstrings or comments. I shall write a patch for bitbake/lib/bb/utils.py 62728 9 brian.avery 2016-06-07 21:28:17 +0000 see bug 9725 for the docstring bug. i put a list of fxns in it and made it block this bug. 62844 10 srifenbark 2016-06-09 16:39:21 +0000 So for documenting these functions, are we suggesting an entire new section in the ref-manual similar to how we document classes and tasks? Right now we have long lists of these at http://www.yoctoproject.org/docs/2.2/ref-manual/ref-manual.html#ref-classes and http://www.yoctoproject.org/docs/2.2/ref-manual/ref-manual.html#ref-tasks, respectively. If so, I imagine that this would create a pretty big list of functions to document. Am I right in understanding the bigger picture here for this documentation bug? Scott 62869 11 brian.avery 2016-06-09 18:19:05 +0000 from my perspective, yes. I'd add a new section Library funxtions (utils are in bitbake/lib/... ) and document each function that is intended for external use. Paul, concur? 62878 12 bluelightning 2016-06-09 21:25:40 +0000 Yes, that would make sense to me also. 62978 13 srifenbark 2016-06-14 20:37:18 +0000 Okay... who can give me the list of functions we need? Or, can I generate that list somehow? Thanks, Scott 63000 14 joshuagloe 2016-06-15 13:29:55 +0000 Hi Scott, (In reply to comment #13) > Okay... who can give me the list of functions we need? Or, can I generate > that list somehow? I have the AR to go and document the functions in the code, which is being tracked in the "Depends on" bug #9725: https://bugzilla.yoctoproject.org/show_bug.cgi?id=9725 When that work is done we should have both the list of functions that need documenting and comments in the code which can form the basis of some manual content. 72498 15 srifenbark 2017-04-13 20:49:53 +0000 Joshua, Can you push this to post 2.3? We can't get this done in time probably. I would change it but I don't own it at the moment :) thanks Scott 86969 16 randy.macleod 2020-04-09 15:18:14 +0000 Robert, would you like to work on this? We think it's important to have it documented. 87331 17 rpjday 2020-05-25 15:19:16 +0000 OK, I'll take a look. 88908 18 mshah 2021-01-11 13:05:46 +0000 Hi All, I fixed Bug 9725 and one can have a look at the changes from the link mentioned in the comments of Bug 9725. Is there any work needed for this bug now? If Yes then please let me know. Thanks, Milan Shah 88917 19 richard.purdie 2021-01-13 23:30:09 +0000 (In reply to comment #18) > Hi All, > > I fixed Bug 9725 and one can have a look at the changes from the link > mentioned in the comments of Bug 9725. > > Is there any work needed for this bug now? If Yes then please let me know. > > Thanks, > Milan Shah For this bug, the work is to add a new "library functions" section to the manual in the reference manual in the yocto-docs repository and document the utils functions to start with. 89538 20 mshah 2021-03-09 13:09:39 +0000 (In reply to comment #19) > For this bug, the work is to add a new "library functions" section to the > manual in the reference manual in the yocto-docs repository and document the > utils functions to start with. Hi Richard, Does it means that I need to create a new file under ref-manual with library functions.rst name and write function details there? If yes then can you share a template to follow or show me a sample to start with? 89542 21 mshah 2021-03-09 13:47:54 +0000 (In reply to comment #19) > > For this bug, the work is to add a new "library functions" section to the > manual in the reference manual in the yocto-docs repository and document the > utils functions to start with. Hi Richard, I'm making a list of all functions to add to the document. I'm concerned about the ordering of these functions. Should I order them alphabetically? If yes then there are some functions that start with an underscore ( _ ), where should I put them? 89616 22 mshah 2021-03-12 12:39:24 +0000 Patch is sent for review. View/Reply Online (#899): https://lists.yoctoproject.org/g/docs/message/899 89621 23 mshah 2021-03-15 06:05:03 +0000 New Patch is sent ----------------- View/Reply Online (#903): https://lists.yoctoproject.org/g/docs/message/903 90416 24 mshah 2021-05-19 05:14:08 +0000 Do we have any update on patch review? Regards Milan Shah 90418 25 randy.macleod 2021-05-20 01:14:01 +0000 Pinged the v2 thread and added michael.opdenacker@bootlin.com 91966 26 randy.macleod 2021-11-11 15:59:27 +0000 Michael, can you followup on this please? 99992 27 randy.macleod 2024-10-24 15:03:54 +0000 Bulk move of 5.1 M4 to 5.2 M2 as approved by AlexB. 101185 28 randy.macleod 2025-02-20 16:21:11 +0000 Antonin, There is a patch on the list as mentioned in the bug or comments. 101701 29 antonin.godard 2025-04-22 08:55:20 +0000 Patches sent on bitbake list to auto document patches from the Python docstrings: https://lists.openembedded.org/g/bitbake-devel/topic/patch_0_4_document_library/112332815 Moving to In Progress Review. 102198 30 antonin.godard 2025-06-06 07:45:01 +0000 Bulk move of bugs I am assigned to from Milestone 5.2 to 5.3M1. 106676 31 mathieu.dubois-briand 2026-08-28 08:02:02 +0000 I can see patch merged: https://git.openembedded.org/bitbake/commit/?id=0a711949acc2696f32a61c591ee3ea37041acb91 Antonin, do we need more or should we close this bug entry? 106678 32 antonin.godard 2026-08-28 09:01:02 +0000 (In reply to Mathieu Dubois-Briand from comment #31) > I can see patch merged: > https://git.openembedded.org/bitbake/commit/ > ?id=0a711949acc2696f32a61c591ee3ea37041acb91 > > Antonin, do we need more or should we close this bug entry? It has been on my mind to try and to the same of `oe.utils.*` function and incorporate that to yocto-docs somehow, which is probably why I haven't closed this bug yet.