diff options
| -rw-r--r-- | documentation/poky-ref-manual/faq.xml | 181 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/introduction.xml | 100 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/migration.xml | 148 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/poky-ref-manual.xml | 18 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/ref-bitbake.xml | 272 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/ref-classes.xml | 346 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/ref-features.xml | 124 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/ref-images.xml | 66 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/ref-structure.xml | 260 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/ref-variables.xml | 1292 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/ref-varlocality.xml | 8 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/resources.xml | 18 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/technical-details.xml | 434 | ||||
| -rw-r--r-- | documentation/poky-ref-manual/usingpoky.xml | 264 |
14 files changed, 1765 insertions, 1766 deletions
diff --git a/documentation/poky-ref-manual/faq.xml b/documentation/poky-ref-manual/faq.xml index 945c7f19af..176573de28 100644 --- a/documentation/poky-ref-manual/faq.xml +++ b/documentation/poky-ref-manual/faq.xml | |||
| @@ -19,11 +19,11 @@ | |||
| 19 | and BitBake. | 19 | and BitBake. |
| 20 | Thus, the generic term used here for the build system is | 20 | Thus, the generic term used here for the build system is |
| 21 | the "OpenEmbedded build system." | 21 | the "OpenEmbedded build system." |
| 22 | Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with | 22 | Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with |
| 23 | changes always being merged to OE-Core or BitBake first before being pulled back | 23 | changes always being merged to OE-Core or BitBake first before being pulled back |
| 24 | into Poky. | 24 | into Poky. |
| 25 | This practice benefits both projects immediately. | 25 | This practice benefits both projects immediately. |
| 26 | For a fuller description of the term "Poky", see the | 26 | For a fuller description of the term "Poky", see the |
| 27 | <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> term in the Yocto Project | 27 | <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> term in the Yocto Project |
| 28 | Development Manual. | 28 | Development Manual. |
| 29 | </para> | 29 | </para> |
| @@ -47,9 +47,9 @@ | |||
| 47 | </itemizedlist> | 47 | </itemizedlist> |
| 48 | </para> | 48 | </para> |
| 49 | <para> | 49 | <para> |
| 50 | These tarballs are self-contained with all required libraries and should work | 50 | These tarballs are self-contained with all required libraries and should work |
| 51 | on most Linux systems. | 51 | on most Linux systems. |
| 52 | To use the tarballs extract them into the root | 52 | To use the tarballs extract them into the root |
| 53 | directory and run the appropriate command: | 53 | directory and run the appropriate command: |
| 54 | <literallayout class='monospaced'> | 54 | <literallayout class='monospaced'> |
| 55 | $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH | 55 | $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH |
| @@ -72,12 +72,12 @@ | |||
| 72 | <para> | 72 | <para> |
| 73 | There are three areas that help with stability; | 73 | There are three areas that help with stability; |
| 74 | <itemizedlist> | 74 | <itemizedlist> |
| 75 | <listitem><para>The Yocto Project team keeps | 75 | <listitem><para>The Yocto Project team keeps |
| 76 | <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small | 76 | <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small |
| 77 | and focused, containing around 830 recipes as opposed to the thousands | 77 | and focused, containing around 830 recipes as opposed to the thousands |
| 78 | available in other OpenEmbedded community layers. | 78 | available in other OpenEmbedded community layers. |
| 79 | Keeping it small makes it easy to test and maintain.</para></listitem> | 79 | Keeping it small makes it easy to test and maintain.</para></listitem> |
| 80 | <listitem><para>The Yocto Project team runs manual and automated tests | 80 | <listitem><para>The Yocto Project team runs manual and automated tests |
| 81 | using a small, fixed set of reference hardware as well as emulated | 81 | using a small, fixed set of reference hardware as well as emulated |
| 82 | targets.</para></listitem> | 82 | targets.</para></listitem> |
| 83 | <listitem><para>The Yocto Project uses an an autobuilder, | 83 | <listitem><para>The Yocto Project uses an an autobuilder, |
| @@ -100,7 +100,7 @@ | |||
| 100 | <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. | 100 | <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. |
| 101 | </para> | 101 | </para> |
| 102 | <para> | 102 | <para> |
| 103 | Usually, if the board is not completely exotic, adding support in | 103 | Usually, if the board is not completely exotic, adding support in |
| 104 | the Yocto Project is fairly straightforward. | 104 | the Yocto Project is fairly straightforward. |
| 105 | </para> | 105 | </para> |
| 106 | </answer> | 106 | </answer> |
| @@ -115,10 +115,10 @@ | |||
| 115 | <answer> | 115 | <answer> |
| 116 | <para> | 116 | <para> |
| 117 | The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink> | 117 | The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink> |
| 118 | is built using the OpenEmbedded build system. | 118 | is built using the OpenEmbedded build system. |
| 119 | See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink> | 119 | See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink> |
| 120 | website for more information. | 120 | website for more information. |
| 121 | There are a number of pre-production devices using the OpenEmbedded build system | 121 | There are a number of pre-production devices using the OpenEmbedded build system |
| 122 | and the Yocto Project team | 122 | and the Yocto Project team |
| 123 | announces them as soon as they are released. | 123 | announces them as soon as they are released. |
| 124 | </para> | 124 | </para> |
| @@ -133,8 +133,8 @@ | |||
| 133 | </question> | 133 | </question> |
| 134 | <answer> | 134 | <answer> |
| 135 | <para> | 135 | <para> |
| 136 | Because the same set of recipes can be used to create output of various formats, the | 136 | Because the same set of recipes can be used to create output of various formats, the |
| 137 | output of an OpenEmbedded build depends on how it was started. | 137 | output of an OpenEmbedded build depends on how it was started. |
| 138 | Usually, the output is a flashable image ready for the target device. | 138 | Usually, the output is a flashable image ready for the target device. |
| 139 | </para> | 139 | </para> |
| 140 | </answer> | 140 | </answer> |
| @@ -150,7 +150,7 @@ | |||
| 150 | <para> | 150 | <para> |
| 151 | To add a package, you need to create a BitBake recipe. | 151 | To add a package, you need to create a BitBake recipe. |
| 152 | For information on how to add a package, see the section | 152 | For information on how to add a package, see the section |
| 153 | "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg'>Adding a Package</ulink>" | 153 | "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg'>Adding a Package</ulink>" |
| 154 | in the Yocto Project Development Manual. | 154 | in the Yocto Project Development Manual. |
| 155 | </para> | 155 | </para> |
| 156 | </answer> | 156 | </answer> |
| @@ -159,16 +159,16 @@ | |||
| 159 | <qandaentry> | 159 | <qandaentry> |
| 160 | <question> | 160 | <question> |
| 161 | <para> | 161 | <para> |
| 162 | Do I have to reflash my entire board with a new Yocto Project image when recompiling | 162 | Do I have to reflash my entire board with a new Yocto Project image when recompiling |
| 163 | a package? | 163 | a package? |
| 164 | </para> | 164 | </para> |
| 165 | </question> | 165 | </question> |
| 166 | <answer> | 166 | <answer> |
| 167 | <para> | 167 | <para> |
| 168 | The OpenEmbedded build system can build packages in various formats such as | 168 | The OpenEmbedded build system can build packages in various formats such as |
| 169 | <filename>ipk</filename> for <filename>opkg</filename>, | 169 | <filename>ipk</filename> for <filename>opkg</filename>, |
| 170 | Debian package (<filename>.deb</filename>), or RPM. | 170 | Debian package (<filename>.deb</filename>), or RPM. |
| 171 | The packages can then be upgraded using the package tools on the device, much like | 171 | The packages can then be upgraded using the package tools on the device, much like |
| 172 | on a desktop distribution such as Ubuntu or Fedora. | 172 | on a desktop distribution such as Ubuntu or Fedora. |
| 173 | </para> | 173 | </para> |
| 174 | </answer> | 174 | </answer> |
| @@ -182,11 +182,11 @@ | |||
| 182 | </question> | 182 | </question> |
| 183 | <answer> | 183 | <answer> |
| 184 | <para> | 184 | <para> |
| 185 | GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink> | 185 | GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink> |
| 186 | platform targeted at mobile and embedded devices. | 186 | platform targeted at mobile and embedded devices. |
| 187 | The the main difference between GNOME Mobile and standard GNOME is that | 187 | The the main difference between GNOME Mobile and standard GNOME is that |
| 188 | desktop-orientated libraries have been removed, along with deprecated libraries, | 188 | desktop-orientated libraries have been removed, along with deprecated libraries, |
| 189 | creating a much smaller footprint. | 189 | creating a much smaller footprint. |
| 190 | </para> | 190 | </para> |
| 191 | </answer> | 191 | </answer> |
| 192 | </qandaentry> | 192 | </qandaentry> |
| @@ -200,7 +200,7 @@ | |||
| 200 | </question> | 200 | </question> |
| 201 | <answer> | 201 | <answer> |
| 202 | <para> | 202 | <para> |
| 203 | You are probably running the build on an NTFS filesystem. | 203 | You are probably running the build on an NTFS filesystem. |
| 204 | Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead. | 204 | Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead. |
| 205 | </para> | 205 | </para> |
| 206 | </answer> | 206 | </answer> |
| @@ -214,8 +214,8 @@ | |||
| 214 | </question> | 214 | </question> |
| 215 | <answer> | 215 | <answer> |
| 216 | <para> | 216 | <para> |
| 217 | To get the Yocto Project working under RHEL/CentOS 5.1 you need to first | 217 | To get the Yocto Project working under RHEL/CentOS 5.1 you need to first |
| 218 | install some required packages. | 218 | install some required packages. |
| 219 | The standard CentOS packages needed are: | 219 | The standard CentOS packages needed are: |
| 220 | <itemizedlist> | 220 | <itemizedlist> |
| 221 | <listitem><para>"Development tools" (selected during installation)</para></listitem> | 221 | <listitem><para>"Development tools" (selected during installation)</para></listitem> |
| @@ -224,19 +224,19 @@ | |||
| 224 | </itemizedlist> | 224 | </itemizedlist> |
| 225 | On top of these, you need the following external packages: | 225 | On top of these, you need the following external packages: |
| 226 | <itemizedlist> | 226 | <itemizedlist> |
| 227 | <listitem><para><filename>python-sqlite2</filename> from | 227 | <listitem><para><filename>python-sqlite2</filename> from |
| 228 | <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink> | 228 | <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink> |
| 229 | </para></listitem> | 229 | </para></listitem> |
| 230 | <listitem><para><filename>help2man</filename> from | 230 | <listitem><para><filename>help2man</filename> from |
| 231 | <ulink url='http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html'>Karan repository</ulink></para></listitem> | 231 | <ulink url='http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html'>Karan repository</ulink></para></listitem> |
| 232 | </itemizedlist> | 232 | </itemizedlist> |
| 233 | </para> | 233 | </para> |
| 234 | 234 | ||
| 235 | <para> | 235 | <para> |
| 236 | Once these packages are installed, the OpenEmbedded build system will be able | 236 | Once these packages are installed, the OpenEmbedded build system will be able |
| 237 | to build standard images. | 237 | to build standard images. |
| 238 | However, there might be a problem with the QEMU emulator segfaulting. | 238 | However, there might be a problem with the QEMU emulator segfaulting. |
| 239 | You can either disable the generation of binary locales by setting | 239 | You can either disable the generation of binary locales by setting |
| 240 | <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link> | 240 | <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link> |
| 241 | </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename> | 241 | </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename> |
| 242 | from the kernel and rebuilding it since that is the patch that causes the problems with QEMU. | 242 | from the kernel and rebuilding it since that is the patch that causes the problems with QEMU. |
| @@ -247,22 +247,22 @@ | |||
| 247 | <qandaentry> | 247 | <qandaentry> |
| 248 | <question> | 248 | <question> |
| 249 | <para> | 249 | <para> |
| 250 | I see lots of 404 responses for files on | 250 | I see lots of 404 responses for files on |
| 251 | <filename>http://www.yoctoproject.org/sources/*</filename>. Is something wrong? | 251 | <filename>http://www.yoctoproject.org/sources/*</filename>. Is something wrong? |
| 252 | </para> | 252 | </para> |
| 253 | </question> | 253 | </question> |
| 254 | <answer> | 254 | <answer> |
| 255 | <para> | 255 | <para> |
| 256 | Nothing is wrong. | 256 | Nothing is wrong. |
| 257 | The OpenEmbedded build system checks any configured source mirrors before downloading | 257 | The OpenEmbedded build system checks any configured source mirrors before downloading |
| 258 | from the upstream sources. | 258 | from the upstream sources. |
| 259 | The build system does this searching for both source archives and | 259 | The build system does this searching for both source archives and |
| 260 | pre-checked out versions of SCM managed software. | 260 | pre-checked out versions of SCM managed software. |
| 261 | These checks help in large installations because it can reduce load on the SCM servers | 261 | These checks help in large installations because it can reduce load on the SCM servers |
| 262 | themselves. | 262 | themselves. |
| 263 | The address above is one of the default mirrors configured into the | 263 | The address above is one of the default mirrors configured into the |
| 264 | build system. | 264 | build system. |
| 265 | Consequently, if an upstream source disappears, the team | 265 | Consequently, if an upstream source disappears, the team |
| 266 | can place sources there so builds continue to work. | 266 | can place sources there so builds continue to work. |
| 267 | </para> | 267 | </para> |
| 268 | </answer> | 268 | </answer> |
| @@ -271,16 +271,16 @@ | |||
| 271 | <qandaentry> | 271 | <qandaentry> |
| 272 | <question> | 272 | <question> |
| 273 | <para> | 273 | <para> |
| 274 | I have machine-specific data in a package for one machine only but the package is | 274 | I have machine-specific data in a package for one machine only but the package is |
| 275 | being marked as machine-specific in all cases, how do I prevent this? | 275 | being marked as machine-specific in all cases, how do I prevent this? |
| 276 | </para> | 276 | </para> |
| 277 | </question> | 277 | </question> |
| 278 | <answer> | 278 | <answer> |
| 279 | <para> | 279 | <para> |
| 280 | Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link> | 280 | Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link> |
| 281 | </filename> = "0" in the <filename>.bb</filename> file but make sure the package is | 281 | </filename> = "0" in the <filename>.bb</filename> file but make sure the package is |
| 282 | manually marked as | 282 | manually marked as |
| 283 | machine-specific in the case that needs it. | 283 | machine-specific in the case that needs it. |
| 284 | The code that handles <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in <filename>base.bbclass</filename>. | 284 | The code that handles <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in <filename>base.bbclass</filename>. |
| 285 | </para> | 285 | </para> |
| 286 | </answer> | 286 | </answer> |
| @@ -295,9 +295,9 @@ | |||
| 295 | <answer> | 295 | <answer> |
| 296 | <para> | 296 | <para> |
| 297 | Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename> | 297 | Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename> |
| 298 | and you therefore need to specify the proxy settings in a | 298 | and you therefore need to specify the proxy settings in a |
| 299 | <filename>.wgetrc</filename> file in your home directory. | 299 | <filename>.wgetrc</filename> file in your home directory. |
| 300 | Example settings in that file would be | 300 | Example settings in that file would be |
| 301 | <literallayout class='monospaced'> | 301 | <literallayout class='monospaced'> |
| 302 | http_proxy = http://proxy.yoyodyne.com:18023/ | 302 | http_proxy = http://proxy.yoyodyne.com:18023/ |
| 303 | ftp_proxy = http://proxy.yoyodyne.com:18023/ | 303 | ftp_proxy = http://proxy.yoyodyne.com:18023/ |
| @@ -317,10 +317,10 @@ | |||
| 317 | </question> | 317 | </question> |
| 318 | <answer> | 318 | <answer> |
| 319 | <para> | 319 | <para> |
| 320 | The <filename>*-native</filename> targets are designed to run on the system | 320 | The <filename>*-native</filename> targets are designed to run on the system |
| 321 | being used for the build. | 321 | being used for the build. |
| 322 | These are usually tools that are needed to assist the build in some way such as | 322 | These are usually tools that are needed to assist the build in some way such as |
| 323 | <filename>quilt-native</filename>, which is used to apply patches. | 323 | <filename>quilt-native</filename>, which is used to apply patches. |
| 324 | The non-native version is the one that runs on the target device. | 324 | The non-native version is the one that runs on the target device. |
| 325 | </para> | 325 | </para> |
| 326 | </answer> | 326 | </answer> |
| @@ -335,11 +335,11 @@ | |||
| 335 | <answer> | 335 | <answer> |
| 336 | <para> | 336 | <para> |
| 337 | If the same build is failing in totally different and random ways, | 337 | If the same build is failing in totally different and random ways, |
| 338 | the most likely explanation is that either the hardware you're running the | 338 | the most likely explanation is that either the hardware you're running the |
| 339 | build on has some problem, or, if you are running the build under virtualisation, | 339 | build on has some problem, or, if you are running the build under virtualisation, |
| 340 | the virtualisation probably has bugs. | 340 | the virtualisation probably has bugs. |
| 341 | The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and | 341 | The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and |
| 342 | CPU activity and is sensitive to even single bit failures in any of these areas. | 342 | CPU activity and is sensitive to even single bit failures in any of these areas. |
| 343 | True random failures have always been traced back to hardware or virtualisation issues. | 343 | True random failures have always been traced back to hardware or virtualisation issues. |
| 344 | </para> | 344 | </para> |
| 345 | </answer> | 345 | </answer> |
| @@ -356,8 +356,8 @@ | |||
| 356 | This is a difficult question and you need to consult your lawyer for the answer | 356 | This is a difficult question and you need to consult your lawyer for the answer |
| 357 | for your specific case. | 357 | for your specific case. |
| 358 | It is worth bearing in mind that for GPL compliance there needs to be enough | 358 | It is worth bearing in mind that for GPL compliance there needs to be enough |
| 359 | information shipped to allow someone else to rebuild the same end result | 359 | information shipped to allow someone else to rebuild the same end result |
| 360 | you are shipping. | 360 | you are shipping. |
| 361 | This means sharing the source code, any patches applied to it, and also any | 361 | This means sharing the source code, any patches applied to it, and also any |
| 362 | configuration information about how that package was configured and built. | 362 | configuration information about how that package was configured and built. |
| 363 | </para> | 363 | </para> |
| @@ -390,9 +390,9 @@ | |||
| 390 | </question> | 390 | </question> |
| 391 | <answer> | 391 | <answer> |
| 392 | <para> | 392 | <para> |
| 393 | The default interfaces file provided by the netbase recipe does not | 393 | The default interfaces file provided by the netbase recipe does not |
| 394 | automatically bring up network interfaces. | 394 | automatically bring up network interfaces. |
| 395 | Therefore, you will need to add a BSP-specific netbase that includes an interfaces | 395 | Therefore, you will need to add a BSP-specific netbase that includes an interfaces |
| 396 | file. | 396 | file. |
| 397 | See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>" | 397 | See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>" |
| 398 | section for information on creating these types of miscellaneous recipe files. | 398 | section for information on creating these types of miscellaneous recipe files. |
| @@ -415,11 +415,11 @@ | |||
| 415 | </question> | 415 | </question> |
| 416 | <answer> | 416 | <answer> |
| 417 | <para> | 417 | <para> |
| 418 | Images are created to be 1.2 times the size of the populated root filesystem. | 418 | Images are created to be 1.2 times the size of the populated root filesystem. |
| 419 | To modify this ratio so that there is more free space available, you need to | 419 | To modify this ratio so that there is more free space available, you need to |
| 420 | set the configuration value <filename>IMAGE_OVERHEAD_FACTOR</filename>. | 420 | set the configuration value <filename>IMAGE_OVERHEAD_FACTOR</filename>. |
| 421 | For example, setting <filename>IMAGE_OVERHEAD_FACTOR</filename> to 1.5 sets | 421 | For example, setting <filename>IMAGE_OVERHEAD_FACTOR</filename> to 1.5 sets |
| 422 | the image size ratio to one and a half times the size of the populated | 422 | the image size ratio to one and a half times the size of the populated |
| 423 | root filesystem. | 423 | root filesystem. |
| 424 | <literallayout class='monospaced'> | 424 | <literallayout class='monospaced'> |
| 425 | IMAGE_OVERHEAD_FACTOR = "1.5" | 425 | IMAGE_OVERHEAD_FACTOR = "1.5" |
| @@ -436,9 +436,9 @@ | |||
| 436 | </question> | 436 | </question> |
| 437 | <answer> | 437 | <answer> |
| 438 | <para> | 438 | <para> |
| 439 | The Yocto Project team has tried to do this before but too many of the tools | 439 | The Yocto Project team has tried to do this before but too many of the tools |
| 440 | the OpenEmbedded build system depends on such as <filename>autoconf</filename> | 440 | the OpenEmbedded build system depends on such as <filename>autoconf</filename> |
| 441 | break when they find spaces in pathnames. | 441 | break when they find spaces in pathnames. |
| 442 | Until that situation changes, the team will not support spaces in pathnames. | 442 | Until that situation changes, the team will not support spaces in pathnames. |
| 443 | </para> | 443 | </para> |
| 444 | </answer> | 444 | </answer> |
| @@ -453,10 +453,10 @@ | |||
| 453 | <answer> | 453 | <answer> |
| 454 | <para> | 454 | <para> |
| 455 | The toolchain configuration is very flexible and customizable. | 455 | The toolchain configuration is very flexible and customizable. |
| 456 | It is primarily controlled with the | 456 | It is primarily controlled with the |
| 457 | <filename><link linkend='var-TCMODE'>TCMODE</link></filename> variable. | 457 | <filename><link linkend='var-TCMODE'>TCMODE</link></filename> variable. |
| 458 | This variable controls which <filename>tcmode-*.inc</filename> file to include | 458 | This variable controls which <filename>tcmode-*.inc</filename> file to include |
| 459 | from the <filename>meta/conf/distro/include</filename> directory within the | 459 | from the <filename>meta/conf/distro/include</filename> directory within the |
| 460 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>. | 460 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>. |
| 461 | </para> | 461 | </para> |
| 462 | 462 | ||
| @@ -466,15 +466,15 @@ | |||
| 466 | However, other patterns are accepted. | 466 | However, other patterns are accepted. |
| 467 | In particular, "external-*" refers to external toolchains of which there are some | 467 | In particular, "external-*" refers to external toolchains of which there are some |
| 468 | basic examples included in the OpenEmbedded Core (<filename>meta</filename>). | 468 | basic examples included in the OpenEmbedded Core (<filename>meta</filename>). |
| 469 | You can use your own custom toolchain definition in your own layer | 469 | You can use your own custom toolchain definition in your own layer |
| 470 | (or as defined in the <filename>local.conf</filename> file) at the location | 470 | (or as defined in the <filename>local.conf</filename> file) at the location |
| 471 | <filename>conf/distro/include/tcmode-*.inc</filename>. | 471 | <filename>conf/distro/include/tcmode-*.inc</filename>. |
| 472 | </para> | 472 | </para> |
| 473 | 473 | ||
| 474 | <para> | 474 | <para> |
| 475 | In addition to the toolchain configuration, you also need a corresponding toolchain recipe file. | 475 | In addition to the toolchain configuration, you also need a corresponding toolchain recipe file. |
| 476 | This recipe file needs to package up any pre-built objects in the toolchain such as | 476 | This recipe file needs to package up any pre-built objects in the toolchain such as |
| 477 | <filename>libgcc</filename>, <filename>libstdcc++</filename>, | 477 | <filename>libgcc</filename>, <filename>libstdcc++</filename>, |
| 478 | any locales, and <filename>libc</filename>. | 478 | any locales, and <filename>libc</filename>. |
| 479 | An example is the <filename>external-sourcery-toolchain.bb</filename>, which is located | 479 | An example is the <filename>external-sourcery-toolchain.bb</filename>, which is located |
| 480 | in <filename>meta/recipes-core/meta/</filename> within the source directory. | 480 | in <filename>meta/recipes-core/meta/</filename> within the source directory. |
| @@ -485,7 +485,7 @@ | |||
| 485 | <qandaentry> | 485 | <qandaentry> |
| 486 | <question> | 486 | <question> |
| 487 | <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'> | 487 | <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'> |
| 488 | How does the OpenEmbedded build system obtain source code and will it work behind my | 488 | How does the OpenEmbedded build system obtain source code and will it work behind my |
| 489 | firewall or proxy server? | 489 | firewall or proxy server? |
| 490 | </para> | 490 | </para> |
| 491 | </question> | 491 | </question> |
| @@ -497,13 +497,13 @@ | |||
| 497 | </para> | 497 | </para> |
| 498 | <para> | 498 | <para> |
| 499 | When the build system searches for source code, it first tries the local download directory. | 499 | When the build system searches for source code, it first tries the local download directory. |
| 500 | If that location fails, Poky tries PREMIRRORS, the upstream source, | 500 | If that location fails, Poky tries PREMIRRORS, the upstream source, |
| 501 | and then MIRRORS in that order. | 501 | and then MIRRORS in that order. |
| 502 | </para> | 502 | </para> |
| 503 | <para> | 503 | <para> |
| 504 | By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS | 504 | By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS |
| 505 | for SCM-based sources, | 505 | for SCM-based sources, |
| 506 | upstreams for normal tarballs, and then falls back to a number of other mirrors | 506 | upstreams for normal tarballs, and then falls back to a number of other mirrors |
| 507 | including the Yocto Project source mirror if those fail. | 507 | including the Yocto Project source mirror if those fail. |
| 508 | </para> | 508 | </para> |
| 509 | <para> | 509 | <para> |
| @@ -521,7 +521,7 @@ | |||
| 521 | <para> | 521 | <para> |
| 522 | These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS | 522 | These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS |
| 523 | requests and direct them to the <filename>http://</filename> sources mirror. | 523 | requests and direct them to the <filename>http://</filename> sources mirror. |
| 524 | You can use <filename>file://</filename> URLs to point to local directories | 524 | You can use <filename>file://</filename> URLs to point to local directories |
| 525 | or network shares as well. | 525 | or network shares as well. |
| 526 | </para> | 526 | </para> |
| 527 | <para> | 527 | <para> |
| @@ -529,7 +529,7 @@ | |||
| 529 | <literallayout class='monospaced'> | 529 | <literallayout class='monospaced'> |
| 530 | BB_NO_NETWORK = "1" | 530 | BB_NO_NETWORK = "1" |
| 531 | </literallayout> | 531 | </literallayout> |
| 532 | This statement tells BitBake to throw an error instead of trying to access the | 532 | This statement tells BitBake to throw an error instead of trying to access the |
| 533 | Internet. | 533 | Internet. |
| 534 | This technique is useful if you want to ensure code builds only from local sources. | 534 | This technique is useful if you want to ensure code builds only from local sources. |
| 535 | </para> | 535 | </para> |
| @@ -559,14 +559,14 @@ | |||
| 559 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | 559 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ |
| 560 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | 560 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ |
| 561 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | 561 | https://.*/.* http://www.yoctoproject.org/sources/ \n" |
| 562 | BB_FETCH_PREMIRRORONLY = "1" | 562 | BB_FETCH_PREMIRRORONLY = "1" |
| 563 | </literallayout> | 563 | </literallayout> |
| 564 | These changes would cause Poky to successfully fetch source over HTTP and | 564 | These changes would cause Poky to successfully fetch source over HTTP and |
| 565 | any network accesses to anything other than the PREMIRROR would fail. | 565 | any network accesses to anything other than the PREMIRROR would fail. |
| 566 | </para> | 566 | </para> |
| 567 | <para> | 567 | <para> |
| 568 | The build system also honors the standard shell environment variables | 568 | The build system also honors the standard shell environment variables |
| 569 | <filename>http_proxy</filename>, <filename>ftp_proxy</filename>, | 569 | <filename>http_proxy</filename>, <filename>ftp_proxy</filename>, |
| 570 | <filename>https_proxy</filename>, and <filename>all_proxy</filename> | 570 | <filename>https_proxy</filename>, and <filename>all_proxy</filename> |
| 571 | to redirect requests through proxy servers. | 571 | to redirect requests through proxy servers. |
| 572 | </para> | 572 | </para> |
| @@ -582,16 +582,16 @@ | |||
| 582 | <answer> | 582 | <answer> |
| 583 | <para> | 583 | <para> |
| 584 | Yes - you can easily do this. | 584 | Yes - you can easily do this. |
| 585 | When you use BitBake to build an image, all the build output goes into the | 585 | When you use BitBake to build an image, all the build output goes into the |
| 586 | directory created when you source the <filename>oe-init-build-env</filename> | 586 | directory created when you source the <filename>oe-init-build-env</filename> |
| 587 | setup file. | 587 | setup file. |
| 588 | By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink> | 588 | By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink> |
| 589 | is named <filename>build</filename> but can be named | 589 | is named <filename>build</filename> but can be named |
| 590 | anything you want. | 590 | anything you want. |
| 591 | </para> | 591 | </para> |
| 592 | 592 | ||
| 593 | <para> | 593 | <para> |
| 594 | Within the build directory is the <filename>tmp</filename> directory. | 594 | Within the build directory is the <filename>tmp</filename> directory. |
| 595 | To remove all the build output yet preserve any source code or downloaded files | 595 | To remove all the build output yet preserve any source code or downloaded files |
| 596 | from previous builds, simply remove the <filename>tmp</filename> directory. | 596 | from previous builds, simply remove the <filename>tmp</filename> directory. |
| 597 | </para> | 597 | </para> |
| @@ -601,7 +601,6 @@ | |||
| 601 | 601 | ||
| 602 | </qandaset> | 602 | </qandaset> |
| 603 | </chapter> | 603 | </chapter> |
| 604 | <!-- | 604 | <!-- |
| 605 | vim: expandtab tw=80 ts=4 | 605 | vim: expandtab tw=80 ts=4 |
| 606 | --> | 606 | --> |
| 607 | |||
diff --git a/documentation/poky-ref-manual/introduction.xml b/documentation/poky-ref-manual/introduction.xml index ab2e7d0f31..38c58da262 100644 --- a/documentation/poky-ref-manual/introduction.xml +++ b/documentation/poky-ref-manual/introduction.xml | |||
| @@ -12,14 +12,14 @@ | |||
| 12 | This manual provides reference information for the current release of the Yocto Project. | 12 | This manual provides reference information for the current release of the Yocto Project. |
| 13 | The Yocto Project is an open-source collaboration project focused on embedded Linux | 13 | The Yocto Project is an open-source collaboration project focused on embedded Linux |
| 14 | developers. | 14 | developers. |
| 15 | Amongst other things, the Yocto Project uses the OpenEmbedded build system, which | 15 | Amongst other things, the Yocto Project uses the OpenEmbedded build system, which |
| 16 | is based on the Poky project, to construct complete Linux images. | 16 | is based on the Poky project, to construct complete Linux images. |
| 17 | You can find complete introductory and getting started information on the Yocto Project | 17 | You can find complete introductory and getting started information on the Yocto Project |
| 18 | by reading the | 18 | by reading the |
| 19 | <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. | 19 | <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. |
| 20 | For task-based information using the Yocto Project, see the | 20 | For task-based information using the Yocto Project, see the |
| 21 | <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>. | 21 | <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>. |
| 22 | You can also find lots of information on the Yocto Project on the | 22 | You can also find lots of information on the Yocto Project on the |
| 23 | <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>. | 23 | <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>. |
| 24 | </para> | 24 | </para> |
| 25 | </section> | 25 | </section> |
| @@ -31,53 +31,53 @@ | |||
| 31 | <itemizedlist> | 31 | <itemizedlist> |
| 32 | <listitem><para><emphasis> | 32 | <listitem><para><emphasis> |
| 33 | <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis> This chapter | 33 | <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis> This chapter |
| 34 | provides an overview of the components that make up the Yocto Project | 34 | provides an overview of the components that make up the Yocto Project |
| 35 | followed by information about debugging images created in the Yocto Project. | 35 | followed by information about debugging images created in the Yocto Project. |
| 36 | </para></listitem> | 36 | </para></listitem> |
| 37 | <listitem><para><emphasis> | 37 | <listitem><para><emphasis> |
| 38 | <link linkend='technical-details'>Technical Details</link>:</emphasis> | 38 | <link linkend='technical-details'>Technical Details</link>:</emphasis> |
| 39 | This chapter describes fundamental Yocto Project components as well as an explanation | 39 | This chapter describes fundamental Yocto Project components as well as an explanation |
| 40 | behind how the Yocto Project uses shared state (sstate) cache to speed build time. | 40 | behind how the Yocto Project uses shared state (sstate) cache to speed build time. |
| 41 | </para></listitem> | 41 | </para></listitem> |
| 42 | <listitem><para><emphasis> | 42 | <listitem><para><emphasis> |
| 43 | <link linkend='ref-structure'>Directory Structure</link>:</emphasis> | 43 | <link linkend='ref-structure'>Directory Structure</link>:</emphasis> |
| 44 | This chapter describes the | 44 | This chapter describes the |
| 45 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> created | 45 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> created |
| 46 | either by unpacking a released Yocto Project tarball on your host development system, | 46 | either by unpacking a released Yocto Project tarball on your host development system, |
| 47 | or by cloning the upstream | 47 | or by cloning the upstream |
| 48 | <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository. | 48 | <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository. |
| 49 | </para></listitem> | 49 | </para></listitem> |
| 50 | <listitem><para><emphasis> | 50 | <listitem><para><emphasis> |
| 51 | <link linkend='ref-bitbake'>BitBake</link>:</emphasis> | 51 | <link linkend='ref-bitbake'>BitBake</link>:</emphasis> |
| 52 | This chapter provides an overview of the BitBake tool and its role within | 52 | This chapter provides an overview of the BitBake tool and its role within |
| 53 | the Yocto Project.</para></listitem> | 53 | the Yocto Project.</para></listitem> |
| 54 | <listitem><para><emphasis> | 54 | <listitem><para><emphasis> |
| 55 | <link linkend='ref-classes'>Classes</link>:</emphasis> | 55 | <link linkend='ref-classes'>Classes</link>:</emphasis> |
| 56 | This chapter describes the classes used in the Yocto Project.</para></listitem> | 56 | This chapter describes the classes used in the Yocto Project.</para></listitem> |
| 57 | <listitem><para><emphasis> | 57 | <listitem><para><emphasis> |
| 58 | <link linkend='ref-images'>Images</link>:</emphasis> | 58 | <link linkend='ref-images'>Images</link>:</emphasis> |
| 59 | This chapter describes the standard images that the Yocto Project supports. | 59 | This chapter describes the standard images that the Yocto Project supports. |
| 60 | </para></listitem> | 60 | </para></listitem> |
| 61 | <listitem><para><emphasis> | 61 | <listitem><para><emphasis> |
| 62 | <link linkend='ref-features'>Features</link>:</emphasis> | 62 | <link linkend='ref-features'>Features</link>:</emphasis> |
| 63 | This chapter describes mechanisms for creating distribution, machine, and image | 63 | This chapter describes mechanisms for creating distribution, machine, and image |
| 64 | features during the build process using the OpenEmbedded build system.</para></listitem> | 64 | features during the build process using the OpenEmbedded build system.</para></listitem> |
| 65 | <listitem><para><emphasis> | 65 | <listitem><para><emphasis> |
| 66 | <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis> | 66 | <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis> |
| 67 | This chapter presents most variables used by the OpenEmbedded build system, which | 67 | This chapter presents most variables used by the OpenEmbedded build system, which |
| 68 | using BitBake. | 68 | using BitBake. |
| 69 | Entries describe the function of the variable and how to apply them. | 69 | Entries describe the function of the variable and how to apply them. |
| 70 | </para></listitem> | 70 | </para></listitem> |
| 71 | <listitem><para><emphasis> | 71 | <listitem><para><emphasis> |
| 72 | <link linkend='ref-varlocality'>Variable Context</link>:</emphasis> | 72 | <link linkend='ref-varlocality'>Variable Context</link>:</emphasis> |
| 73 | This chapter provides variable locality or context.</para></listitem> | 73 | This chapter provides variable locality or context.</para></listitem> |
| 74 | <listitem><para><emphasis> | 74 | <listitem><para><emphasis> |
| 75 | <link linkend='faq'>FAQ</link>:</emphasis> | 75 | <link linkend='faq'>FAQ</link>:</emphasis> |
| 76 | This chapter provides answers for commonly asked questions in the Yocto Project | 76 | This chapter provides answers for commonly asked questions in the Yocto Project |
| 77 | development environment.</para></listitem> | 77 | development environment.</para></listitem> |
| 78 | <listitem><para><emphasis> | 78 | <listitem><para><emphasis> |
| 79 | <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis> | 79 | <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis> |
| 80 | This chapter provides guidance on how you can contribute back to the Yocto | 80 | This chapter provides guidance on how you can contribute back to the Yocto |
| 81 | Project.</para></listitem> | 81 | Project.</para></listitem> |
| 82 | </itemizedlist> | 82 | </itemizedlist> |
| 83 | </para> | 83 | </para> |
| @@ -88,7 +88,7 @@ | |||
| 88 | <title>System Requirements</title> | 88 | <title>System Requirements</title> |
| 89 | <para> | 89 | <para> |
| 90 | For general Yocto Project system requirements, see the | 90 | For general Yocto Project system requirements, see the |
| 91 | "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section | 91 | "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section |
| 92 | in the Yocto Project Quick Start. | 92 | in the Yocto Project Quick Start. |
| 93 | The remainder of this section provides details on system requirements | 93 | The remainder of this section provides details on system requirements |
| 94 | not covered in the Yocto Project Quick Start. | 94 | not covered in the Yocto Project Quick Start. |
| @@ -120,8 +120,8 @@ | |||
| 120 | </para> | 120 | </para> |
| 121 | 121 | ||
| 122 | <note> | 122 | <note> |
| 123 | For additional information on distributions that support the | 123 | For additional information on distributions that support the |
| 124 | Yocto Project, see the | 124 | Yocto Project, see the |
| 125 | <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink> wiki page. | 125 | <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink> wiki page. |
| 126 | </note> | 126 | </note> |
| 127 | </section> | 127 | </section> |
| @@ -130,9 +130,9 @@ | |||
| 130 | <title>Required Packages for the Host Development System</title> | 130 | <title>Required Packages for the Host Development System</title> |
| 131 | 131 | ||
| 132 | <para> | 132 | <para> |
| 133 | The list of packages you need on the host development system can | 133 | The list of packages you need on the host development system can |
| 134 | be large when covering all build scenarios using the Yocto Project. | 134 | be large when covering all build scenarios using the Yocto Project. |
| 135 | This section provides required packages by Linux distribution and | 135 | This section provides required packages by Linux distribution and |
| 136 | further categorized by function. | 136 | further categorized by function. |
| 137 | </para> | 137 | </para> |
| 138 | 138 | ||
| @@ -144,7 +144,7 @@ | |||
| 144 | given a supported Ubuntu Linux distribution: | 144 | given a supported Ubuntu Linux distribution: |
| 145 | <itemizedlist> | 145 | <itemizedlist> |
| 146 | <listitem><para><emphasis>Essentials:</emphasis> | 146 | <listitem><para><emphasis>Essentials:</emphasis> |
| 147 | Packages needed to build an image on a headless | 147 | Packages needed to build an image on a headless |
| 148 | system: | 148 | system: |
| 149 | <literallayout class='monospaced'> | 149 | <literallayout class='monospaced'> |
| 150 | $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; | 150 | $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; |
| @@ -155,13 +155,13 @@ | |||
| 155 | $ sudo apt-get install libsdl1.2-dev xterm | 155 | $ sudo apt-get install libsdl1.2-dev xterm |
| 156 | </literallayout></para></listitem> | 156 | </literallayout></para></listitem> |
| 157 | <listitem><para><emphasis>Documentation:</emphasis> | 157 | <listitem><para><emphasis>Documentation:</emphasis> |
| 158 | Packages needed if you are going to build out the | 158 | Packages needed if you are going to build out the |
| 159 | Yocto Project documentation manuals: | 159 | Yocto Project documentation manuals: |
| 160 | <literallayout class='monospaced'> | 160 | <literallayout class='monospaced'> |
| 161 | $ sudo apt-get install make xsltproc docbook-utils fop | 161 | $ sudo apt-get install make xsltproc docbook-utils fop |
| 162 | </literallayout></para></listitem> | 162 | </literallayout></para></listitem> |
| 163 | <listitem><para><emphasis>ADT Installer Extras:</emphasis> | 163 | <listitem><para><emphasis>ADT Installer Extras:</emphasis> |
| 164 | Packages needed if you are going to be using the | 164 | Packages needed if you are going to be using the |
| 165 | <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: | 165 | <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: |
| 166 | <literallayout class='monospaced'> | 166 | <literallayout class='monospaced'> |
| 167 | $ sudo apt-get install autoconf automake libtool libglib2.0-dev | 167 | $ sudo apt-get install autoconf automake libtool libglib2.0-dev |
| @@ -178,7 +178,7 @@ | |||
| 178 | given a supported Fedora Linux distribution: | 178 | given a supported Fedora Linux distribution: |
| 179 | <itemizedlist> | 179 | <itemizedlist> |
| 180 | <listitem><para><emphasis>Essentials:</emphasis> | 180 | <listitem><para><emphasis>Essentials:</emphasis> |
| 181 | Packages needed to build an image for a headless | 181 | Packages needed to build an image for a headless |
| 182 | system: | 182 | system: |
| 183 | <literallayout class='monospaced'> | 183 | <literallayout class='monospaced'> |
| 184 | $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL; | 184 | $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL; |
| @@ -189,14 +189,14 @@ | |||
| 189 | $ sudo yum install SDL-devel xterm | 189 | $ sudo yum install SDL-devel xterm |
| 190 | </literallayout></para></listitem> | 190 | </literallayout></para></listitem> |
| 191 | <listitem><para><emphasis>Documentation:</emphasis> | 191 | <listitem><para><emphasis>Documentation:</emphasis> |
| 192 | Packages needed if you are going to build out the | 192 | Packages needed if you are going to build out the |
| 193 | Yocto Project documentation manuals: | 193 | Yocto Project documentation manuals: |
| 194 | <literallayout class='monospaced'> | 194 | <literallayout class='monospaced'> |
| 195 | $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ | 195 | $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ |
| 196 | docbook-dtds docbook-utils fop libxslt | 196 | docbook-dtds docbook-utils fop libxslt |
| 197 | </literallayout></para></listitem> | 197 | </literallayout></para></listitem> |
| 198 | <listitem><para><emphasis>ADT Installer Extras:</emphasis> | 198 | <listitem><para><emphasis>ADT Installer Extras:</emphasis> |
| 199 | Packages needed if you are going to be using the | 199 | Packages needed if you are going to be using the |
| 200 | <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: | 200 | <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: |
| 201 | <literallayout class='monospaced'> | 201 | <literallayout class='monospaced'> |
| 202 | $ sudo yum install autoconf automake libtool glib2-devel | 202 | $ sudo yum install autoconf automake libtool glib2-devel |
| @@ -213,7 +213,7 @@ | |||
| 213 | given a supported OpenSUSE Linux distribution: | 213 | given a supported OpenSUSE Linux distribution: |
| 214 | <itemizedlist> | 214 | <itemizedlist> |
| 215 | <listitem><para><emphasis>Essentials:</emphasis> | 215 | <listitem><para><emphasis>Essentials:</emphasis> |
| 216 | Packages needed to build an image for a headless | 216 | Packages needed to build an image for a headless |
| 217 | system: | 217 | system: |
| 218 | <literallayout class='monospaced'> | 218 | <literallayout class='monospaced'> |
| 219 | $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; | 219 | $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; |
| @@ -224,13 +224,13 @@ | |||
| 224 | $ sudo zypper install libSDL-devel xterm | 224 | $ sudo zypper install libSDL-devel xterm |
| 225 | </literallayout></para></listitem> | 225 | </literallayout></para></listitem> |
| 226 | <listitem><para><emphasis>Documentation:</emphasis> | 226 | <listitem><para><emphasis>Documentation:</emphasis> |
| 227 | Packages needed if you are going to build out the | 227 | Packages needed if you are going to build out the |
| 228 | Yocto Project documentation manuals: | 228 | Yocto Project documentation manuals: |
| 229 | <literallayout class='monospaced'> | 229 | <literallayout class='monospaced'> |
| 230 | $ sudo zypper install make fop xsltproc | 230 | $ sudo zypper install make fop xsltproc |
| 231 | </literallayout></para></listitem> | 231 | </literallayout></para></listitem> |
| 232 | <listitem><para><emphasis>ADT Installer Extras:</emphasis> | 232 | <listitem><para><emphasis>ADT Installer Extras:</emphasis> |
| 233 | Packages needed if you are going to be using the | 233 | Packages needed if you are going to be using the |
| 234 | <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: | 234 | <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: |
| 235 | <literallayout class='monospaced'> | 235 | <literallayout class='monospaced'> |
| 236 | $ sudo zypper install autoconf automake libtool glib2-devel | 236 | $ sudo zypper install autoconf automake libtool glib2-devel |
| @@ -247,7 +247,7 @@ | |||
| 247 | given a supported CentOS Linux distribution: | 247 | given a supported CentOS Linux distribution: |
| 248 | <itemizedlist> | 248 | <itemizedlist> |
| 249 | <listitem><para><emphasis>Essentials:</emphasis> | 249 | <listitem><para><emphasis>Essentials:</emphasis> |
| 250 | Packages needed to build an image for a headless | 250 | Packages needed to build an image for a headless |
| 251 | system: | 251 | system: |
| 252 | <literallayout class='monospaced'> | 252 | <literallayout class='monospaced'> |
| 253 | $ sudo yum -y install &CENTOS_HOST_PACKAGES_ESSENTIAL; | 253 | $ sudo yum -y install &CENTOS_HOST_PACKAGES_ESSENTIAL; |
| @@ -258,22 +258,22 @@ | |||
| 258 | $ sudo yum -y install SDL-devel xterm | 258 | $ sudo yum -y install SDL-devel xterm |
| 259 | </literallayout></para></listitem> | 259 | </literallayout></para></listitem> |
| 260 | <listitem><para><emphasis>Documentation:</emphasis> | 260 | <listitem><para><emphasis>Documentation:</emphasis> |
| 261 | Packages needed if you are going to build out the | 261 | Packages needed if you are going to build out the |
| 262 | Yocto Project documentation manuals: | 262 | Yocto Project documentation manuals: |
| 263 | <literallayout class='monospaced'> | 263 | <literallayout class='monospaced'> |
| 264 | $ sudo yum -y install make docbook-style-dsssl docbook-style-xsl \ | 264 | $ sudo yum -y install make docbook-style-dsssl docbook-style-xsl \ |
| 265 | docbook-dtds docbook-utils fop libxslt | 265 | docbook-dtds docbook-utils fop libxslt |
| 266 | </literallayout></para></listitem> | 266 | </literallayout></para></listitem> |
| 267 | <listitem><para><emphasis>ADT Installer Extras:</emphasis> | 267 | <listitem><para><emphasis>ADT Installer Extras:</emphasis> |
| 268 | Packages needed if you are going to be using the | 268 | Packages needed if you are going to be using the |
| 269 | <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: | 269 | <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: |
| 270 | <literallayout class='monospaced'> | 270 | <literallayout class='monospaced'> |
| 271 | $ sudo yum -y install autoconf automake libtool glib2-devel | 271 | $ sudo yum -y install autoconf automake libtool glib2-devel |
| 272 | </literallayout></para></listitem> | 272 | </literallayout></para></listitem> |
| 273 | </itemizedlist> | 273 | </itemizedlist> |
| 274 | <note>Depending on the CentOS version you are using, other requirements | 274 | <note>Depending on the CentOS version you are using, other requirements |
| 275 | and dependencies might exist. | 275 | and dependencies might exist. |
| 276 | For details, you should look at the CentOS sections on the | 276 | For details, you should look at the CentOS sections on the |
| 277 | <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink> | 277 | <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink> |
| 278 | wiki page.</note> | 278 | wiki page.</note> |
| 279 | </para> | 279 | </para> |
| @@ -284,19 +284,19 @@ | |||
| 284 | <section id='intro-getit'> | 284 | <section id='intro-getit'> |
| 285 | <title>Obtaining the Yocto Project</title> | 285 | <title>Obtaining the Yocto Project</title> |
| 286 | <para> | 286 | <para> |
| 287 | The Yocto Project development team makes the Yocto Project available through a number | 287 | The Yocto Project development team makes the Yocto Project available through a number |
| 288 | of methods: | 288 | of methods: |
| 289 | <itemizedlist> | 289 | <itemizedlist> |
| 290 | <listitem><para><emphasis>Releases:</emphasis> Stable, tested releases are available through | 290 | <listitem><para><emphasis>Releases:</emphasis> Stable, tested releases are available through |
| 291 | <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem> | 291 | <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem> |
| 292 | <listitem><para><emphasis>Nightly Builds:</emphasis> These releases are available at | 292 | <listitem><para><emphasis>Nightly Builds:</emphasis> These releases are available at |
| 293 | <ulink url='http://autobuilder.yoctoproject.org/nightly'/>. | 293 | <ulink url='http://autobuilder.yoctoproject.org/nightly'/>. |
| 294 | These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and | 294 | These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and |
| 295 | experimental builds.</para></listitem> | 295 | experimental builds.</para></listitem> |
| 296 | <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find releases | 296 | <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find releases |
| 297 | of the Yocto Project and supported BSPs at the | 297 | of the Yocto Project and supported BSPs at the |
| 298 | <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>. | 298 | <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>. |
| 299 | Along with these downloads, you can find lots of other information at this site. | 299 | Along with these downloads, you can find lots of other information at this site. |
| 300 | </para></listitem> | 300 | </para></listitem> |
| 301 | </itemizedlist> | 301 | </itemizedlist> |
| 302 | </para> | 302 | </para> |
| @@ -305,13 +305,13 @@ | |||
| 305 | <section id='intro-getit-dev'> | 305 | <section id='intro-getit-dev'> |
| 306 | <title>Development Checkouts</title> | 306 | <title>Development Checkouts</title> |
| 307 | <para> | 307 | <para> |
| 308 | Development using the Yocto Project requires a local | 308 | Development using the Yocto Project requires a local |
| 309 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 309 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 310 | You can set up the source directory by downloading a Yocto Project release tarball and unpacking it, | 310 | You can set up the source directory by downloading a Yocto Project release tarball and unpacking it, |
| 311 | or by cloning a copy of the upstream | 311 | or by cloning a copy of the upstream |
| 312 | <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository. | 312 | <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository. |
| 313 | For information on both these methods, see the | 313 | For information on both these methods, see the |
| 314 | "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Setup</ulink>" | 314 | "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Setup</ulink>" |
| 315 | section in the Yocto Project Development Manual. | 315 | section in the Yocto Project Development Manual. |
| 316 | </para> | 316 | </para> |
| 317 | </section> | 317 | </section> |
diff --git a/documentation/poky-ref-manual/migration.xml b/documentation/poky-ref-manual/migration.xml index b311da65c5..40c570f8ca 100644 --- a/documentation/poky-ref-manual/migration.xml +++ b/documentation/poky-ref-manual/migration.xml | |||
| @@ -6,8 +6,8 @@ | |||
| 6 | <title>Migrating to a Newer Yocto Project Release</title> | 6 | <title>Migrating to a Newer Yocto Project Release</title> |
| 7 | 7 | ||
| 8 | <para> | 8 | <para> |
| 9 | This chapter provides information you can use to migrate work to a | 9 | This chapter provides information you can use to migrate work to a |
| 10 | newer Yocto Project release. You can find the same information in the | 10 | newer Yocto Project release. You can find the same information in the |
| 11 | release notes for a given release. | 11 | release notes for a given release. |
| 12 | </para> | 12 | </para> |
| 13 | 13 | ||
| @@ -15,7 +15,7 @@ | |||
| 15 | <title>Moving to the Yocto Project 1.3 Release</title> | 15 | <title>Moving to the Yocto Project 1.3 Release</title> |
| 16 | 16 | ||
| 17 | <para> | 17 | <para> |
| 18 | This section provides migration information for moving to the | 18 | This section provides migration information for moving to the |
| 19 | Yocto Project 1.3 Release. | 19 | Yocto Project 1.3 Release. |
| 20 | </para> | 20 | </para> |
| 21 | 21 | ||
| @@ -23,7 +23,7 @@ | |||
| 23 | <title>Local Configuration</title> | 23 | <title>Local Configuration</title> |
| 24 | 24 | ||
| 25 | <para> | 25 | <para> |
| 26 | Differences include changes for | 26 | Differences include changes for |
| 27 | <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> | 27 | <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> |
| 28 | and <filename>bblayers.conf</filename>. | 28 | and <filename>bblayers.conf</filename>. |
| 29 | </para> | 29 | </para> |
| @@ -32,18 +32,18 @@ | |||
| 32 | <title>SSTATE_MIRRORS</title> | 32 | <title>SSTATE_MIRRORS</title> |
| 33 | 33 | ||
| 34 | <para> | 34 | <para> |
| 35 | The shared state cache (sstate-cache) as pointed to by | 35 | The shared state cache (sstate-cache) as pointed to by |
| 36 | <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> by default | 36 | <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> by default |
| 37 | now has two-character subdirectories to prevent there being an issue with too | 37 | now has two-character subdirectories to prevent there being an issue with too |
| 38 | many files in the same directory. | 38 | many files in the same directory. |
| 39 | Also, native sstate-cache packages will go into a subdirectory named using | 39 | Also, native sstate-cache packages will go into a subdirectory named using |
| 40 | the distro ID string. | 40 | the distro ID string. |
| 41 | If you copy the newly structured sstate-cache to a mirror location | 41 | If you copy the newly structured sstate-cache to a mirror location |
| 42 | (either local or remote) and then point to it in | 42 | (either local or remote) and then point to it in |
| 43 | <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>, | 43 | <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>, |
| 44 | you need to append "PATH" to the end of the mirror URL so that | 44 | you need to append "PATH" to the end of the mirror URL so that |
| 45 | the path used by BitBake before the mirror substitution is | 45 | the path used by BitBake before the mirror substitution is |
| 46 | appended to the path used to access the mirror. | 46 | appended to the path used to access the mirror. |
| 47 | Here is an example: | 47 | Here is an example: |
| 48 | <literallayout class='monospaced'> | 48 | <literallayout class='monospaced'> |
| 49 | SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" | 49 | SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" |
| @@ -55,14 +55,14 @@ | |||
| 55 | <title>bblayers.conf</title> | 55 | <title>bblayers.conf</title> |
| 56 | 56 | ||
| 57 | <para> | 57 | <para> |
| 58 | The <filename>meta-yocto</filename> layer has been split into | 58 | The <filename>meta-yocto</filename> layer has been split into |
| 59 | two parts: <filename>meta-yocto</filename> and | 59 | two parts: <filename>meta-yocto</filename> and |
| 60 | <filename>meta-yocto-bsp</filename>, corresponding to the | 60 | <filename>meta-yocto-bsp</filename>, corresponding to the |
| 61 | Poky reference distro configuration and the reference | 61 | Poky reference distro configuration and the reference |
| 62 | hardware Board Support Packages (BSPs), respectively. | 62 | hardware Board Support Packages (BSPs), respectively. |
| 63 | When running BitBake or Hob for the first time after upgrading, | 63 | When running BitBake or Hob for the first time after upgrading, |
| 64 | your <filename>conf/bblayers.conf</filename> file will be | 64 | your <filename>conf/bblayers.conf</filename> file will be |
| 65 | updated to handle this change and you will be asked to | 65 | updated to handle this change and you will be asked to |
| 66 | re-run/restart for the changes to take effect. | 66 | re-run/restart for the changes to take effect. |
| 67 | </para> | 67 | </para> |
| 68 | </section> | 68 | </section> |
| @@ -87,16 +87,16 @@ | |||
| 87 | <title>Python Function Whitespace</title> | 87 | <title>Python Function Whitespace</title> |
| 88 | 88 | ||
| 89 | <para> | 89 | <para> |
| 90 | All Python functions must now use four spaces for indentation. | 90 | All Python functions must now use four spaces for indentation. |
| 91 | Previously, an inconsistent mix of spaces and tabs existed, | 91 | Previously, an inconsistent mix of spaces and tabs existed, |
| 92 | which made extending these functions using | 92 | which made extending these functions using |
| 93 | <filename>_append</filename> or <filename>_prepend</filename> | 93 | <filename>_append</filename> or <filename>_prepend</filename> |
| 94 | complicated given that Python treats whitespace as | 94 | complicated given that Python treats whitespace as |
| 95 | syntactically significant. | 95 | syntactically significant. |
| 96 | If you are defining or extending any Python functions (e.g. | 96 | If you are defining or extending any Python functions (e.g. |
| 97 | <filename>populate_packages</filename>, <filename>do_unpack</filename>, | 97 | <filename>populate_packages</filename>, <filename>do_unpack</filename>, |
| 98 | <filename>do_patch</filename> and so forth) in custom recipes | 98 | <filename>do_patch</filename> and so forth) in custom recipes |
| 99 | or classes, you need to ensure you are using consistent | 99 | or classes, you need to ensure you are using consistent |
| 100 | four-space indentation. | 100 | four-space indentation. |
| 101 | </para> | 101 | </para> |
| 102 | </section> | 102 | </section> |
| @@ -105,7 +105,7 @@ | |||
| 105 | <title>proto= in SRC_URI</title> | 105 | <title>proto= in SRC_URI</title> |
| 106 | 106 | ||
| 107 | <para> | 107 | <para> |
| 108 | Any use of <filename>proto=</filename> in | 108 | Any use of <filename>proto=</filename> in |
| 109 | <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> | 109 | <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> |
| 110 | needs to be changed to <filename>protocol=</filename>. | 110 | needs to be changed to <filename>protocol=</filename>. |
| 111 | In particular, this applies to the following URIs: | 111 | In particular, this applies to the following URIs: |
| @@ -125,11 +125,11 @@ | |||
| 125 | 125 | ||
| 126 | <para> | 126 | <para> |
| 127 | The suffix <filename>nativesdk</filename> is now implemented | 127 | The suffix <filename>nativesdk</filename> is now implemented |
| 128 | as a prefix, which simplifies a lot of the packaging code for | 128 | as a prefix, which simplifies a lot of the packaging code for |
| 129 | <filename>nativesdk</filename> recipes. | 129 | <filename>nativesdk</filename> recipes. |
| 130 | All custom <filename>nativesdk</filename> recipes and any | 130 | All custom <filename>nativesdk</filename> recipes and any |
| 131 | references need to be updated to use | 131 | references need to be updated to use |
| 132 | <filename>nativesdk-*</filename> instead of | 132 | <filename>nativesdk-*</filename> instead of |
| 133 | <filename>*-nativesdk</filename>. | 133 | <filename>*-nativesdk</filename>. |
| 134 | </para> | 134 | </para> |
| 135 | </section> | 135 | </section> |
| @@ -138,25 +138,25 @@ | |||
| 138 | <title>Task Recipes</title> | 138 | <title>Task Recipes</title> |
| 139 | 139 | ||
| 140 | <para> | 140 | <para> |
| 141 | "Task" recipes are now known as "Package groups" and have | 141 | "Task" recipes are now known as "Package groups" and have |
| 142 | been renamed from <filename>task-*.bb</filename> to | 142 | been renamed from <filename>task-*.bb</filename> to |
| 143 | <filename>packagegroup-*.bb</filename>. | 143 | <filename>packagegroup-*.bb</filename>. |
| 144 | Existing references to the previous <filename>task-*</filename> | 144 | Existing references to the previous <filename>task-*</filename> |
| 145 | names should work in most cases as there is an automatic | 145 | names should work in most cases as there is an automatic |
| 146 | upgrade path for most packages. | 146 | upgrade path for most packages. |
| 147 | However, you should update references in your own recipes and | 147 | However, you should update references in your own recipes and |
| 148 | configurations as they could be removed in future releases. | 148 | configurations as they could be removed in future releases. |
| 149 | You should also rename any custom <filename>task-*</filename> | 149 | You should also rename any custom <filename>task-*</filename> |
| 150 | recipes to <filename>packagegroup-*</filename>, and change | 150 | recipes to <filename>packagegroup-*</filename>, and change |
| 151 | them to inherit <filename>packagegroup</filename> instead of | 151 | them to inherit <filename>packagegroup</filename> instead of |
| 152 | <filename>task</filename>, as well as taking the opportunity | 152 | <filename>task</filename>, as well as taking the opportunity |
| 153 | to remove anything now handled by | 153 | to remove anything now handled by |
| 154 | <filename>packagegroup.bbclass</filename>, such as providing | 154 | <filename>packagegroup.bbclass</filename>, such as providing |
| 155 | <filename>-dev</filename> and <filename>-dbg</filename> | 155 | <filename>-dev</filename> and <filename>-dbg</filename> |
| 156 | packages, setting | 156 | packages, setting |
| 157 | <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>, | 157 | <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>, |
| 158 | and so forth. | 158 | and so forth. |
| 159 | See the | 159 | See the |
| 160 | "<link linkend='ref-classes-packagegroup'>Package Groups - packagegroup.bbclass</link>" | 160 | "<link linkend='ref-classes-packagegroup'>Package Groups - packagegroup.bbclass</link>" |
| 161 | section for further details. | 161 | section for further details. |
| 162 | </para> | 162 | </para> |
| @@ -166,13 +166,13 @@ | |||
| 166 | <title>IMAGE_FEATURES</title> | 166 | <title>IMAGE_FEATURES</title> |
| 167 | 167 | ||
| 168 | <para> | 168 | <para> |
| 169 | Image recipes that previously included "apps-console-core" | 169 | Image recipes that previously included "apps-console-core" |
| 170 | in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> | 170 | in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> |
| 171 | should now include "splash" instead to enable the boot-up | 171 | should now include "splash" instead to enable the boot-up |
| 172 | splash screen. | 172 | splash screen. |
| 173 | Retaining "apps-console-core" will still include the splash | 173 | Retaining "apps-console-core" will still include the splash |
| 174 | screen generates a warning. | 174 | screen generates a warning. |
| 175 | The "apps-x11-core" and "apps-x11-games" | 175 | The "apps-x11-core" and "apps-x11-games" |
| 176 | <filename>IMAGE_FEATURES</filename> features have been removed. | 176 | <filename>IMAGE_FEATURES</filename> features have been removed. |
| 177 | </para> | 177 | </para> |
| 178 | </section> | 178 | </section> |
| @@ -181,55 +181,55 @@ | |||
| 181 | <title>Removed Recipes</title> | 181 | <title>Removed Recipes</title> |
| 182 | 182 | ||
| 183 | <para> | 183 | <para> |
| 184 | The following recipes have been removed. | 184 | The following recipes have been removed. |
| 185 | For most of them, it is unlikely that you would have any | 185 | For most of them, it is unlikely that you would have any |
| 186 | references to them in your own metadata. | 186 | references to them in your own metadata. |
| 187 | However, you should check your metadata against this list to be sure: | 187 | However, you should check your metadata against this list to be sure: |
| 188 | <itemizedlist> | 188 | <itemizedlist> |
| 189 | <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>: | 189 | <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>: |
| 190 | Replaced by <filename>libx11</filename>, which has a negligible | 190 | Replaced by <filename>libx11</filename>, which has a negligible |
| 191 | size difference with modern Xorg.</para></listitem> | 191 | size difference with modern Xorg.</para></listitem> |
| 192 | <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>: | 192 | <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>: |
| 193 | Use <filename>xserver-xorg</filename>, which has a negligible | 193 | Use <filename>xserver-xorg</filename>, which has a negligible |
| 194 | size difference when DRI and GLX modules are not installed.</para></listitem> | 194 | size difference when DRI and GLX modules are not installed.</para></listitem> |
| 195 | <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>: | 195 | <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>: |
| 196 | Effectively unmaintained for many years.</para></listitem> | 196 | Effectively unmaintained for many years.</para></listitem> |
| 197 | <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>: | 197 | <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>: |
| 198 | No longer serves any purpose.</para></listitem> | 198 | No longer serves any purpose.</para></listitem> |
| 199 | <listitem><para><emphasis><filename>galago</filename></emphasis>: | 199 | <listitem><para><emphasis><filename>galago</filename></emphasis>: |
| 200 | Replaced by telepathy.</para></listitem> | 200 | Replaced by telepathy.</para></listitem> |
| 201 | <listitem><para><emphasis><filename>gail</filename></emphasis>: | 201 | <listitem><para><emphasis><filename>gail</filename></emphasis>: |
| 202 | Functionality was integrated into GTK+ 2.13.</para></listitem> | 202 | Functionality was integrated into GTK+ 2.13.</para></listitem> |
| 203 | <listitem><para><emphasis><filename>eggdbus</filename></emphasis>: | 203 | <listitem><para><emphasis><filename>eggdbus</filename></emphasis>: |
| 204 | No longer needed.</para></listitem> | 204 | No longer needed.</para></listitem> |
| 205 | <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>: | 205 | <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>: |
| 206 | The build has been restructured to avoid the need for | 206 | The build has been restructured to avoid the need for |
| 207 | this step.</para></listitem> | 207 | this step.</para></listitem> |
| 208 | <listitem><para><emphasis><filename>libgsmd</filename></emphasis>: | 208 | <listitem><para><emphasis><filename>libgsmd</filename></emphasis>: |
| 209 | Unmaintained for many years. | 209 | Unmaintained for many years. |
| 210 | Functionality now provided by | 210 | Functionality now provided by |
| 211 | <filename>ofono</filename> instead.</para></listitem> | 211 | <filename>ofono</filename> instead.</para></listitem> |
| 212 | <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>: | 212 | <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>: |
| 213 | Largely unmaintained PIM application suite. | 213 | Largely unmaintained PIM application suite. |
| 214 | It has been moved to <filename>meta-gnome</filename> | 214 | It has been moved to <filename>meta-gnome</filename> |
| 215 | in <filename>meta-openembedded</filename>.</para></listitem> | 215 | in <filename>meta-openembedded</filename>.</para></listitem> |
| 216 | </itemizedlist> | 216 | </itemizedlist> |
| 217 | In addition to the previously listed changes, the | 217 | In addition to the previously listed changes, the |
| 218 | <filename>meta-demoapps</filename> directory has also been removed | 218 | <filename>meta-demoapps</filename> directory has also been removed |
| 219 | because the recipes in it were not being maintained and many | 219 | because the recipes in it were not being maintained and many |
| 220 | had become obsolete or broken. | 220 | had become obsolete or broken. |
| 221 | Additionally, these recipes were not parsed in the default configuration. | 221 | Additionally, these recipes were not parsed in the default configuration. |
| 222 | Many of these recipes are already provided in an updated and | 222 | Many of these recipes are already provided in an updated and |
| 223 | maintained form within OpenEmbedded community layers such as | 223 | maintained form within OpenEmbedded community layers such as |
| 224 | <filename>meta-oe</filename> and <filename>meta-gnome</filename>. | 224 | <filename>meta-oe</filename> and <filename>meta-gnome</filename>. |
| 225 | For the remainder, you can now find them in the | 225 | For the remainder, you can now find them in the |
| 226 | <filename>meta-extras</filename> repository, which is in the | 226 | <filename>meta-extras</filename> repository, which is in the |
| 227 | Yocto Project source repositories. | 227 | Yocto Project source repositories. |
| 228 | </para> | 228 | </para> |
| 229 | </section> | 229 | </section> |
| 230 | </section> | 230 | </section> |
| 231 | </section> | 231 | </section> |
| 232 | </chapter> | 232 | </chapter> |
| 233 | <!-- | 233 | <!-- |
| 234 | vim: expandtab tw=80 ts=4 | 234 | vim: expandtab tw=80 ts=4 |
| 235 | --> | 235 | --> |
diff --git a/documentation/poky-ref-manual/poky-ref-manual.xml b/documentation/poky-ref-manual/poky-ref-manual.xml index 51f5e2d9f4..2fcc68d88c 100644 --- a/documentation/poky-ref-manual/poky-ref-manual.xml +++ b/documentation/poky-ref-manual/poky-ref-manual.xml | |||
| @@ -2,18 +2,18 @@ | |||
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| 4 | 4 | ||
| 5 | <book id='poky-ref-manual' lang='en' | 5 | <book id='poky-ref-manual' lang='en' |
| 6 | xmlns:xi="http://www.w3.org/2003/XInclude" | 6 | xmlns:xi="http://www.w3.org/2003/XInclude" |
| 7 | xmlns="http://docbook.org/ns/docbook" | 7 | xmlns="http://docbook.org/ns/docbook" |
| 8 | > | 8 | > |
| 9 | <bookinfo> | 9 | <bookinfo> |
| 10 | 10 | ||
| 11 | <mediaobject> | 11 | <mediaobject> |
| 12 | <imageobject> | 12 | <imageobject> |
| 13 | <imagedata fileref='figures/poky-title.png' | 13 | <imagedata fileref='figures/poky-title.png' |
| 14 | format='SVG' | 14 | format='SVG' |
| 15 | align='left' scalefit='1' width='100%'/> | 15 | align='left' scalefit='1' width='100%'/> |
| 16 | </imageobject> | 16 | </imageobject> |
| 17 | </mediaobject> | 17 | </mediaobject> |
| 18 | 18 | ||
| 19 | <title></title> | 19 | <title></title> |
| @@ -74,7 +74,7 @@ | |||
| 74 | 74 | ||
| 75 | <legalnotice> | 75 | <legalnotice> |
| 76 | <para> | 76 | <para> |
| 77 | Permission is granted to copy, distribute and/or modify this document under | 77 | Permission is granted to copy, distribute and/or modify this document under |
| 78 | the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. | 78 | the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. |
| 79 | </para> | 79 | </para> |
| 80 | <note> | 80 | <note> |
| @@ -116,10 +116,10 @@ | |||
| 116 | 116 | ||
| 117 | <!-- <index id='index'> | 117 | <!-- <index id='index'> |
| 118 | <title>Index</title> | 118 | <title>Index</title> |
| 119 | </index> | 119 | </index> |
| 120 | --> | 120 | --> |
| 121 | 121 | ||
| 122 | </book> | 122 | </book> |
| 123 | <!-- | 123 | <!-- |
| 124 | vim: expandtab tw=80 ts=4 | 124 | vim: expandtab tw=80 ts=4 |
| 125 | --> | 125 | --> |
diff --git a/documentation/poky-ref-manual/ref-bitbake.xml b/documentation/poky-ref-manual/ref-bitbake.xml index b81f12fb7a..b641d5cff9 100644 --- a/documentation/poky-ref-manual/ref-bitbake.xml +++ b/documentation/poky-ref-manual/ref-bitbake.xml | |||
| @@ -14,15 +14,15 @@ | |||
| 14 | $ bitbake core-image-sato | 14 | $ bitbake core-image-sato |
| 15 | </literallayout> | 15 | </literallayout> |
| 16 | </para> | 16 | </para> |
| 17 | 17 | ||
| 18 | <para> | 18 | <para> |
| 19 | This chapter provides an overview of what happens behind the scenes from BitBake's perspective. | 19 | This chapter provides an overview of what happens behind the scenes from BitBake's perspective. |
| 20 | </para> | 20 | </para> |
| 21 | 21 | ||
| 22 | <note> | 22 | <note> |
| 23 | BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships. | 23 | BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships. |
| 24 | As such, it has no real knowledge of what the tasks being executed actually do. | 24 | As such, it has no real knowledge of what the tasks being executed actually do. |
| 25 | BitBake just considers a list of tasks with dependencies and handles metadata | 25 | BitBake just considers a list of tasks with dependencies and handles metadata |
| 26 | that consists of variables in a certain format that get passed to the tasks. | 26 | that consists of variables in a certain format that get passed to the tasks. |
| 27 | </note> | 27 | </note> |
| 28 | 28 | ||
| @@ -30,85 +30,85 @@ | |||
| 30 | <title>Parsing</title> | 30 | <title>Parsing</title> |
| 31 | 31 | ||
| 32 | <para> | 32 | <para> |
| 33 | BitBake parses configuration files, classes, and <filename>.bb</filename> files. | 33 | BitBake parses configuration files, classes, and <filename>.bb</filename> files. |
| 34 | </para> | 34 | </para> |
| 35 | 35 | ||
| 36 | <para> | 36 | <para> |
| 37 | The first thing BitBake does is look for the <filename>bitbake.conf</filename> file. | 37 | The first thing BitBake does is look for the <filename>bitbake.conf</filename> file. |
| 38 | This file resides in the | 38 | This file resides in the |
| 39 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | 39 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> |
| 40 | within the <filename>meta/conf/</filename> directory. | 40 | within the <filename>meta/conf/</filename> directory. |
| 41 | BitBake finds it by examining its | 41 | BitBake finds it by examining its |
| 42 | <link linkend='var-BBPATH'><filename>BBPATH</filename></link> environment | 42 | <link linkend='var-BBPATH'><filename>BBPATH</filename></link> environment |
| 43 | variable and looking for the <filename>meta/conf/</filename> | 43 | variable and looking for the <filename>meta/conf/</filename> |
| 44 | directory. | 44 | directory. |
| 45 | </para> | 45 | </para> |
| 46 | 46 | ||
| 47 | <para> | 47 | <para> |
| 48 | The <filename>bitbake.conf</filename> file lists other configuration | 48 | The <filename>bitbake.conf</filename> file lists other configuration |
| 49 | files to include from a <filename>conf/</filename> | 49 | files to include from a <filename>conf/</filename> |
| 50 | directory below the directories listed in <filename>BBPATH</filename>. | 50 | directory below the directories listed in <filename>BBPATH</filename>. |
| 51 | In general, the most important configuration file from a user's perspective | 51 | In general, the most important configuration file from a user's perspective |
| 52 | is <filename>local.conf</filename>, which contains a user's customized | 52 | is <filename>local.conf</filename>, which contains a user's customized |
| 53 | settings for the OpenEmbedded build environment. | 53 | settings for the OpenEmbedded build environment. |
| 54 | Other notable configuration files are the distribution | 54 | Other notable configuration files are the distribution |
| 55 | configuration file (set by the | 55 | configuration file (set by the |
| 56 | <filename><link linkend='var-DISTRO'>DISTRO</link></filename> variable) | 56 | <filename><link linkend='var-DISTRO'>DISTRO</link></filename> variable) |
| 57 | and the machine configuration file | 57 | and the machine configuration file |
| 58 | (set by the | 58 | (set by the |
| 59 | <filename><link linkend='var-MACHINE'>MACHINE</link></filename> variable). | 59 | <filename><link linkend='var-MACHINE'>MACHINE</link></filename> variable). |
| 60 | The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake environment | 60 | The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake environment |
| 61 | variables are both usually set in | 61 | variables are both usually set in |
| 62 | the <filename>local.conf</filename> file. | 62 | the <filename>local.conf</filename> file. |
| 63 | Valid distribution | 63 | Valid distribution |
| 64 | configuration files are available in the <filename>meta/conf/distro/</filename> directory | 64 | configuration files are available in the <filename>meta/conf/distro/</filename> directory |
| 65 | and valid machine configuration | 65 | and valid machine configuration |
| 66 | files in the <filename>meta/conf/machine/</filename> directory. | 66 | files in the <filename>meta/conf/machine/</filename> directory. |
| 67 | Within the <filename>meta/conf/machine/include/</filename> | 67 | Within the <filename>meta/conf/machine/include/</filename> |
| 68 | directory are various <filename>tune-*.inc</filename> configuration files that provide common | 68 | directory are various <filename>tune-*.inc</filename> configuration files that provide common |
| 69 | "tuning" settings specific to and shared between particular architectures and machines. | 69 | "tuning" settings specific to and shared between particular architectures and machines. |
| 70 | </para> | 70 | </para> |
| 71 | 71 | ||
| 72 | <para> | 72 | <para> |
| 73 | After the parsing of the configuration files, some standard classes are included. | 73 | After the parsing of the configuration files, some standard classes are included. |
| 74 | The <filename>base.bbclass</filename> file is always included. | 74 | The <filename>base.bbclass</filename> file is always included. |
| 75 | Other classes that are specified in the configuration using the | 75 | Other classes that are specified in the configuration using the |
| 76 | <filename><link linkend='var-INHERIT'>INHERIT</link></filename> | 76 | <filename><link linkend='var-INHERIT'>INHERIT</link></filename> |
| 77 | variable are also included. | 77 | variable are also included. |
| 78 | Class files are searched for in a <filename>classes</filename> subdirectory | 78 | Class files are searched for in a <filename>classes</filename> subdirectory |
| 79 | under the paths in <filename>BBPATH</filename> in the same way as | 79 | under the paths in <filename>BBPATH</filename> in the same way as |
| 80 | configuration files. | 80 | configuration files. |
| 81 | </para> | 81 | </para> |
| 82 | 82 | ||
| 83 | <para> | 83 | <para> |
| 84 | After classes are included, the variable | 84 | After classes are included, the variable |
| 85 | <filename><link linkend='var-BBFILES'>BBFILES</link></filename> | 85 | <filename><link linkend='var-BBFILES'>BBFILES</link></filename> |
| 86 | is set, usually in | 86 | is set, usually in |
| 87 | <filename>local.conf</filename>, and defines the list of places to search for | 87 | <filename>local.conf</filename>, and defines the list of places to search for |
| 88 | <filename>.bb</filename> files. | 88 | <filename>.bb</filename> files. |
| 89 | By default, the <filename>BBFILES</filename> variable specifies the | 89 | By default, the <filename>BBFILES</filename> variable specifies the |
| 90 | <filename>meta/recipes-*/</filename> directory within Poky. | 90 | <filename>meta/recipes-*/</filename> directory within Poky. |
| 91 | Adding extra content to <filename>BBFILES</filename> is best achieved through the use of | 91 | Adding extra content to <filename>BBFILES</filename> is best achieved through the use of |
| 92 | BitBake layers as described in the | 92 | BitBake layers as described in the |
| 93 | "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and | 93 | "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and |
| 94 | Creating Layers</ulink>" section of the Yocto Project Development Manual. | 94 | Creating Layers</ulink>" section of the Yocto Project Development Manual. |
| 95 | </para> | 95 | </para> |
| 96 | 96 | ||
| 97 | <para> | 97 | <para> |
| 98 | BitBake parses each <filename>.bb</filename> file in <filename>BBFILES</filename> and | 98 | BitBake parses each <filename>.bb</filename> file in <filename>BBFILES</filename> and |
| 99 | stores the values of various variables. | 99 | stores the values of various variables. |
| 100 | In summary, for each <filename>.bb</filename> | 100 | In summary, for each <filename>.bb</filename> |
| 101 | file the configuration plus the base class of variables are set, followed | 101 | file the configuration plus the base class of variables are set, followed |
| 102 | by the data in the <filename>.bb</filename> file | 102 | by the data in the <filename>.bb</filename> file |
| 103 | itself, followed by any inherit commands that | 103 | itself, followed by any inherit commands that |
| 104 | <filename>.bb</filename> file might contain. | 104 | <filename>.bb</filename> file might contain. |
| 105 | </para> | 105 | </para> |
| 106 | 106 | ||
| 107 | <para> | 107 | <para> |
| 108 | Because parsing <filename>.bb</filename> files is a time | 108 | Because parsing <filename>.bb</filename> files is a time |
| 109 | consuming process, a cache is kept to speed up subsequent parsing. | 109 | consuming process, a cache is kept to speed up subsequent parsing. |
| 110 | This cache is invalid if the timestamp of the <filename>.bb</filename> | 110 | This cache is invalid if the timestamp of the <filename>.bb</filename> |
| 111 | file itself changes, or if the timestamps of any of the include, | 111 | file itself changes, or if the timestamps of any of the include, |
| 112 | configuration or class files the <filename>.bb</filename> | 112 | configuration or class files the <filename>.bb</filename> |
| 113 | file depends on changes. | 113 | file depends on changes. |
| 114 | </para> | 114 | </para> |
| @@ -118,22 +118,22 @@ | |||
| 118 | <title>Preferences and Providers</title> | 118 | <title>Preferences and Providers</title> |
| 119 | 119 | ||
| 120 | <para> | 120 | <para> |
| 121 | Once all the <filename>.bb</filename> files have been | 121 | Once all the <filename>.bb</filename> files have been |
| 122 | parsed, BitBake starts to build the target (<filename>core-image-sato</filename> | 122 | parsed, BitBake starts to build the target (<filename>core-image-sato</filename> |
| 123 | in the previous section's example) and looks for providers of that target. | 123 | in the previous section's example) and looks for providers of that target. |
| 124 | Once a provider is selected, BitBake resolves all the dependencies for | 124 | Once a provider is selected, BitBake resolves all the dependencies for |
| 125 | the target. | 125 | the target. |
| 126 | In the case of <filename>core-image-sato</filename>, it would lead to | 126 | In the case of <filename>core-image-sato</filename>, it would lead to |
| 127 | <filename>packagegroup-core-x11-sato</filename>, | 127 | <filename>packagegroup-core-x11-sato</filename>, |
| 128 | which in turn leads to recipes like <filename>matchbox-terminal</filename>, | 128 | which in turn leads to recipes like <filename>matchbox-terminal</filename>, |
| 129 | <filename>pcmanfm</filename> and <filename>gthumb</filename>. | 129 | <filename>pcmanfm</filename> and <filename>gthumb</filename>. |
| 130 | These recipes in turn depend on <filename>eglibc</filename> and the toolchain. | 130 | These recipes in turn depend on <filename>eglibc</filename> and the toolchain. |
| 131 | </para> | 131 | </para> |
| 132 | 132 | ||
| 133 | <para> | 133 | <para> |
| 134 | Sometimes a target might have multiple providers. | 134 | Sometimes a target might have multiple providers. |
| 135 | A common example is "virtual/kernel", which is provided by each kernel package. | 135 | A common example is "virtual/kernel", which is provided by each kernel package. |
| 136 | Each machine often selects the best kernel provider by using a line similar to the | 136 | Each machine often selects the best kernel provider by using a line similar to the |
| 137 | following in the machine configuration file: | 137 | following in the machine configuration file: |
| 138 | </para> | 138 | </para> |
| 139 | 139 | ||
| @@ -142,25 +142,25 @@ | |||
| 142 | </literallayout> | 142 | </literallayout> |
| 143 | 143 | ||
| 144 | <para> | 144 | <para> |
| 145 | The default <filename><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></filename> | 145 | The default <filename><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></filename> |
| 146 | is the provider with the same name as the target. | 146 | is the provider with the same name as the target. |
| 147 | </para> | 147 | </para> |
| 148 | 148 | ||
| 149 | <para> | 149 | <para> |
| 150 | Understanding how providers are chosen is made complicated by the fact | 150 | Understanding how providers are chosen is made complicated by the fact |
| 151 | that multiple versions might exist. | 151 | that multiple versions might exist. |
| 152 | BitBake defaults to the highest version of a provider. | 152 | BitBake defaults to the highest version of a provider. |
| 153 | Version comparisons are made using the same method as Debian. | 153 | Version comparisons are made using the same method as Debian. |
| 154 | You can use the | 154 | You can use the |
| 155 | <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename> | 155 | <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename> |
| 156 | variable to specify a particular version (usually in the distro configuration). | 156 | variable to specify a particular version (usually in the distro configuration). |
| 157 | You can influence the order by using the | 157 | You can influence the order by using the |
| 158 | <filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></filename> | 158 | <filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></filename> |
| 159 | variable. | 159 | variable. |
| 160 | By default, files have a preference of "0". | 160 | By default, files have a preference of "0". |
| 161 | Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the | 161 | Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the |
| 162 | package unlikely to be used unless it is explicitly referenced. | 162 | package unlikely to be used unless it is explicitly referenced. |
| 163 | Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the package is used. | 163 | Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the package is used. |
| 164 | <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting. | 164 | <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting. |
| 165 | <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental package | 165 | <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental package |
| 166 | versions until they have undergone sufficient testing to be considered stable. | 166 | versions until they have undergone sufficient testing to be considered stable. |
| @@ -175,23 +175,23 @@ | |||
| 175 | <title>Dependencies</title> | 175 | <title>Dependencies</title> |
| 176 | 176 | ||
| 177 | <para> | 177 | <para> |
| 178 | Each target BitBake builds consists of multiple tasks such as | 178 | Each target BitBake builds consists of multiple tasks such as |
| 179 | <filename>fetch</filename>, <filename>unpack</filename>, | 179 | <filename>fetch</filename>, <filename>unpack</filename>, |
| 180 | <filename>patch</filename>, <filename>configure</filename>, | 180 | <filename>patch</filename>, <filename>configure</filename>, |
| 181 | and <filename>compile</filename>. | 181 | and <filename>compile</filename>. |
| 182 | For best performance on multi-core systems, BitBake considers each task as an independent | 182 | For best performance on multi-core systems, BitBake considers each task as an independent |
| 183 | entity with its own set of dependencies. | 183 | entity with its own set of dependencies. |
| 184 | </para> | 184 | </para> |
| 185 | 185 | ||
| 186 | <para> | 186 | <para> |
| 187 | Dependencies are defined through several variables. | 187 | Dependencies are defined through several variables. |
| 188 | You can find information about variables BitBake uses in the BitBake documentation, | 188 | You can find information about variables BitBake uses in the BitBake documentation, |
| 189 | which is found in the <filename>bitbake/doc/manual</filename> directory within the | 189 | which is found in the <filename>bitbake/doc/manual</filename> directory within the |
| 190 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 190 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 191 | At a basic level, it is sufficient to know that BitBake uses the | 191 | At a basic level, it is sufficient to know that BitBake uses the |
| 192 | <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename> and | 192 | <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename> and |
| 193 | <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variables when | 193 | <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variables when |
| 194 | calculating dependencies. | 194 | calculating dependencies. |
| 195 | </para> | 195 | </para> |
| 196 | </section> | 196 | </section> |
| 197 | 197 | ||
| @@ -199,40 +199,40 @@ | |||
| 199 | <title>The Task List</title> | 199 | <title>The Task List</title> |
| 200 | 200 | ||
| 201 | <para> | 201 | <para> |
| 202 | Based on the generated list of providers and the dependency information, | 202 | Based on the generated list of providers and the dependency information, |
| 203 | BitBake can now calculate exactly what tasks it needs to run and in what | 203 | BitBake can now calculate exactly what tasks it needs to run and in what |
| 204 | order it needs to run them. | 204 | order it needs to run them. |
| 205 | The build now starts with BitBake forking off threads up to the limit set in the | 205 | The build now starts with BitBake forking off threads up to the limit set in the |
| 206 | <filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></filename> variable. | 206 | <filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></filename> variable. |
| 207 | BitBake continues to fork threads as long as there are tasks ready to run, | 207 | BitBake continues to fork threads as long as there are tasks ready to run, |
| 208 | those tasks have all their dependencies met, and the thread threshold has not been | 208 | those tasks have all their dependencies met, and the thread threshold has not been |
| 209 | exceeded. | 209 | exceeded. |
| 210 | </para> | 210 | </para> |
| 211 | 211 | ||
| 212 | <para> | 212 | <para> |
| 213 | It is worth noting that you can greatly speed up the build time by properly setting | 213 | It is worth noting that you can greatly speed up the build time by properly setting |
| 214 | the <filename>BB_NUMBER_THREADS</filename> variable. | 214 | the <filename>BB_NUMBER_THREADS</filename> variable. |
| 215 | See the | 215 | See the |
| 216 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | 216 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" |
| 217 | section in the Yocto Project Quick Start for more information. | 217 | section in the Yocto Project Quick Start for more information. |
| 218 | </para> | 218 | </para> |
| 219 | 219 | ||
| 220 | <para> | 220 | <para> |
| 221 | As each task completes, a timestamp is written to the directory specified by the | 221 | As each task completes, a timestamp is written to the directory specified by the |
| 222 | <filename><link linkend='var-STAMP'>STAMP</link></filename> variable (usually | 222 | <filename><link linkend='var-STAMP'>STAMP</link></filename> variable (usually |
| 223 | <filename>build/tmp/stamps/*/</filename>). | 223 | <filename>build/tmp/stamps/*/</filename>). |
| 224 | On subsequent runs, BitBake looks at the <filename>/build/tmp/stamps</filename> | 224 | On subsequent runs, BitBake looks at the <filename>/build/tmp/stamps</filename> |
| 225 | directory and does not rerun | 225 | directory and does not rerun |
| 226 | tasks that are already completed unless a timestamp is found to be invalid. | 226 | tasks that are already completed unless a timestamp is found to be invalid. |
| 227 | Currently, invalid timestamps are only considered on a per | 227 | Currently, invalid timestamps are only considered on a per |
| 228 | <filename>.bb</filename> file basis. | 228 | <filename>.bb</filename> file basis. |
| 229 | So, for example, if the configure stamp has a timestamp greater than the | 229 | So, for example, if the configure stamp has a timestamp greater than the |
| 230 | compile timestamp for a given target, then the compile task would rerun. | 230 | compile timestamp for a given target, then the compile task would rerun. |
| 231 | Running the compile task again, however, has no effect on other providers | 231 | Running the compile task again, however, has no effect on other providers |
| 232 | that depend on that target. | 232 | that depend on that target. |
| 233 | This behavior could change or become configurable in future versions of BitBake. | 233 | This behavior could change or become configurable in future versions of BitBake. |
| 234 | </para> | 234 | </para> |
| 235 | 235 | ||
| 236 | <note> | 236 | <note> |
| 237 | Some tasks are marked as "nostamp" tasks. | 237 | Some tasks are marked as "nostamp" tasks. |
| 238 | No timestamp file is created when these tasks are run. | 238 | No timestamp file is created when these tasks are run. |
| @@ -245,52 +245,52 @@ | |||
| 245 | 245 | ||
| 246 | <para> | 246 | <para> |
| 247 | Tasks can either be a shell task or a Python task. | 247 | Tasks can either be a shell task or a Python task. |
| 248 | For shell tasks, BitBake writes a shell script to | 248 | For shell tasks, BitBake writes a shell script to |
| 249 | <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script. | 249 | <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script. |
| 250 | The generated shell script contains all the exported variables, and the shell functions | 250 | The generated shell script contains all the exported variables, and the shell functions |
| 251 | with all variables expanded. | 251 | with all variables expanded. |
| 252 | Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. | 252 | Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. |
| 253 | Looking at the expanded shell functions in the run file and the output in the log files | 253 | Looking at the expanded shell functions in the run file and the output in the log files |
| 254 | is a useful debugging technique. | 254 | is a useful debugging technique. |
| 255 | </para> | 255 | </para> |
| 256 | 256 | ||
| 257 | <para> | 257 | <para> |
| 258 | For Python tasks, BitBake executes the task internally and logs information to the | 258 | For Python tasks, BitBake executes the task internally and logs information to the |
| 259 | controlling terminal. | 259 | controlling terminal. |
| 260 | Future versions of BitBake will write the functions to files similar to the way | 260 | Future versions of BitBake will write the functions to files similar to the way |
| 261 | shell tasks are handled. | 261 | shell tasks are handled. |
| 262 | Logging will be handled in way similar to shell tasks as well. | 262 | Logging will be handled in way similar to shell tasks as well. |
| 263 | </para> | 263 | </para> |
| 264 | 264 | ||
| 265 | <para> | 265 | <para> |
| 266 | Once all the tasks have been completed BitBake exits. | 266 | Once all the tasks have been completed BitBake exits. |
| 267 | </para> | 267 | </para> |
| 268 | 268 | ||
| 269 | <para> | 269 | <para> |
| 270 | When running a task, BitBake tightly controls the execution environment | 270 | When running a task, BitBake tightly controls the execution environment |
| 271 | of the build tasks to make sure unwanted contamination from the build machine | 271 | of the build tasks to make sure unwanted contamination from the build machine |
| 272 | cannot influence the build. | 272 | cannot influence the build. |
| 273 | Consequently, if you do want something to get passed into the build | 273 | Consequently, if you do want something to get passed into the build |
| 274 | task's environment, you must take a few steps: | 274 | task's environment, you must take a few steps: |
| 275 | <orderedlist> | 275 | <orderedlist> |
| 276 | <listitem><para>Tell BitBake to load what you want from the environment | 276 | <listitem><para>Tell BitBake to load what you want from the environment |
| 277 | into the data store. | 277 | into the data store. |
| 278 | You can do so through the <filename>BB_ENV_EXTRAWHITE</filename> | 278 | You can do so through the <filename>BB_ENV_EXTRAWHITE</filename> |
| 279 | variable. | 279 | variable. |
| 280 | For example, assume you want to prevent the build system from | 280 | For example, assume you want to prevent the build system from |
| 281 | accessing your <filename>$HOME/.ccache</filename> directory. | 281 | accessing your <filename>$HOME/.ccache</filename> directory. |
| 282 | The following command tells BitBake to load | 282 | The following command tells BitBake to load |
| 283 | <filename>CCACHE_DIR</filename> from the environment into the data | 283 | <filename>CCACHE_DIR</filename> from the environment into the data |
| 284 | store: | 284 | store: |
| 285 | <literallayout class='monospaced'> | 285 | <literallayout class='monospaced'> |
| 286 | export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" | 286 | export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" |
| 287 | </literallayout></para></listitem> | 287 | </literallayout></para></listitem> |
| 288 | <listitem><para>Tell BitBake to export what you have loaded into the | 288 | <listitem><para>Tell BitBake to export what you have loaded into the |
| 289 | environment store to the task environment of every running task. | 289 | environment store to the task environment of every running task. |
| 290 | Loading something from the environment into the data store | 290 | Loading something from the environment into the data store |
| 291 | (previous step) only makes it available in the datastore. | 291 | (previous step) only makes it available in the datastore. |
| 292 | To export it to the task environment of every running task, | 292 | To export it to the task environment of every running task, |
| 293 | use a command similar to the following in your | 293 | use a command similar to the following in your |
| 294 | <filename>local.conf</filename> or distro configuration file: | 294 | <filename>local.conf</filename> or distro configuration file: |
| 295 | <literallayout class='monospaced'> | 295 | <literallayout class='monospaced'> |
| 296 | export CCACHE_DIR | 296 | export CCACHE_DIR |
| @@ -301,8 +301,8 @@ | |||
| 301 | <note> | 301 | <note> |
| 302 | A side effect of the previous steps is that BitBake records the variable | 302 | A side effect of the previous steps is that BitBake records the variable |
| 303 | as a dependency of the build process in things like the shared state | 303 | as a dependency of the build process in things like the shared state |
| 304 | checksums. | 304 | checksums. |
| 305 | If doing so results in unnecessary rebuilds of tasks, you can whitelist the | 305 | If doing so results in unnecessary rebuilds of tasks, you can whitelist the |
| 306 | variable so that the shared state code ignores the dependency when it creates | 306 | variable so that the shared state code ignores the dependency when it creates |
| 307 | checksums. | 307 | checksums. |
| 308 | For information on this process, see the <filename>BB_HASHBASE_WHITELIST</filename> | 308 | For information on this process, see the <filename>BB_HASHBASE_WHITELIST</filename> |
| @@ -383,38 +383,38 @@ Options: | |||
| 383 | <title>Fetchers</title> | 383 | <title>Fetchers</title> |
| 384 | 384 | ||
| 385 | <para> | 385 | <para> |
| 386 | BitBake also contains a set of "fetcher" modules that allow | 386 | BitBake also contains a set of "fetcher" modules that allow |
| 387 | retrieval of source code from various types of sources. | 387 | retrieval of source code from various types of sources. |
| 388 | For example, BitBake can get source code from a disk with the metadata, from websites, | 388 | For example, BitBake can get source code from a disk with the metadata, from websites, |
| 389 | from remote shell accounts or from Source Code Management (SCM) systems | 389 | from remote shell accounts or from Source Code Management (SCM) systems |
| 390 | like <filename>cvs/subversion/git</filename>. | 390 | like <filename>cvs/subversion/git</filename>. |
| 391 | </para> | 391 | </para> |
| 392 | 392 | ||
| 393 | <para> | 393 | <para> |
| 394 | Fetchers are usually triggered by entries in | 394 | Fetchers are usually triggered by entries in |
| 395 | <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>. | 395 | <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>. |
| 396 | You can find information about the options and formats of entries for specific | 396 | You can find information about the options and formats of entries for specific |
| 397 | fetchers in the BitBake manual located in the | 397 | fetchers in the BitBake manual located in the |
| 398 | <filename>bitbake/doc/manual</filename> directory of the | 398 | <filename>bitbake/doc/manual</filename> directory of the |
| 399 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 399 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 400 | </para> | 400 | </para> |
| 401 | 401 | ||
| 402 | <para> | 402 | <para> |
| 403 | One useful feature for certain Source Code Manager (SCM) fetchers is the ability to | 403 | One useful feature for certain Source Code Manager (SCM) fetchers is the ability to |
| 404 | "auto-update" when the upstream SCM changes version. | 404 | "auto-update" when the upstream SCM changes version. |
| 405 | Since this ability requires certain functionality from the SCM, not all | 405 | Since this ability requires certain functionality from the SCM, not all |
| 406 | systems support it. | 406 | systems support it. |
| 407 | Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update". | 407 | Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update". |
| 408 | This feature works using the <filename><link linkend='var-SRCREV'>SRCREV</link></filename> | 408 | This feature works using the <filename><link linkend='var-SRCREV'>SRCREV</link></filename> |
| 409 | variable. | 409 | variable. |
| 410 | See the | 410 | See the |
| 411 | "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-srcrev'>Using an External SCM</ulink>" section | 411 | "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-srcrev'>Using an External SCM</ulink>" section |
| 412 | in the Yocto Project Development Manual for more information. | 412 | in the Yocto Project Development Manual for more information. |
| 413 | </para> | 413 | </para> |
| 414 | 414 | ||
| 415 | </section> | 415 | </section> |
| 416 | 416 | ||
| 417 | </chapter> | 417 | </chapter> |
| 418 | <!-- | 418 | <!-- |
| 419 | vim: expandtab tw=80 ts=4 spell spelllang=en_gb | 419 | vim: expandtab tw=80 ts=4 spell spelllang=en_gb |
| 420 | --> | 420 | --> |
diff --git a/documentation/poky-ref-manual/ref-classes.xml b/documentation/poky-ref-manual/ref-classes.xml index 973d065f58..5ba9811853 100644 --- a/documentation/poky-ref-manual/ref-classes.xml +++ b/documentation/poky-ref-manual/ref-classes.xml | |||
| @@ -6,23 +6,23 @@ | |||
| 6 | <title>Classes</title> | 6 | <title>Classes</title> |
| 7 | 7 | ||
| 8 | <para> | 8 | <para> |
| 9 | Class files are used to abstract common functionality and share it amongst multiple | 9 | Class files are used to abstract common functionality and share it amongst multiple |
| 10 | <filename>.bb</filename> files. | 10 | <filename>.bb</filename> files. |
| 11 | Any metadata usually found in a <filename>.bb</filename> file can also be placed in a class | 11 | Any metadata usually found in a <filename>.bb</filename> file can also be placed in a class |
| 12 | file. | 12 | file. |
| 13 | Class files are identified by the extension <filename>.bbclass</filename> and are usually placed | 13 | Class files are identified by the extension <filename>.bbclass</filename> and are usually placed |
| 14 | in a <filename>classes/</filename> directory beneath the | 14 | in a <filename>classes/</filename> directory beneath the |
| 15 | <filename>meta*/</filename> directory found in the | 15 | <filename>meta*/</filename> directory found in the |
| 16 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 16 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 17 | Class files can also be pointed to by BUILDDIR (e.g. <filename>build/</filename>)in the same way as | 17 | Class files can also be pointed to by BUILDDIR (e.g. <filename>build/</filename>)in the same way as |
| 18 | <filename>.conf</filename> files in the <filename>conf</filename> directory. | 18 | <filename>.conf</filename> files in the <filename>conf</filename> directory. |
| 19 | Class files are searched for in <link linkend='var-BBPATH'><filename>BBPATH</filename></link> | 19 | Class files are searched for in <link linkend='var-BBPATH'><filename>BBPATH</filename></link> |
| 20 | using the same method by which <filename>.conf</filename> files are searched. | 20 | using the same method by which <filename>.conf</filename> files are searched. |
| 21 | </para> | 21 | </para> |
| 22 | 22 | ||
| 23 | <para> | 23 | <para> |
| 24 | In most cases inheriting the class is enough to enable its features, although | 24 | In most cases inheriting the class is enough to enable its features, although |
| 25 | for some classes you might need to set variables or override some of the | 25 | for some classes you might need to set variables or override some of the |
| 26 | default behaviour. | 26 | default behaviour. |
| 27 | </para> | 27 | </para> |
| 28 | 28 | ||
| @@ -30,14 +30,14 @@ | |||
| 30 | <title>The base class - <filename>base.bbclass</filename></title> | 30 | <title>The base class - <filename>base.bbclass</filename></title> |
| 31 | 31 | ||
| 32 | <para> | 32 | <para> |
| 33 | The base class is special in that every <filename>.bb</filename> | 33 | The base class is special in that every <filename>.bb</filename> |
| 34 | file inherits it automatically. | 34 | file inherits it automatically. |
| 35 | This class contains definitions for standard basic | 35 | This class contains definitions for standard basic |
| 36 | tasks such as fetching, unpacking, configuring (empty by default), compiling | 36 | tasks such as fetching, unpacking, configuring (empty by default), compiling |
| 37 | (runs any <filename>Makefile</filename> present), installing (empty by default) and packaging | 37 | (runs any <filename>Makefile</filename> present), installing (empty by default) and packaging |
| 38 | (empty by default). | 38 | (empty by default). |
| 39 | These classes are often overridden or extended by other classes | 39 | These classes are often overridden or extended by other classes |
| 40 | such as <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>. | 40 | such as <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>. |
| 41 | The class also contains some commonly used functions such as <filename>oe_runmake</filename>. | 41 | The class also contains some commonly used functions such as <filename>oe_runmake</filename>. |
| 42 | </para> | 42 | </para> |
| 43 | </section> | 43 | </section> |
| @@ -46,14 +46,14 @@ | |||
| 46 | <title>Autotooled Packages - <filename>autotools.bbclass</filename></title> | 46 | <title>Autotooled Packages - <filename>autotools.bbclass</filename></title> |
| 47 | 47 | ||
| 48 | <para> | 48 | <para> |
| 49 | Autotools (<filename>autoconf</filename>, <filename>automake</filename>, | 49 | Autotools (<filename>autoconf</filename>, <filename>automake</filename>, |
| 50 | and <filename>libtool</filename>) bring standardization. | 50 | and <filename>libtool</filename>) bring standardization. |
| 51 | This class defines a set of tasks (configure, compile etc.) that | 51 | This class defines a set of tasks (configure, compile etc.) that |
| 52 | work for all Autotooled packages. | 52 | work for all Autotooled packages. |
| 53 | It should usually be enough to define a few standard variables | 53 | It should usually be enough to define a few standard variables |
| 54 | and then simply <filename>inherit autotools</filename>. | 54 | and then simply <filename>inherit autotools</filename>. |
| 55 | This class can also work with software that emulates Autotools. | 55 | This class can also work with software that emulates Autotools. |
| 56 | For more information, see the | 56 | For more information, see the |
| 57 | "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>" | 57 | "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>" |
| 58 | section in the Yocto Project Development Manual. | 58 | section in the Yocto Project Development Manual. |
| 59 | </para> | 59 | </para> |
| @@ -62,19 +62,19 @@ | |||
| 62 | It's useful to have some idea of how the tasks defined by this class work | 62 | It's useful to have some idea of how the tasks defined by this class work |
| 63 | and what they do behind the scenes. | 63 | and what they do behind the scenes. |
| 64 | <itemizedlist> | 64 | <itemizedlist> |
| 65 | <listitem><para><filename>do_configure</filename> ‐ regenerates the | 65 | <listitem><para><filename>do_configure</filename> ‐ regenerates the |
| 66 | configure script (using <filename>autoreconf</filename>) and then launches it | 66 | configure script (using <filename>autoreconf</filename>) and then launches it |
| 67 | with a standard set of arguments used during cross-compilation. | 67 | with a standard set of arguments used during cross-compilation. |
| 68 | You can pass additional parameters to <filename>configure</filename> through the | 68 | You can pass additional parameters to <filename>configure</filename> through the |
| 69 | <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable. | 69 | <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable. |
| 70 | </para></listitem> | 70 | </para></listitem> |
| 71 | <listitem><para><filename>do_compile</filename> ‐ runs <filename>make</filename> with | 71 | <listitem><para><filename>do_compile</filename> ‐ runs <filename>make</filename> with |
| 72 | arguments that specify the compiler and linker. | 72 | arguments that specify the compiler and linker. |
| 73 | You can pass additional arguments through | 73 | You can pass additional arguments through |
| 74 | the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable. | 74 | the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable. |
| 75 | </para></listitem> | 75 | </para></listitem> |
| 76 | <listitem><para><filename>do_install</filename> ‐ runs <filename>make install</filename> | 76 | <listitem><para><filename>do_install</filename> ‐ runs <filename>make install</filename> |
| 77 | and passes a DESTDIR option, which takes its value from the standard | 77 | and passes a DESTDIR option, which takes its value from the standard |
| 78 | <filename><link linkend='var-DESTDIR'>DESTDIR</link></filename> variable. | 78 | <filename><link linkend='var-DESTDIR'>DESTDIR</link></filename> variable. |
| 79 | </para></listitem> | 79 | </para></listitem> |
| 80 | </itemizedlist> | 80 | </itemizedlist> |
| @@ -85,28 +85,28 @@ | |||
| 85 | <title>Alternatives - <filename>update-alternatives.bbclass</filename></title> | 85 | <title>Alternatives - <filename>update-alternatives.bbclass</filename></title> |
| 86 | 86 | ||
| 87 | <para> | 87 | <para> |
| 88 | Several programs can fulfill the same or similar function and be installed with the same name. | 88 | Several programs can fulfill the same or similar function and be installed with the same name. |
| 89 | For example, the <filename>ar</filename> command is available from the | 89 | For example, the <filename>ar</filename> command is available from the |
| 90 | <filename>busybox</filename>, <filename>binutils</filename> and | 90 | <filename>busybox</filename>, <filename>binutils</filename> and |
| 91 | <filename>elfutils</filename> packages. | 91 | <filename>elfutils</filename> packages. |
| 92 | The <filename>update-alternatives.bbclass</filename> class handles renaming the | 92 | The <filename>update-alternatives.bbclass</filename> class handles renaming the |
| 93 | binaries so that multiple packages can be installed without conflicts. | 93 | binaries so that multiple packages can be installed without conflicts. |
| 94 | The <filename>ar</filename> command still works regardless of which packages are installed | 94 | The <filename>ar</filename> command still works regardless of which packages are installed |
| 95 | or subsequently removed. | 95 | or subsequently removed. |
| 96 | The class renames the conflicting binary in each package and symlinks the highest | 96 | The class renames the conflicting binary in each package and symlinks the highest |
| 97 | priority binary during installation or removal of packages. | 97 | priority binary during installation or removal of packages. |
| 98 | </para> | 98 | </para> |
| 99 | <para> | 99 | <para> |
| 100 | Four variables control this class: | 100 | Four variables control this class: |
| 101 | <itemizedlist> | 101 | <itemizedlist> |
| 102 | <listitem><para><filename>ALTERNATIVE_NAME</filename> ‐ The name of the | 102 | <listitem><para><filename>ALTERNATIVE_NAME</filename> ‐ The name of the |
| 103 | binary that is replaced (<filename>ar</filename> in this example).</para></listitem> | 103 | binary that is replaced (<filename>ar</filename> in this example).</para></listitem> |
| 104 | <listitem><para><filename>ALTERNATIVE_LINK</filename> ‐ The path to | 104 | <listitem><para><filename>ALTERNATIVE_LINK</filename> ‐ The path to |
| 105 | the resulting binary (<filename>/bin/ar</filename> in this example).</para></listitem> | 105 | the resulting binary (<filename>/bin/ar</filename> in this example).</para></listitem> |
| 106 | <listitem><para><filename>ALTERNATIVE_PATH</filename> ‐ The path to the | 106 | <listitem><para><filename>ALTERNATIVE_PATH</filename> ‐ The path to the |
| 107 | real binary (<filename>/usr/bin/ar.binutils</filename> in this example).</para></listitem> | 107 | real binary (<filename>/usr/bin/ar.binutils</filename> in this example).</para></listitem> |
| 108 | <listitem><para><filename>ALTERNATIVE_PRIORITY</filename> ‐ The priority of | 108 | <listitem><para><filename>ALTERNATIVE_PRIORITY</filename> ‐ The priority of |
| 109 | the binary. | 109 | the binary. |
| 110 | The version with the most features should have the highest priority.</para></listitem> | 110 | The version with the most features should have the highest priority.</para></listitem> |
| 111 | </itemizedlist> | 111 | </itemizedlist> |
| 112 | </para> | 112 | </para> |
| @@ -120,12 +120,12 @@ | |||
| 120 | <title>Initscripts - <filename>update-rc.d.bbclass</filename></title> | 120 | <title>Initscripts - <filename>update-rc.d.bbclass</filename></title> |
| 121 | 121 | ||
| 122 | <para> | 122 | <para> |
| 123 | This class uses <filename>update-rc.d</filename> to safely install an | 123 | This class uses <filename>update-rc.d</filename> to safely install an |
| 124 | initialization script on behalf of the package. | 124 | initialization script on behalf of the package. |
| 125 | The OpenEmbedded build system takes care of details such as making sure the script is stopped before | 125 | The OpenEmbedded build system takes care of details such as making sure the script is stopped before |
| 126 | a package is removed and started when the package is installed. | 126 | a package is removed and started when the package is installed. |
| 127 | Three variables control this class: | 127 | Three variables control this class: |
| 128 | <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>, | 128 | <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>, |
| 129 | <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and | 129 | <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and |
| 130 | <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>. | 130 | <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>. |
| 131 | See the variable links for details. | 131 | See the variable links for details. |
| @@ -137,16 +137,16 @@ | |||
| 137 | 137 | ||
| 138 | <para> | 138 | <para> |
| 139 | Before <filename>pkg-config</filename> had become widespread, libraries shipped shell | 139 | Before <filename>pkg-config</filename> had become widespread, libraries shipped shell |
| 140 | scripts to give information about the libraries and include paths needed | 140 | scripts to give information about the libraries and include paths needed |
| 141 | to build software (usually named <filename>LIBNAME-config</filename>). | 141 | to build software (usually named <filename>LIBNAME-config</filename>). |
| 142 | This class assists any recipe using such scripts. | 142 | This class assists any recipe using such scripts. |
| 143 | </para> | 143 | </para> |
| 144 | 144 | ||
| 145 | <para> | 145 | <para> |
| 146 | During staging, BitBake installs such scripts into the | 146 | During staging, BitBake installs such scripts into the |
| 147 | <filename>sysroots/</filename> directory. | 147 | <filename>sysroots/</filename> directory. |
| 148 | BitBake also changes all paths to point into the <filename>sysroots/</filename> | 148 | BitBake also changes all paths to point into the <filename>sysroots/</filename> |
| 149 | directory so all builds that use the script will use the correct | 149 | directory so all builds that use the script will use the correct |
| 150 | directories for the cross compiling layout. | 150 | directories for the cross compiling layout. |
| 151 | </para> | 151 | </para> |
| 152 | </section> | 152 | </section> |
| @@ -171,7 +171,7 @@ | |||
| 171 | 171 | ||
| 172 | <para> | 172 | <para> |
| 173 | During staging, BitBake installs <filename>pkg-config</filename> data into the | 173 | During staging, BitBake installs <filename>pkg-config</filename> data into the |
| 174 | <filename>sysroots/</filename> directory. | 174 | <filename>sysroots/</filename> directory. |
| 175 | By making use of sysroot functionality within <filename>pkg-config</filename>, | 175 | By making use of sysroot functionality within <filename>pkg-config</filename>, |
| 176 | this class no longer has to manipulate the files. | 176 | this class no longer has to manipulate the files. |
| 177 | </para> | 177 | </para> |
| @@ -183,14 +183,14 @@ | |||
| 183 | <para> | 183 | <para> |
| 184 | Many software licenses require that source files be provided along with the binaries. | 184 | Many software licenses require that source files be provided along with the binaries. |
| 185 | To simplify this process, two classes were created: | 185 | To simplify this process, two classes were created: |
| 186 | <filename>src_distribute.bbclass</filename> and | 186 | <filename>src_distribute.bbclass</filename> and |
| 187 | <filename>src_distribute_local.bbclass</filename>. | 187 | <filename>src_distribute_local.bbclass</filename>. |
| 188 | </para> | 188 | </para> |
| 189 | 189 | ||
| 190 | <para> | 190 | <para> |
| 191 | The results of these classes are <filename>tmp/deploy/source/</filename> | 191 | The results of these classes are <filename>tmp/deploy/source/</filename> |
| 192 | subdirs with sources sorted by | 192 | subdirs with sources sorted by |
| 193 | <filename><link linkend='var-LICENSE'>LICENSE</link></filename> field. | 193 | <filename><link linkend='var-LICENSE'>LICENSE</link></filename> field. |
| 194 | If recipes list few licenses (or have entries like "Bitstream Vera"), | 194 | If recipes list few licenses (or have entries like "Bitstream Vera"), |
| 195 | the source archive is placed in each license directory. | 195 | the source archive is placed in each license directory. |
| 196 | </para> | 196 | </para> |
| @@ -198,11 +198,11 @@ | |||
| 198 | <para> | 198 | <para> |
| 199 | This class operates using three modes: | 199 | This class operates using three modes: |
| 200 | <itemizedlist> | 200 | <itemizedlist> |
| 201 | <listitem><para><emphasis>copy:</emphasis> Copies the files to the | 201 | <listitem><para><emphasis>copy:</emphasis> Copies the files to the |
| 202 | distribute directory.</para></listitem> | 202 | distribute directory.</para></listitem> |
| 203 | <listitem><para><emphasis>symlink:</emphasis> Symlinks the files to the | 203 | <listitem><para><emphasis>symlink:</emphasis> Symlinks the files to the |
| 204 | distribute directory.</para></listitem> | 204 | distribute directory.</para></listitem> |
| 205 | <listitem><para><emphasis>move+symlink:</emphasis> Moves the files into | 205 | <listitem><para><emphasis>move+symlink:</emphasis> Moves the files into |
| 206 | the distribute directory and then symlinks them back.</para></listitem> | 206 | the distribute directory and then symlinks them back.</para></listitem> |
| 207 | </itemizedlist> | 207 | </itemizedlist> |
| 208 | </para> | 208 | </para> |
| @@ -213,11 +213,11 @@ | |||
| 213 | 213 | ||
| 214 | <para> | 214 | <para> |
| 215 | Recipes for Perl modules are simple. | 215 | Recipes for Perl modules are simple. |
| 216 | These recipes usually only need to point to the source's archive and then inherit the | 216 | These recipes usually only need to point to the source's archive and then inherit the |
| 217 | proper <filename>.bbclass</filename> file. | 217 | proper <filename>.bbclass</filename> file. |
| 218 | Building is split into two methods depending on which method the module authors used. | 218 | Building is split into two methods depending on which method the module authors used. |
| 219 | </para> | 219 | </para> |
| 220 | 220 | ||
| 221 | <para> | 221 | <para> |
| 222 | Modules that use old <filename>Makefile.PL</filename>-based build system require | 222 | Modules that use old <filename>Makefile.PL</filename>-based build system require |
| 223 | <filename>cpan.bbclass</filename> in their recipes. | 223 | <filename>cpan.bbclass</filename> in their recipes. |
| @@ -240,12 +240,12 @@ | |||
| 240 | </para> | 240 | </para> |
| 241 | 241 | ||
| 242 | <para> | 242 | <para> |
| 243 | Extensions that use an Autotools-based build system require Autotools and | 243 | Extensions that use an Autotools-based build system require Autotools and |
| 244 | <filename>distutils</filename>-based <filename>.bbclasse</filename> files in their recipes. | 244 | <filename>distutils</filename>-based <filename>.bbclasse</filename> files in their recipes. |
| 245 | </para> | 245 | </para> |
| 246 | 246 | ||
| 247 | <para> | 247 | <para> |
| 248 | Extensions that use <filename>distutils</filename>-based build systems require | 248 | Extensions that use <filename>distutils</filename>-based build systems require |
| 249 | <filename>distutils.bbclass</filename> in their recipes. | 249 | <filename>distutils.bbclass</filename> in their recipes. |
| 250 | </para> | 250 | </para> |
| 251 | </section> | 251 | </section> |
| @@ -254,10 +254,10 @@ | |||
| 254 | <title>Developer Shell - <filename>devshell.bbclass</filename></title> | 254 | <title>Developer Shell - <filename>devshell.bbclass</filename></title> |
| 255 | 255 | ||
| 256 | <para> | 256 | <para> |
| 257 | This class adds the <filename>devshell</filename> task. | 257 | This class adds the <filename>devshell</filename> task. |
| 258 | Distribution policy dictates whether to include this class. | 258 | Distribution policy dictates whether to include this class. |
| 259 | See the | 259 | See the |
| 260 | "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section | 260 | "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section |
| 261 | in the Yocto Project Development Manual for more information about using <filename>devshell</filename>. | 261 | in the Yocto Project Development Manual for more information about using <filename>devshell</filename>. |
| 262 | </para> | 262 | </para> |
| 263 | </section> | 263 | </section> |
| @@ -266,16 +266,16 @@ | |||
| 266 | <title>Package Groups - <filename>packagegroup.bbclass</filename></title> | 266 | <title>Package Groups - <filename>packagegroup.bbclass</filename></title> |
| 267 | 267 | ||
| 268 | <para> | 268 | <para> |
| 269 | This class sets default values appropriate for package group recipes (such as | 269 | This class sets default values appropriate for package group recipes (such as |
| 270 | <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>, | 270 | <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>, |
| 271 | <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>, | 271 | <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>, |
| 272 | <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>, | 272 | <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>, |
| 273 | and so forth. | 273 | and so forth. |
| 274 | It is highly recommended that all package group recipes inherit this class. | 274 | It is highly recommended that all package group recipes inherit this class. |
| 275 | </para> | 275 | </para> |
| 276 | <para> | 276 | <para> |
| 277 | For information on how to use this class, see the | 277 | For information on how to use this class, see the |
| 278 | "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Tasks</ulink>" | 278 | "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Tasks</ulink>" |
| 279 | section in the Yocto Project Development Manual. | 279 | section in the Yocto Project Development Manual. |
| 280 | </para> | 280 | </para> |
| 281 | <para> | 281 | <para> |
| @@ -289,41 +289,41 @@ | |||
| 289 | 289 | ||
| 290 | <para> | 290 | <para> |
| 291 | The packaging classes add support for generating packages from a build's | 291 | The packaging classes add support for generating packages from a build's |
| 292 | output. | 292 | output. |
| 293 | The core generic functionality is in <filename>package.bbclass</filename>. | 293 | The core generic functionality is in <filename>package.bbclass</filename>. |
| 294 | The code specific to particular package types is contained in various sub-classes such as | 294 | The code specific to particular package types is contained in various sub-classes such as |
| 295 | <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>, | 295 | <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>, |
| 296 | and <filename>package_rpm.bbclass</filename>. | 296 | and <filename>package_rpm.bbclass</filename>. |
| 297 | Most users will want one or more of these classes. | 297 | Most users will want one or more of these classes. |
| 298 | </para> | 298 | </para> |
| 299 | 299 | ||
| 300 | <para> | 300 | <para> |
| 301 | You can control the list of resulting package formats by using the | 301 | You can control the list of resulting package formats by using the |
| 302 | <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename> | 302 | <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename> |
| 303 | variable defined in the <filename>local.conf</filename> configuration file, | 303 | variable defined in the <filename>local.conf</filename> configuration file, |
| 304 | which is located in the <filename>conf</filename> folder of the | 304 | which is located in the <filename>conf</filename> folder of the |
| 305 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 305 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 306 | When defining the variable, you can specify one or more package types. | 306 | When defining the variable, you can specify one or more package types. |
| 307 | Since images are generated from packages, a packaging class is | 307 | Since images are generated from packages, a packaging class is |
| 308 | needed to enable image generation. | 308 | needed to enable image generation. |
| 309 | The first class listed in this variable is used for image generation. | 309 | The first class listed in this variable is used for image generation. |
| 310 | </para> | 310 | </para> |
| 311 | 311 | ||
| 312 | <para> | 312 | <para> |
| 313 | The package class you choose can affect build-time performance and has space | 313 | The package class you choose can affect build-time performance and has space |
| 314 | ramifications. | 314 | ramifications. |
| 315 | In general, building a package with RPM takes about thirty percent more time as | 315 | In general, building a package with RPM takes about thirty percent more time as |
| 316 | compared to using IPK to build the same or similar package. | 316 | compared to using IPK to build the same or similar package. |
| 317 | This comparison takes into account a complete build of the package with all | 317 | This comparison takes into account a complete build of the package with all |
| 318 | dependencies previously built. | 318 | dependencies previously built. |
| 319 | The reason for this discrepancy is because the RPM package manager creates and | 319 | The reason for this discrepancy is because the RPM package manager creates and |
| 320 | processes more metadata than the IPK package manager. | 320 | processes more metadata than the IPK package manager. |
| 321 | Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename> | 321 | Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename> |
| 322 | to "package_ipk" if you are building smaller systems. | 322 | to "package_ipk" if you are building smaller systems. |
| 323 | </para> | 323 | </para> |
| 324 | 324 | ||
| 325 | <para> | 325 | <para> |
| 326 | Keep in mind, however, that RPM starts to provide more abilities than IPK due to | 326 | Keep in mind, however, that RPM starts to provide more abilities than IPK due to |
| 327 | the fact that it processes more metadata. | 327 | the fact that it processes more metadata. |
| 328 | For example, this information includes individual file types, file checksum generation | 328 | For example, this information includes individual file types, file checksum generation |
| 329 | and evaluation on install, sparse file support, conflict detection and resolution | 329 | and evaluation on install, sparse file support, conflict detection and resolution |
| @@ -332,12 +332,12 @@ | |||
| 332 | 332 | ||
| 333 | <para> | 333 | <para> |
| 334 | Another consideration for packages built using the RPM package manager is space. | 334 | Another consideration for packages built using the RPM package manager is space. |
| 335 | For smaller systems, the extra space used for the Berkley Database and the amount | 335 | For smaller systems, the extra space used for the Berkley Database and the amount |
| 336 | of metadata can affect your ability to do on-device upgrades. | 336 | of metadata can affect your ability to do on-device upgrades. |
| 337 | </para> | 337 | </para> |
| 338 | 338 | ||
| 339 | <para> | 339 | <para> |
| 340 | You can find additional information on the effects of the package class at these | 340 | You can find additional information on the effects of the package class at these |
| 341 | two Yocto Project mailing list links: | 341 | two Yocto Project mailing list links: |
| 342 | <itemizedlist> | 342 | <itemizedlist> |
| 343 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'> | 343 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'> |
| @@ -352,24 +352,24 @@ | |||
| 352 | <title>Building kernels - <filename>kernel.bbclass</filename></title> | 352 | <title>Building kernels - <filename>kernel.bbclass</filename></title> |
| 353 | 353 | ||
| 354 | <para> | 354 | <para> |
| 355 | This class handles building Linux kernels. | 355 | This class handles building Linux kernels. |
| 356 | The class contains code to build all kernel trees. | 356 | The class contains code to build all kernel trees. |
| 357 | All needed headers are staged into the | 357 | All needed headers are staged into the |
| 358 | <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename> | 358 | <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename> |
| 359 | directory to allow out-of-tree module builds using <filename>module.bbclass</filename>. | 359 | directory to allow out-of-tree module builds using <filename>module.bbclass</filename>. |
| 360 | </para> | 360 | </para> |
| 361 | 361 | ||
| 362 | <para> | 362 | <para> |
| 363 | This means that each built kernel module is packaged separately and inter-module | 363 | This means that each built kernel module is packaged separately and inter-module |
| 364 | dependencies are created by parsing the <filename>modinfo</filename> output. | 364 | dependencies are created by parsing the <filename>modinfo</filename> output. |
| 365 | If all modules are required, then installing the <filename>kernel-modules</filename> | 365 | If all modules are required, then installing the <filename>kernel-modules</filename> |
| 366 | package installs all packages with modules and various other kernel packages | 366 | package installs all packages with modules and various other kernel packages |
| 367 | such as <filename>kernel-vmlinux</filename>. | 367 | such as <filename>kernel-vmlinux</filename>. |
| 368 | </para> | 368 | </para> |
| 369 | 369 | ||
| 370 | <para> | 370 | <para> |
| 371 | Various other classes are used by the kernel and module classes internally including | 371 | Various other classes are used by the kernel and module classes internally including |
| 372 | <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>, | 372 | <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>, |
| 373 | <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>. | 373 | <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>. |
| 374 | </para> | 374 | </para> |
| 375 | </section> | 375 | </section> |
| @@ -378,9 +378,9 @@ | |||
| 378 | <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title> | 378 | <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title> |
| 379 | 379 | ||
| 380 | <para> | 380 | <para> |
| 381 | These classes add support for creating images in several formats. | 381 | These classes add support for creating images in several formats. |
| 382 | First, the root filesystem is created from packages using | 382 | First, the root filesystem is created from packages using |
| 383 | one of the <filename>rootfs_*.bbclass</filename> | 383 | one of the <filename>rootfs_*.bbclass</filename> |
| 384 | files (depending on the package format used) and then the image is created. | 384 | files (depending on the package format used) and then the image is created. |
| 385 | </para> | 385 | </para> |
| 386 | 386 | ||
| @@ -389,7 +389,7 @@ | |||
| 389 | variable controls the types of images to generate. | 389 | variable controls the types of images to generate. |
| 390 | </para> | 390 | </para> |
| 391 | 391 | ||
| 392 | <para> | 392 | <para> |
| 393 | The <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename> | 393 | The <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename> |
| 394 | variable controls the list of packages to install into the image. | 394 | variable controls the list of packages to install into the image. |
| 395 | </para> | 395 | </para> |
| @@ -399,11 +399,11 @@ | |||
| 399 | <title>Host System sanity checks - <filename>sanity.bbclass</filename></title> | 399 | <title>Host System sanity checks - <filename>sanity.bbclass</filename></title> |
| 400 | 400 | ||
| 401 | <para> | 401 | <para> |
| 402 | This class checks to see if prerequisite software is present so that | 402 | This class checks to see if prerequisite software is present so that |
| 403 | users can be notified of potential problems that might affect their build. | 403 | users can be notified of potential problems that might affect their build. |
| 404 | The class also performs basic user configuration checks from | 404 | The class also performs basic user configuration checks from |
| 405 | the <filename>local.conf</filename> configuration file to | 405 | the <filename>local.conf</filename> configuration file to |
| 406 | prevent common mistakes that cause build failures. | 406 | prevent common mistakes that cause build failures. |
| 407 | Distribution policy usually determines whether to include this class. | 407 | Distribution policy usually determines whether to include this class. |
| 408 | </para> | 408 | </para> |
| 409 | </section> | 409 | </section> |
| @@ -420,14 +420,14 @@ | |||
| 420 | </para> | 420 | </para> |
| 421 | 421 | ||
| 422 | <para> | 422 | <para> |
| 423 | You can configure the sanity checks so that specific test failures either raise a warning or | 423 | You can configure the sanity checks so that specific test failures either raise a warning or |
| 424 | an error message. | 424 | an error message. |
| 425 | Typically, failures for new tests generate a warning. | 425 | Typically, failures for new tests generate a warning. |
| 426 | Subsequent failures for the same test would then generate an error message | 426 | Subsequent failures for the same test would then generate an error message |
| 427 | once the metadata is in a known and good condition. | 427 | once the metadata is in a known and good condition. |
| 428 | You use the <filename>WARN_QA</filename> variable to specify tests for which you | 428 | You use the <filename>WARN_QA</filename> variable to specify tests for which you |
| 429 | want to generate a warning message on failure. | 429 | want to generate a warning message on failure. |
| 430 | You use the <filename>ERROR_QA</filename> variable to specify tests for which you | 430 | You use the <filename>ERROR_QA</filename> variable to specify tests for which you |
| 431 | want to generate an error message on failure. | 431 | want to generate an error message on failure. |
| 432 | </para> | 432 | </para> |
| 433 | 433 | ||
| @@ -436,41 +436,41 @@ | |||
| 436 | and <filename>ERROR_QA</filename> variables: | 436 | and <filename>ERROR_QA</filename> variables: |
| 437 | <itemizedlist> | 437 | <itemizedlist> |
| 438 | <listitem><para><emphasis><filename>ldflags:</filename></emphasis> | 438 | <listitem><para><emphasis><filename>ldflags:</filename></emphasis> |
| 439 | Ensures that the binaries were linked with the | 439 | Ensures that the binaries were linked with the |
| 440 | <filename>LDFLAGS</filename> options provided by the build system. | 440 | <filename>LDFLAGS</filename> options provided by the build system. |
| 441 | If this test fails, check that the <filename>LDFLAGS</filename> variable | 441 | If this test fails, check that the <filename>LDFLAGS</filename> variable |
| 442 | is being passed to the linker command.</para></listitem> | 442 | is being passed to the linker command.</para></listitem> |
| 443 | <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis> | 443 | <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis> |
| 444 | Checks for dynamic library load paths (rpaths) in the binaries that | 444 | Checks for dynamic library load paths (rpaths) in the binaries that |
| 445 | by default on a standard system are searched by the linker (e.g. | 445 | by default on a standard system are searched by the linker (e.g. |
| 446 | <filename>/lib</filename> and <filename>/usr/lib</filename>). | 446 | <filename>/lib</filename> and <filename>/usr/lib</filename>). |
| 447 | While these paths will not cause any breakage, they do waste space and | 447 | While these paths will not cause any breakage, they do waste space and |
| 448 | are unnecessary.</para></listitem> | 448 | are unnecessary.</para></listitem> |
| 449 | <listitem><para><emphasis><filename>rpaths:</filename></emphasis> | 449 | <listitem><para><emphasis><filename>rpaths:</filename></emphasis> |
| 450 | Checks for rpaths in the binaries that contain build system paths such | 450 | Checks for rpaths in the binaries that contain build system paths such |
| 451 | as <filename>TMPDIR</filename>. | 451 | as <filename>TMPDIR</filename>. |
| 452 | If this test fails, bad <filename>-rpath</filename> options are being | 452 | If this test fails, bad <filename>-rpath</filename> options are being |
| 453 | passed to the linker commands and your binaries have potential security | 453 | passed to the linker commands and your binaries have potential security |
| 454 | issues.</para></listitem> | 454 | issues.</para></listitem> |
| 455 | <listitem><para><emphasis><filename>dev-so:</filename></emphasis> | 455 | <listitem><para><emphasis><filename>dev-so:</filename></emphasis> |
| 456 | Checks that the <filename>.so</filename> symbolic links are in the | 456 | Checks that the <filename>.so</filename> symbolic links are in the |
| 457 | <filename>-dev</filename> package and not in any of the other packages. | 457 | <filename>-dev</filename> package and not in any of the other packages. |
| 458 | In general, these symlinks are only useful for development purposes. | 458 | In general, these symlinks are only useful for development purposes. |
| 459 | Thus, the <filename>-dev</filename> package is the correct location for | 459 | Thus, the <filename>-dev</filename> package is the correct location for |
| 460 | them. | 460 | them. |
| 461 | Some very rare cases do exist for dynamically loaded modules where | 461 | Some very rare cases do exist for dynamically loaded modules where |
| 462 | these symlinks are needed instead in the main package. | 462 | these symlinks are needed instead in the main package. |
| 463 | </para></listitem> | 463 | </para></listitem> |
| 464 | <listitem><para><emphasis><filename>debug-files:</filename></emphasis> | 464 | <listitem><para><emphasis><filename>debug-files:</filename></emphasis> |
| 465 | Checks for <filename>.debug</filename> directories in anything but the | 465 | Checks for <filename>.debug</filename> directories in anything but the |
| 466 | <filename>-dbg</filename> package. | 466 | <filename>-dbg</filename> package. |
| 467 | The debug files should all be in the <filename>-dbg</filename> package. | 467 | The debug files should all be in the <filename>-dbg</filename> package. |
| 468 | Thus, anything packaged elsewhere is incorrect packaging.</para></listitem> | 468 | Thus, anything packaged elsewhere is incorrect packaging.</para></listitem> |
| 469 | <listitem><para><emphasis><filename>arch:</filename></emphasis> | 469 | <listitem><para><emphasis><filename>arch:</filename></emphasis> |
| 470 | Checks the Executable and Linkable Format (ELF) type, bit size and endianness | 470 | Checks the Executable and Linkable Format (ELF) type, bit size and endianness |
| 471 | of any binaries to ensure it matches the target architecture. | 471 | of any binaries to ensure it matches the target architecture. |
| 472 | This test fails if any binaries don't match the type since there would be an | 472 | This test fails if any binaries don't match the type since there would be an |
| 473 | incompatibility. | 473 | incompatibility. |
| 474 | Sometimes software, like bootloaders, might need to bypass this check. | 474 | Sometimes software, like bootloaders, might need to bypass this check. |
| 475 | </para></listitem> | 475 | </para></listitem> |
| 476 | <listitem><para><emphasis><filename>debug-deps:</filename></emphasis> | 476 | <listitem><para><emphasis><filename>debug-deps:</filename></emphasis> |
| @@ -478,24 +478,24 @@ | |||
| 478 | <filename>-dbg</filename> packages and not on any other types of packages, | 478 | <filename>-dbg</filename> packages and not on any other types of packages, |
| 479 | which would cause a packaging bug.</para></listitem> | 479 | which would cause a packaging bug.</para></listitem> |
| 480 | <listitem><para><emphasis><filename>dev-deps:</filename></emphasis> | 480 | <listitem><para><emphasis><filename>dev-deps:</filename></emphasis> |
| 481 | Checks that <filename>-dev</filename> packages only depend on other | 481 | Checks that <filename>-dev</filename> packages only depend on other |
| 482 | <filename>-dev</filename> packages and not on any other types of packages, | 482 | <filename>-dev</filename> packages and not on any other types of packages, |
| 483 | which would be a packaging bug.</para></listitem> | 483 | which would be a packaging bug.</para></listitem> |
| 484 | <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis> | 484 | <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis> |
| 485 | Checks <filename>.pc</filename> files for any | 485 | Checks <filename>.pc</filename> files for any |
| 486 | <filename>TMPDIR/WORKDIR</filename> paths. | 486 | <filename>TMPDIR/WORKDIR</filename> paths. |
| 487 | Any <filename>.pc</filename> file containing these paths is incorrect | 487 | Any <filename>.pc</filename> file containing these paths is incorrect |
| 488 | since <filename>pkg-config</filename> itself adds the correct sysroot prefix | 488 | since <filename>pkg-config</filename> itself adds the correct sysroot prefix |
| 489 | when the files are accessed.</para></listitem> | 489 | when the files are accessed.</para></listitem> |
| 490 | <listitem><para><emphasis><filename>la:</filename></emphasis> | 490 | <listitem><para><emphasis><filename>la:</filename></emphasis> |
| 491 | Checks <filename>.la</filename> files for any <filename>TMPDIR</filename> | 491 | Checks <filename>.la</filename> files for any <filename>TMPDIR</filename> |
| 492 | paths. | 492 | paths. |
| 493 | Any <filename>.la</filename> file continaing these paths is incorrect since | 493 | Any <filename>.la</filename> file continaing these paths is incorrect since |
| 494 | <filename>libtool</filename> adds the correct sysroot prefix when using the | 494 | <filename>libtool</filename> adds the correct sysroot prefix when using the |
| 495 | files automatically itself.</para></listitem> | 495 | files automatically itself.</para></listitem> |
| 496 | <listitem><para><emphasis><filename>desktop:</filename></emphasis> | 496 | <listitem><para><emphasis><filename>desktop:</filename></emphasis> |
| 497 | Runs the <filename>desktop-file-validate</filename> program against any | 497 | Runs the <filename>desktop-file-validate</filename> program against any |
| 498 | <filename>.desktop</filename> files to validate their contents against | 498 | <filename>.desktop</filename> files to validate their contents against |
| 499 | the specification for <filename>.desktop</filename> files.</para></listitem> | 499 | the specification for <filename>.desktop</filename> files.</para></listitem> |
| 500 | </itemizedlist> | 500 | </itemizedlist> |
| 501 | </para> | 501 | </para> |
| @@ -511,17 +511,17 @@ | |||
| 511 | still make the correct values available. | 511 | still make the correct values available. |
| 512 | The <filename><link linkend='structure-meta-site'>meta/site directory</link></filename> | 512 | The <filename><link linkend='structure-meta-site'>meta/site directory</link></filename> |
| 513 | contains test results sorted into different categories such as architecture, endianness, and | 513 | contains test results sorted into different categories such as architecture, endianness, and |
| 514 | the <filename>libc</filename> used. | 514 | the <filename>libc</filename> used. |
| 515 | Site information provides a list of files containing data relevant to | 515 | Site information provides a list of files containing data relevant to |
| 516 | the current build in the | 516 | the current build in the |
| 517 | <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable | 517 | <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable |
| 518 | that Autotools automatically picks up. | 518 | that Autotools automatically picks up. |
| 519 | </para> | 519 | </para> |
| 520 | 520 | ||
| 521 | <para> | 521 | <para> |
| 522 | The class also provides variables like | 522 | The class also provides variables like |
| 523 | <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename> | 523 | <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename> |
| 524 | and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename> | 524 | and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename> |
| 525 | that can be used elsewhere in the metadata. | 525 | that can be used elsewhere in the metadata. |
| 526 | </para> | 526 | </para> |
| 527 | 527 | ||
| @@ -534,14 +534,14 @@ | |||
| 534 | <title>Adding Users - <filename>useradd.bbclass</filename></title> | 534 | <title>Adding Users - <filename>useradd.bbclass</filename></title> |
| 535 | 535 | ||
| 536 | <para> | 536 | <para> |
| 537 | If you have packages that install files that are owned by custom users or groups, | 537 | If you have packages that install files that are owned by custom users or groups, |
| 538 | you can use this class to specify those packages and associate the users and groups | 538 | you can use this class to specify those packages and associate the users and groups |
| 539 | with those packages. | 539 | with those packages. |
| 540 | The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename> | 540 | The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename> |
| 541 | recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | 541 | recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> |
| 542 | provides a simple exmample that shows how to add three | 542 | provides a simple exmample that shows how to add three |
| 543 | users and groups to two packages. | 543 | users and groups to two packages. |
| 544 | See the <filename>useradd-example.bb</filename> for more information on how to | 544 | See the <filename>useradd-example.bb</filename> for more information on how to |
| 545 | use this class. | 545 | use this class. |
| 546 | </para> | 546 | </para> |
| 547 | </section> | 547 | </section> |
| @@ -550,33 +550,33 @@ | |||
| 550 | <title>Using External Source - <filename>externalsrc.bbclass</filename></title> | 550 | <title>Using External Source - <filename>externalsrc.bbclass</filename></title> |
| 551 | 551 | ||
| 552 | <para> | 552 | <para> |
| 553 | You can use this class to build software from source code that is external to the | 553 | You can use this class to build software from source code that is external to the |
| 554 | OpenEmbedded build system. | 554 | OpenEmbedded build system. |
| 555 | In other words, your source code resides in an external tree outside of the Yocto Project. | 555 | In other words, your source code resides in an external tree outside of the Yocto Project. |
| 556 | Building software from an external source tree means that the normal fetch, unpack, and | 556 | Building software from an external source tree means that the normal fetch, unpack, and |
| 557 | patch process is not used. | 557 | patch process is not used. |
| 558 | </para> | 558 | </para> |
| 559 | 559 | ||
| 560 | <para> | 560 | <para> |
| 561 | To use the class, you need to define the | 561 | To use the class, you need to define the |
| 562 | <link linkend='var-S'><filename>S</filename></link> variable to point to the directory that contains the source files. | 562 | <link linkend='var-S'><filename>S</filename></link> variable to point to the directory that contains the source files. |
| 563 | You also need to have your recipe inherit the <filename>externalsrc.bbclass</filename> class. | 563 | You also need to have your recipe inherit the <filename>externalsrc.bbclass</filename> class. |
| 564 | </para> | 564 | </para> |
| 565 | 565 | ||
| 566 | <para> | 566 | <para> |
| 567 | This class expects the source code to support recipe builds that use the | 567 | This class expects the source code to support recipe builds that use the |
| 568 | <link linkend='var-B'><filename>B</filename></link> variable to point to the directory in | 568 | <link linkend='var-B'><filename>B</filename></link> variable to point to the directory in |
| 569 | which the OpenEmbedded build system places the generated objects built from the recipes. | 569 | which the OpenEmbedded build system places the generated objects built from the recipes. |
| 570 | By default, the <filename>B</filename> directory is set to the following, which is separate from the | 570 | By default, the <filename>B</filename> directory is set to the following, which is separate from the |
| 571 | Source Directory (<filename>S</filename>): | 571 | Source Directory (<filename>S</filename>): |
| 572 | <literallayout class='monospaced'> | 572 | <literallayout class='monospaced'> |
| 573 | ${WORKDIR}/${BPN}-{PV}/ | 573 | ${WORKDIR}/${BPN}-{PV}/ |
| 574 | </literallayout> | 574 | </literallayout> |
| 575 | See the glossary entries for the | 575 | See the glossary entries for the |
| 576 | <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>, | 576 | <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>, |
| 577 | <link linkend='var-BPN'><filename>BPN</filename></link>, | 577 | <link linkend='var-BPN'><filename>BPN</filename></link>, |
| 578 | <link linkend='var-PV'><filename>PV</filename></link>, | 578 | <link linkend='var-PV'><filename>PV</filename></link>, |
| 579 | <link linkend='var-S'><filename>S</filename></link>, and | 579 | <link linkend='var-S'><filename>S</filename></link>, and |
| 580 | <link linkend='var-B'><filename>B</filename></link> for more information. | 580 | <link linkend='var-B'><filename>B</filename></link> for more information. |
| 581 | </para> | 581 | </para> |
| 582 | 582 | ||
| @@ -584,26 +584,26 @@ | |||
| 584 | You can build object files in the external tree by setting the | 584 | You can build object files in the external tree by setting the |
| 585 | <filename>B</filename> variable equal to <filename>"${S}"</filename>. | 585 | <filename>B</filename> variable equal to <filename>"${S}"</filename>. |
| 586 | However, this practice does not work well if you use the source for more than one variant | 586 | However, this practice does not work well if you use the source for more than one variant |
| 587 | (i.e., "natives" such as <filename>quilt-native</filename>, | 587 | (i.e., "natives" such as <filename>quilt-native</filename>, |
| 588 | or "crosses" such as <filename>gcc-cross</filename>). | 588 | or "crosses" such as <filename>gcc-cross</filename>). |
| 589 | So, be sure there are no "native", "cross", or "multilib" variants of the recipe. | 589 | So, be sure there are no "native", "cross", or "multilib" variants of the recipe. |
| 590 | </para> | 590 | </para> |
| 591 | 591 | ||
| 592 | <para> | 592 | <para> |
| 593 | If you do want to build different variants of a recipe, you can use the | 593 | If you do want to build different variants of a recipe, you can use the |
| 594 | <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> variable. | 594 | <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> variable. |
| 595 | When you do, the <link linkend='var-B'><filename>B</filename></link> variable must support the | 595 | When you do, the <link linkend='var-B'><filename>B</filename></link> variable must support the |
| 596 | recipe's ability to build variants in different working directories. | 596 | recipe's ability to build variants in different working directories. |
| 597 | Most autotools-based recipes support separating these directories. | 597 | Most autotools-based recipes support separating these directories. |
| 598 | The OpenEmbedded build system defaults to using separate directories for <filename>gcc</filename> | 598 | The OpenEmbedded build system defaults to using separate directories for <filename>gcc</filename> |
| 599 | and some kernel recipes. | 599 | and some kernel recipes. |
| 600 | Alternatively, you can make sure that separate recipes exist that each | 600 | Alternatively, you can make sure that separate recipes exist that each |
| 601 | use the <filename>BBCLASSEXTEND</filename> variable to build each variant. | 601 | use the <filename>BBCLASSEXTEND</filename> variable to build each variant. |
| 602 | The separate recipes can inherit a single target recipe. | 602 | The separate recipes can inherit a single target recipe. |
| 603 | </para> | 603 | </para> |
| 604 | 604 | ||
| 605 | <para> | 605 | <para> |
| 606 | For information on how to use this class, see the | 606 | For information on how to use this class, see the |
| 607 | "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building | 607 | "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building |
| 608 | Software from an External Source</ulink>" section in the Yocto Project Development Manual. | 608 | Software from an External Source</ulink>" section in the Yocto Project Development Manual. |
| 609 | </para> | 609 | </para> |
| @@ -613,12 +613,12 @@ | |||
| 613 | <title>Other Classes</title> | 613 | <title>Other Classes</title> |
| 614 | 614 | ||
| 615 | <para> | 615 | <para> |
| 616 | Thus far, this chapter has discussed only the most useful and important | 616 | Thus far, this chapter has discussed only the most useful and important |
| 617 | classes. | 617 | classes. |
| 618 | However, other classes exist within the <filename>meta/classes</filename> directory | 618 | However, other classes exist within the <filename>meta/classes</filename> directory |
| 619 | in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 619 | in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 620 | You can examine the <filename>.bbclass</filename> files directly for more | 620 | You can examine the <filename>.bbclass</filename> files directly for more |
| 621 | information. | 621 | information. |
| 622 | </para> | 622 | </para> |
| 623 | </section> | 623 | </section> |
| 624 | 624 | ||
| @@ -715,6 +715,6 @@ | |||
| 715 | 715 | ||
| 716 | 716 | ||
| 717 | </chapter> | 717 | </chapter> |
| 718 | <!-- | 718 | <!-- |
| 719 | vim: expandtab tw=80 ts=4 | 719 | vim: expandtab tw=80 ts=4 |
| 720 | --> | 720 | --> |
diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml index ec70547314..77c31275ae 100644 --- a/documentation/poky-ref-manual/ref-features.xml +++ b/documentation/poky-ref-manual/ref-features.xml | |||
| @@ -7,7 +7,7 @@ | |||
| 7 | 7 | ||
| 8 | <para> | 8 | <para> |
| 9 | Features provide a mechanism for working out which packages | 9 | Features provide a mechanism for working out which packages |
| 10 | should be included in the generated images. | 10 | should be included in the generated images. |
| 11 | Distributions can select which features they want to support through the | 11 | Distributions can select which features they want to support through the |
| 12 | <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> | 12 | <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> |
| 13 | variable, which is set in the <filename>poky.conf</filename> distribution configuration file. | 13 | variable, which is set in the <filename>poky.conf</filename> distribution configuration file. |
| @@ -19,16 +19,16 @@ | |||
| 19 | 19 | ||
| 20 | <para> | 20 | <para> |
| 21 | These two variables combine to work out which kernel modules, | 21 | These two variables combine to work out which kernel modules, |
| 22 | utilities, and other packages to include. | 22 | utilities, and other packages to include. |
| 23 | A given distribution can support a selected subset of features so some machine features might not | 23 | A given distribution can support a selected subset of features so some machine features might not |
| 24 | be included if the distribution itself does not support them. | 24 | be included if the distribution itself does not support them. |
| 25 | </para> | 25 | </para> |
| 26 | 26 | ||
| 27 | <para> | 27 | <para> |
| 28 | One method you can use to determine which recipes are checking to see if a | 28 | One method you can use to determine which recipes are checking to see if a |
| 29 | particular feature is contained or not is to <filename>grep</filename> through | 29 | particular feature is contained or not is to <filename>grep</filename> through |
| 30 | the metadata for the feature. | 30 | the metadata for the feature. |
| 31 | Here is an example that discovers the recipes whose build is potentially | 31 | Here is an example that discovers the recipes whose build is potentially |
| 32 | changed based on a given feature: | 32 | changed based on a given feature: |
| 33 | <literallayout class='monospaced'> | 33 | <literallayout class='monospaced'> |
| 34 | $ cd $HOME/poky | 34 | $ cd $HOME/poky |
| @@ -38,21 +38,21 @@ | |||
| 38 | 38 | ||
| 39 | <para> | 39 | <para> |
| 40 | This chapter provides a reference of shipped machine and distro features | 40 | This chapter provides a reference of shipped machine and distro features |
| 41 | you can include as part of the image, a reference on image types you can | 41 | you can include as part of the image, a reference on image types you can |
| 42 | build, and a reference on feature backfilling. | 42 | build, and a reference on feature backfilling. |
| 43 | </para> | 43 | </para> |
| 44 | 44 | ||
| 45 | 45 | ||
| 46 | <section id='ref-features-distro'> | 46 | <section id='ref-features-distro'> |
| 47 | <title>Distro</title> | 47 | <title>Distro</title> |
| 48 | 48 | ||
| 49 | <para> | 49 | <para> |
| 50 | The items below are features you can use with | 50 | The items below are features you can use with |
| 51 | <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. | 51 | <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. |
| 52 | Features do not have a one-to-one correspondence to packages, and they can | 52 | Features do not have a one-to-one correspondence to packages, and they can |
| 53 | go beyond simply controlling the installation of a package or packages. | 53 | go beyond simply controlling the installation of a package or packages. |
| 54 | Sometimes a feature can influence how certain recipes are built. | 54 | Sometimes a feature can influence how certain recipes are built. |
| 55 | For example, a feature might determine whether a particular configure option | 55 | For example, a feature might determine whether a particular configure option |
| 56 | is specified within <filename>do_configure</filename> for a particular | 56 | is specified within <filename>do_configure</filename> for a particular |
| 57 | recipe. | 57 | recipe. |
| 58 | </para> | 58 | </para> |
| @@ -60,7 +60,7 @@ | |||
| 60 | <para> | 60 | <para> |
| 61 | This list only represents features as shipped with the Yocto Project metadata: | 61 | This list only represents features as shipped with the Yocto Project metadata: |
| 62 | <itemizedlist> | 62 | <itemizedlist> |
| 63 | <listitem><para><emphasis>alsa:</emphasis> ALSA support will be included (OSS compatibility | 63 | <listitem><para><emphasis>alsa:</emphasis> ALSA support will be included (OSS compatibility |
| 64 | kernel modules will be installed if available).</para></listitem> | 64 | kernel modules will be installed if available).</para></listitem> |
| 65 | <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only) | 65 | <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only) |
| 66 | </para></listitem> | 66 | </para></listitem> |
| @@ -69,7 +69,7 @@ | |||
| 69 | </para></listitem> | 69 | </para></listitem> |
| 70 | <listitem><para><emphasis>irda:</emphasis> Include Irda support | 70 | <listitem><para><emphasis>irda:</emphasis> Include Irda support |
| 71 | </para></listitem> | 71 | </para></listitem> |
| 72 | <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be | 72 | <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be |
| 73 | loaded during boot). | 73 | loaded during boot). |
| 74 | </para></listitem> | 74 | </para></listitem> |
| 75 | <listitem><para><emphasis>pci:</emphasis> Include PCI bus support | 75 | <listitem><para><emphasis>pci:</emphasis> Include PCI bus support |
| @@ -103,12 +103,12 @@ | |||
| 103 | <title>Machine</title> | 103 | <title>Machine</title> |
| 104 | 104 | ||
| 105 | <para> | 105 | <para> |
| 106 | The items below are features you can use with | 106 | The items below are features you can use with |
| 107 | <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>. | 107 | <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>. |
| 108 | Features do not have a one-to-one correspondence to packages, and they can | 108 | Features do not have a one-to-one correspondence to packages, and they can |
| 109 | go beyond simply controlling the installation of a package or packages. | 109 | go beyond simply controlling the installation of a package or packages. |
| 110 | Sometimes a feature can influence how certain recipes are built. | 110 | Sometimes a feature can influence how certain recipes are built. |
| 111 | For example, a feature might determine whether a particular configure option | 111 | For example, a feature might determine whether a particular configure option |
| 112 | is specified within <filename>do_configure</filename> for a particular | 112 | is specified within <filename>do_configure</filename> for a particular |
| 113 | recipe. | 113 | recipe. |
| 114 | </para> | 114 | </para> |
| @@ -154,7 +154,7 @@ | |||
| 154 | <title>Images</title> | 154 | <title>Images</title> |
| 155 | 155 | ||
| 156 | <para> | 156 | <para> |
| 157 | The contents of images generated by the OpenEmbedded build system can be controlled by the | 157 | The contents of images generated by the OpenEmbedded build system can be controlled by the |
| 158 | <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> | 158 | <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> |
| 159 | and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> | 159 | and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> |
| 160 | variables that you typically configure in your image recipes. | 160 | variables that you typically configure in your image recipes. |
| @@ -164,48 +164,48 @@ | |||
| 164 | </para> | 164 | </para> |
| 165 | 165 | ||
| 166 | <para> | 166 | <para> |
| 167 | Current list of | 167 | Current list of |
| 168 | <filename>IMAGE_FEATURES</filename> contains the following: | 168 | <filename>IMAGE_FEATURES</filename> contains the following: |
| 169 | <itemizedlist> | 169 | <itemizedlist> |
| 170 | <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot. | 170 | <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot. |
| 171 | By default, this screen is provided by <filename>psplash</filename>, which does | 171 | By default, this screen is provided by <filename>psplash</filename>, which does |
| 172 | allow customization. | 172 | allow customization. |
| 173 | If you prefer to use an alternative splash screen package, you can do so by | 173 | If you prefer to use an alternative splash screen package, you can do so by |
| 174 | setting the <filename>SPLASH</filename> variable | 174 | setting the <filename>SPLASH</filename> variable |
| 175 | to a different package name (or names) within the image recipe or at the distro | 175 | to a different package name (or names) within the image recipe or at the distro |
| 176 | configuration level.</para></listitem> | 176 | configuration level.</para></listitem> |
| 177 | <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal | 177 | <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal |
| 178 | SSH server. | 178 | SSH server. |
| 179 | </para></listitem> | 179 | </para></listitem> |
| 180 | <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server, | 180 | <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server, |
| 181 | which is more full-featured than Dropbear. | 181 | which is more full-featured than Dropbear. |
| 182 | Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server | 182 | Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server |
| 183 | are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take | 183 | are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take |
| 184 | precedence and Dropbear will not be installed.</para></listitem> | 184 | precedence and Dropbear will not be installed.</para></listitem> |
| 185 | <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem> | 185 | <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem> |
| 186 | <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a | 186 | <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a |
| 187 | minimal environment.</para></listitem> | 187 | minimal environment.</para></listitem> |
| 188 | <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment. | 188 | <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment. |
| 189 | </para></listitem> | 189 | </para></listitem> |
| 190 | <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device. | 190 | <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device. |
| 191 | </para></listitem> | 191 | </para></listitem> |
| 192 | <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as | 192 | <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as |
| 193 | <filename>strace</filename> and <filename>gdb</filename>. | 193 | <filename>strace</filename> and <filename>gdb</filename>. |
| 194 | </para></listitem> | 194 | </para></listitem> |
| 195 | <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as | 195 | <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as |
| 196 | <filename>oprofile</filename>, <filename>exmap</filename>, and | 196 | <filename>oprofile</filename>, <filename>exmap</filename>, and |
| 197 | <filename>LTTng</filename>.</para></listitem> | 197 | <filename>LTTng</filename>.</para></listitem> |
| 198 | <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g. | 198 | <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g. |
| 199 | touchscreen debugging).</para></listitem> | 199 | touchscreen debugging).</para></listitem> |
| 200 | <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem> | 200 | <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem> |
| 201 | <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and | 201 | <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and |
| 202 | extra library links) for all packages installed in a given image.</para></listitem> | 202 | extra library links) for all packages installed in a given image.</para></listitem> |
| 203 | <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development | 203 | <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development |
| 204 | packages (i.e. static libraries containing <filename>*.a</filename> files) for all | 204 | packages (i.e. static libraries containing <filename>*.a</filename> files) for all |
| 205 | packages installed in a given image.</para></listitem> | 205 | packages installed in a given image.</para></listitem> |
| 206 | <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages | 206 | <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages |
| 207 | installed in a given image.</para></listitem> | 207 | installed in a given image.</para></listitem> |
| 208 | <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages | 208 | <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages |
| 209 | installed in a given image.</para></listitem> | 209 | installed in a given image.</para></listitem> |
| 210 | </itemizedlist> | 210 | </itemizedlist> |
| 211 | </para> | 211 | </para> |
| @@ -218,30 +218,30 @@ | |||
| 218 | Sometimes it is necessary in the OpenEmbedded build system to extend | 218 | Sometimes it is necessary in the OpenEmbedded build system to extend |
| 219 | <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> | 219 | <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> |
| 220 | or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> | 220 | or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> |
| 221 | to control functionality that was previously enabled and not able | 221 | to control functionality that was previously enabled and not able |
| 222 | to be disabled. | 222 | to be disabled. |
| 223 | For these cases, we need to add an | 223 | For these cases, we need to add an |
| 224 | additional feature item to appear in one of these variables, | 224 | additional feature item to appear in one of these variables, |
| 225 | but we do not want to force developers who have existing values | 225 | but we do not want to force developers who have existing values |
| 226 | of the variables in their configuration to add the new feature | 226 | of the variables in their configuration to add the new feature |
| 227 | in order to retain the same overall level of functionality. | 227 | in order to retain the same overall level of functionality. |
| 228 | Thus, the OpenEmbedded build system has a mechanism to | 228 | Thus, the OpenEmbedded build system has a mechanism to |
| 229 | automatically "backfill" these added features into existing | 229 | automatically "backfill" these added features into existing |
| 230 | distro or machine configurations. | 230 | distro or machine configurations. |
| 231 | You can see the list of features for which this is done by | 231 | You can see the list of features for which this is done by |
| 232 | finding the | 232 | finding the |
| 233 | <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link> | 233 | <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link> |
| 234 | and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link> | 234 | and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link> |
| 235 | variables in the <filename>meta/conf/bitbake.conf</filename> file. | 235 | variables in the <filename>meta/conf/bitbake.conf</filename> file. |
| 236 | </para> | 236 | </para> |
| 237 | 237 | ||
| 238 | <para> | 238 | <para> |
| 239 | Because such features are backfilled by default into all | 239 | Because such features are backfilled by default into all |
| 240 | configurations as described in the previous paragraph, developers | 240 | configurations as described in the previous paragraph, developers |
| 241 | who wish to disable the new features need to be able to selectively | 241 | who wish to disable the new features need to be able to selectively |
| 242 | prevent the backfilling from occurring. | 242 | prevent the backfilling from occurring. |
| 243 | They can do this by adding the undesired feature or features to the | 243 | They can do this by adding the undesired feature or features to the |
| 244 | <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link> | 244 | <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link> |
| 245 | or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link> | 245 | or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link> |
| 246 | variables for distro features and machine features respectively. | 246 | variables for distro features and machine features respectively. |
| 247 | </para> | 247 | </para> |
| @@ -249,46 +249,46 @@ | |||
| 249 | <para> | 249 | <para> |
| 250 | Here are two examples to help illustrate feature backfilling: | 250 | Here are two examples to help illustrate feature backfilling: |
| 251 | <itemizedlist> | 251 | <itemizedlist> |
| 252 | <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>: | 252 | <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>: |
| 253 | Previously, PulseAudio support was enabled within the Qt and | 253 | Previously, PulseAudio support was enabled within the Qt and |
| 254 | GStreamer frameworks. | 254 | GStreamer frameworks. |
| 255 | Because of this, the feature is backfilled and thus | 255 | Because of this, the feature is backfilled and thus |
| 256 | enabled for all distros through the | 256 | enabled for all distros through the |
| 257 | <filename>DISTRO_FEATURES_BACKFILL</filename> | 257 | <filename>DISTRO_FEATURES_BACKFILL</filename> |
| 258 | variable in the <filename>meta/conf/bitbake.conf</filename> file. | 258 | variable in the <filename>meta/conf/bitbake.conf</filename> file. |
| 259 | However, your distro needs to disable the feature. | 259 | However, your distro needs to disable the feature. |
| 260 | You can disable the feature without affecting | 260 | You can disable the feature without affecting |
| 261 | other existing distro configurations that need PulseAudio support | 261 | other existing distro configurations that need PulseAudio support |
| 262 | by adding "pulseaudio" to | 262 | by adding "pulseaudio" to |
| 263 | <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename> | 263 | <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename> |
| 264 | in your distro's <filename>.conf</filename> file. | 264 | in your distro's <filename>.conf</filename> file. |
| 265 | Adding the feature to this variable when it also | 265 | Adding the feature to this variable when it also |
| 266 | exists in the <filename>DISTRO_FEATURES_BACKFILL</filename> | 266 | exists in the <filename>DISTRO_FEATURES_BACKFILL</filename> |
| 267 | variable prevents the build system from adding the feature to | 267 | variable prevents the build system from adding the feature to |
| 268 | your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling | 268 | your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling |
| 269 | the feature for that particular distro.</para></listitem> | 269 | the feature for that particular distro.</para></listitem> |
| 270 | <listitem><para><emphasis>The "rtc" machine feature option</emphasis>: | 270 | <listitem><para><emphasis>The "rtc" machine feature option</emphasis>: |
| 271 | Previously, real time clock (RTC) support was enabled for all | 271 | Previously, real time clock (RTC) support was enabled for all |
| 272 | target devices. | 272 | target devices. |
| 273 | Because of this, the feature is backfilled and thus enabled | 273 | Because of this, the feature is backfilled and thus enabled |
| 274 | for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename> | 274 | for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename> |
| 275 | variable in the <filename>meta/conf/bitbake.conf</filename> file. | 275 | variable in the <filename>meta/conf/bitbake.conf</filename> file. |
| 276 | However, your target device does not have this capability. | 276 | However, your target device does not have this capability. |
| 277 | You can disable RTC support for your device without | 277 | You can disable RTC support for your device without |
| 278 | affecting other machines that need RTC support | 278 | affecting other machines that need RTC support |
| 279 | by adding the feature to your machine's | 279 | by adding the feature to your machine's |
| 280 | <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename> | 280 | <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename> |
| 281 | list in the machine's <filename>.conf</filename> file. | 281 | list in the machine's <filename>.conf</filename> file. |
| 282 | Adding the feature to this variable when it also | 282 | Adding the feature to this variable when it also |
| 283 | exists in the <filename>MACHINE_FEATURES_BACKFILL</filename> | 283 | exists in the <filename>MACHINE_FEATURES_BACKFILL</filename> |
| 284 | variable prevents the build system from adding the feature to | 284 | variable prevents the build system from adding the feature to |
| 285 | your configuration's <filename>MACHINE_FEATURES</filename>, effectively | 285 | your configuration's <filename>MACHINE_FEATURES</filename>, effectively |
| 286 | disabling RTC support for that particular machine.</para></listitem> | 286 | disabling RTC support for that particular machine.</para></listitem> |
| 287 | </itemizedlist> | 287 | </itemizedlist> |
| 288 | </para> | 288 | </para> |
| 289 | </section> | 289 | </section> |
| 290 | </chapter> | 290 | </chapter> |
| 291 | 291 | ||
| 292 | <!-- | 292 | <!-- |
| 293 | vim: expandtab tw=80 ts=4 spell spelllang=en_gb | 293 | vim: expandtab tw=80 ts=4 spell spelllang=en_gb |
| 294 | --> | 294 | --> |
diff --git a/documentation/poky-ref-manual/ref-images.xml b/documentation/poky-ref-manual/ref-images.xml index 79f2409933..0a827ca235 100644 --- a/documentation/poky-ref-manual/ref-images.xml +++ b/documentation/poky-ref-manual/ref-images.xml | |||
| @@ -6,8 +6,8 @@ | |||
| 6 | <title>Images</title> | 6 | <title>Images</title> |
| 7 | 7 | ||
| 8 | <para> | 8 | <para> |
| 9 | The OpenEmbedded build process supports several types of images to satisfy different needs. | 9 | The OpenEmbedded build process supports several types of images to satisfy different needs. |
| 10 | When you issue the <filename>bitbake</filename> command you provide a “top-level” recipe | 10 | When you issue the <filename>bitbake</filename> command you provide a “top-level” recipe |
| 11 | that essentially begins the build for the type of image you want. | 11 | that essentially begins the build for the type of image you want. |
| 12 | </para> | 12 | </para> |
| 13 | 13 | ||
| @@ -24,16 +24,16 @@ | |||
| 24 | </note> | 24 | </note> |
| 25 | 25 | ||
| 26 | <para> | 26 | <para> |
| 27 | From within the <filename>poky</filename> Git repository, use the following command to list | 27 | From within the <filename>poky</filename> Git repository, use the following command to list |
| 28 | the supported images: | 28 | the supported images: |
| 29 | <literallayout class='monospaced'> | 29 | <literallayout class='monospaced'> |
| 30 | $ ls meta*/recipes*/images/*.bb | 30 | $ ls meta*/recipes*/images/*.bb |
| 31 | </literallayout> | 31 | </literallayout> |
| 32 | These recipes reside in the <filename>meta/recipes-core/images</filename>, | 32 | These recipes reside in the <filename>meta/recipes-core/images</filename>, |
| 33 | <filename>meta/recipes-extended/images</filename>, | 33 | <filename>meta/recipes-extended/images</filename>, |
| 34 | <filename>meta/recipes-graphics/images</filename>, and | 34 | <filename>meta/recipes-graphics/images</filename>, and |
| 35 | <filename>meta/recipes-sato/images</filename> directories | 35 | <filename>meta/recipes-sato/images</filename> directories |
| 36 | within the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>. | 36 | within the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>. |
| 37 | Although the recipe names are somewhat explanatory, here is a list that describes them: | 37 | Although the recipe names are somewhat explanatory, here is a list that describes them: |
| 38 | </para> | 38 | </para> |
| 39 | 39 | ||
| @@ -45,17 +45,17 @@ | |||
| 45 | <listitem><para><emphasis><filename>core-image-minimal-dev</filename>:</emphasis> | 45 | <listitem><para><emphasis><filename>core-image-minimal-dev</filename>:</emphasis> |
| 46 | A <filename>core-image-minimal</filename> image suitable for development work | 46 | A <filename>core-image-minimal</filename> image suitable for development work |
| 47 | using the host. | 47 | using the host. |
| 48 | The image includes headers and libraries you can use in a host development | 48 | The image includes headers and libraries you can use in a host development |
| 49 | environment. | 49 | environment. |
| 50 | </para></listitem> | 50 | </para></listitem> |
| 51 | <listitem><para><emphasis><filename>core-image-minimal-initramfs</filename>:</emphasis> | 51 | <listitem><para><emphasis><filename>core-image-minimal-initramfs</filename>:</emphasis> |
| 52 | A <filename>core-image-minimal</filename> image that has the Minimal RAM-based | 52 | A <filename>core-image-minimal</filename> image that has the Minimal RAM-based |
| 53 | Initial Root Filesystem (<filename>initramfs</filename>) as part of the kernel, | 53 | Initial Root Filesystem (<filename>initramfs</filename>) as part of the kernel, |
| 54 | which allows the system to find the first “init” program more efficiently. | 54 | which allows the system to find the first “init” program more efficiently. |
| 55 | </para></listitem> | 55 | </para></listitem> |
| 56 | <listitem><para><emphasis><filename>core-image-minimal-mtdutils</filename>:</emphasis> | 56 | <listitem><para><emphasis><filename>core-image-minimal-mtdutils</filename>:</emphasis> |
| 57 | A <filename>core-image-minimal</filename> image that has support | 57 | A <filename>core-image-minimal</filename> image that has support |
| 58 | for the Minimal MTD Utilities, which let the user interact with the | 58 | for the Minimal MTD Utilities, which let the user interact with the |
| 59 | MTD subsystem in the kernel to perform operations on flash devices. | 59 | MTD subsystem in the kernel to perform operations on flash devices. |
| 60 | </para></listitem> | 60 | </para></listitem> |
| 61 | <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis> | 61 | <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis> |
| @@ -69,64 +69,64 @@ | |||
| 69 | <listitem><para><emphasis><filename>core-image-lsb-dev</filename>:</emphasis> | 69 | <listitem><para><emphasis><filename>core-image-lsb-dev</filename>:</emphasis> |
| 70 | A <filename>core-image-lsb</filename> image that is suitable for development work | 70 | A <filename>core-image-lsb</filename> image that is suitable for development work |
| 71 | using the host. | 71 | using the host. |
| 72 | The image includes headers and libraries you can use in a host development | 72 | The image includes headers and libraries you can use in a host development |
| 73 | environment. | 73 | environment. |
| 74 | </para></listitem> | 74 | </para></listitem> |
| 75 | <listitem><para><emphasis><filename>core-image-lsb-sdk</filename>:</emphasis> | 75 | <listitem><para><emphasis><filename>core-image-lsb-sdk</filename>:</emphasis> |
| 76 | A <filename>core-image-lsb</filename> that includes everything in meta-toolchain | 76 | A <filename>core-image-lsb</filename> that includes everything in meta-toolchain |
| 77 | but also includes development headers and libraries to form a complete standalone SDK. | 77 | but also includes development headers and libraries to form a complete standalone SDK. |
| 78 | This image is suitable for development using the target.</para></listitem> | 78 | This image is suitable for development using the target.</para></listitem> |
| 79 | <listitem><para><emphasis><filename>core-image-clutter</filename>:</emphasis> | 79 | <listitem><para><emphasis><filename>core-image-clutter</filename>:</emphasis> |
| 80 | An image with support for the Open GL-based toolkit Clutter, which enables development of | 80 | An image with support for the Open GL-based toolkit Clutter, which enables development of |
| 81 | rich and animated graphical user interfaces.</para></listitem> | 81 | rich and animated graphical user interfaces.</para></listitem> |
| 82 | <listitem><para><emphasis><filename>core-image-sato</filename>:</emphasis> | 82 | <listitem><para><emphasis><filename>core-image-sato</filename>:</emphasis> |
| 83 | An image with Sato support, a mobile environment and visual style that works well | 83 | An image with Sato support, a mobile environment and visual style that works well |
| 84 | with mobile devices. | 84 | with mobile devices. |
| 85 | The image supports X11 with a Sato theme and applications such as | 85 | The image supports X11 with a Sato theme and applications such as |
| 86 | a terminal, editor, file manager, media player, and so forth.</para></listitem> | 86 | a terminal, editor, file manager, media player, and so forth.</para></listitem> |
| 87 | <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis> | 87 | <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis> |
| 88 | A <filename>core-image-sato</filename> image suitable for development | 88 | A <filename>core-image-sato</filename> image suitable for development |
| 89 | using the host. | 89 | using the host. |
| 90 | The image includes libraries needed to build applications on the device itself, | 90 | The image includes libraries needed to build applications on the device itself, |
| 91 | testing and profiling tools, and debug symbols. | 91 | testing and profiling tools, and debug symbols. |
| 92 | This image was formerly <filename>core-image-sdk</filename>.</para></listitem> | 92 | This image was formerly <filename>core-image-sdk</filename>.</para></listitem> |
| 93 | <listitem><para><emphasis><filename>core-image-sato-sdk</filename>:</emphasis> | 93 | <listitem><para><emphasis><filename>core-image-sato-sdk</filename>:</emphasis> |
| 94 | A <filename>core-image-sato</filename> image that includes everything in meta-toolchain. | 94 | A <filename>core-image-sato</filename> image that includes everything in meta-toolchain. |
| 95 | The image also includes development headers and libraries to form a complete standalone SDK | 95 | The image also includes development headers and libraries to form a complete standalone SDK |
| 96 | and is suitable for development using the target.</para></listitem> | 96 | and is suitable for development using the target.</para></listitem> |
| 97 | <listitem><para><emphasis><filename>core-image-rt</filename>:</emphasis> | 97 | <listitem><para><emphasis><filename>core-image-rt</filename>:</emphasis> |
| 98 | A <filename>core-image-minimal</filename> image plus a real-time test suite and | 98 | A <filename>core-image-minimal</filename> image plus a real-time test suite and |
| 99 | tools appropriate for real-time use.</para></listitem> | 99 | tools appropriate for real-time use.</para></listitem> |
| 100 | <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis> | 100 | <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis> |
| 101 | A <filename>core-image-rt</filename> image that includes everything in | 101 | A <filename>core-image-rt</filename> image that includes everything in |
| 102 | <filename>meta-toolchain</filename>. | 102 | <filename>meta-toolchain</filename>. |
| 103 | The image also includes development headers and libraries to form a complete | 103 | The image also includes development headers and libraries to form a complete |
| 104 | stand-alone SDK and is suitable for development using the target.</para></listitem> | 104 | stand-alone SDK and is suitable for development using the target.</para></listitem> |
| 105 | <listitem><para><emphasis><filename>core-image-gtk-directfb</filename>:</emphasis> | 105 | <listitem><para><emphasis><filename>core-image-gtk-directfb</filename>:</emphasis> |
| 106 | An image that uses <filename>gtk+</filename> over <filename>directfb</filename> | 106 | An image that uses <filename>gtk+</filename> over <filename>directfb</filename> |
| 107 | instead of X11. | 107 | instead of X11. |
| 108 | In order to build, this image requires specific distro configuration that enables | 108 | In order to build, this image requires specific distro configuration that enables |
| 109 | <filename>gtk</filename> over <filename>directfb</filename>.</para></listitem> | 109 | <filename>gtk</filename> over <filename>directfb</filename>.</para></listitem> |
| 110 | <listitem><para><emphasis><filename>build-appliance-image</filename>:</emphasis> | 110 | <listitem><para><emphasis><filename>build-appliance-image</filename>:</emphasis> |
| 111 | An image you can boot and run using either the | 111 | An image you can boot and run using either the |
| 112 | <ulink url='http://www.vmware.com/products/player/overview.html'>VMware Player</ulink> | 112 | <ulink url='http://www.vmware.com/products/player/overview.html'>VMware Player</ulink> |
| 113 | or <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>. | 113 | or <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>. |
| 114 | For more information on this image, see the | 114 | For more information on this image, see the |
| 115 | <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> page on | 115 | <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> page on |
| 116 | the Yocto Project website.</para></listitem> | 116 | the Yocto Project website.</para></listitem> |
| 117 | </itemizedlist> | 117 | </itemizedlist> |
| 118 | 118 | ||
| 119 | <tip> | 119 | <tip> |
| 120 | From the Yocto Project release 1.1 onwards, <filename>-live</filename> and | 120 | From the Yocto Project release 1.1 onwards, <filename>-live</filename> and |
| 121 | <filename>-directdisk</filename> images have been replaced by a "live" | 121 | <filename>-directdisk</filename> images have been replaced by a "live" |
| 122 | option in <filename>IMAGE_FSTYPES</filename> that will work with any image to produce an | 122 | option in <filename>IMAGE_FSTYPES</filename> that will work with any image to produce an |
| 123 | image file that can be | 123 | image file that can be |
| 124 | copied directly to a CD or USB device and run as is. | 124 | copied directly to a CD or USB device and run as is. |
| 125 | To build a live image, simply add | 125 | To build a live image, simply add |
| 126 | "live" to <filename>IMAGE_FSTYPES</filename> within the <filename>local.conf</filename> | 126 | "live" to <filename>IMAGE_FSTYPES</filename> within the <filename>local.conf</filename> |
| 127 | file or wherever appropriate and then build the desired image as normal. | 127 | file or wherever appropriate and then build the desired image as normal. |
| 128 | </tip> | 128 | </tip> |
| 129 | </chapter> | 129 | </chapter> |
| 130 | <!-- | 130 | <!-- |
| 131 | vim: expandtab tw=80 ts=4 | 131 | vim: expandtab tw=80 ts=4 |
| 132 | --> | 132 | --> |
diff --git a/documentation/poky-ref-manual/ref-structure.xml b/documentation/poky-ref-manual/ref-structure.xml index 166907ceef..673b05a52b 100644 --- a/documentation/poky-ref-manual/ref-structure.xml +++ b/documentation/poky-ref-manual/ref-structure.xml | |||
| @@ -9,7 +9,7 @@ | |||
| 9 | <para> | 9 | <para> |
| 10 | The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components. | 10 | The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components. |
| 11 | Understanding them and knowing where they are located is key to using the Yocto Project well. | 11 | Understanding them and knowing where they are located is key to using the Yocto Project well. |
| 12 | This chapter describes the Source Directory and gives information about the various | 12 | This chapter describes the Source Directory and gives information about the various |
| 13 | files and directories. | 13 | files and directories. |
| 14 | </para> | 14 | </para> |
| 15 | 15 | ||
| @@ -35,26 +35,26 @@ | |||
| 35 | <para> | 35 | <para> |
| 36 | The <ulink url='source-directory'>Source Directory</ulink> | 36 | The <ulink url='source-directory'>Source Directory</ulink> |
| 37 | includes a copy of BitBake for ease of use. | 37 | includes a copy of BitBake for ease of use. |
| 38 | The copy usually matches the current stable BitBake release from the BitBake project. | 38 | The copy usually matches the current stable BitBake release from the BitBake project. |
| 39 | BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks | 39 | BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks |
| 40 | defined by that data. | 40 | defined by that data. |
| 41 | Failures are usually from the metadata and not from BitBake itself. | 41 | Failures are usually from the metadata and not from BitBake itself. |
| 42 | Consequently, most users do not need to worry about BitBake. | 42 | Consequently, most users do not need to worry about BitBake. |
| 43 | </para> | 43 | </para> |
| 44 | 44 | ||
| 45 | <para> | 45 | <para> |
| 46 | When you run the <filename>bitbake</filename> command, the wrapper script in | 46 | When you run the <filename>bitbake</filename> command, the wrapper script in |
| 47 | <filename>scripts/</filename> is executed to run the main BitBake executable, | 47 | <filename>scripts/</filename> is executed to run the main BitBake executable, |
| 48 | which resides in the <filename>bitbake/bin/</filename> directory. | 48 | which resides in the <filename>bitbake/bin/</filename> directory. |
| 49 | Sourcing the <link linkend="structure-core-script">&OE_INIT_FILE;</link> | 49 | Sourcing the <link linkend="structure-core-script">&OE_INIT_FILE;</link> |
| 50 | script places the <filename>scripts</filename> and <filename>bitbake/bin</filename> | 50 | script places the <filename>scripts</filename> and <filename>bitbake/bin</filename> |
| 51 | directories (in that order) into the shell's <filename>PATH</filename> environment | 51 | directories (in that order) into the shell's <filename>PATH</filename> environment |
| 52 | variable. | 52 | variable. |
| 53 | </para> | 53 | </para> |
| 54 | 54 | ||
| 55 | <para> | 55 | <para> |
| 56 | For more information on BitBake, see the BitBake documentation | 56 | For more information on BitBake, see the BitBake documentation |
| 57 | inculded in the <filename>bitbake/doc/manual</filename> directory of the | 57 | inculded in the <filename>bitbake/doc/manual</filename> directory of the |
| 58 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 58 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 59 | </para> | 59 | </para> |
| 60 | </section> | 60 | </section> |
| @@ -63,21 +63,21 @@ | |||
| 63 | <title><filename>build/</filename></title> | 63 | <title><filename>build/</filename></title> |
| 64 | 64 | ||
| 65 | <para> | 65 | <para> |
| 66 | This directory contains user configuration files and the output | 66 | This directory contains user configuration files and the output |
| 67 | generated by the OpenEmbedded build system in its standard configuration where | 67 | generated by the OpenEmbedded build system in its standard configuration where |
| 68 | the source tree is combined with the output. | 68 | the source tree is combined with the output. |
| 69 | The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> | 69 | The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> |
| 70 | is created initially when you <filename>source</filename> | 70 | is created initially when you <filename>source</filename> |
| 71 | the OpenEmbedded build environment setup script <filename>&OE_INIT_FILE;</filename>. | 71 | the OpenEmbedded build environment setup script <filename>&OE_INIT_FILE;</filename>. |
| 72 | </para> | 72 | </para> |
| 73 | 73 | ||
| 74 | <para> | 74 | <para> |
| 75 | It is also possible to place output and configuration | 75 | It is also possible to place output and configuration |
| 76 | files in a directory separate from the | 76 | files in a directory separate from the |
| 77 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | 77 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> |
| 78 | by providing a directory name when you <filename>source</filename> | 78 | by providing a directory name when you <filename>source</filename> |
| 79 | the setup script. | 79 | the setup script. |
| 80 | For information on separating output from your local Source Directory files, see <link | 80 | For information on separating output from your local Source Directory files, see <link |
| 81 | linkend='structure-core-script'>&OE_INIT_FILE;</link>. | 81 | linkend='structure-core-script'>&OE_INIT_FILE;</link>. |
| 82 | </para> | 82 | </para> |
| 83 | </section> | 83 | </section> |
| @@ -88,9 +88,9 @@ | |||
| 88 | <para> | 88 | <para> |
| 89 | This directory holds the source for the Yocto Project documentation | 89 | This directory holds the source for the Yocto Project documentation |
| 90 | as well as templates and tools that allow you to generate PDF and HTML | 90 | as well as templates and tools that allow you to generate PDF and HTML |
| 91 | versions of the manuals. | 91 | versions of the manuals. |
| 92 | Each manual is contained in a sub-folder. | 92 | Each manual is contained in a sub-folder. |
| 93 | For example, the files for this manual reside in | 93 | For example, the files for this manual reside in |
| 94 | <filename>poky-ref-manual</filename>. | 94 | <filename>poky-ref-manual</filename>. |
| 95 | </para> | 95 | </para> |
| 96 | </section> | 96 | </section> |
| @@ -99,7 +99,7 @@ | |||
| 99 | <title><filename>meta/</filename></title> | 99 | <title><filename>meta/</filename></title> |
| 100 | 100 | ||
| 101 | <para> | 101 | <para> |
| 102 | This directory contains the OpenEmbedded Core metadata. | 102 | This directory contains the OpenEmbedded Core metadata. |
| 103 | The directory holds recipes, common classes, and machine | 103 | The directory holds recipes, common classes, and machine |
| 104 | configuration for emulated targets (qemux86, qemuarm, | 104 | configuration for emulated targets (qemux86, qemuarm, |
| 105 | and so on.) | 105 | and so on.) |
| @@ -138,7 +138,7 @@ | |||
| 138 | <title><filename>meta-skeleton/</filename></title> | 138 | <title><filename>meta-skeleton/</filename></title> |
| 139 | 139 | ||
| 140 | <para> | 140 | <para> |
| 141 | This directory contains template recipes for BSP and kernel development. | 141 | This directory contains template recipes for BSP and kernel development. |
| 142 | </para> | 142 | </para> |
| 143 | </section> | 143 | </section> |
| 144 | 144 | ||
| @@ -146,7 +146,7 @@ | |||
| 146 | <title><filename>scripts/</filename></title> | 146 | <title><filename>scripts/</filename></title> |
| 147 | 147 | ||
| 148 | <para> | 148 | <para> |
| 149 | This directory contains various integration scripts that implement | 149 | This directory contains various integration scripts that implement |
| 150 | extra functionality in the Yocto Project environment (e.g. QEMU scripts). | 150 | extra functionality in the Yocto Project environment (e.g. QEMU scripts). |
| 151 | The <link linkend="structure-core-script">&OE_INIT_FILE;</link> script appends this | 151 | The <link linkend="structure-core-script">&OE_INIT_FILE;</link> script appends this |
| 152 | directory to the shell's <filename>PATH</filename> environment variable. | 152 | directory to the shell's <filename>PATH</filename> environment variable. |
| @@ -154,7 +154,7 @@ | |||
| 154 | 154 | ||
| 155 | <para> | 155 | <para> |
| 156 | The <filename>scripts</filename> directory has useful scripts that assist contributing | 156 | The <filename>scripts</filename> directory has useful scripts that assist contributing |
| 157 | back to the Yocto Project, such as <filename>create_pull_request</filename> and | 157 | back to the Yocto Project, such as <filename>create_pull_request</filename> and |
| 158 | <filename>send_pull_request</filename>. | 158 | <filename>send_pull_request</filename>. |
| 159 | </para> | 159 | </para> |
| 160 | </section> | 160 | </section> |
| @@ -163,23 +163,23 @@ | |||
| 163 | <title><filename>&OE_INIT_FILE;</filename></title> | 163 | <title><filename>&OE_INIT_FILE;</filename></title> |
| 164 | 164 | ||
| 165 | <para> | 165 | <para> |
| 166 | This script sets up the OpenEmbedded build environment. | 166 | This script sets up the OpenEmbedded build environment. |
| 167 | Running this script with the <filename>source</filename> command in | 167 | Running this script with the <filename>source</filename> command in |
| 168 | a shell makes changes to <filename>PATH</filename> and sets other core BitBake variables based on the | 168 | a shell makes changes to <filename>PATH</filename> and sets other core BitBake variables based on the |
| 169 | current working directory. | 169 | current working directory. |
| 170 | You need to run this script before running BitBake commands. | 170 | You need to run this script before running BitBake commands. |
| 171 | The script uses other scripts within the <filename>scripts</filename> directory to do | 171 | The script uses other scripts within the <filename>scripts</filename> directory to do |
| 172 | the bulk of the work. | 172 | the bulk of the work. |
| 173 | </para> | 173 | </para> |
| 174 | 174 | ||
| 175 | <para> | 175 | <para> |
| 176 | By default, running this script without a Build Directory argument creates the | 176 | By default, running this script without a Build Directory argument creates the |
| 177 | <filename>build</filename> directory. | 177 | <filename>build</filename> directory. |
| 178 | If you provide a Build Directory argument when you <filename>source</filename> | 178 | If you provide a Build Directory argument when you <filename>source</filename> |
| 179 | the script, you direct OpenEmbedded build system to create a | 179 | the script, you direct OpenEmbedded build system to create a |
| 180 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> of your choice. | 180 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> of your choice. |
| 181 | For example, the following command creates a Build Directory named | 181 | For example, the following command creates a Build Directory named |
| 182 | <filename>mybuilds</filename> that is outside of the | 182 | <filename>mybuilds</filename> that is outside of the |
| 183 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: | 183 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: |
| 184 | <literallayout class='monospaced'> | 184 | <literallayout class='monospaced'> |
| 185 | $ source &OE_INIT_FILE; ~/mybuilds | 185 | $ source &OE_INIT_FILE; ~/mybuilds |
| @@ -189,7 +189,7 @@ | |||
| 189 | contain spaces. | 189 | contain spaces. |
| 190 | If you attempt to run the <filename>&OE_INIT_FILE;</filename> script | 190 | If you attempt to run the <filename>&OE_INIT_FILE;</filename> script |
| 191 | from a Source Directory that contains spaces in either the filenames | 191 | from a Source Directory that contains spaces in either the filenames |
| 192 | or directory names, the script returns an error indicating no such | 192 | or directory names, the script returns an error indicating no such |
| 193 | file or directory. | 193 | file or directory. |
| 194 | Be sure to use a Source Directory free of names containing spaces. | 194 | Be sure to use a Source Directory free of names containing spaces. |
| 195 | </note> | 195 | </note> |
| @@ -200,7 +200,7 @@ | |||
| 200 | <title><filename>LICENSE, README, and README.hardware</filename></title> | 200 | <title><filename>LICENSE, README, and README.hardware</filename></title> |
| 201 | 201 | ||
| 202 | <para> | 202 | <para> |
| 203 | These files are standard top-level files. | 203 | These files are standard top-level files. |
| 204 | </para> | 204 | </para> |
| 205 | </section> | 205 | </section> |
| 206 | </section> | 206 | </section> |
| @@ -212,8 +212,8 @@ | |||
| 212 | <title><filename>build/pseudodone</filename></title> | 212 | <title><filename>build/pseudodone</filename></title> |
| 213 | 213 | ||
| 214 | <para> | 214 | <para> |
| 215 | This tag file indicates that the initial pseudo binary was created. | 215 | This tag file indicates that the initial pseudo binary was created. |
| 216 | The file is built the first time BitBake is invoked. | 216 | The file is built the first time BitBake is invoked. |
| 217 | </para> | 217 | </para> |
| 218 | </section> | 218 | </section> |
| 219 | 219 | ||
| @@ -221,24 +221,24 @@ | |||
| 221 | <title><filename>build/conf/local.conf</filename></title> | 221 | <title><filename>build/conf/local.conf</filename></title> |
| 222 | 222 | ||
| 223 | <para> | 223 | <para> |
| 224 | This file contains all the local user configuration for your build environment. | 224 | This file contains all the local user configuration for your build environment. |
| 225 | If there is no <filename>local.conf</filename> present, it is created from | 225 | If there is no <filename>local.conf</filename> present, it is created from |
| 226 | <filename>local.conf.sample</filename>. | 226 | <filename>local.conf.sample</filename>. |
| 227 | The <filename>local.conf</filename> file contains documentation on the various configuration options. | 227 | The <filename>local.conf</filename> file contains documentation on the various configuration options. |
| 228 | Any variable set here overrides any variable set elsewhere within the environment unless | 228 | Any variable set here overrides any variable set elsewhere within the environment unless |
| 229 | that variable is hard-coded within a file (e.g. by using '=' instead of '?='). | 229 | that variable is hard-coded within a file (e.g. by using '=' instead of '?='). |
| 230 | Some variables are hard-coded for various reasons but these variables are | 230 | Some variables are hard-coded for various reasons but these variables are |
| 231 | relatively rare. | 231 | relatively rare. |
| 232 | </para> | 232 | </para> |
| 233 | 233 | ||
| 234 | <para> | 234 | <para> |
| 235 | Edit this file to set the <filename><link linkend='var-MACHINE'>MACHINE</link></filename> | 235 | Edit this file to set the <filename><link linkend='var-MACHINE'>MACHINE</link></filename> |
| 236 | for which you want to build, which package types you wish to use | 236 | for which you want to build, which package types you wish to use |
| 237 | (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>), | 237 | (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>), |
| 238 | where you want to downloaded files | 238 | where you want to downloaded files |
| 239 | (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>), | 239 | (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>), |
| 240 | and how you want your host machine to use resources | 240 | and how you want your host machine to use resources |
| 241 | (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> and | 241 | (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> and |
| 242 | <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>). | 242 | <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>). |
| 243 | </para> | 243 | </para> |
| 244 | </section> | 244 | </section> |
| @@ -248,8 +248,8 @@ | |||
| 248 | 248 | ||
| 249 | <para> | 249 | <para> |
| 250 | This file defines layers, which are directory trees, traversed (or walked) by BitBake. | 250 | This file defines layers, which are directory trees, traversed (or walked) by BitBake. |
| 251 | If <filename>bblayers.conf</filename> | 251 | If <filename>bblayers.conf</filename> |
| 252 | is not present, it is created from <filename>bblayers.conf.sample</filename> when | 252 | is not present, it is created from <filename>bblayers.conf.sample</filename> when |
| 253 | you <filename>source</filename> the environment setup script. | 253 | you <filename>source</filename> the environment setup script. |
| 254 | </para> | 254 | </para> |
| 255 | 255 | ||
| @@ -276,7 +276,7 @@ | |||
| 276 | 276 | ||
| 277 | <para> | 277 | <para> |
| 278 | This directory is used for the upstream source tarballs. | 278 | This directory is used for the upstream source tarballs. |
| 279 | The directory can be reused by multiple builds or moved to another location. | 279 | The directory can be reused by multiple builds or moved to another location. |
| 280 | You can control the location of this directory through the | 280 | You can control the location of this directory through the |
| 281 | <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable. | 281 | <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable. |
| 282 | </para> | 282 | </para> |
| @@ -287,7 +287,7 @@ | |||
| 287 | 287 | ||
| 288 | <para> | 288 | <para> |
| 289 | This directory is used for the shared state cache. | 289 | This directory is used for the shared state cache. |
| 290 | The directory can be reused by multiple builds or moved to another location. | 290 | The directory can be reused by multiple builds or moved to another location. |
| 291 | You can control the location of this directory through the | 291 | You can control the location of this directory through the |
| 292 | <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable. | 292 | <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable. |
| 293 | </para> | 293 | </para> |
| @@ -298,9 +298,9 @@ | |||
| 298 | 298 | ||
| 299 | <para> | 299 | <para> |
| 300 | This directory receives all the OpenEmbedded build system's output. | 300 | This directory receives all the OpenEmbedded build system's output. |
| 301 | BitBake creates this directory if it does not exist. | 301 | BitBake creates this directory if it does not exist. |
| 302 | As a last resort, to clean up a build and start it from scratch (other than the downloads), | 302 | As a last resort, to clean up a build and start it from scratch (other than the downloads), |
| 303 | you can remove everything in the <filename>tmp</filename> directory or get rid of the | 303 | you can remove everything in the <filename>tmp</filename> directory or get rid of the |
| 304 | directory completely. | 304 | directory completely. |
| 305 | If you do, you should also completely remove the <filename>build/sstate-cache</filename> | 305 | If you do, you should also completely remove the <filename>build/sstate-cache</filename> |
| 306 | directory as well. | 306 | directory as well. |
| @@ -320,7 +320,7 @@ | |||
| 320 | 320 | ||
| 321 | <para> | 321 | <para> |
| 322 | When BitBake parses the metadata, it creates a cache file of the result that can | 322 | When BitBake parses the metadata, it creates a cache file of the result that can |
| 323 | be used when subsequently running commands. | 323 | be used when subsequently running commands. |
| 324 | These results are stored here on a per-machine basis. | 324 | These results are stored here on a per-machine basis. |
| 325 | </para> | 325 | </para> |
| 326 | </section> | 326 | </section> |
| @@ -337,7 +337,7 @@ | |||
| 337 | <title><filename>build/tmp/deploy/deb/</filename></title> | 337 | <title><filename>build/tmp/deploy/deb/</filename></title> |
| 338 | 338 | ||
| 339 | <para> | 339 | <para> |
| 340 | This directory receives any <filename>.deb</filename> packages produced by | 340 | This directory receives any <filename>.deb</filename> packages produced by |
| 341 | the build process. | 341 | the build process. |
| 342 | The packages are sorted into feeds for different architecture types. | 342 | The packages are sorted into feeds for different architecture types. |
| 343 | </para> | 343 | </para> |
| @@ -347,8 +347,8 @@ | |||
| 347 | <title><filename>build/tmp/deploy/rpm/</filename></title> | 347 | <title><filename>build/tmp/deploy/rpm/</filename></title> |
| 348 | 348 | ||
| 349 | <para> | 349 | <para> |
| 350 | This directory receives any <filename>.rpm</filename> packages produced by | 350 | This directory receives any <filename>.rpm</filename> packages produced by |
| 351 | the build process. | 351 | the build process. |
| 352 | The packages are sorted into feeds for different architecture types. | 352 | The packages are sorted into feeds for different architecture types. |
| 353 | </para> | 353 | </para> |
| 354 | </section> | 354 | </section> |
| @@ -368,16 +368,16 @@ | |||
| 368 | <title><filename>build/tmp/deploy/images/</filename></title> | 368 | <title><filename>build/tmp/deploy/images/</filename></title> |
| 369 | 369 | ||
| 370 | <para> | 370 | <para> |
| 371 | This directory receives complete filesystem images. | 371 | This directory receives complete filesystem images. |
| 372 | If you want to flash the resulting image from a build onto a device, look here for the image. | 372 | If you want to flash the resulting image from a build onto a device, look here for the image. |
| 373 | </para> | 373 | </para> |
| 374 | 374 | ||
| 375 | <para> | 375 | <para> |
| 376 | Be careful when deleting files in this directory. | 376 | Be careful when deleting files in this directory. |
| 377 | You can safely delete old images from this directory (e.g. | 377 | You can safely delete old images from this directory (e.g. |
| 378 | <filename>core-image-*</filename>, <filename>hob-image-*</filename>, | 378 | <filename>core-image-*</filename>, <filename>hob-image-*</filename>, |
| 379 | etc.). | 379 | etc.). |
| 380 | However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.), | 380 | However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.), |
| 381 | bootloader and other supplementary files might be deployed here prior to building an | 381 | bootloader and other supplementary files might be deployed here prior to building an |
| 382 | image. | 382 | image. |
| 383 | Because these files, however, are not directly produced from the image, if you | 383 | Because these files, however, are not directly produced from the image, if you |
| @@ -385,8 +385,8 @@ | |||
| 385 | </para> | 385 | </para> |
| 386 | 386 | ||
| 387 | <para> | 387 | <para> |
| 388 | If you do accidentally delete files here, you will need to force them to be | 388 | If you do accidentally delete files here, you will need to force them to be |
| 389 | re-created. | 389 | re-created. |
| 390 | In order to do that, you will need to know the target that produced them. | 390 | In order to do that, you will need to know the target that produced them. |
| 391 | For example, these commands rebuild and re-create the kernel files: | 391 | For example, these commands rebuild and re-create the kernel files: |
| 392 | <literallayout class='monospaced'> | 392 | <literallayout class='monospaced'> |
| @@ -400,7 +400,7 @@ | |||
| 400 | <title><filename>build/tmp/deploy/ipk/</filename></title> | 400 | <title><filename>build/tmp/deploy/ipk/</filename></title> |
| 401 | 401 | ||
| 402 | <para> | 402 | <para> |
| 403 | This directory receives <filename>.ipk</filename> packages produced by | 403 | This directory receives <filename>.ipk</filename> packages produced by |
| 404 | the build process.</para> | 404 | the build process.</para> |
| 405 | </section> | 405 | </section> |
| 406 | 406 | ||
| @@ -408,9 +408,9 @@ | |||
| 408 | <title><filename>build/tmp/sysroots/</filename></title> | 408 | <title><filename>build/tmp/sysroots/</filename></title> |
| 409 | 409 | ||
| 410 | <para> | 410 | <para> |
| 411 | This directory contains shared header files and libraries as well as other shared | 411 | This directory contains shared header files and libraries as well as other shared |
| 412 | data. | 412 | data. |
| 413 | Packages that need to share output with other packages do so within this directory. | 413 | Packages that need to share output with other packages do so within this directory. |
| 414 | The directory is subdivided by architecture so multiple builds can run within | 414 | The directory is subdivided by architecture so multiple builds can run within |
| 415 | the one Build Directory. | 415 | the one Build Directory. |
| 416 | </para> | 416 | </para> |
| @@ -420,9 +420,9 @@ | |||
| 420 | <title><filename>build/tmp/stamps/</filename></title> | 420 | <title><filename>build/tmp/stamps/</filename></title> |
| 421 | 421 | ||
| 422 | <para> | 422 | <para> |
| 423 | This directory holds information that that BitBake uses for accounting purposes | 423 | This directory holds information that that BitBake uses for accounting purposes |
| 424 | to track what tasks have run and when they have run. | 424 | to track what tasks have run and when they have run. |
| 425 | The directory is sub-divided by architecture. | 425 | The directory is sub-divided by architecture. |
| 426 | The files in the directory are empty of data. | 426 | The files in the directory are empty of data. |
| 427 | However, BitBake uses the filenames and timestamps for tracking purposes. | 427 | However, BitBake uses the filenames and timestamps for tracking purposes. |
| 428 | </para> | 428 | </para> |
| @@ -432,9 +432,9 @@ | |||
| 432 | <title><filename>build/tmp/log/</filename></title> | 432 | <title><filename>build/tmp/log/</filename></title> |
| 433 | 433 | ||
| 434 | <para> | 434 | <para> |
| 435 | This directory contains general logs that are not otherwise placed using the | 435 | This directory contains general logs that are not otherwise placed using the |
| 436 | package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>. | 436 | package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>. |
| 437 | Examples of logs are the output from the <filename>check_pkg</filename> or | 437 | Examples of logs are the output from the <filename>check_pkg</filename> or |
| 438 | <filename>distro_check</filename> tasks. | 438 | <filename>distro_check</filename> tasks. |
| 439 | Running a build does not necessarily mean this directory is created. | 439 | Running a build does not necessarily mean this directory is created. |
| 440 | </para> | 440 | </para> |
| @@ -444,7 +444,7 @@ | |||
| 444 | <title><filename>build/tmp/pkgdata/</filename></title> | 444 | <title><filename>build/tmp/pkgdata/</filename></title> |
| 445 | 445 | ||
| 446 | <para> | 446 | <para> |
| 447 | This directory contains intermediate packaging data that is used later in the packaging process. | 447 | This directory contains intermediate packaging data that is used later in the packaging process. |
| 448 | For more information, see the "<link linkend='ref-classes-package'>Packaging - package*.bbclass</link>" section. | 448 | For more information, see the "<link linkend='ref-classes-package'>Packaging - package*.bbclass</link>" section. |
| 449 | </para> | 449 | </para> |
| 450 | </section> | 450 | </section> |
| @@ -453,7 +453,7 @@ | |||
| 453 | <title><filename>build/tmp/work/</filename></title> | 453 | <title><filename>build/tmp/work/</filename></title> |
| 454 | 454 | ||
| 455 | <para> | 455 | <para> |
| 456 | This directory contains architecture-specific work sub-directories for packages built by BitBake. | 456 | This directory contains architecture-specific work sub-directories for packages built by BitBake. |
| 457 | All tasks execute from a work directory. | 457 | All tasks execute from a work directory. |
| 458 | For example, the source for a particular package is unpacked, patched, configured and compiled all | 458 | For example, the source for a particular package is unpacked, patched, configured and compiled all |
| 459 | within its own work directory. | 459 | within its own work directory. |
| @@ -462,31 +462,31 @@ | |||
| 462 | </para> | 462 | </para> |
| 463 | 463 | ||
| 464 | <para> | 464 | <para> |
| 465 | It is worth considering the structure of a typical work directory. | 465 | It is worth considering the structure of a typical work directory. |
| 466 | As an example, consider the <filename>linux-yocto-kernel-3.0</filename> | 466 | As an example, consider the <filename>linux-yocto-kernel-3.0</filename> |
| 467 | on the machine <filename>qemux86</filename> | 467 | on the machine <filename>qemux86</filename> |
| 468 | built within the Yocto Project. | 468 | built within the Yocto Project. |
| 469 | For this package, a work directory of | 469 | For this package, a work directory of |
| 470 | <filename>tmp/work/qemux86-poky-linux/linux-yocto-3.0+git1+<.....></filename>, | 470 | <filename>tmp/work/qemux86-poky-linux/linux-yocto-3.0+git1+<.....></filename>, |
| 471 | referred to as <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created. | 471 | referred to as <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created. |
| 472 | Within this directory, the source is unpacked to | 472 | Within this directory, the source is unpacked to |
| 473 | <filename>linux-qemux86-standard-build</filename> and then patched by Quilt | 473 | <filename>linux-qemux86-standard-build</filename> and then patched by Quilt |
| 474 | (see the | 474 | (see the |
| 475 | "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Modifying Package | 475 | "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Modifying Package |
| 476 | Source Code with Quilt</ulink>" section in the Yocto Project Development Manual. | 476 | Source Code with Quilt</ulink>" section in the Yocto Project Development Manual. |
| 477 | Within the <filename>linux-qemux86-standard-build</filename> directory, | 477 | Within the <filename>linux-qemux86-standard-build</filename> directory, |
| 478 | standard Quilt directories <filename>linux-3.0/patches</filename> | 478 | standard Quilt directories <filename>linux-3.0/patches</filename> |
| 479 | and <filename>linux-3.0/.pc</filename> are created, | 479 | and <filename>linux-3.0/.pc</filename> are created, |
| 480 | and standard Quilt commands can be used. | 480 | and standard Quilt commands can be used. |
| 481 | </para> | 481 | </para> |
| 482 | 482 | ||
| 483 | <para> | 483 | <para> |
| 484 | There are other directories generated within WORKDIR. | 484 | There are other directories generated within WORKDIR. |
| 485 | The most important directory is WORKDIR<filename>/temp/</filename>, which has log files for each | 485 | The most important directory is WORKDIR<filename>/temp/</filename>, which has log files for each |
| 486 | task (<filename>log.do_*.pid</filename>) and contains the scripts BitBake runs for | 486 | task (<filename>log.do_*.pid</filename>) and contains the scripts BitBake runs for |
| 487 | each task (<filename>run.do_*.pid</filename>). | 487 | each task (<filename>run.do_*.pid</filename>). |
| 488 | The WORKDIR<filename>/image/</filename> directory is where "make | 488 | The WORKDIR<filename>/image/</filename> directory is where "make |
| 489 | install" places its output that is then split into sub-packages | 489 | install" places its output that is then split into sub-packages |
| 490 | within WORKDIR<filename>/packages-split/</filename>. | 490 | within WORKDIR<filename>/packages-split/</filename>. |
| 491 | </para> | 491 | </para> |
| 492 | </section> | 492 | </section> |
| @@ -496,7 +496,7 @@ | |||
| 496 | <title>The Metadata - <filename>meta/</filename></title> | 496 | <title>The Metadata - <filename>meta/</filename></title> |
| 497 | 497 | ||
| 498 | <para> | 498 | <para> |
| 499 | As mentioned previously, metadata is the core of the Yocto Project. | 499 | As mentioned previously, metadata is the core of the Yocto Project. |
| 500 | Metadata has several important subdivisions: | 500 | Metadata has several important subdivisions: |
| 501 | </para> | 501 | </para> |
| 502 | 502 | ||
| @@ -504,16 +504,16 @@ | |||
| 504 | <title><filename>meta/classes/</filename></title> | 504 | <title><filename>meta/classes/</filename></title> |
| 505 | 505 | ||
| 506 | <para> | 506 | <para> |
| 507 | This directory contains the <filename>*.bbclass</filename> files. | 507 | This directory contains the <filename>*.bbclass</filename> files. |
| 508 | Class files are used to abstract common code so it can be reused by multiple | 508 | Class files are used to abstract common code so it can be reused by multiple |
| 509 | packages. | 509 | packages. |
| 510 | Every package inherits the <filename>base.bbclass</filename> file. | 510 | Every package inherits the <filename>base.bbclass</filename> file. |
| 511 | Examples of other important classes are <filename>autotools.bbclass</filename>, which | 511 | Examples of other important classes are <filename>autotools.bbclass</filename>, which |
| 512 | in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort. | 512 | in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort. |
| 513 | Another example is <filename>kernel.bbclass</filename> that contains common code and functions | 513 | Another example is <filename>kernel.bbclass</filename> that contains common code and functions |
| 514 | for working with the Linux kernel. | 514 | for working with the Linux kernel. |
| 515 | Functions like image generation or packaging also have their specific class files | 515 | Functions like image generation or packaging also have their specific class files |
| 516 | such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and | 516 | such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and |
| 517 | <filename>package*.bbclass</filename>. | 517 | <filename>package*.bbclass</filename>. |
| 518 | </para> | 518 | </para> |
| 519 | </section> | 519 | </section> |
| @@ -522,13 +522,13 @@ | |||
| 522 | <title><filename>meta/conf/</filename></title> | 522 | <title><filename>meta/conf/</filename></title> |
| 523 | 523 | ||
| 524 | <para> | 524 | <para> |
| 525 | This directory contains the core set of configuration files that start from | 525 | This directory contains the core set of configuration files that start from |
| 526 | <filename>bitbake.conf</filename> and from which all other configuration | 526 | <filename>bitbake.conf</filename> and from which all other configuration |
| 527 | files are included. | 527 | files are included. |
| 528 | See the include statements at the end of the file and you will note that even | 528 | See the include statements at the end of the file and you will note that even |
| 529 | <filename>local.conf</filename> is loaded from there. | 529 | <filename>local.conf</filename> is loaded from there. |
| 530 | While <filename>bitbake.conf</filename> sets up the defaults, you can often override | 530 | While <filename>bitbake.conf</filename> sets up the defaults, you can often override |
| 531 | these by using the (<filename>local.conf</filename>) file, machine file or | 531 | these by using the (<filename>local.conf</filename>) file, machine file or |
| 532 | the distribution configuration file. | 532 | the distribution configuration file. |
| 533 | </para> | 533 | </para> |
| 534 | </section> | 534 | </section> |
| @@ -537,11 +537,11 @@ | |||
| 537 | <title><filename>meta/conf/machine/</filename></title> | 537 | <title><filename>meta/conf/machine/</filename></title> |
| 538 | 538 | ||
| 539 | <para> | 539 | <para> |
| 540 | This directory contains all the machine configuration files. | 540 | This directory contains all the machine configuration files. |
| 541 | If you set <filename>MACHINE="qemux86"</filename>, | 541 | If you set <filename>MACHINE="qemux86"</filename>, |
| 542 | the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this | 542 | the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this |
| 543 | directory. | 543 | directory. |
| 544 | The <filename>include</filename> directory contains various data common to multiple machines. | 544 | The <filename>include</filename> directory contains various data common to multiple machines. |
| 545 | If you want to add support for a new machine to the Yocto Project, look in this directory. | 545 | If you want to add support for a new machine to the Yocto Project, look in this directory. |
| 546 | </para> | 546 | </para> |
| 547 | </section> | 547 | </section> |
| @@ -550,10 +550,10 @@ | |||
| 550 | <title><filename>meta/conf/distro/</filename></title> | 550 | <title><filename>meta/conf/distro/</filename></title> |
| 551 | 551 | ||
| 552 | <para> | 552 | <para> |
| 553 | Any distribution-specific configuration is controlled from this directory. | 553 | Any distribution-specific configuration is controlled from this directory. |
| 554 | For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here. | 554 | For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here. |
| 555 | This directory includes the versions and the | 555 | This directory includes the versions and the |
| 556 | <filename>SRCDATE</filename> definitions for applications that are configured here. | 556 | <filename>SRCDATE</filename> definitions for applications that are configured here. |
| 557 | An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>. | 557 | An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>. |
| 558 | Although this file mainly inherits its configuration from Poky. | 558 | Although this file mainly inherits its configuration from Poky. |
| 559 | </para> | 559 | </para> |
| @@ -563,7 +563,7 @@ | |||
| 563 | <title><filename>meta/recipes-bsp/</filename></title> | 563 | <title><filename>meta/recipes-bsp/</filename></title> |
| 564 | 564 | ||
| 565 | <para> | 565 | <para> |
| 566 | This directory contains anything linking to specific hardware or hardware | 566 | This directory contains anything linking to specific hardware or hardware |
| 567 | configuration information such as "u-boot" and "grub". | 567 | configuration information such as "u-boot" and "grub". |
| 568 | </para> | 568 | </para> |
| 569 | </section> | 569 | </section> |
| @@ -580,7 +580,7 @@ | |||
| 580 | <title><filename>meta/recipes-core/</filename></title> | 580 | <title><filename>meta/recipes-core/</filename></title> |
| 581 | 581 | ||
| 582 | <para> | 582 | <para> |
| 583 | This directory contains what is needed to build a basic working Linux image | 583 | This directory contains what is needed to build a basic working Linux image |
| 584 | including commonly used dependencies. | 584 | including commonly used dependencies. |
| 585 | </para> | 585 | </para> |
| 586 | </section> | 586 | </section> |
| @@ -598,8 +598,8 @@ | |||
| 598 | <title><filename>meta/recipes-extended/</filename></title> | 598 | <title><filename>meta/recipes-extended/</filename></title> |
| 599 | 599 | ||
| 600 | <para> | 600 | <para> |
| 601 | This directory contains non-essential applications that add features compared to the | 601 | This directory contains non-essential applications that add features compared to the |
| 602 | alternatives in core. | 602 | alternatives in core. |
| 603 | You might need this directory for full tool functionality or for Linux Standard Base (LSB) | 603 | You might need this directory for full tool functionality or for Linux Standard Base (LSB) |
| 604 | compliance. | 604 | compliance. |
| 605 | </para> | 605 | </para> |
| @@ -625,7 +625,7 @@ | |||
| 625 | <title><filename>meta/recipes-kernel/</filename></title> | 625 | <title><filename>meta/recipes-kernel/</filename></title> |
| 626 | 626 | ||
| 627 | <para> | 627 | <para> |
| 628 | This directory contains the kernel and generic applications and libraries that | 628 | This directory contains the kernel and generic applications and libraries that |
| 629 | have strong kernel dependencies. | 629 | have strong kernel dependencies. |
| 630 | </para> | 630 | </para> |
| 631 | </section> | 631 | </section> |
| @@ -651,7 +651,7 @@ | |||
| 651 | 651 | ||
| 652 | <para> | 652 | <para> |
| 653 | This directory contains package and image recipes for using and testing | 653 | This directory contains package and image recipes for using and testing |
| 654 | the <filename>PREEMPT_RT</filename> kernel. | 654 | the <filename>PREEMPT_RT</filename> kernel. |
| 655 | </para> | 655 | </para> |
| 656 | </section> | 656 | </section> |
| 657 | 657 | ||
| @@ -668,7 +668,7 @@ | |||
| 668 | <title><filename>meta/recipes-support/</filename></title> | 668 | <title><filename>meta/recipes-support/</filename></title> |
| 669 | 669 | ||
| 670 | <para> | 670 | <para> |
| 671 | This directory contains recipes that used by other recipes, but that are not directly | 671 | This directory contains recipes that used by other recipes, but that are not directly |
| 672 | included in images (i.e. dependencies of other recipes). | 672 | included in images (i.e. dependencies of other recipes). |
| 673 | </para> | 673 | </para> |
| 674 | </section> | 674 | </section> |
| @@ -678,9 +678,9 @@ | |||
| 678 | 678 | ||
| 679 | <para> | 679 | <para> |
| 680 | This directory contains a list of cached results for various architectures. | 680 | This directory contains a list of cached results for various architectures. |
| 681 | Because certain "autoconf" test results cannot be determined when cross-compiling due to | 681 | Because certain "autoconf" test results cannot be determined when cross-compiling due to |
| 682 | the tests not able to run on a live system, the information in this directory is | 682 | the tests not able to run on a live system, the information in this directory is |
| 683 | passed to "autoconf" for the various architectures. | 683 | passed to "autoconf" for the various architectures. |
| 684 | </para> | 684 | </para> |
| 685 | </section> | 685 | </section> |
| 686 | 686 | ||
| @@ -694,6 +694,6 @@ | |||
| 694 | </section> | 694 | </section> |
| 695 | 695 | ||
| 696 | </chapter> | 696 | </chapter> |
| 697 | <!-- | 697 | <!-- |
| 698 | vim: expandtab tw=80 ts=4 | 698 | vim: expandtab tw=80 ts=4 |
| 699 | --> | 699 | --> |
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml index 275a7465b8..03875132cc 100644 --- a/documentation/poky-ref-manual/ref-variables.xml +++ b/documentation/poky-ref-manual/ref-variables.xml | |||
| @@ -16,48 +16,48 @@ | |||
| 16 | 16 | ||
| 17 | 17 | ||
| 18 | <para> | 18 | <para> |
| 19 | <link linkend='var-ALLOW_EMPTY'>A</link> | 19 | <link linkend='var-ALLOW_EMPTY'>A</link> |
| 20 | <link linkend='var-B'>B</link> | 20 | <link linkend='var-B'>B</link> |
| 21 | <link linkend='var-CFLAGS'>C</link> | 21 | <link linkend='var-CFLAGS'>C</link> |
| 22 | <link linkend='var-D'>D</link> | 22 | <link linkend='var-D'>D</link> |
| 23 | <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link> | 23 | <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link> |
| 24 | <link linkend='var-FILES'>F</link> | 24 | <link linkend='var-FILES'>F</link> |
| 25 | <!-- <link linkend='var-glossary-g'>G</link> --> | 25 | <!-- <link linkend='var-glossary-g'>G</link> --> |
| 26 | <link linkend='var-HOMEPAGE'>H</link> | 26 | <link linkend='var-HOMEPAGE'>H</link> |
| 27 | <link linkend='var-IMAGE_FEATURES'>I</link> | 27 | <link linkend='var-IMAGE_FEATURES'>I</link> |
| 28 | <!-- <link linkend='var-glossary-j'>J</link> --> | 28 | <!-- <link linkend='var-glossary-j'>J</link> --> |
| 29 | <link linkend='var-KBRANCH'>K</link> | 29 | <link linkend='var-KBRANCH'>K</link> |
| 30 | <link linkend='var-LAYERDIR'>L</link> | 30 | <link linkend='var-LAYERDIR'>L</link> |
| 31 | <link linkend='var-MACHINE'>M</link> | 31 | <link linkend='var-MACHINE'>M</link> |
| 32 | <!-- <link linkend='var-glossary-n'>N</link> --> | 32 | <!-- <link linkend='var-glossary-n'>N</link> --> |
| 33 | <link linkend='var-OE_TERMINAL'>O</link> | 33 | <link linkend='var-OE_TERMINAL'>O</link> |
| 34 | <link linkend='var-P'>P</link> | 34 | <link linkend='var-P'>P</link> |
| 35 | <!-- <link linkend='var-glossary-q'>Q</link> --> | 35 | <!-- <link linkend='var-glossary-q'>Q</link> --> |
| 36 | <link linkend='var-RCONFLICTS'>R</link> | 36 | <link linkend='var-RCONFLICTS'>R</link> |
| 37 | <link linkend='var-S'>S</link> | 37 | <link linkend='var-S'>S</link> |
| 38 | <link linkend='var-T'>T</link> | 38 | <link linkend='var-T'>T</link> |
| 39 | <!-- <link linkend='var-glossary-u'>U</link> --> | 39 | <!-- <link linkend='var-glossary-u'>U</link> --> |
| 40 | <!-- <link linkend='var-glossary-v'>V</link> --> | 40 | <!-- <link linkend='var-glossary-v'>V</link> --> |
| 41 | <link linkend='var-WORKDIR'>W</link> | 41 | <link linkend='var-WORKDIR'>W</link> |
| 42 | <!-- <link linkend='var-glossary-x'>X</link> --> | 42 | <!-- <link linkend='var-glossary-x'>X</link> --> |
| 43 | <!-- <link linkend='var-glossary-y'>Y</link> --> | 43 | <!-- <link linkend='var-glossary-y'>Y</link> --> |
| 44 | <!-- <link linkend='var-glossary-z'>Z</link>--> | 44 | <!-- <link linkend='var-glossary-z'>Z</link>--> |
| 45 | </para> | 45 | </para> |
| 46 | 46 | ||
| 47 | <glossdiv id='var-glossary-a'><title>A</title> | 47 | <glossdiv id='var-glossary-a'><title>A</title> |
| 48 | 48 | ||
| 49 | <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm> | 49 | <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm> |
| 50 | <glossdef> | 50 | <glossdef> |
| 51 | <para> | 51 | <para> |
| 52 | Specifies if an output package should still be produced if it is empty. | 52 | Specifies if an output package should still be produced if it is empty. |
| 53 | By default, BitBake does not produce empty packages. | 53 | By default, BitBake does not produce empty packages. |
| 54 | This default behavior can cause issues when there is an | 54 | This default behavior can cause issues when there is an |
| 55 | <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or | 55 | <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or |
| 56 | some other runtime hard-requirement on the existence of the package. | 56 | some other runtime hard-requirement on the existence of the package. |
| 57 | </para> | 57 | </para> |
| 58 | 58 | ||
| 59 | <para> | 59 | <para> |
| 60 | Like all package-controlling variables, you must always use them in | 60 | Like all package-controlling variables, you must always use them in |
| 61 | conjunction with a package name override. | 61 | conjunction with a package name override. |
| 62 | Here is an example: | 62 | Here is an example: |
| 63 | <literallayout class='monospaced'> | 63 | <literallayout class='monospaced'> |
| @@ -69,7 +69,7 @@ | |||
| 69 | 69 | ||
| 70 | <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm> | 70 | <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm> |
| 71 | <glossdef> | 71 | <glossdef> |
| 72 | <para>The email address used to contact the original author or authors in | 72 | <para>The email address used to contact the original author or authors in |
| 73 | order to send patches, forward bugs, etc.</para> | 73 | order to send patches, forward bugs, etc.</para> |
| 74 | </glossdef> | 74 | </glossdef> |
| 75 | </glossentry> | 75 | </glossentry> |
| @@ -86,7 +86,7 @@ | |||
| 86 | </glossdef> | 86 | </glossdef> |
| 87 | </glossentry> | 87 | </glossentry> |
| 88 | 88 | ||
| 89 | </glossdiv> | 89 | </glossdiv> |
| 90 | 90 | ||
| 91 | <glossdiv id='var-glossary-b'><title>B</title> | 91 | <glossdiv id='var-glossary-b'><title>B</title> |
| 92 | 92 | ||
| @@ -101,7 +101,7 @@ | |||
| 101 | <literallayout class='monospaced'> | 101 | <literallayout class='monospaced'> |
| 102 | B = ${WORKDIR}/${BPN}-{PV}/ | 102 | B = ${WORKDIR}/${BPN}-{PV}/ |
| 103 | </literallayout> | 103 | </literallayout> |
| 104 | You can separate the (<filename>S</filename>) directory and the directory pointed to | 104 | You can separate the (<filename>S</filename>) directory and the directory pointed to |
| 105 | by the <filename>B</filename> variable. | 105 | by the <filename>B</filename> variable. |
| 106 | Most autotools-based recipes support separating these directories. | 106 | Most autotools-based recipes support separating these directories. |
| 107 | The build system defaults to using separate directories for <filename>gcc</filename> | 107 | The build system defaults to using separate directories for <filename>gcc</filename> |
| @@ -114,7 +114,7 @@ | |||
| 114 | <glossdef> | 114 | <glossdef> |
| 115 | <para> | 115 | <para> |
| 116 | A list of packages not to install despite being recommended by a recipe. | 116 | A list of packages not to install despite being recommended by a recipe. |
| 117 | Support for this variable exists only when using the | 117 | Support for this variable exists only when using the |
| 118 | <filename>ipk</filename> packaging backend. | 118 | <filename>ipk</filename> packaging backend. |
| 119 | </para> | 119 | </para> |
| 120 | </glossdef> | 120 | </glossdef> |
| @@ -124,50 +124,50 @@ | |||
| 124 | <glossdef> | 124 | <glossdef> |
| 125 | <para> | 125 | <para> |
| 126 | Monitors disk space and available inodes during the build | 126 | Monitors disk space and available inodes during the build |
| 127 | and allows you to control the build based on these | 127 | and allows you to control the build based on these |
| 128 | parameters. | 128 | parameters. |
| 129 | </para> | 129 | </para> |
| 130 | 130 | ||
| 131 | <para> | 131 | <para> |
| 132 | Disk space monitoring is disabled by default. | 132 | Disk space monitoring is disabled by default. |
| 133 | To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename> | 133 | To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename> |
| 134 | variable to your <filename>conf/local.conf</filename> file found in the | 134 | variable to your <filename>conf/local.conf</filename> file found in the |
| 135 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | 135 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
| 136 | Use the following form: | 136 | Use the following form: |
| 137 | <literallayout class='monospaced'> | 137 | <literallayout class='monospaced'> |
| 138 | BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" | 138 | BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" |
| 139 | 139 | ||
| 140 | where: | 140 | where: |
| 141 | 141 | ||
| 142 | <action> is: | 142 | <action> is: |
| 143 | ABORT: Immediately abort the build when | 143 | ABORT: Immediately abort the build when |
| 144 | a threshold is broken. | 144 | a threshold is broken. |
| 145 | STOPTASKS: Stop the build after the currently | 145 | STOPTASKS: Stop the build after the currently |
| 146 | executing tasks have finished when | 146 | executing tasks have finished when |
| 147 | a threshold is broken. | 147 | a threshold is broken. |
| 148 | WARN: Issue a warning but continue the | 148 | WARN: Issue a warning but continue the |
| 149 | build when a threshold is broken. | 149 | build when a threshold is broken. |
| 150 | Subsequent warnings are issued as | 150 | Subsequent warnings are issued as |
| 151 | defined by the | 151 | defined by the |
| 152 | <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable, | 152 | <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable, |
| 153 | which must be defined in the | 153 | which must be defined in the |
| 154 | conf/local.conf file. | 154 | conf/local.conf file. |
| 155 | 155 | ||
| 156 | <dir> is: | 156 | <dir> is: |
| 157 | Any directory you choose. You can specify one or | 157 | Any directory you choose. You can specify one or |
| 158 | more directories to monitor by separating the | 158 | more directories to monitor by separating the |
| 159 | groupings with a space. If two directories are | 159 | groupings with a space. If two directories are |
| 160 | on the same device, only the first directory | 160 | on the same device, only the first directory |
| 161 | is monitored. | 161 | is monitored. |
| 162 | 162 | ||
| 163 | <threshold> is: | 163 | <threshold> is: |
| 164 | Either the minimum available disk space, | 164 | Either the minimum available disk space, |
| 165 | the minimum number of free inodes, or | 165 | the minimum number of free inodes, or |
| 166 | both. You must specify at least one. To | 166 | both. You must specify at least one. To |
| 167 | omit one or the other, simply omit the value. | 167 | omit one or the other, simply omit the value. |
| 168 | Specify the threshold using G, M, K for Gbytes, | 168 | Specify the threshold using G, M, K for Gbytes, |
| 169 | Mbytes, and Kbytes, respectively. If you do | 169 | Mbytes, and Kbytes, respectively. If you do |
| 170 | not specify G, M, or K, Kbytes is assumed by | 170 | not specify G, M, or K, Kbytes is assumed by |
| 171 | default. Do not use GB, MB, or KB. | 171 | default. Do not use GB, MB, or KB. |
| 172 | </literallayout> | 172 | </literallayout> |
| 173 | </para> | 173 | </para> |
| @@ -179,36 +179,36 @@ | |||
| 179 | BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" | 179 | BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" |
| 180 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" | 180 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" |
| 181 | </literallayout> | 181 | </literallayout> |
| 182 | The first example works only if you also provide | 182 | The first example works only if you also provide |
| 183 | the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable | 183 | the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable |
| 184 | in the <filename>conf/local.conf</filename>. | 184 | in the <filename>conf/local.conf</filename>. |
| 185 | This example causes the build system to immediately | 185 | This example causes the build system to immediately |
| 186 | abort when either the disk space in <filename>${TMPDIR}</filename> drops | 186 | abort when either the disk space in <filename>${TMPDIR}</filename> drops |
| 187 | below 1 Gbyte or the available free inodes drops below | 187 | below 1 Gbyte or the available free inodes drops below |
| 188 | 100 Kbytes. | 188 | 100 Kbytes. |
| 189 | Because two directories are provided with the variable, the | 189 | Because two directories are provided with the variable, the |
| 190 | build system also issue a | 190 | build system also issue a |
| 191 | warning when the disk space in the | 191 | warning when the disk space in the |
| 192 | <filename>${SSTATE_DIR}</filename> directory drops | 192 | <filename>${SSTATE_DIR}</filename> directory drops |
| 193 | below 1 Gbyte or the number of free inodes drops | 193 | below 1 Gbyte or the number of free inodes drops |
| 194 | below 100 Kbytes. | 194 | below 100 Kbytes. |
| 195 | Subsequent warnings are issued during intervals as | 195 | Subsequent warnings are issued during intervals as |
| 196 | defined by the <filename>BB_DISKMON_WARNINTERVAL</filename> | 196 | defined by the <filename>BB_DISKMON_WARNINTERVAL</filename> |
| 197 | variable. | 197 | variable. |
| 198 | </para> | 198 | </para> |
| 199 | 199 | ||
| 200 | <para> | 200 | <para> |
| 201 | The second example stops the build after all currently | 201 | The second example stops the build after all currently |
| 202 | executing tasks complete when the minimum disk space | 202 | executing tasks complete when the minimum disk space |
| 203 | in the <filename>${TMPDIR}</filename> directory drops | 203 | in the <filename>${TMPDIR}</filename> directory drops |
| 204 | below 1 Gbyte. | 204 | below 1 Gbyte. |
| 205 | No disk monitoring occurs for the free inodes in this case. | 205 | No disk monitoring occurs for the free inodes in this case. |
| 206 | </para> | 206 | </para> |
| 207 | 207 | ||
| 208 | <para> | 208 | <para> |
| 209 | The final example immediately aborts the build when the | 209 | The final example immediately aborts the build when the |
| 210 | number of free inodes in the <filename>${TMPDIR}</filename> directory | 210 | number of free inodes in the <filename>${TMPDIR}</filename> directory |
| 211 | drops below 100 Kbytes. | 211 | drops below 100 Kbytes. |
| 212 | No disk space monitoring for the directory itself occurs | 212 | No disk space monitoring for the directory itself occurs |
| 213 | in this case. | 213 | in this case. |
| 214 | </para> | 214 | </para> |
| @@ -219,26 +219,26 @@ | |||
| 219 | <glossdef> | 219 | <glossdef> |
| 220 | <para> | 220 | <para> |
| 221 | Defines the disk space and free inode warning intervals. | 221 | Defines the disk space and free inode warning intervals. |
| 222 | To set these intervals, define the variable in your | 222 | To set these intervals, define the variable in your |
| 223 | <filename>conf/local.conf</filename> file in the | 223 | <filename>conf/local.conf</filename> file in the |
| 224 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | 224 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
| 225 | </para> | 225 | </para> |
| 226 | 226 | ||
| 227 | <para> | 227 | <para> |
| 228 | If you are going to use the | 228 | If you are going to use the |
| 229 | <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must | 229 | <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must |
| 230 | also use the | 230 | also use the |
| 231 | <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable | 231 | <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable |
| 232 | and define its action as "WARN". | 232 | and define its action as "WARN". |
| 233 | During the build, subsequent warnings are issued each time | 233 | During the build, subsequent warnings are issued each time |
| 234 | disk space or number of free inodes further reduces by | 234 | disk space or number of free inodes further reduces by |
| 235 | the respective interval. | 235 | the respective interval. |
| 236 | </para> | 236 | </para> |
| 237 | 237 | ||
| 238 | <para> | 238 | <para> |
| 239 | If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename> | 239 | If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename> |
| 240 | variable and you do use <filename>BB_DISKMON_DIRS</filename> with | 240 | variable and you do use <filename>BB_DISKMON_DIRS</filename> with |
| 241 | the "WARN" action, the disk monitoring interval defaults to | 241 | the "WARN" action, the disk monitoring interval defaults to |
| 242 | the following: | 242 | the following: |
| 243 | <literallayout class='monospaced'> | 243 | <literallayout class='monospaced'> |
| 244 | BB_DISKMON_WARNINTERVAL = "50M,5K" | 244 | BB_DISKMON_WARNINTERVAL = "50M,5K" |
| @@ -246,22 +246,22 @@ | |||
| 246 | </para> | 246 | </para> |
| 247 | 247 | ||
| 248 | <para> | 248 | <para> |
| 249 | When specifying the variable in your configuration file, | 249 | When specifying the variable in your configuration file, |
| 250 | use the following form: | 250 | use the following form: |
| 251 | <literallayout class='monospaced'> | 251 | <literallayout class='monospaced'> |
| 252 | BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" | 252 | BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" |
| 253 | 253 | ||
| 254 | where: | 254 | where: |
| 255 | 255 | ||
| 256 | <disk_space_interval> is: | 256 | <disk_space_interval> is: |
| 257 | An interval of memory expressed in either | 257 | An interval of memory expressed in either |
| 258 | G, M, or K for Gbytes, Mbytes, or Kbytes, | 258 | G, M, or K for Gbytes, Mbytes, or Kbytes, |
| 259 | respectively. You cannot use GB, MB, or KB. | 259 | respectively. You cannot use GB, MB, or KB. |
| 260 | 260 | ||
| 261 | <disk_inode_interval> is: | 261 | <disk_inode_interval> is: |
| 262 | An interval of free inodes expressed in either | 262 | An interval of free inodes expressed in either |
| 263 | G, M, or K for Gbytes, Mbytes, or Kbytes, | 263 | G, M, or K for Gbytes, Mbytes, or Kbytes, |
| 264 | respectively. You cannot use GB, MB, or KB. | 264 | respectively. You cannot use GB, MB, or KB. |
| 265 | </literallayout> | 265 | </literallayout> |
| 266 | </para> | 266 | </para> |
| 267 | 267 | ||
| @@ -271,12 +271,12 @@ | |||
| 271 | BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" | 271 | BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" |
| 272 | BB_DISKMON_WARNINTERVAL = "50M,5K" | 272 | BB_DISKMON_WARNINTERVAL = "50M,5K" |
| 273 | </literallayout> | 273 | </literallayout> |
| 274 | These variables cause the OpenEmbedded build system to | 274 | These variables cause the OpenEmbedded build system to |
| 275 | issue subsequent warnings each time the available | 275 | issue subsequent warnings each time the available |
| 276 | disk space further reduces by 50 Mbytes or the number | 276 | disk space further reduces by 50 Mbytes or the number |
| 277 | of free inodes further reduces by 5 Kbytes in the | 277 | of free inodes further reduces by 5 Kbytes in the |
| 278 | <filename>${SSTATE_DIR}</filename> directory. | 278 | <filename>${SSTATE_DIR}</filename> directory. |
| 279 | Subsequent warnings based on the interval occur each time | 279 | Subsequent warnings based on the interval occur each time |
| 280 | a respective interval is reached beyond the intial warning | 280 | a respective interval is reached beyond the intial warning |
| 281 | (i.e. 1 Gbytes and 100 Kbytes). | 281 | (i.e. 1 Gbytes and 100 Kbytes). |
| 282 | </para> | 282 | </para> |
| @@ -310,24 +310,24 @@ | |||
| 310 | <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm> | 310 | <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm> |
| 311 | <glossdef> | 311 | <glossdef> |
| 312 | <para>Prevents BitBake from processing recipes and recipe append files. | 312 | <para>Prevents BitBake from processing recipes and recipe append files. |
| 313 | You can use the <filename>BBMASK</filename> variable to "hide" | 313 | You can use the <filename>BBMASK</filename> variable to "hide" |
| 314 | these <filename>.bb</filename> and <filename>.bbappend</filename> files. | 314 | these <filename>.bb</filename> and <filename>.bbappend</filename> files. |
| 315 | BitBake ignores any recipe or recipe append files that match the expression. | 315 | BitBake ignores any recipe or recipe append files that match the expression. |
| 316 | It is as if BitBake does not see them at all. | 316 | It is as if BitBake does not see them at all. |
| 317 | Consequently, matching files are not parsed or otherwise used by | 317 | Consequently, matching files are not parsed or otherwise used by |
| 318 | BitBake.</para> | 318 | BitBake.</para> |
| 319 | <para>The value you provide is passed to python's regular expression compiler. | 319 | <para>The value you provide is passed to python's regular expression compiler. |
| 320 | For complete syntax information, see python's documentation at | 320 | For complete syntax information, see python's documentation at |
| 321 | <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>. | 321 | <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>. |
| 322 | The expression is compared against the full paths to the files. | 322 | The expression is compared against the full paths to the files. |
| 323 | For example, the following uses a complete regular expression to tell | 323 | For example, the following uses a complete regular expression to tell |
| 324 | BitBake to ignore all recipe and recipe append files in the | 324 | BitBake to ignore all recipe and recipe append files in the |
| 325 | <filename>.*/meta-ti/recipes-misc/</filename> directory: | 325 | <filename>.*/meta-ti/recipes-misc/</filename> directory: |
| 326 | <literallayout class='monospaced'> | 326 | <literallayout class='monospaced'> |
| 327 | BBMASK = ".*/meta-ti/recipes-misc/" | 327 | BBMASK = ".*/meta-ti/recipes-misc/" |
| 328 | </literallayout></para> | 328 | </literallayout></para> |
| 329 | <para>Use the <filename>BBMASK</filename> variable from within the | 329 | <para>Use the <filename>BBMASK</filename> variable from within the |
| 330 | <filename>conf/local.conf</filename> file found | 330 | <filename>conf/local.conf</filename> file found |
| 331 | in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.</para> | 331 | in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.</para> |
| 332 | </glossdef> | 332 | </glossdef> |
| 333 | </glossentry> | 333 | </glossentry> |
| @@ -342,9 +342,9 @@ | |||
| 342 | 342 | ||
| 343 | <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm> | 343 | <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm> |
| 344 | <glossdef> | 344 | <glossdef> |
| 345 | <para>Lists the names of configured layers. | 345 | <para>Lists the names of configured layers. |
| 346 | These names are used to find the other <filename>BBFILE_*</filename> | 346 | These names are used to find the other <filename>BBFILE_*</filename> |
| 347 | variables. | 347 | variables. |
| 348 | Typically, each layer will append its name to this variable in its | 348 | Typically, each layer will append its name to this variable in its |
| 349 | <filename>conf/layer.conf</filename> file. | 349 | <filename>conf/layer.conf</filename> file. |
| 350 | </para> | 350 | </para> |
| @@ -353,9 +353,9 @@ | |||
| 353 | 353 | ||
| 354 | <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm> | 354 | <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm> |
| 355 | <glossdef> | 355 | <glossdef> |
| 356 | <para>Variable that expands to match files from <filename>BBFILES</filename> in a particular layer. | 356 | <para>Variable that expands to match files from <filename>BBFILES</filename> in a particular layer. |
| 357 | This variable is used in the <filename>conf/layer.conf</filename> file and must | 357 | This variable is used in the <filename>conf/layer.conf</filename> file and must |
| 358 | be suffixed with the name of the specific layer (e.g. | 358 | be suffixed with the name of the specific layer (e.g. |
| 359 | <filename>BBFILE_PATTERN_emenlow</filename>).</para> | 359 | <filename>BBFILE_PATTERN_emenlow</filename>).</para> |
| 360 | </glossdef> | 360 | </glossdef> |
| 361 | </glossentry> | 361 | </glossentry> |
| @@ -364,21 +364,21 @@ | |||
| 364 | <glossdef> | 364 | <glossdef> |
| 365 | <para>Assigns the priority for recipe files in each layer.</para> | 365 | <para>Assigns the priority for recipe files in each layer.</para> |
| 366 | <para>This variable is useful in situations where the same recipe appears in | 366 | <para>This variable is useful in situations where the same recipe appears in |
| 367 | more than one layer. | 367 | more than one layer. |
| 368 | Setting this variable allows you to prioritize a | 368 | Setting this variable allows you to prioritize a |
| 369 | layer against other layers that contain the same recipe - effectively | 369 | layer against other layers that contain the same recipe - effectively |
| 370 | letting you control the precedence for the multiple layers. | 370 | letting you control the precedence for the multiple layers. |
| 371 | The precedence established through this variable stands regardless of a | 371 | The precedence established through this variable stands regardless of a |
| 372 | recipe's version (<filename>PV</filename> variable). | 372 | recipe's version (<filename>PV</filename> variable). |
| 373 | For example, a layer that has a recipe with a higher <filename>PV</filename> value but for | 373 | For example, a layer that has a recipe with a higher <filename>PV</filename> value but for |
| 374 | which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a | 374 | which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a |
| 375 | lower precedence.</para> | 375 | lower precedence.</para> |
| 376 | <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher | 376 | <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher |
| 377 | precedence. | 377 | precedence. |
| 378 | For example, the value 6 has a higher precedence than the value 5. | 378 | For example, the value 6 has a higher precedence than the value 5. |
| 379 | If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer | 379 | If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer |
| 380 | dependencies (see the | 380 | dependencies (see the |
| 381 | <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for | 381 | <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for |
| 382 | more information. | 382 | more information. |
| 383 | The default priority, if unspecified | 383 | The default priority, if unspecified |
| 384 | for a layer with no dependencies, is the lowest defined priority + 1 | 384 | for a layer with no dependencies, is the lowest defined priority + 1 |
| @@ -398,7 +398,7 @@ | |||
| 398 | 398 | ||
| 399 | <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm> | 399 | <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm> |
| 400 | <glossdef> | 400 | <glossdef> |
| 401 | <para>Used by BitBake to locate <filename>.bbclass</filename> and configuration files. | 401 | <para>Used by BitBake to locate <filename>.bbclass</filename> and configuration files. |
| 402 | This variable is analogous to the <filename>PATH</filename> variable.</para> | 402 | This variable is analogous to the <filename>PATH</filename> variable.</para> |
| 403 | </glossdef> | 403 | </glossdef> |
| 404 | </glossentry> | 404 | </glossentry> |
| @@ -411,9 +411,9 @@ | |||
| 411 | 411 | ||
| 412 | <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm> | 412 | <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm> |
| 413 | <glossdef> | 413 | <glossdef> |
| 414 | <para>Lists the layers to enable during the build. | 414 | <para>Lists the layers to enable during the build. |
| 415 | This variable is defined in the <filename>bblayers.conf</filename> configuration | 415 | This variable is defined in the <filename>bblayers.conf</filename> configuration |
| 416 | file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | 416 | file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
| 417 | Here is an example: | 417 | Here is an example: |
| 418 | <literallayout class='monospaced'> | 418 | <literallayout class='monospaced'> |
| 419 | BBLAYERS = " \ | 419 | BBLAYERS = " \ |
| @@ -428,7 +428,7 @@ | |||
| 428 | /home/scottrif/poky/meta-yocto \ | 428 | /home/scottrif/poky/meta-yocto \ |
| 429 | " | 429 | " |
| 430 | </literallayout> | 430 | </literallayout> |
| 431 | This example enables four layers, one of which is a custom, user-defined layer | 431 | This example enables four layers, one of which is a custom, user-defined layer |
| 432 | named <filename>meta-mykernel</filename>. | 432 | named <filename>meta-mykernel</filename>. |
| 433 | </para> | 433 | </para> |
| 434 | </glossdef> | 434 | </glossdef> |
| @@ -464,7 +464,7 @@ Core layer for images cannot be removed | |||
| 464 | 464 | ||
| 465 | <glossentry id='var-BP'><glossterm>BP</glossterm> | 465 | <glossentry id='var-BP'><glossterm>BP</glossterm> |
| 466 | <glossdef> | 466 | <glossdef> |
| 467 | <para>The base recipe name and version but without any special | 467 | <para>The base recipe name and version but without any special |
| 468 | recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>, | 468 | recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>, |
| 469 | and so forth). | 469 | and so forth). |
| 470 | <filename>BP</filename> is comprised of the following: | 470 | <filename>BP</filename> is comprised of the following: |
| @@ -495,8 +495,8 @@ Core layer for images cannot be removed | |||
| 495 | <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm> | 495 | <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm> |
| 496 | <glossdef> | 496 | <glossdef> |
| 497 | <para> | 497 | <para> |
| 498 | Flags passed to C compiler for the target system. | 498 | Flags passed to C compiler for the target system. |
| 499 | This variable evaluates to the same as | 499 | This variable evaluates to the same as |
| 500 | <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>. | 500 | <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>. |
| 501 | </para> | 501 | </para> |
| 502 | </glossdef> | 502 | </glossdef> |
| @@ -504,7 +504,7 @@ Core layer for images cannot be removed | |||
| 504 | 504 | ||
| 505 | <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm> | 505 | <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm> |
| 506 | <glossdef> | 506 | <glossdef> |
| 507 | <para>A set of features common between | 507 | <para>A set of features common between |
| 508 | <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> | 508 | <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> |
| 509 | and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. | 509 | and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. |
| 510 | See the glossary descriptions for these variables for more information.</para> | 510 | See the glossary descriptions for these variables for more information.</para> |
| @@ -513,11 +513,11 @@ Core layer for images cannot be removed | |||
| 513 | 513 | ||
| 514 | <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm> | 514 | <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm> |
| 515 | <glossdef> | 515 | <glossdef> |
| 516 | <para>A regular expression which evaluates to match the machines the recipe | 516 | <para>A regular expression which evaluates to match the machines the recipe |
| 517 | works with. | 517 | works with. |
| 518 | It stops recipes being run on machines for which they are not compatible. | 518 | It stops recipes being run on machines for which they are not compatible. |
| 519 | This is particularly useful with kernels. | 519 | This is particularly useful with kernels. |
| 520 | It also helps to increase parsing speed as further parsing of the recipe is skipped | 520 | It also helps to increase parsing speed as further parsing of the recipe is skipped |
| 521 | if it is found the current machine is not compatible.</para> | 521 | if it is found the current machine is not compatible.</para> |
| 522 | </glossdef> | 522 | </glossdef> |
| 523 | </glossentry> | 523 | </glossentry> |
| @@ -527,46 +527,46 @@ Core layer for images cannot be removed | |||
| 527 | <para> | 527 | <para> |
| 528 | Identifies editable or configurable files that are part of a package. | 528 | Identifies editable or configurable files that are part of a package. |
| 529 | If the Package Management System (PMS) is being used to update | 529 | If the Package Management System (PMS) is being used to update |
| 530 | packages on the target system, it is possible that | 530 | packages on the target system, it is possible that |
| 531 | configuration files you have changed after the original installation | 531 | configuration files you have changed after the original installation |
| 532 | and that you now want to remain unchanged are overwritten. | 532 | and that you now want to remain unchanged are overwritten. |
| 533 | In other words, editable files might exist in the package that you do not | 533 | In other words, editable files might exist in the package that you do not |
| 534 | want reset as part of the package update process. | 534 | want reset as part of the package update process. |
| 535 | You can use the <filename>CONFFILES</filename> variable to list the files in the | 535 | You can use the <filename>CONFFILES</filename> variable to list the files in the |
| 536 | package that you wish to prevent the PMS from overwriting during this update process. | 536 | package that you wish to prevent the PMS from overwriting during this update process. |
| 537 | </para> | 537 | </para> |
| 538 | 538 | ||
| 539 | <para> | 539 | <para> |
| 540 | To use the <filename>CONFFILES</filename> variable, provide a package name | 540 | To use the <filename>CONFFILES</filename> variable, provide a package name |
| 541 | override that identifies the resulting package. | 541 | override that identifies the resulting package. |
| 542 | Then, provide a space-separated list of files. | 542 | Then, provide a space-separated list of files. |
| 543 | Here is an example: | 543 | Here is an example: |
| 544 | <literallayout class='monospaced'> | 544 | <literallayout class='monospaced'> |
| 545 | CONFFILES_${PN} += "${sysconfdir}/file1 \ | 545 | CONFFILES_${PN} += "${sysconfdir}/file1 \ |
| 546 | ${sysconfdir}/file2 ${sysconfdir}/file3" | 546 | ${sysconfdir}/file2 ${sysconfdir}/file3" |
| 547 | </literallayout> | 547 | </literallayout> |
| 548 | </para> | 548 | </para> |
| 549 | 549 | ||
| 550 | <para> | 550 | <para> |
| 551 | A relationship exists between the <filename>CONFFILES</filename> and | 551 | A relationship exists between the <filename>CONFFILES</filename> and |
| 552 | <filename><link linkend='var-FILES'>FILES</link></filename> variables. | 552 | <filename><link linkend='var-FILES'>FILES</link></filename> variables. |
| 553 | The files listed within <filename>CONFFILES</filename> must be a subset of | 553 | The files listed within <filename>CONFFILES</filename> must be a subset of |
| 554 | the files listed within <filename>FILES</filename>. | 554 | the files listed within <filename>FILES</filename>. |
| 555 | Because the configuration files you provide with <filename>CONFFILES</filename> | 555 | Because the configuration files you provide with <filename>CONFFILES</filename> |
| 556 | are simply being identified so that the PMS will not overwrite them, | 556 | are simply being identified so that the PMS will not overwrite them, |
| 557 | it makes sense that | 557 | it makes sense that |
| 558 | the files must already be included as part of the package through the | 558 | the files must already be included as part of the package through the |
| 559 | <filename>FILES</filename> variable. | 559 | <filename>FILES</filename> variable. |
| 560 | </para> | 560 | </para> |
| 561 | 561 | ||
| 562 | <note> | 562 | <note> |
| 563 | When specifying paths as part of the <filename>CONFFILES</filename> variable, | 563 | When specifying paths as part of the <filename>CONFFILES</filename> variable, |
| 564 | it is good practice to use appropriate path variables. | 564 | it is good practice to use appropriate path variables. |
| 565 | For example, <filename>${sysconfdir}</filename> rather than | 565 | For example, <filename>${sysconfdir}</filename> rather than |
| 566 | <filename>/etc</filename> or <filename>${bindir}</filename> rather | 566 | <filename>/etc</filename> or <filename>${bindir}</filename> rather |
| 567 | than <filename>/usr/bin</filename>. | 567 | than <filename>/usr/bin</filename>. |
| 568 | You can find a list of these variables at the top of the | 568 | You can find a list of these variables at the top of the |
| 569 | <filename>/meta/conf/bitbake.conf</filename> file in the | 569 | <filename>/meta/conf/bitbake.conf</filename> file in the |
| 570 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 570 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 571 | </note> | 571 | </note> |
| 572 | </glossdef> | 572 | </glossdef> |
| @@ -575,9 +575,9 @@ Core layer for images cannot be removed | |||
| 575 | <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm> | 575 | <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm> |
| 576 | <glossdef> | 576 | <glossdef> |
| 577 | <para> | 577 | <para> |
| 578 | A list of files that contains <filename>autoconf</filename> test results relevant | 578 | A list of files that contains <filename>autoconf</filename> test results relevant |
| 579 | to the current build. | 579 | to the current build. |
| 580 | This variable is used by the Autotools utilities when running | 580 | This variable is used by the Autotools utilities when running |
| 581 | <filename>configure</filename>. | 581 | <filename>configure</filename>. |
| 582 | </para> | 582 | </para> |
| 583 | </glossdef> | 583 | </glossdef> |
| @@ -586,9 +586,9 @@ Core layer for images cannot be removed | |||
| 586 | <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm> | 586 | <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm> |
| 587 | <glossdef> | 587 | <glossdef> |
| 588 | <para> | 588 | <para> |
| 589 | Specifies the list of packages to be added to the image. | 589 | Specifies the list of packages to be added to the image. |
| 590 | This variable should only be set in the <filename>local.conf</filename> | 590 | This variable should only be set in the <filename>local.conf</filename> |
| 591 | configuration file found in the | 591 | configuration file found in the |
| 592 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | 592 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
| 593 | </para> | 593 | </para> |
| 594 | 594 | ||
| @@ -611,9 +611,9 @@ Core layer for images cannot be removed | |||
| 611 | <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm> | 611 | <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm> |
| 612 | <glossdef> | 612 | <glossdef> |
| 613 | <para> | 613 | <para> |
| 614 | Specifies to build packages with debugging information. | 614 | Specifies to build packages with debugging information. |
| 615 | This influences the value of the | 615 | This influences the value of the |
| 616 | <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename> | 616 | <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename> |
| 617 | variable. | 617 | variable. |
| 618 | </para> | 618 | </para> |
| 619 | </glossdef> | 619 | </glossdef> |
| @@ -622,9 +622,9 @@ Core layer for images cannot be removed | |||
| 622 | <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm> | 622 | <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm> |
| 623 | <glossdef> | 623 | <glossdef> |
| 624 | <para> | 624 | <para> |
| 625 | The options to pass in | 625 | The options to pass in |
| 626 | <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> | 626 | <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> |
| 627 | and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling | 627 | and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling |
| 628 | a system for debugging. | 628 | a system for debugging. |
| 629 | This variable defaults to "-O -fno-omit-frame-pointer -g". | 629 | This variable defaults to "-O -fno-omit-frame-pointer -g". |
| 630 | </para> | 630 | </para> |
| @@ -641,9 +641,9 @@ Core layer for images cannot be removed | |||
| 641 | <glossdef> | 641 | <glossdef> |
| 642 | <para> | 642 | <para> |
| 643 | Lists a recipe's build-time dependencies | 643 | Lists a recipe's build-time dependencies |
| 644 | (i.e. other recipe files). | 644 | (i.e. other recipe files). |
| 645 | The system ensures that all the dependencies listed | 645 | The system ensures that all the dependencies listed |
| 646 | have been built and have their contents in the appropriate | 646 | have been built and have their contents in the appropriate |
| 647 | sysroots before the recipe's configure task is executed. | 647 | sysroots before the recipe's configure task is executed. |
| 648 | </para> | 648 | </para> |
| 649 | </glossdef> | 649 | </glossdef> |
| @@ -652,8 +652,8 @@ Core layer for images cannot be removed | |||
| 652 | <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm> | 652 | <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm> |
| 653 | <glossdef> | 653 | <glossdef> |
| 654 | <para>The package description used by package managers. | 654 | <para>The package description used by package managers. |
| 655 | If not set, <filename>DESCRIPTION</filename> takes | 655 | If not set, <filename>DESCRIPTION</filename> takes |
| 656 | the value of the | 656 | the value of the |
| 657 | <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link> | 657 | <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link> |
| 658 | variable. | 658 | variable. |
| 659 | </para> | 659 | </para> |
| @@ -669,11 +669,11 @@ Core layer for images cannot be removed | |||
| 669 | <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm> | 669 | <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm> |
| 670 | <glossdef> | 670 | <glossdef> |
| 671 | <para> | 671 | <para> |
| 672 | The short name of the distribution. | 672 | The short name of the distribution. |
| 673 | This variable corresponds to a file with the | 673 | This variable corresponds to a file with the |
| 674 | extension <filename>.conf</filename> | 674 | extension <filename>.conf</filename> |
| 675 | located in a <filename>conf/distro</filename> directory | 675 | located in a <filename>conf/distro</filename> directory |
| 676 | within the metadata that contains the distribution configuration. | 676 | within the metadata that contains the distribution configuration. |
| 677 | The | 677 | The |
| 678 | value must not contain spaces, and is typically all lower-case. | 678 | value must not contain spaces, and is typically all lower-case. |
| 679 | </para> | 679 | </para> |
| @@ -689,11 +689,11 @@ Core layer for images cannot be removed | |||
| 689 | <glossdef> | 689 | <glossdef> |
| 690 | <para> | 690 | <para> |
| 691 | Specifies a list of distro-specific packages to add to all images. | 691 | Specifies a list of distro-specific packages to add to all images. |
| 692 | This variable takes affect through | 692 | This variable takes affect through |
| 693 | <filename>packagegroup-base</filename> so the | 693 | <filename>packagegroup-base</filename> so the |
| 694 | variable only really applies to the more full-featured | 694 | variable only really applies to the more full-featured |
| 695 | images that include <filename>packagegroup-base</filename>. | 695 | images that include <filename>packagegroup-base</filename>. |
| 696 | You can use this variable to keep distro policy out of | 696 | You can use this variable to keep distro policy out of |
| 697 | generic images. | 697 | generic images. |
| 698 | As with all other distro variables, you set this variable | 698 | As with all other distro variables, you set this variable |
| 699 | in the distro <filename>.conf</filename> file. | 699 | in the distro <filename>.conf</filename> file. |
| @@ -704,10 +704,10 @@ Core layer for images cannot be removed | |||
| 704 | <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm> | 704 | <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm> |
| 705 | <glossdef> | 705 | <glossdef> |
| 706 | <para> | 706 | <para> |
| 707 | Specifies a list of distro-specific packages to add to all images | 707 | Specifies a list of distro-specific packages to add to all images |
| 708 | if the packages exist. | 708 | if the packages exist. |
| 709 | The packages might not exist or be empty (e.g. kernel modules). | 709 | The packages might not exist or be empty (e.g. kernel modules). |
| 710 | The list of packages are automatically installed but can be | 710 | The list of packages are automatically installed but can be |
| 711 | removed by the user. | 711 | removed by the user. |
| 712 | </para> | 712 | </para> |
| 713 | </glossdef> | 713 | </glossdef> |
| @@ -725,18 +725,18 @@ Core layer for images cannot be removed | |||
| 725 | 725 | ||
| 726 | <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm> | 726 | <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm> |
| 727 | <glossdef> | 727 | <glossdef> |
| 728 | <para>Features to be added to | 728 | <para>Features to be added to |
| 729 | <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> | 729 | <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> |
| 730 | if not also present in | 730 | if not also present in |
| 731 | <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>. | 731 | <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>. |
| 732 | </para> | 732 | </para> |
| 733 | 733 | ||
| 734 | <para> | 734 | <para> |
| 735 | This variable is set in the <filename>meta/conf/bitbake.conf</filename> file. | 735 | This variable is set in the <filename>meta/conf/bitbake.conf</filename> file. |
| 736 | It is not intended to be user-configurable. | 736 | It is not intended to be user-configurable. |
| 737 | It is best to just reference the variable to see which distro features are | 737 | It is best to just reference the variable to see which distro features are |
| 738 | being backfilled for all distro configurations. | 738 | being backfilled for all distro configurations. |
| 739 | See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for | 739 | See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for |
| 740 | more information. | 740 | more information. |
| 741 | </para> | 741 | </para> |
| 742 | </glossdef> | 742 | </glossdef> |
| @@ -749,7 +749,7 @@ Core layer for images cannot be removed | |||
| 749 | that should not backfilled (i.e. added to | 749 | that should not backfilled (i.e. added to |
| 750 | <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>) | 750 | <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>) |
| 751 | during the build. | 751 | during the build. |
| 752 | See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for | 752 | See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for |
| 753 | more information. | 753 | more information. |
| 754 | </para> | 754 | </para> |
| 755 | </glossdef> | 755 | </glossdef> |
| @@ -764,9 +764,9 @@ Core layer for images cannot be removed | |||
| 764 | <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm> | 764 | <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm> |
| 765 | <glossdef> | 765 | <glossdef> |
| 766 | <para>Alias names used for the recipe in various Linux distributions.</para> | 766 | <para>Alias names used for the recipe in various Linux distributions.</para> |
| 767 | <para>See the | 767 | <para>See the |
| 768 | "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling | 768 | "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling |
| 769 | a Package Name Alias</ulink>" section in the Yocto Project Development | 769 | a Package Name Alias</ulink>" section in the Yocto Project Development |
| 770 | Manual for more information.</para> | 770 | Manual for more information.</para> |
| 771 | </glossdef> | 771 | </glossdef> |
| 772 | </glossentry> | 772 | </glossentry> |
| @@ -784,8 +784,8 @@ Core layer for images cannot be removed | |||
| 784 | You can set this directory by defining the <filename>DL_DIR</filename> | 784 | You can set this directory by defining the <filename>DL_DIR</filename> |
| 785 | variable in the <filename>/conf/local.conf</filename> file. | 785 | variable in the <filename>/conf/local.conf</filename> file. |
| 786 | This directory is self-maintaining and you should not have | 786 | This directory is self-maintaining and you should not have |
| 787 | to touch it. | 787 | to touch it. |
| 788 | By default, the directory is <filename>downloads</filename> in the | 788 | By default, the directory is <filename>downloads</filename> in the |
| 789 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | 789 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
| 790 | <literallayout class='monospaced'> | 790 | <literallayout class='monospaced'> |
| 791 | #DL_DIR ?= "${TOPDIR}/downloads" | 791 | #DL_DIR ?= "${TOPDIR}/downloads" |
| @@ -795,22 +795,22 @@ Core layer for images cannot be removed | |||
| 795 | </para> | 795 | </para> |
| 796 | 796 | ||
| 797 | <para> | 797 | <para> |
| 798 | During a first build, the system downloads many different source code | 798 | During a first build, the system downloads many different source code |
| 799 | tarballs from various upstream projects. | 799 | tarballs from various upstream projects. |
| 800 | Downloading can take a while, particularly if your network | 800 | Downloading can take a while, particularly if your network |
| 801 | connection is slow. | 801 | connection is slow. |
| 802 | Tarballs are all stored in the directory defined by | 802 | Tarballs are all stored in the directory defined by |
| 803 | <filename>DL_DIR</filename> and the build system looks there first | 803 | <filename>DL_DIR</filename> and the build system looks there first |
| 804 | to find source tarballs. | 804 | to find source tarballs. |
| 805 | <note> | 805 | <note> |
| 806 | When wiping and rebuilding, you can preserve this directory to speed | 806 | When wiping and rebuilding, you can preserve this directory to speed |
| 807 | up this part of subsequent builds. | 807 | up this part of subsequent builds. |
| 808 | </note> | 808 | </note> |
| 809 | </para> | 809 | </para> |
| 810 | 810 | ||
| 811 | <para> | 811 | <para> |
| 812 | You can safely share this directory between multiple builds on the | 812 | You can safely share this directory between multiple builds on the |
| 813 | same development machine. | 813 | same development machine. |
| 814 | For additional information on how the build process gets source files | 814 | For additional information on how the build process gets source files |
| 815 | when working behind a firewall or proxy server, see the | 815 | when working behind a firewall or proxy server, see the |
| 816 | "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>" | 816 | "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>" |
| @@ -836,15 +836,15 @@ Core layer for images cannot be removed | |||
| 836 | <glossdef> | 836 | <glossdef> |
| 837 | <para> | 837 | <para> |
| 838 | Used with file and pathnames to create a prefix for a recipe's | 838 | Used with file and pathnames to create a prefix for a recipe's |
| 839 | version based on the recipe's | 839 | version based on the recipe's |
| 840 | <link linkend='var-PE'><filename>PE</filename></link> value. | 840 | <link linkend='var-PE'><filename>PE</filename></link> value. |
| 841 | If <filename>PE</filename> is set and greater than zero for a recipe, | 841 | If <filename>PE</filename> is set and greater than zero for a recipe, |
| 842 | <filename>EXTENDPE</filename> becomes that value (e.g if | 842 | <filename>EXTENDPE</filename> becomes that value (e.g if |
| 843 | <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename> | 843 | <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename> |
| 844 | becomes "1_"). | 844 | becomes "1_"). |
| 845 | If a recipe's <filename>PE</filename> is not set (the default) or is equal to | 845 | If a recipe's <filename>PE</filename> is not set (the default) or is equal to |
| 846 | zero, <filename>EXTENDPE</filename> becomes "".</para> | 846 | zero, <filename>EXTENDPE</filename> becomes "".</para> |
| 847 | <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link> | 847 | <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link> |
| 848 | variable for an example. | 848 | variable for an example. |
| 849 | </para> | 849 | </para> |
| 850 | </glossdef> | 850 | </glossdef> |
| @@ -855,38 +855,38 @@ Core layer for images cannot be removed | |||
| 855 | <para>Allows extra packages to be added to the generated images. | 855 | <para>Allows extra packages to be added to the generated images. |
| 856 | You set this variable in the <filename>local.conf</filename> | 856 | You set this variable in the <filename>local.conf</filename> |
| 857 | configuration file. | 857 | configuration file. |
| 858 | Note that some image features are also added using the | 858 | Note that some image features are also added using the |
| 859 | <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> | 859 | <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> |
| 860 | variable generally configured in image recipes. | 860 | variable generally configured in image recipes. |
| 861 | You can use this variable to add more features in addition to those. | 861 | You can use this variable to add more features in addition to those. |
| 862 | Here are some examples of features you can add:</para> | 862 | Here are some examples of features you can add:</para> |
| 863 | <literallayout class='monospaced'> | 863 | <literallayout class='monospaced'> |
| 864 | "dbg-pkgs" - Adds -dbg packages for all installed packages | 864 | "dbg-pkgs" - Adds -dbg packages for all installed packages |
| 865 | including symbol information for debugging and | 865 | including symbol information for debugging and |
| 866 | profiling. | 866 | profiling. |
| 867 | 867 | ||
| 868 | "dev-pkgs" - Adds -dev packages for all installed packages. | 868 | "dev-pkgs" - Adds -dev packages for all installed packages. |
| 869 | This is useful if you want to develop against | 869 | This is useful if you want to develop against |
| 870 | the libraries in the image. | 870 | the libraries in the image. |
| 871 | 871 | ||
| 872 | "tools-sdk" - Adds development tools such as gcc, make, | 872 | "tools-sdk" - Adds development tools such as gcc, make, |
| 873 | pkgconfig and so forth. | 873 | pkgconfig and so forth. |
| 874 | 874 | ||
| 875 | "tools-debug" - Adds debugging tools such as gdb and | 875 | "tools-debug" - Adds debugging tools such as gdb and |
| 876 | strace. | 876 | strace. |
| 877 | 877 | ||
| 878 | "tools-profile" - Adds profiling tools such as oprofile, | 878 | "tools-profile" - Adds profiling tools such as oprofile, |
| 879 | exmap, lttng and valgrind (x86 only). | 879 | exmap, lttng and valgrind (x86 only). |
| 880 | 880 | ||
| 881 | "tools-testapps" - Adds useful testing tools such as | 881 | "tools-testapps" - Adds useful testing tools such as |
| 882 | ts_print, aplay, arecord and so | 882 | ts_print, aplay, arecord and so |
| 883 | forth. | 883 | forth. |
| 884 | 884 | ||
| 885 | "debug-tweaks" - Makes an image suitable for development. | 885 | "debug-tweaks" - Makes an image suitable for development. |
| 886 | For example, ssh root access has a blank | 886 | For example, ssh root access has a blank |
| 887 | password. You should remove this feature | 887 | password. You should remove this feature |
| 888 | before you produce a production image. | 888 | before you produce a production image. |
| 889 | </literallayout> | 889 | </literallayout> |
| 890 | 890 | ||
| 891 | <para>There are other valid features too, see the | 891 | <para>There are other valid features too, see the |
| 892 | <link linkend='ref-features-image'>Images</link> | 892 | <link linkend='ref-features-image'>Images</link> |
| @@ -901,12 +901,12 @@ Core layer for images cannot be removed | |||
| 901 | </para> | 901 | </para> |
| 902 | <para>Sometimes a recipe is required to build the final image but is not | 902 | <para>Sometimes a recipe is required to build the final image but is not |
| 903 | needed in the root filesystem. | 903 | needed in the root filesystem. |
| 904 | You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to | 904 | You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to |
| 905 | list these recipes and thus, specify the dependencies. | 905 | list these recipes and thus, specify the dependencies. |
| 906 | A typical example is a required bootloader in a machine configuration. | 906 | A typical example is a required bootloader in a machine configuration. |
| 907 | </para> | 907 | </para> |
| 908 | <note> | 908 | <note> |
| 909 | To add packages to the root filesystem, see the various | 909 | To add packages to the root filesystem, see the various |
| 910 | <filename>*DEPENDS</filename> and <filename>*RECOMMENDS</filename> | 910 | <filename>*DEPENDS</filename> and <filename>*RECOMMENDS</filename> |
| 911 | variables. | 911 | variables. |
| 912 | </note> | 912 | </note> |
| @@ -944,32 +944,32 @@ Core layer for images cannot be removed | |||
| 944 | <para> | 944 | <para> |
| 945 | To use the <filename>FILES</filename> variable, provide a package name | 945 | To use the <filename>FILES</filename> variable, provide a package name |
| 946 | override that identifies the resulting package. | 946 | override that identifies the resulting package. |
| 947 | Then, provide a space-separated list of files or paths that identifies the | 947 | Then, provide a space-separated list of files or paths that identifies the |
| 948 | files you want included as part of the resulting package. | 948 | files you want included as part of the resulting package. |
| 949 | Here is an example: | 949 | Here is an example: |
| 950 | <literallayout class='monospaced'> | 950 | <literallayout class='monospaced'> |
| 951 | FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" | 951 | FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" |
| 952 | </literallayout> | 952 | </literallayout> |
| 953 | </para> | 953 | </para> |
| 954 | 954 | ||
| 955 | <note> | 955 | <note> |
| 956 | When specifying paths as part of the <filename>FILES</filename> variable, | 956 | When specifying paths as part of the <filename>FILES</filename> variable, |
| 957 | it is good practice to use appropriate path variables. | 957 | it is good practice to use appropriate path variables. |
| 958 | For example, <filename>${sysconfdir}</filename> rather than | 958 | For example, <filename>${sysconfdir}</filename> rather than |
| 959 | <filename>/etc</filename> or <filename>${bindir}</filename> rather | 959 | <filename>/etc</filename> or <filename>${bindir}</filename> rather |
| 960 | than <filename>/usr/bin</filename>. | 960 | than <filename>/usr/bin</filename>. |
| 961 | You can find a list of these variables at the top of the | 961 | You can find a list of these variables at the top of the |
| 962 | <filename>/meta/conf/bitbake.conf</filename> file in the | 962 | <filename>/meta/conf/bitbake.conf</filename> file in the |
| 963 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 963 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 964 | </note> | 964 | </note> |
| 965 | 965 | ||
| 966 | <para> | 966 | <para> |
| 967 | If some of the files you provide with the <filename>FILES</filename> variable | 967 | If some of the files you provide with the <filename>FILES</filename> variable |
| 968 | are editable and you know they should not be | 968 | are editable and you know they should not be |
| 969 | overwritten during the package update process by the Package Management | 969 | overwritten during the package update process by the Package Management |
| 970 | System (PMS), you can identify these files so that the PMS will not | 970 | System (PMS), you can identify these files so that the PMS will not |
| 971 | overwrite them. | 971 | overwrite them. |
| 972 | See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename> | 972 | See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename> |
| 973 | variable for information on how to identify these files to the PMS. | 973 | variable for information on how to identify these files to the PMS. |
| 974 | </para> | 974 | </para> |
| 975 | 975 | ||
| @@ -979,11 +979,11 @@ Core layer for images cannot be removed | |||
| 979 | <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm> | 979 | <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm> |
| 980 | <glossdef> | 980 | <glossdef> |
| 981 | <para> | 981 | <para> |
| 982 | Extends the search path the OpenEmbedded build system uses when | 982 | Extends the search path the OpenEmbedded build system uses when |
| 983 | looking for files and patches as it processes recipes. | 983 | looking for files and patches as it processes recipes. |
| 984 | The directories BitBake uses when it processes recipes is defined by the | 984 | The directories BitBake uses when it processes recipes is defined by the |
| 985 | <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> variable. | 985 | <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> variable. |
| 986 | You can add directories to the search path by defining the | 986 | You can add directories to the search path by defining the |
| 987 | <filename>FILESEXTRAPATHS</filename> variable. | 987 | <filename>FILESEXTRAPATHS</filename> variable. |
| 988 | </para> | 988 | </para> |
| 989 | 989 | ||
| @@ -993,17 +993,17 @@ Core layer for images cannot be removed | |||
| 993 | <literallayout class='monospaced'> | 993 | <literallayout class='monospaced'> |
| 994 | FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" | 994 | FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" |
| 995 | </literallayout> | 995 | </literallayout> |
| 996 | Typically, you want your directories searched first. | 996 | Typically, you want your directories searched first. |
| 997 | To make sure that happens, use <filename>_prepend</filename> and | 997 | To make sure that happens, use <filename>_prepend</filename> and |
| 998 | the immediate expansion (<filename>:=</filename>) operator as shown in the | 998 | the immediate expansion (<filename>:=</filename>) operator as shown in the |
| 999 | previous example. | 999 | previous example. |
| 1000 | Finally, to maintain the integrity of the <filename>FILESPATH</filename> variable, | 1000 | Finally, to maintain the integrity of the <filename>FILESPATH</filename> variable, |
| 1001 | you must include the appropriate beginning or ending (as needed) colon character. | 1001 | you must include the appropriate beginning or ending (as needed) colon character. |
| 1002 | </para> | 1002 | </para> |
| 1003 | 1003 | ||
| 1004 | <para> | 1004 | <para> |
| 1005 | The <filename>FILESEXTRAPATHS</filename> variable is intended for use in | 1005 | The <filename>FILESEXTRAPATHS</filename> variable is intended for use in |
| 1006 | <filename>.bbappend</filename> files to include any additional files provided in that layer. | 1006 | <filename>.bbappend</filename> files to include any additional files provided in that layer. |
| 1007 | You typically accomplish this with the following: | 1007 | You typically accomplish this with the following: |
| 1008 | <literallayout class='monospaced'> | 1008 | <literallayout class='monospaced'> |
| 1009 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 1009 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" |
| @@ -1017,15 +1017,15 @@ Core layer for images cannot be removed | |||
| 1017 | <para> | 1017 | <para> |
| 1018 | The default set of directories the OpenEmbedded build system uses | 1018 | The default set of directories the OpenEmbedded build system uses |
| 1019 | when searching for patches and files. | 1019 | when searching for patches and files. |
| 1020 | During the build process, BitBake searches each directory in | 1020 | During the build process, BitBake searches each directory in |
| 1021 | <filename>FILESPATH</filename> in the specified order when looking for | 1021 | <filename>FILESPATH</filename> in the specified order when looking for |
| 1022 | files and patches specified by each <filename>file://</filename> URI in a recipe. | 1022 | files and patches specified by each <filename>file://</filename> URI in a recipe. |
| 1023 | </para> | 1023 | </para> |
| 1024 | 1024 | ||
| 1025 | <para> | 1025 | <para> |
| 1026 | The default value for the <filename>FILESPATH</filename> variable is defined | 1026 | The default value for the <filename>FILESPATH</filename> variable is defined |
| 1027 | in the <filename>base.bbclass</filename> class found in | 1027 | in the <filename>base.bbclass</filename> class found in |
| 1028 | <filename>meta/classes</filename> in the | 1028 | <filename>meta/classes</filename> in the |
| 1029 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: | 1029 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: |
| 1030 | <literallayout class='monospaced'> | 1030 | <literallayout class='monospaced'> |
| 1031 | FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | 1031 | FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ |
| @@ -1033,9 +1033,9 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | |||
| 1033 | "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \ | 1033 | "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \ |
| 1034 | "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}" | 1034 | "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}" |
| 1035 | </literallayout> | 1035 | </literallayout> |
| 1036 | Do not hand-edit the <filename>FILESPATH</filename> variable. | 1036 | Do not hand-edit the <filename>FILESPATH</filename> variable. |
| 1037 | If you want to extend the set of pathnames that BitBake uses when searching for | 1037 | If you want to extend the set of pathnames that BitBake uses when searching for |
| 1038 | files and patches, use the | 1038 | files and patches, use the |
| 1039 | <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> variable. | 1039 | <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> variable. |
| 1040 | </para> | 1040 | </para> |
| 1041 | </glossdef> | 1041 | </glossdef> |
| @@ -1045,29 +1045,29 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | |||
| 1045 | <glossdef> | 1045 | <glossdef> |
| 1046 | <para>Allows you to define your own file permissions settings table as part of | 1046 | <para>Allows you to define your own file permissions settings table as part of |
| 1047 | your configuration for the packaging process. | 1047 | your configuration for the packaging process. |
| 1048 | For example, suppose you need a consistent set of custom permissions for | 1048 | For example, suppose you need a consistent set of custom permissions for |
| 1049 | a set of groups and users across an entire work project. | 1049 | a set of groups and users across an entire work project. |
| 1050 | It is best to do this in the packages themselves but this is not always | 1050 | It is best to do this in the packages themselves but this is not always |
| 1051 | possible. | 1051 | possible. |
| 1052 | </para> | 1052 | </para> |
| 1053 | <para> | 1053 | <para> |
| 1054 | By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which | 1054 | By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which |
| 1055 | is located in the <filename>meta/files</filename> folder in the | 1055 | is located in the <filename>meta/files</filename> folder in the |
| 1056 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 1056 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 1057 | If you create your own file permissions setting table, you should place it in your | 1057 | If you create your own file permissions setting table, you should place it in your |
| 1058 | layer or the distros layer. | 1058 | layer or the distros layer. |
| 1059 | </para> | 1059 | </para> |
| 1060 | <para> | 1060 | <para> |
| 1061 | You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the | 1061 | You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the |
| 1062 | <filename>conf/local.conf</filename> file, which is found in the | 1062 | <filename>conf/local.conf</filename> file, which is found in the |
| 1063 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to | 1063 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to |
| 1064 | point to your custom <filename>fs-perms.txt</filename>. | 1064 | point to your custom <filename>fs-perms.txt</filename>. |
| 1065 | You can specify more than a single file permissions setting table. | 1065 | You can specify more than a single file permissions setting table. |
| 1066 | The paths you specify to these files must be defined within the | 1066 | The paths you specify to these files must be defined within the |
| 1067 | <filename>BBPATH</filename> variable. | 1067 | <filename>BBPATH</filename> variable. |
| 1068 | </para> | 1068 | </para> |
| 1069 | <para> | 1069 | <para> |
| 1070 | For guidance on how to create your own file permissions settings table file, | 1070 | For guidance on how to create your own file permissions settings table file, |
| 1071 | examine the existing <filename>fs-perms.txt</filename>. | 1071 | examine the existing <filename>fs-perms.txt</filename>. |
| 1072 | </para> | 1072 | </para> |
| 1073 | </glossdef> | 1073 | </glossdef> |
| @@ -1076,11 +1076,11 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | |||
| 1076 | <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm> | 1076 | <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm> |
| 1077 | <glossdef> | 1077 | <glossdef> |
| 1078 | <para> | 1078 | <para> |
| 1079 | The options to pass in | 1079 | The options to pass in |
| 1080 | <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> | 1080 | <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> |
| 1081 | and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> | 1081 | and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> |
| 1082 | when compiling an optimized system. | 1082 | when compiling an optimized system. |
| 1083 | This variable defaults to | 1083 | This variable defaults to |
| 1084 | "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2". | 1084 | "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2". |
| 1085 | </para> | 1085 | </para> |
| 1086 | </glossdef> | 1086 | </glossdef> |
| @@ -1110,7 +1110,7 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | |||
| 1110 | Typically, you configure this variable in an image recipe. | 1110 | Typically, you configure this variable in an image recipe. |
| 1111 | Note that you can also add extra features to the image by using the | 1111 | Note that you can also add extra features to the image by using the |
| 1112 | <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable. | 1112 | <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable. |
| 1113 | See the "<link linkend="ref-features-image">Images</link>" section for the | 1113 | See the "<link linkend="ref-features-image">Images</link>" section for the |
| 1114 | full list of features that can be included in images built by the | 1114 | full list of features that can be included in images built by the |
| 1115 | OpenEmbedded build system.</para> | 1115 | OpenEmbedded build system.</para> |
| 1116 | </glossdef> | 1116 | </glossdef> |
| @@ -1131,28 +1131,28 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | |||
| 1131 | </para> | 1131 | </para> |
| 1132 | 1132 | ||
| 1133 | <para> | 1133 | <para> |
| 1134 | Image recipes set <filename>IMAGE_INSTALL</filename> to specify the | 1134 | Image recipes set <filename>IMAGE_INSTALL</filename> to specify the |
| 1135 | packages to install into an image through <filename>image.bbclass</filename>. | 1135 | packages to install into an image through <filename>image.bbclass</filename>. |
| 1136 | Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>, | 1136 | Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>, |
| 1137 | that can take | 1137 | that can take |
| 1138 | <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists | 1138 | <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists |
| 1139 | and turn these into auto-generated entries in | 1139 | and turn these into auto-generated entries in |
| 1140 | <filename>IMAGE_INSTALL</filename> in addition to its default contents. | 1140 | <filename>IMAGE_INSTALL</filename> in addition to its default contents. |
| 1141 | </para> | 1141 | </para> |
| 1142 | 1142 | ||
| 1143 | <para> | 1143 | <para> |
| 1144 | Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename> | 1144 | Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename> |
| 1145 | operator from the <filename>/conf/local.conf</filename> file or from within | 1145 | operator from the <filename>/conf/local.conf</filename> file or from within |
| 1146 | an image recipe is not recommended as it can cause ordering issues. | 1146 | an image recipe is not recommended as it can cause ordering issues. |
| 1147 | Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename> | 1147 | Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename> |
| 1148 | to a default value using the <filename>?=</filename> operator, using a | 1148 | to a default value using the <filename>?=</filename> operator, using a |
| 1149 | <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename> | 1149 | <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename> |
| 1150 | will result in unexpected behavior when used in | 1150 | will result in unexpected behavior when used in |
| 1151 | <filename>/conf/local.conf</filename>. | 1151 | <filename>/conf/local.conf</filename>. |
| 1152 | Furthermore, the same operation from with an image recipe may or may not | 1152 | Furthermore, the same operation from with an image recipe may or may not |
| 1153 | succeed depending on the specific situation. | 1153 | succeed depending on the specific situation. |
| 1154 | In both these cases, the behavior is contrary to how most users expect | 1154 | In both these cases, the behavior is contrary to how most users expect |
| 1155 | the <filename>+=</filename> operator to work. | 1155 | the <filename>+=</filename> operator to work. |
| 1156 | </para> | 1156 | </para> |
| 1157 | 1157 | ||
| 1158 | <para> | 1158 | <para> |
| @@ -1171,27 +1171,27 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | |||
| 1171 | <para> | 1171 | <para> |
| 1172 | Defines a multiplier that the build system applies to the initial image | 1172 | Defines a multiplier that the build system applies to the initial image |
| 1173 | size for cases when the multiplier times the returned disk usage value | 1173 | size for cases when the multiplier times the returned disk usage value |
| 1174 | for the image is greater than the sum of | 1174 | for the image is greater than the sum of |
| 1175 | <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename> | 1175 | <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename> |
| 1176 | and | 1176 | and |
| 1177 | <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>. | 1177 | <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>. |
| 1178 | The result of the multiplier applied to the initial image size creates | 1178 | The result of the multiplier applied to the initial image size creates |
| 1179 | free disk space in the image as overhead. | 1179 | free disk space in the image as overhead. |
| 1180 | By default, the build process uses a multiplier of 1.3 for this variable. | 1180 | By default, the build process uses a multiplier of 1.3 for this variable. |
| 1181 | This default value results in 30% free disk space added to the image when this | 1181 | This default value results in 30% free disk space added to the image when this |
| 1182 | method is used to determine the final generated image size. | 1182 | method is used to determine the final generated image size. |
| 1183 | You should be aware that post install scripts and the package management | 1183 | You should be aware that post install scripts and the package management |
| 1184 | system uses disk space inside this overhead area. | 1184 | system uses disk space inside this overhead area. |
| 1185 | Consequently, the multiplier does not produce an image with | 1185 | Consequently, the multiplier does not produce an image with |
| 1186 | all the theoretical free disk space. | 1186 | all the theoretical free disk space. |
| 1187 | See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename> | 1187 | See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename> |
| 1188 | for information on how the build system determines the overall image size. | 1188 | for information on how the build system determines the overall image size. |
| 1189 | </para> | 1189 | </para> |
| 1190 | 1190 | ||
| 1191 | <para> | 1191 | <para> |
| 1192 | The default 30% free disk space typically gives the image enough room to boot | 1192 | The default 30% free disk space typically gives the image enough room to boot |
| 1193 | and allows for basic post installs while still leaving a small amount of | 1193 | and allows for basic post installs while still leaving a small amount of |
| 1194 | free disk space. | 1194 | free disk space. |
| 1195 | If 30% free space is inadequate, you can increase the default value. | 1195 | If 30% free space is inadequate, you can increase the default value. |
| 1196 | For example, the following setting gives you 50% free space added to the image: | 1196 | For example, the following setting gives you 50% free space added to the image: |
| 1197 | <literallayout class='monospaced'> | 1197 | <literallayout class='monospaced'> |
| @@ -1201,12 +1201,12 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | |||
| 1201 | 1201 | ||
| 1202 | <para> | 1202 | <para> |
| 1203 | Alternatively, you can ensure a specific amount of free disk space is added | 1203 | Alternatively, you can ensure a specific amount of free disk space is added |
| 1204 | to the image by using | 1204 | to the image by using |
| 1205 | <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename> | 1205 | <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename> |
| 1206 | the variable. | 1206 | the variable. |
| 1207 | </para> | 1207 | </para> |
| 1208 | </glossdef> | 1208 | </glossdef> |
| 1209 | </glossentry> | 1209 | </glossentry> |
| 1210 | 1210 | ||
| 1211 | <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm> | 1211 | <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm> |
| 1212 | <glossdef> | 1212 | <glossdef> |
| @@ -1214,32 +1214,32 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | |||
| 1214 | Defines additional free disk space created in the image in Kbytes. | 1214 | Defines additional free disk space created in the image in Kbytes. |
| 1215 | By default, this variable is set to "0". | 1215 | By default, this variable is set to "0". |
| 1216 | This free disk space is added to the image after the build system determines | 1216 | This free disk space is added to the image after the build system determines |
| 1217 | the image size as described in | 1217 | the image size as described in |
| 1218 | <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>. | 1218 | <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>. |
| 1219 | </para> | 1219 | </para> |
| 1220 | 1220 | ||
| 1221 | <para> | 1221 | <para> |
| 1222 | This variable is particularly useful when you want to ensure that a | 1222 | This variable is particularly useful when you want to ensure that a |
| 1223 | specific amount of free disk space is available on a device after an image | 1223 | specific amount of free disk space is available on a device after an image |
| 1224 | is installed and running. | 1224 | is installed and running. |
| 1225 | For example, to be sure 5 Gbytes of free disk space is available, set the | 1225 | For example, to be sure 5 Gbytes of free disk space is available, set the |
| 1226 | variable as follows: | 1226 | variable as follows: |
| 1227 | <literallayout class='monospaced'> | 1227 | <literallayout class='monospaced'> |
| 1228 | IMAGE_ROOTFS_EXTRA_SPACE = "5242880" | 1228 | IMAGE_ROOTFS_EXTRA_SPACE = "5242880" |
| 1229 | </literallayout> | 1229 | </literallayout> |
| 1230 | </para> | 1230 | </para> |
| 1231 | </glossdef> | 1231 | </glossdef> |
| 1232 | </glossentry> | 1232 | </glossentry> |
| 1233 | 1233 | ||
| 1234 | <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm> | 1234 | <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm> |
| 1235 | <glossdef> | 1235 | <glossdef> |
| 1236 | <para> | 1236 | <para> |
| 1237 | Defines the size in Kbytes for the generated image. | 1237 | Defines the size in Kbytes for the generated image. |
| 1238 | The OpenEmbedded build system determines the final size for the generated | 1238 | The OpenEmbedded build system determines the final size for the generated |
| 1239 | image using an algorithm that takes into account the initial disk space used | 1239 | image using an algorithm that takes into account the initial disk space used |
| 1240 | for the generated image, a requested size for the image, and requested | 1240 | for the generated image, a requested size for the image, and requested |
| 1241 | additional free disk space to be added to the image. | 1241 | additional free disk space to be added to the image. |
| 1242 | Programatically, the build system determines the final size of the | 1242 | Programatically, the build system determines the final size of the |
| 1243 | generated image as follows: | 1243 | generated image as follows: |
| 1244 | <literallayout class='monospaced'> | 1244 | <literallayout class='monospaced'> |
| 1245 | if (image-du * overhead) < rootfs-size: | 1245 | if (image-du * overhead) < rootfs-size: |
| @@ -1251,7 +1251,7 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | |||
| 1251 | 1251 | ||
| 1252 | image-du = Returned value of the du command on | 1252 | image-du = Returned value of the du command on |
| 1253 | the image. | 1253 | the image. |
| 1254 | 1254 | ||
| 1255 | overhead = IMAGE_OVERHEAD_FACTOR | 1255 | overhead = IMAGE_OVERHEAD_FACTOR |
| 1256 | 1256 | ||
| 1257 | rootfs-size = IMAGE_ROOTFS_SIZE | 1257 | rootfs-size = IMAGE_ROOTFS_SIZE |
| @@ -1261,12 +1261,12 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | |||
| 1261 | 1261 | ||
| 1262 | xspace = IMAGE_ROOTFS_EXTRA_SPACE | 1262 | xspace = IMAGE_ROOTFS_EXTRA_SPACE |
| 1263 | </literallayout> | 1263 | </literallayout> |
| 1264 | <!-- In the above example, <filename>overhead</filename> is defined by the | 1264 | <!-- In the above example, <filename>overhead</filename> is defined by the |
| 1265 | <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename> | 1265 | <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename> |
| 1266 | variable, <filename>xspace</filename> is defined by the | 1266 | variable, <filename>xspace</filename> is defined by the |
| 1267 | <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename> | 1267 | <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename> |
| 1268 | variable, and <filename>du</filename> is the results of the disk usage command | 1268 | variable, and <filename>du</filename> is the results of the disk usage command |
| 1269 | on the initially generated image. --> | 1269 | on the initially generated image. --> |
| 1270 | </para> | 1270 | </para> |
| 1271 | </glossdef> | 1271 | </glossdef> |
| 1272 | </glossentry> | 1272 | </glossentry> |
| @@ -1275,38 +1275,38 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | |||
| 1275 | <glossdef> | 1275 | <glossdef> |
| 1276 | <para>Helps define the recipe revision for recipes that share | 1276 | <para>Helps define the recipe revision for recipes that share |
| 1277 | a common <filename>include</filename> file. | 1277 | a common <filename>include</filename> file. |
| 1278 | You can think of this variable as part of the recipe revision | 1278 | You can think of this variable as part of the recipe revision |
| 1279 | as set from within an include file.</para> | 1279 | as set from within an include file.</para> |
| 1280 | <para>Suppose, for example, you have a set of recipes that | 1280 | <para>Suppose, for example, you have a set of recipes that |
| 1281 | are used across several projects. | 1281 | are used across several projects. |
| 1282 | And, within each of those recipes the revision | 1282 | And, within each of those recipes the revision |
| 1283 | (its <filename>PR</filename> value) is set accordingly. | 1283 | (its <filename>PR</filename> value) is set accordingly. |
| 1284 | In this case, when the revision of those recipes changes | 1284 | In this case, when the revision of those recipes changes |
| 1285 | the burden is on you to find all those recipes and | 1285 | the burden is on you to find all those recipes and |
| 1286 | be sure that they get changed to reflect the updated | 1286 | be sure that they get changed to reflect the updated |
| 1287 | version of the recipe. | 1287 | version of the recipe. |
| 1288 | In this scenario, it can get complicated when recipes | 1288 | In this scenario, it can get complicated when recipes |
| 1289 | used in many places and that provide common functionality | 1289 | used in many places and that provide common functionality |
| 1290 | are upgraded to a new revision.</para> | 1290 | are upgraded to a new revision.</para> |
| 1291 | <para>A more efficient way of dealing with this situation is | 1291 | <para>A more efficient way of dealing with this situation is |
| 1292 | to set the <filename>INC_PR</filename> variable inside | 1292 | to set the <filename>INC_PR</filename> variable inside |
| 1293 | the <filename>include</filename> files that the recipes | 1293 | the <filename>include</filename> files that the recipes |
| 1294 | share and then expand the <filename>INC_PR</filename> | 1294 | share and then expand the <filename>INC_PR</filename> |
| 1295 | variable within the recipes to help | 1295 | variable within the recipes to help |
| 1296 | define the recipe revision. | 1296 | define the recipe revision. |
| 1297 | </para> | 1297 | </para> |
| 1298 | <para> | 1298 | <para> |
| 1299 | The following provides an example that shows how to use | 1299 | The following provides an example that shows how to use |
| 1300 | the <filename>INC_PR</filename> variable | 1300 | the <filename>INC_PR</filename> variable |
| 1301 | given a common <filename>include</filename> file that | 1301 | given a common <filename>include</filename> file that |
| 1302 | defines the variable. | 1302 | defines the variable. |
| 1303 | Once the variable is defined in the | 1303 | Once the variable is defined in the |
| 1304 | <filename>include</filename> file, you can use the | 1304 | <filename>include</filename> file, you can use the |
| 1305 | variable to set the <filename>PR</filename> values in | 1305 | variable to set the <filename>PR</filename> values in |
| 1306 | each recipe. | 1306 | each recipe. |
| 1307 | You will notice that when you set a recipe's | 1307 | You will notice that when you set a recipe's |
| 1308 | <filename>PR</filename> you can provide more granular | 1308 | <filename>PR</filename> you can provide more granular |
| 1309 | revisioning by appending values to the | 1309 | revisioning by appending values to the |
| 1310 | <filename>INC_PR</filename> variable: | 1310 | <filename>INC_PR</filename> variable: |
| 1311 | <literallayout class='monospaced'> | 1311 | <literallayout class='monospaced'> |
| 1312 | recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" | 1312 | recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" |
| @@ -1314,8 +1314,8 @@ recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" | |||
| 1314 | recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" | 1314 | recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" |
| 1315 | recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | 1315 | recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" |
| 1316 | </literallayout> | 1316 | </literallayout> |
| 1317 | The first line of the example establishes the baseline | 1317 | The first line of the example establishes the baseline |
| 1318 | revision to be used for all recipes that use the | 1318 | revision to be used for all recipes that use the |
| 1319 | <filename>include</filename> file. | 1319 | <filename>include</filename> file. |
| 1320 | The remaining lines in the example are from individual | 1320 | The remaining lines in the example are from individual |
| 1321 | recipes and show how the <filename>PR</filename> value | 1321 | recipes and show how the <filename>PR</filename> value |
| @@ -1335,8 +1335,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1335 | <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> | 1335 | <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> |
| 1336 | <glossdef> | 1336 | <glossdef> |
| 1337 | <para> | 1337 | <para> |
| 1338 | Causes the named class to be inherited at | 1338 | Causes the named class to be inherited at |
| 1339 | this point during parsing. | 1339 | this point during parsing. |
| 1340 | The variable is only valid in configuration files. | 1340 | The variable is only valid in configuration files. |
| 1341 | </para> | 1341 | </para> |
| 1342 | </glossdef> | 1342 | </glossdef> |
| @@ -1346,8 +1346,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1346 | <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm> | 1346 | <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm> |
| 1347 | <glossdef> | 1347 | <glossdef> |
| 1348 | <para> | 1348 | <para> |
| 1349 | A list of the packages that contain initscripts. | 1349 | A list of the packages that contain initscripts. |
| 1350 | If multiple packages are specified, you need to append the package name | 1350 | If multiple packages are specified, you need to append the package name |
| 1351 | to the other <filename>INITSCRIPT_*</filename> as an override.</para> | 1351 | to the other <filename>INITSCRIPT_*</filename> as an override.</para> |
| 1352 | <para> | 1352 | <para> |
| 1353 | This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>. | 1353 | This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>. |
| @@ -1372,12 +1372,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1372 | <glossdef> | 1372 | <glossdef> |
| 1373 | <para> | 1373 | <para> |
| 1374 | Specifies the options to pass to <filename>update-rc.d</filename>. | 1374 | Specifies the options to pass to <filename>update-rc.d</filename>. |
| 1375 | An example is <filename>start 99 5 2 . stop 20 0 1 6 .</filename>, which gives the script a | 1375 | An example is <filename>start 99 5 2 . stop 20 0 1 6 .</filename>, which gives the script a |
| 1376 | runlevel of 99, starts the script in initlevels 2 and 5, and | 1376 | runlevel of 99, starts the script in initlevels 2 and 5, and |
| 1377 | stops the script in levels 0, 1 and 6. | 1377 | stops the script in levels 0, 1 and 6. |
| 1378 | </para> | 1378 | </para> |
| 1379 | <para> | 1379 | <para> |
| 1380 | The variable is mandatory and is used in recipes when using | 1380 | The variable is mandatory and is used in recipes when using |
| 1381 | <filename>update-rc.d.bbclass</filename>. | 1381 | <filename>update-rc.d.bbclass</filename>. |
| 1382 | </para> | 1382 | </para> |
| 1383 | </glossdef> | 1383 | </glossdef> |
| @@ -1394,36 +1394,36 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1394 | <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm> | 1394 | <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm> |
| 1395 | <glossdef> | 1395 | <glossdef> |
| 1396 | <para> | 1396 | <para> |
| 1397 | A regular expression used by the build process to explicitly identify the kernel | 1397 | A regular expression used by the build process to explicitly identify the kernel |
| 1398 | branch that is validated, patched and configured during a build. | 1398 | branch that is validated, patched and configured during a build. |
| 1399 | The <filename>KBRANCH</filename> variable is optional. | 1399 | The <filename>KBRANCH</filename> variable is optional. |
| 1400 | You can use it to trigger checks to ensure the exact kernel branch you want is | 1400 | You can use it to trigger checks to ensure the exact kernel branch you want is |
| 1401 | being used by the build process. | 1401 | being used by the build process. |
| 1402 | </para> | 1402 | </para> |
| 1403 | 1403 | ||
| 1404 | <para> | 1404 | <para> |
| 1405 | Values for this variable are set in the kernel's recipe file and the kernel's | 1405 | Values for this variable are set in the kernel's recipe file and the kernel's |
| 1406 | append file. | 1406 | append file. |
| 1407 | For example, if you are using the Yocto Project kernel that is based on the | 1407 | For example, if you are using the Yocto Project kernel that is based on the |
| 1408 | Linux 3.4 kernel, the kernel recipe file is the | 1408 | Linux 3.4 kernel, the kernel recipe file is the |
| 1409 | <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> file. | 1409 | <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> file. |
| 1410 | Following is the default value for <filename>KBRANCH</filename> and the default | 1410 | Following is the default value for <filename>KBRANCH</filename> and the default |
| 1411 | override for the architectures the Yocto Project supports: | 1411 | override for the architectures the Yocto Project supports: |
| 1412 | <literallayout class='monospaced'> | 1412 | <literallayout class='monospaced'> |
| 1413 | KBRANCH_DEFAULT = "standard/base" | 1413 | KBRANCH_DEFAULT = "standard/base" |
| 1414 | KBRANCH = "${KBRANCH_DEFAULT}" | 1414 | KBRANCH = "${KBRANCH_DEFAULT}" |
| 1415 | </literallayout> | 1415 | </literallayout> |
| 1416 | This branch exists in the <filename>linux-yocto-3.4</filename> kernel Git | 1416 | This branch exists in the <filename>linux-yocto-3.4</filename> kernel Git |
| 1417 | repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>. | 1417 | repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>. |
| 1418 | </para> | 1418 | </para> |
| 1419 | 1419 | ||
| 1420 | <para> | 1420 | <para> |
| 1421 | This variable is also used from the kernel's append file to identify the kernel | 1421 | This variable is also used from the kernel's append file to identify the kernel |
| 1422 | branch specific to a particular machine or target hardware. | 1422 | branch specific to a particular machine or target hardware. |
| 1423 | The kernel's append file is located in the BSP layer for a given machine. | 1423 | The kernel's append file is located in the BSP layer for a given machine. |
| 1424 | For example, the kernel append file for the Crown Bay BSP is in the | 1424 | For example, the kernel append file for the Crown Bay BSP is in the |
| 1425 | <filename>meta-intel</filename> Git repository and is named | 1425 | <filename>meta-intel</filename> Git repository and is named |
| 1426 | <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>. | 1426 | <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>. |
| 1427 | Here are the related statements from the append file: | 1427 | Here are the related statements from the append file: |
| 1428 | <literallayout class='monospaced'> | 1428 | <literallayout class='monospaced'> |
| 1429 | COMPATIBLE_MACHINE_crownbay = "crownbay" | 1429 | COMPATIBLE_MACHINE_crownbay = "crownbay" |
| @@ -1434,9 +1434,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1434 | KMACHINE_crownbay-noemgd = "crownbay" | 1434 | KMACHINE_crownbay-noemgd = "crownbay" |
| 1435 | KBRANCH_crownbay-noemgd = "standard/crownbay" | 1435 | KBRANCH_crownbay-noemgd = "standard/crownbay" |
| 1436 | </literallayout> | 1436 | </literallayout> |
| 1437 | The <filename>KBRANCH_*</filename> statements identify the kernel branch to | 1437 | The <filename>KBRANCH_*</filename> statements identify the kernel branch to |
| 1438 | use when building for the Crown Bay BSP. | 1438 | use when building for the Crown Bay BSP. |
| 1439 | In this case there are two identical statements: one for each type of | 1439 | In this case there are two identical statements: one for each type of |
| 1440 | Crown Bay machine. | 1440 | Crown Bay machine. |
| 1441 | </para> | 1441 | </para> |
| 1442 | </glossdef> | 1442 | </glossdef> |
| @@ -1446,18 +1446,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1446 | <glossdef> | 1446 | <glossdef> |
| 1447 | <para>Includes additional metadata from the Yocto Project kernel Git repository. | 1447 | <para>Includes additional metadata from the Yocto Project kernel Git repository. |
| 1448 | In the OpenEmbedded build system, the default Board Support Packages (BSPs) | 1448 | In the OpenEmbedded build system, the default Board Support Packages (BSPs) |
| 1449 | metadata is provided through | 1449 | metadata is provided through |
| 1450 | the <filename>KMACHINE</filename> and <filename>KBRANCH</filename> variables. | 1450 | the <filename>KMACHINE</filename> and <filename>KBRANCH</filename> variables. |
| 1451 | You can use the <filename>KERNEL_FEATURES</filename> variable to further | 1451 | You can use the <filename>KERNEL_FEATURES</filename> variable to further |
| 1452 | add metadata for all BSPs.</para> | 1452 | add metadata for all BSPs.</para> |
| 1453 | <para>The metadata you add through this variable includes config fragments and | 1453 | <para>The metadata you add through this variable includes config fragments and |
| 1454 | features descriptions, | 1454 | features descriptions, |
| 1455 | which usually includes patches as well as config fragments. | 1455 | which usually includes patches as well as config fragments. |
| 1456 | You typically override the <filename>KERNEL_FEATURES</filename> variable | 1456 | You typically override the <filename>KERNEL_FEATURES</filename> variable |
| 1457 | for a specific machine. | 1457 | for a specific machine. |
| 1458 | In this way, you can provide validated, but optional, sets of kernel | 1458 | In this way, you can provide validated, but optional, sets of kernel |
| 1459 | configurations and features.</para> | 1459 | configurations and features.</para> |
| 1460 | <para>For example, the following adds <filename>netfilter</filename> to all | 1460 | <para>For example, the following adds <filename>netfilter</filename> to all |
| 1461 | the Yocto Project kernels and adds sound support to the <filename>qemux86</filename> | 1461 | the Yocto Project kernels and adds sound support to the <filename>qemux86</filename> |
| 1462 | machine: | 1462 | machine: |
| 1463 | <literallayout class='monospaced'> | 1463 | <literallayout class='monospaced'> |
| @@ -1472,10 +1472,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1472 | 1472 | ||
| 1473 | <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm> | 1473 | <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm> |
| 1474 | <glossdef> | 1474 | <glossdef> |
| 1475 | <para>The type of kernel to build for a device, usually set by the | 1475 | <para>The type of kernel to build for a device, usually set by the |
| 1476 | machine configuration files and defaults to "zImage". | 1476 | machine configuration files and defaults to "zImage". |
| 1477 | This variable is used | 1477 | This variable is used |
| 1478 | when building the kernel and is passed to <filename>make</filename> as the target to | 1478 | when building the kernel and is passed to <filename>make</filename> as the target to |
| 1479 | build.</para> | 1479 | build.</para> |
| 1480 | </glossdef> | 1480 | </glossdef> |
| 1481 | </glossentry> | 1481 | </glossentry> |
| @@ -1486,22 +1486,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1486 | The machine as known by the kernel. | 1486 | The machine as known by the kernel. |
| 1487 | Sometimes the machine name used by the kernel does not match the machine name | 1487 | Sometimes the machine name used by the kernel does not match the machine name |
| 1488 | used by the OpenEmbedded build system. | 1488 | used by the OpenEmbedded build system. |
| 1489 | For example, the machine name that the OpenEmbedded build system understands as | 1489 | For example, the machine name that the OpenEmbedded build system understands as |
| 1490 | <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel. | 1490 | <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel. |
| 1491 | The kernel understands that machine as <filename>arm_versatile926ejs</filename>. | 1491 | The kernel understands that machine as <filename>arm_versatile926ejs</filename>. |
| 1492 | For cases like these, the <filename>KMACHINE</filename> variable maps the | 1492 | For cases like these, the <filename>KMACHINE</filename> variable maps the |
| 1493 | kernel machine name to the OpenEmbedded build system machine name. | 1493 | kernel machine name to the OpenEmbedded build system machine name. |
| 1494 | </para> | 1494 | </para> |
| 1495 | 1495 | ||
| 1496 | <para> | 1496 | <para> |
| 1497 | Kernel machine names are initially defined in the | 1497 | Kernel machine names are initially defined in the |
| 1498 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Yocto Linux Kernel</ulink> in | 1498 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Yocto Linux Kernel</ulink> in |
| 1499 | the <filename>meta</filename> branch. | 1499 | the <filename>meta</filename> branch. |
| 1500 | From the <filename>meta</filename> branch, look in | 1500 | From the <filename>meta</filename> branch, look in |
| 1501 | the <filename>meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc</filename> file. | 1501 | the <filename>meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc</filename> file. |
| 1502 | For example, from the <filename>meta</filename> branch in the | 1502 | For example, from the <filename>meta</filename> branch in the |
| 1503 | <filename>linux-yocto-3.0</filename> kernel, the | 1503 | <filename>linux-yocto-3.0</filename> kernel, the |
| 1504 | <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file | 1504 | <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file |
| 1505 | has the following: | 1505 | has the following: |
| 1506 | <literallayout class='monospaced'> | 1506 | <literallayout class='monospaced'> |
| 1507 | define KMACHINE cedartrail | 1507 | define KMACHINE cedartrail |
| @@ -1511,7 +1511,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1511 | include ktypes/standard | 1511 | include ktypes/standard |
| 1512 | branch cedartrail | 1512 | branch cedartrail |
| 1513 | 1513 | ||
| 1514 | include cedartrail.scc | 1514 | include cedartrail.scc |
| 1515 | </literallayout> | 1515 | </literallayout> |
| 1516 | You can see that the kernel understands the machine name for the Cedar Trail BSP as | 1516 | You can see that the kernel understands the machine name for the Cedar Trail BSP as |
| 1517 | <filename>cedartrail</filename>. | 1517 | <filename>cedartrail</filename>. |
| @@ -1533,14 +1533,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1533 | KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail" | 1533 | KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail" |
| 1534 | KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc" | 1534 | KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc" |
| 1535 | </literallayout> | 1535 | </literallayout> |
| 1536 | The <filename>KMACHINE</filename> statements in the kernel's append file make sure that | 1536 | The <filename>KMACHINE</filename> statements in the kernel's append file make sure that |
| 1537 | the OpenEmbedded build system and the Yocto Linux kernel understand the same machine | 1537 | the OpenEmbedded build system and the Yocto Linux kernel understand the same machine |
| 1538 | names. | 1538 | names. |
| 1539 | </para> | 1539 | </para> |
| 1540 | 1540 | ||
| 1541 | <para> | 1541 | <para> |
| 1542 | This append file uses two <filename>KMACHINE</filename> statements. | 1542 | This append file uses two <filename>KMACHINE</filename> statements. |
| 1543 | The first is not really necessary but does ensure that the machine known to the | 1543 | The first is not really necessary but does ensure that the machine known to the |
| 1544 | OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine | 1544 | OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine |
| 1545 | in the kernel also known as <filename>cedartrail</filename>: | 1545 | in the kernel also known as <filename>cedartrail</filename>: |
| 1546 | <literallayout class='monospaced'> | 1546 | <literallayout class='monospaced'> |
| @@ -1550,12 +1550,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1550 | 1550 | ||
| 1551 | <para> | 1551 | <para> |
| 1552 | The second statement is a good example of why the <filename>KMACHINE</filename> variable | 1552 | The second statement is a good example of why the <filename>KMACHINE</filename> variable |
| 1553 | is needed. | 1553 | is needed. |
| 1554 | In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename> | 1554 | In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename> |
| 1555 | machine name to refer to the Cedar Trail BSP that does not support the propriatory | 1555 | machine name to refer to the Cedar Trail BSP that does not support the propriatory |
| 1556 | PowerVR driver. | 1556 | PowerVR driver. |
| 1557 | The kernel, however, uses the machine name <filename>cedartrail</filename>. | 1557 | The kernel, however, uses the machine name <filename>cedartrail</filename>. |
| 1558 | Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to | 1558 | Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to |
| 1559 | the kernel's <filename>cedartrail</filename> name: | 1559 | the kernel's <filename>cedartrail</filename> name: |
| 1560 | <literallayout class='monospaced'> | 1560 | <literallayout class='monospaced'> |
| 1561 | KMACHINE_cedartrail-nopvr = "cedartrail" | 1561 | KMACHINE_cedartrail-nopvr = "cedartrail" |
| @@ -1563,9 +1563,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1563 | </para> | 1563 | </para> |
| 1564 | 1564 | ||
| 1565 | <para> | 1565 | <para> |
| 1566 | BSPs that ship with the Yocto Project release provide all mappings between the Yocto | 1566 | BSPs that ship with the Yocto Project release provide all mappings between the Yocto |
| 1567 | Project kernel machine names and the OpenEmbedded machine names. | 1567 | Project kernel machine names and the OpenEmbedded machine names. |
| 1568 | Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine | 1568 | Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine |
| 1569 | name you use is different than that used in the kernel. | 1569 | name you use is different than that used in the kernel. |
| 1570 | </para> | 1570 | </para> |
| 1571 | </glossdef> | 1571 | </glossdef> |
| @@ -1583,16 +1583,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1583 | to be compared against <filename>LAYERVERSION_anotherlayer</filename> in this case). | 1583 | to be compared against <filename>LAYERVERSION_anotherlayer</filename> in this case). |
| 1584 | An error will be produced if any dependency is missing or | 1584 | An error will be produced if any dependency is missing or |
| 1585 | the version numbers do not match exactly (if specified). | 1585 | the version numbers do not match exactly (if specified). |
| 1586 | This variable is used in the <filename>conf/layer.conf</filename> file | 1586 | This variable is used in the <filename>conf/layer.conf</filename> file |
| 1587 | and must be suffixed with the name of the specific layer (e.g. | 1587 | and must be suffixed with the name of the specific layer (e.g. |
| 1588 | <filename>LAYERDEPENDS_mylayer</filename>).</para> | 1588 | <filename>LAYERDEPENDS_mylayer</filename>).</para> |
| 1589 | </glossdef> | 1589 | </glossdef> |
| 1590 | </glossentry> | 1590 | </glossentry> |
| 1591 | 1591 | ||
| 1592 | <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm> | 1592 | <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm> |
| 1593 | <glossdef> | 1593 | <glossdef> |
| 1594 | <para>When used inside the <filename>layer.conf</filename> configuration | 1594 | <para>When used inside the <filename>layer.conf</filename> configuration |
| 1595 | file, this variable provides the path of the current layer. | 1595 | file, this variable provides the path of the current layer. |
| 1596 | This variable requires immediate expansion | 1596 | This variable requires immediate expansion |
| 1597 | (see the BitBake manual) as lazy expansion can result in | 1597 | (see the BitBake manual) as lazy expansion can result in |
| 1598 | the expansion happening in the wrong directory and therefore | 1598 | the expansion happening in the wrong directory and therefore |
| @@ -1605,7 +1605,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1605 | <para>Optionally specifies the version of a layer as a single number. | 1605 | <para>Optionally specifies the version of a layer as a single number. |
| 1606 | You can use this within <filename>LAYERDEPENDS</filename> for another layer in order to | 1606 | You can use this within <filename>LAYERDEPENDS</filename> for another layer in order to |
| 1607 | depend on a specific version of the layer. | 1607 | depend on a specific version of the layer. |
| 1608 | This variable is used in the <filename>conf/layer.conf</filename> file | 1608 | This variable is used in the <filename>conf/layer.conf</filename> file |
| 1609 | and must be suffixed with the name of the specific layer (e.g. | 1609 | and must be suffixed with the name of the specific layer (e.g. |
| 1610 | <filename>LAYERVERSION_mylayer</filename>).</para> | 1610 | <filename>LAYERVERSION_mylayer</filename>).</para> |
| 1611 | </glossdef> | 1611 | </glossdef> |
| @@ -1615,9 +1615,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1615 | <glossdef> | 1615 | <glossdef> |
| 1616 | <para>Checksums of the license text in the recipe source code.</para> | 1616 | <para>Checksums of the license text in the recipe source code.</para> |
| 1617 | <para>This variable tracks changes in license text of the source | 1617 | <para>This variable tracks changes in license text of the source |
| 1618 | code files. | 1618 | code files. |
| 1619 | If the license text is changed, it will trigger a build | 1619 | If the license text is changed, it will trigger a build |
| 1620 | failure, which gives the developer an opportunity to review any | 1620 | failure, which gives the developer an opportunity to review any |
| 1621 | license change.</para> | 1621 | license change.</para> |
| 1622 | <para> | 1622 | <para> |
| 1623 | This variable must be defined for all recipes (unless <filename>LICENSE</filename> | 1623 | This variable must be defined for all recipes (unless <filename>LICENSE</filename> |
| @@ -1636,14 +1636,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1636 | <itemizedlist> | 1636 | <itemizedlist> |
| 1637 | <listitem><para>Do not use spaces within individual | 1637 | <listitem><para>Do not use spaces within individual |
| 1638 | license names.</para></listitem> | 1638 | license names.</para></listitem> |
| 1639 | <listitem><para>Separate license names using | 1639 | <listitem><para>Separate license names using |
| 1640 | | (pipe) when there is a choice between licenses. | 1640 | | (pipe) when there is a choice between licenses. |
| 1641 | </para></listitem> | 1641 | </para></listitem> |
| 1642 | <listitem><para>Separate license names using | 1642 | <listitem><para>Separate license names using |
| 1643 | & (ampersand) when multiple licenses exist | 1643 | & (ampersand) when multiple licenses exist |
| 1644 | that cover different parts of the source. | 1644 | that cover different parts of the source. |
| 1645 | </para></listitem> | 1645 | </para></listitem> |
| 1646 | <listitem><para>You can use spaces between license | 1646 | <listitem><para>You can use spaces between license |
| 1647 | names.</para></listitem> | 1647 | names.</para></listitem> |
| 1648 | </itemizedlist> | 1648 | </itemizedlist> |
| 1649 | </para> | 1649 | </para> |
| @@ -1655,12 +1655,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1655 | LICENSE = "MPL-1 & LGPLv2.1" | 1655 | LICENSE = "MPL-1 & LGPLv2.1" |
| 1656 | LICENSE = "GPLv2+" | 1656 | LICENSE = "GPLv2+" |
| 1657 | </literallayout> | 1657 | </literallayout> |
| 1658 | The first example is from the recipes for Qt, which the user | 1658 | The first example is from the recipes for Qt, which the user |
| 1659 | may choose to distribute under either the LGPL version | 1659 | may choose to distribute under either the LGPL version |
| 1660 | 2.1 or GPL version 3. | 1660 | 2.1 or GPL version 3. |
| 1661 | The second example is from Cairo where two licenses cover | 1661 | The second example is from Cairo where two licenses cover |
| 1662 | different parts of the source code. | 1662 | different parts of the source code. |
| 1663 | The final example is from <filename>sysstat</filename>, | 1663 | The final example is from <filename>sysstat</filename>, |
| 1664 | which presents a single license. | 1664 | which presents a single license. |
| 1665 | </para> | 1665 | </para> |
| 1666 | </glossdef> | 1666 | </glossdef> |
| @@ -1669,10 +1669,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1669 | <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm> | 1669 | <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm> |
| 1670 | <glossdef> | 1670 | <glossdef> |
| 1671 | <para>Path to additional licenses used during the build. | 1671 | <para>Path to additional licenses used during the build. |
| 1672 | By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename> | 1672 | By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename> |
| 1673 | to define the directory that holds common license text used during the build. | 1673 | to define the directory that holds common license text used during the build. |
| 1674 | The <filename>LICENSE_PATH</filename> variable allows you to extend that | 1674 | The <filename>LICENSE_PATH</filename> variable allows you to extend that |
| 1675 | location to other areas that have additional licenses: | 1675 | location to other areas that have additional licenses: |
| 1676 | <literallayout class='monospaced'> | 1676 | <literallayout class='monospaced'> |
| 1677 | LICENSE_PATH += "/path/to/additional/common/licenses" | 1677 | LICENSE_PATH += "/path/to/additional/common/licenses" |
| 1678 | </literallayout></para> | 1678 | </literallayout></para> |
| @@ -1687,26 +1687,26 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1687 | <glossdef> | 1687 | <glossdef> |
| 1688 | <para> | 1688 | <para> |
| 1689 | Specifies the target device for which the image is built. | 1689 | Specifies the target device for which the image is built. |
| 1690 | You define <filename>MACHINE</filename> in the | 1690 | You define <filename>MACHINE</filename> in the |
| 1691 | <filename>local.conf</filename> file found in the | 1691 | <filename>local.conf</filename> file found in the |
| 1692 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | 1692 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
| 1693 | By default, <filename>MACHINE</filename> is set to | 1693 | By default, <filename>MACHINE</filename> is set to |
| 1694 | "qemux86", which is an x86-based architecture machine to | 1694 | "qemux86", which is an x86-based architecture machine to |
| 1695 | be emulated using QEMU: | 1695 | be emulated using QEMU: |
| 1696 | <literallayout class='monospaced'> | 1696 | <literallayout class='monospaced'> |
| 1697 | MACHINE ?= "qemux86" | 1697 | MACHINE ?= "qemux86" |
| 1698 | </literallayout> | 1698 | </literallayout> |
| 1699 | The variable corresponds to a machine configuration file of the | 1699 | The variable corresponds to a machine configuration file of the |
| 1700 | same name, through which machine-specific configurations are set. | 1700 | same name, through which machine-specific configurations are set. |
| 1701 | Thus, when <filename>MACHINE</filename> is set to "qemux86" there | 1701 | Thus, when <filename>MACHINE</filename> is set to "qemux86" there |
| 1702 | exists the corresponding <filename>qemux86.conf</filename> machine | 1702 | exists the corresponding <filename>qemux86.conf</filename> machine |
| 1703 | configuration file, which can be found in the | 1703 | configuration file, which can be found in the |
| 1704 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | 1704 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> |
| 1705 | in <filename>meta/conf/machine</filename>. | 1705 | in <filename>meta/conf/machine</filename>. |
| 1706 | </para> | 1706 | </para> |
| 1707 | 1707 | ||
| 1708 | <para> | 1708 | <para> |
| 1709 | The list of machines supported by the Yocto Project as | 1709 | The list of machines supported by the Yocto Project as |
| 1710 | shipped include the following: | 1710 | shipped include the following: |
| 1711 | <literallayout class='monospaced'> | 1711 | <literallayout class='monospaced'> |
| 1712 | MACHINE ?= "qemuarm" | 1712 | MACHINE ?= "qemuarm" |
| @@ -1721,10 +1721,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1721 | </literallayout> | 1721 | </literallayout> |
| 1722 | The last four are Yocto Project reference hardware boards, which | 1722 | The last four are Yocto Project reference hardware boards, which |
| 1723 | are provided in the <filename>meta-yocto-bsp</filename> layer. | 1723 | are provided in the <filename>meta-yocto-bsp</filename> layer. |
| 1724 | <note>Adding additional Board Support Package (BSP) layers | 1724 | <note>Adding additional Board Support Package (BSP) layers |
| 1725 | to your configuration adds new possible settings for | 1725 | to your configuration adds new possible settings for |
| 1726 | <filename>MACHINE</filename>. | 1726 | <filename>MACHINE</filename>. |
| 1727 | </note> | 1727 | </note> |
| 1728 | </para> | 1728 | </para> |
| 1729 | </glossdef> | 1729 | </glossdef> |
| 1730 | </glossentry> | 1730 | </glossentry> |
| @@ -1736,16 +1736,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1736 | A list of required machine-specific packages to install as part of | 1736 | A list of required machine-specific packages to install as part of |
| 1737 | the image being built. | 1737 | the image being built. |
| 1738 | The build process depends on these packages being present. | 1738 | The build process depends on these packages being present. |
| 1739 | Furthermore, because this is a "machine essential" variable, the list of | 1739 | Furthermore, because this is a "machine essential" variable, the list of |
| 1740 | packages are essential for the machine to boot. | 1740 | packages are essential for the machine to boot. |
| 1741 | The impact of this variable affects images based on | 1741 | The impact of this variable affects images based on |
| 1742 | <filename>packagegroup-core-boot</filename>, | 1742 | <filename>packagegroup-core-boot</filename>, |
| 1743 | including the <filename>core-image-minimal</filename> image. | 1743 | including the <filename>core-image-minimal</filename> image. |
| 1744 | </para> | 1744 | </para> |
| 1745 | <para> | 1745 | <para> |
| 1746 | This variable is similar to the | 1746 | This variable is similar to the |
| 1747 | <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename> | 1747 | <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename> |
| 1748 | variable with the exception that the image being built has a build | 1748 | variable with the exception that the image being built has a build |
| 1749 | dependency on the variable's list of packages. | 1749 | dependency on the variable's list of packages. |
| 1750 | In other words, the image will not build if a file in this list is not found. | 1750 | In other words, the image will not build if a file in this list is not found. |
| 1751 | </para> | 1751 | </para> |
| @@ -1768,16 +1768,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1768 | A list of recommended machine-specific packages to install as part of | 1768 | A list of recommended machine-specific packages to install as part of |
| 1769 | the image being built. | 1769 | the image being built. |
| 1770 | The build process does not depend on these packages being present. | 1770 | The build process does not depend on these packages being present. |
| 1771 | However, because this is a "machine essential" variable, the list of | 1771 | However, because this is a "machine essential" variable, the list of |
| 1772 | packages are essential for the machine to boot. | 1772 | packages are essential for the machine to boot. |
| 1773 | The impact of this variable affects images based on | 1773 | The impact of this variable affects images based on |
| 1774 | <filename>packagegroup-core-boot</filename>, | 1774 | <filename>packagegroup-core-boot</filename>, |
| 1775 | including the <filename>core-image-minimal</filename> image. | 1775 | including the <filename>core-image-minimal</filename> image. |
| 1776 | </para> | 1776 | </para> |
| 1777 | <para> | 1777 | <para> |
| 1778 | This variable is similar to the | 1778 | This variable is similar to the |
| 1779 | <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename> | 1779 | <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename> |
| 1780 | variable with the exception that the image being built does not have a build | 1780 | variable with the exception that the image being built does not have a build |
| 1781 | dependency on the variable's list of packages. | 1781 | dependency on the variable's list of packages. |
| 1782 | In other words, the image will still build if a package in this list is not found. | 1782 | In other words, the image will still build if a package in this list is not found. |
| 1783 | Typically, this variable is used to handle essential kernel modules, whose | 1783 | Typically, this variable is used to handle essential kernel modules, whose |
| @@ -1790,20 +1790,20 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1790 | However, the driver can be built as a module or | 1790 | However, the driver can be built as a module or |
| 1791 | into the kernel depending on the kernel configuration. | 1791 | into the kernel depending on the kernel configuration. |
| 1792 | If the driver is built as a module, you want it to be installed. | 1792 | If the driver is built as a module, you want it to be installed. |
| 1793 | But, when the driver is built into the kernel, you still want the | 1793 | But, when the driver is built into the kernel, you still want the |
| 1794 | build to succeed. | 1794 | build to succeed. |
| 1795 | This variable sets up a "recommends" relationship so that in the latter case, | 1795 | This variable sets up a "recommends" relationship so that in the latter case, |
| 1796 | the build will not fail due to the missing package. | 1796 | the build will not fail due to the missing package. |
| 1797 | To accomplish this, assuming the package for the module was called | 1797 | To accomplish this, assuming the package for the module was called |
| 1798 | <filename>kernel-module-ab123</filename>, you would use the | 1798 | <filename>kernel-module-ab123</filename>, you would use the |
| 1799 | following in the machine's <filename>.conf</filename> configuration | 1799 | following in the machine's <filename>.conf</filename> configuration |
| 1800 | file: | 1800 | file: |
| 1801 | <literallayout class='monospaced'> | 1801 | <literallayout class='monospaced'> |
| 1802 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" | 1802 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" |
| 1803 | </literallayout> | 1803 | </literallayout> |
| 1804 | </para> | 1804 | </para> |
| 1805 | <para> | 1805 | <para> |
| 1806 | Some examples of these machine essentials are flash, screen, keyboard, mouse, | 1806 | Some examples of these machine essentials are flash, screen, keyboard, mouse, |
| 1807 | or touchscreen drivers (depending on the machine). | 1807 | or touchscreen drivers (depending on the machine). |
| 1808 | </para> | 1808 | </para> |
| 1809 | </glossdef> | 1809 | </glossdef> |
| @@ -1812,21 +1812,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1812 | <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm> | 1812 | <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm> |
| 1813 | <glossdef> | 1813 | <glossdef> |
| 1814 | <para> | 1814 | <para> |
| 1815 | A list of machine-specific packages to install as part of the | 1815 | A list of machine-specific packages to install as part of the |
| 1816 | image being built that are not essential for the machine to boot. | 1816 | image being built that are not essential for the machine to boot. |
| 1817 | However, the build process for more fully-featured images | 1817 | However, the build process for more fully-featured images |
| 1818 | depends on the packages being present. | 1818 | depends on the packages being present. |
| 1819 | </para> | 1819 | </para> |
| 1820 | <para> | 1820 | <para> |
| 1821 | This variable affects all images based on | 1821 | This variable affects all images based on |
| 1822 | <filename>packagegroup-base</filename>, which does not include the | 1822 | <filename>packagegroup-base</filename>, which does not include the |
| 1823 | <filename>core-image-minimal</filename> or <filename>core-image-basic</filename> | 1823 | <filename>core-image-minimal</filename> or <filename>core-image-basic</filename> |
| 1824 | images. | 1824 | images. |
| 1825 | </para> | 1825 | </para> |
| 1826 | <para> | 1826 | <para> |
| 1827 | The variable is similar to the | 1827 | The variable is similar to the |
| 1828 | <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename> | 1828 | <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename> |
| 1829 | variable with the exception that the image being built has a build | 1829 | variable with the exception that the image being built has a build |
| 1830 | dependency on the variable's list of packages. | 1830 | dependency on the variable's list of packages. |
| 1831 | In other words, the image will not build if a file in this list is not found. | 1831 | In other words, the image will not build if a file in this list is not found. |
| 1832 | </para> | 1832 | </para> |
| @@ -1834,8 +1834,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1834 | An example is a machine that has WiFi capability but is not essential | 1834 | An example is a machine that has WiFi capability but is not essential |
| 1835 | For the machine to boot the image. | 1835 | For the machine to boot the image. |
| 1836 | However, if you are building a more fully-featured image, you want to enable | 1836 | However, if you are building a more fully-featured image, you want to enable |
| 1837 | the WiFi. | 1837 | the WiFi. |
| 1838 | The package containing the firmware for the WiFi hardware is always | 1838 | The package containing the firmware for the WiFi hardware is always |
| 1839 | expected to exist, so it is acceptable for the build process to depend upon | 1839 | expected to exist, so it is acceptable for the build process to depend upon |
| 1840 | finding the package. | 1840 | finding the package. |
| 1841 | In this case, assuming the package for the firmware was called | 1841 | In this case, assuming the package for the firmware was called |
| @@ -1852,20 +1852,20 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1852 | <glossdef> | 1852 | <glossdef> |
| 1853 | <para></para> | 1853 | <para></para> |
| 1854 | <para> | 1854 | <para> |
| 1855 | A list of machine-specific packages to install as part of the | 1855 | A list of machine-specific packages to install as part of the |
| 1856 | image being built that are not essential for booting the machine. | 1856 | image being built that are not essential for booting the machine. |
| 1857 | The image being built has no build dependency on this list of packages. | 1857 | The image being built has no build dependency on this list of packages. |
| 1858 | </para> | 1858 | </para> |
| 1859 | <para> | 1859 | <para> |
| 1860 | This variable affects only images based on | 1860 | This variable affects only images based on |
| 1861 | <filename>packagegroup-base</filename>, which does not include the | 1861 | <filename>packagegroup-base</filename>, which does not include the |
| 1862 | <filename>core-image-minimal</filename> or <filename>core-image-basic</filename> | 1862 | <filename>core-image-minimal</filename> or <filename>core-image-basic</filename> |
| 1863 | images. | 1863 | images. |
| 1864 | </para> | 1864 | </para> |
| 1865 | <para> | 1865 | <para> |
| 1866 | This variable is similar to the | 1866 | This variable is similar to the |
| 1867 | <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename> | 1867 | <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename> |
| 1868 | variable with the exception that the image being built does not have a build | 1868 | variable with the exception that the image being built does not have a build |
| 1869 | dependency on the variable's list of packages. | 1869 | dependency on the variable's list of packages. |
| 1870 | In other words, the image will build if a file in this list is not found. | 1870 | In other words, the image will build if a file in this list is not found. |
| 1871 | </para> | 1871 | </para> |
| @@ -1873,7 +1873,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1873 | An example is a machine that has WiFi capability but is not essential | 1873 | An example is a machine that has WiFi capability but is not essential |
| 1874 | For the machine to boot the image. | 1874 | For the machine to boot the image. |
| 1875 | However, if you are building a more fully-featured image, you want to enable | 1875 | However, if you are building a more fully-featured image, you want to enable |
| 1876 | WiFi. | 1876 | WiFi. |
| 1877 | In this case, the package containing the WiFi kernel module will not be produced | 1877 | In this case, the package containing the WiFi kernel module will not be produced |
| 1878 | if the WiFi driver is built into the kernel, in which case you still want the | 1878 | if the WiFi driver is built into the kernel, in which case you still want the |
| 1879 | build to succeed instead of failing as a result of the package not being found. | 1879 | build to succeed instead of failing as a result of the package not being found. |
| @@ -1889,19 +1889,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1889 | 1889 | ||
| 1890 | <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm> | 1890 | <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm> |
| 1891 | <glossdef> | 1891 | <glossdef> |
| 1892 | <para>Specifies the list of hardware features the | 1892 | <para>Specifies the list of hardware features the |
| 1893 | <link linkend='var-MACHINE'>MACHINE</link> supports. | 1893 | <link linkend='var-MACHINE'>MACHINE</link> supports. |
| 1894 | For example, including the "bluetooth" feature causes the | 1894 | For example, including the "bluetooth" feature causes the |
| 1895 | <filename>bluez</filename> bluetooth daemon to be built and | 1895 | <filename>bluez</filename> bluetooth daemon to be built and |
| 1896 | added to the image. | 1896 | added to the image. |
| 1897 | It also causes the <filename>connman</filename> recipe | 1897 | It also causes the <filename>connman</filename> recipe |
| 1898 | to look at <filename>MACHINE_FEATURES</filename> and when it | 1898 | to look at <filename>MACHINE_FEATURES</filename> and when it |
| 1899 | finds "bluetooth" there it enables the bluetooth | 1899 | finds "bluetooth" there it enables the bluetooth |
| 1900 | support in ConnMan. | 1900 | support in ConnMan. |
| 1901 | </para> | 1901 | </para> |
| 1902 | 1902 | ||
| 1903 | <para> | 1903 | <para> |
| 1904 | For a list of features supported by the Yocto Project as shipped, | 1904 | For a list of features supported by the Yocto Project as shipped, |
| 1905 | see the "<link linkend='ref-features-machine'>Machine</link>" section. | 1905 | see the "<link linkend='ref-features-machine'>Machine</link>" section. |
| 1906 | </para> | 1906 | </para> |
| 1907 | </glossdef> | 1907 | </glossdef> |
| @@ -1909,18 +1909,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1909 | 1909 | ||
| 1910 | <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm> | 1910 | <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm> |
| 1911 | <glossdef> | 1911 | <glossdef> |
| 1912 | <para>Features to be added to | 1912 | <para>Features to be added to |
| 1913 | <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename> | 1913 | <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename> |
| 1914 | if not also present in | 1914 | if not also present in |
| 1915 | <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>. | 1915 | <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>. |
| 1916 | </para> | 1916 | </para> |
| 1917 | 1917 | ||
| 1918 | <para> | 1918 | <para> |
| 1919 | This variable is set in the <filename>meta/conf/bitbake.conf</filename> file. | 1919 | This variable is set in the <filename>meta/conf/bitbake.conf</filename> file. |
| 1920 | It is not intended to be user-configurable. | 1920 | It is not intended to be user-configurable. |
| 1921 | It is best to just reference the variable to see which machine features are | 1921 | It is best to just reference the variable to see which machine features are |
| 1922 | being backfilled for all machine configurations. | 1922 | being backfilled for all machine configurations. |
| 1923 | See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for | 1923 | See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for |
| 1924 | more information. | 1924 | more information. |
| 1925 | </para> | 1925 | </para> |
| 1926 | </glossdef> | 1926 | </glossdef> |
| @@ -1933,7 +1933,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1933 | that should not be backfilled (i.e. added to | 1933 | that should not be backfilled (i.e. added to |
| 1934 | <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>) | 1934 | <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>) |
| 1935 | during the build. | 1935 | during the build. |
| 1936 | See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for | 1936 | See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for |
| 1937 | more information. | 1937 | more information. |
| 1938 | </para> | 1938 | </para> |
| 1939 | </glossdef> | 1939 | </glossdef> |
| @@ -1949,13 +1949,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1949 | <glossdef> | 1949 | <glossdef> |
| 1950 | <para> | 1950 | <para> |
| 1951 | Specifies a prefix has been added to | 1951 | Specifies a prefix has been added to |
| 1952 | <link linkend='var-PN'><filename>PN</filename></link> to create a special version | 1952 | <link linkend='var-PN'><filename>PN</filename></link> to create a special version |
| 1953 | of a recipe or package, such as a multilib version. | 1953 | of a recipe or package, such as a multilib version. |
| 1954 | The variable is used in places where the prefix needs to be | 1954 | The variable is used in places where the prefix needs to be |
| 1955 | added to or removed from a the name (e.g. the | 1955 | added to or removed from a the name (e.g. the |
| 1956 | <link linkend='var-BPN'><filename>BPN</filename></link> variable). | 1956 | <link linkend='var-BPN'><filename>BPN</filename></link> variable). |
| 1957 | <filename>MLPREFIX</filename> gets set when a prefix has been | 1957 | <filename>MLPREFIX</filename> gets set when a prefix has been |
| 1958 | added to <filename>PN</filename>. | 1958 | added to <filename>PN</filename>. |
| 1959 | </para> | 1959 | </para> |
| 1960 | </glossdef> | 1960 | </glossdef> |
| 1961 | </glossentry> | 1961 | </glossentry> |
| @@ -1981,17 +1981,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 1981 | <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm> | 1981 | <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm> |
| 1982 | <glossdef> | 1982 | <glossdef> |
| 1983 | <para> | 1983 | <para> |
| 1984 | Controls how the OpenEmbedded build system spawns | 1984 | Controls how the OpenEmbedded build system spawns |
| 1985 | interactive terminals on the host development system | 1985 | interactive terminals on the host development system |
| 1986 | (e.g. using the BitBake command with the | 1986 | (e.g. using the BitBake command with the |
| 1987 | <filename>-c devshell</filename> command-line option). | 1987 | <filename>-c devshell</filename> command-line option). |
| 1988 | For more information, see the | 1988 | For more information, see the |
| 1989 | "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section | 1989 | "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section |
| 1990 | in the Yocto Project Development Manual. | 1990 | in the Yocto Project Development Manual. |
| 1991 | </para> | 1991 | </para> |
| 1992 | 1992 | ||
| 1993 | <para> | 1993 | <para> |
| 1994 | You can use the following values for the | 1994 | You can use the following values for the |
| 1995 | <filename>OE_TERMINAL</filename> variable: | 1995 | <filename>OE_TERMINAL</filename> variable: |
| 1996 | <literallayout class='monospaced'> | 1996 | <literallayout class='monospaced'> |
| 1997 | auto | 1997 | auto |
| @@ -2000,10 +2000,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2000 | rxvt | 2000 | rxvt |
| 2001 | screen | 2001 | screen |
| 2002 | konsole | 2002 | konsole |
| 2003 | none | 2003 | none |
| 2004 | </literallayout> | 2004 | </literallayout> |
| 2005 | <note>Konsole support only works for KDE 3.x. | 2005 | <note>Konsole support only works for KDE 3.x. |
| 2006 | Also, "auto" is the default behavior for | 2006 | Also, "auto" is the default behavior for |
| 2007 | <filename>OE_TERMINAL</filename></note> | 2007 | <filename>OE_TERMINAL</filename></note> |
| 2008 | </para> | 2008 | </para> |
| 2009 | </glossdef> | 2009 | </glossdef> |
| @@ -2030,9 +2030,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2030 | 2030 | ||
| 2031 | <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm> | 2031 | <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm> |
| 2032 | <glossdef> | 2032 | <glossdef> |
| 2033 | <para>Enables easily adding packages to | 2033 | <para>Enables easily adding packages to |
| 2034 | <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> | 2034 | <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> |
| 2035 | before <filename>${PN}</filename> so that the packages can pick | 2035 | before <filename>${PN}</filename> so that the packages can pick |
| 2036 | up files that would normally be included in the default package.</para> | 2036 | up files that would normally be included in the default package.</para> |
| 2037 | </glossdef> | 2037 | </glossdef> |
| 2038 | </glossentry> | 2038 | </glossentry> |
| @@ -2040,15 +2040,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2040 | <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm> | 2040 | <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm> |
| 2041 | <glossdef> | 2041 | <glossdef> |
| 2042 | <para>This variable, which is set in the <filename>local.conf</filename> configuration | 2042 | <para>This variable, which is set in the <filename>local.conf</filename> configuration |
| 2043 | file found in the <filename>conf</filename> folder of the | 2043 | file found in the <filename>conf</filename> folder of the |
| 2044 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, | 2044 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, |
| 2045 | specifies the package manager to use when packaging data. | 2045 | specifies the package manager to use when packaging data. |
| 2046 | You can provide one or more arguments for the variable with the first | 2046 | You can provide one or more arguments for the variable with the first |
| 2047 | argument being the package manager used to create images: | 2047 | argument being the package manager used to create images: |
| 2048 | <literallayout class='monospaced'> | 2048 | <literallayout class='monospaced'> |
| 2049 | PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" | 2049 | PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" |
| 2050 | </literallayout> | 2050 | </literallayout> |
| 2051 | For information on build performance effects as a result of the | 2051 | For information on build performance effects as a result of the |
| 2052 | package manager use, see | 2052 | package manager use, see |
| 2053 | <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link> | 2053 | <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link> |
| 2054 | in this manual. | 2054 | in this manual. |
| @@ -2067,33 +2067,33 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2067 | <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm> | 2067 | <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm> |
| 2068 | <glossdef> | 2068 | <glossdef> |
| 2069 | <para> | 2069 | <para> |
| 2070 | This variable provides a means of enabling or disabling | 2070 | This variable provides a means of enabling or disabling |
| 2071 | features of a recipe on a per-recipe basis. | 2071 | features of a recipe on a per-recipe basis. |
| 2072 | The <filename>PACKAGECONFIG</filename> | 2072 | The <filename>PACKAGECONFIG</filename> |
| 2073 | variable itself specifies a space-separated list of the | 2073 | variable itself specifies a space-separated list of the |
| 2074 | features to enable. | 2074 | features to enable. |
| 2075 | The features themselves are specified as flags on the | 2075 | The features themselves are specified as flags on the |
| 2076 | <filename>PACKAGECONFIG</filename> variable. | 2076 | <filename>PACKAGECONFIG</filename> variable. |
| 2077 | You can provide up to four arguments, which are separated by | 2077 | You can provide up to four arguments, which are separated by |
| 2078 | commas, to determine the behavior of each feature | 2078 | commas, to determine the behavior of each feature |
| 2079 | when it is enabled or disabled. | 2079 | when it is enabled or disabled. |
| 2080 | You can omit any argument you like but must retain the | 2080 | You can omit any argument you like but must retain the |
| 2081 | separating commas. | 2081 | separating commas. |
| 2082 | The arguments specify the following: | 2082 | The arguments specify the following: |
| 2083 | <orderedlist> | 2083 | <orderedlist> |
| 2084 | <listitem><para>Extra arguments | 2084 | <listitem><para>Extra arguments |
| 2085 | that should be added to the configure script argument list | 2085 | that should be added to the configure script argument list |
| 2086 | (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>) | 2086 | (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>) |
| 2087 | if the feature is enabled.</para></listitem> | 2087 | if the feature is enabled.</para></listitem> |
| 2088 | <listitem><para>Extra arguments | 2088 | <listitem><para>Extra arguments |
| 2089 | that should be added to <filename>EXTRA_OECONF</filename> | 2089 | that should be added to <filename>EXTRA_OECONF</filename> |
| 2090 | if the feature is disabled. | 2090 | if the feature is disabled. |
| 2091 | </para></listitem> | 2091 | </para></listitem> |
| 2092 | <listitem><para>Additional build dependencies | 2092 | <listitem><para>Additional build dependencies |
| 2093 | (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>) | 2093 | (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>) |
| 2094 | that should be added if the feature is enabled. | 2094 | that should be added if the feature is enabled. |
| 2095 | </para></listitem> | 2095 | </para></listitem> |
| 2096 | <listitem><para>Additional runtime dependencies | 2096 | <listitem><para>Additional runtime dependencies |
| 2097 | (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>) | 2097 | (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>) |
| 2098 | that should be added if the feature is enabled. | 2098 | that should be added if the feature is enabled. |
| 2099 | </para></listitem> | 2099 | </para></listitem> |
| @@ -2101,25 +2101,25 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2101 | </para> | 2101 | </para> |
| 2102 | 2102 | ||
| 2103 | <para> | 2103 | <para> |
| 2104 | Consider the following example taken from the | 2104 | Consider the following example taken from the |
| 2105 | <filename>librsvg</filename> recipe. | 2105 | <filename>librsvg</filename> recipe. |
| 2106 | In this example the feature is <filename>croco</filename>, which | 2106 | In this example the feature is <filename>croco</filename>, which |
| 2107 | has three arguments that determine the feature's behavior. | 2107 | has three arguments that determine the feature's behavior. |
| 2108 | <literallayout class='monospaced'> | 2108 | <literallayout class='monospaced'> |
| 2109 | PACKAGECONFIG ??= "croco" | 2109 | PACKAGECONFIG ??= "croco" |
| 2110 | PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco" | 2110 | PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco" |
| 2111 | </literallayout> | 2111 | </literallayout> |
| 2112 | The <filename>--with-croco</filename> and | 2112 | The <filename>--with-croco</filename> and |
| 2113 | <filename>libcroco</filename> arguments apply only if | 2113 | <filename>libcroco</filename> arguments apply only if |
| 2114 | the feature is enabled. | 2114 | the feature is enabled. |
| 2115 | In this case, <filename>--with-croco</filename> is | 2115 | In this case, <filename>--with-croco</filename> is |
| 2116 | added to the configure script argument list and | 2116 | added to the configure script argument list and |
| 2117 | <filename>libcroco</filename> is added to | 2117 | <filename>libcroco</filename> is added to |
| 2118 | <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>. | 2118 | <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>. |
| 2119 | On the other hand, if the feature is disabled say through | 2119 | On the other hand, if the feature is disabled say through |
| 2120 | a <filename>.bbappend</filename> file in another layer, then | 2120 | a <filename>.bbappend</filename> file in another layer, then |
| 2121 | the second argument <filename>--without-croco</filename> is | 2121 | the second argument <filename>--without-croco</filename> is |
| 2122 | added to the configure script rather than | 2122 | added to the configure script rather than |
| 2123 | <filename>--with-croco</filename>. | 2123 | <filename>--with-croco</filename>. |
| 2124 | </para> | 2124 | </para> |
| 2125 | </glossdef> | 2125 | </glossdef> |
| @@ -2138,29 +2138,29 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2138 | <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm> | 2138 | <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm> |
| 2139 | <glossdef> | 2139 | <glossdef> |
| 2140 | <para> | 2140 | <para> |
| 2141 | A promise that your recipe satisfies runtime dependencies | 2141 | A promise that your recipe satisfies runtime dependencies |
| 2142 | for optional modules that are found in other recipes. | 2142 | for optional modules that are found in other recipes. |
| 2143 | <filename>PACKAGES_DYNAMIC</filename> | 2143 | <filename>PACKAGES_DYNAMIC</filename> |
| 2144 | does not actually satisfy the dependencies, it only states that | 2144 | does not actually satisfy the dependencies, it only states that |
| 2145 | they should be satisfied. | 2145 | they should be satisfied. |
| 2146 | For example, if a hard, runtime dependency | 2146 | For example, if a hard, runtime dependency |
| 2147 | (<filename>RDEPENDS</filename>) of another package is satisfied | 2147 | (<filename>RDEPENDS</filename>) of another package is satisfied |
| 2148 | at build time through the <filename>PACKAGES_DYNAMIC</filename> | 2148 | at build time through the <filename>PACKAGES_DYNAMIC</filename> |
| 2149 | variable, but a package with the module name is never actually | 2149 | variable, but a package with the module name is never actually |
| 2150 | produced, then the other package will be broken. | 2150 | produced, then the other package will be broken. |
| 2151 | Thus, if you attempt to include that package in an image, | 2151 | Thus, if you attempt to include that package in an image, |
| 2152 | you will get a dependency failure from the packaging system | 2152 | you will get a dependency failure from the packaging system |
| 2153 | during <filename>do_rootfs</filename>. | 2153 | during <filename>do_rootfs</filename>. |
| 2154 | Typically, if there is a chance that such a situation can | 2154 | Typically, if there is a chance that such a situation can |
| 2155 | occur and the package that is not created is valid | 2155 | occur and the package that is not created is valid |
| 2156 | without the dependency being satisfied, then you should use | 2156 | without the dependency being satisfied, then you should use |
| 2157 | <filename>RRECOMMENDS</filename> (a soft runtime dependency) | 2157 | <filename>RRECOMMENDS</filename> (a soft runtime dependency) |
| 2158 | instead of <filename>RDEPENDS</filename>. | 2158 | instead of <filename>RDEPENDS</filename>. |
| 2159 | </para> | 2159 | </para> |
| 2160 | 2160 | ||
| 2161 | <para> | 2161 | <para> |
| 2162 | For an example of how to use the <filename>PACKAGES_DYNAMIC</filename> | 2162 | For an example of how to use the <filename>PACKAGES_DYNAMIC</filename> |
| 2163 | variable when you are splitting packages, see the | 2163 | variable when you are splitting packages, see the |
| 2164 | "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section | 2164 | "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section |
| 2165 | in the Yocto Project Development Manual. | 2165 | in the Yocto Project Development Manual. |
| 2166 | </para> | 2166 | </para> |
| @@ -2169,11 +2169,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2169 | 2169 | ||
| 2170 | <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm> | 2170 | <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm> |
| 2171 | <glossdef> | 2171 | <glossdef> |
| 2172 | <para>Specifies extra options that are passed to the <filename>make</filename> command during the | 2172 | <para>Specifies extra options that are passed to the <filename>make</filename> command during the |
| 2173 | compile tasks. | 2173 | compile tasks. |
| 2174 | This variable is usually in the form <filename>-j 4</filename>, where the number | 2174 | This variable is usually in the form <filename>-j 4</filename>, where the number |
| 2175 | represents the maximum number of parallel threads make can run. | 2175 | represents the maximum number of parallel threads make can run. |
| 2176 | If you development host supports multiple cores a good rule of thumb is to set | 2176 | If you development host supports multiple cores a good rule of thumb is to set |
| 2177 | this variable to twice the number of cores on the host.</para> | 2177 | this variable to twice the number of cores on the host.</para> |
| 2178 | </glossdef> | 2178 | </glossdef> |
| 2179 | </glossentry> | 2179 | </glossentry> |
| @@ -2194,21 +2194,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2194 | <glossdef> | 2194 | <glossdef> |
| 2195 | <para>This variable can have two separate functions depending on the context: a recipe | 2195 | <para>This variable can have two separate functions depending on the context: a recipe |
| 2196 | name or a resulting package name.</para> | 2196 | name or a resulting package name.</para> |
| 2197 | <para><filename>PN</filename> refers to a recipe name in the context of a file used | 2197 | <para><filename>PN</filename> refers to a recipe name in the context of a file used |
| 2198 | by the OpenEmbedded build system as input to create a package. | 2198 | by the OpenEmbedded build system as input to create a package. |
| 2199 | The name is normally extracted from the recipe file name. | 2199 | The name is normally extracted from the recipe file name. |
| 2200 | For example, if the recipe is named | 2200 | For example, if the recipe is named |
| 2201 | <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename> | 2201 | <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename> |
| 2202 | will be "expat".</para> | 2202 | will be "expat".</para> |
| 2203 | <para> | 2203 | <para> |
| 2204 | The variable refers to a package name in the context of a file created or produced by the | 2204 | The variable refers to a package name in the context of a file created or produced by the |
| 2205 | OpenEmbedded build system.</para> | 2205 | OpenEmbedded build system.</para> |
| 2206 | <para>If applicable, the <filename>PN</filename> variable also contains any special | 2206 | <para>If applicable, the <filename>PN</filename> variable also contains any special |
| 2207 | suffix or prefix. | 2207 | suffix or prefix. |
| 2208 | For example, using <filename>bash</filename> to build packages for the native | 2208 | For example, using <filename>bash</filename> to build packages for the native |
| 2209 | machine, <filename>PN</filename> is <filename>bash-native</filename>. | 2209 | machine, <filename>PN</filename> is <filename>bash-native</filename>. |
| 2210 | Using <filename>bash</filename> to build packages for the target and for Multilib, | 2210 | Using <filename>bash</filename> to build packages for the target and for Multilib, |
| 2211 | <filename>PN</filename> would be <filename>bash</filename> and | 2211 | <filename>PN</filename> would be <filename>bash</filename> and |
| 2212 | <filename>lib64-bash</filename>, respectively. | 2212 | <filename>lib64-bash</filename>, respectively. |
| 2213 | </para> | 2213 | </para> |
| 2214 | </glossdef> | 2214 | </glossdef> |
| @@ -2216,7 +2216,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2216 | 2216 | ||
| 2217 | <glossentry id='var-PR'><glossterm>PR</glossterm> | 2217 | <glossentry id='var-PR'><glossterm>PR</glossterm> |
| 2218 | <glossdef> | 2218 | <glossdef> |
| 2219 | <para>The revision of the recipe. | 2219 | <para>The revision of the recipe. |
| 2220 | The default value for this variable is "r0". | 2220 | The default value for this variable is "r0". |
| 2221 | </para> | 2221 | </para> |
| 2222 | </glossdef> | 2222 | </glossdef> |
| @@ -2224,10 +2224,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2224 | 2224 | ||
| 2225 | <glossentry id='var-PRINC'><glossterm>PRINC</glossterm> | 2225 | <glossentry id='var-PRINC'><glossterm>PRINC</glossterm> |
| 2226 | <glossdef> | 2226 | <glossdef> |
| 2227 | <para>Causes the <filename>PR</filename> variable of | 2227 | <para>Causes the <filename>PR</filename> variable of |
| 2228 | <filename>.bbappend</filename> files to dynamically increment. | 2228 | <filename>.bbappend</filename> files to dynamically increment. |
| 2229 | This increment minimizes the impact of layer ordering.</para> | 2229 | This increment minimizes the impact of layer ordering.</para> |
| 2230 | <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist, | 2230 | <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist, |
| 2231 | <filename>PRINC</filename> should be self referencing. | 2231 | <filename>PRINC</filename> should be self referencing. |
| 2232 | This variable defaults to 0.</para> | 2232 | This variable defaults to 0.</para> |
| 2233 | <para>Following is an example that increments <filename>PR</filename> by two: | 2233 | <para>Following is an example that increments <filename>PR</filename> by two: |
| @@ -2235,8 +2235,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2235 | PRINC := "${@int(PRINC) + 2}" | 2235 | PRINC := "${@int(PRINC) + 2}" |
| 2236 | </literallayout> | 2236 | </literallayout> |
| 2237 | It is adviseable not to use strings such as ".= '.1'" with the variable because | 2237 | It is adviseable not to use strings such as ".= '.1'" with the variable because |
| 2238 | this usage is very sensitive to layer ordering. | 2238 | this usage is very sensitive to layer ordering. |
| 2239 | Explicit assignments should be avoided as they cannot adequately represent multiple | 2239 | Explicit assignments should be avoided as they cannot adequately represent multiple |
| 2240 | <filename>.bbappend</filename> files.</para> | 2240 | <filename>.bbappend</filename> files.</para> |
| 2241 | </glossdef> | 2241 | </glossdef> |
| 2242 | </glossentry> | 2242 | </glossentry> |
| @@ -2245,11 +2245,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2245 | <glossdef> | 2245 | <glossdef> |
| 2246 | <para>The version of the recipe. | 2246 | <para>The version of the recipe. |
| 2247 | The version is normally extracted from the recipe filename. | 2247 | The version is normally extracted from the recipe filename. |
| 2248 | For example, if the recipe is named | 2248 | For example, if the recipe is named |
| 2249 | <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename> | 2249 | <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename> |
| 2250 | will be "2.0.1". | 2250 | will be "2.0.1". |
| 2251 | <filename>PV</filename> is generally not overridden within | 2251 | <filename>PV</filename> is generally not overridden within |
| 2252 | a recipe unless it is building an unstable (i.e. development) version from a source code repository | 2252 | a recipe unless it is building an unstable (i.e. development) version from a source code repository |
| 2253 | (e.g. Git or Subversion). | 2253 | (e.g. Git or Subversion). |
| 2254 | </para> | 2254 | </para> |
| 2255 | </glossdef> | 2255 | </glossdef> |
| @@ -2258,9 +2258,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2258 | <glossentry id='var-PE'><glossterm>PE</glossterm> | 2258 | <glossentry id='var-PE'><glossterm>PE</glossterm> |
| 2259 | <glossdef> | 2259 | <glossdef> |
| 2260 | <para> | 2260 | <para> |
| 2261 | the epoch of the recipe. | 2261 | the epoch of the recipe. |
| 2262 | The default value is "0". | 2262 | The default value is "0". |
| 2263 | The field is used to make upgrades possible when the versioning scheme changes in | 2263 | The field is used to make upgrades possible when the versioning scheme changes in |
| 2264 | some backwards incompatible way. | 2264 | some backwards incompatible way. |
| 2265 | </para> | 2265 | </para> |
| 2266 | </glossdef> | 2266 | </glossdef> |
| @@ -2270,10 +2270,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2270 | <glossdef> | 2270 | <glossdef> |
| 2271 | <para> | 2271 | <para> |
| 2272 | If multiple recipes provide an item, this variable | 2272 | If multiple recipes provide an item, this variable |
| 2273 | determines which recipe should be given preference. | 2273 | determines which recipe should be given preference. |
| 2274 | The variable must always be suffixed with the name of the | 2274 | The variable must always be suffixed with the name of the |
| 2275 | provided item, and should be set to the | 2275 | provided item, and should be set to the |
| 2276 | <filename>PN</filename> of the recipe | 2276 | <filename>PN</filename> of the recipe |
| 2277 | to which you want to give precedence. | 2277 | to which you want to give precedence. |
| 2278 | Here is an example: | 2278 | Here is an example: |
| 2279 | <literallayout class='monospaced'> | 2279 | <literallayout class='monospaced'> |
| @@ -2288,17 +2288,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2288 | <para> | 2288 | <para> |
| 2289 | If there are multiple versions of recipes available, this | 2289 | If there are multiple versions of recipes available, this |
| 2290 | variable determines which recipe should be given preference. | 2290 | variable determines which recipe should be given preference. |
| 2291 | The variable must always be suffixed with the <filename>PN</filename> | 2291 | The variable must always be suffixed with the <filename>PN</filename> |
| 2292 | for which to select, and should be set to the | 2292 | for which to select, and should be set to the |
| 2293 | <filename>PV</filename> to which you want to give precedence. | 2293 | <filename>PV</filename> to which you want to give precedence. |
| 2294 | You can use the "<filename>%</filename>" character as a wildcard | 2294 | You can use the "<filename>%</filename>" character as a wildcard |
| 2295 | to match any number of characters, which can be useful when | 2295 | to match any number of characters, which can be useful when |
| 2296 | specifying versions that contain long revision number that could | 2296 | specifying versions that contain long revision number that could |
| 2297 | potentially change. | 2297 | potentially change. |
| 2298 | Here are two examples: | 2298 | Here are two examples: |
| 2299 | <literallayout class='monospaced'> | 2299 | <literallayout class='monospaced'> |
| 2300 | PREFERRED_VERSION_python = "2.6.6" | 2300 | PREFERRED_VERSION_python = "2.6.6" |
| 2301 | PREFERRED_VERSION_linux-yocto = "3.0+git%" | 2301 | PREFERRED_VERSION_linux-yocto = "3.0+git%" |
| 2302 | </literallayout> | 2302 | </literallayout> |
| 2303 | </para> | 2303 | </para> |
| 2304 | </glossdef> | 2304 | </glossdef> |
| @@ -2317,7 +2317,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2317 | Note that the package will not be installed if the conflicting packages are not | 2317 | Note that the package will not be installed if the conflicting packages are not |
| 2318 | first removed.</para> | 2318 | first removed.</para> |
| 2319 | <para> | 2319 | <para> |
| 2320 | Like all package-controlling variables, you must always use them in | 2320 | Like all package-controlling variables, you must always use them in |
| 2321 | conjunction with a package name override. | 2321 | conjunction with a package name override. |
| 2322 | Here is an example: | 2322 | Here is an example: |
| 2323 | <literallayout class='monospaced'> | 2323 | <literallayout class='monospaced'> |
| @@ -2330,59 +2330,59 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2330 | <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> | 2330 | <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> |
| 2331 | <glossdef> | 2331 | <glossdef> |
| 2332 | <para> | 2332 | <para> |
| 2333 | Lists a package's run-time dependencies (i.e. other packages) | 2333 | Lists a package's run-time dependencies (i.e. other packages) |
| 2334 | that must be installed for the package to be built. | 2334 | that must be installed for the package to be built. |
| 2335 | In other words, in order for the package to be built and | 2335 | In other words, in order for the package to be built and |
| 2336 | run correctly, it depends on the listed packages. | 2336 | run correctly, it depends on the listed packages. |
| 2337 | If a package in this list cannot be found, it is probable | 2337 | If a package in this list cannot be found, it is probable |
| 2338 | that a dependency error would occur before the build. | 2338 | that a dependency error would occur before the build. |
| 2339 | </para> | 2339 | </para> |
| 2340 | 2340 | ||
| 2341 | <para> | 2341 | <para> |
| 2342 | The names of the variables you list with | 2342 | The names of the variables you list with |
| 2343 | <filename>RDEPENDS</filename> must be the names of other | 2343 | <filename>RDEPENDS</filename> must be the names of other |
| 2344 | packages as listed in the | 2344 | packages as listed in the |
| 2345 | <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> | 2345 | <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> |
| 2346 | variable. | 2346 | variable. |
| 2347 | You should not list recipe names (<filename>PN</filename>). | 2347 | You should not list recipe names (<filename>PN</filename>). |
| 2348 | </para> | 2348 | </para> |
| 2349 | 2349 | ||
| 2350 | <para> | 2350 | <para> |
| 2351 | Because the <filename>RDEPENDS</filename> variable applies | 2351 | Because the <filename>RDEPENDS</filename> variable applies |
| 2352 | to packages being built, you should | 2352 | to packages being built, you should |
| 2353 | always attach a package name to the variable to specify the | 2353 | always attach a package name to the variable to specify the |
| 2354 | particular run-time package that has the dependency. | 2354 | particular run-time package that has the dependency. |
| 2355 | For example, suppose you are building a development package | 2355 | For example, suppose you are building a development package |
| 2356 | that depends on the <filename>perl</filename> package. | 2356 | that depends on the <filename>perl</filename> package. |
| 2357 | In this case, you would use the following | 2357 | In this case, you would use the following |
| 2358 | <filename>RDEPENDS</filename> statement: | 2358 | <filename>RDEPENDS</filename> statement: |
| 2359 | <literallayout class='monospaced'> | 2359 | <literallayout class='monospaced'> |
| 2360 | RDEPENDS_${PN}-dev += "perl" | 2360 | RDEPENDS_${PN}-dev += "perl" |
| 2361 | </literallayout> | 2361 | </literallayout> |
| 2362 | In the example, the package name | 2362 | In the example, the package name |
| 2363 | (<filename>${PN}-dev</filename>) must appear as it would | 2363 | (<filename>${PN}-dev</filename>) must appear as it would |
| 2364 | in the | 2364 | in the |
| 2365 | <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> | 2365 | <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> |
| 2366 | namespace before any renaming of the output package by | 2366 | namespace before any renaming of the output package by |
| 2367 | classes like <filename>debian.bbclass</filename>. | 2367 | classes like <filename>debian.bbclass</filename>. |
| 2368 | </para> | 2368 | </para> |
| 2369 | 2369 | ||
| 2370 | <para> | 2370 | <para> |
| 2371 | In many cases you do not need to explicitly add dependencies | 2371 | In many cases you do not need to explicitly add dependencies |
| 2372 | to <filename>RDEPENDS</filename> since some automatic | 2372 | to <filename>RDEPENDS</filename> since some automatic |
| 2373 | handling occurs: | 2373 | handling occurs: |
| 2374 | <itemizedlist> | 2374 | <itemizedlist> |
| 2375 | <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If | 2375 | <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If |
| 2376 | a run-time package contains a shared library | 2376 | a run-time package contains a shared library |
| 2377 | (<filename>.so</filename>), the build | 2377 | (<filename>.so</filename>), the build |
| 2378 | processes the library in order to determine other | 2378 | processes the library in order to determine other |
| 2379 | libraries to which it is dynamically linked. | 2379 | libraries to which it is dynamically linked. |
| 2380 | The build process adds these libraries to | 2380 | The build process adds these libraries to |
| 2381 | <filename>RDEPENDS</filename> when creating the run-time | 2381 | <filename>RDEPENDS</filename> when creating the run-time |
| 2382 | package.</para></listitem> | 2382 | package.</para></listitem> |
| 2383 | <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If | 2383 | <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If |
| 2384 | the package ships a <filename>pkg-config</filename> | 2384 | the package ships a <filename>pkg-config</filename> |
| 2385 | information file, the build process uses this file | 2385 | information file, the build process uses this file |
| 2386 | to add items to the <filename>RDEPENDS</filename> | 2386 | to add items to the <filename>RDEPENDS</filename> |
| 2387 | variable to create the run-time packages. | 2387 | variable to create the run-time packages. |
| 2388 | </para></listitem> | 2388 | </para></listitem> |
| @@ -2394,11 +2394,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2394 | <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm> | 2394 | <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm> |
| 2395 | <glossdef> | 2395 | <glossdef> |
| 2396 | <para> | 2396 | <para> |
| 2397 | A list of packages that extend the usability of a package being | 2397 | A list of packages that extend the usability of a package being |
| 2398 | built. | 2398 | built. |
| 2399 | The package being built does not depend on this list of packages in | 2399 | The package being built does not depend on this list of packages in |
| 2400 | order to successfully build, but needs them for the extended usability. | 2400 | order to successfully build, but needs them for the extended usability. |
| 2401 | To specify runtime dependencies for packages, see the | 2401 | To specify runtime dependencies for packages, see the |
| 2402 | <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variable. | 2402 | <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variable. |
| 2403 | </para> | 2403 | </para> |
| 2404 | <para> | 2404 | <para> |
| @@ -2409,8 +2409,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2409 | process continues without an error. | 2409 | process continues without an error. |
| 2410 | </para> | 2410 | </para> |
| 2411 | <para> | 2411 | <para> |
| 2412 | Because the <filename>RRECOMMENDS</filename> variable applies to packages | 2412 | Because the <filename>RRECOMMENDS</filename> variable applies to packages |
| 2413 | being built, you should | 2413 | being built, you should |
| 2414 | always attach an override to the variable to specify the particular package | 2414 | always attach an override to the variable to specify the particular package |
| 2415 | whose usability is being extended. | 2415 | whose usability is being extended. |
| 2416 | For example, suppose you are building a development package that is extended | 2416 | For example, suppose you are building a development package that is extended |
| @@ -2419,9 +2419,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2419 | <literallayout class='monospaced'> | 2419 | <literallayout class='monospaced'> |
| 2420 | RRECOMMENDS_${PN}-dev += "<wireless_package_name>" | 2420 | RRECOMMENDS_${PN}-dev += "<wireless_package_name>" |
| 2421 | </literallayout> | 2421 | </literallayout> |
| 2422 | In the example, the package name (<filename>${PN}-dev</filename>) must | 2422 | In the example, the package name (<filename>${PN}-dev</filename>) must |
| 2423 | appear as it would in the | 2423 | appear as it would in the |
| 2424 | <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any | 2424 | <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any |
| 2425 | renaming of the output package by classes like <filename>debian.bbclass</filename>. | 2425 | renaming of the output package by classes like <filename>debian.bbclass</filename>. |
| 2426 | </para> | 2426 | </para> |
| 2427 | </glossdef> | 2427 | </glossdef> |
| @@ -2442,22 +2442,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2442 | <para> | 2442 | <para> |
| 2443 | The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> | 2443 | The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> |
| 2444 | where unpacked package source code resides. | 2444 | where unpacked package source code resides. |
| 2445 | This location is within the working directory | 2445 | This location is within the working directory |
| 2446 | (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>), which | 2446 | (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>), which |
| 2447 | is not static. | 2447 | is not static. |
| 2448 | The unpacked source location depends on the package name | 2448 | The unpacked source location depends on the package name |
| 2449 | (<filename><link linkend='var-PN'>PN</link></filename>) and | 2449 | (<filename><link linkend='var-PN'>PN</link></filename>) and |
| 2450 | package version (<filename><link linkend='var-PV'>PV</link></filename>) as | 2450 | package version (<filename><link linkend='var-PV'>PV</link></filename>) as |
| 2451 | follows: | 2451 | follows: |
| 2452 | <literallayout class='monospaced'> | 2452 | <literallayout class='monospaced'> |
| 2453 | ${WORKDIR}/${PN}-${PV} | 2453 | ${WORKDIR}/${PN}-${PV} |
| 2454 | </literallayout> | 2454 | </literallayout> |
| 2455 | As an example, assume a | 2455 | As an example, assume a |
| 2456 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level | 2456 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level |
| 2457 | folder named <filename>poky</filename> | 2457 | folder named <filename>poky</filename> |
| 2458 | and a default <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> | 2458 | and a default <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> |
| 2459 | at <filename>poky/build</filename>. | 2459 | at <filename>poky/build</filename>. |
| 2460 | In this case, the working directory the build system uses to build | 2460 | In this case, the working directory the build system uses to build |
| 2461 | the <filename>db</filename> package is the following: | 2461 | the <filename>db</filename> package is the following: |
| 2462 | <literallayout class='monospaced'> | 2462 | <literallayout class='monospaced'> |
| 2463 | ~/poky/build/tmp/work/qemux86-poky-linux/db-5.1.19-r3/db-5.1.19 | 2463 | ~/poky/build/tmp/work/qemux86-poky-linux/db-5.1.19-r3/db-5.1.19 |
| @@ -2468,9 +2468,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2468 | 2468 | ||
| 2469 | <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm> | 2469 | <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm> |
| 2470 | <glossdef> | 2470 | <glossdef> |
| 2471 | <para>Equivalent to | 2471 | <para>Equivalent to |
| 2472 | <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>. | 2472 | <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>. |
| 2473 | However, this variable applies to the SDK generated from an image using | 2473 | However, this variable applies to the SDK generated from an image using |
| 2474 | <filename>bitbake -c populate_sdk imagename</filename>). | 2474 | <filename>bitbake -c populate_sdk imagename</filename>). |
| 2475 | </para> | 2475 | </para> |
| 2476 | </glossdef> | 2476 | </glossdef> |
| @@ -2486,10 +2486,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2486 | <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm> | 2486 | <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm> |
| 2487 | <glossdef> | 2487 | <glossdef> |
| 2488 | <para> | 2488 | <para> |
| 2489 | The variable takes the value of | 2489 | The variable takes the value of |
| 2490 | <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename> | 2490 | <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename> |
| 2491 | unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1". | 2491 | unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1". |
| 2492 | In this case the value of | 2492 | In this case the value of |
| 2493 | <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used. | 2493 | <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used. |
| 2494 | </para> | 2494 | </para> |
| 2495 | </glossdef> | 2495 | </glossdef> |
| @@ -2498,7 +2498,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2498 | 2498 | ||
| 2499 | <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm> | 2499 | <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm> |
| 2500 | <glossdef> | 2500 | <glossdef> |
| 2501 | <para>The speed and device for the serial port used to attach the serial console. | 2501 | <para>The speed and device for the serial port used to attach the serial console. |
| 2502 | This variable is given to the kernel as the "console" | 2502 | This variable is given to the kernel as the "console" |
| 2503 | parameter and after booting occurs <filename>getty</filename> is started on that port | 2503 | parameter and after booting occurs <filename>getty</filename> is started on that port |
| 2504 | so remote login is possible.</para> | 2504 | so remote login is possible.</para> |
| @@ -2508,7 +2508,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2508 | <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm> | 2508 | <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm> |
| 2509 | <glossdef> | 2509 | <glossdef> |
| 2510 | <para> | 2510 | <para> |
| 2511 | Specifies the endian byte order of the target system. | 2511 | Specifies the endian byte order of the target system. |
| 2512 | The value should be either "le" for little-endian or "be" for big-endian. | 2512 | The value should be either "le" for little-endian or "be" for big-endian. |
| 2513 | </para> | 2513 | </para> |
| 2514 | </glossdef> | 2514 | </glossdef> |
| @@ -2526,7 +2526,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2526 | <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm> | 2526 | <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm> |
| 2527 | <glossdef> | 2527 | <glossdef> |
| 2528 | <para> | 2528 | <para> |
| 2529 | A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the | 2529 | A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the |
| 2530 | OpenEmbedded build system to create variants of recipes or packages. | 2530 | OpenEmbedded build system to create variants of recipes or packages. |
| 2531 | The list specifies the prefixes to strip off during certain circumstances | 2531 | The list specifies the prefixes to strip off during certain circumstances |
| 2532 | such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable. | 2532 | such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable. |
| @@ -2539,7 +2539,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2539 | <para>The list of source files - local or remote. | 2539 | <para>The list of source files - local or remote. |
| 2540 | This variable tells the OpenEmbedded build system which bits to pull | 2540 | This variable tells the OpenEmbedded build system which bits to pull |
| 2541 | in for the build and how to pull them in. | 2541 | in for the build and how to pull them in. |
| 2542 | For example, if the recipe only needs to fetch a tarball from the | 2542 | For example, if the recipe only needs to fetch a tarball from the |
| 2543 | internet, the recipe uses a single <filename>SRC_URI</filename> entry. | 2543 | internet, the recipe uses a single <filename>SRC_URI</filename> entry. |
| 2544 | On the other hand, if the recipe needs to fetch a tarball, apply | 2544 | On the other hand, if the recipe needs to fetch a tarball, apply |
| 2545 | two patches, and include a custom file, the recipe would include four | 2545 | two patches, and include a custom file, the recipe would include four |
| @@ -2547,120 +2547,120 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2547 | <para>The following list explains the available URI protocols: | 2547 | <para>The following list explains the available URI protocols: |
| 2548 | <itemizedlist> | 2548 | <itemizedlist> |
| 2549 | <listitem><para><emphasis><filename>file://</filename> -</emphasis> Fetches files, which is usually | 2549 | <listitem><para><emphasis><filename>file://</filename> -</emphasis> Fetches files, which is usually |
| 2550 | a file shipped with the metadata, from the local machine. | 2550 | a file shipped with the metadata, from the local machine. |
| 2551 | The path is relative to the | 2551 | The path is relative to the |
| 2552 | <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> | 2552 | <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> |
| 2553 | variable. | 2553 | variable. |
| 2554 | Thus, the build system searches, in order, from the following directories, | 2554 | Thus, the build system searches, in order, from the following directories, |
| 2555 | which are assumed to be a subdirectories of the directory in which the | 2555 | which are assumed to be a subdirectories of the directory in which the |
| 2556 | recipe file resides: | 2556 | recipe file resides: |
| 2557 | <itemizedlist> | 2557 | <itemizedlist> |
| 2558 | <listitem><para><emphasis><filename>${PN}</filename> -</emphasis> The recipe name | 2558 | <listitem><para><emphasis><filename>${PN}</filename> -</emphasis> The recipe name |
| 2559 | with any special suffix or prefix, if applicable. | 2559 | with any special suffix or prefix, if applicable. |
| 2560 | For example, using <filename>bash</filename> to build for the native | 2560 | For example, using <filename>bash</filename> to build for the native |
| 2561 | machine, <filename>PN</filename> is <filename>bash-native</filename>. | 2561 | machine, <filename>PN</filename> is <filename>bash-native</filename>. |
| 2562 | Using <filename>bash</filename> to build for the target and for Multilib, | 2562 | Using <filename>bash</filename> to build for the target and for Multilib, |
| 2563 | <filename>PN</filename> would be <filename>bash</filename> and | 2563 | <filename>PN</filename> would be <filename>bash</filename> and |
| 2564 | <filename>lib64-bash</filename>, respectively. | 2564 | <filename>lib64-bash</filename>, respectively. |
| 2565 | </para></listitem> | 2565 | </para></listitem> |
| 2566 | <listitem><para><emphasis><filename>${PF}</filename> - </emphasis> | 2566 | <listitem><para><emphasis><filename>${PF}</filename> - </emphasis> |
| 2567 | <filename>${PN}-${EXTENDPE}${PV}-${PR}</filename>. | 2567 | <filename>${PN}-${EXTENDPE}${PV}-${PR}</filename>. |
| 2568 | The recipe name including all version and revision numbers | 2568 | The recipe name including all version and revision numbers |
| 2569 | (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and | 2569 | (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and |
| 2570 | <filename>bash-4.2-r1/</filename>).</para></listitem> | 2570 | <filename>bash-4.2-r1/</filename>).</para></listitem> |
| 2571 | <listitem><para><emphasis><filename>${P}</filename> -</emphasis> | 2571 | <listitem><para><emphasis><filename>${P}</filename> -</emphasis> |
| 2572 | <filename>${PN}-${PV}</filename>. | 2572 | <filename>${PN}-${PV}</filename>. |
| 2573 | The recipe name and version (i.e. <filename>bash-4.2</filename>). | 2573 | The recipe name and version (i.e. <filename>bash-4.2</filename>). |
| 2574 | </para></listitem> | 2574 | </para></listitem> |
| 2575 | <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis> The | 2575 | <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis> The |
| 2576 | base recipe name without any special suffix or version numbers. | 2576 | base recipe name without any special suffix or version numbers. |
| 2577 | </para></listitem> | 2577 | </para></listitem> |
| 2578 | <listitem><para><emphasis><filename>${BP}</filename> -</emphasis> | 2578 | <listitem><para><emphasis><filename>${BP}</filename> -</emphasis> |
| 2579 | <filename>${BPN}-${PV}</filename>. | 2579 | <filename>${BPN}-${PV}</filename>. |
| 2580 | The base recipe name and version but without any special | 2580 | The base recipe name and version but without any special |
| 2581 | package name suffix.</para></listitem> | 2581 | package name suffix.</para></listitem> |
| 2582 | <listitem><para><emphasis>Files -</emphasis> Files beneath the directory in which the recipe | 2582 | <listitem><para><emphasis>Files -</emphasis> Files beneath the directory in which the recipe |
| 2583 | resides.</para></listitem> | 2583 | resides.</para></listitem> |
| 2584 | <listitem><para><emphasis>Directory -</emphasis> The directory itself in which the recipe | 2584 | <listitem><para><emphasis>Directory -</emphasis> The directory itself in which the recipe |
| 2585 | resides.</para></listitem> | 2585 | resides.</para></listitem> |
| 2586 | </itemizedlist></para></listitem> | 2586 | </itemizedlist></para></listitem> |
| 2587 | <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a | 2587 | <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a |
| 2588 | Bazaar revision control repository.</para></listitem> | 2588 | Bazaar revision control repository.</para></listitem> |
| 2589 | <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a | 2589 | <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a |
| 2590 | Git revision control repository.</para></listitem> | 2590 | Git revision control repository.</para></listitem> |
| 2591 | <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from | 2591 | <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from |
| 2592 | an OSC (OpenSuse Build service) revision control repository.</para></listitem> | 2592 | an OSC (OpenSuse Build service) revision control repository.</para></listitem> |
| 2593 | <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from | 2593 | <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from |
| 2594 | a repo (Git) repository.</para></listitem> | 2594 | a repo (Git) repository.</para></listitem> |
| 2595 | <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from | 2595 | <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from |
| 2596 | an SVK revision control repository.</para></listitem> | 2596 | an SVK revision control repository.</para></listitem> |
| 2597 | <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from | 2597 | <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from |
| 2598 | the Internet using <filename>http</filename>.</para></listitem> | 2598 | the Internet using <filename>http</filename>.</para></listitem> |
| 2599 | <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files | 2599 | <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files |
| 2600 | from the Internet using <filename>https</filename>.</para></listitem> | 2600 | from the Internet using <filename>https</filename>.</para></listitem> |
| 2601 | <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files | 2601 | <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files |
| 2602 | from the Internet using <filename>ftp</filename>.</para></listitem> | 2602 | from the Internet using <filename>ftp</filename>.</para></listitem> |
| 2603 | <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from | 2603 | <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from |
| 2604 | a CVS revision control repository.</para></listitem> | 2604 | a CVS revision control repository.</para></listitem> |
| 2605 | <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from | 2605 | <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from |
| 2606 | a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem> | 2606 | a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem> |
| 2607 | <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from | 2607 | <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from |
| 2608 | a Perforce (<filename>p4</filename>) revision control repository.</para></listitem> | 2608 | a Perforce (<filename>p4</filename>) revision control repository.</para></listitem> |
| 2609 | <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from | 2609 | <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from |
| 2610 | a secure shell.</para></listitem> | 2610 | a secure shell.</para></listitem> |
| 2611 | <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from | 2611 | <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from |
| 2612 | a Subversion (<filename>svn</filename>) revision control repository.</para></listitem> | 2612 | a Subversion (<filename>svn</filename>) revision control repository.</para></listitem> |
| 2613 | </itemizedlist> | 2613 | </itemizedlist> |
| 2614 | </para> | 2614 | </para> |
| 2615 | <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist. | 2615 | <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist. |
| 2616 | Here are standard options: | 2616 | Here are standard options: |
| 2617 | <itemizedlist> | 2617 | <itemizedlist> |
| 2618 | <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply | 2618 | <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply |
| 2619 | the patch or not. | 2619 | the patch or not. |
| 2620 | The default action is to apply the patch.</para></listitem> | 2620 | The default action is to apply the patch.</para></listitem> |
| 2621 | <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which | 2621 | <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which |
| 2622 | striplevel to use when applying the patch. | 2622 | striplevel to use when applying the patch. |
| 2623 | The default level is 1.</para></listitem> | 2623 | The default level is 1.</para></listitem> |
| 2624 | </itemizedlist> | 2624 | </itemizedlist> |
| 2625 | </para> | 2625 | </para> |
| 2626 | <para>Here are options specific to recipes building code from a revision control system: | 2626 | <para>Here are options specific to recipes building code from a revision control system: |
| 2627 | <itemizedlist> | 2627 | <itemizedlist> |
| 2628 | <listitem><para><emphasis><filename>mindate</filename> -</emphasis> Only applies | 2628 | <listitem><para><emphasis><filename>mindate</filename> -</emphasis> Only applies |
| 2629 | the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link> | 2629 | the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link> |
| 2630 | is equal to or greater than <filename>mindate</filename>.</para></listitem> | 2630 | is equal to or greater than <filename>mindate</filename>.</para></listitem> |
| 2631 | <listitem><para><emphasis><filename>maxdate</filename> -</emphasis> Only applies | 2631 | <listitem><para><emphasis><filename>maxdate</filename> -</emphasis> Only applies |
| 2632 | the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link> | 2632 | the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link> |
| 2633 | is not later than <filename>mindate</filename>.</para></listitem> | 2633 | is not later than <filename>mindate</filename>.</para></listitem> |
| 2634 | <listitem><para><emphasis><filename>minrev</filename> -</emphasis> Only applies | 2634 | <listitem><para><emphasis><filename>minrev</filename> -</emphasis> Only applies |
| 2635 | the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> | 2635 | the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> |
| 2636 | is equal to or greater than <filename>minrev</filename>.</para></listitem> | 2636 | is equal to or greater than <filename>minrev</filename>.</para></listitem> |
| 2637 | <listitem><para><emphasis><filename>maxrev</filename> -</emphasis> Only applies | 2637 | <listitem><para><emphasis><filename>maxrev</filename> -</emphasis> Only applies |
| 2638 | the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> | 2638 | the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> |
| 2639 | is not later than <filename>maxrev</filename>.</para></listitem> | 2639 | is not later than <filename>maxrev</filename>.</para></listitem> |
| 2640 | <listitem><para><emphasis><filename>rev</filename> -</emphasis> Only applies the | 2640 | <listitem><para><emphasis><filename>rev</filename> -</emphasis> Only applies the |
| 2641 | patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> | 2641 | patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> |
| 2642 | is equal to <filename>rev</filename>.</para></listitem> | 2642 | is equal to <filename>rev</filename>.</para></listitem> |
| 2643 | <listitem><para><emphasis><filename>notrev</filename> -</emphasis> Only applies | 2643 | <listitem><para><emphasis><filename>notrev</filename> -</emphasis> Only applies |
| 2644 | the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> | 2644 | the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> |
| 2645 | is not equal to <filename>rev</filename>.</para></listitem> | 2645 | is not equal to <filename>rev</filename>.</para></listitem> |
| 2646 | </itemizedlist> | 2646 | </itemizedlist> |
| 2647 | </para> | 2647 | </para> |
| 2648 | <para>Here are some additional options worth mentioning: | 2648 | <para>Here are some additional options worth mentioning: |
| 2649 | <itemizedlist> | 2649 | <itemizedlist> |
| 2650 | <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls | 2650 | <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls |
| 2651 | whether or not to unpack the file if it is an archive. | 2651 | whether or not to unpack the file if it is an archive. |
| 2652 | The default action is to upack the file.</para></listitem> | 2652 | The default action is to upack the file.</para></listitem> |
| 2653 | <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file | 2653 | <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file |
| 2654 | (or extracts its contents) into the specified | 2654 | (or extracts its contents) into the specified |
| 2655 | subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>. | 2655 | subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>. |
| 2656 | This option is useful for unusual tarballs or other archives that | 2656 | This option is useful for unusual tarballs or other archives that |
| 2657 | don't have their files already in a subdirectory within the archive. | 2657 | don't have their files already in a subdirectory within the archive. |
| 2658 | </para></listitem> | 2658 | </para></listitem> |
| 2659 | <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a | 2659 | <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a |
| 2660 | name to be used for association with <filename>SRC_URI</filename> checksums | 2660 | name to be used for association with <filename>SRC_URI</filename> checksums |
| 2661 | when you have more than one file specified in <filename>SRC_URI</filename>. | 2661 | when you have more than one file specified in <filename>SRC_URI</filename>. |
| 2662 | </para></listitem> | 2662 | </para></listitem> |
| 2663 | <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies | 2663 | <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies |
| 2664 | the filename used when storing the downloaded file.</para></listitem> | 2664 | the filename used when storing the downloaded file.</para></listitem> |
| 2665 | </itemizedlist> | 2665 | </itemizedlist> |
| 2666 | </para> | 2666 | </para> |
| @@ -2671,11 +2671,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2671 | <glossdef> | 2671 | <glossdef> |
| 2672 | <para></para> | 2672 | <para></para> |
| 2673 | <para> | 2673 | <para> |
| 2674 | By default, the OpenEmbedded build system automatically detects whether | 2674 | By default, the OpenEmbedded build system automatically detects whether |
| 2675 | <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> | 2675 | <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> |
| 2676 | contains files that are machine-specific. | 2676 | contains files that are machine-specific. |
| 2677 | If so, the build system automatically changes | 2677 | If so, the build system automatically changes |
| 2678 | <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>. | 2678 | <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>. |
| 2679 | Setting this variable to "0" disables this behavior. | 2679 | Setting this variable to "0" disables this behavior. |
| 2680 | </para> | 2680 | </para> |
| 2681 | </glossdef> | 2681 | </glossdef> |
| @@ -2695,7 +2695,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2695 | <para> | 2695 | <para> |
| 2696 | The revision of the source code used to build the package. | 2696 | The revision of the source code used to build the package. |
| 2697 | This variable applies to Subversion, Git, Mercurial and Bazaar | 2697 | This variable applies to Subversion, Git, Mercurial and Bazaar |
| 2698 | only. | 2698 | only. |
| 2699 | Note that if you wish to build a fixed revision and you wish | 2699 | Note that if you wish to build a fixed revision and you wish |
| 2700 | to avoid performing a query on the remote repository every time | 2700 | to avoid performing a query on the remote repository every time |
| 2701 | BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a | 2701 | BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a |
| @@ -2713,30 +2713,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2713 | <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm> | 2713 | <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm> |
| 2714 | <glossdef> | 2714 | <glossdef> |
| 2715 | <para> | 2715 | <para> |
| 2716 | Configures the OpenEmbedded build system to search other | 2716 | Configures the OpenEmbedded build system to search other |
| 2717 | mirror locations for prebuilt cache data objects before | 2717 | mirror locations for prebuilt cache data objects before |
| 2718 | building out the data. | 2718 | building out the data. |
| 2719 | This variable works like fetcher | 2719 | This variable works like fetcher |
| 2720 | <filename>MIRRORS</filename>/<filename>PREMIRRORS</filename> | 2720 | <filename>MIRRORS</filename>/<filename>PREMIRRORS</filename> |
| 2721 | and points to the cache locations to check for the shared | 2721 | and points to the cache locations to check for the shared |
| 2722 | objects. | 2722 | objects. |
| 2723 | </para> | 2723 | </para> |
| 2724 | 2724 | ||
| 2725 | <para> | 2725 | <para> |
| 2726 | You can specify a filesystem directory or a remote URL such | 2726 | You can specify a filesystem directory or a remote URL such |
| 2727 | as HTTP or FTP. | 2727 | as HTTP or FTP. |
| 2728 | The locations you specify need to contain the shared state | 2728 | The locations you specify need to contain the shared state |
| 2729 | cache (sstate-cache) results from previous builds. | 2729 | cache (sstate-cache) results from previous builds. |
| 2730 | The sstate-cache you point to can also be from builds on | 2730 | The sstate-cache you point to can also be from builds on |
| 2731 | other machines. | 2731 | other machines. |
| 2732 | </para> | 2732 | </para> |
| 2733 | 2733 | ||
| 2734 | <para> | 2734 | <para> |
| 2735 | If a mirror uses the same structure as | 2735 | If a mirror uses the same structure as |
| 2736 | <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, | 2736 | <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, |
| 2737 | you need to add | 2737 | you need to add |
| 2738 | "PATH" at the end as shown in the examples below. | 2738 | "PATH" at the end as shown in the examples below. |
| 2739 | The build system substitues the correct path within the | 2739 | The build system substitues the correct path within the |
| 2740 | directory structure. | 2740 | directory structure. |
| 2741 | <literallayout class='monospaced'> | 2741 | <literallayout class='monospaced'> |
| 2742 | SSTATE_MIRRORS ?= "\ | 2742 | SSTATE_MIRRORS ?= "\ |
| @@ -2761,14 +2761,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2761 | <para> | 2761 | <para> |
| 2762 | Specifies the base path used to create recipe stamp files. | 2762 | Specifies the base path used to create recipe stamp files. |
| 2763 | The path to an actual stamp file is constructed by evaluating this | 2763 | The path to an actual stamp file is constructed by evaluating this |
| 2764 | string and then appending additional information. | 2764 | string and then appending additional information. |
| 2765 | Currently, the default assignment for <filename>STAMP</filename> | 2765 | Currently, the default assignment for <filename>STAMP</filename> |
| 2766 | as set in the <filename>meta/conf/bitbake.conf</filename> file | 2766 | as set in the <filename>meta/conf/bitbake.conf</filename> file |
| 2767 | is: | 2767 | is: |
| 2768 | <literallayout class='monospaced'> | 2768 | <literallayout class='monospaced'> |
| 2769 | STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}-${EXTENDPE}${PV}-${PR}" | 2769 | STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}-${EXTENDPE}${PV}-${PR}" |
| 2770 | </literallayout> | 2770 | </literallayout> |
| 2771 | See <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, | 2771 | See <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, |
| 2772 | <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, | 2772 | <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, |
| 2773 | <link linkend='var-PN'><filename>PN</filename></link>, | 2773 | <link linkend='var-PN'><filename>PN</filename></link>, |
| 2774 | <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>, | 2774 | <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>, |
| @@ -2781,12 +2781,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2781 | 2781 | ||
| 2782 | <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm> | 2782 | <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm> |
| 2783 | <glossdef> | 2783 | <glossdef> |
| 2784 | <para>The short (72 characters or less) summary of the binary package for packaging | 2784 | <para>The short (72 characters or less) summary of the binary package for packaging |
| 2785 | systems such as <filename>opkg</filename>, <filename>rpm</filename> or | 2785 | systems such as <filename>opkg</filename>, <filename>rpm</filename> or |
| 2786 | <filename>dpkg</filename>. | 2786 | <filename>dpkg</filename>. |
| 2787 | By default, <filename>SUMMARY</filename> is used to define | 2787 | By default, <filename>SUMMARY</filename> is used to define |
| 2788 | the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link> | 2788 | the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link> |
| 2789 | variable if <filename>DESCRIPTION</filename> is not set | 2789 | variable if <filename>DESCRIPTION</filename> is not set |
| 2790 | in the recipe. | 2790 | in the recipe. |
| 2791 | </para> | 2791 | </para> |
| 2792 | </glossdef> | 2792 | </glossdef> |
| @@ -2798,18 +2798,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2798 | 2798 | ||
| 2799 | <glossentry id='var-T'><glossterm>T</glossterm> | 2799 | <glossentry id='var-T'><glossterm>T</glossterm> |
| 2800 | <glossdef> | 2800 | <glossdef> |
| 2801 | <para>This variable points to a directory were Bitbake places temporary | 2801 | <para>This variable points to a directory were Bitbake places temporary |
| 2802 | files when building a particular package. | 2802 | files when building a particular package. |
| 2803 | It is typically set as follows: | 2803 | It is typically set as follows: |
| 2804 | <literallayout class='monospaced'> | 2804 | <literallayout class='monospaced'> |
| 2805 | T = ${WORKDIR}/temp | 2805 | T = ${WORKDIR}/temp |
| 2806 | </literallayout> | 2806 | </literallayout> |
| 2807 | The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> | 2807 | The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> |
| 2808 | is the directory into which Bitbake unpacks and builds the package. | 2808 | is the directory into which Bitbake unpacks and builds the package. |
| 2809 | The default <filename>bitbake.conf</filename> file sets this variable.</para> | 2809 | The default <filename>bitbake.conf</filename> file sets this variable.</para> |
| 2810 | <para>The <filename>T</filename> variable is not to be confused with | 2810 | <para>The <filename>T</filename> variable is not to be confused with |
| 2811 | the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable, | 2811 | the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable, |
| 2812 | which points to the root of the directory tree where Bitbake | 2812 | which points to the root of the directory tree where Bitbake |
| 2813 | places the output of an entire build. | 2813 | places the output of an entire build. |
| 2814 | </para> | 2814 | </para> |
| 2815 | </glossdef> | 2815 | </glossdef> |
| @@ -2817,7 +2817,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2817 | 2817 | ||
| 2818 | <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm> | 2818 | <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm> |
| 2819 | <glossdef> | 2819 | <glossdef> |
| 2820 | <para>The architecture of the device being built. | 2820 | <para>The architecture of the device being built. |
| 2821 | While a number of values are possible, the OpenEmbedded build system primarily supports | 2821 | While a number of values are possible, the OpenEmbedded build system primarily supports |
| 2822 | <filename>arm</filename> and <filename>i586</filename>.</para> | 2822 | <filename>arm</filename> and <filename>i586</filename>.</para> |
| 2823 | </glossdef> | 2823 | </glossdef> |
| @@ -2826,8 +2826,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2826 | <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm> | 2826 | <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm> |
| 2827 | <glossdef> | 2827 | <glossdef> |
| 2828 | <para> | 2828 | <para> |
| 2829 | Flags passed to the C compiler for the target system. | 2829 | Flags passed to the C compiler for the target system. |
| 2830 | This variable evaluates to the same as | 2830 | This variable evaluates to the same as |
| 2831 | <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>. | 2831 | <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>. |
| 2832 | </para> | 2832 | </para> |
| 2833 | </glossdef> | 2833 | </glossdef> |
| @@ -2836,7 +2836,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2836 | 2836 | ||
| 2837 | <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm> | 2837 | <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm> |
| 2838 | <glossdef> | 2838 | <glossdef> |
| 2839 | <para>Specifies the method for handling FPU code. | 2839 | <para>Specifies the method for handling FPU code. |
| 2840 | For FPU-less targets, which include most ARM CPUs, the variable must be | 2840 | For FPU-less targets, which include most ARM CPUs, the variable must be |
| 2841 | set to "soft". | 2841 | set to "soft". |
| 2842 | If not, the kernel emulation gets used, which results in a performance penalty.</para> | 2842 | If not, the kernel emulation gets used, which results in a performance penalty.</para> |
| @@ -2845,9 +2845,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2845 | 2845 | ||
| 2846 | <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm> | 2846 | <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm> |
| 2847 | <glossdef> | 2847 | <glossdef> |
| 2848 | <para>Specifies the target's operating system. | 2848 | <para>Specifies the target's operating system. |
| 2849 | The variable can be set to "linux" for <filename>eglibc</filename>-based systems and | 2849 | The variable can be set to "linux" for <filename>eglibc</filename>-based systems and |
| 2850 | to "linux-uclibc" for <filename>uclibc</filename>. | 2850 | to "linux-uclibc" for <filename>uclibc</filename>. |
| 2851 | For ARM/EABI targets, there are also "linux-gnueabi" and | 2851 | For ARM/EABI targets, there are also "linux-gnueabi" and |
| 2852 | "linux-uclibc-gnueabi" values possible.</para> | 2852 | "linux-uclibc-gnueabi" values possible.</para> |
| 2853 | </glossdef> | 2853 | </glossdef> |
| @@ -2864,7 +2864,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2864 | <para> | 2864 | <para> |
| 2865 | You can select <filename>eglibc</filename> or <filename>uclibc</filename>. | 2865 | You can select <filename>eglibc</filename> or <filename>uclibc</filename>. |
| 2866 | <note> | 2866 | <note> |
| 2867 | This release of the Yocto Project does not support the | 2867 | This release of the Yocto Project does not support the |
| 2868 | <filename>glibc</filename> implementation of <filename>libc</filename>. | 2868 | <filename>glibc</filename> implementation of <filename>libc</filename>. |
| 2869 | </note> | 2869 | </note> |
| 2870 | </para> | 2870 | </para> |
| @@ -2874,7 +2874,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2874 | <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm> | 2874 | <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm> |
| 2875 | <glossdef> | 2875 | <glossdef> |
| 2876 | <para> | 2876 | <para> |
| 2877 | The toolchain selector. | 2877 | The toolchain selector. |
| 2878 | This variable replaces <filename>POKYMODE</filename>, which is no longer | 2878 | This variable replaces <filename>POKYMODE</filename>, which is no longer |
| 2879 | supported. | 2879 | supported. |
| 2880 | </para> | 2880 | </para> |
| @@ -2882,39 +2882,39 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2882 | The <filename>TCMODE</filename> variable selects the external toolchain | 2882 | The <filename>TCMODE</filename> variable selects the external toolchain |
| 2883 | built using the OpenEmbedded build system or a few supported combinations of | 2883 | built using the OpenEmbedded build system or a few supported combinations of |
| 2884 | the upstream GCC or CodeSourcery Labs toolchain. | 2884 | the upstream GCC or CodeSourcery Labs toolchain. |
| 2885 | The variable identifies the <filename>tcmode-*</filename> files used in | 2885 | The variable identifies the <filename>tcmode-*</filename> files used in |
| 2886 | the <filename>meta/conf/distro/include</filename> directory, which is found in the | 2886 | the <filename>meta/conf/distro/include</filename> directory, which is found in the |
| 2887 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 2887 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 2888 | </para> | 2888 | </para> |
| 2889 | <para> | 2889 | <para> |
| 2890 | By default, <filename>TCMODE</filename> is set to "default", which | 2890 | By default, <filename>TCMODE</filename> is set to "default", which |
| 2891 | chooses the <filename>tcmode-default.inc</filename> file. | 2891 | chooses the <filename>tcmode-default.inc</filename> file. |
| 2892 | The variable is similar to | 2892 | The variable is similar to |
| 2893 | <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls | 2893 | <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls |
| 2894 | the variant of the GNU standard C library (<filename>libc</filename>) | 2894 | the variant of the GNU standard C library (<filename>libc</filename>) |
| 2895 | used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>. | 2895 | used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>. |
| 2896 | </para> | 2896 | </para> |
| 2897 | </glossdef> | 2897 | </glossdef> |
| 2898 | </glossentry> | 2898 | </glossentry> |
| 2899 | 2899 | ||
| 2900 | <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm> | 2900 | <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm> |
| 2901 | <glossdef> | 2901 | <glossdef> |
| 2902 | <para> | 2902 | <para> |
| 2903 | This variable is the temporary directory the OpenEmbedded build system | 2903 | This variable is the temporary directory the OpenEmbedded build system |
| 2904 | uses when it does its work building images. | 2904 | uses when it does its work building images. |
| 2905 | By default, the <filename>TMPDIR</filename> variable is named | 2905 | By default, the <filename>TMPDIR</filename> variable is named |
| 2906 | <filename>tmp</filename> within the | 2906 | <filename>tmp</filename> within the |
| 2907 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | 2907 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
| 2908 | </para> | 2908 | </para> |
| 2909 | 2909 | ||
| 2910 | <para> | 2910 | <para> |
| 2911 | If you want to establish this directory in a location other than the | 2911 | If you want to establish this directory in a location other than the |
| 2912 | default, you can uncomment the following statement in the | 2912 | default, you can uncomment the following statement in the |
| 2913 | <filename>conf/local.conf</filename> file in the | 2913 | <filename>conf/local.conf</filename> file in the |
| 2914 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: | 2914 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: |
| 2915 | <literallayout class='monospaced'> | 2915 | <literallayout class='monospaced'> |
| 2916 | #TMPDIR = "${TOPDIR}/tmp" | 2916 | #TMPDIR = "${TOPDIR}/tmp" |
| 2917 | </literallayout> | 2917 | </literallayout> |
| 2918 | </para> | 2918 | </para> |
| 2919 | </glossdef> | 2919 | </glossdef> |
| 2920 | </glossentry> | 2920 | </glossentry> |
| @@ -2922,10 +2922,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2922 | <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm> | 2922 | <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm> |
| 2923 | <glossdef> | 2923 | <glossdef> |
| 2924 | <para> | 2924 | <para> |
| 2925 | This variable is the | 2925 | This variable is the |
| 2926 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | 2926 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
| 2927 | BitBake automatically sets this variable. | 2927 | BitBake automatically sets this variable. |
| 2928 | The OpenEmbedded build system uses the Build Directory when building images. | 2928 | The OpenEmbedded build system uses the Build Directory when building images. |
| 2929 | </para> | 2929 | </para> |
| 2930 | </glossdef> | 2930 | </glossdef> |
| 2931 | </glossentry> | 2931 | </glossentry> |
| @@ -2943,7 +2943,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2943 | <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm> | 2943 | <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm> |
| 2944 | <glossdef> | 2944 | <glossdef> |
| 2945 | <para> | 2945 | <para> |
| 2946 | The pathname of the working directory in which the OpenEmbedded build system | 2946 | The pathname of the working directory in which the OpenEmbedded build system |
| 2947 | builds a recipe. | 2947 | builds a recipe. |
| 2948 | This directory is located within the | 2948 | This directory is located within the |
| 2949 | <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes | 2949 | <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes |
| @@ -2964,17 +2964,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2964 | </para> | 2964 | </para> |
| 2965 | 2965 | ||
| 2966 | <para> | 2966 | <para> |
| 2967 | For packages that are not dependent on a particular machine, | 2967 | For packages that are not dependent on a particular machine, |
| 2968 | <filename>WORKDIR</filename> is defined as follows: | 2968 | <filename>WORKDIR</filename> is defined as follows: |
| 2969 | <literallayout class='monospaced'> | 2969 | <literallayout class='monospaced'> |
| 2970 | ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} | 2970 | ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} |
| 2971 | </literallayout> | 2971 | </literallayout> |
| 2972 | As an example, assume a | 2972 | As an example, assume a |
| 2973 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level | 2973 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level |
| 2974 | folder name <filename>poky</filename> and a default | 2974 | folder name <filename>poky</filename> and a default |
| 2975 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> | 2975 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> |
| 2976 | at <filename>poky/build</filename>. | 2976 | at <filename>poky/build</filename>. |
| 2977 | In this case, the working directory the build system uses to build | 2977 | In this case, the working directory the build system uses to build |
| 2978 | the <filename>v86d</filename> package is the following: | 2978 | the <filename>v86d</filename> package is the following: |
| 2979 | <literallayout class='monospaced'> | 2979 | <literallayout class='monospaced'> |
| 2980 | ~/poky/build/tmp/work/qemux86-poky-linux/v86d-01.9-r0 | 2980 | ~/poky/build/tmp/work/qemux86-poky-linux/v86d-01.9-r0 |
| @@ -2987,11 +2987,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 2987 | <literallayout class='monospaced'> | 2987 | <literallayout class='monospaced'> |
| 2988 | ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} | 2988 | ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} |
| 2989 | </literallayout> | 2989 | </literallayout> |
| 2990 | As an example, again assume a Source Directory top-level folder | 2990 | As an example, again assume a Source Directory top-level folder |
| 2991 | named <filename>poky</filename> and a default Build Directory | 2991 | named <filename>poky</filename> and a default Build Directory |
| 2992 | at <filename>poky/build</filename>. | 2992 | at <filename>poky/build</filename>. |
| 2993 | In this case, the working directory the build system uses to build | 2993 | In this case, the working directory the build system uses to build |
| 2994 | the <filename>acl</filename> recipe, which is being built for a | 2994 | the <filename>acl</filename> recipe, which is being built for a |
| 2995 | MIPS-based device, is the following: | 2995 | MIPS-based device, is the following: |
| 2996 | <literallayout class='monospaced'> | 2996 | <literallayout class='monospaced'> |
| 2997 | ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 | 2997 | ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 |
| @@ -3013,6 +3013,6 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | |||
| 3013 | 3013 | ||
| 3014 | </glossary> | 3014 | </glossary> |
| 3015 | </chapter> | 3015 | </chapter> |
| 3016 | <!-- | 3016 | <!-- |
| 3017 | vim: expandtab tw=80 ts=4 | 3017 | vim: expandtab tw=80 ts=4 |
| 3018 | --> | 3018 | --> |
diff --git a/documentation/poky-ref-manual/ref-varlocality.xml b/documentation/poky-ref-manual/ref-varlocality.xml index a9db35fe4b..ae8f75c2f5 100644 --- a/documentation/poky-ref-manual/ref-varlocality.xml +++ b/documentation/poky-ref-manual/ref-varlocality.xml | |||
| @@ -6,10 +6,10 @@ | |||
| 6 | <title>Variable Context</title> | 6 | <title>Variable Context</title> |
| 7 | 7 | ||
| 8 | <para> | 8 | <para> |
| 9 | While most variables can be used in almost any context such as | 9 | While most variables can be used in almost any context such as |
| 10 | <filename>.conf</filename>, <filename>.bbclass</filename>, | 10 | <filename>.conf</filename>, <filename>.bbclass</filename>, |
| 11 | <filename>.inc</filename>, and <filename>.bb</filename> files, | 11 | <filename>.inc</filename>, and <filename>.bb</filename> files, |
| 12 | some variables are often associated with a particular locality or context. | 12 | some variables are often associated with a particular locality or context. |
| 13 | This chapter describes some common associations. | 13 | This chapter describes some common associations. |
| 14 | </para> | 14 | </para> |
| 15 | 15 | ||
| @@ -80,7 +80,7 @@ | |||
| 80 | <title>Local</title> | 80 | <title>Local</title> |
| 81 | 81 | ||
| 82 | <para> | 82 | <para> |
| 83 | This section lists variables whose context is the local configuration through the | 83 | This section lists variables whose context is the local configuration through the |
| 84 | <filename>local.conf</filename> file. | 84 | <filename>local.conf</filename> file. |
| 85 | <itemizedlist> | 85 | <itemizedlist> |
| 86 | <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename> | 86 | <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename> |
| @@ -188,6 +188,6 @@ | |||
| 188 | </section> | 188 | </section> |
| 189 | </section> | 189 | </section> |
| 190 | </chapter> | 190 | </chapter> |
| 191 | <!-- | 191 | <!-- |
| 192 | vim: expandtab tw=80 ts=4 spell spelllang=en_gb | 192 | vim: expandtab tw=80 ts=4 spell spelllang=en_gb |
| 193 | --> | 193 | --> |
diff --git a/documentation/poky-ref-manual/resources.xml b/documentation/poky-ref-manual/resources.xml index 8c47b18ec7..a6916064f6 100644 --- a/documentation/poky-ref-manual/resources.xml +++ b/documentation/poky-ref-manual/resources.xml | |||
| @@ -9,7 +9,7 @@ | |||
| 9 | <title>Introduction</title> | 9 | <title>Introduction</title> |
| 10 | <para> | 10 | <para> |
| 11 | The Yocto Project team is happy for people to experiment with the Yocto Project. | 11 | The Yocto Project team is happy for people to experiment with the Yocto Project. |
| 12 | A number of places exist to find help if you run into difficulties or find bugs. | 12 | A number of places exist to find help if you run into difficulties or find bugs. |
| 13 | To find out how to download source code, | 13 | To find out how to download source code, |
| 14 | see the "<ulink url='&YOCTO_DOCS_DEV_URL;#local-yp-release'>Yocto Project Release</ulink>" | 14 | see the "<ulink url='&YOCTO_DOCS_DEV_URL;#local-yp-release'>Yocto Project Release</ulink>" |
| 15 | list item in the Yocto Project Development Manual. | 15 | list item in the Yocto Project Development Manual. |
| @@ -20,7 +20,7 @@ | |||
| 20 | <title>Tracking Bugs</title> | 20 | <title>Tracking Bugs</title> |
| 21 | 21 | ||
| 22 | <para> | 22 | <para> |
| 23 | If you find problems with the Yocto Project, you should report them using the | 23 | If you find problems with the Yocto Project, you should report them using the |
| 24 | Bugzilla application at <ulink url='&YOCTO_BUGZILLA_URL;'></ulink>. | 24 | Bugzilla application at <ulink url='&YOCTO_BUGZILLA_URL;'></ulink>. |
| 25 | </para> | 25 | </para> |
| 26 | </section> | 26 | </section> |
| @@ -75,18 +75,18 @@ | |||
| 75 | The company where the Yocto Project build system Poky was first developed. | 75 | The company where the Yocto Project build system Poky was first developed. |
| 76 | OpenedHand has since been acquired by Intel Corporation.</para></listitem> --> | 76 | OpenedHand has since been acquired by Intel Corporation.</para></listitem> --> |
| 77 | <listitem><para><emphasis><ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis> | 77 | <listitem><para><emphasis><ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis> |
| 78 | The company who acquired OpenedHand in 2008 and began development on the | 78 | The company who acquired OpenedHand in 2008 and began development on the |
| 79 | Yocto Project.</para></listitem> | 79 | Yocto Project.</para></listitem> |
| 80 | <listitem><para><emphasis><ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> | 80 | <listitem><para><emphasis><ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> |
| 81 | The upstream, generic, embedded distribution used as the basis for the build system in the | 81 | The upstream, generic, embedded distribution used as the basis for the build system in the |
| 82 | Yocto Project. | 82 | Yocto Project. |
| 83 | Poky derives from and contributes back to the OpenEmbedded project.</para></listitem> | 83 | Poky derives from and contributes back to the OpenEmbedded project.</para></listitem> |
| 84 | <listitem><para><emphasis><ulink url='http://developer.berlios.de/projects/bitbake/'> | 84 | <listitem><para><emphasis><ulink url='http://developer.berlios.de/projects/bitbake/'> |
| 85 | BitBake</ulink>:</emphasis> The tool used to process metadata.</para></listitem> | 85 | BitBake</ulink>:</emphasis> The tool used to process metadata.</para></listitem> |
| 86 | <listitem><para><emphasis>BitBake User Manual:</emphasis> | 86 | <listitem><para><emphasis>BitBake User Manual:</emphasis> |
| 87 | A comprehensive guide to the BitBake tool. | 87 | A comprehensive guide to the BitBake tool. |
| 88 | You can find the BitBake User Manual in the <filename>bitbake/doc/manual</filename> | 88 | You can find the BitBake User Manual in the <filename>bitbake/doc/manual</filename> |
| 89 | directory, which is found in the | 89 | directory, which is found in the |
| 90 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 90 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 91 | </para></listitem> | 91 | </para></listitem> |
| 92 | <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Index.html'>QEMU</ulink>: | 92 | <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Index.html'>QEMU</ulink>: |
| @@ -100,7 +100,7 @@ | |||
| 100 | 100 | ||
| 101 | <para> | 101 | <para> |
| 102 | The Yocto Project gladly accepts contributions. | 102 | The Yocto Project gladly accepts contributions. |
| 103 | You can submit changes to the project either by creating and sending pull requests, | 103 | You can submit changes to the project either by creating and sending pull requests, |
| 104 | or by submitting patches through email. | 104 | or by submitting patches through email. |
| 105 | For information on how to do both, see the | 105 | For information on how to do both, see the |
| 106 | "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>" | 106 | "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>" |
| @@ -109,6 +109,6 @@ | |||
| 109 | </section> | 109 | </section> |
| 110 | 110 | ||
| 111 | </chapter> | 111 | </chapter> |
| 112 | <!-- | 112 | <!-- |
| 113 | vim: expandtab tw=80 ts=4 | 113 | vim: expandtab tw=80 ts=4 |
| 114 | --> | 114 | --> |
diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml index 042a96ed87..72689a0e22 100644 --- a/documentation/poky-ref-manual/technical-details.xml +++ b/documentation/poky-ref-manual/technical-details.xml | |||
| @@ -6,7 +6,7 @@ | |||
| 6 | <title>Technical Details</title> | 6 | <title>Technical Details</title> |
| 7 | 7 | ||
| 8 | <para> | 8 | <para> |
| 9 | This chapter provides technical details for various parts of the Yocto Project. | 9 | This chapter provides technical details for various parts of the Yocto Project. |
| 10 | Currently, topics include Yocto Project components and shared state (sstate) cache. | 10 | Currently, topics include Yocto Project components and shared state (sstate) cache. |
| 11 | </para> | 11 | </para> |
| 12 | 12 | ||
| @@ -14,21 +14,21 @@ | |||
| 14 | <title>Yocto Project Components</title> | 14 | <title>Yocto Project Components</title> |
| 15 | 15 | ||
| 16 | <para> | 16 | <para> |
| 17 | The BitBake task executor together with various types of configuration files form the | 17 | The BitBake task executor together with various types of configuration files form the |
| 18 | OpenEmbedded Core. | 18 | OpenEmbedded Core. |
| 19 | This section overviews the BitBake task executor and the | 19 | This section overviews the BitBake task executor and the |
| 20 | configuration files by describing what they are used for and how they interact. | 20 | configuration files by describing what they are used for and how they interact. |
| 21 | </para> | 21 | </para> |
| 22 | 22 | ||
| 23 | <para> | 23 | <para> |
| 24 | BitBake handles the parsing and execution of the data files. | 24 | BitBake handles the parsing and execution of the data files. |
| 25 | The data itself is of various types: | 25 | The data itself is of various types: |
| 26 | <itemizedlist> | 26 | <itemizedlist> |
| 27 | <listitem><para><emphasis>Recipes:</emphasis> Provides details about particular | 27 | <listitem><para><emphasis>Recipes:</emphasis> Provides details about particular |
| 28 | pieces of software</para></listitem> | 28 | pieces of software</para></listitem> |
| 29 | <listitem><para><emphasis>Class Data:</emphasis> An abstraction of common build | 29 | <listitem><para><emphasis>Class Data:</emphasis> An abstraction of common build |
| 30 | information (e.g. how to build a Linux kernel).</para></listitem> | 30 | information (e.g. how to build a Linux kernel).</para></listitem> |
| 31 | <listitem><para><emphasis>Configuration Data:</emphasis> Defines machine-specific settings, | 31 | <listitem><para><emphasis>Configuration Data:</emphasis> Defines machine-specific settings, |
| 32 | policy decisions, etc. | 32 | policy decisions, etc. |
| 33 | Configuration data acts as the glue to bind everything together.</para></listitem> | 33 | Configuration data acts as the glue to bind everything together.</para></listitem> |
| 34 | </itemizedlist> | 34 | </itemizedlist> |
| @@ -37,17 +37,17 @@ | |||
| 37 | section in the Yocto Project Development Manual. | 37 | section in the Yocto Project Development Manual. |
| 38 | </para> | 38 | </para> |
| 39 | 39 | ||
| 40 | <para> | 40 | <para> |
| 41 | BitBake knows how to combine multiple data sources together and refers to each data source | 41 | BitBake knows how to combine multiple data sources together and refers to each data source |
| 42 | as a layer. | 42 | as a layer. |
| 43 | For information on layers, see the | 43 | For information on layers, see the |
| 44 | "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and | 44 | "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and |
| 45 | Creating Layers</ulink>" section of the Yocto Project Development Manual. | 45 | Creating Layers</ulink>" section of the Yocto Project Development Manual. |
| 46 | </para> | 46 | </para> |
| 47 | 47 | ||
| 48 | <para> | 48 | <para> |
| 49 | Following are some brief details on these core components. | 49 | Following are some brief details on these core components. |
| 50 | For more detailed information on these components see the | 50 | For more detailed information on these components see the |
| 51 | "<link linkend='ref-structure'>Directory Structure</link>" chapter. | 51 | "<link linkend='ref-structure'>Directory Structure</link>" chapter. |
| 52 | </para> | 52 | </para> |
| 53 | 53 | ||
| @@ -57,7 +57,7 @@ | |||
| 57 | <para> | 57 | <para> |
| 58 | BitBake is the tool at the heart of the OpenEmbedded build system and is responsible | 58 | BitBake is the tool at the heart of the OpenEmbedded build system and is responsible |
| 59 | for parsing the metadata, generating a list of tasks from it, | 59 | for parsing the metadata, generating a list of tasks from it, |
| 60 | and then executing those tasks. | 60 | and then executing those tasks. |
| 61 | To see a list of the options BitBake supports, use the following help command: | 61 | To see a list of the options BitBake supports, use the following help command: |
| 62 | <literallayout class='monospaced'> | 62 | <literallayout class='monospaced'> |
| 63 | $ bitbake --help | 63 | $ bitbake --help |
| @@ -66,8 +66,8 @@ | |||
| 66 | 66 | ||
| 67 | <para> | 67 | <para> |
| 68 | The most common usage for BitBake is <filename>bitbake <packagename></filename>, where | 68 | The most common usage for BitBake is <filename>bitbake <packagename></filename>, where |
| 69 | <filename>packagename</filename> is the name of the package you want to build | 69 | <filename>packagename</filename> is the name of the package you want to build |
| 70 | (referred to as the "target" in this manual). | 70 | (referred to as the "target" in this manual). |
| 71 | The target often equates to the first part of a <filename>.bb</filename> filename. | 71 | The target often equates to the first part of a <filename>.bb</filename> filename. |
| 72 | So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you | 72 | So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you |
| 73 | might type the following: | 73 | might type the following: |
| @@ -76,15 +76,15 @@ | |||
| 76 | </literallayout> | 76 | </literallayout> |
| 77 | Several different versions of <filename>matchbox-desktop</filename> might exist. | 77 | Several different versions of <filename>matchbox-desktop</filename> might exist. |
| 78 | BitBake chooses the one selected by the distribution configuration. | 78 | BitBake chooses the one selected by the distribution configuration. |
| 79 | You can get more details about how BitBake chooses between different | 79 | You can get more details about how BitBake chooses between different |
| 80 | target versions and providers in the | 80 | target versions and providers in the |
| 81 | "<link linkend='ref-bitbake-providers'>Preferences and Providers</link>" section. | 81 | "<link linkend='ref-bitbake-providers'>Preferences and Providers</link>" section. |
| 82 | </para> | 82 | </para> |
| 83 | 83 | ||
| 84 | <para> | 84 | <para> |
| 85 | BitBake also tries to execute any dependent tasks first. | 85 | BitBake also tries to execute any dependent tasks first. |
| 86 | So for example, before building <filename>matchbox-desktop</filename>, BitBake | 86 | So for example, before building <filename>matchbox-desktop</filename>, BitBake |
| 87 | would build a cross compiler and <filename>eglibc</filename> if they had not already | 87 | would build a cross compiler and <filename>eglibc</filename> if they had not already |
| 88 | been built. | 88 | been built. |
| 89 | <note>This release of the Yocto Project does not support the <filename>glibc</filename> | 89 | <note>This release of the Yocto Project does not support the <filename>glibc</filename> |
| 90 | GNU version of the Unix standard C library. By default, the OpenEmbedded build system | 90 | GNU version of the Unix standard C library. By default, the OpenEmbedded build system |
| @@ -92,12 +92,12 @@ | |||
| 92 | </para> | 92 | </para> |
| 93 | 93 | ||
| 94 | <para> | 94 | <para> |
| 95 | A useful BitBake option to consider is the <filename>-k</filename> or | 95 | A useful BitBake option to consider is the <filename>-k</filename> or |
| 96 | <filename>--continue</filename> option. | 96 | <filename>--continue</filename> option. |
| 97 | This option instructs BitBake to try and continue processing the job as much | 97 | This option instructs BitBake to try and continue processing the job as much |
| 98 | as possible even after encountering an error. | 98 | as possible even after encountering an error. |
| 99 | When an error occurs, the target that | 99 | When an error occurs, the target that |
| 100 | failed and those that depend on it cannot be remade. | 100 | failed and those that depend on it cannot be remade. |
| 101 | However, when you use this option other dependencies can still be processed. | 101 | However, when you use this option other dependencies can still be processed. |
| 102 | </para> | 102 | </para> |
| 103 | </section> | 103 | </section> |
| @@ -106,17 +106,17 @@ | |||
| 106 | <title>Metadata (Recipes)</title> | 106 | <title>Metadata (Recipes)</title> |
| 107 | 107 | ||
| 108 | <para> | 108 | <para> |
| 109 | The <filename>.bb</filename> files are usually referred to as "recipes." | 109 | The <filename>.bb</filename> files are usually referred to as "recipes." |
| 110 | In general, a recipe contains information about a single piece of software. | 110 | In general, a recipe contains information about a single piece of software. |
| 111 | The information includes the location from which to download the source patches | 111 | The information includes the location from which to download the source patches |
| 112 | (if any are needed), which special configuration options to apply, | 112 | (if any are needed), which special configuration options to apply, |
| 113 | how to compile the source files, and how to package the compiled output. | 113 | how to compile the source files, and how to package the compiled output. |
| 114 | </para> | 114 | </para> |
| 115 | 115 | ||
| 116 | <para> | 116 | <para> |
| 117 | The term "package" can also be used to describe recipes. | 117 | The term "package" can also be used to describe recipes. |
| 118 | However, since the same word is used for the packaged output from the OpenEmbedded | 118 | However, since the same word is used for the packaged output from the OpenEmbedded |
| 119 | build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files), | 119 | build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files), |
| 120 | this document avoids using the term "package" when referring to recipes. | 120 | this document avoids using the term "package" when referring to recipes. |
| 121 | </para> | 121 | </para> |
| 122 | </section> | 122 | </section> |
| @@ -126,7 +126,7 @@ | |||
| 126 | 126 | ||
| 127 | <para> | 127 | <para> |
| 128 | Class files (<filename>.bbclass</filename>) contain information that is useful to share | 128 | Class files (<filename>.bbclass</filename>) contain information that is useful to share |
| 129 | between metadata files. | 129 | between metadata files. |
| 130 | An example is the Autotools class, which contains | 130 | An example is the Autotools class, which contains |
| 131 | common settings for any application that Autotools uses. | 131 | common settings for any application that Autotools uses. |
| 132 | The "<link linkend='ref-classes'>Classes</link>" chapter provides details | 132 | The "<link linkend='ref-classes'>Classes</link>" chapter provides details |
| @@ -139,8 +139,8 @@ | |||
| 139 | 139 | ||
| 140 | <para> | 140 | <para> |
| 141 | The configuration files (<filename>.conf</filename>) define various configuration variables | 141 | The configuration files (<filename>.conf</filename>) define various configuration variables |
| 142 | that govern the OpenEmbedded build process. | 142 | that govern the OpenEmbedded build process. |
| 143 | These files fall into several areas that define machine configuration options, | 143 | These files fall into several areas that define machine configuration options, |
| 144 | distribution configuration options, compiler tuning options, general common configuration | 144 | distribution configuration options, compiler tuning options, general common configuration |
| 145 | options and user configuration options (<filename>local.conf</filename>, which is found | 145 | options and user configuration options (<filename>local.conf</filename>, which is found |
| 146 | in the <ulink url='build-directory'>Build Directory</ulink>). | 146 | in the <ulink url='build-directory'>Build Directory</ulink>). |
| @@ -152,19 +152,19 @@ | |||
| 152 | <title>Shared State Cache</title> | 152 | <title>Shared State Cache</title> |
| 153 | 153 | ||
| 154 | <para> | 154 | <para> |
| 155 | By design, the OpenEmbedded build system builds everything from scratch unless | 155 | By design, the OpenEmbedded build system builds everything from scratch unless |
| 156 | BitBake can determine that parts don't need to be rebuilt. | 156 | BitBake can determine that parts don't need to be rebuilt. |
| 157 | Fundamentally, building from scratch is attractive as it means all parts are | 157 | Fundamentally, building from scratch is attractive as it means all parts are |
| 158 | built fresh and there is no possibility of stale data causing problems. | 158 | built fresh and there is no possibility of stale data causing problems. |
| 159 | When developers hit problems, they typically default back to building from scratch | 159 | When developers hit problems, they typically default back to building from scratch |
| 160 | so they know the state of things from the start. | 160 | so they know the state of things from the start. |
| 161 | </para> | 161 | </para> |
| 162 | 162 | ||
| 163 | <para> | 163 | <para> |
| 164 | Building an image from scratch is both an advantage and a disadvantage to the process. | 164 | Building an image from scratch is both an advantage and a disadvantage to the process. |
| 165 | As mentioned in the previous paragraph, building from scratch ensures that | 165 | As mentioned in the previous paragraph, building from scratch ensures that |
| 166 | everything is current and starts from a known state. | 166 | everything is current and starts from a known state. |
| 167 | However, building from scratch also takes much longer as it generally means | 167 | However, building from scratch also takes much longer as it generally means |
| 168 | rebuilding things that don't necessarily need rebuilt. | 168 | rebuilding things that don't necessarily need rebuilt. |
| 169 | </para> | 169 | </para> |
| 170 | 170 | ||
| @@ -181,15 +181,15 @@ | |||
| 181 | </para> | 181 | </para> |
| 182 | 182 | ||
| 183 | <para> | 183 | <para> |
| 184 | For the first question, the build system detects changes in the "inputs" to a given task by | 184 | For the first question, the build system detects changes in the "inputs" to a given task by |
| 185 | creating a checksum (or signature) of the task's inputs. | 185 | creating a checksum (or signature) of the task's inputs. |
| 186 | If the checksum changes, the system assumes the inputs have changed and the task needs to be | 186 | If the checksum changes, the system assumes the inputs have changed and the task needs to be |
| 187 | rerun. | 187 | rerun. |
| 188 | For the second question, the shared state (sstate) code tracks which tasks add which output | 188 | For the second question, the shared state (sstate) code tracks which tasks add which output |
| 189 | to the build process. | 189 | to the build process. |
| 190 | This means the output from a given task can be removed, upgraded or otherwise manipulated. | 190 | This means the output from a given task can be removed, upgraded or otherwise manipulated. |
| 191 | The third question is partly addressed by the solution for the second question | 191 | The third question is partly addressed by the solution for the second question |
| 192 | assuming the build system can fetch the sstate objects from remote locations and | 192 | assuming the build system can fetch the sstate objects from remote locations and |
| 193 | install them if they are deemed to be valid. | 193 | install them if they are deemed to be valid. |
| 194 | </para> | 194 | </para> |
| 195 | 195 | ||
| @@ -202,18 +202,18 @@ | |||
| 202 | <title>Overall Architecture</title> | 202 | <title>Overall Architecture</title> |
| 203 | 203 | ||
| 204 | <para> | 204 | <para> |
| 205 | When determining what parts of the system need to be built, BitBake | 205 | When determining what parts of the system need to be built, BitBake |
| 206 | uses a per-task basis and does not use a per-recipe basis. | 206 | uses a per-task basis and does not use a per-recipe basis. |
| 207 | You might wonder why using a per-task basis is preferred over a per-recipe basis. | 207 | You might wonder why using a per-task basis is preferred over a per-recipe basis. |
| 208 | To help explain, consider having the IPK packaging backend enabled and then switching to DEB. | 208 | To help explain, consider having the IPK packaging backend enabled and then switching to DEB. |
| 209 | In this case, <filename>do_install</filename> and <filename>do_package</filename> | 209 | In this case, <filename>do_install</filename> and <filename>do_package</filename> |
| 210 | output are still valid. | 210 | output are still valid. |
| 211 | However, with a per-recipe approach, the build would not include the | 211 | However, with a per-recipe approach, the build would not include the |
| 212 | <filename>.deb</filename> files. | 212 | <filename>.deb</filename> files. |
| 213 | Consequently, you would have to invalidate the whole build and rerun it. | 213 | Consequently, you would have to invalidate the whole build and rerun it. |
| 214 | Rerunning everything is not the best situation. | 214 | Rerunning everything is not the best situation. |
| 215 | Also in this case, the core must be "taught" much about specific tasks. | 215 | Also in this case, the core must be "taught" much about specific tasks. |
| 216 | This methodology does not scale well and does not allow users to easily add new tasks | 216 | This methodology does not scale well and does not allow users to easily add new tasks |
| 217 | in layers or as external recipes without touching the packaged-staging core. | 217 | in layers or as external recipes without touching the packaged-staging core. |
| 218 | </para> | 218 | </para> |
| 219 | </section> | 219 | </section> |
| @@ -222,37 +222,37 @@ | |||
| 222 | <title>Checksums (Signatures)</title> | 222 | <title>Checksums (Signatures)</title> |
| 223 | 223 | ||
| 224 | <para> | 224 | <para> |
| 225 | The shared state code uses a checksum, which is a unique signature of a task's | 225 | The shared state code uses a checksum, which is a unique signature of a task's |
| 226 | inputs, to determine if a task needs to be run again. | 226 | inputs, to determine if a task needs to be run again. |
| 227 | Because it is a change in a task's inputs that triggers a rerun, the process | 227 | Because it is a change in a task's inputs that triggers a rerun, the process |
| 228 | needs to detect all the inputs to a given task. | 228 | needs to detect all the inputs to a given task. |
| 229 | For shell tasks, this turns out to be fairly easy because | 229 | For shell tasks, this turns out to be fairly easy because |
| 230 | the build process generates a "run" shell script for each task and | 230 | the build process generates a "run" shell script for each task and |
| 231 | it is possible to create a checksum that gives you a good idea of when | 231 | it is possible to create a checksum that gives you a good idea of when |
| 232 | the task's data changes. | 232 | the task's data changes. |
| 233 | </para> | 233 | </para> |
| 234 | 234 | ||
| 235 | <para> | 235 | <para> |
| 236 | To complicate the problem, there are things that should not be included in | 236 | To complicate the problem, there are things that should not be included in |
| 237 | the checksum. | 237 | the checksum. |
| 238 | First, there is the actual specific build path of a given task - | 238 | First, there is the actual specific build path of a given task - |
| 239 | the <filename>WORKDIR</filename>. | 239 | the <filename>WORKDIR</filename>. |
| 240 | It does not matter if the working directory changes because it should not | 240 | It does not matter if the working directory changes because it should not |
| 241 | affect the output for target packages. | 241 | affect the output for target packages. |
| 242 | Also, the build process has the objective of making native/cross packages relocatable. | 242 | Also, the build process has the objective of making native/cross packages relocatable. |
| 243 | The checksum therefore needs to exclude <filename>WORKDIR</filename>. | 243 | The checksum therefore needs to exclude <filename>WORKDIR</filename>. |
| 244 | The simplistic approach for excluding the working directory is to set | 244 | The simplistic approach for excluding the working directory is to set |
| 245 | <filename>WORKDIR</filename> to some fixed value and create the checksum | 245 | <filename>WORKDIR</filename> to some fixed value and create the checksum |
| 246 | for the "run" script. | 246 | for the "run" script. |
| 247 | </para> | 247 | </para> |
| 248 | 248 | ||
| 249 | <para> | 249 | <para> |
| 250 | Another problem results from the "run" scripts containing functions that | 250 | Another problem results from the "run" scripts containing functions that |
| 251 | might or might not get called. | 251 | might or might not get called. |
| 252 | The incremental build solution contains code that figures out dependencies | 252 | The incremental build solution contains code that figures out dependencies |
| 253 | between shell functions. | 253 | between shell functions. |
| 254 | This code is used to prune the "run" scripts down to the minimum set, | 254 | This code is used to prune the "run" scripts down to the minimum set, |
| 255 | thereby alleviating this problem and making the "run" scripts much more | 255 | thereby alleviating this problem and making the "run" scripts much more |
| 256 | readable as a bonus. | 256 | readable as a bonus. |
| 257 | </para> | 257 | </para> |
| 258 | 258 | ||
| @@ -260,62 +260,62 @@ | |||
| 260 | So far we have solutions for shell scripts. | 260 | So far we have solutions for shell scripts. |
| 261 | What about python tasks? | 261 | What about python tasks? |
| 262 | The same approach applies even though these tasks are more difficult. | 262 | The same approach applies even though these tasks are more difficult. |
| 263 | The process needs to figure out what variables a python function accesses | 263 | The process needs to figure out what variables a python function accesses |
| 264 | and what functions it calls. | 264 | and what functions it calls. |
| 265 | Again, the incremental build solution contains code that first figures out | 265 | Again, the incremental build solution contains code that first figures out |
| 266 | the variable and function dependencies, and then creates a checksum for the data | 266 | the variable and function dependencies, and then creates a checksum for the data |
| 267 | used as the input to the task. | 267 | used as the input to the task. |
| 268 | </para> | 268 | </para> |
| 269 | 269 | ||
| 270 | <para> | 270 | <para> |
| 271 | Like the <filename>WORKDIR</filename> case, situations exist where dependencies | 271 | Like the <filename>WORKDIR</filename> case, situations exist where dependencies |
| 272 | should be ignored. | 272 | should be ignored. |
| 273 | For these cases, you can instruct the build process to ignore a dependency | 273 | For these cases, you can instruct the build process to ignore a dependency |
| 274 | by using a line like the following: | 274 | by using a line like the following: |
| 275 | <literallayout class='monospaced'> | 275 | <literallayout class='monospaced'> |
| 276 | PACKAGE_ARCHS[vardepsexclude] = "MACHINE" | 276 | PACKAGE_ARCHS[vardepsexclude] = "MACHINE" |
| 277 | </literallayout> | 277 | </literallayout> |
| 278 | This example ensures that the <filename>PACKAGE_ARCHS</filename> variable does not | 278 | This example ensures that the <filename>PACKAGE_ARCHS</filename> variable does not |
| 279 | depend on the value of <filename>MACHINE</filename>, even if it does reference it. | 279 | depend on the value of <filename>MACHINE</filename>, even if it does reference it. |
| 280 | </para> | 280 | </para> |
| 281 | 281 | ||
| 282 | <para> | 282 | <para> |
| 283 | Equally, there are cases where we need to add dependencies BitBake is not able to find. | 283 | Equally, there are cases where we need to add dependencies BitBake is not able to find. |
| 284 | You can accomplish this by using a line like the following: | 284 | You can accomplish this by using a line like the following: |
| 285 | <literallayout class='monospaced'> | 285 | <literallayout class='monospaced'> |
| 286 | PACKAGE_ARCHS[vardeps] = "MACHINE" | 286 | PACKAGE_ARCHS[vardeps] = "MACHINE" |
| 287 | </literallayout> | 287 | </literallayout> |
| 288 | This example explicitly adds the <filename>MACHINE</filename> variable as a | 288 | This example explicitly adds the <filename>MACHINE</filename> variable as a |
| 289 | dependency for <filename>PACKAGE_ARCHS</filename>. | 289 | dependency for <filename>PACKAGE_ARCHS</filename>. |
| 290 | </para> | 290 | </para> |
| 291 | 291 | ||
| 292 | <para> | 292 | <para> |
| 293 | Consider a case with inline python, for example, where BitBake is not | 293 | Consider a case with inline python, for example, where BitBake is not |
| 294 | able to figure out dependencies. | 294 | able to figure out dependencies. |
| 295 | When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake | 295 | When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake |
| 296 | produces output when it discovers something for which it cannot figure out | 296 | produces output when it discovers something for which it cannot figure out |
| 297 | dependencies. | 297 | dependencies. |
| 298 | The Yocto Project team has currently not managed to cover those dependencies | 298 | The Yocto Project team has currently not managed to cover those dependencies |
| 299 | in detail and is aware of the need to fix this situation. | 299 | in detail and is aware of the need to fix this situation. |
| 300 | </para> | 300 | </para> |
| 301 | 301 | ||
| 302 | <para> | 302 | <para> |
| 303 | Thus far, this section has limited discussion to the direct inputs into a task. | 303 | Thus far, this section has limited discussion to the direct inputs into a task. |
| 304 | Information based on direct inputs is referred to as the "basehash" in the | 304 | Information based on direct inputs is referred to as the "basehash" in the |
| 305 | code. | 305 | code. |
| 306 | However, there is still the question of a task's indirect inputs - the | 306 | However, there is still the question of a task's indirect inputs - the |
| 307 | things that were already built and present in the Build Directory. | 307 | things that were already built and present in the Build Directory. |
| 308 | The checksum (or signature) for a particular task needs to add the hashes | 308 | The checksum (or signature) for a particular task needs to add the hashes |
| 309 | of all the tasks on which the particular task depends. | 309 | of all the tasks on which the particular task depends. |
| 310 | Choosing which dependencies to add is a policy decision. | 310 | Choosing which dependencies to add is a policy decision. |
| 311 | However, the effect is to generate a master checksum that combines the basehash | 311 | However, the effect is to generate a master checksum that combines the basehash |
| 312 | and the hashes of the task's dependencies. | 312 | and the hashes of the task's dependencies. |
| 313 | </para> | 313 | </para> |
| 314 | 314 | ||
| 315 | <para> | 315 | <para> |
| 316 | At the code level, there are a variety of ways both the basehash and the | 316 | At the code level, there are a variety of ways both the basehash and the |
| 317 | dependent task hashes can be influenced. | 317 | dependent task hashes can be influenced. |
| 318 | Within the BitBake configuration file, we can give BitBake some extra information | 318 | Within the BitBake configuration file, we can give BitBake some extra information |
| 319 | to help it construct the basehash. | 319 | to help it construct the basehash. |
| 320 | The following statements effectively result in a list of global variable | 320 | The following statements effectively result in a list of global variable |
| 321 | dependency excludes - variables never included in any checksum: | 321 | dependency excludes - variables never included in any checksum: |
| @@ -325,42 +325,42 @@ | |||
| 325 | BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER" | 325 | BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER" |
| 326 | BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET" | 326 | BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET" |
| 327 | </literallayout> | 327 | </literallayout> |
| 328 | The previous example actually excludes | 328 | The previous example actually excludes |
| 329 | <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> | 329 | <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> |
| 330 | since it is actually constructed as a path within | 330 | since it is actually constructed as a path within |
| 331 | <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on | 331 | <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on |
| 332 | the whitelist. | 332 | the whitelist. |
| 333 | </para> | 333 | </para> |
| 334 | 334 | ||
| 335 | <para> | 335 | <para> |
| 336 | The rules for deciding which hashes of dependent tasks to include through | 336 | The rules for deciding which hashes of dependent tasks to include through |
| 337 | dependency chains are more complex and are generally accomplished with a | 337 | dependency chains are more complex and are generally accomplished with a |
| 338 | python function. | 338 | python function. |
| 339 | The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples | 339 | The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples |
| 340 | of this and also illustrates how you can insert your own policy into the system | 340 | of this and also illustrates how you can insert your own policy into the system |
| 341 | if so desired. | 341 | if so desired. |
| 342 | This file defines the two basic signature generators <filename>OE-Core</filename> | 342 | This file defines the two basic signature generators <filename>OE-Core</filename> |
| 343 | uses: "OEBasic" and "OEBasicHash". | 343 | uses: "OEBasic" and "OEBasicHash". |
| 344 | By default, there is a dummy "noop" signature handler enabled in BitBake. | 344 | By default, there is a dummy "noop" signature handler enabled in BitBake. |
| 345 | This means that behavior is unchanged from previous versions. | 345 | This means that behavior is unchanged from previous versions. |
| 346 | <filename>OE-Core</filename> uses the "OEBasic" signature handler by default | 346 | <filename>OE-Core</filename> uses the "OEBasic" signature handler by default |
| 347 | through this setting in the <filename>bitbake.conf</filename> file: | 347 | through this setting in the <filename>bitbake.conf</filename> file: |
| 348 | <literallayout class='monospaced'> | 348 | <literallayout class='monospaced'> |
| 349 | BB_SIGNATURE_HANDLER ?= "OEBasic" | 349 | BB_SIGNATURE_HANDLER ?= "OEBasic" |
| 350 | </literallayout> | 350 | </literallayout> |
| 351 | The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the | 351 | The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the |
| 352 | "OEBasic" version but adds the task hash to the stamp files. | 352 | "OEBasic" version but adds the task hash to the stamp files. |
| 353 | This results in any metadata change that changes the task hash, automatically | 353 | This results in any metadata change that changes the task hash, automatically |
| 354 | causing the task to be run again. | 354 | causing the task to be run again. |
| 355 | This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link> | 355 | This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link> |
| 356 | values and changes to metadata automatically ripple across the build. | 356 | values and changes to metadata automatically ripple across the build. |
| 357 | Currently, this behavior is not the default behavior for <filename>OE-Core</filename> | 357 | Currently, this behavior is not the default behavior for <filename>OE-Core</filename> |
| 358 | but is the default in <filename>poky</filename>. | 358 | but is the default in <filename>poky</filename>. |
| 359 | </para> | 359 | </para> |
| 360 | 360 | ||
| 361 | <para> | 361 | <para> |
| 362 | It is also worth noting that the end result of these signature generators is to | 362 | It is also worth noting that the end result of these signature generators is to |
| 363 | make some dependency and hash information available to the build. | 363 | make some dependency and hash information available to the build. |
| 364 | This information includes: | 364 | This information includes: |
| 365 | <literallayout class='monospaced'> | 365 | <literallayout class='monospaced'> |
| 366 | BB_BASEHASH_task-<taskname> - the base hashes for each task in the recipe | 366 | BB_BASEHASH_task-<taskname> - the base hashes for each task in the recipe |
| @@ -375,15 +375,15 @@ | |||
| 375 | <title>Shared State</title> | 375 | <title>Shared State</title> |
| 376 | 376 | ||
| 377 | <para> | 377 | <para> |
| 378 | Checksums and dependencies, as discussed in the previous section, solve half the | 378 | Checksums and dependencies, as discussed in the previous section, solve half the |
| 379 | problem. | 379 | problem. |
| 380 | The other part of the problem is being able to use checksum information during the build | 380 | The other part of the problem is being able to use checksum information during the build |
| 381 | and being able to reuse or rebuild specific components. | 381 | and being able to reuse or rebuild specific components. |
| 382 | </para> | 382 | </para> |
| 383 | 383 | ||
| 384 | <para> | 384 | <para> |
| 385 | The shared state class (<filename>sstate.bbclass</filename>) | 385 | The shared state class (<filename>sstate.bbclass</filename>) |
| 386 | is a relatively generic implementation of how to "capture" a snapshot of a given task. | 386 | is a relatively generic implementation of how to "capture" a snapshot of a given task. |
| 387 | The idea is that the build process does not care about the source of a task's output. | 387 | The idea is that the build process does not care about the source of a task's output. |
| 388 | Output could be freshly built or it could be downloaded and unpacked from | 388 | Output could be freshly built or it could be downloaded and unpacked from |
| 389 | somewhere - the build process doesn't need to worry about its source. | 389 | somewhere - the build process doesn't need to worry about its source. |
| @@ -392,17 +392,17 @@ | |||
| 392 | <para> | 392 | <para> |
| 393 | There are two types of output, one is just about creating a directory | 393 | There are two types of output, one is just about creating a directory |
| 394 | in <filename>WORKDIR</filename>. | 394 | in <filename>WORKDIR</filename>. |
| 395 | A good example is the output of either <filename>do_install</filename> or | 395 | A good example is the output of either <filename>do_install</filename> or |
| 396 | <filename>do_package</filename>. | 396 | <filename>do_package</filename>. |
| 397 | The other type of output occurs when a set of data is merged into a shared directory | 397 | The other type of output occurs when a set of data is merged into a shared directory |
| 398 | tree such as the sysroot. | 398 | tree such as the sysroot. |
| 399 | </para> | 399 | </para> |
| 400 | 400 | ||
| 401 | <para> | 401 | <para> |
| 402 | The Yocto Project team has tried to keep the details of the implementation hidden in | 402 | The Yocto Project team has tried to keep the details of the implementation hidden in |
| 403 | <filename>sstate.bbclass</filename>. | 403 | <filename>sstate.bbclass</filename>. |
| 404 | From a user's perspective, adding shared state wrapping to a task | 404 | From a user's perspective, adding shared state wrapping to a task |
| 405 | is as simple as this <filename>do_deploy</filename> example taken from | 405 | is as simple as this <filename>do_deploy</filename> example taken from |
| 406 | <filename>do_deploy.bbclass</filename>: | 406 | <filename>do_deploy.bbclass</filename>: |
| 407 | <literallayout class='monospaced'> | 407 | <literallayout class='monospaced'> |
| 408 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" | 408 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" |
| @@ -418,13 +418,13 @@ | |||
| 418 | </literallayout> | 418 | </literallayout> |
| 419 | In the example, we add some extra flags to the task, a name field ("deploy"), an | 419 | In the example, we add some extra flags to the task, a name field ("deploy"), an |
| 420 | input directory where the task sends data, and the output | 420 | input directory where the task sends data, and the output |
| 421 | directory where the data from the task should eventually be copied. | 421 | directory where the data from the task should eventually be copied. |
| 422 | We also add a <filename>_setscene</filename> variant of the task and add the task | 422 | We also add a <filename>_setscene</filename> variant of the task and add the task |
| 423 | name to the <filename>SSTATETASKS</filename> list. | 423 | name to the <filename>SSTATETASKS</filename> list. |
| 424 | </para> | 424 | </para> |
| 425 | 425 | ||
| 426 | <para> | 426 | <para> |
| 427 | If you have a directory whose contents you need to preserve, you can do this with | 427 | If you have a directory whose contents you need to preserve, you can do this with |
| 428 | a line like the following: | 428 | a line like the following: |
| 429 | <literallayout class='monospaced'> | 429 | <literallayout class='monospaced'> |
| 430 | do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" | 430 | do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" |
| @@ -441,21 +441,21 @@ | |||
| 441 | </para> | 441 | </para> |
| 442 | 442 | ||
| 443 | <para> | 443 | <para> |
| 444 | Behind the scenes, the shared state code works by looking in | 444 | Behind the scenes, the shared state code works by looking in |
| 445 | <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and | 445 | <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and |
| 446 | <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> | 446 | <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> |
| 447 | for shared state files. | 447 | for shared state files. |
| 448 | Here is an example: | 448 | Here is an example: |
| 449 | <literallayout class='monospaced'> | 449 | <literallayout class='monospaced'> |
| 450 | SSTATE_MIRRORS ?= "\ | 450 | SSTATE_MIRRORS ?= "\ |
| 451 | file://.* http://someserver.tld/share/sstate/PATH \n \ | 451 | file://.* http://someserver.tld/share/sstate/PATH \n \ |
| 452 | file://.* file:///some/local/dir/sstate/PATH" | 452 | file://.* file:///some/local/dir/sstate/PATH" |
| 453 | </literallayout> | 453 | </literallayout> |
| 454 | <note> | 454 | <note> |
| 455 | The shared state directory (<filename>SSTATE_DIR</filename>) is | 455 | The shared state directory (<filename>SSTATE_DIR</filename>) is |
| 456 | organized into two-character subdirectories, where the subdirectory | 456 | organized into two-character subdirectories, where the subdirectory |
| 457 | names are based on the first two characters of the hash. | 457 | names are based on the first two characters of the hash. |
| 458 | If the shared state directory structure for a mirror has the | 458 | If the shared state directory structure for a mirror has the |
| 459 | same structure as <filename>SSTATE_DIR</filename>, you must | 459 | same structure as <filename>SSTATE_DIR</filename>, you must |
| 460 | specify "PATH" as part of the URI to enable the build system | 460 | specify "PATH" as part of the URI to enable the build system |
| 461 | to map to the appropriate subdirectory. | 461 | to map to the appropriate subdirectory. |
| @@ -465,8 +465,8 @@ | |||
| 465 | <para> | 465 | <para> |
| 466 | The shared state package validity can be detected just by looking at the | 466 | The shared state package validity can be detected just by looking at the |
| 467 | filename since the filename contains the task checksum (or signature) as | 467 | filename since the filename contains the task checksum (or signature) as |
| 468 | described earlier in this section. | 468 | described earlier in this section. |
| 469 | If a valid shared state package is found, the build process downloads it | 469 | If a valid shared state package is found, the build process downloads it |
| 470 | and uses it to accelerate the task. | 470 | and uses it to accelerate the task. |
| 471 | </para> | 471 | </para> |
| 472 | 472 | ||
| @@ -474,19 +474,19 @@ | |||
| 474 | The build processes uses the <filename>*_setscene</filename> tasks | 474 | The build processes uses the <filename>*_setscene</filename> tasks |
| 475 | for the task acceleration phase. | 475 | for the task acceleration phase. |
| 476 | BitBake goes through this phase before the main execution code and tries | 476 | BitBake goes through this phase before the main execution code and tries |
| 477 | to accelerate any tasks for which it can find shared state packages. | 477 | to accelerate any tasks for which it can find shared state packages. |
| 478 | If a shared state package for a task is available, the shared state | 478 | If a shared state package for a task is available, the shared state |
| 479 | package is used. | 479 | package is used. |
| 480 | This means the task and any tasks on which it is dependent are not | 480 | This means the task and any tasks on which it is dependent are not |
| 481 | executed. | 481 | executed. |
| 482 | </para> | 482 | </para> |
| 483 | 483 | ||
| 484 | <para> | 484 | <para> |
| 485 | As a real world example, the aim is when building an IPK-based image, | 485 | As a real world example, the aim is when building an IPK-based image, |
| 486 | only the <filename>do_package_write_ipk</filename> tasks would have their | 486 | only the <filename>do_package_write_ipk</filename> tasks would have their |
| 487 | shared state packages fetched and extracted. | 487 | shared state packages fetched and extracted. |
| 488 | Since the sysroot is not used, it would never get extracted. | 488 | Since the sysroot is not used, it would never get extracted. |
| 489 | This is another reason why a task-based approach is preferred over a | 489 | This is another reason why a task-based approach is preferred over a |
| 490 | recipe-based approach, which would have to install the output from every task. | 490 | recipe-based approach, which would have to install the output from every task. |
| 491 | </para> | 491 | </para> |
| 492 | </section> | 492 | </section> |
| @@ -495,9 +495,9 @@ | |||
| 495 | <title>Tips and Tricks</title> | 495 | <title>Tips and Tricks</title> |
| 496 | 496 | ||
| 497 | <para> | 497 | <para> |
| 498 | The code in the build system that supports incremental builds is not | 498 | The code in the build system that supports incremental builds is not |
| 499 | simple code. | 499 | simple code. |
| 500 | This section presents some tips and tricks that help you work around | 500 | This section presents some tips and tricks that help you work around |
| 501 | issues related to shared state code. | 501 | issues related to shared state code. |
| 502 | </para> | 502 | </para> |
| 503 | 503 | ||
| @@ -505,25 +505,25 @@ | |||
| 505 | <title>Debugging</title> | 505 | <title>Debugging</title> |
| 506 | 506 | ||
| 507 | <para> | 507 | <para> |
| 508 | When things go wrong, debugging needs to be straightforward. | 508 | When things go wrong, debugging needs to be straightforward. |
| 509 | Because of this, the Yocto Project team included strong debugging | 509 | Because of this, the Yocto Project team included strong debugging |
| 510 | tools: | 510 | tools: |
| 511 | <itemizedlist> | 511 | <itemizedlist> |
| 512 | <listitem><para>Whenever a shared state package is written out, so is a | 512 | <listitem><para>Whenever a shared state package is written out, so is a |
| 513 | corresponding <filename>.siginfo</filename> file. | 513 | corresponding <filename>.siginfo</filename> file. |
| 514 | This practice results in a pickled python database of all | 514 | This practice results in a pickled python database of all |
| 515 | the metadata that went into creating the hash for a given shared state | 515 | the metadata that went into creating the hash for a given shared state |
| 516 | package.</para></listitem> | 516 | package.</para></listitem> |
| 517 | <listitem><para>If BitBake is run with the <filename>--dump-signatures</filename> | 517 | <listitem><para>If BitBake is run with the <filename>--dump-signatures</filename> |
| 518 | (or <filename>-S</filename>) option, BitBake dumps out | 518 | (or <filename>-S</filename>) option, BitBake dumps out |
| 519 | <filename>.siginfo</filename> files in | 519 | <filename>.siginfo</filename> files in |
| 520 | the stamp directory for every task it would have executed instead of | 520 | the stamp directory for every task it would have executed instead of |
| 521 | building the specified target package.</para></listitem> | 521 | building the specified target package.</para></listitem> |
| 522 | <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that | 522 | <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that |
| 523 | can process these <filename>.siginfo</filename> files. | 523 | can process these <filename>.siginfo</filename> files. |
| 524 | If one file is specified, it will dump out the dependency | 524 | If one file is specified, it will dump out the dependency |
| 525 | information in the file. | 525 | information in the file. |
| 526 | If two files are specified, it will compare the two files and dump out | 526 | If two files are specified, it will compare the two files and dump out |
| 527 | the differences between the two. | 527 | the differences between the two. |
| 528 | This allows the question of "What changed between X and Y?" to be | 528 | This allows the question of "What changed between X and Y?" to be |
| 529 | answered easily.</para></listitem> | 529 | answered easily.</para></listitem> |
| @@ -538,41 +538,41 @@ | |||
| 538 | The shared state code uses checksums and shared state | 538 | The shared state code uses checksums and shared state |
| 539 | cache to avoid unnecessarily rebuilding tasks. | 539 | cache to avoid unnecessarily rebuilding tasks. |
| 540 | As with all schemes, this one has some drawbacks. | 540 | As with all schemes, this one has some drawbacks. |
| 541 | It is possible that you could make implicit changes that are not factored | 541 | It is possible that you could make implicit changes that are not factored |
| 542 | into the checksum calculation, but do affect a task's output. | 542 | into the checksum calculation, but do affect a task's output. |
| 543 | A good example is perhaps when a tool changes its output. | 543 | A good example is perhaps when a tool changes its output. |
| 544 | Let's say that the output of <filename>rpmdeps</filename> needed to change. | 544 | Let's say that the output of <filename>rpmdeps</filename> needed to change. |
| 545 | The result of the change should be that all the "package", "package_write_rpm", | 545 | The result of the change should be that all the "package", "package_write_rpm", |
| 546 | and "package_deploy-rpm" shared state cache items would become invalid. | 546 | and "package_deploy-rpm" shared state cache items would become invalid. |
| 547 | But, because this is a change that is external to the code and therefore implicit, | 547 | But, because this is a change that is external to the code and therefore implicit, |
| 548 | the associated shared state cache items do not become invalidated. | 548 | the associated shared state cache items do not become invalidated. |
| 549 | In this case, the build process would use the cached items rather than running the | 549 | In this case, the build process would use the cached items rather than running the |
| 550 | task again. | 550 | task again. |
| 551 | Obviously, these types of implicit changes can cause problems. | 551 | Obviously, these types of implicit changes can cause problems. |
| 552 | </para> | 552 | </para> |
| 553 | 553 | ||
| 554 | <para> | 554 | <para> |
| 555 | To avoid these problems during the build, you need to understand the effects of any | 555 | To avoid these problems during the build, you need to understand the effects of any |
| 556 | change you make. | 556 | change you make. |
| 557 | Note that any changes you make directly to a function automatically are factored into | 557 | Note that any changes you make directly to a function automatically are factored into |
| 558 | the checksum calculation and thus, will invalidate the associated area of sstate cache. | 558 | the checksum calculation and thus, will invalidate the associated area of sstate cache. |
| 559 | You need to be aware of any implicit changes that are not obvious changes to the | 559 | You need to be aware of any implicit changes that are not obvious changes to the |
| 560 | code and could affect the output of a given task. | 560 | code and could affect the output of a given task. |
| 561 | Once you are aware of such a change, you can take steps to invalidate the cache | 561 | Once you are aware of such a change, you can take steps to invalidate the cache |
| 562 | and force the task to run. | 562 | and force the task to run. |
| 563 | The step to take is as simple as changing a function's comments in the source code. | 563 | The step to take is as simple as changing a function's comments in the source code. |
| 564 | For example, to invalidate package shared state files, change the comment statements | 564 | For example, to invalidate package shared state files, change the comment statements |
| 565 | of <filename>do_package</filename> or the comments of one of the functions it calls. | 565 | of <filename>do_package</filename> or the comments of one of the functions it calls. |
| 566 | The change is purely cosmetic, but it causes the checksum to be recalculated and | 566 | The change is purely cosmetic, but it causes the checksum to be recalculated and |
| 567 | forces the task to be run again. | 567 | forces the task to be run again. |
| 568 | </para> | 568 | </para> |
| 569 | 569 | ||
| 570 | <note> | 570 | <note> |
| 571 | For an example of a commit that makes a cosmetic change to invalidate | 571 | For an example of a commit that makes a cosmetic change to invalidate |
| 572 | a shared state, see this | 572 | a shared state, see this |
| 573 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>. | 573 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>. |
| 574 | </note> | 574 | </note> |
| 575 | </section> | 575 | </section> |
| 576 | </section> | 576 | </section> |
| 577 | </section> | 577 | </section> |
| 578 | 578 | ||
| @@ -580,24 +580,24 @@ | |||
| 580 | <title>x32</title> | 580 | <title>x32</title> |
| 581 | 581 | ||
| 582 | <para> | 582 | <para> |
| 583 | x32 is a new processor-specific Application Binary Interface (psABI) for x86_64. | 583 | x32 is a new processor-specific Application Binary Interface (psABI) for x86_64. |
| 584 | An ABI defines the calling conventions between functions in a processing environment. | 584 | An ABI defines the calling conventions between functions in a processing environment. |
| 585 | The interface determines what registers are used and what the sizes are for various C data types. | 585 | The interface determines what registers are used and what the sizes are for various C data types. |
| 586 | </para> | 586 | </para> |
| 587 | 587 | ||
| 588 | <para> | 588 | <para> |
| 589 | Some processing environments prefer using 32-bit applications even when running | 589 | Some processing environments prefer using 32-bit applications even when running |
| 590 | on Intel 64-bit platforms. | 590 | on Intel 64-bit platforms. |
| 591 | Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms. | 591 | Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms. |
| 592 | The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources, | 592 | The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources, |
| 593 | leaving the system underutilized. | 593 | leaving the system underutilized. |
| 594 | Now consider the x86_64 psABI. | 594 | Now consider the x86_64 psABI. |
| 595 | This ABI is newer and uses 64-bits for data sizes and program pointers. | 595 | This ABI is newer and uses 64-bits for data sizes and program pointers. |
| 596 | The extra bits increase the footprint size of the programs, libraries, | 596 | The extra bits increase the footprint size of the programs, libraries, |
| 597 | and also increases the memory and file system size requirements. | 597 | and also increases the memory and file system size requirements. |
| 598 | Executing under the x32 psABI enables user programs to utilize CPU and system resources | 598 | Executing under the x32 psABI enables user programs to utilize CPU and system resources |
| 599 | more efficiently while keeping the memory footprint of the applications low. | 599 | more efficiently while keeping the memory footprint of the applications low. |
| 600 | Extra bits are used for registers but not for addressing mechanisms. | 600 | Extra bits are used for registers but not for addressing mechanisms. |
| 601 | </para> | 601 | </para> |
| 602 | 602 | ||
| 603 | <section id='support'> | 603 | <section id='support'> |
| @@ -608,14 +608,14 @@ | |||
| 608 | release supports current development specifications of x32 psABI. | 608 | release supports current development specifications of x32 psABI. |
| 609 | As of this release of the Yocto Project, x32 psABI support exists as follows: | 609 | As of this release of the Yocto Project, x32 psABI support exists as follows: |
| 610 | <itemizedlist> | 610 | <itemizedlist> |
| 611 | <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets. | 611 | <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets. |
| 612 | </para></listitem> | 612 | </para></listitem> |
| 613 | <listitem><para>You can use the x32 psABI support through the <filename>meta-x32</filename> | 613 | <listitem><para>You can use the x32 psABI support through the <filename>meta-x32</filename> |
| 614 | layer on top of the OE-core/Yocto layer.</para></listitem> | 614 | layer on top of the OE-core/Yocto layer.</para></listitem> |
| 615 | <listitem><para>The toolchain from the <filename>experimental/meta-x32</filename> layer | 615 | <listitem><para>The toolchain from the <filename>experimental/meta-x32</filename> layer |
| 616 | is used for building x32 psABI program binaries.</para></listitem> | 616 | is used for building x32 psABI program binaries.</para></listitem> |
| 617 | <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem> | 617 | <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem> |
| 618 | <listitem><para>You can create and boot <filename>core-image-minimal</filename> and | 618 | <listitem><para>You can create and boot <filename>core-image-minimal</filename> and |
| 619 | <filename>core-image-sato</filename> images.</para></listitem> | 619 | <filename>core-image-sato</filename> images.</para></listitem> |
| 620 | </itemizedlist> | 620 | </itemizedlist> |
| 621 | </para> | 621 | </para> |
| @@ -625,18 +625,18 @@ | |||
| 625 | <title>Future Development and Limitations</title> | 625 | <title>Future Development and Limitations</title> |
| 626 | 626 | ||
| 627 | <para> | 627 | <para> |
| 628 | As of this Yocto Project release, the x32 psABI kernel and library interfaces | 628 | As of this Yocto Project release, the x32 psABI kernel and library interfaces |
| 629 | specifications are not finalized. | 629 | specifications are not finalized. |
| 630 | </para> | 630 | </para> |
| 631 | 631 | ||
| 632 | <para> | 632 | <para> |
| 633 | Future Plans for the x32 psABI in the Yocto Project include the following: | 633 | Future Plans for the x32 psABI in the Yocto Project include the following: |
| 634 | <itemizedlist> | 634 | <itemizedlist> |
| 635 | <listitem><para>Enhance and fix the few remaining recipes so they | 635 | <listitem><para>Enhance and fix the few remaining recipes so they |
| 636 | work with and support x32 toolchains.</para></listitem> | 636 | work with and support x32 toolchains.</para></listitem> |
| 637 | <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem> | 637 | <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem> |
| 638 | <listitem><para>Support larger images.</para></listitem> | 638 | <listitem><para>Support larger images.</para></listitem> |
| 639 | <listitem><para>Integrate x32 recipes, toolchain, and kernel changes from | 639 | <listitem><para>Integrate x32 recipes, toolchain, and kernel changes from |
| 640 | <filename>experimental/meta-x32</filename> into OE-core.</para></listitem> | 640 | <filename>experimental/meta-x32</filename> into OE-core.</para></listitem> |
| 641 | </itemizedlist> | 641 | </itemizedlist> |
| 642 | </para> | 642 | </para> |
| @@ -650,7 +650,7 @@ | |||
| 650 | Yocto Project, you can follow these steps to use the x32 spABI: | 650 | Yocto Project, you can follow these steps to use the x32 spABI: |
| 651 | <itemizedlist> | 651 | <itemizedlist> |
| 652 | <listitem><para>Add the <filename>experimental/meta-x32</filename> layer to your local | 652 | <listitem><para>Add the <filename>experimental/meta-x32</filename> layer to your local |
| 653 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | 653 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
| 654 | You can find the <filename>experimental/meta-x32</filename> source repository at | 654 | You can find the <filename>experimental/meta-x32</filename> source repository at |
| 655 | <ulink url='&YOCTO_GIT_URL;'></ulink>.</para></listitem> | 655 | <ulink url='&YOCTO_GIT_URL;'></ulink>.</para></listitem> |
| 656 | <listitem><para>Edit your <filename>conf/bblayers.conf</filename> file so that it includes | 656 | <listitem><para>Edit your <filename>conf/bblayers.conf</filename> file so that it includes |
| @@ -677,8 +677,8 @@ | |||
| 677 | or 'INVALID'), True) or 'lib'}" | 677 | or 'INVALID'), True) or 'lib'}" |
| 678 | #MACHINE = "atom-pc" | 678 | #MACHINE = "atom-pc" |
| 679 | #DEFAULTTUNE = "core2-64-x32" | 679 | #DEFAULTTUNE = "core2-64-x32" |
| 680 | </literallayout></para></listitem> | 680 | </literallayout></para></listitem> |
| 681 | <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI. | 681 | <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI. |
| 682 | Here is an example: | 682 | Here is an example: |
| 683 | <literallayout class='monospaced'> | 683 | <literallayout class='monospaced'> |
| 684 | $ bitake core-image-sato | 684 | $ bitake core-image-sato |
| @@ -696,15 +696,15 @@ | |||
| 696 | <title>Licenses</title> | 696 | <title>Licenses</title> |
| 697 | 697 | ||
| 698 | <para> | 698 | <para> |
| 699 | This section describes the mechanism by which the OpenEmbedded build system | 699 | This section describes the mechanism by which the OpenEmbedded build system |
| 700 | tracks changes to licensing text. | 700 | tracks changes to licensing text. |
| 701 | The section also describes how to enable commercially licensed recipes, | 701 | The section also describes how to enable commercially licensed recipes, |
| 702 | which by default are disabled. | 702 | which by default are disabled. |
| 703 | </para> | 703 | </para> |
| 704 | 704 | ||
| 705 | <para> | 705 | <para> |
| 706 | For information that can help you maintain compliance with various open | 706 | For information that can help you maintain compliance with various open |
| 707 | source licensing during the lifecycle of the product, see the | 707 | source licensing during the lifecycle of the product, see the |
| 708 | "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>" section | 708 | "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>" section |
| 709 | in the Yocto Project Development Manual. | 709 | in the Yocto Project Development Manual. |
| 710 | </para> | 710 | </para> |
| @@ -713,8 +713,8 @@ | |||
| 713 | <title>Tracking License Changes</title> | 713 | <title>Tracking License Changes</title> |
| 714 | 714 | ||
| 715 | <para> | 715 | <para> |
| 716 | The license of an upstream project might change in the future. | 716 | The license of an upstream project might change in the future. |
| 717 | In order to prevent these changes going unnoticed, the | 717 | In order to prevent these changes going unnoticed, the |
| 718 | <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename> | 718 | <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename> |
| 719 | variable tracks changes to the license text. The checksums are validated at the end of the | 719 | variable tracks changes to the license text. The checksums are validated at the end of the |
| 720 | configure step, and if the checksums do not match, the build will fail. | 720 | configure step, and if the checksums do not match, the build will fail. |
| @@ -736,15 +736,15 @@ | |||
| 736 | </para> | 736 | </para> |
| 737 | 737 | ||
| 738 | <para> | 738 | <para> |
| 739 | The build system uses the | 739 | The build system uses the |
| 740 | <filename><link linkend='var-S'>S</link></filename> variable as the | 740 | <filename><link linkend='var-S'>S</link></filename> variable as the |
| 741 | default directory used when searching files listed in | 741 | default directory used when searching files listed in |
| 742 | <filename>LIC_FILES_CHKSUM</filename>. | 742 | <filename>LIC_FILES_CHKSUM</filename>. |
| 743 | The previous example employs the default directory. | 743 | The previous example employs the default directory. |
| 744 | </para> | 744 | </para> |
| 745 | 745 | ||
| 746 | <para> | 746 | <para> |
| 747 | You can also use relative paths as shown in the following example: | 747 | You can also use relative paths as shown in the following example: |
| 748 | <literallayout class='monospaced'> | 748 | <literallayout class='monospaced'> |
| 749 | LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ | 749 | LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ |
| 750 | md5=bb14ed3c4cda583abc85401304b5cd4e" | 750 | md5=bb14ed3c4cda583abc85401304b5cd4e" |
| @@ -753,14 +753,14 @@ | |||
| 753 | </para> | 753 | </para> |
| 754 | 754 | ||
| 755 | <para> | 755 | <para> |
| 756 | In this example, the first line locates a file in | 756 | In this example, the first line locates a file in |
| 757 | <filename>${S}/src/ls.c</filename>. | 757 | <filename>${S}/src/ls.c</filename>. |
| 758 | The second line refers to a file in | 758 | The second line refers to a file in |
| 759 | <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent | 759 | <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent |
| 760 | of <filename><link linkend='var-S'>S</link></filename>. | 760 | of <filename><link linkend='var-S'>S</link></filename>. |
| 761 | </para> | 761 | </para> |
| 762 | <para> | 762 | <para> |
| 763 | Note that this variable is mandatory for all recipes, unless the | 763 | Note that this variable is mandatory for all recipes, unless the |
| 764 | <filename>LICENSE</filename> variable is set to "CLOSED". | 764 | <filename>LICENSE</filename> variable is set to "CLOSED". |
| 765 | </para> | 765 | </para> |
| 766 | </section> | 766 | </section> |
| @@ -768,48 +768,48 @@ | |||
| 768 | <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"> | 768 | <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"> |
| 769 | <title>Explanation of Syntax</title> | 769 | <title>Explanation of Syntax</title> |
| 770 | <para> | 770 | <para> |
| 771 | As mentioned in the previous section, the | 771 | As mentioned in the previous section, the |
| 772 | <filename>LIC_FILES_CHKSUM</filename> variable lists all the | 772 | <filename>LIC_FILES_CHKSUM</filename> variable lists all the |
| 773 | important files that contain the license text for the source code. | 773 | important files that contain the license text for the source code. |
| 774 | It is possible to specify a checksum for an entire file, or a specific section of a | 774 | It is possible to specify a checksum for an entire file, or a specific section of a |
| 775 | file (specified by beginning and ending line numbers with the "beginline" and "endline" | 775 | file (specified by beginning and ending line numbers with the "beginline" and "endline" |
| 776 | parameters, respectively). | 776 | parameters, respectively). |
| 777 | The latter is useful for source files with a license notice header, | 777 | The latter is useful for source files with a license notice header, |
| 778 | README documents, and so forth. | 778 | README documents, and so forth. |
| 779 | If you do not use the "beginline" parameter, then it is assumed that the text begins on the | 779 | If you do not use the "beginline" parameter, then it is assumed that the text begins on the |
| 780 | first line of the file. | 780 | first line of the file. |
| 781 | Similarly, if you do not use the "endline" parameter, it is assumed that the license text | 781 | Similarly, if you do not use the "endline" parameter, it is assumed that the license text |
| 782 | ends with the last line of the file. | 782 | ends with the last line of the file. |
| 783 | </para> | 783 | </para> |
| 784 | 784 | ||
| 785 | <para> | 785 | <para> |
| 786 | The "md5" parameter stores the md5 checksum of the license text. | 786 | The "md5" parameter stores the md5 checksum of the license text. |
| 787 | If the license text changes in any way as compared to this parameter | 787 | If the license text changes in any way as compared to this parameter |
| 788 | then a mismatch occurs. | 788 | then a mismatch occurs. |
| 789 | This mismatch triggers a build failure and notifies the developer. | 789 | This mismatch triggers a build failure and notifies the developer. |
| 790 | Notification allows the developer to review and address the license text changes. | 790 | Notification allows the developer to review and address the license text changes. |
| 791 | Also note that if a mismatch occurs during the build, the correct md5 | 791 | Also note that if a mismatch occurs during the build, the correct md5 |
| 792 | checksum is placed in the build log and can be easily copied to the recipe. | 792 | checksum is placed in the build log and can be easily copied to the recipe. |
| 793 | </para> | 793 | </para> |
| 794 | 794 | ||
| 795 | <para> | 795 | <para> |
| 796 | There is no limit to how many files you can specify using the | 796 | There is no limit to how many files you can specify using the |
| 797 | <filename>LIC_FILES_CHKSUM</filename> variable. | 797 | <filename>LIC_FILES_CHKSUM</filename> variable. |
| 798 | Generally, however, every project requires a few specifications for license tracking. | 798 | Generally, however, every project requires a few specifications for license tracking. |
| 799 | Many projects have a "COPYING" file that stores the license information for all the source | 799 | Many projects have a "COPYING" file that stores the license information for all the source |
| 800 | code files. | 800 | code files. |
| 801 | This practice allows you to just track the "COPYING" file as long as it is kept up to date. | 801 | This practice allows you to just track the "COPYING" file as long as it is kept up to date. |
| 802 | </para> | 802 | </para> |
| 803 | 803 | ||
| 804 | <tip> | 804 | <tip> |
| 805 | If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match | 805 | If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match |
| 806 | error and displays the correct "md5" parameter value during the build. | 806 | error and displays the correct "md5" parameter value during the build. |
| 807 | The correct parameter is also captured in the build log. | 807 | The correct parameter is also captured in the build log. |
| 808 | </tip> | 808 | </tip> |
| 809 | 809 | ||
| 810 | <tip> | 810 | <tip> |
| 811 | If the whole file contains only license text, you do not need to use the "beginline" and | 811 | If the whole file contains only license text, you do not need to use the "beginline" and |
| 812 | "endline" parameters. | 812 | "endline" parameters. |
| 813 | </tip> | 813 | </tip> |
| 814 | </section> | 814 | </section> |
| 815 | </section> | 815 | </section> |
| @@ -820,10 +820,10 @@ | |||
| 820 | <para> | 820 | <para> |
| 821 | By default, the OpenEmbedded build system disables | 821 | By default, the OpenEmbedded build system disables |
| 822 | components that have commercial or other special licensing | 822 | components that have commercial or other special licensing |
| 823 | requirements. | 823 | requirements. |
| 824 | Such requirements are defined on a | 824 | Such requirements are defined on a |
| 825 | recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable | 825 | recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable |
| 826 | definition in the affected recipe. | 826 | definition in the affected recipe. |
| 827 | For instance, the | 827 | For instance, the |
| 828 | <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> | 828 | <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> |
| 829 | recipe contains the following statement: | 829 | recipe contains the following statement: |
| @@ -839,7 +839,7 @@ | |||
| 839 | definition to be enabled and included in an image, it | 839 | definition to be enabled and included in an image, it |
| 840 | needs to have a matching entry in the global | 840 | needs to have a matching entry in the global |
| 841 | <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable | 841 | <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable |
| 842 | typically defined in your <filename>local.conf</filename> file. | 842 | typically defined in your <filename>local.conf</filename> file. |
| 843 | For example, to enable | 843 | For example, to enable |
| 844 | the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> | 844 | the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> |
| 845 | package, you could add either the string | 845 | package, you could add either the string |
| @@ -867,7 +867,7 @@ | |||
| 867 | the initial underscore character or characters. | 867 | the initial underscore character or characters. |
| 868 | A partial string will match | 868 | A partial string will match |
| 869 | any license that contains the given string as the first | 869 | any license that contains the given string as the first |
| 870 | portion of its license. | 870 | portion of its license. |
| 871 | For example, the following | 871 | For example, the following |
| 872 | whitelist string will also match both of the packages | 872 | whitelist string will also match both of the packages |
| 873 | previously mentioned as well as any other packages that have | 873 | previously mentioned as well as any other packages that have |
| @@ -879,7 +879,7 @@ | |||
| 879 | 879 | ||
| 880 | <section id="license-flag-matching"> | 880 | <section id="license-flag-matching"> |
| 881 | <title>License Flag Matching</title> | 881 | <title>License Flag Matching</title> |
| 882 | 882 | ||
| 883 | <para> | 883 | <para> |
| 884 | The definition of 'matching' in reference to a | 884 | The definition of 'matching' in reference to a |
| 885 | recipe's <filename>LICENSE_FLAGS</filename> setting is simple. | 885 | recipe's <filename>LICENSE_FLAGS</filename> setting is simple. |
| @@ -891,7 +891,7 @@ | |||
| 891 | Before a flag | 891 | Before a flag |
| 892 | defined by a particular recipe is tested against the | 892 | defined by a particular recipe is tested against the |
| 893 | contents of the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, the | 893 | contents of the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, the |
| 894 | string <filename>_${PN}</filename> (with | 894 | string <filename>_${PN}</filename> (with |
| 895 | <link linkend='var-PN'><filename>PN</filename></link> expanded of course) is | 895 | <link linkend='var-PN'><filename>PN</filename></link> expanded of course) is |
| 896 | appended to the flag, thus automatically making each | 896 | appended to the flag, thus automatically making each |
| 897 | <filename>LICENSE_FLAGS</filename> value recipe-specific. | 897 | <filename>LICENSE_FLAGS</filename> value recipe-specific. |
| @@ -907,7 +907,7 @@ | |||
| 907 | You can broaden the match by | 907 | You can broaden the match by |
| 908 | putting any "_"-separated beginning subset of a | 908 | putting any "_"-separated beginning subset of a |
| 909 | <filename>LICENSE_FLAGS</filename> flag in the whitelist, which will also | 909 | <filename>LICENSE_FLAGS</filename> flag in the whitelist, which will also |
| 910 | match. | 910 | match. |
| 911 | For example, simply specifying "commercial" in | 911 | For example, simply specifying "commercial" in |
| 912 | the whitelist would match any expanded <filename>LICENSE_FLAGS</filename> | 912 | the whitelist would match any expanded <filename>LICENSE_FLAGS</filename> |
| 913 | definition starting with "commercial" such as | 913 | definition starting with "commercial" such as |
| @@ -923,7 +923,7 @@ | |||
| 923 | <para> | 923 | <para> |
| 924 | Broadening the match allows for a range of specificity for the items | 924 | Broadening the match allows for a range of specificity for the items |
| 925 | in the whitelist, from more general to perfectly | 925 | in the whitelist, from more general to perfectly |
| 926 | specific. | 926 | specific. |
| 927 | So you have the choice of exhaustively | 927 | So you have the choice of exhaustively |
| 928 | enumerating each license flag in the whitelist to | 928 | enumerating each license flag in the whitelist to |
| 929 | allow only those specific recipes into the image, or | 929 | allow only those specific recipes into the image, or |
| @@ -935,7 +935,7 @@ | |||
| 935 | <para> | 935 | <para> |
| 936 | This scheme works even if the flag already | 936 | This scheme works even if the flag already |
| 937 | has <filename>_${PN}</filename> appended - the extra <filename>_${PN}</filename> is | 937 | has <filename>_${PN}</filename> appended - the extra <filename>_${PN}</filename> is |
| 938 | redundant, but does not affect the outcome. | 938 | redundant, but does not affect the outcome. |
| 939 | For example, a license flag of "commercial_1.2_foo" would | 939 | For example, a license flag of "commercial_1.2_foo" would |
| 940 | turn into "commercial_1.2_foo_foo" and would match | 940 | turn into "commercial_1.2_foo_foo" and would match |
| 941 | both the general "commercial" and the specific | 941 | both the general "commercial" and the specific |
| @@ -944,8 +944,8 @@ | |||
| 944 | "commercial_1.2_foo_foo" and "commercial_1.2", which | 944 | "commercial_1.2_foo_foo" and "commercial_1.2", which |
| 945 | does not make much sense regarding use in the whitelist. | 945 | does not make much sense regarding use in the whitelist. |
| 946 | </para> | 946 | </para> |
| 947 | 947 | ||
| 948 | <para> | 948 | <para> |
| 949 | For a versioned string, you could instead specify | 949 | For a versioned string, you could instead specify |
| 950 | "commercial_foo_1.2", which would turn into | 950 | "commercial_foo_1.2", which would turn into |
| 951 | "commercial_foo_1.2_foo". | 951 | "commercial_foo_1.2_foo". |
| @@ -993,8 +993,8 @@ | |||
| 993 | </para> | 993 | </para> |
| 994 | 994 | ||
| 995 | <para> | 995 | <para> |
| 996 | Specifying audio and video plug-ins as part of the | 996 | Specifying audio and video plug-ins as part of the |
| 997 | <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and | 997 | <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and |
| 998 | <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements | 998 | <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements |
| 999 | or commercial qt components as part of | 999 | or commercial qt components as part of |
| 1000 | the <filename>COMMERCIAL_QT</filename> statement (along | 1000 | the <filename>COMMERCIAL_QT</filename> statement (along |
| @@ -1006,6 +1006,6 @@ | |||
| 1006 | </section> | 1006 | </section> |
| 1007 | </section> | 1007 | </section> |
| 1008 | </chapter> | 1008 | </chapter> |
| 1009 | <!-- | 1009 | <!-- |
| 1010 | vim: expandtab tw=80 ts=4 | 1010 | vim: expandtab tw=80 ts=4 |
| 1011 | --> | 1011 | --> |
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml index e5b5edb846..286b5fa783 100644 --- a/documentation/poky-ref-manual/usingpoky.xml +++ b/documentation/poky-ref-manual/usingpoky.xml | |||
| @@ -17,8 +17,8 @@ | |||
| 17 | <para> | 17 | <para> |
| 18 | This section provides a summary of the build process and provides information | 18 | This section provides a summary of the build process and provides information |
| 19 | for less obvious aspects of the build process. | 19 | for less obvious aspects of the build process. |
| 20 | For general information on how to build an image using the OpenEmbedded build | 20 | For general information on how to build an image using the OpenEmbedded build |
| 21 | system, see the | 21 | system, see the |
| 22 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | 22 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" |
| 23 | section of the Yocto Project Quick Start. | 23 | section of the Yocto Project Quick Start. |
| 24 | </para> | 24 | </para> |
| @@ -35,12 +35,12 @@ | |||
| 35 | </para> | 35 | </para> |
| 36 | 36 | ||
| 37 | <para> | 37 | <para> |
| 38 | The <filename>build_dir</filename> is optional and specifies the directory the | 38 | The <filename>build_dir</filename> is optional and specifies the directory the |
| 39 | OpenEmbedded build system uses for the build - | 39 | OpenEmbedded build system uses for the build - |
| 40 | the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | 40 | the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
| 41 | If you do not specify a Build Directory it defaults to <filename>build</filename> | 41 | If you do not specify a Build Directory it defaults to <filename>build</filename> |
| 42 | in your current working directory. | 42 | in your current working directory. |
| 43 | A common practice is to use a different Build Directory for different targets. | 43 | A common practice is to use a different Build Directory for different targets. |
| 44 | For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename> | 44 | For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename> |
| 45 | target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target. | 45 | target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target. |
| 46 | See <link linkend="structure-core-script">&OE_INIT_FILE;</link> | 46 | See <link linkend="structure-core-script">&OE_INIT_FILE;</link> |
| @@ -55,13 +55,13 @@ | |||
| 55 | </para> | 55 | </para> |
| 56 | 56 | ||
| 57 | <para> | 57 | <para> |
| 58 | The <filename>target</filename> is the name of the recipe you want to build. | 58 | The <filename>target</filename> is the name of the recipe you want to build. |
| 59 | Common targets are the images in <filename>meta/recipes-core/images</filename>, | 59 | Common targets are the images in <filename>meta/recipes-core/images</filename>, |
| 60 | <filename>/meta/recipes-sato/images</filename>, etc. all found in the | 60 | <filename>/meta/recipes-sato/images</filename>, etc. all found in the |
| 61 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 61 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 62 | Or, the target can be the name of a recipe for a specific piece of software such as | 62 | Or, the target can be the name of a recipe for a specific piece of software such as |
| 63 | <application>busybox</application>. | 63 | <application>busybox</application>. |
| 64 | For more details about the images the OpenEmbedded build system supports, see the | 64 | For more details about the images the OpenEmbedded build system supports, see the |
| 65 | "<link linkend="ref-images">Images</link>" chapter. | 65 | "<link linkend="ref-images">Images</link>" chapter. |
| 66 | </para> | 66 | </para> |
| 67 | 67 | ||
| @@ -76,9 +76,9 @@ | |||
| 76 | <title>Building an Image Using GPL Components</title> | 76 | <title>Building an Image Using GPL Components</title> |
| 77 | 77 | ||
| 78 | <para> | 78 | <para> |
| 79 | When building an image using GPL components, you need to maintain your original | 79 | When building an image using GPL components, you need to maintain your original |
| 80 | settings and not switch back and forth applying different versions of the GNU | 80 | settings and not switch back and forth applying different versions of the GNU |
| 81 | General Public License. | 81 | General Public License. |
| 82 | If you rebuild using different versions of GPL, dependency errors might occur | 82 | If you rebuild using different versions of GPL, dependency errors might occur |
| 83 | due to some components not being rebuilt. | 83 | due to some components not being rebuilt. |
| 84 | </para> | 84 | </para> |
| @@ -89,11 +89,11 @@ | |||
| 89 | <title>Installing and Using the Result</title> | 89 | <title>Installing and Using the Result</title> |
| 90 | 90 | ||
| 91 | <para> | 91 | <para> |
| 92 | Once an image has been built, it often needs to be installed. | 92 | Once an image has been built, it often needs to be installed. |
| 93 | The images and kernels built by the OpenEmbedded build system are placed in the | 93 | The images and kernels built by the OpenEmbedded build system are placed in the |
| 94 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in | 94 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in |
| 95 | <filename class="directory">tmp/deploy/images</filename>. | 95 | <filename class="directory">tmp/deploy/images</filename>. |
| 96 | For information on how to run pre-built images such as <filename>qemux86</filename> | 96 | For information on how to run pre-built images such as <filename>qemux86</filename> |
| 97 | and <filename>qemuarm</filename>, see the | 97 | and <filename>qemuarm</filename>, see the |
| 98 | "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" | 98 | "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" |
| 99 | section in the Yocto Project Quick Start. | 99 | section in the Yocto Project Quick Start. |
| @@ -106,25 +106,25 @@ | |||
| 106 | <title>Debugging Build Failures</title> | 106 | <title>Debugging Build Failures</title> |
| 107 | 107 | ||
| 108 | <para> | 108 | <para> |
| 109 | The exact method for debugging build failures depends on the nature of the | 109 | The exact method for debugging build failures depends on the nature of the |
| 110 | problem and on the system's area from which the bug originates. | 110 | problem and on the system's area from which the bug originates. |
| 111 | Standard debugging practices such as comparison against the last | 111 | Standard debugging practices such as comparison against the last |
| 112 | known working version with examination of the changes and the re-application of steps | 112 | known working version with examination of the changes and the re-application of steps |
| 113 | to identify the one causing the problem are | 113 | to identify the one causing the problem are |
| 114 | valid for the Yocto Project just as they are for any other system. | 114 | valid for the Yocto Project just as they are for any other system. |
| 115 | Even though it is impossible to detail every possible potential failure, | 115 | Even though it is impossible to detail every possible potential failure, |
| 116 | this section provides some general tips to aid in debugging. | 116 | this section provides some general tips to aid in debugging. |
| 117 | </para> | 117 | </para> |
| 118 | 118 | ||
| 119 | <section id='usingpoky-debugging-taskfailures'> | 119 | <section id='usingpoky-debugging-taskfailures'> |
| 120 | <title>Task Failures</title> | 120 | <title>Task Failures</title> |
| 121 | 121 | ||
| 122 | <para>The log file for shell tasks is available in | 122 | <para>The log file for shell tasks is available in |
| 123 | <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. | 123 | <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. |
| 124 | For example, the <filename>compile</filename> task for the QEMU minimal image for the x86 | 124 | For example, the <filename>compile</filename> task for the QEMU minimal image for the x86 |
| 125 | machine (<filename>qemux86</filename>) might be | 125 | machine (<filename>qemux86</filename>) might be |
| 126 | <filename>tmp/work/qemux86-poky-linux/core-image-minimal-1.0-r0/temp/log.do_compile.20830</filename>. | 126 | <filename>tmp/work/qemux86-poky-linux/core-image-minimal-1.0-r0/temp/log.do_compile.20830</filename>. |
| 127 | To see what BitBake runs to generate that log, look at the corresponding | 127 | To see what BitBake runs to generate that log, look at the corresponding |
| 128 | <filename>run.do_taskname.pid</filename> file located in the same directory. | 128 | <filename>run.do_taskname.pid</filename> file located in the same directory. |
| 129 | </para> | 129 | </para> |
| 130 | 130 | ||
| @@ -137,17 +137,17 @@ | |||
| 137 | <title>Running Specific Tasks</title> | 137 | <title>Running Specific Tasks</title> |
| 138 | 138 | ||
| 139 | <para> | 139 | <para> |
| 140 | Any given package consists of a set of tasks. | 140 | Any given package consists of a set of tasks. |
| 141 | The standard BitBake behavior in most cases is: <filename>fetch</filename>, | 141 | The standard BitBake behavior in most cases is: <filename>fetch</filename>, |
| 142 | <filename>unpack</filename>, | 142 | <filename>unpack</filename>, |
| 143 | <filename>patch</filename>, <filename>configure</filename>, | 143 | <filename>patch</filename>, <filename>configure</filename>, |
| 144 | <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>, | 144 | <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>, |
| 145 | <filename>package_write</filename>, and <filename>build</filename>. | 145 | <filename>package_write</filename>, and <filename>build</filename>. |
| 146 | The default task is <filename>build</filename> and any tasks on which it depends | 146 | The default task is <filename>build</filename> and any tasks on which it depends |
| 147 | build first. | 147 | build first. |
| 148 | Some tasks exist, such as <filename>devshell</filename>, that are not part of the | 148 | Some tasks exist, such as <filename>devshell</filename>, that are not part of the |
| 149 | default build chain. | 149 | default build chain. |
| 150 | If you wish to run a task that is not part of the default build chain, you can use the | 150 | If you wish to run a task that is not part of the default build chain, you can use the |
| 151 | <filename>-c</filename> option in BitBake as follows: | 151 | <filename>-c</filename> option in BitBake as follows: |
| 152 | <literallayout class='monospaced'> | 152 | <literallayout class='monospaced'> |
| 153 | $ bitbake matchbox-desktop -c devshell | 153 | $ bitbake matchbox-desktop -c devshell |
| @@ -155,8 +155,8 @@ | |||
| 155 | </para> | 155 | </para> |
| 156 | 156 | ||
| 157 | <para> | 157 | <para> |
| 158 | If you wish to rerun a task, use the <filename>-f</filename> force option. | 158 | If you wish to rerun a task, use the <filename>-f</filename> force option. |
| 159 | For example, the following sequence forces recompilation after changing files in the | 159 | For example, the following sequence forces recompilation after changing files in the |
| 160 | working directory. | 160 | working directory. |
| 161 | <literallayout class='monospaced'> | 161 | <literallayout class='monospaced'> |
| 162 | $ bitbake matchbox-desktop | 162 | $ bitbake matchbox-desktop |
| @@ -173,7 +173,7 @@ | |||
| 173 | <para> | 173 | <para> |
| 174 | This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it. | 174 | This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it. |
| 175 | The last command reruns all tasks (basically the packaging tasks) after the compile. | 175 | The last command reruns all tasks (basically the packaging tasks) after the compile. |
| 176 | BitBake recognizes that the <filename>compile</filename> task was rerun and therefore | 176 | BitBake recognizes that the <filename>compile</filename> task was rerun and therefore |
| 177 | understands that the other tasks also need to be run again. | 177 | understands that the other tasks also need to be run again. |
| 178 | </para> | 178 | </para> |
| 179 | 179 | ||
| @@ -191,13 +191,13 @@ | |||
| 191 | <title>Dependency Graphs</title> | 191 | <title>Dependency Graphs</title> |
| 192 | 192 | ||
| 193 | <para> | 193 | <para> |
| 194 | Sometimes it can be hard to see why BitBake wants to build some other packages before a given | 194 | Sometimes it can be hard to see why BitBake wants to build some other packages before a given |
| 195 | package you have specified. | 195 | package you have specified. |
| 196 | The <filename>bitbake -g targetname</filename> command creates the | 196 | The <filename>bitbake -g targetname</filename> command creates the |
| 197 | <filename>depends.dot</filename>, <filename>package-depends.dot</filename>, | 197 | <filename>depends.dot</filename>, <filename>package-depends.dot</filename>, |
| 198 | and <filename>task-depends.dot</filename> files in the current directory. | 198 | and <filename>task-depends.dot</filename> files in the current directory. |
| 199 | These files show the package and task dependencies and are useful for debugging problems. | 199 | These files show the package and task dependencies and are useful for debugging problems. |
| 200 | You can use the <filename>bitbake -g -u depexp targetname</filename> command to | 200 | You can use the <filename>bitbake -g -u depexp targetname</filename> command to |
| 201 | display the results in a more human-readable form. | 201 | display the results in a more human-readable form. |
| 202 | </para> | 202 | </para> |
| 203 | </section> | 203 | </section> |
| @@ -208,7 +208,7 @@ | |||
| 208 | <para> | 208 | <para> |
| 209 | You can see debug output from BitBake by using the <filename>-D</filename> option. | 209 | You can see debug output from BitBake by using the <filename>-D</filename> option. |
| 210 | The debug output gives more information about what BitBake | 210 | The debug output gives more information about what BitBake |
| 211 | is doing and the reason behind it. | 211 | is doing and the reason behind it. |
| 212 | Each <filename>-D</filename> option you use increases the logging level. | 212 | Each <filename>-D</filename> option you use increases the logging level. |
| 213 | The most common usage is <filename>-DDD</filename>. | 213 | The most common usage is <filename>-DDD</filename>. |
| 214 | </para> | 214 | </para> |
| @@ -217,7 +217,7 @@ | |||
| 217 | The output from <filename>bitbake -DDD -v targetname</filename> can reveal why | 217 | The output from <filename>bitbake -DDD -v targetname</filename> can reveal why |
| 218 | BitBake chose a certain version of a package or why BitBake | 218 | BitBake chose a certain version of a package or why BitBake |
| 219 | picked a certain provider. | 219 | picked a certain provider. |
| 220 | This command could also help you in a situation where you think BitBake did something | 220 | This command could also help you in a situation where you think BitBake did something |
| 221 | unexpected. | 221 | unexpected. |
| 222 | </para> | 222 | </para> |
| 223 | </section> | 223 | </section> |
| @@ -226,9 +226,9 @@ | |||
| 226 | <title>Building with No Dependencies</title> | 226 | <title>Building with No Dependencies</title> |
| 227 | <para> | 227 | <para> |
| 228 | If you really want to build a specific <filename>.bb</filename> file, you can use | 228 | If you really want to build a specific <filename>.bb</filename> file, you can use |
| 229 | the command form <filename>bitbake -b <somepath/somefile.bb></filename>. | 229 | the command form <filename>bitbake -b <somepath/somefile.bb></filename>. |
| 230 | This command form does not check for dependencies so you should use it | 230 | This command form does not check for dependencies so you should use it |
| 231 | only when you know its dependencies already exist. | 231 | only when you know its dependencies already exist. |
| 232 | You can also specify fragments of the filename. | 232 | You can also specify fragments of the filename. |
| 233 | In this case, BitBake checks for a unique match. | 233 | In this case, BitBake checks for a unique match. |
| 234 | </para> | 234 | </para> |
| @@ -243,31 +243,31 @@ | |||
| 243 | to show the environment from parsing a single recipe file only. | 243 | to show the environment from parsing a single recipe file only. |
| 244 | </para> | 244 | </para> |
| 245 | </section> | 245 | </section> |
| 246 | 246 | ||
| 247 | <section id='recipe-logging-mechanisms'> | 247 | <section id='recipe-logging-mechanisms'> |
| 248 | <title>Recipe Logging Mechanisms</title> | 248 | <title>Recipe Logging Mechanisms</title> |
| 249 | <para> | 249 | <para> |
| 250 | Best practices exist while writing recipes that both log build progress and | 250 | Best practices exist while writing recipes that both log build progress and |
| 251 | act on build conditions such as warnings and errors. | 251 | act on build conditions such as warnings and errors. |
| 252 | Both Python and Bash language bindings exist for the logging mechanism: | 252 | Both Python and Bash language bindings exist for the logging mechanism: |
| 253 | <itemizedlist> | 253 | <itemizedlist> |
| 254 | <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake | 254 | <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake |
| 255 | supports several loglevels: <filename>bb.fatal</filename>, | 255 | supports several loglevels: <filename>bb.fatal</filename>, |
| 256 | <filename>bb.error</filename>, <filename>bb.warn</filename>, | 256 | <filename>bb.error</filename>, <filename>bb.warn</filename>, |
| 257 | <filename>bb.note</filename>, <filename>bb.plain</filename>, | 257 | <filename>bb.note</filename>, <filename>bb.plain</filename>, |
| 258 | and <filename>bb.debug</filename>.</para></listitem> | 258 | and <filename>bb.debug</filename>.</para></listitem> |
| 259 | <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set | 259 | <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set |
| 260 | of loglevels exist and are accessed with a similar syntax: | 260 | of loglevels exist and are accessed with a similar syntax: |
| 261 | <filename>bbfatal</filename>, <filename>bberror</filename>, | 261 | <filename>bbfatal</filename>, <filename>bberror</filename>, |
| 262 | <filename>bbwarn</filename>, <filename>bbnote</filename>, | 262 | <filename>bbwarn</filename>, <filename>bbnote</filename>, |
| 263 | <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem> | 263 | <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem> |
| 264 | </itemizedlist> | 264 | </itemizedlist> |
| 265 | </para> | 265 | </para> |
| 266 | 266 | ||
| 267 | <para> | 267 | <para> |
| 268 | For guidance on how logging is handled in both Python and Bash recipes, see the | 268 | For guidance on how logging is handled in both Python and Bash recipes, see the |
| 269 | <filename>logging.bbclass</filename> file in the | 269 | <filename>logging.bbclass</filename> file in the |
| 270 | <filename>meta/classes</filename> folder of the | 270 | <filename>meta/classes</filename> folder of the |
| 271 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | 271 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 272 | </para> | 272 | </para> |
| 273 | 273 | ||
| @@ -275,14 +275,14 @@ | |||
| 275 | <title>Logging With Python</title> | 275 | <title>Logging With Python</title> |
| 276 | <para> | 276 | <para> |
| 277 | When creating recipes using Python and inserting code that handles build logs | 277 | When creating recipes using Python and inserting code that handles build logs |
| 278 | keep in mind the goal is to have informative logs while keeping the console as | 278 | keep in mind the goal is to have informative logs while keeping the console as |
| 279 | "silent" as possible. | 279 | "silent" as possible. |
| 280 | Also, if you want status messages in the log use the "debug" loglevel. | 280 | Also, if you want status messages in the log use the "debug" loglevel. |
| 281 | </para> | 281 | </para> |
| 282 | 282 | ||
| 283 | <para> | 283 | <para> |
| 284 | Following is an example written in Python. | 284 | Following is an example written in Python. |
| 285 | The code handles logging for a function that determines the number of tasks | 285 | The code handles logging for a function that determines the number of tasks |
| 286 | needed to be run: | 286 | needed to be run: |
| 287 | <literallayout class='monospaced'> | 287 | <literallayout class='monospaced'> |
| 288 | python do_listtasks() { | 288 | python do_listtasks() { |
| @@ -307,8 +307,8 @@ | |||
| 307 | <title>Logging With Bash</title> | 307 | <title>Logging With Bash</title> |
| 308 | <para> | 308 | <para> |
| 309 | When creating recipes using Bash and inserting code that handles build | 309 | When creating recipes using Bash and inserting code that handles build |
| 310 | logs you have the same goals - informative with minimal console output. | 310 | logs you have the same goals - informative with minimal console output. |
| 311 | The syntax you use for recipes written in Bash is similar to that of | 311 | The syntax you use for recipes written in Bash is similar to that of |
| 312 | recipes written in Python described in the previous section. | 312 | recipes written in Python described in the previous section. |
| 313 | </para> | 313 | </para> |
| 314 | 314 | ||
| @@ -337,22 +337,22 @@ | |||
| 337 | </para> | 337 | </para> |
| 338 | </section> | 338 | </section> |
| 339 | </section> | 339 | </section> |
| 340 | 340 | ||
| 341 | <section id='usingpoky-debugging-others'> | 341 | <section id='usingpoky-debugging-others'> |
| 342 | <title>Other Tips</title> | 342 | <title>Other Tips</title> |
| 343 | 343 | ||
| 344 | <para> | 344 | <para> |
| 345 | Here are some other tips that you might find useful: | 345 | Here are some other tips that you might find useful: |
| 346 | <itemizedlist> | 346 | <itemizedlist> |
| 347 | <listitem><para>When adding new packages, it is worth watching for | 347 | <listitem><para>When adding new packages, it is worth watching for |
| 348 | undesirable items making their way into compiler command lines. | 348 | undesirable items making their way into compiler command lines. |
| 349 | For example, you do not want references to local system files like | 349 | For example, you do not want references to local system files like |
| 350 | <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>. | 350 | <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>. |
| 351 | </para></listitem> | 351 | </para></listitem> |
| 352 | <listitem><para>If you want to remove the psplash boot splashscreen, | 352 | <listitem><para>If you want to remove the psplash boot splashscreen, |
| 353 | add <filename>psplash=false</filename> to the kernel command line. | 353 | add <filename>psplash=false</filename> to the kernel command line. |
| 354 | Doing so prevents psplash from loading and thus allows you to see the console. | 354 | Doing so prevents psplash from loading and thus allows you to see the console. |
| 355 | It is also possible to switch out of the splashscreen by | 355 | It is also possible to switch out of the splashscreen by |
| 356 | switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). | 356 | switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). |
| 357 | </para></listitem> | 357 | </para></listitem> |
| 358 | </itemizedlist> | 358 | </itemizedlist> |
| @@ -365,25 +365,25 @@ | |||
| 365 | 365 | ||
| 366 | <para> | 366 | <para> |
| 367 | A build's quality can be influenced by many things. | 367 | A build's quality can be influenced by many things. |
| 368 | For example, if you upgrade a recipe to use a new version of an upstream software | 368 | For example, if you upgrade a recipe to use a new version of an upstream software |
| 369 | package or you experiment with some new configuration options, subtle changes | 369 | package or you experiment with some new configuration options, subtle changes |
| 370 | can occur that you might not detect until later. | 370 | can occur that you might not detect until later. |
| 371 | Consider the case where your recipe is using a newer version of an upstream package. | 371 | Consider the case where your recipe is using a newer version of an upstream package. |
| 372 | In this case, a new version of a piece of software might introduce an optional | 372 | In this case, a new version of a piece of software might introduce an optional |
| 373 | dependency on another library, which is auto-detected. | 373 | dependency on another library, which is auto-detected. |
| 374 | If that library has already been built when the software is building, | 374 | If that library has already been built when the software is building, |
| 375 | then the software will link to the built library and that library will be pulled | 375 | then the software will link to the built library and that library will be pulled |
| 376 | into your image along with the new software even if you did not want the | 376 | into your image along with the new software even if you did not want the |
| 377 | library. | 377 | library. |
| 378 | </para> | 378 | </para> |
| 379 | 379 | ||
| 380 | <para> | 380 | <para> |
| 381 | The <filename>buildhistory</filename> class exists to help you maintain | 381 | The <filename>buildhistory</filename> class exists to help you maintain |
| 382 | the quality of your build output. | 382 | the quality of your build output. |
| 383 | You can use the class to highlight unexpected and possibly unwanted | 383 | You can use the class to highlight unexpected and possibly unwanted |
| 384 | changes in the build output. | 384 | changes in the build output. |
| 385 | When you enable build history it records information about the contents of | 385 | When you enable build history it records information about the contents of |
| 386 | each package and image and then commits that information to a local Git | 386 | each package and image and then commits that information to a local Git |
| 387 | repository where you can examine the information. | 387 | repository where you can examine the information. |
| 388 | </para> | 388 | </para> |
| 389 | 389 | ||
| @@ -396,7 +396,7 @@ | |||
| 396 | </para></listitem> | 396 | </para></listitem> |
| 397 | <listitem><para>How to limit the information used for build history | 397 | <listitem><para>How to limit the information used for build history |
| 398 | </para></listitem> | 398 | </para></listitem> |
| 399 | <listitem><para>How to examine the build history from both a | 399 | <listitem><para>How to examine the build history from both a |
| 400 | command-line and web interface</para></listitem> | 400 | command-line and web interface</para></listitem> |
| 401 | </itemizedlist> | 401 | </itemizedlist> |
| 402 | </para> | 402 | </para> |
| @@ -406,41 +406,41 @@ | |||
| 406 | 406 | ||
| 407 | <para> | 407 | <para> |
| 408 | Build history is disabled by default. | 408 | Build history is disabled by default. |
| 409 | To enable it, add the following statements to the end of your | 409 | To enable it, add the following statements to the end of your |
| 410 | <filename>conf/local.conf</filename> file found in the | 410 | <filename>conf/local.conf</filename> file found in the |
| 411 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: | 411 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: |
| 412 | <literallayout class='monospaced'> | 412 | <literallayout class='monospaced'> |
| 413 | INHERIT += "buildhistory" | 413 | INHERIT += "buildhistory" |
| 414 | BUILDHISTORY_COMMIT = "1" | 414 | BUILDHISTORY_COMMIT = "1" |
| 415 | </literallayout> | 415 | </literallayout> |
| 416 | Enabling build history as previously described | 416 | Enabling build history as previously described |
| 417 | causes the build process to collect build | 417 | causes the build process to collect build |
| 418 | output information and commit it to a local | 418 | output information and commit it to a local |
| 419 | <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository. | 419 | <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository. |
| 420 | <note> | 420 | <note> |
| 421 | Enabling build history increases your build times slightly, | 421 | Enabling build history increases your build times slightly, |
| 422 | particularly for images, and increases the amount of disk | 422 | particularly for images, and increases the amount of disk |
| 423 | space used during the build. | 423 | space used during the build. |
| 424 | </note> | 424 | </note> |
| 425 | </para> | 425 | </para> |
| 426 | 426 | ||
| 427 | <para> | 427 | <para> |
| 428 | You can disable build history by removing the previous statements | 428 | You can disable build history by removing the previous statements |
| 429 | from your <filename>conf/local.conf</filename> file. | 429 | from your <filename>conf/local.conf</filename> file. |
| 430 | However, you should realize that enabling and disabling | 430 | However, you should realize that enabling and disabling |
| 431 | build history in this manner can change the | 431 | build history in this manner can change the |
| 432 | <filename>do_package</filename> task checksums, which if you | 432 | <filename>do_package</filename> task checksums, which if you |
| 433 | are using the OEBasicHash signature generator (the default | 433 | are using the OEBasicHash signature generator (the default |
| 434 | for many current distro configurations including | 434 | for many current distro configurations including |
| 435 | <filename>DISTRO = "poky"</filename> and | 435 | <filename>DISTRO = "poky"</filename> and |
| 436 | <filename>DISTRO = ""</filename>) will result in the packaging | 436 | <filename>DISTRO = ""</filename>) will result in the packaging |
| 437 | tasks being re-run during the subsequent build. | 437 | tasks being re-run during the subsequent build. |
| 438 | </para> | 438 | </para> |
| 439 | 439 | ||
| 440 | <para> | 440 | <para> |
| 441 | To disable the build history functionality without causing the | 441 | To disable the build history functionality without causing the |
| 442 | packaging tasks to be re-run, add just this statement to your | 442 | packaging tasks to be re-run, add just this statement to your |
| 443 | <filename>conf/local.conf</filename> file: | 443 | <filename>conf/local.conf</filename> file: |
| 444 | <literallayout class='monospaced'> | 444 | <literallayout class='monospaced'> |
| 445 | BUILDHISTORY_FEATURES = "" | 445 | BUILDHISTORY_FEATURES = "" |
| 446 | </literallayout> | 446 | </literallayout> |
| @@ -451,19 +451,19 @@ | |||
| 451 | <title>Understanding What the Build History Contains</title> | 451 | <title>Understanding What the Build History Contains</title> |
| 452 | 452 | ||
| 453 | <para> | 453 | <para> |
| 454 | Build history information is kept in | 454 | Build history information is kept in |
| 455 | <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename> | 455 | <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename> |
| 456 | in the Build Directory. | 456 | in the Build Directory. |
| 457 | The following is an example abbreviated listing: | 457 | The following is an example abbreviated listing: |
| 458 | <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" /> | 458 | <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" /> |
| 459 | </para> | 459 | </para> |
| 460 | 460 | ||
| 461 | <section id='build-history-package-information'> | 461 | <section id='build-history-package-information'> |
| 462 | <title>Build History Package Information</title> | 462 | <title>Build History Package Information</title> |
| 463 | 463 | ||
| 464 | <para> | 464 | <para> |
| 465 | The history for each package contains a text file that has | 465 | The history for each package contains a text file that has |
| 466 | name-value pairs with information about the package. | 466 | name-value pairs with information about the package. |
| 467 | For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename> | 467 | For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename> |
| 468 | contains the following: | 468 | contains the following: |
| 469 | <literallayout class='monospaced'> | 469 | <literallayout class='monospaced'> |
| @@ -474,21 +474,21 @@ | |||
| 474 | PKGSIZE = 564701 | 474 | PKGSIZE = 564701 |
| 475 | FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \ | 475 | FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \ |
| 476 | /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \ | 476 | /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \ |
| 477 | /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \ | 477 | /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \ |
| 478 | /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers | 478 | /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers |
| 479 | FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh | 479 | FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh |
| 480 | </literallayout> | 480 | </literallayout> |
| 481 | Most of these name-value pairs corresponds to variables used | 481 | Most of these name-value pairs corresponds to variables used |
| 482 | to produce the package. | 482 | to produce the package. |
| 483 | The exceptions are <filename>FILELIST</filename>, which is the | 483 | The exceptions are <filename>FILELIST</filename>, which is the |
| 484 | actual list of files in the package, and | 484 | actual list of files in the package, and |
| 485 | <filename>PKGSIZE</filename>, which is the total size of files | 485 | <filename>PKGSIZE</filename>, which is the total size of files |
| 486 | in the package in bytes. | 486 | in the package in bytes. |
| 487 | </para> | 487 | </para> |
| 488 | 488 | ||
| 489 | <para> | 489 | <para> |
| 490 | There is also a file corresponding to the recipe from which the | 490 | There is also a file corresponding to the recipe from which the |
| 491 | package came (e.g. | 491 | package came (e.g. |
| 492 | <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>): | 492 | <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>): |
| 493 | <literallayout class='monospaced'> | 493 | <literallayout class='monospaced'> |
| 494 | PV = 1.19.3 | 494 | PV = 1.19.3 |
| @@ -509,18 +509,18 @@ | |||
| 509 | The files produced for each image are as follows: | 509 | The files produced for each image are as follows: |
| 510 | <itemizedlist> | 510 | <itemizedlist> |
| 511 | <listitem><para><emphasis>build-id:</emphasis> | 511 | <listitem><para><emphasis>build-id:</emphasis> |
| 512 | Human-readable information about the build configuration | 512 | Human-readable information about the build configuration |
| 513 | and metadata source revisions.</para></listitem> | 513 | and metadata source revisions.</para></listitem> |
| 514 | <listitem><para><emphasis>*.dot:</emphasis> | 514 | <listitem><para><emphasis>*.dot:</emphasis> |
| 515 | Dependency graphs for the image that are | 515 | Dependency graphs for the image that are |
| 516 | compatible with <filename>graphviz</filename>. | 516 | compatible with <filename>graphviz</filename>. |
| 517 | </para></listitem> | 517 | </para></listitem> |
| 518 | <listitem><para><emphasis>files-in-image.txt:</emphasis> | 518 | <listitem><para><emphasis>files-in-image.txt:</emphasis> |
| 519 | A list of files in the image with permissions, | 519 | A list of files in the image with permissions, |
| 520 | owner, group, size, and symlink information. | 520 | owner, group, size, and symlink information. |
| 521 | </para></listitem> | 521 | </para></listitem> |
| 522 | <listitem><para><emphasis>image-info.txt:</emphasis> | 522 | <listitem><para><emphasis>image-info.txt:</emphasis> |
| 523 | A text file containing name-value pairs with information | 523 | A text file containing name-value pairs with information |
| 524 | about the image. | 524 | about the image. |
| 525 | See the following listing example for more information. | 525 | See the following listing example for more information. |
| 526 | </para></listitem> | 526 | </para></listitem> |
| @@ -535,7 +535,7 @@ | |||
| 535 | </itemizedlist> | 535 | </itemizedlist> |
| 536 | <note> | 536 | <note> |
| 537 | Installed package information is able to be gathered and | 537 | Installed package information is able to be gathered and |
| 538 | produced even if package management is disabled for the final | 538 | produced even if package management is disabled for the final |
| 539 | image. | 539 | image. |
| 540 | </note> | 540 | </note> |
| 541 | </para> | 541 | </para> |
| @@ -551,15 +551,15 @@ | |||
| 551 | package-management ssh-server-dropbear package-management | 551 | package-management ssh-server-dropbear package-management |
| 552 | IMAGE_LINGUAS = en-us en-gb | 552 | IMAGE_LINGUAS = en-us en-gb |
| 553 | IMAGE_INSTALL = task-core-boot task-base-extended | 553 | IMAGE_INSTALL = task-core-boot task-base-extended |
| 554 | BAD_RECOMMENDATIONS = | 554 | BAD_RECOMMENDATIONS = |
| 555 | ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; | 555 | ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; |
| 556 | IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; | 556 | IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; |
| 557 | IMAGESIZE = 171816 | 557 | IMAGESIZE = 171816 |
| 558 | </literallayout> | 558 | </literallayout> |
| 559 | Other than <filename>IMAGESIZE</filename>, which is the | 559 | Other than <filename>IMAGESIZE</filename>, which is the |
| 560 | total size of the files in the image in Kbytes, the | 560 | total size of the files in the image in Kbytes, the |
| 561 | name-value pairs are variables that may have influenced the | 561 | name-value pairs are variables that may have influenced the |
| 562 | content of the image. | 562 | content of the image. |
| 563 | This information is often useful when you are trying to determine | 563 | This information is often useful when you are trying to determine |
| 564 | why a change in the package or file listings has occurred. | 564 | why a change in the package or file listings has occurred. |
| 565 | </para> | 565 | </para> |
| @@ -568,15 +568,15 @@ | |||
| 568 | <section id='using-build-history-to-gather-image-information-only'> | 568 | <section id='using-build-history-to-gather-image-information-only'> |
| 569 | <title>Using Build History to Gather Image Information Only</title> | 569 | <title>Using Build History to Gather Image Information Only</title> |
| 570 | 570 | ||
| 571 | <para> | 571 | <para> |
| 572 | As you can see, build history produces image information, | 572 | As you can see, build history produces image information, |
| 573 | including dependency graphs, so you can see why something | 573 | including dependency graphs, so you can see why something |
| 574 | was pulled into the image. | 574 | was pulled into the image. |
| 575 | If you are just interested in this information and not | 575 | If you are just interested in this information and not |
| 576 | interested in collecting history or any package information, | 576 | interested in collecting history or any package information, |
| 577 | you can enable writing only image information without | 577 | you can enable writing only image information without |
| 578 | any history by adding the following | 578 | any history by adding the following |
| 579 | to your <filename>conf/local.conf</filename> file found in the | 579 | to your <filename>conf/local.conf</filename> file found in the |
| 580 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: | 580 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: |
| 581 | <literallayout class='monospaced'> | 581 | <literallayout class='monospaced'> |
| 582 | INHERIT += "buildhistory" | 582 | INHERIT += "buildhistory" |
| @@ -590,28 +590,28 @@ | |||
| 590 | <title>Examining Build History Information</title> | 590 | <title>Examining Build History Information</title> |
| 591 | 591 | ||
| 592 | <para> | 592 | <para> |
| 593 | You can examine build history output from the command line or | 593 | You can examine build history output from the command line or |
| 594 | from a web interface. | 594 | from a web interface. |
| 595 | </para> | 595 | </para> |
| 596 | 596 | ||
| 597 | <para> | 597 | <para> |
| 598 | To see any changes that have occurred (assuming you have | 598 | To see any changes that have occurred (assuming you have |
| 599 | <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply | 599 | <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply |
| 600 | use any Git command that allows you to view the history of | 600 | use any Git command that allows you to view the history of |
| 601 | a repository. | 601 | a repository. |
| 602 | Here is one method: | 602 | Here is one method: |
| 603 | <literallayout class='monospaced'> | 603 | <literallayout class='monospaced'> |
| 604 | $ git log -p | 604 | $ git log -p |
| 605 | </literallayout> | 605 | </literallayout> |
| 606 | You need to realize, however, that this method does show | 606 | You need to realize, however, that this method does show |
| 607 | changes that are not significant (e.g. a package's size | 607 | changes that are not significant (e.g. a package's size |
| 608 | changing by a few bytes). | 608 | changing by a few bytes). |
| 609 | </para> | 609 | </para> |
| 610 | 610 | ||
| 611 | <para> | 611 | <para> |
| 612 | A command-line tool called <filename>buildhistory-diff</filename> | 612 | A command-line tool called <filename>buildhistory-diff</filename> |
| 613 | does exist though that queries the Git repository and prints just | 613 | does exist though that queries the Git repository and prints just |
| 614 | the differences that might be significant in human-readable form. | 614 | the differences that might be significant in human-readable form. |
| 615 | Here is an example: | 615 | Here is an example: |
| 616 | <literallayout class='monospaced'> | 616 | <literallayout class='monospaced'> |
| 617 | $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ | 617 | $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ |
| @@ -632,7 +632,7 @@ | |||
| 632 | </para> | 632 | </para> |
| 633 | 633 | ||
| 634 | <para> | 634 | <para> |
| 635 | To see changes to the build history using a web interface, follow | 635 | To see changes to the build history using a web interface, follow |
| 636 | the instruction in the <filename>README</filename> file here. | 636 | the instruction in the <filename>README</filename> file here. |
| 637 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>. | 637 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>. |
| 638 | </para> | 638 | </para> |
| @@ -646,6 +646,6 @@ | |||
| 646 | </section> | 646 | </section> |
| 647 | 647 | ||
| 648 | </chapter> | 648 | </chapter> |
| 649 | <!-- | 649 | <!-- |
| 650 | vim: expandtab tw=80 ts=4 | 650 | vim: expandtab tw=80 ts=4 |
| 651 | --> | 651 | --> |
