10401 2016-10-08 00:37:30 +0000 Suggested fleshing out of the 'addtask' documentation 2016-10-11 15:02:55 +0000 1 1 9 Documentation BitBake User Manual bitbake-manual 2.2 x86 Multiple RESOLVED FIXED 11 Oct 2016: RESOLVED Undecided normal 2.3 M1 1 ulfalizer srifenbark kergoth richard.purdie ross.burton srifenbark --- --- Done (doc changes complete) oldest_to_newest 67072 0 ulfalizer 2016-10-08 00:37:30 +0000 Here's some suggested changes to add some more details and do some cleanup in '3.6. Tasks': * '3.6. Tasks' and '3.6.1. Promoting a Function to a Task' repeat the same example verbatim. '3.6. Tasks' could be shortened to just the introductory paragraph, and could also be simplified a bit. For example, addtask forces task names to start with "do_", so calling it a convention might give the wrong idea. Here's a suggested new version of '3.6. Tasks': Tasks are BitBake execution units that make up the steps that BitBake can run for a given recipe. Tasks are only supported in recipes and classes (that is, in .bb files and files included or inherited from .bb files). Tasks have names that start with "do_". * '3.6.1. Promoting a Function to a Task' could then be rewritten as follows: Tasks are either [shell functions](https://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#shell-functions) or [BitBake-style Python functions](https://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#bitbake-style-python-functions) that have been promoted to tasks by using the 'addtask' command. The 'addtask' command can also optionally describe dependencies between the task and other tasks. Here is an example of a task being defined, along with some dependencies being declared: python do_printdate () { import time print time.strftime('%Y%m%d', time.gmtime()) } addtask printdate after do_fetch before do_build The first argument to 'addtask' is the name of the function to promote to a task. If the name does not start with "do_", "do_" is added implicitly, which enforces the convention that all task names start with "do_". In the example above, the 'do_printdate' task becomes a dependency of the 'do_build' task, which is the default task (the task run by 'bitbake' command unless another task is specified explicitly). In addition, the 'do_printdate' task becomes dependent upon the 'do_fetch' task. Running the 'do_build' task will result in the 'do_printdate' task running first. Note { If you try out the example above, you might see 'do_printdate' only being run the first time you build the recipe with 'bitbake'. This is because BitBake considers the task "up-to-date" after that. If you want to force the task to always be rerun for experimentation purposes, you can make BitBake always consider it "out-of-date" by using the [[nostamp]](https://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#variable-flags) variable flag, as follows: do_printdate[nostamp] = "1" Another option is to explicitly run the task with the '-f' flag, as follows: $ bitbake <recipe> -c printdate -f When manually selecting a task to run with 'bitbake <recipe> -c <task>', the "do_" prefix on the task can also be omitted. } You might wonder what the practical effect of using 'addtask' without specifying any dependencies is, like in the following example: addtask printdate In this case, assuming dependencies have not been added through some other means, the only way to run the task is by explicitly selecting it with 'bitbake <recipe> -c printdate'. The 'do_listtasks' task can be run to list all the tasks defined in a recipe, using 'bitbake <recipe> -c listtasks'. For more information on task dependencies, see the [Dependencies](https://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#dependencies) section. See the [Variable Flags](https://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#variable-flags) section for variable flags that can be used with tasks. * As an unrelated change, the [noexec] and [nostamp] description in '3.7. Variable Flags' could be clarified a bit, and a warning could be added: [noexec]: When set to "1", marks the task as being empty, with no execution required. <same as before...> [nostamp]: When set to "1", tells BitBake <same as before...> Caution { Any task that depends (possibly indirectly) on a [nostamp] task will always be executed as well. This can cause unnecessary rebuilding if you are not careful. } Cheers, Ulf 67100 1 srifenbark 2016-10-10 19:53:12 +0000 Ulf, See http://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#tasks for the new 3.6 section. See http://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#promoting-a-function-to-a-task for the new 3.6.1 section. See http://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#variable-flags for the changes to the two flags. Let me know if there are any problems or changes. thanks, Scott 67116 2 ulfalizer 2016-10-11 01:15:57 +0000 A few nits below: * The "to" sounds weird to me here: Here is an example that shows how to define a task and [to] declare some dependencies: * Missing "that" here? If you try out the previous example, you might see [that] the do_printdata... * Extra "the" before the command here: the only way to run the task is by explicitly selecting it with [the] bitbake recipe -c printdate. Cheers, Ulf 67141 3 srifenbark 2016-10-11 15:02:55 +0000 Ulf, Thanks for the catches... See http://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#promoting-a-function-to-a-task. I am setting to RESOLVED and turning doc flag to "done." Scott