summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--bitbake/doc/user-manual/user-manual-bitbakecommand.xml164
-rw-r--r--bitbake/doc/user-manual/user-manual-execution.xml1303
2 files changed, 702 insertions, 765 deletions
diff --git a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml b/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
index e895c6b3f0..5c301a56f3 100644
--- a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
+++ b/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
@@ -4,17 +4,22 @@
4<chapter id="user-manual-command"> 4<chapter id="user-manual-command">
5 <title>The BitBake Command</title> 5 <title>The BitBake Command</title>
6 6
7 <section id='bitbake-command-introduction'> 7 <para>
8 <title>Introduction</title> 8 BitBake is the underlying piece of the build system.
9 9 Two excellent examples are the Yocto Project and the OpenEmbedded
10 <para> 10 build systems.
11 Bitbake is the primary command in the system. 11 Each provide an environment in which to develop embedded Linux
12 It facilitates executing tasks in a single <filename>.bb</filename> 12 images, and each use BitBake as their underlying build engine.
13 file, or executing a given task on a set of multiple 13 </para>
14 <filename>.bb</filename> files, accounting for interdependencies 14
15 amongst them. 15 <para>
16 </para> 16 BitBake facilitates executing tasks in a single <filename>.bb</filename>
17 </section> 17 file, or executing a given task on a set of multiple
18 <filename>.bb</filename> files, accounting for interdependencies
19 amongst them.
20 This chapter presents the BitBake syntax, provides some execution
21 examples, and shows you how to control BitBake with key metadata.
22 </para>
18 23
19 <section id='usage-and-syntax'> 24 <section id='usage-and-syntax'>
20 <title>Usage and syntax</title> 25 <title>Usage and syntax</title>
@@ -110,7 +115,9 @@ Options:
110 <para> 115 <para>
111 Executing tasks for a single recipe file is relatively simple. 116 Executing tasks for a single recipe file is relatively simple.
112 You specify the file in question, and BitBake parses 117 You specify the file in question, and BitBake parses
113 it and executes the specified task (or “build” by default). 118 it and executes the specified task.
119 If you do not specify a task, BitBake executes the default
120 task, which is "build”.
114 BitBake obeys inter-task dependencies when doing 121 BitBake obeys inter-task dependencies when doing
115 so. 122 so.
116 </para> 123 </para>
@@ -138,38 +145,36 @@ Options:
138 when one wants to manage multiple <filename>.bb</filename> 145 when one wants to manage multiple <filename>.bb</filename>
139 files. 146 files.
140 Clearly there needs to be a way to tell BitBake what 147 Clearly there needs to be a way to tell BitBake what
141 files are available, and of those, which we 148 files are available, and of those, which you
142 want to execute at this time. 149 want to execute.
143 There also needs to be a way for each <filename>.bb</filename> 150 There also needs to be a way for each recipe
144 to express its dependencies, both for build-time and 151 to express its dependencies, both for build-time and
145 runtime. 152 runtime.
146 There must be a way for the user to express their preferences 153 There must be a way for you to express recipe preferences
147 when multiple recipes provide the same functionality, or when 154 when multiple recipes provide the same functionality, or when
148 there are multiple versions of a <filename>.bb</filename> file. 155 there are multiple versions of a recipe.
149 </para>
150
151 <para>
152 The next section, Metadata, outlines how to specify such things.
153 </para> 156 </para>
154 157
155 <para> 158 <para>
156 The <filename>bitbake</filename> command, when not using 159 The <filename>bitbake</filename> command, when not using
157 "--buildfile", accepts a PROVIDER, not a filename or 160 "--buildfile" or "-b" only accepts a "PROVIDER".
158 anything else. 161 You cannot provide anything else.
159 By default, a <filename>.bb</filename> generally PROVIDES its 162 By default, a recipe file generally "PROVIDES" its
160 packagename, packagename-version, and packagename-version-revision. 163 "packagename", "packagename-version", and
164 "packagename-version-revision" as shown in the following
165 example:
161 <literallayout class='monospaced'> 166 <literallayout class='monospaced'>
162 $ bitbake foo 167 $ bitbake foo
163 168
164 $ bitbake foo-1.0 169 $ bitbake foo-1.0
165 170
166 $ bitbake foo-1.0-r0 171 $ bitbake foo-1.0-r0
167 172 </literallayout>
173 This next example "PROVIDES" the package name and also uses
174 the "-c" option to tell BitBake to just excute the
175 <filename>do_clean</filename> task:
176 <literallayout class='monospaced'>
168 $ bitbake -c clean foo 177 $ bitbake -c clean foo
169
170 $ bitbake virtual/whatever
171
172 $ bitbake -c clean virtual/whatever
173 </literallayout> 178 </literallayout>
174 </para> 179 </para>
175 </section> 180 </section>
@@ -180,88 +185,57 @@ Options:
180 <para> 185 <para>
181 BitBake is able to generate dependency graphs using 186 BitBake is able to generate dependency graphs using
182 the dot syntax. 187 the dot syntax.
183 These graphs can be converted to images using the dot 188 You can convert these graphs into images using the dot
184 application from 189 application from
185 <ulink url='http://www.graphviz.org'>Graphviz</ulink>. 190 <ulink url='http://www.graphviz.org'>Graphviz</ulink>.
186 Two files will be written into the current working directory:
187 <filename>depends.dot</filename> containing dependency information
188 at the package level and <filename>task-depends.dot</filename>
189 containing a breakdown of the dependencies at the task level.
190 To stop depending on common depends, one can use the "-I" depend
191 option to omit these from the graph.
192 This can lead to more readable graphs.
193 This way, <filename>DEPENDS</filename> from inherited classes
194 such as <filename>base.bbclass</filename> can be removed from the
195 graph.
196 <literallayout class='monospaced'>
197 $ bitbake -g foo
198
199 $ bitbake -g -I virtual/whatever -I bloom foo
200 </literallayout>
201 </para> 191 </para>
202 </section>
203 </section>
204
205 <section id='special-variables'>
206 <title>Special Variables</title>
207
208 <para>
209 Certain variables affect BitBake operation:
210 </para>
211
212 <section id='bb-number-threads'>
213 <title><filename>BB_NUMBER_THREADS</filename></title>
214 192
215 <para> 193 <para>
216 The number of threads BitBake should run at once (default: 1). 194 When you generate a dependency graph, BitBake writes two files
195 to the current working directory:
196 <filename>depends.dot</filename>, which contains dependency information
197 at the package level, and <filename>task-depends.dot</filename>,
198 which contains a breakdown of the dependencies at the task level.
217 </para> 199 </para>
218 </section>
219 </section>
220
221 <section id='bitbake-command-metadata'>
222 <title>Metadata</title>
223 200
224 <para> 201 <para>
225 As you may have seen in the usage information, or in the 202 To stop depending on common depends, use use the "-I" depend
226 information about <filename>.bb</filename> files, the 203 option and BitBake omits them from the graph.
227 <filename>BBFILES</filename> variable is how the BitBake 204 Leaving this information out can produce more readable graphs.
228 tool locates its files. 205 This way, you can remove from the graph
229 This variable is a space-separated list of files 206 <filename>DEPENDS</filename> from inherited classes
230 that are available, and supports wildcards. 207 such as <filename>base.bbclass</filename>.
231 </para> 208 </para>
232
233 <section id='setting-bbfiles'>
234 <title>Setting <filename>BBFILES</filename></title>
235 209
236 <para> 210 <para>
211 Here are two exmples that create dependency graphs.
212 The second example omits common depends from the graph:
237 <literallayout class='monospaced'> 213 <literallayout class='monospaced'>
238 BBFILES = "/path/to/bbfiles/*.bb" 214 $ bitbake -g foo
215
216 $ bitbake -g -I virtual/whatever -I bloom foo
239 </literallayout> 217 </literallayout>
240 With regard to dependencies, it expects the
241 <filename>.bb</filename> to define a
242 <filename>DEPENDS</filename> variable, which contains a
243 space separated list of “package names”, which themselves
244 are the <filename>PN</filename> variable. The
245 <filename>PN</filename> variable is, in general,
246 set to a component of the <filename>.bb</filename>
247 filename by default.
248 </para> 218 </para>
249 </section> 219 </section>
220 </section>
250 221
251 <section id='depending-on-another-recipe-file'> 222 <section id='controlling-bitbake'>
252 <title>Depending on Another Recipe File</title> 223 <title>Controlling BitBake</title>
253
254 <para>
255 <literallayout class='monospaced'>
256 a.bb:
257 224
258 PN = "package-a" 225 <para>
259 DEPENDS += "package-b" 226 Including variables in your recipe and class files help control
227 how BitBake operates.
228 </para>
260 229
261 b.bb: 230 <section id='execution-threads'>
231 <title>Execution Threads</title>
262 232
263 PN = "package-b" 233 <para>
264 </literallayout> 234 You can control how many thread BitBake supports by using the
235 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
236 variable.
237 You would set this in your <filename>local.conf</filename>
238 configuration file.
265 </para> 239 </para>
266 </section> 240 </section>
267 241
diff --git a/bitbake/doc/user-manual/user-manual-execution.xml b/bitbake/doc/user-manual/user-manual-execution.xml
index 365392dbff..aa345de698 100644
--- a/bitbake/doc/user-manual/user-manual-execution.xml
+++ b/bitbake/doc/user-manual/user-manual-execution.xml
@@ -5,686 +5,649 @@
5 <title>Execution</title> 5 <title>Execution</title>
6 6
7 <para> 7 <para>
8 Tasks can either be a shell task or a Python task. 8 The primary purpose for running BitBake is to produce an
9 For shell tasks, BitBake writes a shell script to 9 image, which can be a kernel or a software development kit (SDK).
10 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> 10 Of course, you can execute the <filename>bitbake</filename>
11 and then executes the script. 11 command with options that cause it to execute single tasks,
12 The generated shell script contains all the exported variables, 12 compile single recipe files, capture or clear data, or simply
13 and the shell functions with all variables expanded. 13 return information about the execution environment.
14 Output from the shell script goes to the file
15 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
16 Looking at the expanded shell functions in the run file and
17 the output in the log files is a useful debugging technique.
18 </para> 14 </para>
19 15
20 <para> 16 <para>
21 For Python tasks, BitBake executes the task internally and logs 17 This chapter describes BitBake's execution process from start
22 information to the controlling terminal. 18 to finish when you use it to create an image.
23 Future versions of BitBake will write the functions to files 19 The execution process is launched using the following command
24 similar to the way shell tasks are handled. 20 form:
25 Logging will be handled in a way similar to shell tasks as well. 21 <literallayout class='monospaced'>
22 $ bitbake &lt;target&gt;
23 </literallayout>
24 For information on the BitBake command and its options,
25 see the
26 "<link linkend='user-manual-command'>BitBake Command</link>
27 chapter.
26 </para> 28 </para>
27 29
28 <para> 30 <section id='parsing-the-base-configuration-metadata'>
29 Once all the tasks have been completed BitBake exits. 31 <title>Parsing the Base Configuration Metadata</title>
30 </para> 32
33 <para>
34 The first thing BitBake does is parse base configuration
35 metadata.
36 Base configuration metadata consists of the
37 <filename>bblayers.conf</filename> file to determine what
38 layers BitBake needs to recognize, all necessary
39 <filename>layer.conf</filename> files (one from each layer),
40 and <filename>bitbake.conf</filename>.
41 </para>
42
43 <para>
44 The <filename>bitbake.conf</filename> file resides in the
45 <filename>conf</filename> directory, which must be listed in
46 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
47 This configuratoin file lists and includes other configuration
48 files from the <filename>conf</filename> directory below the
49 directories listed in <filename>BBPATH</filename>.
50 In general, the most important of these included
51 configuration files from a user's perspective
52 is <filename>local.conf</filename>, which contains the user's
53 customized settings for the build environment.
54 </para>
55
56 <para>
57 Other notable configuration files are the distribution configuration
58 file and the machine configuration file.
59 These configuration files are normally identified by
60 variables unique to the build systems using BitBake.
61 For example, the Yocto Project uses the
62 <filename>DISTRO</filename> and <filename>MACHINE</filename>
63 variables, respectively.
64 </para>
65
66 <para>
67 Prior to parsing configuration files, Bitbake looks
68 at certain variables, including:
69 <itemizedlist>
70 <listitem><para><link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link></para></listitem>
71 <listitem><para><link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link></para></listitem>
72 <listitem><para><link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link></para></listitem>
73 <listitem><para><link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link></para></listitem>
74 <listitem><para><link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link></para></listitem>
75 <listitem><para><link linkend='var-PREFERRED_PROVIDERS'><filename>PREFERRED_PROVIDERS</filename></link></para></listitem>
76 </itemizedlist>
77 </para>
78
79 <para>
80 The base configuration metadata is global
81 and therefore affects all packages and tasks that are executed.
82 </para>
83
84 <para>
85 BitBake first searches the current working directory for an
86 optional <filename>conf/bblayers.conf</filename> configuration file.
87 This file is expected to contain a
88 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
89 variable that is a space delimited list of 'layer' directories.
90 </para>
91
92 <para>
93 For each directory (layer) in this list, a <filename>conf/layer.conf</filename>
94 file is searched for and parsed with the
95 <link linkend='var-LAYERDIR'><filename>LAYERDIR</filename></link>
96 variable being set to the directory where the layer was found.
97 The idea is these files automatically setup
98 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
99 and other variables correctly for a given build directory.
100 </para>
101
102 <para>
103 BitBake then expects to find the <filename>conf/bitbake.conf</filename>
104 file somewhere in the user-specified <filename>BBPATH</filename>.
105 That configuration file generally has include directives to pull
106 in any other metadata such as files specific to the architecture,
107 the machine, the local environment, and so forth.
108 </para>
109
110 <para>
111 Only variable definitions and include directives are allowed
112 in <filename>.conf</filename> files.
113 The following variables include:
114 <itemizedlist>
115 <listitem><para>
116 <link linkend='var-BITBAKE_UI'><filename>BITBAKE_UI</filename></link>
117 </para></listitem>
118 <listitem><para>
119 <link linkend='var-BBDEBUG'><filename>BBDEBUG</filename></link>
120 </para></listitem>
121 <listitem><para>
122 <link linkend='var-MULTI_PROVIDER_WHITELIST'><filename>MULTI_PROVIDER_WHITELIST</filename></link>
123 </para></listitem>
124 <listitem><para>
125 <link linkend='var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></link>
126 </para></listitem>
127 <listitem><para>
128 <filename>BBPKGS</filename>
129 </para></listitem>
130 <listitem><para>
131 <link linkend='var-BB_DEFAULT_TASK'><filename>BB_DEFAULT_TASK</filename></link>
132 </para></listitem>
133 <listitem><para>
134 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
135 </para></listitem>
136 <listitem><para>
137 <link linkend='var-BB_VERBOSE_LOGS'><filename>BB_VERBOSE_LOGS</filename></link>
138 </para></listitem>
139 <listitem><para>
140 <link linkend='var-BB_NICE_LEVEL'><filename>BB_NICE_LEVEL</filename></link>
141 </para></listitem>
142 <listitem><para>
143 <link linkend='var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></link>
144 </para></listitem>
145 <listitem><para>
146 <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link>
147 </para></listitem>
148 <listitem><para>
149 <link linkend='var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></link>
150 </para></listitem>
151 <listitem><para>
152 <link linkend='var-BBINCLUDED'><filename>BBINCLUDED</filename></link>
153 </para></listitem>
154 <listitem><para>
155 <link linkend='var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></link>
156 </para></listitem>
157 <listitem><para>
158 <link linkend='var-BUILDNAME'><filename>BUILDNAME</filename></link>
159 </para></listitem>
160 <listitem><para>
161 <link linkend='var-BBMASK'><filename>BBMASK</filename></link>
162 </para></listitem>
163 </itemizedlist>
164 </para>
165
166 <para>
167 After parsing configuration files, BitBake uses its rudimentary
168 inheritance mechanism, which is through class files, to inherit
169 some standard classes.
170 BitBake parses a class when the inherit directive responsible
171 for getting that class is encountered.
172 </para>
173
174 <para>
175 The <filename>base.bbclass</filename> file is always included.
176 Other classes that are specified in the configuration using the
177 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
178 variable are also included.
179 BitBake searches for class files in a "classes" subdirectory under
180 the paths in <filename>BBPATH</filename> in the same way as
181 configuration files.
182 </para>
183
184 <para>
185 A good way to get an idea of the configuration files and
186 the class files used in your execution environment is to
187 run the following BitBake command:
188 <literallayout class='monospaced'>
189 $ bitbake -e > mybb.log
190 </literallayout>
191 Examining the top of the <filename>mybb.log</filename>
192 shows you the many configuration files and class files
193 used in your execution environment.
194 </para>
195 </section>
196
197 <section id='locating-recipes'>
198 <title>Locating Recipes</title>
199
200 <para>
201 The <filename>BBFILES</filename> variable is how BitBake
202 locates files.
203 This variable is a space-separated list of files
204 that are available, supports wildcards, and is set shortly
205 after the parsing phase of BitBake's execution.
206 </para>
207
208 <para>
209 <literallayout class='monospaced'>
210 BBFILES = "/path/to/bbfiles/*.bb"
211 </literallayout>
212 With regard to dependencies, it expects the
213 <filename>.bb</filename> to define a
214 <filename>DEPENDS</filename> variable, which contains a
215 space separated list of “package names”, which themselves
216 are the <filename>PN</filename> variable. The
217 <filename>PN</filename> variable is, in general,
218 set to a component of the <filename>.bb</filename>
219 filename by default.
220 </para>
221 </section>
222
223 <section id='parsing-recipes'>
224 <title>Parsing Recipes</title>
225
226 <para>
227 After classes are included, the variable
228 <filename>BBFILES</filename> is set, usually in
229 <filename>local.conf</filename>, and defines the list of
230 places to search for recipe and append files.
231 Adding extra content to <filename>BBFILES</filename> is best
232 achieved through the use of BitBake layers.
233 </para>
234
235 <para>
236 BitBake parses each recipe and append file located with
237 <filename>BBFILES</filename> and stores the values of various
238 variables into the datastore.
239 In summary, for each recipe and append file pairing, the configuration
240 plus the base class of variables are set, followed by the data in the
241 recipe file itself, followed by any inherit commands
242 that the recipe file might contain.
243 </para>
244
245 <para>
246 Part of parsing a recipe is making sure that all the recipes
247 that the recipe being parsed depends on are understood.
248 These other recipes could be located in other layers or in
249 a specific layer version.
250 These two variables in a recipe can help with with these
251 cases:
252 <itemizedlist>
253 <listitem><para>
254 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
255 </para></listitem>
256 <listitem><para>
257 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link>
258 </para></listitem>
259 </itemizedlist>
260 </para>
261
262 <para>
263 Because parsing recipe and append files is a time consuming
264 process, a cache, referred to as the "setscene"
265 is kept to speed up subsequent parsing.
266 The setscene is invalid if the timestamps of a recipe changes,
267 any of the include files change, configuration files change,
268 or class files on which the recipe file depends change.
269 </para>
270 </section>
271
272 <section id='executing-tasks'>
273 <title>Executing Tasks</title>
274
275 <para>
276 Tasks can either be a shell task or a Python task.
277 For shell tasks, BitBake writes a shell script to
278 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename>
279 and then executes the script.
280 The generated shell script contains all the exported variables,
281 and the shell functions with all variables expanded.
282 Output from the shell script goes to the file
283 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
284 Looking at the expanded shell functions in the run file and
285 the output in the log files is a useful debugging technique.
286 </para>
287
288 <para>
289 For Python tasks, BitBake executes the task internally and logs
290 information to the controlling terminal.
291 Future versions of BitBake will write the functions to files
292 similar to the way shell tasks are handled.
293 Logging will be handled in a way similar to shell tasks as well.
294 </para>
295
296 <para>
297 Variables specific to scheduling functionality exist:
298 <itemizedlist>
299 <listitem><para>
300 <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
301 </para></listitem>
302 <listitem><para>
303 <link linkend='var-BB_SCHEDULERS'><filename>BB_SCHEDULERS</filename></link>
304 </para></listitem>
305 </itemizedlist>
306 </para>
307 </section>
308
309 <section id='source-fetching-dev-environment'>
310 <title>Source Fetching</title>
311
312 <para>
313 The first stages of building a recipe are to fetch and unpack
314 the source code:
315 <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
316 </para>
317
318 <para>
319 The <filename>do_fetch</filename> and
320 <filename>do_unpack</filename> tasks fetch the source files
321 and unpack them into the work directory.
322 By default, everything is accomplished in the
323 build directory,
324 which has a defined structure.
325 </para>
326
327 <para>
328 Unpacked source files are pointed to by a variable.
329 For example, in the Yocto Project and OpenEmbedded build systems,
330 the <filename>S</filename> variable points to these source files.
331 Each recipe has an area in the Build Directory where the
332 unpacked source code resides.
333 The name of that directory for any given recipe is defined from
334 several different variables.
335 You can see the variables that define these directories
336 by looking at the figure that shows the structure and variables
337 used in the Yocto Project:
338 <itemizedlist>
339 <listitem><para><filename>TMPDIR</filename>
340 </para></listitem>
341 <listitem><para><filename>PACKAGE_ARCH</filename>
342 </para></listitem>
343 <listitem><para><filename>TARGET_OS</filename>
344 </para></listitem>
345 <listitem><para><link linkend='var-PN'><filename>PN</filename></link>
346 </para></listitem>
347 <listitem><para><link linkend='var-PV'><filename>PV</filename></link>
348 </para></listitem>
349 <listitem><para><link linkend='var-PR'><filename>PR</filename></link>
350 </para></listitem>
351 <listitem><para><filename>WORKDIR</filename>
352 </para></listitem>
353 <listitem><para><filename>S</filename>
354 </para></listitem>
355 </itemizedlist>
356 </para>
357
358 <para>
359 Briefly, the <filename>S</filename> directory contains the
360 unpacked source files for a recipe.
361 The <filename>WORKDIR</filename> directory is where all the
362 building goes on for a given recipe.
363 </para>
364 </section>
365
366 <section id='patching-dev-environment'>
367 <title>Patching</title>
368
369 <para>
370 Once source code is fetched and unpacked, BitBake locates
371 patch files and applies them to the source files:
372 <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
373 </para>
374
375 <para>
376 The <filename>do_patch</filename> task processes recipes by
377 using the
378 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
379 variable to locate applicable patch files, which by default
380 are <filename>*.patch</filename> or
381 <filename>*.diff</filename> files, or any file if
382 "apply=yes" is specified for the file in
383 <filename>SRC_URI</filename>.
384 </para>
31 385
32 <section id='parsing-and-execution'> 386 <para>
33 <title>Parsing and Execution</title> 387 BitBake finds and applies multiple patches for a single recipe
34 388 in the order in which it finds the patches.
35 <section id='parsing-overview'> 389 Patches are applied to the recipe's source files located in the
36 <title>Parsing Overview</title> 390 <filename>S</filename> directory.
37 391 </para>
38 <para> 392
39 BitBake parses configuration files, classes, recipes, and append 393 <para>
40 files. 394 For more information on how the source directories are
41 </para> 395 created, see the
42 396 "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
43 <para> 397 section.
44 The first thing BitBake does is look for the 398 </para>
45 <filename>bitbake.conf</filename> file.
46 This file resides in the <filename>conf</filename>
47 directory, which must be listed in
48 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
49 </para>
50
51 <para>
52 The <filename>bitbake.conf</filename> file lists other configuration
53 files to include from the <filename>conf</filename> directory below the
54 directories listed in <filename>BBPATH</filename>.
55 In general, the most important of these
56 configuration files from a user's perspective
57 is <filename>local.conf</filename>, which contains the user's
58 customized settings for the build environment.
59 </para>
60
61 <para>
62 Other notable configuration files are the distribution configuration
63 file and the machine configuration file.
64 These configuration files are normally identified by
65 variables unique to the build systems using BitBake.
66 For example, the Yocto Project uses the
67 <filename>DISTRO</filename> and <filename>MACHINE</filename>
68 variables, respectively.
69 </para>
70
71 <para>
72 After parsing of the configuration files, some standard classes are
73 included.
74 The <filename>base.bbclass</filename> file
75 is always included.
76 Other classes that are specified in the configuration using the
77 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
78 variable are also included.
79 BitBake searches for class files in a "classes" subdirectory under
80 the paths in <filename>BBPATH</filename> in the same way as
81 configuration files.
82 </para>
83
84 <para>
85 After classes are included, the variable
86 <filename>BBFILES</filename> is set, usually in
87 <filename>local.conf</filename>, and defines the list of
88 places to search for recipe and append files.
89 Adding extra content to <filename>BBFILES</filename> is best
90 achieved through the use of BitBake layers.
91 </para>
92
93 <para>
94 BitBake parses each recipe and append file located with
95 <filename>BBFILES</filename> and stores the values of various
96 variables into the datastore.
97 In summary, for each recipe and append file pairing, the configuration
98 plus the base class of variables are set, followed by the data in the
99 recipe file itself, followed by any inherit commands
100 that the recipe file might contain.
101 </para>
102
103 <para>
104 Because parsing recipe and append files is a time consuming
105 process, a cache, referred to as the "setscene"
106 is kept to speed up subsequent parsing.
107 The setscene is invalid if the timestamps of a recipe changes,
108 any of the include files change, configuration files change,
109 or class files on which the recipe file depends change.
110 </para>
111 </section>
112
113 <section id='parsing-configuration-files'>
114 <title>Configuration files</title>
115
116 <para>
117 Prior to parsing configuration files, Bitbake looks
118 at certain variables, including:
119 <itemizedlist>
120 <listitem><para><link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link></para></listitem>
121 <listitem><para><link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link></para></listitem>
122 <listitem><para><link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link></para></listitem>
123 <listitem><para><link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link></para></listitem>
124 <listitem><para><link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link></para></listitem>
125 <listitem><para><link linkend='var-PREFERRED_PROVIDERS'><filename>PREFERRED_PROVIDERS</filename></link></para></listitem>
126 </itemizedlist>
127 </para>
128
129 <para>
130 The first kind of metadata in BitBake is configuration metadata.
131 This metadata is global, and therefore affects all packages and
132 tasks that are executed.
133 </para>
134
135 <para>
136 BitBake will first search the current working directory for an
137 optional <filename>conf/bblayers.conf</filename> configuration file.
138 This file is expected to contain a
139 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
140 variable that is a space delimited list of 'layer' directories.
141 For each directory in this list, a <filename>conf/layer.conf</filename>
142 file will be searched for and parsed with the
143 <link linkend='var-LAYERDIR'><filename>LAYERDIR</filename></link>
144 variable being set to the directory where the layer was found.
145 The idea is these files will setup
146 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
147 and other variables correctly for a given build directory automatically
148 for the user.
149 </para>
150
151 <para>
152 BitBake will then expect to find <filename>conf/bitbake.conf</filename>
153 file somewhere in the user specified <filename>BBPATH</filename>.
154 That configuration file generally has include directives to pull
155 in any other metadata (generally files specific to architecture,
156 machine, local and so on).
157 </para>
158
159 <para>
160 Only variable definitions and include directives are allowed
161 in <filename>.conf</filename> files.
162 The following variables include:
163 <itemizedlist>
164 <listitem><para>
165 <link linkend='var-BITBAKE_UI'><filename>BITBAKE_UI</filename></link>
166 </para></listitem>
167 <listitem><para>
168 <link linkend='var-BBDEBUG'><filename>BBDEBUG</filename></link>
169 </para></listitem>
170 <listitem><para>
171 <link linkend='var-MULTI_PROVIDER_WHITELIST'><filename>MULTI_PROVIDER_WHITELIST</filename></link>
172 </para></listitem>
173 <listitem><para>
174 <link linkend='var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></link>
175 </para></listitem>
176 <listitem><para>
177 <filename>BBPKGS</filename>
178 </para></listitem>
179 <listitem><para>
180 <link linkend='var-BB_DEFAULT_TASK'><filename>BB_DEFAULT_TASK</filename></link>
181 </para></listitem>
182 <listitem><para>
183 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
184 </para></listitem>
185 <listitem><para>
186 <link linkend='var-BB_VERBOSE_LOGS'><filename>BB_VERBOSE_LOGS</filename></link>
187 </para></listitem>
188 <listitem><para>
189 <link linkend='var-BB_NICE_LEVEL'><filename>BB_NICE_LEVEL</filename></link>
190 </para></listitem>
191 <listitem><para>
192 <link linkend='var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></link>
193 </para></listitem>
194 <listitem><para>
195 <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link>
196 </para></listitem>
197 <listitem><para>
198 <link linkend='var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></link>
199 </para></listitem>
200 <listitem><para>
201 <link linkend='var-BBINCLUDED'><filename>BBINCLUDED</filename></link>
202 </para></listitem>
203 <listitem><para>
204 <link linkend='var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></link>
205 </para></listitem>
206 <listitem><para>
207 <link linkend='var-BUILDNAME'><filename>BUILDNAME</filename></link>
208 </para></listitem>
209 <listitem><para>
210 <link linkend='var-BBMASK'><filename>BBMASK</filename></link>
211 </para></listitem>
212 </itemizedlist>
213 </para>
214
215 <section id='layers'>
216 <title>Layers</title>
217
218 <para>
219 Layers allow you to isolate different types of
220 customizations from each other.
221 While you might find it tempting to keep everything in one layer
222 when working on a single project, the more modular you organize
223 your metadata, the easier it is to cope with future changes.
224 </para>
225
226 <para>
227 To illustrate how you can use layers to keep things modular,
228 consider machine customizations.
229 These types of customizations typically reside in a special layer,
230 rather than a general layer, called a Board Specific Package (BSP) Layer.
231 Furthermore, the machine customizations should be isolated from
232 recipes and metadata that support a new GUI environment, for
233 example.
234 This situation gives you a couple of layers: one for the machine
235 configurations and one for the GUI environment.
236 It is important to understand, however, that the BSP layer can still
237 make machine-specific additions to recipes within
238 the GUI environment layer without polluting the GUI layer itself
239 with those machine-specific changes.
240 You can accomplish this through a recipe that is a BitBake append
241 (<filename>.bbappend</filename>) file.
242 </para>
243
244 <para>
245 There are certain variables specific to layers:
246 <itemizedlist>
247 <listitem><para>
248 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
249 </para></listitem>
250 <listitem><para>
251 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link>
252 </para></listitem>
253 </itemizedlist>
254 </para>
255 </section>
256
257 <section id='schedulers'>
258 <title>Schedulers</title>
259
260 <para>
261 Variables specific to scheduling functionality exist:
262 <itemizedlist>
263 <listitem><para>
264 <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
265 </para></listitem>
266 <listitem><para>
267 <link linkend='var-BB_SCHEDULERS'><filename>BB_SCHEDULERS</filename></link>
268 </para></listitem>
269 </itemizedlist>
270 </para>
271 </section>
272 </section>
273
274 <section id='metadata-classes'>
275 <title>Classes</title>
276
277 <para>
278 BitBake's rudimentary inheritance mechanism is accomplished using
279 classes.
280 As briefly mentioned in the metadata introduction, BitBake
281 parses a class when an inherit directive is encountered, and it
282 is located in the <filename>classes</filename> directory
283 relative to the directories in
284 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
285 </para>
286 </section>
287
288 <section id='recipe-bb-files'>
289 <title>Recipe (<filename>.bb</filename>) Files</title>
290
291 <para>
292 Recipe files, which are files that have the
293 <filename>.bb</filename> file extension, are logical units of
294 tasks for execution.
295 Normally, that logical unit is a package that needs to be
296 built.
297 </para>
298
299 <para>
300 BitBake obeys all inter-recipe dependencies.
301 </para>
302
303 <para>
304 Recipe files must reside in locations found in the
305 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
306 variable.
307 </para>
308 </section>
309
310 <section id='append-bbappend-files'>
311 <title>Append (<filename>.bbappend</filename>) Files</title>
312
313 <para>
314 Append files, which are files that have the
315 <filename>.bbappend</filename> file extension, add or
316 extend build information to an existing
317 <link linkend='recipe-bb-files'>recipe file</link>.
318 </para>
319
320 <para>
321 BitBake expects every append file to have a corresponding recipe file.
322 Furthermore, the append file and corresponding recipe file
323 must use the same root filename.
324 The filenames can differ only in the file type suffix used
325 (e.g. <filename>formfactor_0.0.bb</filename> and
326 <filename>formfactor_0.0.bbappend</filename>).
327 </para>
328
329 <para>
330 Information in append files overrides the information in the
331 similarly-named recipe file.
332 </para>
333 </section>
334 </section> 399 </section>
335 400
336 <section id='bitbake-dev-environment'> 401 <section id='configuration-and-compilation-dev-environment'>
337 <title>BitBake</title> 402 <title>Configuration and Compilation</title>
338
339 <para>
340 The OpenEmbedded build system uses BitBake to produce images.
341 BitBake consists of several functional areas.
342 This section takes a closer look at each of those areas.
343 </para>
344
345 <section id='source-fetching-dev-environment'>
346 <title>Source Fetching</title>
347
348 <para>
349 The first stages of building a recipe are to fetch and unpack
350 the source code:
351 <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
352 </para>
353figures/
354 <para>
355 The <filename>do_fetch</filename> and
356 <filename>do_unpack</filename> tasks fetch the source files
357 and unpack them into the work directory.
358 By default, everything is accomplished in the
359 build directory,
360 which has a defined structure.
361 </para>
362
363 <para>
364 Unpacked source files are pointed to by a variable.
365 For example, in the Yocto Project and OpenEmbedded build systems,
366 the <filename>S</filename> variable points to these source files.
367 Each recipe has an area in the Build Directory where the
368 unpacked source code resides.
369 The name of that directory for any given recipe is defined from
370 several different variables.
371 You can see the variables that define these directories
372 by looking at the figure that shows the structure and variables
373 used in the Yocto Project:
374 <itemizedlist>
375 <listitem><para><filename>TMPDIR</filename>
376 </para></listitem>
377 <listitem><para><filename>PACKAGE_ARCH</filename>
378 </para></listitem>
379 <listitem><para><filename>TARGET_OS</filename>
380 </para></listitem>
381 <listitem><para><link linkend='var-PN'><filename>PN</filename></link>
382 </para></listitem>
383 <listitem><para><link linkend='var-PV'><filename>PV</filename></link>
384 </para></listitem>
385 <listitem><para><link linkend='var-PR'><filename>PR</filename></link>
386 </para></listitem>
387 <listitem><para><filename>WORKDIR</filename>
388 </para></listitem>
389 <listitem><para><filename>S</filename>
390 </para></listitem>
391 </itemizedlist>
392 </para>
393
394 <para>
395 Briefly, the <filename>S</filename> directory contains the
396 unpacked source files for a recipe.
397 The <filename>WORKDIR</filename> directory is where all the
398 building goes on for a given recipe.
399 </para>
400 </section>
401
402 <section id='patching-dev-environment'>
403 <title>Patching</title>
404
405 <para>
406 Once source code is fetched and unpacked, BitBake locates
407 patch files and applies them to the source files:
408 <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
409 </para>
410
411 <para>
412 The <filename>do_patch</filename> task processes recipes by
413 using the
414 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
415 variable to locate applicable patch files, which by default
416 are <filename>*.patch</filename> or
417 <filename>*.diff</filename> files, or any file if
418 "apply=yes" is specified for the file in
419 <filename>SRC_URI</filename>.
420 </para>
421
422 <para>
423 BitBake finds and applies multiple patches for a single recipe
424 in the order in which it finds the patches.
425 Patches are applied to the recipe's source files located in the
426 <filename>S</filename> directory.
427 </para>
428
429 <para>
430 For more information on how the source directories are
431 created, see the
432 "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
433 section.
434 </para>
435 </section>
436
437 <section id='configuration-and-compilation-dev-environment'>
438 <title>Configuration and Compilation</title>
439
440 <para>
441 After source code is patched, BitBake executes tasks that
442 configure and compile the source code:
443 <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
444 </para>
445
446 <para>
447 This step in the build process consists of three tasks:
448 <itemizedlist>
449 <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
450 This task configures the source by enabling and
451 disabling any build-time and configuration options for
452 the software being built.
453 Configurations can come from the recipe itself as well
454 as from an inherited class.
455 Additionally, the software itself might configure itself
456 depending on the target for which it is being built.
457 </para>
458
459 <para>The configurations handled by the
460 <filename>do_configure</filename> task are specific
461 to source code configuration for the source code
462 being built by the recipe.</para>
463
464 <para>If you are using the Autotools class
465 (<filename>autotools.bbclass</filename>),
466 you can add additional configuration options by using
467 the <filename>EXTRA_OECONF</filename>
468 variable.
469 For information on how this variable works within
470 that class, see the
471 <filename>meta/classes/autotools.bbclass</filename> file.
472 </para></listitem>
473 <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
474 Once a configuration task has been satisfied, BitBake
475 compiles the source using the
476 <filename>do_compile</filename> task.
477 Compilation occurs in the directory pointed to by the
478 <link linkend='var-B'><filename>B</filename></link>
479 variable.
480 Realize that the <filename>B</filename> directory is, by
481 default, the same as the
482 <filename>S</filename>
483 directory.</para></listitem>
484 <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
485 Once compilation is done, BitBake executes the
486 <filename>do_install</filename> task.
487 This task copies files from the <filename>B</filename>
488 directory and places them in a holding area pointed to
489 by the <filename>D</filename> variable.</para></listitem>
490 </itemizedlist>
491 </para>
492 </section>
493
494 <section id='package-splitting-dev-environment'>
495 <title>Package Splitting</title>
496
497 <para>
498 After source code is configured and compiled, the
499 OpenEmbedded build system analyzes
500 the results and splits the output into packages:
501 <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
502 </para>
503
504 <para>
505 The <filename>do_package</filename> and
506 <filename>do_packagedata</filename> tasks combine to analyze
507 the files found in the <filename>D</filename> directory
508 and split them into subsets based on available packages and
509 files.
510 The analyzing process involves the following as well as other
511 items: splitting out debugging symbols,
512 looking at shared library dependencies between packages,
513 and looking at package relationships.
514 The <filename>do_packagedata</filename> task creates package
515 metadata based on the analysis such that the
516 OpenEmbedded build system can generate the final packages.
517 Working, staged, and intermediate results of the analysis
518 and package splitting process use these areas:
519 <itemizedlist>
520 <listitem><para><filename>PKGD</filename>
521 </para></listitem>
522 <listitem><para><filename>PKGDATA_DIR</filename>
523 </para></listitem>
524 <listitem><para><filename>PKGDESTWORK</filename>
525 </para></listitem>
526 <listitem><para><filename>PKGDEST</filename>
527 </para></listitem>
528 </itemizedlist>
529 The <filename>FILES</filename>
530 variable defines the files that go into each package in
531 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
532 If you want details on how this is accomplished in the Yocto Project
533 for example, you can look at the <filename>package.bbclass</filename>
534 file in a Yocto tree.
535 </para>
536
537 <para>
538 Depending on the type of packages being created (RPM, DEB, or
539 IPK), the <filename>do_package_write_*</filename> task
540 creates the actual packages and places them in the
541 Package Feed area, which is
542 <filename>${TMPDIR}/deploy</filename>.
543 <note>
544 Support for creating feeds directly from the
545 <filename>deploy/*</filename> directories does not exist.
546 Creating such feeds usually requires some kind of feed
547 maintenance mechanism that would upload the new packages
548 into an official package feed (e.g. the
549 Ångström distribution).
550 This functionality is highly distribution-specific
551 and thus is not provided out of the box.
552 </note>
553 </para>
554 </section>
555
556 <section id='image-generation-dev-environment'>
557 <title>Image Generation</title>
558
559 <para>
560 Once packages are split and stored in the Package Feeds area,
561 the OpenEmbedded build system uses BitBake to generate the
562 root filesystem image:
563 <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
564 </para>
565
566 <para>
567 The image generation process consists of several stages and
568 depends on many variables.
569 The <filename>do_rootfs</filename> task uses these key variables
570 to help create the list of packages to actually install:
571 <itemizedlist>
572 <listitem><para><filename>IMAGE_INSTALL</filename>:
573 Lists out the base set of packages to install from
574 the Package Feeds area.</para></listitem>
575 <listitem><para><filename>PACKAGE_EXCLUDE</filename>:
576 Specifies packages that should not be installed.
577 </para></listitem>
578 <listitem><para><filename>IMAGE_FEATURES</filename>:
579 Specifies features to include in the image.
580 Most of these features map to additional packages for
581 installation.</para></listitem>
582 <listitem><para><filename>PACKAGE_CLASSES</filename>:
583 Specifies the package backend to use and consequently
584 helps determine where to locate packages within the
585 Package Feeds area.</para></listitem>
586 <listitem><para><filename>IMAGE_LINGUAS</filename>:
587 Determines the language(s) for which additional
588 language support packages are installed.
589 </para></listitem>
590 </itemizedlist>
591 </para>
592
593 <para>
594 Package installation is under control of the package manager
595 (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or
596 not package management is enabled for the target.
597 At the end of the process, if package management is not
598 enabled for the target, the package manager's data files
599 are deleted from the root filesystem.
600 </para>
601
602 <para>
603 During image generation, the build system attempts to run
604 all post-installation scripts.
605 Any that fail to run on the build host are run on the
606 target when the target system is first booted.
607 If you are using a
608 read-only root filesystem,
609 all the post installation scripts must succeed during the
610 package installation phase since the root filesystem cannot be
611 written into.
612 </para>
613
614 <para>
615 During Optimization, optimizing processes are run across
616 the image.
617 These processes include <filename>mklibs</filename> and
618 <filename>prelink</filename>.
619 The <filename>mklibs</filename> process optimizes the size
620 of the libraries.
621 A <filename>prelink</filename> process optimizes the dynamic
622 linking of shared libraries to reduce start up time of
623 executables.
624 </para>
625
626 <para>
627 Part of the image generation process includes compressing the
628 root filesystem image.
629 Compression is accomplished through several optimization
630 routines designed to reduce the overall size of the image.
631 </para>
632
633 <para>
634 After the root filesystem has been constructed, the image
635 generation process turns everything into an image file or
636 a set of image files.
637 The formats used for the root filesystem depend on the
638 <filename>IMAGE_FSTYPES</filename> variable.
639 </para>
640 403
404 <para>
405 After source code is patched, BitBake executes tasks that
406 configure and compile the source code:
407 <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
408 </para>
409
410 <para>
411 This step in the build process consists of three tasks:
412 <itemizedlist>
413 <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
414 This task configures the source by enabling and
415 disabling any build-time and configuration options for
416 the software being built.
417 Configurations can come from the recipe itself as well
418 as from an inherited class.
419 Additionally, the software itself might configure itself
420 depending on the target for which it is being built.
421 </para>
422
423 <para>The configurations handled by the
424 <filename>do_configure</filename> task are specific
425 to source code configuration for the source code
426 being built by the recipe.</para>
427
428 <para>If you are using the Autotools class
429 (<filename>autotools.bbclass</filename>),
430 you can add additional configuration options by using
431 the <filename>EXTRA_OECONF</filename>
432 variable.
433 For information on how this variable works within
434 that class, see the
435 <filename>meta/classes/autotools.bbclass</filename> file.
436 </para></listitem>
437 <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
438 Once a configuration task has been satisfied, BitBake
439 compiles the source using the
440 <filename>do_compile</filename> task.
441 Compilation occurs in the directory pointed to by the
442 <link linkend='var-B'><filename>B</filename></link>
443 variable.
444 Realize that the <filename>B</filename> directory is, by
445 default, the same as the
446 <filename>S</filename>
447 directory.</para></listitem>
448 <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
449 Once compilation is done, BitBake executes the
450 <filename>do_install</filename> task.
451 This task copies files from the <filename>B</filename>
452 directory and places them in a holding area pointed to
453 by the <filename>D</filename> variable.</para></listitem>
454 </itemizedlist>
455 </para>
456 </section>
457
458 <section id='package-splitting-dev-environment'>
459 <title>Package Splitting</title>
460
461 <para>
462 After source code is configured and compiled, the
463 OpenEmbedded build system analyzes
464 the results and splits the output into packages:
465 <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
466 </para>
467
468 <para>
469 The <filename>do_package</filename> and
470 <filename>do_packagedata</filename> tasks combine to analyze
471 the files found in the <filename>D</filename> directory
472 and split them into subsets based on available packages and
473 files.
474 The analyzing process involves the following as well as other
475 items: splitting out debugging symbols,
476 looking at shared library dependencies between packages,
477 and looking at package relationships.
478 The <filename>do_packagedata</filename> task creates package
479 metadata based on the analysis such that the
480 OpenEmbedded build system can generate the final packages.
481 Working, staged, and intermediate results of the analysis
482 and package splitting process use these areas:
483 <itemizedlist>
484 <listitem><para><filename>PKGD</filename>
485 </para></listitem>
486 <listitem><para><filename>PKGDATA_DIR</filename>
487 </para></listitem>
488 <listitem><para><filename>PKGDESTWORK</filename>
489 </para></listitem>
490 <listitem><para><filename>PKGDEST</filename>
491 </para></listitem>
492 </itemizedlist>
493 The <filename>FILES</filename>
494 variable defines the files that go into each package in
495 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
496 If you want details on how this is accomplished in the Yocto Project
497 for example, you can look at the <filename>package.bbclass</filename>
498 file in a Yocto tree.
499 </para>
500
501 <para>
502 Depending on the type of packages being created (RPM, DEB, or
503 IPK), the <filename>do_package_write_*</filename> task
504 creates the actual packages and places them in the
505 Package Feed area, which is
506 <filename>${TMPDIR}/deploy</filename>.
641 <note> 507 <note>
642 The entire image generation process is run under Pseudo. 508 Support for creating feeds directly from the
643 Running under Pseudo ensures that the files in the root 509 <filename>deploy/*</filename> directories does not exist.
644 filesystem have correct ownership. 510 Creating such feeds usually requires some kind of feed
511 maintenance mechanism that would upload the new packages
512 into an official package feed (e.g. the
513 Ångström distribution).
514 This functionality is highly distribution-specific
515 and thus is not provided out of the box.
645 </note> 516 </note>
646 </section> 517 </para>
647 518 </section>
648 <section id='sdk-generation-dev-environment'> 519
649 <title>SDK Generation</title> 520 <section id='image-generation-dev-environment'>
650 521 <title>Image Generation</title>
651 <para> 522
652 The OpenEmbedded build system uses BitBake to generate the 523 <para>
653 Software Development Kit (SDK) installer script: 524 Once packages are split and stored in the Package Feeds area,
654 <imagedata fileref="figures/sdk-generation.png" align="center" width="6in" depth="7in" /> 525 the OpenEmbedded build system uses BitBake to generate the
655 </para> 526 root filesystem image:
656 527 <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
657 <para> 528 </para>
658 Like image generation, the SDK script process consists of 529
659 several stages and depends on many variables. 530 <para>
660 The <filename>do_populate_sdk</filename> task uses these 531 The image generation process consists of several stages and
661 key variables to help create the list of packages to actually 532 depends on many variables.
662 install. 533 The <filename>do_rootfs</filename> task uses these key variables
663 </para> 534 to help create the list of packages to actually install:
664 535 <itemizedlist>
665 <para> 536 <listitem><para><filename>IMAGE_INSTALL</filename>:
666 The <filename>do_populate_sdk</filename> task handles two 537 Lists out the base set of packages to install from
667 parts: a target part and a host part. 538 the Package Feeds area.</para></listitem>
668 The target part is the part built for the target hardware and 539 <listitem><para><filename>PACKAGE_EXCLUDE</filename>:
669 includes libraries and headers. 540 Specifies packages that should not be installed.
670 The host part is the part of the SDK that runs on the 541 </para></listitem>
671 <filename>SDKMACHINE</filename>. 542 <listitem><para><filename>IMAGE_FEATURES</filename>:
672 </para> 543 Specifies features to include in the image.
673 544 Most of these features map to additional packages for
674 <para> 545 installation.</para></listitem>
675 Once both parts are constructed, the 546 <listitem><para><filename>PACKAGE_CLASSES</filename>:
676 <filename>do_populate_sdk</filename> task performs some cleanup 547 Specifies the package backend to use and consequently
677 on both parts. 548 helps determine where to locate packages within the
678 After the cleanup, the task creates a cross-development 549 Package Feeds area.</para></listitem>
679 environment setup script and any configuration files that 550 <listitem><para><filename>IMAGE_LINGUAS</filename>:
680 might be needed. 551 Determines the language(s) for which additional
681 </para> 552 language support packages are installed.
682 553 </para></listitem>
683 <para> 554 </itemizedlist>
684 The final output of the task is the Cross-development 555 </para>
685 toolchain installation script (<filename>.sh</filename> file), 556
686 which includes the environment setup script. 557 <para>
687 </para> 558 Package installation is under control of the package manager
688 </section> 559 (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or
560 not package management is enabled for the target.
561 At the end of the process, if package management is not
562 enabled for the target, the package manager's data files
563 are deleted from the root filesystem.
564 </para>
565
566 <para>
567 During image generation, the build system attempts to run
568 all post-installation scripts.
569 Any that fail to run on the build host are run on the
570 target when the target system is first booted.
571 If you are using a
572 read-only root filesystem,
573 all the post installation scripts must succeed during the
574 package installation phase since the root filesystem cannot be
575 written into.
576 </para>
577
578 <para>
579 During Optimization, optimizing processes are run across
580 the image.
581 These processes include <filename>mklibs</filename> and
582 <filename>prelink</filename>.
583 The <filename>mklibs</filename> process optimizes the size
584 of the libraries.
585 A <filename>prelink</filename> process optimizes the dynamic
586 linking of shared libraries to reduce start up time of
587 executables.
588 </para>
589
590 <para>
591 Part of the image generation process includes compressing the
592 root filesystem image.
593 Compression is accomplished through several optimization
594 routines designed to reduce the overall size of the image.
595 </para>
596
597 <para>
598 After the root filesystem has been constructed, the image
599 generation process turns everything into an image file or
600 a set of image files.
601 The formats used for the root filesystem depend on the
602 <filename>IMAGE_FSTYPES</filename> variable.
603 </para>
604
605 <note>
606 The entire image generation process is run under Pseudo.
607 Running under Pseudo ensures that the files in the root
608 filesystem have correct ownership.
609 </note>
610 </section>
611
612 <section id='sdk-generation-dev-environment'>
613 <title>SDK Generation</title>
614
615 <para>
616 The OpenEmbedded build system uses BitBake to generate the
617 Software Development Kit (SDK) installer script:
618 <imagedata fileref="figures/sdk-generation.png" align="center" width="6in" depth="7in" />
619 </para>
620
621 <para>
622 Like image generation, the SDK script process consists of
623 several stages and depends on many variables.
624 The <filename>do_populate_sdk</filename> task uses these
625 key variables to help create the list of packages to actually
626 install.
627 </para>
628
629 <para>
630 The <filename>do_populate_sdk</filename> task handles two
631 parts: a target part and a host part.
632 The target part is the part built for the target hardware and
633 includes libraries and headers.
634 The host part is the part of the SDK that runs on the
635 <filename>SDKMACHINE</filename>.
636 </para>
637
638 <para>
639 Once both parts are constructed, the
640 <filename>do_populate_sdk</filename> task performs some cleanup
641 on both parts.
642 After the cleanup, the task creates a cross-development
643 environment setup script and any configuration files that
644 might be needed.
645 </para>
646
647 <para>
648 The final output of the task is the Cross-development
649 toolchain installation script (<filename>.sh</filename> file),
650 which includes the environment setup script.
651 </para>
689 </section> 652 </section>
690</chapter> 653</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-11-11 15:57:57 +0000