Skip to contentSkip to conversation

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

DISCUSSION Robert P. J. Day 2 participants 3 messages Aug 26, 2014 – Aug 27, 2014

lore
Share & tools
lore
#0 lore raw

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

Signature · 7 lines
========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================
#1 lore raw

Robert,

I can see your link being referenced from the YP ref-manual to augment variable descriptions and explanations. Also, your compilation could act as another source of information similar to the list of "other information" items that currently are shown at the front of the dev-manual.

Scott

Quoted 102 lines

-----Original Message-----
From: [email protected] [mailto:yocto- [email protected]] On Behalf Of Robert P. J. Day
Sent: Tuesday, August 26, 2014 4:11 AM
To: Yocto discussion list
Subject: [yocto] building a hierarchical poky variable glossary, noting what's missing

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#Genera
l_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_r
ootfs.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

===========================================================
=============

--
_______________________________________________
yocto mailing list
[email protected]
https://lists.yoctoproject.org/listinfo/yocto

#2 lore raw
Quoted 7 lines · Scott M

Robert,

I can see your link being referenced from the YP ref-manual to augment variable descriptions and explanations. Also, your compilation could act as another source of information similar to the list of "other information" items that currently are shown at the front of the dev-manual.

this whole thing will come in fits and spurts, and may even be
redesigned completely if i think of a better way but, for the time being, if you're bored :-), you can always peruse it from time to time and note the variables that aren't included either in documentation.conf or the ref manual and do something about them:

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

of course, it's impossible to document *every* variable but in some cases, it's obvious that some variables deserve documentation.

rday

Signature · 7 lines
========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

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