diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml index 70fa5102f5..c2e102ce37 100644 --- a/documentation/poky-ref-manual/usingpoky.xml +++ b/documentation/poky-ref-manual/usingpoky.xml @@ -13,27 +13,33 @@ Poky Overview - At the core of Poky is the bitbake task executor together with various types of - configuration files. This section gives an overview of bitbake and the - configuration files, in particular what they are used for, and how they - interact. + The bitbake task executor together with various types of configuration files form the core of Poky. + This section overviews the bitbake task executor and the + configuration files by describing what they are used for and they they interact. - Bitbake handles the parsing and execution of the data - files. The data itself is of various types; recipes which give - details about particular pieces of software, class data which is an - abstraction of common build information (e.g. how to build a Linux kernel) - and configuration data for machines, policy decisions, etc., which acts as - a glue and binds everything together. Bitbake knows how to combine multiple - data sources together, each data source being referred to as a 'layer'. + Bitbake handles the parsing and execution of the data files. + The data itself is of various types: + + Recipes: Provides details about particular pieces of software + Class Data: An abstraction of common build information (e.g. how to build a + Linux kernel). + Configuration Data: Defines machine-specific settings, policy decisions, etc. + Configuration data acts a the glue to bind everything together. + + + + + Bitbake knows how to combine multiple data sources together and refers to each data source + as a 'layer'. - The directory structure walkthrough - section gives details on the meaning of specific directories but some - brief details on the core components follows: + Following are some brief details on these core components. + For more detailed information on these components see the + 'Reference: Directory Structure' + appendix.
@@ -42,23 +48,30 @@ 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 it - supports look at bitbake --help. + and then executing them. To see a list of the options bitbake + supports look at 'bitbake --help'. - The most common usage is bitbake packagename where - packagename is the name of the package you wish to build - (from now on called the target). This often equates to the first part of a .bb - filename, so to run the matchbox-desktop_1.2.3.bb file, you - might type bitbake matchbox-desktop. - Several different versions of matchbox-desktop might exist and - bitbake will choose the one selected by the distribution configuration - (more details about how bitbake chooses between different versions - and providers is available in the - 'Preferences and Providers' section). Bitbake will also try to execute any - dependent tasks first so before building matchbox-desktop it - would build a cross compiler and glibc if not already built. + 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). + 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: + + $ bitbake matchbox-desktop + + 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. + + + 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.
@@ -67,17 +80,17 @@ 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 where to download the source, any patches that are needed, - any special configuration options, 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 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. - 'package' can also be used to describe recipes but since the same - word is used for the packaged output from Poky (i.e. .ipk or .deb - files), this document will avoid it. + 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. @@ -86,11 +99,12 @@ Classes - Class (.bbclass) files contain information which is useful to share - between metadata files. An example is the autotools class which contains - the common settings that any application using autotools would use. The - classes reference section gives details - on common classes and how to use them. + 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. + The Reference: Classes appendix provides details + about common classes and how to use them. @@ -98,18 +112,17 @@ Configuration - The configuration (.conf) files define various configuration variables - which govern what Poky does. These are split into several areas, such - as machine configuration options, distribution configuration options, - compiler tuning options, general common configuration and user - configuration (local.conf). + 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, + distribution configuration options, compiler tuning options, general common configuration + options and user configuration options (local.conf). -
Running a Build @@ -122,14 +135,14 @@ $ source poky-init-build-env [build_dir] - The build_dir is the dir containing all the building object files. The default - build dir is poky-dir/build. Multiple build_dir can be used for different targets. - For example, ~/build/x86 for qemux86 target, and ~/build/arm for qemuarm target. + 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 poky-init-build-env - for detail info + for more detailed information. - Once the Poky build environment is set up, a target can now be built using: + Once the Poky build environment is set up, a target can be built using: @@ -137,11 +150,13 @@ $ bitbake <target> - The target is the name of the recipe you want to build. Common targets are the - images (in meta/packages/images/) - or the name of a recipe for a specific piece of software like - busybox. More details about the standard images - are available in the image reference section. + 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. + 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 + 'Reference: Images' appendix.
@@ -149,11 +164,15 @@ $ bitbake <target> 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 covered in the Running an Image section. See your - board/machine documentation for information about how to install these images. + 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. + For information about how to install these images, see the documentation for your + particular board/machine. @@ -163,66 +182,73 @@ $ bitbake <target> The exact method for debugging Poky depends on the nature of the - bug(s) and which part of the system they might be from. Standard - debugging practises such as comparing to the last - known working version and examining the changes, reapplying the - changes in steps to identify the one causing the problem etc. are - valid for Poky just like any other system. It's impossible to detail - every possible potential failure here but there are some general - tips to aid debugging: + problem and on the system's area from which the bug originates. + Standard debugging practises such as comparison against the last + known working version with examination of the changes and the reapplication of steps + to identify the one causing the problem are + valid for Poky just as they are for any other system. + It's impossible to detail every possible potential failure but here are some general + tips to aid in debugging:
Task Failures The log file for shell tasks is available in ${WORKDIR}/temp/log.do_taskname.pid. - For the compile task of busybox 1.01 on the ARM spitz machine, this - might be tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234 - for example. To see what bitbake ran to generate that log, look at the run.do_taskname.pid - file in the same directory. + 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. - The output from python tasks is sent directly to the console at present. + Presently, the output from python tasks is sent directly to the console.
Running specific tasks - 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 this depends on are - built first hence the standard bitbake behaviour. There are - some tasks such as devshell which are not part of the - default build chain. If you wish to run such a task you can - use the "-c" option to bitbake e.g. bitbake - matchbox-desktop -c devshell. + 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: + +$ bitbake matchbox-desktop -c devshell + - If you wish to rerun a task you can use the force option - "-f". A typical usage session might look like: + If you wish to rerun a task use the force option "-f". + For example, the following sequence forces recompilation after changing files in the + working directory. + -% bitbake matchbox-desktop -[change some source in the WORKDIR for example] -% bitbake matchbox-desktop -c compile -f -% bitbake matchbox-desktop +$ bitbake matchbox-desktop +[make some changes to the source code in the WORKDIR] +$ bitbake matchbox-desktop -c compile -f +$ bitbake matchbox-desktop + - which would build matchbox-desktop, then recompile it. The - final command reruns all tasks after the compile (basically - the packaging tasks) since bitbake will notice that the - compile has been rerun and hence the other tasks also need - to run again. + 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. - You can view a list of tasks in a given package by running - the listtasks task e.g. bitbake matchbox-desktop -c - listtasks, and the result is in file ${WORKDIR}/temp/log.do_listtasks. + You can view a list of tasks in a given package by running the listtasks task. + For example: + +$ bitbake matchbox-desktop -c + + The results are in the file ${WORKDIR}/temp/log.do_listtasks.
@@ -230,16 +256,13 @@ $ bitbake <target> Dependency Graphs - Sometimes it can be hard to see why bitbake wants to build - some other packages before a given package you've specified. - bitbake -g targetname will create - depends.dot and - task-depends.dot files in the current - directory. They show - which packages and tasks depend on which other packages and - tasks and are useful for debugging purposes. - "bitbake -g -u depexp targetname" will show result - in more human-readable GUI style. + 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. + 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. @@ -247,17 +270,19 @@ $ bitbake <target> General Bitbake Problems - Debug output from bitbake can be seen with 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/or why. Each -D option increases the logging - level, the most common usage being "-DDD". + 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 - a certain version of a package might be chosen, why bitbake - picked a certain provider or help in other situations where - bitbake does something you're not expecting. + 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.