From 18a758b9e99641207883c81cb7862a8737eb0682 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Tue, 26 Feb 2008 11:41:20 +0000 Subject: README*: Update after addition of manual git-svn-id: https://svn.o-hand.com/repos/poky/trunk@3867 311d38ba-8fff-0310-9ca6-ca027cbcb966 --- README.commands | 106 --------------------------- README.host.sdk | 51 ------------- README.structure | 214 ------------------------------------------------------- 3 files changed, 371 deletions(-) delete mode 100644 README.commands delete mode 100644 README.host.sdk delete mode 100644 README.structure diff --git a/README.commands b/README.commands deleted file mode 100644 index c84eefad99..0000000000 --- a/README.commands +++ /dev/null @@ -1,106 +0,0 @@ - Using Poky - Poky Commands - ========================== - -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 " where is the name -of the package you wish to build. 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. -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. - - -Bitbake - Package 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 -case 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 the 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". - - -Bitbake - 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 matchbox-desktop -g" will -create a task-depends.dot file in the current directory. This shows which -packages and tasks depend on which other packages and tasks and it useful for -debugging purposes. - - -Bitbake - Advanced Usage -======================== - -Debug output from bitbake can be seen with the "-D" option and can sometimes -give more information about what bitbake is doing and/or why. Each -D options -increases the logging level, the most common usage being "-DDD". - -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 the dependencies already exist. You can -specify fragments of the filename and bitbake will see if it can find a unique -match. - -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. - -The -k option will cause bitbake to try and continue even if a task fails. It -can be useful for world or unattended builds. - -The -s option lists all the versions of packages that bitbake will use. - - -Bitbake - More Information -========================== - -See the bitbake user manual at: http://bitbake.berlios.de/manual/ - -QEMU -==== - -Running images built by poky under qemu is possible within the poky environment -through the "runqemu" command. It has the form: - -runqemu MACHINE IMAGETYPE ZIMAGE IMAGEFILE - -where: - -MACHINE - the machine to emulate (qemux86, qemuarm, spitz, akita) -IMAGETYPE - the type of image to use (nfs or ext2) -ZIMAGE - location of the kernel binary to use -IMAGEFILE - location of the image file to use -(common options are in brackets) - -MACHINE is mandatory, the others are optional. - -This assumes a suitable qemu binary is available with support for a given -machine. For further information see scripts/poky-qemu.README. - - Copyright (C) 2006-2007 OpenedHand Ltd. diff --git a/README.host.sdk b/README.host.sdk deleted file mode 100644 index d46c92af9b..0000000000 --- a/README.host.sdk +++ /dev/null @@ -1,51 +0,0 @@ -Using Poky generated host SDK -============================= - -How to build host SDK -==== - -You need to setup Poky and then run one command: - -$ bitbake meta-toolchain - -Result would be tarball in tmp/deploy/sdk/ with everything needed to build for -your target device. Unpack this in / directory - toolchain will reside in -/usr/local/poky/arm/ dir. - -Usage of SDK -===== - -First add toolchain into PATH: - -$ export PATH=/usr/local/poky/arm/bin/:$PATH - -Compiler is 'arm-poky-linux-gnueabi-gcc'. Building 'helloworld' example is -simple: - -$ arm-poky-linux-gnueabi-gcc hello.c -o hello -$ file hello -hello: ELF 32-bit LSB executable, ARM, version 1 (SYSV), for GNU/Linux 2.6.14, dynamically linked (uses shared libs), not stripped - -Autotools and SDK -====== - -'Configure' scripts allow to specify Host, Target, Build architecture. To build -with Poky SDK you need to specify: - -./configure --target=arm-poky-linux-gnueabi --host=arm-poky-linux-gnueabi - - -Using packages from Poky -======== - -During development it is often situation that we want to use some libraries -which are available in Poky build. Their packages need to be unpacked to -/usr/local/poky/arm/arm-poky-linux-gnueabi/ directory. - -For example to add libiw (from wireless-tools package) you need to unpack two -packages: - -libiw29_29-pre20-r0_armv5te.ipk -libiw-dev_29-pre20-r0_armv5te.ipk - - Copyright (C) 2006-2007 OpenedHand Ltd. diff --git a/README.structure b/README.structure deleted file mode 100644 index 761b37b41f..0000000000 --- a/README.structure +++ /dev/null @@ -1,214 +0,0 @@ - A walk through the poky directory tree - ====================================== - -Poky consists of several components and understanding what these are and where -they each live is one of the keys to using it. - -Top level core components -========================= - - -bitbake/ - -A copy of bitbake is included within poky for ease of use and resides here. -This should usually be the same as a standard bitbake release from the bitbake -project. Bitbake is a metadata interpreter and is responsible for reading the -poky metadata and running the tasks it defines. Failures are usually from the -metadata and not bitbake itself and most users don't need to worry about -bitbake. bitbake/bin is placed into the PATH environmental variable so bitbake -can be found. - -build/ - -This directory contains user configuration files and the output from Poky is -also placed here. - -meta/ - -The core metadata - this is the key part of poky. Within this directory there -are definitions of the machines, the poky distribution and the packages that -make up a given system. - -meta-extras/ - -Similar to meta containing some extra package files not included in standard -poky, disabled by default and hence not supported as part of poky. - -scripts/ - -Various integration scripts which implement extra functionality in the poky -environment for example the qemu scripts. This directory is appended to the -PATH environmental variable. - -sources/ - -Whilst not part of a checkout, poky will create this directory as part of any -build. Any downloads are placed in this directory (as specified by the -DL_DIR variable). This directory can be shared between poky builds to save -downloading files multiple times. SCM checkouts are also stored here as e.g. -sources/svn/, sources/cvs/ or sources/git/ and the sources directory may contain -archives of checkouts for various revisions or dates. - -Its worth noting that bitbake creates .md5 stamp files for downloads. It uses -these to mark downloads as complete as well as for checksum and access -accounting purposes. If you add a file manually to the directory, you need to -touch the corresponding .md5 file too. - -poky-init-build-env - -This script is used to setup the poky build environment. Sourcing this file in -a shell makes changes to PATH and sets other core bitbake variables based on the -current working directory. You need to use this before running poky commands. -Internally it uses scripts within the scripts/ directory to do the bulk of the -work. - - -The Build Directory -=================== - -conf/local.conf - -This file contains all the local user configuration of poky. If it isn't -present, its created from local.conf.sample. That file contains documentation -on the various standard options which can be configured there although any -standard conf file variable can be also be set here and usually overrides any -variable set elsewhere within poky. - -Edit this file to set the MACHINE you want to build for, which package types you -which to use (PACKAGE_CLASSES) or where downloaded files should go (DL_DIR) for -exmaple. - -tmp/ - -This is created by bitbake if it doesn't exist and is where all the poky output -is placed. To clean poky and start a build from scratch (other than downloads), -you can wipe this directory. tmp has some important subcomponents detailed -below. - -tmp/cache/ - -When bitbake parses the metadata it creates a cache file of the result which can -be used when subsequently running the command. These are stored here, usually on -a per machine basis. - -tmp/cross/ - -The cross compiler when generated is placed into this directory and those -beneath it. - -tmp/deploy/ - -Any 'end result' output from poky is placed under here. - -tmp/deploy/deb/ - -Any .deb packages emitted by poky are placed here, sorted into feeds for -different architecture types. - -tmp/deploy/images/ - -Complete filesystem images are placed here. If you want to flash the resulting -image from a build onto a device, look here for them. - -tmp/deploy/ipk/ - -Any resulting .ipk packages emitted by poky are placed here. - -tmp/rootfs/ - -This is a temporary scratch area used when creating filesystem images. It is run -under fakeroot and is not useful once that fakeroot session has ended as -information is lost. It is left around since it is still useful in debugging -image creation problems. - -tmp/staging/ - -Any package needing to share output with other packages does so within staging. -This means it contains any shared header files and any shared libraries amongst -other data. It is subdivided by architecture so multiple builds can run within -the one build directory. - -tmp/stamps/ - -This is used by bitbake for accounting purposes to keep track of which tasks -have been run and when. It is also subdivided by architecture. The files are -empty and the important information is the filenames and timestamps. - -tmp/work/ - -Each package build by bitbake is worked on its own work directory. Here, the -source is unpacked, patched, configured, compiled etc. It is subdivided by -architecture. - -It is worth considering the structure of a typical work directory. An example is -the linux-rp kernel, version 2.6.20 r7 on the machine spitz built within poky -which would result in a work directory of -"tmp/work/spitz-poky-linux-gnueabi/linux-rp-2.6.20-r7", referred to as WORKDIR. - -Within this, the source is unpacked to linux-2.6.20 and then patched by quilt -hence the existence of the standard quilt directories linux-2.6.20/patches and -linux-2.6.20/.pc. Within the linux-2.6.20 directory, standard quilt commands -can be used. - -There are other directories generated within WORKDIR. The most important/useful -is WORKDIR/temp which has log files for each task (log.do_*.pid) and the scripts -bitbake runs for each task (run.do_*.pid). WORKDIR/image is where "make install" -places its output which is then split into subpackages within WORKDIR/install. - - -The Metadata -============ - -As mentioned previously, this is the core of poky. It has several important -subdivisions: - -meta/classes/ - -Contains the *.bbclass files. Class files are used to abstract common code -allowing it to be reused by multiple packages. The base.bbclass file is -inherited by every package. Examples of other important classes are -autotools.bbclass which in theory allows any "autotooled" package to work with -poky with minimal effort or kernel.bbclass which contains common code and -functions for working with the linux kernel. Functions like image generation or -packaging also have their specific class files (image.bbclass, rootfs_*.bbclass -and package*.bbclass). - -meta/conf/ - -This is the core set of configuration files which start from bitbake.conf and -from which all other configuration files are included (see the includes at the -end of the file, even local.conf is loaded from there!). Whilst bitbake.conf -sets up the defaults, often these can be overridden by user (local.conf), -machine or distribution configuration files. - -meta/conf/machine/ - -Contains all the machine configuration files. If you set MACHINE="spitz", the -end result is poky looking for a spitz.conf file in this directory. The includes -directory contains various data common to multiple machines. If you want to add -support for a new machine to poky, this is the directory to look in. - -meta/conf/distro/ - -Any distribution specific configuration is controlled from here. OpenEmbedded -supports multiple distributions of which poky is one. Poky only contains the -poky distribution so poky.conf is the main file here. This includes the -versions and SRCDATES for applications which are configured here. An example of -an alternative configuration is poky-bleeding.conf although this mainly inherits -its configuration from poky itself. - -packages/ - -Each application (package) poky can build has an associated .bb file which are -all stored under this directory. Poky finds them through the BBFILES variable -which defaults to packages/*/*.bb. Adding a new piece of software to poky -consists of adding the appropriate .bb file. The .bb files from OpenEmbedded -upstream are usually compatible although they are not supported. - -site/ - -Certain autoconf test results cannot be determined when cross compiling since it -can't run tests on a live system. This directory therefore contains a list of -cached results for various architectures which is passed to autoconf. - - Copyright (C) 2006-2007 OpenedHand Ltd. -- cgit 1.2.3-korg