[v2,2/2] bitbake-user-manual: update Hello World example

Fix broken link "Obtaining bitbake".
Update documentation for the bitbake hello world example, the output was
outdated.
Fix LAYERSERIES_COMPAT warning by adding dunfell as default compatible release.
Add proper formating for base.bbclass command.

Reviewed-by: Ever ATILANO <ever.atilano@smile.fr>
Reviewed-by: Yoann CONGAL <yoann.congal@smile.fr>
Signed-off-by: Fawzi KHABER <fawzi.khaber@smile.fr>
---
 .../bitbake-user-manual-hello.rst             | 53 +++++++------------
 1 file changed, 18 insertions(+), 35 deletions(-)

Hi Fawzi

Many thanks for this patch too. Much appreciated!

Good catch finding this outdated part of the BitBake manual.

See my comments below...

On 27.02.23 at 14:51, Fawzi KHABER wrote:
> Fix broken link "Obtaining bitbake".
> Update documentation for the bitbake hello world example, the output was
> outdated.
> Fix LAYERSERIES_COMPAT warning by adding dunfell as default compatible release.
> Add proper formating for base.bbclass command.
>
> Reviewed-by: Ever ATILANO <ever.atilano@smile.fr>
> Reviewed-by: Yoann CONGAL <yoann.congal@smile.fr>
> Signed-off-by: Fawzi KHABER <fawzi.khaber@smile.fr>
> ---
>   .../bitbake-user-manual-hello.rst             | 53 +++++++------------
>   1 file changed, 18 insertions(+), 35 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-hello.rst b/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
> index 722dc5a2..0cf81ce4 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
> @@ -18,7 +18,7 @@ it.
>   Obtaining BitBake
>   =================
>   
> -See the :ref:`bitbake-user-manual/bitbake-user-manual-hello:obtaining bitbake` section for
> +See the :ref:`bitbake-user-manual/bitbake-user-manual-intro:obtaining bitbake` section for
>   information on how to obtain BitBake. Once you have the source code on
>   your machine, the BitBake directory appears as follows::
>   
> @@ -52,7 +52,7 @@ directory to where your local BitBake files are and run the following
>   command::
>   
>     $ ./bin/bitbake --version
> -  BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0
> +  BitBake Build Tool Core version 2.3.1
>   
>   The console output tells you what version
>   you are running.
> @@ -130,23 +130,11 @@ Following is the complete "Hello World" example.
>       directory. Run the ``bitbake`` command and see what it does::
>   
>          $ bitbake
> -       The BBPATH variable is not set and bitbake did not
> -       find a conf/bblayers.conf file in the expected location.
> +       ERROR: The BBPATH variable is not set and bitbake did not find a conf/bblayers.conf file in the expected location.
>          Maybe you accidentally invoked bitbake from the wrong directory?
> -       DEBUG: Removed the following variables from the environment:
> -       GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
> -       GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
> -       XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
> -       MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
> -       GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
> -       XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
> -       _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,
> -       UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS
> -
> -    The majority of this output is specific to environment variables that
> -    are not directly relevant to BitBake. However, the very first
> -    message regarding the :term:`BBPATH` variable and the
> -    ``conf/bblayers.conf`` file is relevant.
> +
> +
> +


Why are you adding 3 empty lines here?

>   
>       When you run BitBake, it begins looking for metadata files. The
>       :term:`BBPATH` variable is what tells BitBake where
> @@ -254,17 +242,6 @@ Following is the complete "Hello World" example.


Wait, before this, it seems you forgot to update the output of the 
"bitbake" command right after setting the BBPATH variable. Or maybe you 
didn't work with the "master" branch. Here's what I get when I use 
bitbake from the current Poky master branch:

$bitbake
Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake 
--help' for usage information.

Unless there's something in my environment that makes BitBake behave 
differently, but that's worth double checking anyway.

>       exists, you can run the ``bitbake`` command again::
>   
>          $ bitbake
> -       ERROR: Traceback (most recent call last):
> -         File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
> -           return func(fn, *args)
> -         File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
> -           bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
> -         File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
> -           include(fn, file, lineno, d, "inherit")
> -         File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
> -           raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
> -       ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
> -
>          ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
>   
>       In the sample output,


Same here. At this stage on Poky master, I get:
$bitbake
Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake 
--help' for usage information.

> @@ -284,7 +261,10 @@ Following is the complete "Hello World" example.
>         $ mkdir classes
>   
>       Move to the ``classes`` directory and then create the
> -    ``base.bbclass`` file by inserting this single line: addtask build
> +    ``base.bbclass`` file by inserting this single line::
> +
> +      addtask build
> +
>       The minimal task that BitBake runs is the ``do_build`` task. This is
>       all the example needs in order to build the project. Of course, the
>       ``base.bbclass`` can have much more depending on which build


