summaryrefslogtreecommitdiffstats
path: root/README.structure
diff options
context:
space:
mode:
authorRichard Purdie <richard@openedhand.com>2008-02-26 11:41:20 +0000
committerRichard Purdie <richard@openedhand.com>2008-02-26 11:41:20 +0000
commit18a758b9e99641207883c81cb7862a8737eb0682 (patch)
tree0981494a839dbd38369de6ad420357a4545c3e7f /README.structure
parentb2bdf19d90f9ac43a576076a408fb6104db4e5be (diff)
downloadpoky-18a758b9e99641207883c81cb7862a8737eb0682.tar.gz
README*: Update after addition of manual
git-svn-id: https://svn.o-hand.com/repos/poky/trunk@3867 311d38ba-8fff-0310-9ca6-ca027cbcb966
Diffstat (limited to 'README.structure')
-rw-r--r--README.structure214
1 files changed, 0 insertions, 214 deletions
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.