| Summary: | Better document support for variables and updaet OE User Manual | ||
|---|---|---|---|
| Product: | [Documentation] Development Manual | Reporter: | Robert Yang <liezhi.yang> |
| Component: | development | Assignee: | Scott Rifenbark <srifenbark> |
| Status: | RESOLVED FIXED | QA Contact: | |
| Severity: | enhancement | ||
| Priority: | Medium | CC: | bluelightning, jessica.zhang, liezhi.yang, mark.hatle, richard.purdie, sgw |
| Version: | 1.5 | ||
| Target Milestone: | Future | ||
| Hardware: | x86 | ||
| OS: | Multiple | ||
| Whiteboard: | 22 July 2014: reset doc flag | ||
| OS type for building Yocto: | --- | Type of Regression: | --- |
| Verified: | Documentation change: | Done (doc changes complete) | |
|
Description
Robert Yang
2013-04-22 06:45:15 UTC
I am unclear as to whether this bug applies to me or not. The link referenced in the bug resolves to an OpenEmbedded User's Manual. This manual is different than the BitBake User's Manual that ships as part of the YP release. Can the bug team look this bug over and categorize it or remove it appropriately? Thanks, Scott These are variables that are used by OpenEmbedded-core (and thus the YP) in order to control the build process, image generation, and deployment aspects of the system. Someone needs to go through and document all of the various control infrastructure that is in place so people stop inventing new ways of doing the same thing, as well as help eliminate questions about some of the more esoteric features. Hey Mark, Do we have a definitive list of the various control structure? By control structure, do you mean individual variables? Or, are you talking about some programming constructs or something else. If we have a set of variables then I can document them once I have some information for each of the variables. We do have a bug out right now that is sort of a running open bug that is against variable documentation. I know we have many undocumented variables. The bug is 2085 (https://bugzilla.yoctoproject.org/show_bug.cgi?id=2085). Scott This bug is related to 2085, but is a bit different. There are a few key places that variables and their usage should be described. Robert suggested three key areas (and a couple more) that should be expanded with more variable information when the user integrating a recipe has to work around, or otherwise change the default behavior of the system. There are a ton of variables that can dictate system behavior, but people don't know which items are available to them. Moving target to "future". There's a lot of only vaguely defined ideas in this bug, so it's hard to tell what's genuinely missing. The reference to the OE user manual is a little bit misleading - that manual is not one we maintain (and I doubt it will ever be updated by the OE project in future). If we're using it as a guide as to what it covers (or suggests covering) that we don't currently cover, that is reasonable though. It's worth noting that Scott has just finished adding a section on how to write a new recipe, with some help from me: http://www.yoctoproject.org/docs/1.6/dev-manual/dev-manual.html#new-recipe-writing-a-new-recipe We've also recently expanded the documentation on all of our classes to cover those that were previously undocumented, adding a large number of previously undocumented variables to the glossary in the process: http://www.yoctoproject.org/docs/1.6/ref-manual/ref-manual.html#ref-classes http://www.yoctoproject.org/docs/1.6/ref-manual/ref-manual.html#ref-variables-glos With reference to this latest documentation, what exactly is still missing? From your list, "declaring volatiles" is probably still not covered, but the rest should be covered in some form. (FWIW, any feedback on the new documentation is welcome.) No comments so I'm going to mark this resolved as discussed by Paul with the work we've done already. If there are any other specific issues this can be reopened or specific issues can be opened. Thank you Richard. As such, I am setting the documentation flag to "Done." Scott |