[PATCH] doc: More explanation to tasks that recursively depend on themselves

[PATCH] doc: More explanation to tasks that recursively depend on themselves

[Jacob Kroon]

Signed-off-by: Jacob Kroon <jacob.kroon@gmail.com>
---
 .../bitbake-user-manual-metadata.xml               | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index 95a8b95b..069a0ec8 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -2565,15 +2565,17 @@
             </para>
 
             <para>
-                You might want to not only have BitBake look for
-                dependencies of those tasks, but also have BitBake look
-                for build-time and runtime dependencies of the dependent
-                tasks as well.
-                If that is the case, you need to reference the task name
-                itself in the task list:
+                BitBake allows a task to recursively depend on itself by
+                referencing itself in the task list:
                 <literallayout class='monospaced'>
      do_a[recrdeptask] = "do_a do_b"
                 </literallayout>
+                In the same way as before, this means that the <filename>do_a</filename>
+                and <filename>do_b</filename> tasks of the current recipe and all
+                recipes reachable (by way of dependencies) from the recipe
+                must run before the <filename>do_a</filename> task can run. In this
+                case BitBake will ignore the current recipe's <filename>do_a</filename>
+                task circular dependency on itself.
             </para>
         </section>
 

Re: [bitbake-devel] [PATCH] doc: More explanation to tasks that recursively depend on themselves

[Richard Purdie]

On Thu, 2020-05-28 at 08:41 +0200, Jacob Kroon wrote:
> Signed-off-by: Jacob Kroon <jacob.kroon@gmail.com>
> ---
>  .../bitbake-user-manual-metadata.xml               | 14 ++++++++------
>  1 file changed, 8 insertions(+), 6 deletions(-)
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
> index 95a8b95b..069a0ec8 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
> @@ -2565,15 +2565,17 @@
>              </para>
>  
>              <para>
> -                You might want to not only have BitBake look for
> -                dependencies of those tasks, but also have BitBake look
> -                for build-time and runtime dependencies of the dependent
> -                tasks as well.
> -                If that is the case, you need to reference the task name
> -                itself in the task list:
> +                BitBake allows a task to recursively depend on itself by
> +                referencing itself in the task list:
>                  <literallayout class='monospaced'>
>       do_a[recrdeptask] = "do_a do_b"
>                  </literallayout>
> +                In the same way as before, this means that the <filename>do_a</filename>
> +                and <filename>do_b</filename> tasks of the current recipe and all
> +                recipes reachable (by way of dependencies) from the recipe
> +                must run before the <filename>do_a</filename> task can run. In this
> +                case BitBake will ignore the current recipe's <filename>do_a</filename>
> +                task circular dependency on itself.
>              </para>
>          </section>

I'm not sure I 100% agree with the change. I think the original first
paragraph is clearer but it is good to add something about breaking the
circular dependency where necessary.

Cheers,

Richard

Re: [bitbake-devel] [PATCH] doc: More explanation to tasks that recursively depend on themselves

[Jacob Kroon]

On 5/28/20 3:46 PM, Richard Purdie wrote:
> On Thu, 2020-05-28 at 08:41 +0200, Jacob Kroon wrote:
>> Signed-off-by: Jacob Kroon <jacob.kroon@gmail.com>
>> ---
>>   .../bitbake-user-manual-metadata.xml               | 14 ++++++++------
>>   1 file changed, 8 insertions(+), 6 deletions(-)
>>
>> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
>> index 95a8b95b..069a0ec8 100644
>> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
>> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
>> @@ -2565,15 +2565,17 @@
>>               </para>
>>   
>>               <para>
>> -                You might want to not only have BitBake look for
>> -                dependencies of those tasks, but also have BitBake look
>> -                for build-time and runtime dependencies of the dependent
>> -                tasks as well.
>> -                If that is the case, you need to reference the task name
>> -                itself in the task list:
>> +                BitBake allows a task to recursively depend on itself by
>> +                referencing itself in the task list:
>>                   <literallayout class='monospaced'>
>>        do_a[recrdeptask] = "do_a do_b"
>>                   </literallayout>
>> +                In the same way as before, this means that the <filename>do_a</filename>
>> +                and <filename>do_b</filename> tasks of the current recipe and all
>> +                recipes reachable (by way of dependencies) from the recipe
>> +                must run before the <filename>do_a</filename> task can run. In this
>> +                case BitBake will ignore the current recipe's <filename>do_a</filename>
>> +                task circular dependency on itself.
>>               </para>
>>           </section>
> 
> I'm not sure I 100% agree with the change. I think the original first
> paragraph is clearer but it is good to add something about breaking the
> circular dependency where necessary.
> 

I think the hard part for me as a non-native english speaker was 
identifying what "those tasks" and "dependent tasks" referred to. And I 
tend to dislike the phrase "look for", since BitBake is *adding* 
dependencies, right ?

Let me do another attempt in a v2.

