From 73ffb8298b545a1a1fb96bc5952b7365c4c43bfd Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 7 Dec 2012 17:29:51 -0600 Subject: Documentation: poky-ref-manual - Removed all trailing whitespace. (From yocto-docs rev: 564a28c2501034ea7e2eb16afc43dfaf931b6f6f) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/usingpoky.xml | 264 ++++++++++++++-------------- 1 file changed, 132 insertions(+), 132 deletions(-) (limited to 'documentation/poky-ref-manual/usingpoky.xml') 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 @@ This section provides a summary of the build process and provides information for less obvious aspects of the build process. - For general information on how to build an image using the OpenEmbedded build - system, see the + For general information on how to build an image using the OpenEmbedded build + system, see the "Building an Image" section of the Yocto Project Quick Start. @@ -35,12 +35,12 @@ - The build_dir is optional and specifies the directory the - OpenEmbedded build system uses for the build - + The build_dir is optional and specifies the directory the + OpenEmbedded build system uses for the build - the Build Directory. If you do not specify a Build Directory it defaults to build in your current working directory. - A common practice is to use a different Build Directory for different targets. + A common practice is to use a different Build Directory for different targets. For example, ~/build/x86 for a qemux86 target, and ~/build/arm for a qemuarm target. See &OE_INIT_FILE; @@ -55,13 +55,13 @@ - The target is the name of the recipe you want to build. + The target is the name of the recipe you want to build. Common targets are the images in meta/recipes-core/images, - /meta/recipes-sato/images, etc. all found in the + /meta/recipes-sato/images, etc. all found in the Source Directory. - Or, the target can be the name of a recipe for a specific piece of software such as - busybox. - For more details about the images the OpenEmbedded build system supports, see the + Or, the target can be the name of a recipe for a specific piece of software such as + busybox. + For more details about the images the OpenEmbedded build system supports, see the "Images" chapter. @@ -76,9 +76,9 @@ Building an Image Using GPL Components - When building an image using GPL components, you need to maintain your original + When building an image using GPL components, you need to maintain your original settings and not switch back and forth applying different versions of the GNU - General Public License. + General Public License. If you rebuild using different versions of GPL, dependency errors might occur due to some components not being rebuilt. @@ -89,11 +89,11 @@ Installing and Using the Result - Once an image has been built, it often needs to be installed. - The images and kernels built by the OpenEmbedded build system are placed in the - Build Directory in - tmp/deploy/images. - For information on how to run pre-built images such as qemux86 + Once an image has been built, it often needs to be installed. + The images and kernels built by the OpenEmbedded build system are placed in the + Build Directory in + tmp/deploy/images. + For information on how to run pre-built images such as qemux86 and qemuarm, see the "Using Pre-Built Binaries and QEMU" section in the Yocto Project Quick Start. @@ -106,25 +106,25 @@ Debugging Build Failures - The exact method for debugging build failures depends on the nature of the - problem and on the system's area from which the bug originates. - Standard debugging practices such as comparison against the last - known working version with examination of the changes and the re-application of steps + The exact method for debugging build failures depends on the nature of the + problem and on the system's area from which the bug originates. + Standard debugging practices such as comparison against the last + known working version with examination of the changes and the re-application of steps to identify the one causing the problem are - valid for the Yocto Project just as they are for any other system. - Even though it is impossible to detail every possible potential failure, + valid for the Yocto Project just as they are for any other system. + Even though it is impossible to detail every possible potential failure, this section provides some general tips to aid in debugging.
Task Failures - The log file for shell tasks is available in - ${WORKDIR}/temp/log.do_taskname.pid. + The log file for shell tasks is available in + ${WORKDIR}/temp/log.do_taskname.pid. For example, the compile task for the QEMU minimal image for the x86 - machine (qemux86) might be + machine (qemux86) might be tmp/work/qemux86-poky-linux/core-image-minimal-1.0-r0/temp/log.do_compile.20830. - To see what BitBake runs to generate that log, look at the corresponding + To see what BitBake runs to generate that log, look at the corresponding run.do_taskname.pid file located in the same directory. @@ -137,17 +137,17 @@ Running Specific Tasks - Any given package consists of a set of tasks. - The standard BitBake behavior in most cases is: fetch, - unpack, + Any given package consists of a set of tasks. + The standard BitBake behavior in most cases is: fetch, + unpack, patch, configure, compile, install, package, - package_write, and build. - The default task is build and any tasks on which it depends + package_write, and build. + The default task is build and any tasks on which it depends build first. Some tasks exist, such as devshell, that are not part of the - default build chain. - If you wish to run a task that is not part of the default build chain, you can use the + default build chain. + If you wish to run a task that is not part of the default build chain, you can use the -c option in BitBake as follows: $ bitbake matchbox-desktop -c devshell @@ -155,8 +155,8 @@ - If you wish to rerun a task, use the -f force option. - For example, the following sequence forces recompilation after changing files in the + If you wish to rerun a task, use the -f force option. + For example, the following sequence forces recompilation after changing files in the working directory. $ bitbake matchbox-desktop @@ -173,7 +173,7 @@ This sequence first builds matchbox-desktop and then recompiles it. The last command reruns all tasks (basically the packaging tasks) after the compile. - BitBake recognizes that the compile task was rerun and therefore + BitBake recognizes that the compile task was rerun and therefore understands that the other tasks also need to be run again. @@ -191,13 +191,13 @@ Dependency Graphs - Sometimes it can be hard to see why BitBake wants to build some other packages before a given + Sometimes it can be hard to see why BitBake wants to build some other packages before a given package you have specified. - The bitbake -g targetname command creates the + The bitbake -g targetname command creates the depends.dot, package-depends.dot, - and task-depends.dot files in the current directory. + and task-depends.dot files in the current directory. These files show the package and task dependencies and are useful for debugging problems. - You can use the bitbake -g -u depexp targetname command to + You can use the bitbake -g -u depexp targetname command to display the results in a more human-readable form.
@@ -208,7 +208,7 @@ You can see debug output from BitBake by using the -D option. The debug output gives more information about what BitBake - is doing and the reason behind it. + is doing and the reason behind it. Each -D option you use increases the logging level. The most common usage is -DDD. @@ -217,7 +217,7 @@ The output from bitbake -DDD -v targetname can reveal why BitBake chose a certain version of a package or why BitBake picked a certain provider. - This command could also help you in a situation where you think BitBake did something + This command could also help you in a situation where you think BitBake did something unexpected. @@ -226,9 +226,9 @@ Building with No Dependencies If you really want to build a specific .bb file, you can use - the command form bitbake -b <somepath/somefile.bb>. + the command form bitbake -b <somepath/somefile.bb>. This command form does not check for dependencies so you should use it - only when you know its dependencies already exist. + only when you know its dependencies already exist. You can also specify fragments of the filename. In this case, BitBake checks for a unique match. @@ -243,31 +243,31 @@ to show the environment from parsing a single recipe file only. - +
Recipe Logging Mechanisms - Best practices exist while writing recipes that both log build progress and - act on build conditions such as warnings and errors. + Best practices exist while writing recipes that both log build progress and + act on build conditions such as warnings and errors. Both Python and Bash language bindings exist for the logging mechanism: Python: For Python functions, BitBake - supports several loglevels: bb.fatal, + supports several loglevels: bb.fatal, bb.error, bb.warn, bb.note, bb.plain, and bb.debug. - Bash: For Bash functions, the same set + Bash: For Bash functions, the same set of loglevels exist and are accessed with a similar syntax: - bbfatal, bberror, - bbwarn, bbnote, + bbfatal, bberror, + bbwarn, bbnote, bbplain, and bbdebug. - For guidance on how logging is handled in both Python and Bash recipes, see the - logging.bbclass file in the - meta/classes folder of the + For guidance on how logging is handled in both Python and Bash recipes, see the + logging.bbclass file in the + meta/classes folder of the Source Directory. @@ -275,14 +275,14 @@ Logging With Python When creating recipes using Python and inserting code that handles build logs - keep in mind the goal is to have informative logs while keeping the console as - "silent" as possible. + keep in mind the goal is to have informative logs while keeping the console as + "silent" as possible. Also, if you want status messages in the log use the "debug" loglevel. Following is an example written in Python. - The code handles logging for a function that determines the number of tasks + The code handles logging for a function that determines the number of tasks needed to be run: python do_listtasks() { @@ -307,8 +307,8 @@ Logging With Bash When creating recipes using Bash and inserting code that handles build - logs you have the same goals - informative with minimal console output. - The syntax you use for recipes written in Bash is similar to that of + logs you have the same goals - informative with minimal console output. + The syntax you use for recipes written in Bash is similar to that of recipes written in Python described in the previous section. @@ -337,22 +337,22 @@
- +
Other Tips Here are some other tips that you might find useful: - When adding new packages, it is worth watching for + When adding new packages, it is worth watching for undesirable items making their way into compiler command lines. - For example, you do not want references to local system files like + For example, you do not want references to local system files like /usr/lib/ or /usr/include/. - If you want to remove the psplash boot splashscreen, + If you want to remove the psplash boot splashscreen, add psplash=false to the kernel command line. Doing so prevents psplash from loading and thus allows you to see the console. - It is also possible to switch out of the splashscreen by + It is also possible to switch out of the splashscreen by switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). @@ -365,25 +365,25 @@ A build's quality can be influenced by many things. - For example, if you upgrade a recipe to use a new version of an upstream software + For example, if you upgrade a recipe to use a new version of an upstream software package or you experiment with some new configuration options, subtle changes - can occur that you might not detect until later. + can occur that you might not detect until later. Consider the case where your recipe is using a newer version of an upstream package. - In this case, a new version of a piece of software might introduce an optional + In this case, a new version of a piece of software might introduce an optional dependency on another library, which is auto-detected. - If that library has already been built when the software is building, - then the software will link to the built library and that library will be pulled - into your image along with the new software even if you did not want the + If that library has already been built when the software is building, + then the software will link to the built library and that library will be pulled + into your image along with the new software even if you did not want the library. The buildhistory class exists to help you maintain the quality of your build output. - You can use the class to highlight unexpected and possibly unwanted + You can use the class to highlight unexpected and possibly unwanted changes in the build output. - When you enable build history it records information about the contents of - each package and image and then commits that information to a local Git + When you enable build history it records information about the contents of + each package and image and then commits that information to a local Git repository where you can examine the information. @@ -396,7 +396,7 @@ How to limit the information used for build history - How to examine the build history from both a + How to examine the build history from both a command-line and web interface @@ -406,41 +406,41 @@ Build history is disabled by default. - To enable it, add the following statements to the end of your - conf/local.conf file found in the + To enable it, add the following statements to the end of your + conf/local.conf file found in the Build Directory: INHERIT += "buildhistory" BUILDHISTORY_COMMIT = "1" - Enabling build history as previously described + Enabling build history as previously described causes the build process to collect build - output information and commit it to a local + output information and commit it to a local Git repository. - Enabling build history increases your build times slightly, + Enabling build history increases your build times slightly, particularly for images, and increases the amount of disk space used during the build. - + You can disable build history by removing the previous statements from your conf/local.conf file. - However, you should realize that enabling and disabling - build history in this manner can change the - do_package task checksums, which if you - are using the OEBasicHash signature generator (the default + However, you should realize that enabling and disabling + build history in this manner can change the + do_package task checksums, which if you + are using the OEBasicHash signature generator (the default for many current distro configurations including - DISTRO = "poky" and - DISTRO = "") will result in the packaging + DISTRO = "poky" and + DISTRO = "") will result in the packaging tasks being re-run during the subsequent build. - To disable the build history functionality without causing the - packaging tasks to be re-run, add just this statement to your - conf/local.conf file: + To disable the build history functionality without causing the + packaging tasks to be re-run, add just this statement to your + conf/local.conf file: BUILDHISTORY_FEATURES = "" @@ -451,19 +451,19 @@ Understanding What the Build History Contains - Build history information is kept in + Build history information is kept in $TMPDIR/buildhistory in the Build Directory. The following is an example abbreviated listing: - +
Build History Package Information The history for each package contains a text file that has - name-value pairs with information about the package. + name-value pairs with information about the package. For example, buildhistory/packages/core2-poky-linux/busybox/busybox/latest contains the following: @@ -474,21 +474,21 @@ PKGSIZE = 564701 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \ /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \ - /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \ + /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \ /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh - Most of these name-value pairs corresponds to variables used + Most of these name-value pairs corresponds to variables used to produce the package. - The exceptions are FILELIST, which is the - actual list of files in the package, and - PKGSIZE, which is the total size of files + The exceptions are FILELIST, which is the + actual list of files in the package, and + PKGSIZE, which is the total size of files in the package in bytes. - There is also a file corresponding to the recipe from which the - package came (e.g. + There is also a file corresponding to the recipe from which the + package came (e.g. buildhistory/packages/core2-poky-linux/busybox/latest): PV = 1.19.3 @@ -509,18 +509,18 @@ The files produced for each image are as follows: build-id: - Human-readable information about the build configuration + Human-readable information about the build configuration and metadata source revisions. *.dot: - Dependency graphs for the image that are + Dependency graphs for the image that are compatible with graphviz. files-in-image.txt: - A list of files in the image with permissions, + A list of files in the image with permissions, owner, group, size, and symlink information. image-info.txt: - A text file containing name-value pairs with information + A text file containing name-value pairs with information about the image. See the following listing example for more information. @@ -535,7 +535,7 @@ Installed package information is able to be gathered and - produced even if package management is disabled for the final + produced even if package management is disabled for the final image. @@ -551,15 +551,15 @@ package-management ssh-server-dropbear package-management IMAGE_LINGUAS = en-us en-gb IMAGE_INSTALL = task-core-boot task-base-extended - BAD_RECOMMENDATIONS = - ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; - IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; + BAD_RECOMMENDATIONS = + ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; + IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; IMAGESIZE = 171816 Other than IMAGESIZE, which is the - total size of the files in the image in Kbytes, the - name-value pairs are variables that may have influenced the - content of the image. + total size of the files in the image in Kbytes, the + name-value pairs are variables that may have influenced the + content of the image. This information is often useful when you are trying to determine why a change in the package or file listings has occurred. @@ -568,15 +568,15 @@
Using Build History to Gather Image Information Only - - As you can see, build history produces image information, + + As you can see, build history produces image information, including dependency graphs, so you can see why something - was pulled into the image. - If you are just interested in this information and not - interested in collecting history or any package information, - you can enable writing only image information without - any history by adding the following - to your conf/local.conf file found in the + was pulled into the image. + If you are just interested in this information and not + interested in collecting history or any package information, + you can enable writing only image information without + any history by adding the following + to your conf/local.conf file found in the Build Directory: INHERIT += "buildhistory" @@ -590,28 +590,28 @@ Examining Build History Information - You can examine build history output from the command line or + You can examine build history output from the command line or from a web interface. - To see any changes that have occurred (assuming you have - BUILDHISTORY_COMMIT = "1"), you can simply - use any Git command that allows you to view the history of - a repository. + To see any changes that have occurred (assuming you have + BUILDHISTORY_COMMIT = "1"), you can simply + use any Git command that allows you to view the history of + a repository. Here is one method: - $ git log -p + $ git log -p - You need to realize, however, that this method does show - changes that are not significant (e.g. a package's size + You need to realize, however, that this method does show + changes that are not significant (e.g. a package's size changing by a few bytes). A command-line tool called buildhistory-diff - does exist though that queries the Git repository and prints just - the differences that might be significant in human-readable form. + does exist though that queries the Git repository and prints just + the differences that might be significant in human-readable form. Here is an example: $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ @@ -632,7 +632,7 @@ - To see changes to the build history using a web interface, follow + To see changes to the build history using a web interface, follow the instruction in the README file here. . @@ -646,6 +646,6 @@
- -- cgit v1.2.3-54-g00ecf