Good catch. This is ugly in the current docs.

> @@ -328,10 +308,11 @@ Following is the complete "Hello World" example.
>         BBFILES += "${LAYERDIR}/*.bb"
>         BBFILE_COLLECTIONS += "mylayer"
>         BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/"
> +      LAYERSERIES_COMPAT_mylayer = "dunfell"

You may mention that "dunfell" is just an example, and should be adapted 
to the OpenEmbedded-Core version(s) that your layer supports. By the 
way, "kirkstone" should be a better choice as it should last longer than 
"dunfell".

By the way, wishing we had a DISTRO_NAME_NO_CAP macro like in the YP 
manual, but that's will be a separate topic.

>   
>       For information on these variables, click on :term:`BBFILES`,
> -    :term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS` or :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>`
> -    to go to the definitions in the glossary.
> +    :term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS`, :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>`
> +    or :term:`LAYERSERIES_COMPAT` to go to the definitions in the glossary.
>   
>       You need to create the recipe file next. Inside your layer at the
>       top-level, use an editor and create a recipe file named
> @@ -389,12 +370,14 @@ Following is the complete "Hello World" example.


Before this too, I don't have the same output when I run "bitbake 
printhello" for the first time:

$ bitbake printhello
ERROR: Nothing PROVIDES 'printhello'

>       target::
>   
>          $ bitbake printhello
> +       Loading cache: 100% |
> +       Loaded 0 entries from dependency cache.
>          Parsing recipes: 100% |##################################################################################|
> -       Time: 00:00:00
>          Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
>          NOTE: Resolving any missing task queue dependencies
> -       NOTE: Preparing RunQueue
> -       NOTE: Executing RunQueue Tasks
> +       Initialising tasks: 100% |###############################################################################|
> +       NOTE: No setscene tasks
> +       NOTE: Executing Tasks
>          ********************
>          *                  *
>          *  Hello, World!   *


Weird, I believe I followed the instructions correctly, but I still have:
ERROR: Nothing PROVIDES 'printhello'

This will probably help to know which version of Bitbake you're using. 
For documentation in "master", you should be using "master" too.

Sorry for all this changes, but it's great to fix an outdated version. 
If you lack time, I'll be happy to suggest a V2 that you could review 
then. Let me know...

Thanks again
Michael.

Hi Michael,

On 2/27/23 18:42, Michael Opdenacker wrote:
>>         When you run BitBake, it begins looking for metadata files. The
>>       :term:`BBPATH` variable is what tells BitBake where
>> @@ -254,17 +242,6 @@ Following is the complete "Hello World" example.
> 
> 
> Wait, before this, it seems you forgot to update the output of the "bitbake" command right after setting the BBPATH variable. Or maybe you didn't work with the "master" branch. Here's what I get when I use bitbake from the current Poky master branch:
> 
> $bitbake
> Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
> 
> Unless there's something in my environment that makes BitBake behave differently, but that's worth double checking anyway.

FYI, we already did some back and forth internally on this ^^

Be sure to have the BBPATH envvar unset before starting. Its really easy mixing shells and reusing one that did have a OE env sourced at some point and so an active BBPATH envvar.

Here is a minimal script I used to reproduce the output in the patch.

  $ printenv |grep BBPATH # ensure $BBPATH is not set
  $ git clone git://git.openembedded.org/bitbake # clone latest master bitbake
  $ cd bitbake/
  $ ./bin/bitbake --version
  BitBake Build Tool Core version 2.3.1
  
  $ export PATH=$PWD/bin:$PATH
  $ which bitbake # must point to the above bitbake
  
  $ mkdir ../hello && cd ../hello/
  $ bitbake
  ERROR: The BBPATH variable is not set and bitbake did not find a conf/bblayers.conf file in the expected location.
  Maybe you accidentally invoked bitbake from the wrong directory?

I guess the following differences come from the same reason.

