From 295b855fc916628ca9f2d9ef68d5aa6832cb569f Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 18 Aug 2011 07:52:05 -0700 Subject: documentation/poky-ref-manual/usingpoky.xml: re-write for Yocto General re-write to make the chapter Yocto Project friendly. Weeded out the references to "Poky." (From yocto-docs rev: ac4fc6082f458e5ee60962693ee332bbf1e3c1a9) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/usingpoky.xml | 247 ++++++++++++++++------------ 1 file changed, 143 insertions(+), 104 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 b07ec70fac..ed30d8df51 100644 --- a/documentation/poky-ref-manual/usingpoky.xml +++ b/documentation/poky-ref-manual/usingpoky.xml @@ -4,16 +4,17 @@ Using Poky - This section gives an overview of the components that make up Poky - followed by information about running poky builds and dealing with any - problems that may arise. + This section gives an overview of the components that make up the Yocto Project + followed by information about Yocto Project builds and dealing with any + problems that might arise.
Poky Overview - The BitBake task executor together with various types of configuration files form the core of Poky. + The BitBake task executor together with various types of configuration files form the + Yocto Project core. This section overviews the BitBake task executor and the configuration files by describing what they are used for and they they interact. @@ -28,6 +29,11 @@ Configuration Data: Defines machine-specific settings, policy decisions, etc. Configuration data acts a the glue to bind everything together. + For more information on data, see the + + Yocto Project Terms section in + + The Yocto Project Development Manual. @@ -46,16 +52,19 @@ BitBake - BitBake is the tool at the heart of Poky and is responsible - for parsing the metadata, generating a list of tasks from it - and then executing them. To see a list of the options BitBake - supports look at 'bitbake --help'. + BitBake is the tool at the heart of the Yocto Project and is responsible + for parsing the metadata, generating a list of tasks from it, + and then executing those tasks. + To see a list of the options BitBake supports, use the following help command: + + $ bitbake --help + The most common usage for BitBake is bitbake <packagename>, where - packagename is the name of the package you want to build (referred to as the 'target' - in this manual). + packagename is the name of the package you want to build + (referred to as the "target" in this manual). The target often equates to the first part of a .bb filename. So, to run the matchbox-desktop_1.2.3.bb file, you might type the following: @@ -64,43 +73,46 @@ Several different versions of matchbox-desktop might exist. BitBake chooses the one selected by the distribution configuration. - You can get more details about how BitBake chooses between different versions - and providers in the - 'Preferences and Providers' section. + You can get more details about how BitBake chooses between different + target versions and providers in the + Preferences and Providers section. + BitBake also tries to execute any dependent tasks first. - So for example, before building matchbox-desktop BitBake - would build a cross compiler and glibc if they had not already been built. + So for example, before building matchbox-desktop, BitBake + would build a cross compiler and glibc if they had not already + been built. + A useful BitBake option to consider is the -k or --continue option. This option instructs BitBake to try and continue processing the job as much - as possible even after encountering an error. When an error occurs the target that - failed and those that depend on it cannot be remade. However, when you use this - option other dependencies can still be processed. + as possible even after encountering an error. + When an error occurs, the target that + failed and those that depend on it cannot be remade. + However, when you use this option other dependencies can still be processed. -
Metadata (Recipes) - The .bb files are usually referred to as 'recipes'. - In general, a recipe contains information about a single piece of software such - as from where to download the source patches (if any are needed), which special - configuration options to apply, how to compile the source files, and how to - package the compiled output. + The .bb files are usually referred to as "recipes." + In general, a recipe contains information about a single piece of software. + The information includes the location from which to download the source patches + (if any are needed), which special configuration options to apply, + how to compile the source files, and how to package the compiled output. - The term 'package' can also be used to describe recipes. - However, since the same word is used for the packaged output from Poky (i.e. .ipk or .deb - files), this document avoids it. + The term "package" can also be used to describe recipes. + However, since the same word is used for the packaged output from the Yocto + Project (i.e. .ipk or .deb files), + this document avoids using the term "package" to refer to recipes. -
@@ -109,8 +121,8 @@ Class files (.bbclass) contain information that is useful to share between metadata files. - An example is the autotools class, which contains - common settings for any application that autotools uses. + An example is the Autotools class, which contains + common settings for any application that Autotools uses. The Reference: Classes appendix provides details about common classes and how to use them. @@ -121,13 +133,13 @@ The configuration files (.conf) define various configuration variables - that govern what Poky does. - These files are split into several areas that define machine configuration options, + that govern the Yocto Project build process. + These files fall into several areas that define machine configuration options, distribution configuration options, compiler tuning options, general common configuration - options and user configuration options (local.conf). + options and user configuration options (local.conf, which is found + in the Yocto Project files build directory).
- @@ -135,47 +147,64 @@ Running a Build - First the Poky build environment needs to be set up using the following command: + You can find information on how to build an image using the Yocto Project in the + + Building an Image section of the + + Yocto Project Quick Start. + This section provides a quick overview. + + The first thing you need to do is set up the Yocto Project build environment by sourcing + the environment setup script as follows: - $ source oe-init-build-env [build_dir] + $ source oe-init-build-env [build_dir]; + - The build_dir is the dir containing all the build's object files. The default - build dir is poky-dir/build. A different build_dir can be used for each of the targets. - For example, ~/build/x86 for a qemux86 target, and ~/build/arm for a qemuarm target. - Please refer to oe-init-build-env - for more detailed information. - - - Once the Poky build environment is set up, a target can be built using: + The build_dir is optional and specifies the directory Yocto Project + uses for the build. + If you do not specify a build directory it defaults to build + in the Yocto Project files directory structure. + 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-build-env + for more information on this script. + + Once the Yocto Project 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. + 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. + /meta/recipes-sato/images, etc. all found in the Yocto Project + files. Or, the target can be the name of a recipe for a specific piece of software such as busybox. - For more details about the standard images available, see the + For more details about the images Yocto Project supports, see the 'Reference: Images' appendix. + Building an image without GNU Public License Version 3 (GPLv3) components is only supported for minimal and base images. See 'Reference: Images' for more information. + - 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 - Public License. If you rebuild using different versions of GPL you can get - dependency errors due to some components not being rebuilt. + Public License. + If you rebuild using different versions of GPL, dependency errors might occur + due to some components not being rebuilt. @@ -183,17 +212,18 @@ Installing and Using the Result - Once an image has been built it often needs to be installed. - The images/kernels built by Poky are placed in the - tmp/deploy/images directory. - Running qemux86 and qemuarm images is described in the - 'Using Pre-Built Binaries and QEMU' section of the Yocto Project Quick Start. - See - for the guide. + Once an image has been built, it often needs to be installed. + The images and kernels built by the Yocto Project 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/machine. -
@@ -213,15 +243,17 @@
Task Failures - The log file for shell tasks is available in ${WORKDIR}/temp/log.do_taskname.pid. - For example, the "compile" task of busybox 1.01 on the ARM spitz machine might be + The log file for shell tasks is available in + ${WORKDIR}/temp/log.do_taskname.pid. + For example, the compile task of busybox 1.01 on the ARM spitz + machine might be tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234. 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. + Presently, the output from Python tasks is sent directly to the console.
@@ -230,28 +262,33 @@ Any given package consists of a set of tasks. - In most cases the series 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 - hence, - the standard BitBake behaviour. - 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 - "-c" option in BitBake as follows: + 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 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 + -c option in BitBake as follows: $ bitbake matchbox-desktop -c devshell - If you wish to rerun a task use the force option "-f". + 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 - [make some changes to the source code in the WORKDIR] + . + . + [make some changes to the source code in the working directory] + . + . $ bitbake matchbox-desktop -c compile -f $ bitbake matchbox-desktop @@ -259,14 +296,14 @@ 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 understands that the other - tasks also need to be run again. + 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. - For example: + You can view a list of tasks in a given package by running the + listtasks task as follows: $ bitbake matchbox-desktop -c @@ -279,12 +316,13 @@ Sometimes it can be hard to see why BitBake wants to build some other packages before a given - package you've specified. - The bitbake -g targetname command creates the depends.dot and - task-depends.dot files in the current directory. + package you have specified. + The bitbake -g targetname command creates the + depends.dot 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 display the results - in a more human-readable form. + You can use the bitbake -g -u depexp targetname command to + display the results in a more human-readable form.
@@ -292,10 +330,10 @@ General BitBake Problems - You can see debug output from BitBake by using the "-D" option. + 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. + Each -D option you use increases the logging level. The most common usage is -DDD. @@ -312,19 +350,20 @@ 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. - You can also specify fragments of the filename and BitBake checks for a unique match. + You can also specify fragments of the filename. + In this case, BitBake checks for a unique match.
Variables - The "-e" option dumps the resulting environment for + The -e option dumps the resulting environment for either the configuration (no package specified) or for a - specific package when specified with the "-b" option. + specific package when specified with the -b option.
@@ -422,23 +461,23 @@
Other Tips - - - When adding new packages it is worth watching for undesireable 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 thus allowing 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). + Here are some other tips that you might find useful: + + When adding new packages, it is worth watching for + undesireable 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). + + -
-- cgit v1.2.3-54-g00ecf