[yocto] pedantic observations on bitbake user manual (ch 1)

[Robert P. J. Day]

  since bitbake is primarily under the YP banner these days, i'm just
going to throw out a number of observations on the current user
manual, and others can decide what to do about any of them. so without
further ado, chapter 1 cuz i'll break this into bite-size pieces ...

1.3.3 Classes

  "Class files, which are denoted by the .bbclass extension, contain
information that is useful to share between metadata files. The
BitBake source tree currently comes with one class metadata file
called base.bbclass. You can find this file in the classes directory.
The base.bbclass class files is special since it is always included
automatically for all recipes and classes. This class contains
definitions for standard basic tasks such as fetching, ..."

  this is slightly confusing since, if you check out bitbake directly
from its repo, then, yes, it has a single class file (base.bbclass),
but that file has very little functionality -- certainly nothing to do
with fetching, etc. OTOH, if you check out the poky repo, then, yes,
you get a base.bbclass file (and many other class files) that is far
more complete and defines basic fetching and so on.

  that subsection seems to conflate what you get if you check out
bitbake directly, versus what you get if you more typically check out
poky. and i think that's confusing since a later section talks about
how to obtain bitbake, and its first suggestion is "git clone." so i
think section 1.3.3 has the potential to confuse some readers.

1.4 Obtaining BitBake

  "Cloning BitBake: Using Git to clone the BitBake source code
repository is the recommended method for obtaining BitBake..."
                  ^^^^^^^^^^^

  it is? i would think that the recommended method is to check out
poky, which guarantees that the version of bitbake you get has been
Q/A tested against the other layers that come with it. i would think
that cloning bitbake from its repo is more for testers than regular
developers.

1.5.1 Usage and Syntax

  - needs to update output of "bitbake -h", there's a bit more being
printed these days.

1.5.2.1 Executing a Task Against a Single Recipe

  - seems contradictory, first says, "BitBake obeys inter-task
dependencies when doing so, then says, "The "-b" option explicitly
does not handle recipe dependencies."

  that will *definitely* confuse some readers.

1.5.2.2 Executing Tasks Against a Set of Recipe Files

  "This next example "PROVIDES" the package name and also uses the
"-c" option to tell BitBake to just execute the do_clean task:"

  AIUI, "-c" will also require outdated dependent tasks to be run as
well, no?  the way the above is worded doesn't read that way.

  that's it for chapter 1.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================