From c527fd1f14c27855a37f2e8ac5346ce8d940ced2 Mon Sep 17 00:00:00 2001 From: Tudor Florea Date: Thu, 16 Oct 2014 03:05:19 +0200 Subject: initial commit for Enea Linux 4.0-140929 Migrated from the internal git server on the daisy-enea-point-release branch Signed-off-by: Tudor Florea --- documentation/ref-manual/usingpoky.xml | 882 +++++++++++++++++++++++++++++++++ 1 file changed, 882 insertions(+) create mode 100644 documentation/ref-manual/usingpoky.xml (limited to 'documentation/ref-manual/usingpoky.xml') diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml new file mode 100644 index 0000000000..a8a6f3b92a --- /dev/null +++ b/documentation/ref-manual/usingpoky.xml @@ -0,0 +1,882 @@ + %poky; ] > + + +Using the Yocto Project + + + This chapter describes common usage for the Yocto Project. + The information is introductory in nature as other manuals in the Yocto Project + documentation set provide more details on how to use the Yocto Project. + + +
+ Running a Build + + + 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 + "Building an Image" + section of the Yocto Project Quick Start. + + +
+ Build Overview + + + The first thing you need to do is set up the OpenEmbedded build + environment by sourcing an environment setup script + (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + Here is an example: + + $ source &OE_INIT_FILE; [<build_dir>] + + + + + The build_dir argument 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 a directory + named build in your current working directory. + 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. + + + + Once the build environment is set up, you can build a target using: + + $ bitbake <target> + + + + + 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 + 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 + "Images" chapter. + + + + Building an image without GNU General Public License Version 3 (GPLv3) components + is supported for only minimal and base images. + See the "Images" chapter for more information. + +
+ +
+ Building an Image Using GPL Components + + + 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. + If you rebuild using different versions of GPL, dependency errors might occur + due to some components not being rebuilt. + +
+
+ +
+ 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 + and qemuarm, see the + "Using Pre-Built Binaries and QEMU" + section in the Yocto Project Quick Start. + For information about how to install these images, see the documentation for your + particular board or machine. + +
+ +
+ 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 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, + this section provides some general tips to aid in debugging. + + + + A useful feature for debugging is the error reporting tool. + Configuring the Yocto Project to use this tool causes the + OpenEmbedded build system to produce error reporting commands as + part of the console output. + You can enter the commands after the build completes + to log error information + into a common database, that can help you figure out what might be + going wrong. + For information on how to enable and use this feature, see the + "Using the Error Reporting Tool" + section in the Yocto Project Development Manual. + + + + For discussions on debugging, see the + "Debugging With the GNU Project Debugger (GDB) Remotely" + and + "Working within Eclipse" + sections in the Yocto Project Development Manual. + + + + The remainder of this section presents many examples of the + bitbake command. + You can learn about BitBake by reading the + BitBake User Manual. + + + +
+ Task Failures + + 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 + 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 + run.do_taskname.pid file located in the same directory. + + + + Presently, the output from Python tasks is sent directly to the console. + +
+ +
+ Running Specific Tasks + + + 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 + build first. + Some tasks, such as devshell, 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 + -c option in BitBake. + Here is an example: + + $ bitbake matchbox-desktop -c devshell + + + + + If you wish to rerun a task, use the -f force + option. + For example, the following sequence forces recompilation after + changing files in the work directory. + + $ bitbake matchbox-desktop + . + . + [make some changes to the source code in the work directory] + . + . + $ bitbake matchbox-desktop -c compile -f + $ bitbake matchbox-desktop + + + + + This sequence first builds and then recompiles + matchbox-desktop. + The last command reruns all tasks (basically the packaging tasks) after the compile. + BitBake recognizes that the compile task was rerun and therefore + understands that the other tasks also need to be run again. + + + + You can view a list of tasks in a given package by running the + listtasks task as follows: + + $ bitbake matchbox-desktop -c listtasks + + The results appear as output to the console and are also in the + file ${WORKDIR}/temp/log.do_listtasks. + +
+ +
+ Dependency Graphs + + + Sometimes it can be hard to see why BitBake wants to build + other packages before building a given package you have specified. + The bitbake -g <targetname> command + creates the pn-buildlist, + pn-depends.dot, + package-depends.dot, and + task-depends.dot files in the current + directory. + These files show what will be built and the package and task + dependencies, which are useful for debugging problems. + You can use the + bitbake -g -u depexp <targetname> + command to display the results in a more human-readable form. + +
+ +
+ General BitBake Problems + + + 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. + Each -D option you use increases the logging level. + The most common usage is -DDD. + + + + 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 + unexpected. + +
+ +
+ Development Host System Issues + + + Sometimes issues on the host development system can cause your + build to fail. + Following are known, host-specific problems. + Be sure to always consult the + Release Notes + for a look at all release-related issues. + + eglibc-initial fails to build: + If your development host system has the unpatched + GNU Make 3.82, + the do_install task + fails for eglibc-initial during the + build. + Typically, every distribution that ships + GNU Make 3.82 as + the default already has the patched version. + However, some distributions, such as Debian, have + GNU Make 3.82 as an option, which + is unpatched. + You will see this error on these types of distributions. + Switch to GNU Make 3.81 or patch + your make to solve the problem. + + + +
+ +
+ Building with No Dependencies + + To build a specific recipe (.bb file), + you can use the following command form: + + $ bitbake -b <somepath/somerecipe.bb> + + This command form does not check for dependencies. + Consequently, you should use it + only when you know existing dependencies have been met. + + You can also specify fragments of the filename. + In this case, BitBake checks for a unique match. + + +
+ +
+ Variables + + You can use the -e BitBake option to + display the parsing environment for a configuration. + The following displays the general parsing environment: + + $ bitbake -e + + This next example shows the parsing environment for a specific + recipe: + + $ bitbake -e <recipename> + + +
+ +
+ Recipe Logging Mechanisms + + 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, + bb.error, bb.warn, + bb.note, bb.plain, + and bb.debug. + Bash: For Bash functions, the same set + of loglevels exist and are accessed with a similar syntax: + 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 + Source Directory. + + +
+ 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. + 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 + needed to be run: + + python do_listtasks() { + bb.debug(2, "Starting to figure out the task list") + if noteworthy_condition: + bb.note("There are 47 tasks to run") + bb.debug(2, "Got to point xyz") + if warning_trigger: + bb.warn("Detected warning_trigger, this might be a problem later.") + if recoverable_error: + bb.error("Hit recoverable_error, you really need to fix this!") + if fatal_error: + bb.fatal("fatal_error detected, unable to print the task list") + bb.plain("The tasks present are abc") + bb.debug(2, "Finished figuring out the tasklist") + } + + +
+ +
+ 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 + recipes written in Python described in the previous section. + + + + Following is an example written in Bash. + The code logs the progress of the do_my_function function. + + do_my_function() { + bbdebug 2 "Running do_my_function" + if [ exceptional_condition ]; then + bbnote "Hit exceptional_condition" + fi + bbdebug 2 "Got to point xyz" + if [ warning_trigger ]; then + bbwarn "Detected warning_trigger, this might cause a problem later." + fi + if [ recoverable_error ]; then + bberror "Hit recoverable_error, correcting" + fi + if [ fatal_error ]; then + bbfatal "fatal_error detected" + fi + bbdebug 2 "Completed do_my_function" + } + + +
+
+ +
+ Other Tips + + + Here are some other tips that you might find useful: + + 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 + /usr/lib/ or /usr/include/. + + 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 + switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). + + + +
+
+ +
+ Maintaining Build Output Quality + + + Many factors can influence the quality of a build. + 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. + 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 + dependency on another library, which is auto-detected. + If that library has already been built when the software is building, + 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 + 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 + repository where you can examine the information. + + + + The remainder of this section describes the following: + + How you can enable and disable + build history + How to understand what the build history contains + + How to limit the information used for build history + + How to examine the build history from both a + command-line and web interface + + + +
+ Enabling and Disabling Build History + + + Build history is disabled by default. + To enable it, add the following INHERIT + statement and set the + BUILDHISTORY_COMMIT + variable to "1" at the end of your + conf/local.conf file found in the + Build Directory: + + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "1" + + Enabling build history as previously described + causes the build process to collect build + output information and commit it to a local + Git repository. + + 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. + +
+ +
+ Understanding What the Build History Contains + + + Build history information is kept in + $TOPDIR/buildhistory + in the Build Directory as defined by the + BUILDHISTORY_DIR + variable. + The following is an example abbreviated listing: + + + + + At the top level, there is a metadata-revs file + that lists the revisions of the repositories for the layers enabled + when the build was produced. + The rest of the data splits into separate + packages, images and + sdk directories, the contents of which are + described below. + + +
+ Build History Package Information + + + The history for each package contains a text file that has + name-value pairs with information about the package. + For example, buildhistory/packages/core2-poky-linux/busybox/busybox/latest + contains the following: + + PV = 1.19.3 + PR = r3 + RDEPENDS = update-rc.d eglibc (>= 2.13) + RRECOMMENDS = busybox-syslog busybox-udhcpc + 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/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 correspond 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 + in the package in bytes. + + + + 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 + PR = r3 + DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \ + virtual/libc update-rc.d-native + PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \ + busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \ + busybox-staticdev busybox-locale + + + + + Finally, for those recipes fetched from a version control + system (e.g., Git), a file exists that lists source revisions + that are specified in the recipe and lists the actual revisions + used during the build. + Listed and actual revisions might differ when + SRCREV + is set to + ${AUTOREV}. + Here is an example assuming + buildhistory/packages/emenlow-poky-linux/linux-yocto/latest_srcrev): + + # SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf" + SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf" + # SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02" + SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02" + # SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24" + SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24" + + You can use the buildhistory-collect-srcrevs + command to collect the stored SRCREV values + from build history and report them in a format suitable for use in + global configuration (e.g., local.conf + or a distro include file) to override floating + AUTOREV values to a fixed set of revisions. + Here is some example output from this command: + + # emenlow-poky-linux + SRCREV_machine_pn-linux-yocto = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf" + SRCREV_emgd_pn-linux-yocto = "caea08c988e0f41103bbe18eafca20348f95da02" + SRCREV_meta_pn-linux-yocto = "c2ed0f16fdec628242a682897d5d86df4547cf24" + # core2-poky-linux + SRCREV_pn-kmod = "62081c0f68905b22f375156d4532fd37fa5c8d33" + SRCREV_pn-blktrace = "d6918c8832793b4205ed3bfede78c2f915c23385" + SRCREV_pn-opkg = "649" + + + Here are some notes on using the + buildhistory-collect-srcrevs command: + + By default, only values where the + SRCREV was + not hardcoded (usually when AUTOREV + was used) are reported. + Use the -a option to see all + SRCREV values. + + The output statements might not have any effect + if overrides are applied elsewhere in the build system + configuration. + Use the -f option to add the + forcevariable override to each output line + if you need to work around this restriction. + + The script does apply special handling when + building for multiple machines. + However, the script does place a + comment before each set of values that specifies + which triplet to which they belong as shown above + (e.g., emenlow-poky-linux). + + + + +
+ +
+ Build History Image Information + + + The files produced for each image are as follows: + + image-files: + A directory containing selected files from the root + filesystem. + The files are defined by + BUILDHISTORY_IMAGE_FILES. + + build-id: + Human-readable information about the build configuration + and metadata source revisions. + *.dot: + Dependency graphs for the image that are + compatible with graphviz. + + files-in-image.txt: + 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 + about the image. + See the following listing example for more information. + + installed-package-names.txt: + A list of installed packages by name only. + installed-package-sizes.txt: + A list of installed packages ordered by size. + + installed-packages.txt: + A list of installed packages with full package + filenames. + + + Installed package information is able to be gathered and + produced even if package management is disabled for the final + image. + + + + + Here is an example of image-info.txt: + + DISTRO = poky + DISTRO_VERSION = 1.1+snapshot-20120207 + USER_CLASSES = image-mklibs image-prelink + IMAGE_CLASSES = image_types + IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \ + 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 ; + 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. + This information is often useful when you are trying to determine + why a change in the package or file listings has occurred. + +
+ +
+ Using Build History to Gather Image Information Only + + + 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 specific package or SDK 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" + BUILDHISTORY_COMMIT = "0" + BUILDHISTORY_FEATURES = "image" + + Here, you set the + BUILDHISTORY_FEATURES + variable to use the image feature only. + +
+ +
+ Build History SDK Information + + Build history collects similar information on the contents + of SDKs (e.g. meta-toolchain + or bitbake -c populate_sdk imagename) + as compared to information it collects for images. + The following list shows the files produced for each SDK: + + files-in-sdk.txt: + A list of files in the SDK with permissions, + owner, group, size, and symlink information. + This list includes both the host and target parts + of the SDK. + + sdk-info.txt: + A text file containing name-value pairs with information + about the SDK. + See the following listing example for more information. + + The following information appears under + each of the host + and target directories + for the portions of the SDK that run on the host and + on the target, respectively: + + depends.dot: + Dependency graph for the SDK that is + compatible with graphviz. + + installed-package-names.txt: + A list of installed packages by name only. + + installed-package-sizes.txt: + A list of installed packages ordered by size. + + installed-packages.txt: + A list of installed packages with full package + filenames. + + + + + + + Here is an example of sdk-info.txt: + + DISTRO = poky + DISTRO_VERSION = 1.3+snapshot-20130327 + SDK_NAME = poky-eglibc-i686-arm + SDK_VERSION = 1.3+snapshot + SDKMACHINE = + SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs + BAD_RECOMMENDATIONS = + SDKSIZE = 352712 + + Other than SDKSIZE, which is the + total size of the files in the SDK in Kbytes, the + name-value pairs are variables that might have influenced the + content of the SDK. + This information is often useful when you are trying to + determine why a change in the package or file listings + has occurred. + +
+ +
+ Examining Build History Information + + + 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. + Here is one method: + + $ git log -p + + 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. + Here is an example: + + $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ + Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt): + /etc/anotherpkg.conf was added + /sbin/anotherpkg was added + * (installed-package-names.txt): + * anotherpkg was added + Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt): + anotherpkg was added + packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras" + * PR changed from "r0" to "r1" + * PV changed from "0.1.10" to "0.1.12" + packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%) + * PR changed from "r0" to "r1" + * PV changed from "0.1.10" to "0.1.12" + + + + + To see changes to the build history using a web interface, follow + the instruction in the README file here. + . + + + + Here is a sample screenshot of the interface: + + +
+
+
+ + + -- cgit v1.2.3-54-g00ecf