From 22083287912ebd552e33b79f7c567bc966376d43 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Fri, 15 Oct 2010 11:55:59 +0100 Subject: handbook: Move into documentation directory Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/usingpoky.xml | 316 ++++++++++++++++++++++++++++ 1 file changed, 316 insertions(+) create mode 100644 documentation/poky-ref-manual/usingpoky.xml (limited to 'documentation/poky-ref-manual/usingpoky.xml') diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml new file mode 100644 index 0000000000..ad6bda2545 --- /dev/null +++ b/documentation/poky-ref-manual/usingpoky.xml @@ -0,0 +1,316 @@ + + +Using Poky + + + This section gives an overview of the components that make up Poky + following by information about running poky builds and dealing with any + problems that may arise. + + +
+ 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. + + + + 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'. + + + + The directory structure walkthrough + section gives details on the meaning of specific directories but some + brief details on the core components follows: + + +
+ 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 it + 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. + + +
+ +
+ 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. + + + + '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. + + +
+ +
+ 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. + +
+ +
+ 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). + +
+ +
+ + + +
+ Running a Build + + + First the Poky build environment needs to be set up using the following command: + + + +$ 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. + Please refer to poky-init-build-env + for detail info + + + Once the Poky build environment is set up, a target can now be built using: + + + +$ bitbake <target> +$ bitbake qemu-native + + + + 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 qemu-native target will build the poky customized qemu, and will be used + by runqemu script later. + +
+ +
+ 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. + + +
+ +
+ Debugging Build Failures + + + 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: + + +
+ 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. + + + The output from python tasks is sent directly to the console at present. +
+ +
+ 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. + + + + If you wish to rerun a task you can use the force option + "-f". A typical usage session might look like: + + + +% bitbake matchbox-desktop +[change some source in the WORKDIR for example] +% 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. + + + + 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.pid. + +
+ +
+ 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. + +
+ +
+ General Bitbake Problems + + + Debug output from bitbake can be seen with 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". + + + + 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. + +
+ +
+ Building with no dependencies + + + If you really want to build a specific .bb file, you can use + the form bitbake -b somepath/somefile.bb. Note that this + will not check the dependencies so this option should only + be used when you know its dependencies already exist. You + can specify fragments of the filename and bitbake will see + if it can find a unique match. + + +
+ +
+ Variables + + + The "-e" option will dump the resulting environment for + either the configuration (no package specified) or for a + specific package when specified with the "-b" option. + +
+ +
+ Other Tips + + + When adding new packages it is worth keeping an eye open for bad + things creeping into compiler commandlines such as references to local + system files (/usr/lib/ or /usr/include/ etc.). + + + + + + If you want to remove the psplash boot splashscreen, add "psplash=false" + to the kernel commandline and psplash won't load allowing you to see + the console. It's also possible to switch out of the splashscreen by + switching virtual console (Fn+Left or Fn+Right on a Zaurus). + + + +
+
+ + + -- cgit v1.2.3-54-g00ecf