[yocto] building a hierarchical poky variable glossary, noting what's missing

[Robert P. J. Day]

  g'day, eh? for my own benefit (that is, for the sake of my upcoming
yocto project courses), i'm starting a topic-based poky variable
glossary, just so i can quickly display all of the variables related
to a particular topic.

  i know there's *some* of that in the ref manual here:

 http://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html#ref-varlocality

but i'm interested in a much more complete list and, more importantly,
i want to add chunks of code or explanations where i think it's
useful. i started one of those a while back, but i'm updating it now
and it's here (ignore everything below "----- OLD CONTENT, TO BE
DELETED -----"):

 http://www.crashcourse.ca/wiki/index.php/Poky_Variable_Glossary

and here are a couple features i'm adding that might be of interest to
other doc writers (like scott rifenbark).

  first, as i add more sections and variables, each variable will be
represented by a link to the (in-progress) ref manual entry, just so i
can take advantage of what already exists, so that's no big deal.

  next, in some cases, it's informative to grab some code or output
from grep to accompany the variable reference, such as what i do here
for the PARALLEL_MAKE* variables, just to show how they're being
used:

http://www.crashcourse.ca/wiki/index.php/Poky_Variable_Glossary#General_build_variables

this makes it really easy during class to show what some variables are
doing, and how to use them.

  finally, i can also note which variables aren't currently documented
in either the ref manual or in the meta/conf/documentation.conf file,
since that takes little extra time.

  here's an example documenting the variables that affect the final
size of the rootfs image:

http://www.crashcourse.ca/wiki/index.php/Poky_Variable_Glossary#Final_rootfs.2Fimage_size

first, as you can see, in some cases, it makes sense to reproduce the
code that uses all those variables so students see how they hang
together, after which i list the variables, and there are two
variations i'm using to show missing documentation.

  if there's no hyperlink (as with IMAGE_ROOTFS_MAXSIZE), that means
there is no entry for that variable in the poky reference manual, so
someone is welcome to add that.

  also, the string "{!doc}" means there's no entry for that variable
in the "documentation.conf" file so, once again, someone is welcome to
do something about that if they want.

  finally, in some cases, it's not clear whether a variable should be
documented anywhere if it's obvious it's being used only locally in a
recipe or class and is not meant to be manipulated by the developer.
here's an example:

 http://www.crashcourse.ca/wiki/index.php/Poky_Variable_Glossary#U-Boot

note in u-boot.inc the variable SPL_BINARY, then SPL_IMAGE and
SPL_SYMLINK which are calculated based on it. so which of these (if
any) deserve documentation? for now, i'm going with SPL_BINARY since
it's meant to be used by the developer (i even show show where), but
i'm leaving out the other two. it's all a judgment call.

  clearly, this is a long-term project but i'll add more sections on a
regular basis and try to keep things up to date. if there's a better
way to do this, i'm open to suggestions.

rday

-- 

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

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