summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
diff options
context:
space:
mode:
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml188
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 badc7c0e46..d1b93bc076 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 @@
505 <title>Unseting variables</title> 505 <title>Unseting variables</title>
506 506
507 <para> 507 <para>
508 It is possible to completely remove a variable or a variable flag 508 It is possible to completely remove a variable or a variable flag
509 from BitBake's internal data dictionary by using the "unset" keyword. 509 from BitBake's internal data dictionary by using the "unset" keyword.
510 Here is an example: 510 Here is an example:
511 <literallayout class='monospaced'> 511 <literallayout class='monospaced'>
512 unset DATE 512 unset DATE
513 unset do_fetch[noexec] 513 unset do_fetch[noexec]
514 </literallayout> 514 </literallayout>
515 These two statements remove the <filename>DATE</filename> and the 515 These two statements remove the <filename>DATE</filename> and the
516 <filename>do_fetch[noexec]</filename> flag. 516 <filename>do_fetch[noexec]</filename> flag.
517 </para> 517 </para>
518 518
@@ -1984,128 +1984,194 @@
1984 <title>Events</title> 1984 <title>Events</title>
1985 1985
1986 <para> 1986 <para>
1987 BitBake allows installation of event handlers within 1987 BitBake allows installation of event handlers within recipe
1988 recipe and class files. 1988 and class files.
1989 Events are triggered at certain points during operation, 1989 Events are triggered at certain points during operation, such
1990 such as the beginning of an operation against a given recipe 1990 as the beginning of operation against a given recipe
1991 (<filename>*.bb</filename> file), the start of a given task, 1991 (i.e. <filename>*.bb</filename>), the start of a given task,
1992 task failure, task success, and so forth. 1992 a task failure, a task success, and so forth.
1993 The intent is to make it easy to do things like email 1993 The intent is to make it easy to do things like email
1994 notification on build failure. 1994 notification on build failures.
1995 </para> 1995 </para>
1996 1996
1997 <para> 1997 <para>
1998 Following is an example event handler that 1998 Following is an example event handler that prints the name
1999 prints the name of the event and the content of 1999 of the event and the content of the
2000 the <filename>FILE</filename> variable: 2000 <filename>FILE</filename> variable:
2001 <literallayout class='monospaced'> 2001 <literallayout class='monospaced'>
2002 addhandler myclass_eventhandler 2002 addhandler myclass_eventhandler
2003 python myclass_eventhandler() { 2003 python myclass_eventhandler() {
2004 from bb.event import getName 2004 from bb.event import getName
2005 from bb import data
2006 print("The name of the Event is %s" % getName(e)) 2005 print("The name of the Event is %s" % getName(e))
2007 print("The file we run for is %s" % data.getVar('FILE', e.data, True)) 2006 print("The file we run for is %s" % d.getVar('FILE'))
2008 } 2007 }
2008 myclass_eventhandler[eventmask] = "bb.event.BuildStarted bb.event.BuildCompleted"
2009 </literallayout> 2009 </literallayout>
2010 This event handler gets called every time an event is 2010 In the previous example, an eventmask has been set so that
2011 triggered. 2011 the handler only sees the "BuildStarted" and "BuildCompleted"
2012 A global variable "<filename>e</filename>" is defined and 2012 events.
2013 "<filename>e.data</filename>" contains an instance of 2013 This event handler gets called every time an event matching
2014 "<filename>bb.data</filename>". 2014 the eventmask is triggered.
2015 With the <filename>getName(e)</filename> method, one can get 2015 A global variable "e" is defined, which represents the current
2016 event.
2017 With the <filename>getName(e)</filename> method, you can get
2016 the name of the triggered event. 2018 the name of the triggered event.
2019 The global datastore is available as "d".
2020 In legacy code, you might see "e.data" used to get the datastore".
2021 However, realize that "e.data" is deprecated and you should use
2022 "d" going forward.
2017 </para> 2023 </para>
2018 2024
2019 <para> 2025 <para>
2020 Because you probably are only interested in a subset of events, 2026 The context of the datastore is appropriate to the event
2021 you would likely use the <filename>[eventmask]</filename> flag 2027 in question.
2022 for your event handler to be sure that only certain events 2028 For example, "BuildStarted" and "BuildCompleted" events run
2023 trigger the handler. 2029 before any tasks are executed so would be in the global
2024 Given the previous example, suppose you only wanted the 2030 configuration datastore namespace.
2025 <filename>bb.build.TaskFailed</filename> event to trigger that 2031 No recipe-specific metadata exists in that namespace.
2026 event handler. 2032 The "BuildStarted" and "buildCompleted" events also run in
2027 Use the flag as follows: 2033 the main cooker/server process rather than any worker context.
2028 <literallayout class='monospaced'> 2034 Thus, any changes made to the datastore would be seen by other
2029 addhandler myclass_eventhandler 2035 cooker/server events within the current build but not seen
2030 myclass_eventhandler[eventmask] = "bb.build.TaskFailed" 2036 outside of that build or in any worker context.
2031 python myclass_eventhandler() { 2037 Task events run in the actual tasks in question consequently
2032 from bb.event import getName 2038 have recipe-specific and task-specific contents.
2033 from bb import data 2039 These events run in the worker context and are discarded at
2034 print("The name of the Event is %s" % getName(e)) 2040 the end of task execution.
2035 print("The file we run for is %s" % data.getVar('FILE', e.data, True))
2036 }
2037 </literallayout>
2038 </para> 2041 </para>
2039 2042
2040 <para> 2043 <para>
2041 During a standard build, the following common events might occur: 2044 During a standard build, the following common events might
2045 occur.
2046 The following events are the most common kinds of events that
2047 most metadata might have an interest in viewing:
2042 <itemizedlist> 2048 <itemizedlist>
2043 <listitem><para> 2049 <listitem><para>
2044 <filename>bb.event.ConfigParsed()</filename> 2050 <filename>bb.event.ConfigParsed()</filename>:
2051 Fired when the base configuration; which consists of
2052 <filename>bitbake.conf</filename>,
2053 <filename>base.bbclass</filename> and any global
2054 <filename>INHERIT</filename> statements; has been parsed.
2055 You can see multiple such events when each of the
2056 workers parse the base configuration or if the server
2057 changes configuration and reparses.
2058 Any given datastore only has one such event executed
2059 against it, however.
2060 If
2061 <link linkende='var-BB_INVALIDCONF'><filename>BB_INVALIDCONF</filename></link>
2062 is set in the datastore by the event handler, the
2063 configuration is reparsed and a new event triggered,
2064 allowing the metadata to update configuration.
2065 </para></listitem>
2066 <listitem><para>
2067 <filename>bb.event.HeartbeatEvent()</filename>:
2068 Fires at regular time intervals of one second.
2069 You can configure the interval time using the
2070 <filename>BB_HEARTBEAT_EVENT</filename> variable.
2071 The event's "time" attribute is the
2072 <filename>time.time()</filename> value when the
2073 event is triggered.
2074 This event is useful for activities such as
2075 system state monitoring.
2045 </para></listitem> 2076 </para></listitem>
2046 <listitem><para> 2077 <listitem><para>
2047 <filename>bb.event.ParseStarted()</filename> 2078 <filename>bb.event.ParseStarted()</filename>:
2079 Fired when BitBake is about to start parsing recipes.
2080 This event's "total" attribute represents the number of
2081 recipes BitBake plans to parse.
2048 </para></listitem> 2082 </para></listitem>
2049 <listitem><para> 2083 <listitem><para>
2050 <filename>bb.event.ParseProgress()</filename> 2084 <filename>bb.event.ParseProgress()</filename>:
2085 Fired as parsing progresses.
2086 This event's "current" attribute is the number of
2087 recipes parsed as well as the "total" attribute.
2051 </para></listitem> 2088 </para></listitem>
2052 <listitem><para> 2089 <listitem><para>
2053 <filename>bb.event.ParseCompleted()</filename> 2090 <filename>bb.event.ParseCompleted()</filename>:
2091 Fired when parsing is complete.
2092 This event's "cached", "parsed", "skipped", "virtuals",
2093 "masked", and "errors" attributes provide statistics
2094 for the parsing results.
2054 </para></listitem> 2095 </para></listitem>
2055 <listitem><para> 2096 <listitem><para>
2056 <filename>bb.event.BuildStarted()</filename> 2097 <filename>bb.event.BuildStarted()</filename>:
2098 Fired when a new build starts.
2057 </para></listitem> 2099 </para></listitem>
2058 <listitem><para> 2100 <listitem><para>
2059 <filename>bb.build.TaskStarted()</filename> 2101 <filename>bb.build.TaskStarted()</filename>:
2102 Fired when a task starts.
2103 This event's "taskfile" attribute points to the recipe
2104 from which the task originates.
2105 The "taskname" attribute, which is the task's name,
2106 includes the <filename>do_</filename> prefix, and the
2107 "logfile" attribute point to where the task's output is
2108 stored.
2109 Finally, the "time" attribute is the task's execution start
2110 time.
2060 </para></listitem> 2111 </para></listitem>
2061 <listitem><para> 2112 <listitem><para>
2062 <filename>bb.build.TaskInvalid()</filename> 2113 <filename>bb.build.TaskInvalid()</filename>:
2114 Fired if BitBake tries to execute a task that does not exist.
2063 </para></listitem> 2115 </para></listitem>
2064 <listitem><para> 2116 <listitem><para>
2065 <filename>bb.build.TaskFailedSilent()</filename> 2117 <filename>bb.build.TaskFailedSilent()</filename>:
2118 Fired for setscene tasks that fail and should not be
2119 presented to the user verbosely.
2066 </para></listitem> 2120 </para></listitem>
2067 <listitem><para> 2121 <listitem><para>
2068 <filename>bb.build.TaskFailed()</filename> 2122 <filename>bb.build.TaskFailed()</filename>:
2123 Fired for normal tasks that fail.
2069 </para></listitem> 2124 </para></listitem>
2070 <listitem><para> 2125 <listitem><para>
2071 <filename>bb.build.TaskSucceeded()</filename> 2126 <filename>bb.build.TaskSucceeded()</filename>:
2127 Fired when a task successfully completes.
2072 </para></listitem> 2128 </para></listitem>
2073 <listitem><para> 2129 <listitem><para>
2074 <filename>bb.event.BuildCompleted()</filename> 2130 <filename>bb.event.BuildCompleted()</filename>:
2131 Fired when a build finishes.
2075 </para></listitem> 2132 </para></listitem>
2076 <listitem><para> 2133 <listitem><para>
2077 <filename>bb.cooker.CookerExit()</filename> 2134 <filename>bb.cooker.CookerExit()</filename>:
2135 Fired when the BitBake server/cooker shuts down.
2136 This event is usually only seen by the UIs as a
2137 sign they should also shutdown.
2078 </para></listitem> 2138 </para></listitem>
2079 </itemizedlist> 2139 </itemizedlist>
2080 Here is a list of other events that occur based on specific requests 2140 </para>
2081 to the server: 2141
2142 <para>
2143 This next list of example events occur based on specific
2144 requests to the server.
2145 These events are often used to communicate larger pieces of
2146 information from the BitBake server to other parts of
2147 BitBake such as user interfaces:
2082 <itemizedlist> 2148 <itemizedlist>
2083 <listitem><para> 2149 <listitem><para>
2084 <filename>bb.event.TreeDataPreparationStarted()</filename> 2150 <filename>bb.event.TreeDataPreparationStarted()</filename>
2085 </para></listitem> 2151 </para></listitem>
2086 <listitem><para> 2152 <listitem><para>
2087 <filename>bb.event.TreeDataPreparationProgress</filename> 2153 <filename>bb.event.TreeDataPreparationProgress()</filename>
2088 </para></listitem> 2154 </para></listitem>
2089 <listitem><para> 2155 <listitem><para>
2090 <filename>bb.event.TreeDataPreparationCompleted</filename> 2156 <filename>bb.event.TreeDataPreparationCompleted()</filename>
2091 </para></listitem> 2157 </para></listitem>
2092 <listitem><para> 2158 <listitem><para>
2093 <filename>bb.event.DepTreeGenerated</filename> 2159 <filename>bb.event.DepTreeGenerated()</filename>
2094 </para></listitem> 2160 </para></listitem>
2095 <listitem><para> 2161 <listitem><para>
2096 <filename>bb.event.CoreBaseFilesFound</filename> 2162 <filename>bb.event.CoreBaseFilesFound()</filename>
2097 </para></listitem> 2163 </para></listitem>
2098 <listitem><para> 2164 <listitem><para>
2099 <filename>bb.event.ConfigFilePathFound</filename> 2165 <filename>bb.event.ConfigFilePathFound()</filename>
2100 </para></listitem> 2166 </para></listitem>
2101 <listitem><para> 2167 <listitem><para>
2102 <filename>bb.event.FilesMatchingFound</filename> 2168 <filename>bb.event.FilesMatchingFound()</filename>
2103 </para></listitem> 2169 </para></listitem>
2104 <listitem><para> 2170 <listitem><para>
2105 <filename>bb.event.ConfigFilesFound</filename> 2171 <filename>bb.event.ConfigFilesFound()</filename>
2106 </para></listitem> 2172 </para></listitem>
2107 <listitem><para> 2173 <listitem><para>
2108 <filename>bb.event.TargetsTreeGenerated</filename> 2174 <filename>bb.event.TargetsTreeGenerated()</filename>
2109 </para></listitem> 2175 </para></listitem>
2110 </itemizedlist> 2176 </itemizedlist>
2111 </para> 2177 </para>