From e3b7e8430cb207756b59b32128aa3cef6a626fa1 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 10 Jan 2017 15:37:16 -0800 Subject: bitbake-user-manual: Updated Event descriptions Fixes [YOCTO #10886] Added text descriptions for many of the events in the list of the "Events" section. Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../bitbake-user-manual-metadata.xml | 188 ++++++++++++++------- 1 file changed, 127 insertions(+), 61 deletions(-) diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml index badc7c0e4..d1b93bc07 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml @@ -505,14 +505,14 @@ Unseting variables - It is possible to completely remove a variable or a variable flag + It is possible to completely remove a variable or a variable flag from BitBake's internal data dictionary by using the "unset" keyword. Here is an example: unset DATE unset do_fetch[noexec] - These two statements remove the DATE and the + These two statements remove the DATE and the do_fetch[noexec] flag. @@ -1984,128 +1984,194 @@ Events - BitBake allows installation of event handlers within - recipe and class files. - Events are triggered at certain points during operation, - such as the beginning of an operation against a given recipe - (*.bb file), the start of a given task, - task failure, task success, and so forth. + BitBake allows installation of event handlers within recipe + and class files. + Events are triggered at certain points during operation, such + as the beginning of operation against a given recipe + (i.e. *.bb), the start of a given task, + a task failure, a task success, and so forth. The intent is to make it easy to do things like email - notification on build failure. + notification on build failures. - Following is an example event handler that - prints the name of the event and the content of - the FILE variable: + Following is an example event handler that prints the name + of the event and the content of the + FILE variable: addhandler myclass_eventhandler python myclass_eventhandler() { from bb.event import getName - from bb import data print("The name of the Event is %s" % getName(e)) - print("The file we run for is %s" % data.getVar('FILE', e.data, True)) + print("The file we run for is %s" % d.getVar('FILE')) } + myclass_eventhandler[eventmask] = "bb.event.BuildStarted bb.event.BuildCompleted" - This event handler gets called every time an event is - triggered. - A global variable "e" is defined and - "e.data" contains an instance of - "bb.data". - With the getName(e) method, one can get + In the previous example, an eventmask has been set so that + the handler only sees the "BuildStarted" and "BuildCompleted" + events. + This event handler gets called every time an event matching + the eventmask is triggered. + A global variable "e" is defined, which represents the current + event. + With the getName(e) method, you can get the name of the triggered event. + The global datastore is available as "d". + In legacy code, you might see "e.data" used to get the datastore". + However, realize that "e.data" is deprecated and you should use + "d" going forward. - Because you probably are only interested in a subset of events, - you would likely use the [eventmask] flag - for your event handler to be sure that only certain events - trigger the handler. - Given the previous example, suppose you only wanted the - bb.build.TaskFailed event to trigger that - event handler. - Use the flag as follows: - - addhandler myclass_eventhandler - myclass_eventhandler[eventmask] = "bb.build.TaskFailed" - python myclass_eventhandler() { - from bb.event import getName - from bb import data - print("The name of the Event is %s" % getName(e)) - print("The file we run for is %s" % data.getVar('FILE', e.data, True)) - } - + The context of the datastore is appropriate to the event + in question. + For example, "BuildStarted" and "BuildCompleted" events run + before any tasks are executed so would be in the global + configuration datastore namespace. + No recipe-specific metadata exists in that namespace. + The "BuildStarted" and "buildCompleted" events also run in + the main cooker/server process rather than any worker context. + Thus, any changes made to the datastore would be seen by other + cooker/server events within the current build but not seen + outside of that build or in any worker context. + Task events run in the actual tasks in question consequently + have recipe-specific and task-specific contents. + These events run in the worker context and are discarded at + the end of task execution. - During a standard build, the following common events might occur: + During a standard build, the following common events might + occur. + The following events are the most common kinds of events that + most metadata might have an interest in viewing: - bb.event.ConfigParsed() + bb.event.ConfigParsed(): + Fired when the base configuration; which consists of + bitbake.conf, + base.bbclass and any global + INHERIT statements; has been parsed. + You can see multiple such events when each of the + workers parse the base configuration or if the server + changes configuration and reparses. + Any given datastore only has one such event executed + against it, however. + If + BB_INVALIDCONF + is set in the datastore by the event handler, the + configuration is reparsed and a new event triggered, + allowing the metadata to update configuration. + + + bb.event.HeartbeatEvent(): + Fires at regular time intervals of one second. + You can configure the interval time using the + BB_HEARTBEAT_EVENT variable. + The event's "time" attribute is the + time.time() value when the + event is triggered. + This event is useful for activities such as + system state monitoring. - bb.event.ParseStarted() + bb.event.ParseStarted(): + Fired when BitBake is about to start parsing recipes. + This event's "total" attribute represents the number of + recipes BitBake plans to parse. - bb.event.ParseProgress() + bb.event.ParseProgress(): + Fired as parsing progresses. + This event's "current" attribute is the number of + recipes parsed as well as the "total" attribute. - bb.event.ParseCompleted() + bb.event.ParseCompleted(): + Fired when parsing is complete. + This event's "cached", "parsed", "skipped", "virtuals", + "masked", and "errors" attributes provide statistics + for the parsing results. - bb.event.BuildStarted() + bb.event.BuildStarted(): + Fired when a new build starts. - bb.build.TaskStarted() + bb.build.TaskStarted(): + Fired when a task starts. + This event's "taskfile" attribute points to the recipe + from which the task originates. + The "taskname" attribute, which is the task's name, + includes the do_ prefix, and the + "logfile" attribute point to where the task's output is + stored. + Finally, the "time" attribute is the task's execution start + time. - bb.build.TaskInvalid() + bb.build.TaskInvalid(): + Fired if BitBake tries to execute a task that does not exist. - bb.build.TaskFailedSilent() + bb.build.TaskFailedSilent(): + Fired for setscene tasks that fail and should not be + presented to the user verbosely. - bb.build.TaskFailed() + bb.build.TaskFailed(): + Fired for normal tasks that fail. - bb.build.TaskSucceeded() + bb.build.TaskSucceeded(): + Fired when a task successfully completes. - bb.event.BuildCompleted() + bb.event.BuildCompleted(): + Fired when a build finishes. - bb.cooker.CookerExit() + bb.cooker.CookerExit(): + Fired when the BitBake server/cooker shuts down. + This event is usually only seen by the UIs as a + sign they should also shutdown. - Here is a list of other events that occur based on specific requests - to the server: + + + + This next list of example events occur based on specific + requests to the server. + These events are often used to communicate larger pieces of + information from the BitBake server to other parts of + BitBake such as user interfaces: bb.event.TreeDataPreparationStarted() - bb.event.TreeDataPreparationProgress + bb.event.TreeDataPreparationProgress() - bb.event.TreeDataPreparationCompleted + bb.event.TreeDataPreparationCompleted() - bb.event.DepTreeGenerated + bb.event.DepTreeGenerated() - bb.event.CoreBaseFilesFound + bb.event.CoreBaseFilesFound() - bb.event.ConfigFilePathFound + bb.event.ConfigFilePathFound() - bb.event.FilesMatchingFound + bb.event.FilesMatchingFound() - bb.event.ConfigFilesFound + bb.event.ConfigFilesFound() - bb.event.TargetsTreeGenerated + bb.event.TargetsTreeGenerated() -- cgit 1.2.3-korg