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 ======================================================================== -- _______________________________________________ yocto mailing list yocto@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto