Many of the variables we have in our variable reference are actually understood by BitBake itself; we should copy these definitions into the BitBake manual (and scrub them for any mention of OE-specific functionality). Candidates from our documentation: BB_DANGLINGAPPENDS_WARNONLY BB_DISKMON_DIRS BB_DISKMON_WARNINTERVAL BB_GENERATE_MIRROR_TARBALLS BB_NUMBER_THREADS BBCLASSEXTEND BBFILE_COLLECTIONS BBFILE_PATTERN BBFILE_PRIORITY BBFILES BBINCLUDELOGS BBLAYERS BBMASK BBPATH BBSERVER DEPENDS DL_DIR EXCLUDE_FROM_WORLD INHERIT LAYERDEPENDS LAYERDIR LAYERVERSION MIRRORS OVERRIDES PACKAGES_DYNAMIC PN PV PF PREFERRED_PROVIDER PREFERRED_VERSION PREMIRRORS PROVIDES RDEPENDS RRECOMMENDS RPROVIDES SRC_URI SRCDATE SRCREV STAMP T TOPDIR Some undocumented ones (some of these would be appropriate solely for the BitBake manual as opposes to adding to both that and the YP reference): ASSUME_PROVIDED BB_CURRENTTASK BB_FETCH_PREMIRRORONLY BB_FILENAME BB_HASHBASE_WHITELIST BB_HASHCHECK_FUNCTION BB_HASHCONFIG_WHITELIST BB_INVALIDCONF BB_LOGFMT BB_NICE_LEVEL BB_NO_NETWORK BB_NUMBER_PARSE_THREADS BB_RUNFMT BB_RUNTASK BB_SCHEDULER BB_SCHEDULERS BB_SETSCENE_DEPVALID BB_SETSCENE_VERIFY_FUNCTION BB_SIGNATURE_EXCLUDE_FLAGS BB_SIGNATURE_HANDLER BB_SRCREV_POLICY BB_STAMP_POLICY BB_STAMP_WHITELIST BB_STRICT_CHECKSUM BB_TASK_NICE_LEVEL BB_VERBOSE_LOGS BB_WORKERCONTEXT BUILDNAME CACHE FAKEROOT FAKEROOTDIRS FAKEROOTENV FETCHCMD FILE FILESDIR FILESPATH MULTI_PROVIDER_WHITELIST PERSISTENT_DIR PREFERRED_PROVIDERS SRCREV_FORMAT STAMPCLEAN
A quick braindump of descriptions for some of these: ASSUME_PROVIDED - Contains a list of recipe names (PN values) which bitbake doesn't attempt to build butinstead assumes are already present. In particular is often used for some of the native tools like git-native so the git binary from the host is used instead of building git-native. BB_CURRENTTASK - When a task is being run, this variable will contain the name of the currently running task (without the do_ prefix). BB_FETCH_PREMIRRORONLY - When set to "1", bitbake's fetcher module will only search PREMIRRORS for files, not the main SRC_URI url or MIRRORS. BB_FILENAME - When a task is being run, this variable will contain the filename of the recipe that the task belongs to. BB_NICE_LEVEL - Allows bitbake to run run at a specific priority(nice) level. System permissions usually mean that bitbake can reduce its priority but not raise it again. Also see BB_TASK_NICE_LEVEL BB_HASHCONFIG_WHITELIST - One of the ways BitBake determines whether to reparse the main metadata is by using a checksum of the variables in the datastore of the base configuration data. This list is a list of variables which are excluded from that checksum, for example DATE and TIME are usually excluded since if they weren't the cache would never be used. BB_TASK_NICE_LEVEL - Allows specific tasks to change their priority(nice) level. This can be used in combination with task overrides to raise/lower priorities of specific tasks. On the yocto project autobuilder, qemu emulation in images is given a higher priority compared to build tasks using this technique to ensure the images don't suffer timeouts on loaded systems. BB_NO_NETWORK - Disabled network access in the Bitbake Fetcher modules. Any command which would attempt to access the network will instead become an error. This is useful for testing source mirrors, running builds when not connected to the internet and when operating in certain kinds of firewall environments. BB_NUMBER_PARSE_THREADS - Sets the number of threads to use when parsing. By default this is the number of cores on the system. EXPORT_FUNCTIONS - This is useful in a class context to allow automatic mapping between functions. The best way to understand the behaviour is by example. A class "someclass" might define a funcition called "someclass_somefunction" and then "EXPORT_FUNCTIONS somefunction". This would mean that if somefunction doesn't exist, a dummy function somefunction would be inserted which simply called someclass_somefunction. This means a class can define functions that the user can override/customise but the core class functions are still available to call into. This is often used for tasks like do_configure and kernel_do_configure in kernel.bbclass in the OE metadata. STAMPCLEAN - A version of STAMP which contains wildcards to match the range of files a clean operation should remove. This is used by Bitbake when creating a new stamp to remove any other stamps it should be removing.
EXPORT_FUNCTIONS was missing from the list but I added a description!
I definitely agree we want to document EXPORT_FUNCTIONS, but for Scott's benefit, I'm not sure it belongs in the BitBake variable glossary since it's really a command. Perhaps a section on bbclasses would be a better home for it?
Created attachment 1739 [details] Initial raw version of variable reference I'm attaching a copy of the ref-variables.xml from the Yocto Project reference manual with all of the irrelevant variables removed and most of the OpenEmbedded related references edited out. There is still some editing to be done - some notes I've made: * BBFILES and BBINCLUDELOGS need work * BBCLASSEXTEND and BBSERVER need rewriting for how BitBake deals with them * Most of PACKAGES_DYNAMIC and RRECOMMENDS are invalid because the logic isn't in BitBake * References to the "build directory" probably need to go * I'm unsure as to how to deal with the concept of a "package" within BitBake, e.g. when we talk about runtime dependencies. * There are a number of variables such as SUMMARY, DESCRIPTION etc. where BitBake's only concern with them is to store them in the cache. I wonder if we're going to be adding a lot of comments like "there is no special functionality associated with this variable in BitBake itself, but an example implementation in OpenEmbedded is..."
Created attachment 1740 [details] Initial raw version of variable reference Argh, Bugzilla chewed up my attachement, setting a different type this time.
The initial file Paul provided me is in the poky-contrib/srifenbark/wmat3 version of the manual. I have scrubbed out linked references to "Build Directory" and removed several straggling cross-references back into the YP set since we decided that the BB manual would not reference any material there. I need information to satisfy the remainder of Comment 4 listed out by Paul. I will fold in Richard's descriptions for some of the variables as listed in Comment 1. Scott
Regarding EXPORT FUNCTIONS - Paul indicated this is a command and not a variable. I am not sure where we want this yet but I was trying to re-write the description and am not sure I got it right. Here is what I have: ---------------------------------------------- EXPORT_FUNCTIONS Allows for automatic mapping between functions within the context of a class. To help understand how this variable works, consider a class named "someclass" that defines a function called "someclass_somefunction". The function is then exported using the following command: EXPORT_FUNCTIONS somefunction This would mean that if "somefunction" did not exist, a dummy function named "somefunction" would be inserted and it would simply call "someclass_somefunction". If follows then that a class can define functions that the user can override or customize while leaving the the core class available to to call. Exporting functions in this manner is often used for tasks such as do_configure and kernel_do_configure in kernel.bbclass in the OE metadata. ---------------------------------------------- I don't follow the part that says "This would mean that if 'somefunction' did not exist...." In the example, it states that 'somefunction' is defined in 'someclass'. So the whole last paragraph is sort of lost on me.
I have added 10 of the variables from the list of undocumented variables. It would be good to check these out for accuracy. To find them, you can view a reviewable version of the BitBake manual at http://www.yoctoproject.org/docs/temp/user-manual/user-manual.html. You can go directly to a variable using the "#var-<NAME>" form (e.g. http://www.yoctoproject.org/docs/temp/user-manual/user-manual.html#var-ASSUME_PROVIDED). I know this temporary area is under yocto and I hope that is okay. It was a convenient way to make the manual available for viewing. If it a problem, let me know and we can figure something else out. Here is the list now: ASSUME_PROVIDED -------------------------> documented BB_CURRENTTASK --------------------------> documented BB_FETCH_PREMIRRORONLY ------------------> documented BB_FILENAME -----------------------------> documented BB_HASHBASE_WHITELIST BB_HASHCHECK_FUNCTION BB_HASHCONFIG_WHITELIST -----------------> documented BB_INVALIDCONF BB_LOGFMT BB_NICE_LEVEL ---------------------------> documented BB_NO_NETWORK ---------------------------> documented BB_NUMBER_PARSE_THREADS -----------------> documented BB_RUNFMT BB_RUNTASK BB_SCHEDULER BB_SCHEDULERS BB_SETSCENE_DEPVALID BB_SETSCENE_VERIFY_FUNCTION BB_SIGNATURE_EXCLUDE_FLAGS BB_SIGNATURE_HANDLER BB_SRCREV_POLICY BB_STAMP_POLICY BB_STAMP_WHITELIST BB_STRICT_CHECKSUM BB_TASK_NICE_LEVEL ----------------------> documented BB_VERBOSE_LOGS BB_WORKERCONTEXT BUILDNAME CACHE FAKEROOT FAKEROOTDIRS FAKEROOTENV FETCHCMD FILE FILESDIR FILESPATH MULTI_PROVIDER_WHITELIST PERSISTENT_DIR PREFERRED_PROVIDERS SRCREV_FORMAT STAMPCLEAN ------------------------------> documented
Here is the list now - all targeted variables are in. They have not all be reviewed. I have implemented the review comments received to date. There is one outstanding review email out there. The variables can be viewed at http://www.yoctoproject.org/docs/temp/user-manual/user-manual.html in the glossary. Scott ASSUME_PROVIDED -------------------------> documented BB_CURRENTTASK --------------------------> documented BB_FETCH_PREMIRRORONLY ------------------> documented BB_FILENAME -----------------------------> documented BB_HASHBASE_WHITELIST--------------------> documented BB_HASHCHECK_FUNCTION -------------------> documented BB_HASHCONFIG_WHITELIST -----------------> documented BB_INVALIDCONF --------------------------> documented BB_LOGFMT -------------------------------> documented BB_NICE_LEVEL ---------------------------> documented BB_NO_NETWORK ---------------------------> documented BB_NUMBER_PARSE_THREADS -----------------> documented BB_RUNFMT -------------------------------> documented BB_RUNTASK ------------------------------> documented BB_SCHEDULER ----------------------------> documented BB_SCHEDULERS ---------------------------> documented BB_SETSCENE_DEPVALID --------------------> documented BB_SETSCENE_VERIFY_FUNCTION -------------> documented BB_SIGNATURE_EXCLUDE_FLAGS --------------> documented BB_SIGNATURE_HANDLER --------------------> documented BB_SRCREV_POLICY ------------------------> documented BB_STAMP_POLICY -------------------------> documented BB_STAMP_WHITELIST ----------------------> documented BB_STRICT_CHECKSUM ----------------------> documented BB_TASK_NICE_LEVEL ----------------------> documented BB_VERBOSE_LOGS -------------------------> documented BB_WORKERCONTEXT ------------------------> documented BUILDNAME -------------------------------> documented CACHE -----------------------------------> documented FAKEROOT --------------------------------> documented FAKEROOTDIRS ----------------------------> documented FAKEROOTENV -----------------------------> documented FETCHCMD --------------------------------> documented FILE ------------------------------------> documented FILESDIR --------------------------------> documented FILESPATH -------------------------------> documented MULTI_PROVIDER_WHITELIST ----------------> documented PERSISTENT_DIR --------------------------> documented PREFERRED_PROVIDERS ---------------------> documented SRCREV_FORMAT ---------------------------> documented STAMPCLEAN ------------------------------> documented
This bug is nearly complete. It has been reviewed by Paul. I will wait longer to see if I can get a review out of Richard for the glossary. Once that happens, we will call it done. Scott
EXPORT_FUNCTIONS is not in the manual and is a key variable we do need to add
Is EXPORT_FUNCTIONS really a variable though? At least syntax-wise it's not used like one...
(No argument against documenting it though - we definitely need to)
Hi, We need the mapping section reviewed. Richard approved it but Paul had some issues. So, leaving this open for a bit longer. http://www.yoctoproject.org/docs/1.6/user-manual/user-manual.html#automatically-mapping-functions-within-the-context-of-a-class. Scott
Hi, I have implemented the feedback here. See http://www.yoctoproject.org/docs/1.6/bitbake-user-manual/bitbake-user-manual.html#flexible-inheritance-for-class-functions. Once this is approved, I will close the bug and mark the docs as "Done." Thanks Scott
Hi, This bug is complete for 1.6. Possibly open a new bug to deal with syncing the BB variables in the BB manual with the YP reference manual per Paul's suggestion. Scott