summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/ref-manual/figures/user-configuration.pngbin23369 -> 23323 bytes
-rw-r--r--documentation/ref-manual/technical-details.xml404
2 files changed, 283 insertions, 121 deletions
diff --git a/documentation/ref-manual/figures/user-configuration.png b/documentation/ref-manual/figures/user-configuration.png
index 2c81dae08c..b4dafe60a2 100644
--- a/documentation/ref-manual/figures/user-configuration.png
+++ b/documentation/ref-manual/figures/user-configuration.png
Binary files differ
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 79d16549c3..664c4f7986 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -222,147 +222,309 @@
222 environment: 222 environment:
223 </para> 223 </para>
224 224
225 <mediaobject> 225 <imagedata fileref="figures/user-configuration.png" align="center" width="6in" depth="3.5in" />
226 <imageobject>
227 <imagedata fileref="figures/user-configuration.png"
228 format="PNG" align='center' scalefit='1' width="100%"/>
229 </imageobject>
230 </mediaobject>
231 226
232 <para> 227 <para>
233 BitBake needs some basic configuration files in order to complete 228 BitBake needs some basic configuration files in order to complete
234 a build. 229 a build.
235 These files are <filename>*.conf</filename> files. 230 These files are <filename>*.conf</filename> files.
236 The minimally necessary ones reside as example files in the 231 The minimally necessary ones reside as example files in the
237 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 232 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
238 For simplicity, this section refers to the Source Directory as 233 For simplicity, this section refers to the Source Directory as
239 the "Poky Directory." 234 the "Poky Directory."
240 <note> 235 <note>
241 Poky is primarily an aggregation of existing repositories and 236 Poky is primarily an aggregation of existing repositories and
242 is not actual canonical upstream source for anything. 237 is not actual canonical upstream source for anything.
243 </note> 238 </note>
244 When you clone the <filename>poky</filename> Git repository or you 239 When you clone the <filename>poky</filename> Git repository or you
245 download and unpack a Yocto Project release, you can set up the 240 download and unpack a Yocto Project release, you can set up the
246 Source Directory to be named anything you want. 241 Source Directory to be named anything you want.
247 Here, though, we will assume that you have a cloned repository that 242 For this discussion, the cloned repository uses the default
248 has the default name <filename>poky</filename>. 243 name <filename>poky</filename>.
249 </para> 244 </para>
250 245
251 <para> 246 <para>
252 The <filename>meta-yocto</filename> layer inside Poky contains 247 The <filename>meta-yocto</filename> layer inside Poky contains
253 a <filename>conf</filename> directory that has example 248 a <filename>conf</filename> directory that has example
254 configuration files. 249 configuration files.
255 These example files are used as a basis for creating actual 250 These example files are used as a basis for creating actual
256 configuration files when you source the build environment 251 configuration files when you source the build environment
257 script <filename>oe-init-build-env</filename>. 252 script <filename>oe-init-build-env</filename>.
258 <note> 253 <note>
259 The <filename>oe-init-build-env</filename> script also exists 254 The <filename>oe-init-build-env</filename> script also exists
260 in the <filename>meta</filename> directory of the OE-Core 255 in the <filename>meta</filename> directory of the OE-Core
261 root directory. 256 root directory.
262 Both scripts look for sample configuration files through 257 Both scripts look for sample configuration files through
263 a <filename>$TEMPLATECONF</filename> variable. 258 a <filename>$TEMPLATECONF</filename> variable.
264 When using the Yocto Project Development Environment, 259 When using the Yocto Project Development Environment,
265 that location resolves to the samples found in the 260 that location resolves to the samples found in the
266 <filename>poky/meta-yocto/conf</filename> directory. 261 <filename>poky/meta-yocto/conf</filename> directory.
267 </note> 262 </note>
268 </para> 263 </para>
269 264
270 <para> 265 <para>
271 When you source the build environment script, it creates a 266 When you source the build environment script, it creates a
272 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 267 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
273 that BitBake uses as the area in which it does all its work 268 if one does not already exist.
274 during builds. 269 BitBake uses the Build Directory for all its work during builds.
275 The Build Directory has a <filename>conf</filename> directory that 270 The Build Directory has a <filename>conf</filename> directory that
276 contains default versions of your <filename>local.conf</filename> 271 contains default versions of your <filename>local.conf</filename>
277 and <filename>bblayers.conf</filename> configuration files. 272 and <filename>bblayers.conf</filename> configuration files.
278 These default configuration files are created by 273 These default configuration files are created by
279 <filename>oe-init-build-env</filename> only if versions of these 274 <filename>oe-init-build-env</filename> only if versions of these
280 files do not already exist in the Build Directory you specify 275 files do not already exist in the Build Directory you specify
281 when you run the script. 276 when you run the script.
282 </para> 277 </para>
278
279 <para>
280 The <filename>local.conf</filename> file provides many
281 basic variables that define your build.
282 Here is a list of a few.
283 To see the default configurations in a <filename>local.conf</filename>
284 file created by the build environment script, see the
285 <filename>local.conf.sample</filename> in the
286 <filename>meta-yocto</filename> layer:
287 <itemizedlist>
288 <listitem><para><emphasis>Parallelism Options:</emphasis>
289 Controlled by the
290 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
291 and
292 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
293 variables.</para></listitem>
294 <listitem><para><emphasis>Target Machine Selection:</emphasis>
295 Controlled by the
296 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
297 variable.</para></listitem>
298 <listitem><para><emphasis>Download Directory:</emphasis>
299 Controlled by the
300 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
301 variable.</para></listitem>
302 <listitem><para><emphasis>Shared State Directory:</emphasis>
303 Controlled by the
304 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
305 variable.</para></listitem>
306 <listitem><para><emphasis>Build Output:</emphasis>
307 Controlled by the
308 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
309 variable.</para></listitem>
310 </itemizedlist>
311 </para>
312
313 <para>
314 The <filename>bblayers.conf</filename> file tells BitBake what
315 layers you want it to consider during the build.
316 The list of layers includes default layers needed by the build
317 system.
318 You have to manually add any custom layers that you have created.
319 You can find more information on working with the
320 <filename>bblayers.conf</filename> file in the
321 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
322 section in the Yocto Project Development Manual.
323 </para>
324
325 <para>
326 The files <filename>site.conf</filename> and
327 <filename>auto.conf</filename> are not created by the environment
328 initialization script.
329 If you want these configuration files, you must create them
330 yourself:
331 <itemizedlist>
332 <listitem><para><emphasis><filename>site.conf</filename>:</emphasis>
333 I don't really know what this does.
334 All I know is that if you want it, you need to hand-create
335 it.
336 I need some information on it.</para></listitem>
337 <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
338 This file is not hand-created.
339 Rather, the file is usually created and written to by
340 an autobuilder.
341 The settings put into the file are typically the same as
342 you would find in the <filename>local.conf</filename>
343 or <filename>site.conf</filename> files.
344 </para></listitem>
345 </itemizedlist>
346 </para>
347
348 <para>
349 You can edit all configuration files to further define
350 the build.
351 This process is represented by the "User Configuration Edits"
352 box in the figure.
353 </para>
354
355 <para>
356 When you launch your build with the
357 <filename>bitbake &lt;target&gt;</filename> command, BitBake
358 draws on the user configurations you have provided in your
359 Build Directory.
360 </para>
361 </section>
362
363 <section id="metadata-machine-configuration-and-policy-configuration">
364 <title>Metadata, Machine Configuration, and Policy Configuration</title>
365
366 <para>
367 The previous section described the user configurations that
368 define the BitBake's global behavior.
369 This section takes a closer look at the layers the build system
370 uses to further control the build.
371 These layers provide Metadata for the software, machine, and
372 policy.
373 </para>
283 374
284 <para> 375 <para>
285 The <filename>local.conf</filename> file provides many 376 In general, three types of layer input exist:
286 basic variables that define your build.
287 Here is a list of a few.
288 To see the default configurations in a <filename>local.conf</filename>
289 file created by the build environment script, see the
290 <filename>local.conf.sample</filename> in the
291 <filename>meta-yocto</filename> layer:
292 <itemizedlist> 377 <itemizedlist>
293 <listitem><para><emphasis>Parallelism Options:</emphasis> 378 <listitem><para><emphasis>Metadata:</emphasis>
294 Controlled by the 379 Software layers contain user-supplied recipe files,
295 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> 380 patches, and append files.
296 and 381 </para></listitem>
297 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link> 382 <listitem><para><emphasis>Machine Configuration:</emphasis>
298 variables.</para></listitem> 383 Board Support Package (BSP) layers provide machine
299 <listitem><para><emphasis>Target Machine Selection:</emphasis> 384 configurations.
300 Controlled by the 385 This type of information is specific to a particular
301 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> 386 target architecture.</para></listitem>
302 variable.</para></listitem> 387 <listitem><para><emphasis>Policy Configuration:</emphasis>
303 <listitem><para><emphasis>Download Directory:</emphasis> 388 Distribution Layers provide top-level or general
304 Controlled by the 389 policies for the image or SDK being built.
305 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link> 390 For example, this layer would dictate whether BitBake
306 variable.</para></listitem> 391 produces RPM or IPK packages.</para></listitem>
307 <listitem><para><emphasis>Shared State Directory:</emphasis>
308 Controlled by the
309 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
310 variable.</para></listitem>
311 <listitem><para><emphasis>Build Output:</emphasis>
312 Controlled by the
313 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
314 variable.</para></listitem>
315 </itemizedlist> 392 </itemizedlist>
316 </para> 393 </para>
317 394
318 <para> 395 <para>
319 The <filename>bblayers.conf</filename> file tells BitBake what 396 The following figure shows an expanded representation of the
320 layers you want it to consider during the build. 397 Metadata, Machine Configuration, and Policy Configuration input
321 The list of layers includes default layers needed by the build 398 boxes of the Yocto Project development environment:
322 system.
323 You have to manually add any custom layers that you have created.
324 You can find more information on working with the
325 <filename>bblayers.conf</filename> file in the
326 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
327 section in the Yocto Project Development Manual.
328 </para> 399 </para>
329 400
401 <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" />
402
330 <para> 403 <para>
331 The files <filename>site.conf</filename> and 404 The Yocto Project has many layers that can be used.
332 <filename>auto.conf</filename> are not created by the environment 405 You can see a web-interface listing of them on the
333 initialization script. 406 <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
334 If you want these configuration files, you must create them 407 page.
335 yourself: 408 The layers are shown at the bottom categorized under
336 <itemizedlist> 409 "Yocto Metadata Layers."
337 <listitem><para><emphasis><filename>site.conf</filename>:</emphasis> 410 These layers are fundamentally a subset of the
338 I don't really know what this does. 411 <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>,
339 All I know is that if you want it, you need to hand-create 412 which shows all layers supported by OpenEmbedded.
340 it.
341 I need some information on it.</para></listitem>
342 <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
343 This file is not hand-created.
344 Rather, the file is usually created and written to by
345 an autobuilder.
346 The settings put into the file are typically the same as
347 you would find in the <filename>local.conf</filename>
348 or <filename>site.conf</filename> files.
349 </para></listitem>
350 </itemizedlist>
351 </para> 413 </para>
352 414
415 <note>
416 Layers exist in the Yocto Project Source Repositories that cannot
417 be found in the OpenEmbedded Metadata Index.
418 These layers are either deprecated or experimental in nature.
419 </note>
420
353 <para> 421 <para>
354 You can edit all configuration files to further define 422 BitBake uses the <filename>bblayers.conf</filename> file that is
355 the build. 423 part of the user configuration to find what layers it should be
356 This process is represented by the "User Configuration Edits" 424 using as part of the build.
357 box in the figure.
358 </para> 425 </para>
359 426
360 <para> 427 <para>
361 When you launch your build with the 428 For more information on layers, see the
362 <filename>bitbake &lt;target&gt;</filename> command, BitBake 429 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
363 draws on the user configurations you have provided in your 430 section in the Yocto Project Development Manual.
364 Build Directory.
365 </para> 431 </para>
432
433 <section id="software-layer">
434 <title>Software Layer</title>
435
436 <para>
437 The software layer provides the Metadata for your source
438 code used during the build.
439 This general layer minimally contains license
440 information; a <filename>README</filename> file; a layer
441 configuration file named <filename>layer.conf</filename>;
442 and recipe files (<filename>.bb</filename>), append files
443 (<filename>.bbappend</filename>), and patches
444 (<filename>.patch</filename>).
445 </para>
446
447 <para>
448 You provide any new recipes that your project needs in the
449 form of recipe files.
450 If you are modifying any existing recipes from other layers,
451 rather than duplicate them here with the modifcations, you can
452 provide a recipe append file that just has the modifications.
453 Patch files are stored in the <filename>files</filename>
454 directory.
455 </para>
456 </section>
457
458 <section id="distro-layer">
459 <title>Distro Layer</title>
460
461 <para>
462 The distribution layer provides policy configurations for your
463 distribution.
464 Best practices dictate that you isolate these types of
465 configurations into their own layer.
466 Metadata you provide in this layer overrides similar settings
467 that BitBake finds in your <filename>local.conf</filename>
468 file in the Build Directory.
469 </para>
470
471 <para>
472 The following list provides some explanation and references
473 for what you typically find in the distribution layer:
474 <itemizedlist>
475 <listitem><para><emphasis>classes:</emphasis>
476 Class files (<filename>.bbclass</filename>) hold
477 common functionality that can be shared among
478 recipes in the distribution.
479 When your recipes inherit a class, they take on the
480 settings and functions for that class.
481 You can read more about class files in the
482 "<link linkend='ref-classes'>Classes</link>" section.
483 </para></listitem>
484 <listitem><para><emphasis>conf:</emphasis>
485 This area holds configuration information for the
486 distribution.
487 Any distribution-wide include files and, of course, the
488 <filename>layer.conf</filename> configuration
489 file that every layer must have.</para></listitem>
490 <listitem><para><emphasis>recipes-core:</emphasis>
491 Recipes and append files that affect common
492 functionality across the distribution.
493 This area also can hold common distribution headers,
494 initialization files, and
495 <filename>defconfig</filename> files for the
496 distribution.</para></listitem>
497 </itemizedlist>
498 </para>
499 </section>
500
501 <section id="bsp-layer">
502 <title>BSP Layer</title>
503
504 <para>
505 The BSP Layer provides machine configurations.
506 Everything in this layer is specific to the machine for which
507 you are building the image or the SDK.
508 BSP Layer's have a structure that is followed if they are
509 considered to be compatible with the Yocto Project.
510 For information on the structure, see the
511 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
512 </para>
513
514 <para>
515 The BSP Layer contains a configuration directory that has
516 configuration files for the machine
517 (<filename>&lt;machine&gt;.conf</filename>) and, of course,
518 the layer (<filename>layer.conf</filename>).
519 </para>
520
521 <para>
522 The remainder of the layer is dedicated to specific recipes
523 by function: bsp, core, graphics, and kernel.
524 Metadata can exist for multiple formfactors, graphics
525 support systems, and so forth.
526 </para>
527 </section>
366 </section> 528 </section>
367</section> 529</section>
368 530