summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--README.commands106
-rw-r--r--README.host.sdk51
-rw-r--r--README.structure214
3 files changed, 0 insertions, 371 deletions
diff --git a/README.commands b/README.commands
deleted file mode 100644
index c84eefad99..0000000000
--- a/README.commands
+++ /dev/null
@@ -1,106 +0,0 @@
1 Using Poky - Poky Commands
2 ==========================
3
4Bitbake
5=======
6
7Bitbake is the tool at the heart of poky and is responsible for parsing the
8metadata, generating a list of tasks from it and then executing them. To see a
9list of the options it supports look at "bitbake --help".
10
11The most common usage is "bitbake <packagename>" where <packagename> is the name
12of the package you wish to build. This often equates to the first part of a .bb
13filename so to run the matchbox-desktop_1.2.3.bb file, you might type "bitbake
14matchbox-desktop. Several different versions of matchbox-desktop might exist
15and bitbake will choose the one selected by the distribution configuration.
16Bitbake will also try to execute any dependent tasks first so before building
17matchbox-desktop it would build a cross compiler and glibc if not already built.
18
19
20Bitbake - Package Tasks
21=======================
22
23Any given package consists of a set of tasks, in most cases the series is fetch,
24unpack, patch, configure, compile, install, package, package_write and build.
25The default task is "build" and any tasks this depends on are built first hence
26the standard bitbake behaviour. There are some tasks such as devshell which are
27not part of the default build chain. If you wish to run such a task you can use
28the "-c" option to bitbake e.g. "bitbake matchbox-desktop -c devshell".
29
30If you wish to rerun a task you can use the force option "-f". A typical usage
31case might look like:
32
33% bitbake matchbox-desktop
34[change some source in the WORKDIR for example]
35% bitbake matchbox-desktop -c compile -f
36% bitbake matchbox-desktop
37
38which would build matchbox-desktop, then recompile it. The final command reruns
39all tasks after the compile (basically the packaging tasks) since bitbake will
40notice the the compile has been rerun and hence the other tasks also need to run
41again.
42
43You can view a list of tasks in a given package by running the listtasks task
44e.g. "bitbake matchbox-desktop -c listtasks".
45
46
47Bitbake - Dependency Graphs
48===========================
49
50Sometimes it can be hard to see why bitbake wants to build some other packages
51before a given package you've specified. "bitbake matchbox-desktop -g" will
52create a task-depends.dot file in the current directory. This shows which
53packages and tasks depend on which other packages and tasks and it useful for
54debugging purposes.
55
56
57Bitbake - Advanced Usage
58========================
59
60Debug output from bitbake can be seen with the "-D" option and can sometimes
61give more information about what bitbake is doing and/or why. Each -D options
62increases the logging level, the most common usage being "-DDD".
63
64If you really want to build a specific .bb file, you can use the form "bitbake
65-b somepath/somefile.bb". Note that this will not check the dependencies so this
66option should only be used when you know the dependencies already exist. You can
67specify fragments of the filename and bitbake will see if it can find a unique
68match.
69
70The -e option will dump the resulting environment for either the configuration
71(no package specified) or for a specific package when specified with the -b
72option.
73
74The -k option will cause bitbake to try and continue even if a task fails. It
75can be useful for world or unattended builds.
76
77The -s option lists all the versions of packages that bitbake will use.
78
79
80Bitbake - More Information
81==========================
82
83See the bitbake user manual at: http://bitbake.berlios.de/manual/
84
85QEMU
86====
87
88Running images built by poky under qemu is possible within the poky environment
89through the "runqemu" command. It has the form:
90
91runqemu MACHINE IMAGETYPE ZIMAGE IMAGEFILE
92
93where:
94
95MACHINE - the machine to emulate (qemux86, qemuarm, spitz, akita)
96IMAGETYPE - the type of image to use (nfs or ext2)
97ZIMAGE - location of the kernel binary to use
98IMAGEFILE - location of the image file to use
99(common options are in brackets)
100
101MACHINE is mandatory, the others are optional.
102
103This assumes a suitable qemu binary is available with support for a given
104machine. For further information see scripts/poky-qemu.README.
105
106 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 @@
1Using Poky generated host SDK
2=============================
3
4How to build host SDK
5====
6
7You need to setup Poky and then run one command:
8
9$ bitbake meta-toolchain
10
11Result would be tarball in tmp/deploy/sdk/ with everything needed to build for
12your target device. Unpack this in / directory - toolchain will reside in
13/usr/local/poky/arm/ dir.
14
15Usage of SDK
16=====
17
18First add toolchain into PATH:
19
20$ export PATH=/usr/local/poky/arm/bin/:$PATH
21
22Compiler is 'arm-poky-linux-gnueabi-gcc'. Building 'helloworld' example is
23simple:
24
25$ arm-poky-linux-gnueabi-gcc hello.c -o hello
26$ file hello
27hello: ELF 32-bit LSB executable, ARM, version 1 (SYSV), for GNU/Linux 2.6.14, dynamically linked (uses shared libs), not stripped
28
29Autotools and SDK
30======
31
32'Configure' scripts allow to specify Host, Target, Build architecture. To build
33with Poky SDK you need to specify:
34
35./configure --target=arm-poky-linux-gnueabi --host=arm-poky-linux-gnueabi
36
37
38Using packages from Poky
39========
40
41During development it is often situation that we want to use some libraries
42which are available in Poky build. Their packages need to be unpacked to
43/usr/local/poky/arm/arm-poky-linux-gnueabi/ directory.
44
45For example to add libiw (from wireless-tools package) you need to unpack two
46packages:
47
48libiw29_29-pre20-r0_armv5te.ipk
49libiw-dev_29-pre20-r0_armv5te.ipk
50
51 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 @@
1 A walk through the poky directory tree
2 ======================================
3
4Poky consists of several components and understanding what these are and where
5they each live is one of the keys to using it.
6
7Top level core components
8=========================
9
10
11bitbake/
12
13A copy of bitbake is included within poky for ease of use and resides here.
14This should usually be the same as a standard bitbake release from the bitbake
15project. Bitbake is a metadata interpreter and is responsible for reading the
16poky metadata and running the tasks it defines. Failures are usually from the
17metadata and not bitbake itself and most users don't need to worry about
18bitbake. bitbake/bin is placed into the PATH environmental variable so bitbake
19can be found.
20
21build/
22
23This directory contains user configuration files and the output from Poky is
24also placed here.
25
26meta/
27
28The core metadata - this is the key part of poky. Within this directory there
29are definitions of the machines, the poky distribution and the packages that
30make up a given system.
31
32meta-extras/
33
34Similar to meta containing some extra package files not included in standard
35poky, disabled by default and hence not supported as part of poky.
36
37scripts/
38
39Various integration scripts which implement extra functionality in the poky
40environment for example the qemu scripts. This directory is appended to the
41PATH environmental variable.
42
43sources/
44
45Whilst not part of a checkout, poky will create this directory as part of any
46build. Any downloads are placed in this directory (as specified by the
47DL_DIR variable). This directory can be shared between poky builds to save
48downloading files multiple times. SCM checkouts are also stored here as e.g.
49sources/svn/, sources/cvs/ or sources/git/ and the sources directory may contain
50archives of checkouts for various revisions or dates.
51
52Its worth noting that bitbake creates .md5 stamp files for downloads. It uses
53these to mark downloads as complete as well as for checksum and access
54accounting purposes. If you add a file manually to the directory, you need to
55touch the corresponding .md5 file too.
56
57poky-init-build-env
58
59This script is used to setup the poky build environment. Sourcing this file in
60a shell makes changes to PATH and sets other core bitbake variables based on the
61current working directory. You need to use this before running poky commands.
62Internally it uses scripts within the scripts/ directory to do the bulk of the
63work.
64
65
66The Build Directory
67===================
68
69conf/local.conf
70
71This file contains all the local user configuration of poky. If it isn't
72present, its created from local.conf.sample. That file contains documentation
73on the various standard options which can be configured there although any
74standard conf file variable can be also be set here and usually overrides any
75variable set elsewhere within poky.
76
77Edit this file to set the MACHINE you want to build for, which package types you
78which to use (PACKAGE_CLASSES) or where downloaded files should go (DL_DIR) for
79exmaple.
80
81tmp/
82
83This is created by bitbake if it doesn't exist and is where all the poky output
84is placed. To clean poky and start a build from scratch (other than downloads),
85you can wipe this directory. tmp has some important subcomponents detailed
86below.
87
88tmp/cache/
89
90When bitbake parses the metadata it creates a cache file of the result which can
91be used when subsequently running the command. These are stored here, usually on
92a per machine basis.
93
94tmp/cross/
95
96The cross compiler when generated is placed into this directory and those
97beneath it.
98
99tmp/deploy/
100
101Any 'end result' output from poky is placed under here.
102
103tmp/deploy/deb/
104
105Any .deb packages emitted by poky are placed here, sorted into feeds for
106different architecture types.
107
108tmp/deploy/images/
109
110Complete filesystem images are placed here. If you want to flash the resulting
111image from a build onto a device, look here for them.
112
113tmp/deploy/ipk/
114
115Any resulting .ipk packages emitted by poky are placed here.
116
117tmp/rootfs/
118
119This is a temporary scratch area used when creating filesystem images. It is run
120under fakeroot and is not useful once that fakeroot session has ended as
121information is lost. It is left around since it is still useful in debugging
122image creation problems.
123
124tmp/staging/
125
126Any package needing to share output with other packages does so within staging.
127This means it contains any shared header files and any shared libraries amongst
128other data. It is subdivided by architecture so multiple builds can run within
129the one build directory.
130
131tmp/stamps/
132
133This is used by bitbake for accounting purposes to keep track of which tasks
134have been run and when. It is also subdivided by architecture. The files are
135empty and the important information is the filenames and timestamps.
136
137tmp/work/
138
139Each package build by bitbake is worked on its own work directory. Here, the
140source is unpacked, patched, configured, compiled etc. It is subdivided by
141architecture.
142
143It is worth considering the structure of a typical work directory. An example is
144the linux-rp kernel, version 2.6.20 r7 on the machine spitz built within poky
145which would result in a work directory of
146"tmp/work/spitz-poky-linux-gnueabi/linux-rp-2.6.20-r7", referred to as WORKDIR.
147
148Within this, the source is unpacked to linux-2.6.20 and then patched by quilt
149hence the existence of the standard quilt directories linux-2.6.20/patches and
150linux-2.6.20/.pc. Within the linux-2.6.20 directory, standard quilt commands
151can be used.
152
153There are other directories generated within WORKDIR. The most important/useful
154is WORKDIR/temp which has log files for each task (log.do_*.pid) and the scripts
155bitbake runs for each task (run.do_*.pid). WORKDIR/image is where "make install"
156places its output which is then split into subpackages within WORKDIR/install.
157
158
159The Metadata
160============
161
162As mentioned previously, this is the core of poky. It has several important
163subdivisions:
164
165meta/classes/
166
167Contains the *.bbclass files. Class files are used to abstract common code
168allowing it to be reused by multiple packages. The base.bbclass file is
169inherited by every package. Examples of other important classes are
170autotools.bbclass which in theory allows any "autotooled" package to work with
171poky with minimal effort or kernel.bbclass which contains common code and
172functions for working with the linux kernel. Functions like image generation or
173packaging also have their specific class files (image.bbclass, rootfs_*.bbclass
174and package*.bbclass).
175
176meta/conf/
177
178This is the core set of configuration files which start from bitbake.conf and
179from which all other configuration files are included (see the includes at the
180end of the file, even local.conf is loaded from there!). Whilst bitbake.conf
181sets up the defaults, often these can be overridden by user (local.conf),
182machine or distribution configuration files.
183
184meta/conf/machine/
185
186Contains all the machine configuration files. If you set MACHINE="spitz", the
187end result is poky looking for a spitz.conf file in this directory. The includes
188directory contains various data common to multiple machines. If you want to add
189support for a new machine to poky, this is the directory to look in.
190
191meta/conf/distro/
192
193Any distribution specific configuration is controlled from here. OpenEmbedded
194supports multiple distributions of which poky is one. Poky only contains the
195poky distribution so poky.conf is the main file here. This includes the
196versions and SRCDATES for applications which are configured here. An example of
197an alternative configuration is poky-bleeding.conf although this mainly inherits
198its configuration from poky itself.
199
200packages/
201
202Each application (package) poky can build has an associated .bb file which are
203all stored under this directory. Poky finds them through the BBFILES variable
204which defaults to packages/*/*.bb. Adding a new piece of software to poky
205consists of adding the appropriate .bb file. The .bb files from OpenEmbedded
206upstream are usually compatible although they are not supported.
207
208site/
209
210Certain autoconf test results cannot be determined when cross compiling since it
211can't run tests on a live system. This directory therefore contains a list of
212cached results for various architectures which is passed to autoconf.
213
214 Copyright (C) 2006-2007 OpenedHand Ltd.