Can you try again with the above script?
>>       exists, you can run the ``bitbake`` command again::
>>            $ bitbake
>> -       ERROR: Traceback (most recent call last):
>> -         File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
>> -           return func(fn, *args)
>> -         File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
>> -           bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
>> -         File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
>> -           include(fn, file, lineno, d, "inherit")
>> -         File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
>> -           raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
>> -       ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
>> -
>>          ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
>>         In the sample output,
> 
> 
> Same here. At this stage on Poky master, I get:
> $bitbake
> Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
> 
>> @@ -284,7 +261,10 @@ Following is the complete "Hello World" example.
>>         $ mkdir classes
>>         Move to the ``classes`` directory and then create the
>> -    ``base.bbclass`` file by inserting this single line: addtask build
>> +    ``base.bbclass`` file by inserting this single line::
>> +
>> +      addtask build
>> +
>>       The minimal task that BitBake runs is the ``do_build`` task. This is
>>       all the example needs in order to build the project. Of course, the
>>       ``base.bbclass`` can have much more depending on which build
> 
> 
> Good catch. This is ugly in the current docs.
> 
>> @@ -328,10 +308,11 @@ Following is the complete "Hello World" example.
>>         BBFILES += "${LAYERDIR}/*.bb"
>>         BBFILE_COLLECTIONS += "mylayer"
>>         BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/"
>> +      LAYERSERIES_COMPAT_mylayer = "dunfell"
> 
> You may mention that "dunfell" is just an example, and should be adapted to the OpenEmbedded-Core version(s) that your layer supports. By the way, "kirkstone" should be a better choice as it should last longer than "dunfell".
> 
> By the way, wishing we had a DISTRO_NAME_NO_CAP macro like in the YP manual, but that's will be a separate topic.
> 
>>         For information on these variables, click on :term:`BBFILES`,
>> -    :term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS` or :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>`
>> -    to go to the definitions in the glossary.
>> +    :term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS`, :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>`
>> +    or :term:`LAYERSERIES_COMPAT` to go to the definitions in the glossary.
>>         You need to create the recipe file next. Inside your layer at the
>>       top-level, use an editor and create a recipe file named
>> @@ -389,12 +370,14 @@ Following is the complete "Hello World" example.
> 
> 
> Before this too, I don't have the same output when I run "bitbake printhello" for the first time:
> 
> $ bitbake printhello
> ERROR: Nothing PROVIDES 'printhello'
> 
>>       target::
>>            $ bitbake printhello
>> +       Loading cache: 100% |
>> +       Loaded 0 entries from dependency cache.
>>          Parsing recipes: 100% |##################################################################################|
>> -       Time: 00:00:00
>>          Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
>>          NOTE: Resolving any missing task queue dependencies
>> -       NOTE: Preparing RunQueue
>> -       NOTE: Executing RunQueue Tasks
>> +       Initialising tasks: 100% |###############################################################################|
>> +       NOTE: No setscene tasks
>> +       NOTE: Executing Tasks
>>          ********************
>>          *                  *
>>          *  Hello, World!   *
> 
> 
> Weird, I believe I followed the instructions correctly, but I still have:
> ERROR: Nothing PROVIDES 'printhello'
> 
> This will probably help to know which version of Bitbake you're using. For documentation in "master", you should be using "master" too.
> 
> Sorry for all this changes, but it's great to fix an outdated version. If you lack time, I'll be happy to suggest a V2 that you could review then. Let me know...
> 
> Thanks again
> Michael.
>

Hi Yoann,

On 27.02.23 at 19:13, Yoann Congal wrote:
> Hi Michael,
>
> On 2/27/23 18:42, Michael Opdenacker wrote:
>>>          When you run BitBake, it begins looking for metadata files. The
>>>        :term:`BBPATH` variable is what tells BitBake where
>>> @@ -254,17 +242,6 @@ Following is the complete "Hello World" example.
>>
>> Wait, before this, it seems you forgot to update the output of the "bitbake" command right after setting the BBPATH variable. Or maybe you didn't work with the "master" branch. Here's what I get when I use bitbake from the current Poky master branch:
>>
>> $bitbake
>> Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
>>
>> Unless there's something in my environment that makes BitBake behave differently, but that's worth double checking anyway.
> FYI, we already did some back and forth internally on this ^^
>
> Be sure to have the BBPATH envvar unset before starting. Its really easy mixing shells and reusing one that did have a OE env sourced at some point and so an active BBPATH envvar.
>
> Here is a minimal script I used to reproduce the output in the patch.
>
>    $ printenv |grep BBPATH # ensure $BBPATH is not set
>    $ git clone git://git.openembedded.org/bitbake # clone latest master bitbake
>    $ cd bitbake/
>    $ ./bin/bitbake --version
>    BitBake Build Tool Core version 2.3.1
>    
>    $ export PATH=$PWD/bin:$PATH
>    $ which bitbake # must point to the above bitbake
>    
>    $ mkdir ../hello && cd ../hello/
>    $ bitbake
>    ERROR: The BBPATH variable is not set and bitbake did not find a conf/bblayers.conf file in the expected location.
>    Maybe you accidentally invoked bitbake from the wrong directory?
>
> I guess the following differences come from the same reason.
>
> Can you try again with the above script?