Jacob

Re: [bitbake-devel] [PATCH] doc: More explanation to tasks that recursively depend on themselves

[Jacob Kroon]

On 5/28/20 3:46 PM, Richard Purdie wrote:
> On Thu, 2020-05-28 at 08:41 +0200, Jacob Kroon wrote:
>> Signed-off-by: Jacob Kroon <jacob.kroon@gmail.com>
>> ---
>>   .../bitbake-user-manual-metadata.xml               | 14 ++++++++------
>>   1 file changed, 8 insertions(+), 6 deletions(-)
>>
>> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
>> index 95a8b95b..069a0ec8 100644
>> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
>> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
>> @@ -2565,15 +2565,17 @@
>>               </para>
>>   
>>               <para>
>> -                You might want to not only have BitBake look for
>> -                dependencies of those tasks, but also have BitBake look
>> -                for build-time and runtime dependencies of the dependent
>> -                tasks as well.
>> -                If that is the case, you need to reference the task name
>> -                itself in the task list:
>> +                BitBake allows a task to recursively depend on itself by
>> +                referencing itself in the task list:
>>                   <literallayout class='monospaced'>
>>        do_a[recrdeptask] = "do_a do_b"
>>                   </literallayout>
>> +                In the same way as before, this means that the <filename>do_a</filename>
>> +                and <filename>do_b</filename> tasks of the current recipe and all
>> +                recipes reachable (by way of dependencies) from the recipe
>> +                must run before the <filename>do_a</filename> task can run. In this
>> +                case BitBake will ignore the current recipe's <filename>do_a</filename>
>> +                task circular dependency on itself.
>>               </para>
>>           </section>
> 
> I'm not sure I 100% agree with the change. I think the original first
> paragraph is clearer but it is good to add something about breaking the
> circular dependency where necessary.
> 

I've read the original text several times, and I must disagree with you. 
I think its easy to misinterpret "dependencies of those tasks" as 
meaning "the tasks that the right-hand-side listed tasks depend on".

I think it would be easier to understand if we just wrote something like

"It is allowed for a task to recursively depend on itself by including 
itself in the list of tasks. In this case BitBake will ignore the 
current recipe's circular task dependency on itself."

What do you think ?

Jacob

Re: [bitbake-devel] [PATCH] doc: More explanation to tasks that recursively depend on themselves

[Richard Purdie]

On Thu, 2020-05-28 at 22:27 +0200, Jacob Kroon wrote:
> On 5/28/20 3:46 PM, Richard Purdie wrote:
> > On Thu, 2020-05-28 at 08:41 +0200, Jacob Kroon wrote:
> > > Signed-off-by: Jacob Kroon <jacob.kroon@gmail.com>
> > > ---
> > >   .../bitbake-user-manual-metadata.xml               | 14 ++++++++------
> > >   1 file changed, 8 insertions(+), 6 deletions(-)
> > > 
> > > diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
> > > index 95a8b95b..069a0ec8 100644
> > > --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
> > > +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
> > > @@ -2565,15 +2565,17 @@
> > >               </para>
> > >   
> > >               <para>
> > > -                You might want to not only have BitBake look for
> > > -                dependencies of those tasks, but also have BitBake look
> > > -                for build-time and runtime dependencies of the dependent
> > > -                tasks as well.
> > > -                If that is the case, you need to reference the task name
> > > -                itself in the task list:
> > > +                BitBake allows a task to recursively depend on itself by
> > > +                referencing itself in the task list:
> > >                   <literallayout class='monospaced'>
> > >        do_a[recrdeptask] = "do_a do_b"
> > >                   </literallayout>
> > > +                In the same way as before, this means that the <filename>do_a</filename>
> > > +                and <filename>do_b</filename> tasks of the current recipe and all
> > > +                recipes reachable (by way of dependencies) from the recipe
> > > +                must run before the <filename>do_a</filename> task can run. In this
> > > +                case BitBake will ignore the current recipe's <filename>do_a</filename>
> > > +                task circular dependency on itself.
> > >               </para>
> > >           </section>
> > 
> > I'm not sure I 100% agree with the change. I think the original first
> > paragraph is clearer but it is good to add something about breaking the
> > circular dependency where necessary.
> > 
> 
> I've read the original text several times, and I must disagree with you. 
> I think its easy to misinterpret "dependencies of those tasks" as 
> meaning "the tasks that the right-hand-side listed tasks depend on".
> 
> I think it would be easier to understand if we just wrote something like
> 
> "It is allowed for a task to recursively depend on itself by including 
> itself in the list of tasks. In this case BitBake will ignore the 
> current recipe's circular task dependency on itself."
> 
> What do you think ?

After I went and looked at this in the context of the manual it does
read differently to how I was thinking it read. Sorry, this patch
doesn't give the context needed in this case and I was missing that. I
think you're right.

I'll take the patch, sorry for the confusion.

Cheers,

Richard