diff options
-rw-r--r-- | documentation/poky-ref-manual/extendpoky.xml | 190 |
1 files changed, 95 insertions, 95 deletions
diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml index ad8918dcb8..03546e6d3f 100644 --- a/documentation/poky-ref-manual/extendpoky.xml +++ b/documentation/poky-ref-manual/extendpoky.xml | |||
@@ -5,13 +5,12 @@ | |||
5 | 5 | ||
6 | <title>Extending Poky</title> | 6 | <title>Extending Poky</title> |
7 | <para> | 7 | <para> |
8 | This section provides information about how to extend the functionality | 8 | This chapter provides information about how to extend the functionality |
9 | already present in Poky. | 9 | already present in Poky. |
10 | The section also documents standard tasks such as adding new | 10 | The chapter also documents standard tasks such as adding new |
11 | software packages, extending or customizing images or porting Poky to | 11 | software packages, extending or customizing images or porting Poky to |
12 | new hardware (adding a new machine). | 12 | new hardware (adding a new machine). |
13 | Finally, the section contains advice about how | 13 | Finally, the chapter contains advice about how to make changes to Poky to achieve the best results. |
14 | to make changes to Poky to achieve the best results. | ||
15 | </para> | 14 | </para> |
16 | 15 | ||
17 | <section id='usingpoky-extend-addpkg'> | 16 | <section id='usingpoky-extend-addpkg'> |
@@ -21,7 +20,7 @@ | |||
21 | Writing a recipe means creating a <filename>.bb</filename> file that sets some | 20 | Writing a recipe means creating a <filename>.bb</filename> file that sets some |
22 | variables. | 21 | variables. |
23 | For information on variables that are useful for recipes and for information about recipe naming | 22 | For information on variables that are useful for recipes and for information about recipe naming |
24 | issues, see <link linkend='ref-varlocality-recipe-required'>Recipe Variables - Required</link> | 23 | issues, see the <link linkend='ref-varlocality-recipe-required'>Recipe Variables - Required</link> |
25 | appendix. | 24 | appendix. |
26 | </para> | 25 | </para> |
27 | <para> | 26 | <para> |
@@ -29,7 +28,7 @@ | |||
29 | whether someone else has written one already. | 28 | whether someone else has written one already. |
30 | OpenEmbedded is a good place to look as it has a wider scope and range of packages. | 29 | OpenEmbedded is a good place to look as it has a wider scope and range of packages. |
31 | Because Poky aims to be compatible with OpenEmbedded, most recipes should | 30 | Because Poky aims to be compatible with OpenEmbedded, most recipes should |
32 | just work in Poky. | 31 | simply work in Poky. |
33 | </para> | 32 | </para> |
34 | <para> | 33 | <para> |
35 | For new packages, the simplest way to add a recipe is to base it on a similar | 34 | For new packages, the simplest way to add a recipe is to base it on a similar |
@@ -43,11 +42,11 @@ | |||
43 | Building an application from a single file that is stored locally (e.g. under | 42 | Building an application from a single file that is stored locally (e.g. under |
44 | <filename>files/</filename>) requires a recipe that has the file listed in | 43 | <filename>files/</filename>) requires a recipe that has the file listed in |
45 | the <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. | 44 | the <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. |
46 | Additionally, you need to manually write the <function>do_compile</function> and | 45 | Additionally, you need to manually write the "do_compile" and |
47 | <function>do_install</function> tasks. | 46 | "do_install" tasks. |
48 | The <glossterm><link linkend='var-S'>S</link></glossterm> variable defines the | 47 | The <glossterm><link linkend='var-S'>S</link></glossterm> variable defines the |
49 | directory containing the source code, which is set to <glossterm><link linkend='var-WORKDIR'> | 48 | directory containing the source code, which is set to <glossterm><link linkend='var-WORKDIR'> |
50 | WORKDIR</link></glossterm> in this case - the directory BitBake uses for the build. | 49 | WORKDIR</link></glossterm> in this case - the directory Bitbake uses for the build. |
51 | </para> | 50 | </para> |
52 | <programlisting> | 51 | <programlisting> |
53 | DESCRIPTION = "Simple helloworld application" | 52 | DESCRIPTION = "Simple helloworld application" |
@@ -82,13 +81,13 @@ do_install() { | |||
82 | Applications that use autotools such as <filename>autoconf</filename> and | 81 | Applications that use autotools such as <filename>autoconf</filename> and |
83 | <filename>automake</filename> require a recipe that has a source archive listed in | 82 | <filename>automake</filename> require a recipe that has a source archive listed in |
84 | <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> and | 83 | <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> and |
85 | <filename>also inherits autotools</filename>, which instructs BitBake to use the | 84 | <filename>also inherits autotools</filename>, which instructs Bitbake to use the |
86 | <filename>autotools.bbclass</filename> containing the definitions of all the steps | 85 | <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps |
87 | needed to build an autotooled application. | 86 | needed to build an autotooled application. |
88 | The result of the build is automatically packaged. | 87 | The result of the build is automatically packaged. |
89 | And, if the application uses NLS for localization, packages with local information are | 88 | And, if the application uses NLS for localization, packages with local information are |
90 | generated (one package per language). | 89 | generated (one package per language). |
91 | Following is one example (<filename>hello_2.2.bb</filename>) | 90 | Following is one example: (<filename>hello_2.2.bb</filename>) |
92 | </para> | 91 | </para> |
93 | <programlisting> | 92 | <programlisting> |
94 | DESCRIPTION = "GNU Helloworld application" | 93 | DESCRIPTION = "GNU Helloworld application" |
@@ -102,9 +101,9 @@ SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" | |||
102 | inherit autotools gettext | 101 | inherit autotools gettext |
103 | </programlisting> | 102 | </programlisting> |
104 | <para> | 103 | <para> |
105 | <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link> | 104 | The variable <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link> |
106 | </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'> | 105 | </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'> |
107 | track source license change</link>. | 106 | track source license changes</link>. |
108 | You can quickly create autotool-based recipes in a manner similar to the previous example. | 107 | You can quickly create autotool-based recipes in a manner similar to the previous example. |
109 | </para> | 108 | </para> |
110 | 109 | ||
@@ -115,13 +114,13 @@ inherit autotools gettext | |||
115 | <para> | 114 | <para> |
116 | Applications that use GNU <filename>make</filename> also require a recipe that has | 115 | Applications that use GNU <filename>make</filename> also require a recipe that has |
117 | the source archive listed in <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. | 116 | the source archive listed in <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. |
118 | You do not need to add a <function>do_compile</function> step since by default BitBake | 117 | You do not need to add a <function>do_compile</function> step since by default Bitbake |
119 | starts the <filename>make</filename> command to compile the application. | 118 | starts the <filename>make</filename> command to compile the application. |
120 | If you need additional <filename>make</filename> options you should store them in the | 119 | If you need additional <filename>make</filename> options you should store them in the |
121 | <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable. | 120 | <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable. |
122 | Bitbake passes these options into the <filename>make</filename> GNU invocation. | 121 | Bitbake passes these options into the <filename>make</filename> GNU invocation. |
123 | Note that a <function>do_install</function> task is still required. | 122 | Note that a "do_install" task is still required. |
124 | Otherwise BitBake runs an empty <function>do_install</function> task by default. | 123 | Otherwise Bitbake runs an empty "do_install" task by default. |
125 | </para> | 124 | </para> |
126 | <para> | 125 | <para> |
127 | Some applications might require extra parameters to be passed to the compiler. | 126 | Some applications might require extra parameters to be passed to the compiler. |
@@ -134,7 +133,7 @@ inherit autotools gettext | |||
134 | CFLAGS_prepend = "-I ${S}/include " | 133 | CFLAGS_prepend = "-I ${S}/include " |
135 | </programlisting> | 134 | </programlisting> |
136 | <para> | 135 | <para> |
137 | In the following example <filename>mtd-utils</filename> is a Makefile-based package: | 136 | In the following example <filename>mtd-utils</filename> is a makefile-based package: |
138 | </para> | 137 | </para> |
139 | <programlisting> | 138 | <programlisting> |
140 | DESCRIPTION = "Tools for managing memory technology devices." | 139 | DESCRIPTION = "Tools for managing memory technology devices." |
@@ -171,7 +170,7 @@ do_install () { | |||
171 | </para> | 170 | </para> |
172 | <para> | 171 | <para> |
173 | Following is an example that uses the "libXpm" recipe (<filename>libxpm_3.5.7.bb</filename>). | 172 | Following is an example that uses the "libXpm" recipe (<filename>libxpm_3.5.7.bb</filename>). |
174 | By default, the "libXpm" recipe generates a single package containing the library, along | 173 | By default, the "libXpm" recipe generates a single package that contains the library along |
175 | with a few binaries. | 174 | with a few binaries. |
176 | You can modify the recipe to split the binaries into separate packages: | 175 | You can modify the recipe to split the binaries into separate packages: |
177 | </para> | 176 | </para> |
@@ -198,8 +197,8 @@ FILES_sxpm = "${bindir}/sxpm" | |||
198 | package by default, we prepend the <glossterm><link linkend='var-PACKAGES'>PACKAGES</link> | 197 | package by default, we prepend the <glossterm><link linkend='var-PACKAGES'>PACKAGES</link> |
199 | </glossterm> variable so additional package names are added to the start of list. | 198 | </glossterm> variable so additional package names are added to the start of list. |
200 | This results in the extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_* | 199 | This results in the extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_* |
201 | variables then containing information defining which files and | 200 | variables then containing information that define which files and |
202 | directories go into which package. | 201 | directories go into which packages. |
203 | Files included by earlier packages are skipped by latter packages. | 202 | Files included by earlier packages are skipped by latter packages. |
204 | Thus, the main <glossterm><link linkend='var-PN'>PN</link></glossterm> package does not include | 203 | Thus, the main <glossterm><link linkend='var-PN'>PN</link></glossterm> package does not include |
205 | the above listed files. | 204 | the above listed files. |
@@ -234,7 +233,7 @@ pkg_postinst_PACKAGENAME () { | |||
234 | Sometimes it is necessary for the execution of a post-installation | 233 | Sometimes it is necessary for the execution of a post-installation |
235 | script to be delayed until the first boot. | 234 | script to be delayed until the first boot. |
236 | For example, the script might need to be executed on the device itself. | 235 | For example, the script might need to be executed on the device itself. |
237 | To delay script execution until boot time, use the following structure for the | 236 | To delay script execution until boot time, use the following structure in the |
238 | post-installation script: | 237 | post-installation script: |
239 | </para> | 238 | </para> |
240 | <programlisting> | 239 | <programlisting> |
@@ -259,8 +258,8 @@ fi | |||
259 | <section id='usingpoky-extend-customimage'> | 258 | <section id='usingpoky-extend-customimage'> |
260 | <title>Customizing Images</title> | 259 | <title>Customizing Images</title> |
261 | <para> | 260 | <para> |
262 | You can customize Poky images to satisfy particular requirements. | 261 | You can customize Poky images to satisfy particular requirements. |
263 | This section describes several methods and provides guidelines for each. | 262 | This section describes several methods and provides guidelines for each. |
264 | </para> | 263 | </para> |
265 | 264 | ||
266 | <section id='usingpoky-extend-customimage-custombb'> | 265 | <section id='usingpoky-extend-customimage-custombb'> |
@@ -344,8 +343,8 @@ RRECOMMENDS_task-custom-tools = "\ | |||
344 | <filename>task-custom-tools</filename>. | 343 | <filename>task-custom-tools</filename>. |
345 | To build an image using these task packages, you need to add | 344 | To build an image using these task packages, you need to add |
346 | "task-custom-apps" and/or "task-custom-tools" to <glossterm><link | 345 | "task-custom-apps" and/or "task-custom-tools" to <glossterm><link |
347 | linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> or other forms | 346 | linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm>. |
348 | of image dependencies as described in other areas of this section. | 347 | For other forms of image dependencies see the other areas of this section. |
349 | </para> | 348 | </para> |
350 | </section> | 349 | </section> |
351 | 350 | ||
@@ -359,7 +358,7 @@ RRECOMMENDS_task-custom-tools = "\ | |||
359 | <filename>meta/classes/poky-image.bbclass</filename>, which shows how poky achieves this. | 358 | <filename>meta/classes/poky-image.bbclass</filename>, which shows how poky achieves this. |
360 | In summary, the file looks at the contents of the | 359 | In summary, the file looks at the contents of the |
361 | <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> | 360 | <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> |
362 | variable and then maps them into a set of tasks or packages. | 361 | variable and then maps that into a set of tasks or packages. |
363 | Based on this information the <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link> | 362 | Based on this information the <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link> |
364 | </glossterm> variable is generated automatically. | 363 | </glossterm> variable is generated automatically. |
365 | Users can add extra features by extending the class or creating a custom class for use | 364 | Users can add extra features by extending the class or creating a custom class for use |
@@ -370,12 +369,12 @@ RRECOMMENDS_task-custom-tools = "\ | |||
370 | <section id='usingpoky-extend-customimage-localconf'> | 369 | <section id='usingpoky-extend-customimage-localconf'> |
371 | <title>Customizing Images Using local.conf</title> | 370 | <title>Customizing Images Using local.conf</title> |
372 | <para> | 371 | <para> |
373 | It is possible to customize image contents by abusing variables used by distribution | 372 | It is possible to customize image contents by using variables used by distribution |
374 | maintainers in local.conf. | 373 | maintainers in the <filename>local.conf</filename>. |
375 | This method only allows the addition of packages and is not recommended. | 374 | This method only allows the addition of packages and is not recommended. |
376 | </para> | 375 | </para> |
377 | <para> | 376 | <para> |
378 | For example, to add the "strace" package into the image the you would add this to the | 377 | For example, to add the "strace" package into the image you would add this package to the |
379 | <filename>local.conf</filename> file: | 378 | <filename>local.conf</filename> file: |
380 | </para> | 379 | </para> |
381 | <programlisting> | 380 | <programlisting> |
@@ -387,18 +386,18 @@ DISTRO_EXTRA_RDEPENDS += "strace" | |||
387 | distribution maintainers, adding packages using this method is not as simple as adding | 386 | distribution maintainers, adding packages using this method is not as simple as adding |
388 | them using a custom <filename>.bb</filename> file. | 387 | them using a custom <filename>.bb</filename> file. |
389 | Using the <filename>local.conf</filename> file method could result in some packages | 388 | Using the <filename>local.conf</filename> file method could result in some packages |
390 | requiring recreation. | 389 | needing to be recreated. |
391 | For example, if packages were previously created and the image was rebuilt then the packages | 390 | For example, if packages were previously created and the image was rebuilt then the packages |
392 | would need to be recreated. | 391 | would need to be recreated. |
393 | </para> | 392 | </para> |
394 | <para> | 393 | <para> |
395 | Cleaning task-* packages is required because they use the | 394 | Cleaning task-* packages are required because they use the |
396 | <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'> | 395 | <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'> |
397 | DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. | 396 | DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. |
398 | You do not have to build them by hand because Poky images depend on the packages they contain. | 397 | You do not have to build them by hand because Poky images depend on the packages they contain. |
399 | This means dependencies are automatically built when the image builds. | 398 | This means dependencies are automatically built when the image builds. |
400 | For this reason we don't use the "rebuild" task. | 399 | For this reason we don't use the "rebuild" task. |
401 | In this case the "rebuild" task does does not care about | 400 | In this case the "rebuild" task does not care about |
402 | dependencies - it only rebuilds the specified package. | 401 | dependencies - it only rebuilds the specified package. |
403 | </para> | 402 | </para> |
404 | <programlisting> | 403 | <programlisting> |
@@ -416,24 +415,23 @@ $ bitbake poky-image-sato | |||
416 | This section provides information that gives you an idea of the changes you must make. | 415 | This section provides information that gives you an idea of the changes you must make. |
417 | The information covers adding machines similar to those Poky already supports. | 416 | The information covers adding machines similar to those Poky already supports. |
418 | Although well within the capabilities of Poky, adding a totally new architecture might require | 417 | Although well within the capabilities of Poky, adding a totally new architecture might require |
419 | changes to <filename>gcc/glibc</filename> and to the site information. | 418 | changes to <filename>gcc/glibc</filename> and to the site information, which is |
420 | Consequently, the information is beyond the scope of this manual. | 419 | beyond the scope of this manual. |
421 | </para> | 420 | </para> |
422 | 421 | ||
423 | <section id="platdev-newmachine-conffile"> | 422 | <section id="platdev-newmachine-conffile"> |
424 | <title>Adding the Machine Configuration File</title> | 423 | <title>Adding the Machine Configuration File</title> |
425 | <para> | 424 | <para> |
426 | To add a machine configuration you need to add a <filename>.conf</filename> file | 425 | To add a machine configuration you need to add a <filename>.conf</filename> file |
427 | with details of the device being added to <filename>conf/machine/</filename>. | 426 | with details of the device being added to the <filename>conf/machine/</filename> file. |
428 | The name of the file determines the name Poky uses to reference the new machine. | 427 | The name of the file determines the name Poky uses to reference the new machine. |
429 | </para> | 428 | </para> |
430 | <para> | 429 | <para> |
431 | The most important variables to set in this file are <glossterm> | 430 | The most important variables to set in this file are <glossterm> |
432 | <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm> | 431 | <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm> (e.g. "arm"), |
433 | (e.g. "arm"), <glossterm><link linkend='var-PREFERRED_PROVIDER'> | 432 | <glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm>_virtual/kernel |
434 | PREFERRED_PROVIDER</link></glossterm>_virtual/kernel (see below) and | 433 | (see below) and <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></glossterm> |
435 | <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES | 434 | (e.g. "kernel26 apm screen wifi"). |
436 | </link></glossterm> (e.g. "kernel26 apm screen wifi"). | ||
437 | You might also need other variables like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE | 435 | You might also need other variables like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE |
438 | </link></glossterm> (e.g. "115200 ttyS0"), <glossterm> | 436 | </link></glossterm> (e.g. "115200 ttyS0"), <glossterm> |
439 | <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link> | 437 | <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link> |
@@ -461,7 +459,7 @@ $ bitbake poky-image-sato | |||
461 | <link linkend='var-S'>S</link></glossterm> to point at the source code. | 459 | <link linkend='var-S'>S</link></glossterm> to point at the source code. |
462 | You need to create a "configure" task that configures the unpacked kernel with a defconfig. | 460 | You need to create a "configure" task that configures the unpacked kernel with a defconfig. |
463 | You can do this by using a <filename>make defconfig</filename> command or | 461 | You can do this by using a <filename>make defconfig</filename> command or |
464 | more commonly by copying in a suitable defconfig and and then running | 462 | more commonly by copying in a suitable <filename>defconfig</filename> file and and then running |
465 | <filename>make oldconfig</filename>. | 463 | <filename>make oldconfig</filename>. |
466 | By making use of "inherit kernel" and potentially some of the | 464 | By making use of "inherit kernel" and potentially some of the |
467 | <filename>linux-*.inc</filename> files, most other functionality is | 465 | <filename>linux-*.inc</filename> files, most other functionality is |
@@ -486,12 +484,12 @@ COMPATIBLE_MACHINE = '(qemux86|qemumips)' | |||
486 | <title>Adding a Formfactor Configuration File</title> | 484 | <title>Adding a Formfactor Configuration File</title> |
487 | <para> | 485 | <para> |
488 | A formfactor configuration file provides information about the | 486 | A formfactor configuration file provides information about the |
489 | target hardware on which Poky is running, and that Poky cannot | 487 | target hardware on which Poky is running, and information that Poky cannot |
490 | obtain from other sources such as the kernel. | 488 | obtain from other sources such as the kernel. |
491 | Some examples of information contained in a formfactor configuration file include | 489 | Some examples of information contained in a formfactor configuration file include |
492 | framebuffer orientation, whether or not the system has a keyboard, | 490 | framebuffer orientation, whether or not the system has a keyboard, |
493 | the positioning of the keyboard in relation to the screen, and | 491 | the positioning of the keyboard in relation to the screen, and |
494 | screen resolution. | 492 | the screen resolution. |
495 | </para> | 493 | </para> |
496 | <para> | 494 | <para> |
497 | Reasonable defaults are used in most cases, but if customization is | 495 | Reasonable defaults are used in most cases, but if customization is |
@@ -545,7 +543,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
545 | <para> | 543 | <para> |
546 | The Poky tree includes several additional layers such as meta-emenlow and meta-extras | 544 | The Poky tree includes several additional layers such as meta-emenlow and meta-extras |
547 | that demonstrate this functionality. | 545 | that demonstrate this functionality. |
548 | The meta-emenlow layer is an example layer that by default is enabled. | 546 | The meta-emenlow layer is an example layer that, by default, is enabled. |
549 | However, the meta-extras repository is not enabled by default. | 547 | However, the meta-extras repository is not enabled by default. |
550 | It is easy though to enable any layer. | 548 | It is easy though to enable any layer. |
551 | You simply add the layer's path to the | 549 | You simply add the layer's path to the |
@@ -554,16 +552,16 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
554 | The following example shows how to enable meta-extras in the Poky build: | 552 | The following example shows how to enable meta-extras in the Poky build: |
555 | </para> | 553 | </para> |
556 | <para> | 554 | <para> |
557 | <literallayout class='monospaced'> | 555 | <programlisting> |
558 | LCONF_VERSION = "1" | 556 | LCONF_VERSION = "1" |
559 | 557 | ||
560 | BBFILES ?= "" | 558 | BBFILES ?= "" |
561 | BBLAYERS = " \ | 559 | BBLAYERS = " \ |
562 | /path/to/poky/meta \ | 560 | /path/to/poky/meta \ |
563 | /path/to/poky/meta-emenlow \ | 561 | /path/to/poky/meta-emenlow \ |
564 | /path/to/poky/meta-extras \ | 562 | /path/to/poky/meta-extras \ |
565 | " | 563 | " |
566 | </literallayout> | 564 | </programlisting> |
567 | </para> | 565 | </para> |
568 | 566 | ||
569 | <para> | 567 | <para> |
@@ -575,18 +573,18 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
575 | </para> | 573 | </para> |
576 | <para> | 574 | <para> |
577 | The <filename>meta-emenlow/conf/layer.conf</filename> file demonstrates the required syntax: | 575 | The <filename>meta-emenlow/conf/layer.conf</filename> file demonstrates the required syntax: |
578 | <literallayout class='monospaced'> | 576 | <programlisting> |
579 | # We have a conf and classes directory, add to BBPATH | 577 | # We have a conf and classes directory, add to BBPATH |
580 | BBPATH := "${BBPATH}:${LAYERDIR}" | 578 | BBPATH := "${BBPATH}:${LAYERDIR}" |
581 | 579 | ||
582 | # We have a recipes directory containing both .bb and .bbappend files, add to BBFILES | 580 | # We have a recipes directory containing both .bb and .bbappend files, add to BBFILES |
583 | BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ | 581 | BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ |
584 | ${LAYERDIR}/recipes/*/*.bbappend" | 582 | ${LAYERDIR}/recipes/*/*.bbappend" |
585 | 583 | ||
586 | BBFILE_COLLECTIONS += "emenlow" | 584 | BBFILE_COLLECTIONS += "emenlow" |
587 | BBFILE_PATTERN_emenlow := "^${LAYERDIR}/" | 585 | BBFILE_PATTERN_emenlow := "^${LAYERDIR}/" |
588 | BBFILE_PRIORITY_emenlow = "6" | 586 | BBFILE_PRIORITY_emenlow = "6" |
589 | </literallayout> | 587 | </programlisting> |
590 | </para> | 588 | </para> |
591 | <para> | 589 | <para> |
592 | In the previous example, the recipes for the layers are added to | 590 | In the previous example, the recipes for the layers are added to |
@@ -598,7 +596,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
598 | a particular layer, in this case by using the base pathname. | 596 | a particular layer, in this case by using the base pathname. |
599 | The <glossterm><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></glossterm> variable | 597 | The <glossterm><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></glossterm> variable |
600 | then assigns different priorities to the files in different layers. | 598 | then assigns different priorities to the files in different layers. |
601 | This technique useful in situations where the same package might appear in multiple | 599 | Applying priorities is useful in situations where the same package might appear in multiple |
602 | layers and allows you to choose what layer should take precedence. | 600 | layers and allows you to choose what layer should take precedence. |
603 | </para> | 601 | </para> |
604 | <para> | 602 | <para> |
@@ -637,11 +635,14 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
637 | revision control system. | 635 | revision control system. |
638 | Because some simple practices can significantly improve usability, policy for committing changes | 636 | Because some simple practices can significantly improve usability, policy for committing changes |
639 | is important. | 637 | is important. |
638 | It helps to use a consistent documentation style when committing changes. | ||
639 | We have found the following style works well. | ||
640 | </para> | ||
641 | <para> | ||
640 | Following are suggestions for committing changes to the Poky core: | 642 | Following are suggestions for committing changes to the Poky core: |
641 | </para> | 643 | </para> |
644 | |||
642 | <para> | 645 | <para> |
643 | It helps to use a consistent documentation style when committing changes. | ||
644 | We have found the following style works well. | ||
645 | <itemizedlist> | 646 | <itemizedlist> |
646 | <listitem><para>The first line of the commit summarizes the change and begins with the | 647 | <listitem><para>The first line of the commit summarizes the change and begins with the |
647 | name of the affected package or packages. | 648 | name of the affected package or packages. |
@@ -680,10 +681,10 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
680 | <para> | 681 | <para> |
681 | If a committed change results in changing the package output | 682 | If a committed change results in changing the package output |
682 | then the value of the <glossterm><link linkend='var-PR'>PR</link> | 683 | then the value of the <glossterm><link linkend='var-PR'>PR</link> |
683 | </glossterm> variable needs to be increased ('bumped') as part of that commit. | 684 | </glossterm> variable needs to be increased (or 'bumped') as part of that commit. |
684 | This means that for new recipes you be sure to add the PR variable and set its initial value | 685 | This means that for new recipes you must be sure to add the PR variable and set its initial value |
685 | equal to "r0". | 686 | equal to "r0". |
686 | Not initially defining PR makes makes it easy to miss when you bump a package. | 687 | Not initially defining PR makes it easy to miss when you bump a package. |
687 | Note that you can only use integer values for the PR variable. | 688 | Note that you can only use integer values for the PR variable. |
688 | </para> | 689 | </para> |
689 | <para> | 690 | <para> |
@@ -691,7 +692,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
691 | linkend='var-PV'>PV</link></glossterm>) and PR variables should be reset to "r0". | 692 | linkend='var-PV'>PV</link></glossterm>) and PR variables should be reset to "r0". |
692 | </para> | 693 | </para> |
693 | <para> | 694 | <para> |
694 | Usually a package version only increases. | 695 | Usually, version increases occur only to packages. |
695 | However, if for some reason PV changes but does not increase, you can increase the | 696 | However, if for some reason PV changes but does not increase, you can increase the |
696 | <glossterm><link linkend='var-PE'>PE</link></glossterm> variable (Package Epoch). | 697 | <glossterm><link linkend='var-PE'>PE</link></glossterm> variable (Package Epoch). |
697 | The PE variable defaults to '0'. | 698 | The PE variable defaults to '0'. |
@@ -718,7 +719,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
718 | <section id="usingpoky-changes-collaborate"> | 719 | <section id="usingpoky-changes-collaborate"> |
719 | <title>Using Poky in a Team Environment</title> | 720 | <title>Using Poky in a Team Environment</title> |
720 | <para> | 721 | <para> |
721 | It may not be immediately clear how you can use Poky in a team environment, | 722 | It might not be immediately clear how you can use Poky in a team environment, |
722 | or scale it for a large team of developers. | 723 | or scale it for a large team of developers. |
723 | The specifics of any situation determine the best solution. | 724 | The specifics of any situation determine the best solution. |
724 | Granted that Poky offers immense flexibility regarding this, practices do exist | 725 | Granted that Poky offers immense flexibility regarding this, practices do exist |
@@ -728,7 +729,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
728 | The core component of any development effort with Poky is often an | 729 | The core component of any development effort with Poky is often an |
729 | automated build testing framework and an image generation process. | 730 | automated build testing framework and an image generation process. |
730 | You can use these core components to check that the metadata is buildable, | 731 | You can use these core components to check that the metadata is buildable, |
731 | highlight when commits break the builds, and provide up-to-date images that | 732 | highlight when commits break the build, and provide up-to-date images that |
732 | allow people to test the end result and use it as a base platform for further | 733 | allow people to test the end result and use it as a base platform for further |
733 | development. | 734 | development. |
734 | Experience shows that buildbot is a good fit for this role. | 735 | Experience shows that buildbot is a good fit for this role. |
@@ -747,7 +748,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
747 | </para> | 748 | </para> |
748 | <para> | 749 | <para> |
749 | Full builds build and test everything from the ground up. | 750 | Full builds build and test everything from the ground up. |
750 | They usually happen at preset times like during the night when the machine | 751 | They usually happen at predetermined times like during the night when the machine |
751 | load is low. | 752 | load is low. |
752 | </para> | 753 | </para> |
753 | <para> | 754 | <para> |
@@ -768,7 +769,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
768 | Of course circumstances will be different in each case. | 769 | Of course circumstances will be different in each case. |
769 | However, this situation reveals one of Poky's advantages - the system itself does not | 770 | However, this situation reveals one of Poky's advantages - the system itself does not |
770 | force any particular policy on users, unlike a lot of build systems. | 771 | force any particular policy on users, unlike a lot of build systems. |
771 | The system allows the best policy to be chosen for the given circumstances. | 772 | The system allows the best policies to be chosen for the given circumstances. |
772 | </para> | 773 | </para> |
773 | </section> | 774 | </section> |
774 | 775 | ||
@@ -797,7 +798,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
797 | Although Poky is usually used to build software, you can use it to modify software. | 798 | Although Poky is usually used to build software, you can use it to modify software. |
798 | </para> | 799 | </para> |
799 | <para> | 800 | <para> |
800 | During building, source is available in the | 801 | During a build, source is available in the |
801 | <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory. | 802 | <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory. |
802 | The actual location depends on the type of package and the architecture of the target device. | 803 | The actual location depends on the type of package and the architecture of the target device. |
803 | For a standard recipe not related to | 804 | For a standard recipe not related to |
@@ -811,7 +812,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
811 | <para> | 812 | <para> |
812 | Be sure the package recipe sets the | 813 | Be sure the package recipe sets the |
813 | <glossterm><link linkend='var-S'>S</link></glossterm> variable to something | 814 | <glossterm><link linkend='var-S'>S</link></glossterm> variable to something |
814 | other than standard <filename>WORKDIR/PN-PV/</filename> value. | 815 | other than the standard <filename>WORKDIR/PN-PV/</filename> value. |
815 | </para> | 816 | </para> |
816 | </tip> | 817 | </tip> |
817 | <para> | 818 | <para> |
@@ -820,9 +821,9 @@ DISPLAY_SUBPIXEL_ORDER=vrgb | |||
820 | following example: | 821 | following example: |
821 | </para> | 822 | </para> |
822 | 823 | ||
823 | <programlisting> | 824 | <literallayout class='monospaced'> |
824 | bitbake -c compile -f NAME_OF_PACKAGE | 825 | $ bitbake -c compile -f NAME_OF_PACKAGE |
825 | </programlisting> | 826 | </literallayout> |
826 | 827 | ||
827 | <para> | 828 | <para> |
828 | The "-f" or "--force" option forces re-execution of the specified task. | 829 | The "-f" or "--force" option forces re-execution of the specified task. |
@@ -836,28 +837,28 @@ bitbake -c compile -f NAME_OF_PACKAGE | |||
836 | <title>Modifying Package Source Code with quilt</title> | 837 | <title>Modifying Package Source Code with quilt</title> |
837 | <para> | 838 | <para> |
838 | By default Poky uses <ulink url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink> | 839 | By default Poky uses <ulink url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink> |
839 | to manage patches in the <filename>do_patch</filename> task. | 840 | to manage patches in the "do_patch" task. |
840 | This is a powerful tool that you can use to track all modifications to package sources. | 841 | This is a powerful tool that you can use to track all modifications to package sources. |
841 | </para> | 842 | </para> |
842 | <para> | 843 | <para> |
843 | Before modifying source code, it is important to notify quilt so it can track the changes | 844 | Before modifying source code, it is important to notify quilt so it can track the changes |
844 | into the new patch file: | 845 | into the new patch file: |
845 | 846 | ||
846 | <programlisting> | 847 | <literallayout class='monospaced'> |
847 | quilt new NAME-OF-PATCH.patch | 848 | quilt new NAME-OF-PATCH.patch |
848 | </programlisting> | 849 | </literallayout> |
849 | 850 | ||
850 | After notifying quilt, add all modified files into that patch: | 851 | After notifying quilt, add all modified files into that patch: |
851 | <programlisting> | 852 | <literallayout class='monospaced'> |
852 | quilt add file1 file2 file3 | 853 | quilt add file1 file2 file3 |
853 | </programlisting> | 854 | </literallayout> |
854 | 855 | ||
855 | You can now start editing. | 856 | You can now start editing. |
856 | Once you are done editing, you need to use quilt to generate the final patch that | 857 | Once you are done editing, you need to use quilt to generate the final patch that |
857 | will contain all your modifications. | 858 | will contain all your modifications. |
858 | <programlisting> | 859 | <literallayout class='monospaced'> |
859 | quilt refresh | 860 | quilt refresh |
860 | </programlisting> | 861 | </literallayout> |
861 | 862 | ||
862 | You can find the resulting patch file in the | 863 | You can find the resulting patch file in the |
863 | <filename>patches/</filename> subdirectory of the source | 864 | <filename>patches/</filename> subdirectory of the source |
@@ -869,8 +870,8 @@ quilt refresh | |||
869 | SRC_URI += "file://NAME-OF-PATCH.patch" | 870 | SRC_URI += "file://NAME-OF-PATCH.patch" |
870 | </programlisting> | 871 | </programlisting> |
871 | Finally, don't forget to 'bump' the | 872 | Finally, don't forget to 'bump' the |
872 | <glossterm><link linkend='var-PR'>PR</link></glossterm> value in the same recipe. | 873 | <glossterm><link linkend='var-PR'>PR</link></glossterm> value in the same recipe since |
873 | The resulting packages have changed. | 874 | the resulting packages have changed. |
874 | </para> | 875 | </para> |
875 | </section> | 876 | </section> |
876 | 877 | ||
@@ -880,8 +881,7 @@ SRC_URI += "file://NAME-OF-PATCH.patch" | |||
880 | <title>Track License Change</title> | 881 | <title>Track License Change</title> |
881 | <para> | 882 | <para> |
882 | The license of an upstream project might change in the future. | 883 | The license of an upstream project might change in the future. |
883 | To address this situation, Poky uses the | 884 | Poky uses the <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable |
884 | <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable | ||
885 | to track license changes. | 885 | to track license changes. |
886 | </para> | 886 | </para> |
887 | 887 | ||
@@ -940,7 +940,7 @@ LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" | |||
940 | This mismatch triggers a build failure and notifies the developer. | 940 | This mismatch triggers a build failure and notifies the developer. |
941 | Notification allows the developer to review and address the license text changes. | 941 | Notification allows the developer to review and address the license text changes. |
942 | Also note that if a mis-match occurs during the build, the correct md5 | 942 | Also note that if a mis-match occurs during the build, the correct md5 |
943 | checksum is placed in the build log, which can be easily copied to a .bb file. | 943 | checksum is placed in the build log and can be easily copied to a .bb file. |
944 | </para> | 944 | </para> |
945 | <para> | 945 | <para> |
946 | There is no limit to how many files you can specify using the LIC_FILES_CHKSUM variable. | 946 | There is no limit to how many files you can specify using the LIC_FILES_CHKSUM variable. |
@@ -950,7 +950,7 @@ LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" | |||
950 | This practice allow you to just track the "COPYING" file as long as it is kept up to date. | 950 | This practice allow you to just track the "COPYING" file as long as it is kept up to date. |
951 | </para> | 951 | </para> |
952 | <tip> | 952 | <tip> |
953 | If you specify an empty or invalid "md5" parameter, bitback returns an md5 mis-match | 953 | If you specify an empty or invalid "md5" parameter, Bitbake returns an md5 mis-match |
954 | error and displays the correct "md5" parameter value during the build. The correct parameter | 954 | error and displays the correct "md5" parameter value during the build. The correct parameter |
955 | is also captured in the build log. | 955 | is also captured in the build log. |
956 | </tip> | 956 | </tip> |
@@ -966,7 +966,7 @@ LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" | |||
966 | <para> | 966 | <para> |
967 | Sometimes a package name you are using might exist under an alias or as a similarly named | 967 | Sometimes a package name you are using might exist under an alias or as a similarly named |
968 | package in a different distribution. | 968 | package in a different distribution. |
969 | Poky implements a distro_check task that automatically connects to major distributions | 969 | Poky implements a "distro_check" task that automatically connects to major distributions |
970 | and checks for these situations. | 970 | and checks for these situations. |
971 | If the package exists under a different name in a different distribution you get a | 971 | If the package exists under a different name in a different distribution you get a |
972 | distro_check mismatch. | 972 | distro_check mismatch. |
@@ -986,7 +986,7 @@ DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ | |||
986 | </programlisting> | 986 | </programlisting> |
987 | </para> | 987 | </para> |
988 | <para> | 988 | <para> |
989 | If you have more than one distribution alias separate them with a space. | 989 | If you have more than one distribution alias, separate them with a space. |
990 | Note that Poky currently automatically checks the Fedora, OpenSuSE, Debian, Ubuntu, | 990 | Note that Poky currently automatically checks the Fedora, OpenSuSE, Debian, Ubuntu, |
991 | and Mandriva distributions for source package recipes without having to specify them | 991 | and Mandriva distributions for source package recipes without having to specify them |
992 | using the DISTRO_PN_ALIAS variable. | 992 | using the DISTRO_PN_ALIAS variable. |