[gnome-continuous-yocto/gnomeostree-3.28-rocko: 4302/8267] bitbake: bitbake-user-manual: Updated Event descriptions
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-continuous-yocto/gnomeostree-3.28-rocko: 4302/8267] bitbake: bitbake-user-manual: Updated Event descriptions
- Date: Sun, 17 Dec 2017 01:50:46 +0000 (UTC)
commit 000d2708b2e5dd2ea53132225fad41f8ddf95fc0
Author: Scott Rifenbark <srifenbark gmail com>
Date: Tue Jan 10 15:37:16 2017 -0800
bitbake: bitbake-user-manual: Updated Event descriptions
Fixes [YOCTO #10886]
Added text descriptions for many of the events in the list of the
"Events" section.
(Bitbake rev: e3b7e8430cb207756b59b32128aa3cef6a626fa1)
Signed-off-by: Scott Rifenbark <srifenbark gmail com>
Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>
.../bitbake-user-manual-metadata.xml | 188 +++++++++++++-------
1 files changed, 127 insertions(+), 61 deletions(-)
---
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index badc7c0..d1b93bc 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -505,14 +505,14 @@
<title>Unseting variables</title>
<para>
- 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:
<literallayout class='monospaced'>
unset DATE
unset do_fetch[noexec]
</literallayout>
- These two statements remove the <filename>DATE</filename> and the
+ These two statements remove the <filename>DATE</filename> and the
<filename>do_fetch[noexec]</filename> flag.
</para>
@@ -1984,128 +1984,194 @@
<title>Events</title>
<para>
- 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
- (<filename>*.bb</filename> 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. <filename>*.bb</filename>), 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.
</para>
<para>
- Following is an example event handler that
- prints the name of the event and the content of
- the <filename>FILE</filename> variable:
+ Following is an example event handler that prints the name
+ of the event and the content of the
+ <filename>FILE</filename> variable:
<literallayout class='monospaced'>
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"
</literallayout>
- This event handler gets called every time an event is
- triggered.
- A global variable "<filename>e</filename>" is defined and
- "<filename>e.data</filename>" contains an instance of
- "<filename>bb.data</filename>".
- With the <filename>getName(e)</filename> 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 <filename>getName(e)</filename> 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.
</para>
<para>
- Because you probably are only interested in a subset of events,
- you would likely use the <filename>[eventmask]</filename> flag
- for your event handler to be sure that only certain events
- trigger the handler.
- Given the previous example, suppose you only wanted the
- <filename>bb.build.TaskFailed</filename> event to trigger that
- event handler.
- Use the flag as follows:
- <literallayout class='monospaced'>
- 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))
- }
- </literallayout>
+ 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.
</para>
<para>
- 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:
<itemizedlist>
<listitem><para>
- <filename>bb.event.ConfigParsed()</filename>
+ <filename>bb.event.ConfigParsed()</filename>:
+ Fired when the base configuration; which consists of
+ <filename>bitbake.conf</filename>,
+ <filename>base.bbclass</filename> and any global
+ <filename>INHERIT</filename> 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
+ <link linkende='var-BB_INVALIDCONF'><filename>BB_INVALIDCONF</filename></link>
+ is set in the datastore by the event handler, the
+ configuration is reparsed and a new event triggered,
+ allowing the metadata to update configuration.
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.HeartbeatEvent()</filename>:
+ Fires at regular time intervals of one second.
+ You can configure the interval time using the
+ <filename>BB_HEARTBEAT_EVENT</filename> variable.
+ The event's "time" attribute is the
+ <filename>time.time()</filename> value when the
+ event is triggered.
+ This event is useful for activities such as
+ system state monitoring.
</para></listitem>
<listitem><para>
- <filename>bb.event.ParseStarted()</filename>
+ <filename>bb.event.ParseStarted()</filename>:
+ Fired when BitBake is about to start parsing recipes.
+ This event's "total" attribute represents the number of
+ recipes BitBake plans to parse.
</para></listitem>
<listitem><para>
- <filename>bb.event.ParseProgress()</filename>
+ <filename>bb.event.ParseProgress()</filename>:
+ Fired as parsing progresses.
+ This event's "current" attribute is the number of
+ recipes parsed as well as the "total" attribute.
</para></listitem>
<listitem><para>
- <filename>bb.event.ParseCompleted()</filename>
+ <filename>bb.event.ParseCompleted()</filename>:
+ Fired when parsing is complete.
+ This event's "cached", "parsed", "skipped", "virtuals",
+ "masked", and "errors" attributes provide statistics
+ for the parsing results.
</para></listitem>
<listitem><para>
- <filename>bb.event.BuildStarted()</filename>
+ <filename>bb.event.BuildStarted()</filename>:
+ Fired when a new build starts.
</para></listitem>
<listitem><para>
- <filename>bb.build.TaskStarted()</filename>
+ <filename>bb.build.TaskStarted()</filename>:
+ 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 <filename>do_</filename> 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.
</para></listitem>
<listitem><para>
- <filename>bb.build.TaskInvalid()</filename>
+ <filename>bb.build.TaskInvalid()</filename>:
+ Fired if BitBake tries to execute a task that does not exist.
</para></listitem>
<listitem><para>
- <filename>bb.build.TaskFailedSilent()</filename>
+ <filename>bb.build.TaskFailedSilent()</filename>:
+ Fired for setscene tasks that fail and should not be
+ presented to the user verbosely.
</para></listitem>
<listitem><para>
- <filename>bb.build.TaskFailed()</filename>
+ <filename>bb.build.TaskFailed()</filename>:
+ Fired for normal tasks that fail.
</para></listitem>
<listitem><para>
- <filename>bb.build.TaskSucceeded()</filename>
+ <filename>bb.build.TaskSucceeded()</filename>:
+ Fired when a task successfully completes.
</para></listitem>
<listitem><para>
- <filename>bb.event.BuildCompleted()</filename>
+ <filename>bb.event.BuildCompleted()</filename>:
+ Fired when a build finishes.
</para></listitem>
<listitem><para>
- <filename>bb.cooker.CookerExit()</filename>
+ <filename>bb.cooker.CookerExit()</filename>:
+ Fired when the BitBake server/cooker shuts down.
+ This event is usually only seen by the UIs as a
+ sign they should also shutdown.
</para></listitem>
</itemizedlist>
- Here is a list of other events that occur based on specific requests
- to the server:
+ </para>
+
+ <para>
+ 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:
<itemizedlist>
<listitem><para>
<filename>bb.event.TreeDataPreparationStarted()</filename>
</para></listitem>
<listitem><para>
- <filename>bb.event.TreeDataPreparationProgress</filename>
+ <filename>bb.event.TreeDataPreparationProgress()</filename>
</para></listitem>
<listitem><para>
- <filename>bb.event.TreeDataPreparationCompleted</filename>
+ <filename>bb.event.TreeDataPreparationCompleted()</filename>
</para></listitem>
<listitem><para>
- <filename>bb.event.DepTreeGenerated</filename>
+ <filename>bb.event.DepTreeGenerated()</filename>
</para></listitem>
<listitem><para>
- <filename>bb.event.CoreBaseFilesFound</filename>
+ <filename>bb.event.CoreBaseFilesFound()</filename>
</para></listitem>
<listitem><para>
- <filename>bb.event.ConfigFilePathFound</filename>
+ <filename>bb.event.ConfigFilePathFound()</filename>
</para></listitem>
<listitem><para>
- <filename>bb.event.FilesMatchingFound</filename>
+ <filename>bb.event.FilesMatchingFound()</filename>
</para></listitem>
<listitem><para>
- <filename>bb.event.ConfigFilesFound</filename>
+ <filename>bb.event.ConfigFilesFound()</filename>
</para></listitem>
<listitem><para>
- <filename>bb.event.TargetsTreeGenerated</filename>
+ <filename>bb.event.TargetsTreeGenerated()</filename>
</para></listitem>
</itemizedlist>
</para>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