I've just tested this so far, and I have the same output as you do.

However, when I run "bitbake" again after setting BBPATH (step 4), I get 
an error message that is not mentioned in the patch (which doesn't 
update step 4):

ERROR: Unable to parse 
/home/mike/work/git/git.openembedded.org/bitbake/lib/bb/parse/__init__.py
Traceback (most recent call last):
   File 
"/home/mike/work/git/git.openembedded.org/bitbake/lib/bb/parse/__init__.py", 
line 127, in resolve_file(fn='conf/bitbake.conf', 
d=<bb.data_smart.DataSmart object at 0x7fbe7a5200a0>):
              if not newfn:
     >            raise IOError(errno.ENOENT, "file %s not found in %s" 
% (fn, bbpath))
              fn = newfn
FileNotFoundError: [Errno 2] file conf/bitbake.conf not found in 
/home/mike/tmp/hello

I confirm I'm using the latest bitbake.


>>>        exists, you can run the ``bitbake`` command again::
>>>             $ bitbake
>>> -       ERROR: Traceback (most recent call last):
>>> -         File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
>>> -           return func(fn, *args)
>>> -         File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
>>> -           bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
>>> -         File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
>>> -           include(fn, file, lineno, d, "inherit")
>>> -         File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
>>> -           raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
>>> -       ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
>>> -
>>>           ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
>>>          In the sample output,
>>
>> Same here. At this stage on Poky master, I get:
>> $bitbake
>> Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.


Now, I'm getting something different. Maybe I wasn´t referring to the 
right step (step 6 here). I have the same error but with extra details:

ERROR: Unable to parse 
/home/mike/work/git/git.openembedded.org/bitbake/lib/bb/parse/parse_py/BBHandler.py
Traceback (most recent call last):
   File 
"/home/mike/work/git/git.openembedded.org/bitbake/lib/bb/parse/parse_py/BBHandler.py", 
line 67, in inherit(files=['base'], fn='configuration INHERITs', 
lineno=0, d=<bb.data_smart.DataSmart object at 0x7fac30c200a0>):
              if not os.path.exists(file):
     >            raise ParseError("Could not inherit file %s" % (file), 
fn, lineno)

bb.parse.ParseError: ParseError in configuration INHERITs: Could not 
inherit file classes/base.bbclass

I think at least there should be a "..." line to indicate that there are 
more lines between the bitbake command and the final line. Unless I'm 
the only one getting this.

>>> @@ -284,7 +261,10 @@ Following is the complete "Hello World" example.
>>>          $ mkdir classes
>>>          Move to the ``classes`` directory and then create the
>>> -    ``base.bbclass`` file by inserting this single line: addtask build
>>> +    ``base.bbclass`` file by inserting this single line::
>>> +
>>> +      addtask build
>>> +
>>>        The minimal task that BitBake runs is the ``do_build`` task. This is
>>>        all the example needs in order to build the project. Of course, the
>>>        ``base.bbclass`` can have much more depending on which build
>>
>> Good catch. This is ugly in the current docs.
>>
>>> @@ -328,10 +308,11 @@ Following is the complete "Hello World" example.
>>>          BBFILES += "${LAYERDIR}/*.bb"
>>>          BBFILE_COLLECTIONS += "mylayer"
>>>          BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/"
>>> +      LAYERSERIES_COMPAT_mylayer = "dunfell"
>> You may mention that "dunfell" is just an example, and should be adapted to the OpenEmbedded-Core version(s) that your layer supports. By the way, "kirkstone" should be a better choice as it should last longer than "dunfell".
>>
>> By the way, wishing we had a DISTRO_NAME_NO_CAP macro like in the YP manual, but that's will be a separate topic.


This should still be addressed.

Fawzi, could you send an update addressing at least the above remarks?

Then, I'll be happy to test your new instructions again.

Thanks again,

Cheers
Michael.

Hi Michael,

Thank you for the review, i will update the output and send the patch series V3.

Best regards,
Fawzi

Hello Michael,

As i was preparing my patch v3, i found an issue with the LAYERSERIES_COMPAT Variable. bitbake and OE seems to be maintained separately but they are linked.
so for this hello world example should not include an OE release in bblayers.conf but :
if LAYERSERIES_COMPAT is not set it produces a warning, and if a default value is set but OE is not included, the build fails with
No core layer found to work with layer '%s'. Missing entry in bblayers.conf
this change was introduced in 5815a7258ebb8a989e0c6f5798853559d9413f02 to fix https://bugzilla.yoctoproject.org/show_bug.cgi?id=14340
I would suggest, keeping the warning for now.

Best regards,
Fawzi.