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>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
3b4a36be50
commit
000d2708b2
|
|
@ -505,14 +505,14 @@
|
||||||
<title>Unseting variables</title>
|
<title>Unseting variables</title>
|
||||||
|
|
||||||
<para>
|
<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.
|
from BitBake's internal data dictionary by using the "unset" keyword.
|
||||||
Here is an example:
|
Here is an example:
|
||||||
<literallayout class='monospaced'>
|
<literallayout class='monospaced'>
|
||||||
unset DATE
|
unset DATE
|
||||||
unset do_fetch[noexec]
|
unset do_fetch[noexec]
|
||||||
</literallayout>
|
</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.
|
<filename>do_fetch[noexec]</filename> flag.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
|
@ -1984,128 +1984,194 @@
|
||||||
<title>Events</title>
|
<title>Events</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
BitBake allows installation of event handlers within
|
BitBake allows installation of event handlers within recipe
|
||||||
recipe and class files.
|
and class files.
|
||||||
Events are triggered at certain points during operation,
|
Events are triggered at certain points during operation, such
|
||||||
such as the beginning of an operation against a given recipe
|
as the beginning of operation against a given recipe
|
||||||
(<filename>*.bb</filename> file), the start of a given task,
|
(i.e. <filename>*.bb</filename>), the start of a given task,
|
||||||
task failure, task success, and so forth.
|
a task failure, a task success, and so forth.
|
||||||
The intent is to make it easy to do things like email
|
The intent is to make it easy to do things like email
|
||||||
notification on build failure.
|
notification on build failures.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Following is an example event handler that
|
Following is an example event handler that prints the name
|
||||||
prints the name of the event and the content of
|
of the event and the content of the
|
||||||
the <filename>FILE</filename> variable:
|
<filename>FILE</filename> variable:
|
||||||
<literallayout class='monospaced'>
|
<literallayout class='monospaced'>
|
||||||
addhandler myclass_eventhandler
|
addhandler myclass_eventhandler
|
||||||
python myclass_eventhandler() {
|
python myclass_eventhandler() {
|
||||||
from bb.event import getName
|
from bb.event import getName
|
||||||
from bb import data
|
|
||||||
print("The name of the Event is %s" % getName(e))
|
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>
|
</literallayout>
|
||||||
This event handler gets called every time an event is
|
In the previous example, an eventmask has been set so that
|
||||||
triggered.
|
the handler only sees the "BuildStarted" and "BuildCompleted"
|
||||||
A global variable "<filename>e</filename>" is defined and
|
events.
|
||||||
"<filename>e.data</filename>" contains an instance of
|
This event handler gets called every time an event matching
|
||||||
"<filename>bb.data</filename>".
|
the eventmask is triggered.
|
||||||
With the <filename>getName(e)</filename> method, one can get
|
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 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>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Because you probably are only interested in a subset of events,
|
The context of the datastore is appropriate to the event
|
||||||
you would likely use the <filename>[eventmask]</filename> flag
|
in question.
|
||||||
for your event handler to be sure that only certain events
|
For example, "BuildStarted" and "BuildCompleted" events run
|
||||||
trigger the handler.
|
before any tasks are executed so would be in the global
|
||||||
Given the previous example, suppose you only wanted the
|
configuration datastore namespace.
|
||||||
<filename>bb.build.TaskFailed</filename> event to trigger that
|
No recipe-specific metadata exists in that namespace.
|
||||||
event handler.
|
The "BuildStarted" and "buildCompleted" events also run in
|
||||||
Use the flag as follows:
|
the main cooker/server process rather than any worker context.
|
||||||
<literallayout class='monospaced'>
|
Thus, any changes made to the datastore would be seen by other
|
||||||
addhandler myclass_eventhandler
|
cooker/server events within the current build but not seen
|
||||||
myclass_eventhandler[eventmask] = "bb.build.TaskFailed"
|
outside of that build or in any worker context.
|
||||||
python myclass_eventhandler() {
|
Task events run in the actual tasks in question consequently
|
||||||
from bb.event import getName
|
have recipe-specific and task-specific contents.
|
||||||
from bb import data
|
These events run in the worker context and are discarded at
|
||||||
print("The name of the Event is %s" % getName(e))
|
the end of task execution.
|
||||||
print("The file we run for is %s" % data.getVar('FILE', e.data, True))
|
|
||||||
}
|
|
||||||
</literallayout>
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<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>
|
<itemizedlist>
|
||||||
<listitem><para>
|
<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>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.ParseStarted()</filename>
|
<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>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.ParseProgress()</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>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.ParseCompleted()</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>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.BuildStarted()</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>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.build.TaskStarted()</filename>
|
<filename>bb.event.BuildStarted()</filename>:
|
||||||
|
Fired when a new build starts.
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.build.TaskInvalid()</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>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.build.TaskFailedSilent()</filename>
|
<filename>bb.build.TaskInvalid()</filename>:
|
||||||
|
Fired if BitBake tries to execute a task that does not exist.
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.build.TaskFailed()</filename>
|
<filename>bb.build.TaskFailedSilent()</filename>:
|
||||||
|
Fired for setscene tasks that fail and should not be
|
||||||
|
presented to the user verbosely.
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.build.TaskSucceeded()</filename>
|
<filename>bb.build.TaskFailed()</filename>:
|
||||||
|
Fired for normal tasks that fail.
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.BuildCompleted()</filename>
|
<filename>bb.build.TaskSucceeded()</filename>:
|
||||||
|
Fired when a task successfully completes.
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.cooker.CookerExit()</filename>
|
<filename>bb.event.BuildCompleted()</filename>:
|
||||||
|
Fired when a build finishes.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
<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>
|
</para></listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
Here is a list of other events that occur based on specific requests
|
</para>
|
||||||
to the server:
|
|
||||||
|
<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>
|
<itemizedlist>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.TreeDataPreparationStarted()</filename>
|
<filename>bb.event.TreeDataPreparationStarted()</filename>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.TreeDataPreparationProgress</filename>
|
<filename>bb.event.TreeDataPreparationProgress()</filename>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.TreeDataPreparationCompleted</filename>
|
<filename>bb.event.TreeDataPreparationCompleted()</filename>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.DepTreeGenerated</filename>
|
<filename>bb.event.DepTreeGenerated()</filename>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.CoreBaseFilesFound</filename>
|
<filename>bb.event.CoreBaseFilesFound()</filename>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.ConfigFilePathFound</filename>
|
<filename>bb.event.ConfigFilePathFound()</filename>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.FilesMatchingFound</filename>
|
<filename>bb.event.FilesMatchingFound()</filename>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.ConfigFilesFound</filename>
|
<filename>bb.event.ConfigFilesFound()</filename>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>
|
<listitem><para>
|
||||||
<filename>bb.event.TargetsTreeGenerated</filename>
|
<filename>bb.event.TargetsTreeGenerated()</filename>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue