summaryrefslogtreecommitdiffstats
path: root/handbook/ref-structure.xml
diff options
context:
space:
mode:
authorRichard Purdie <richard@openedhand.com>2008-02-26 11:31:34 +0000
committerRichard Purdie <richard@openedhand.com>2008-02-26 11:31:34 +0000
commit882e9cd2affb773eec8b1d387ab4e3b5cbdc0994 (patch)
treef023b2ce9abf3b894a81986e0a00e23d77b55e66 /handbook/ref-structure.xml
parent7197110f46511492a48cd359b3ddf75b60ea47c8 (diff)
downloadpoky-882e9cd2affb773eec8b1d387ab4e3b5cbdc0994.tar.gz
Add Poky handbook
git-svn-id: https://svn.o-hand.com/repos/poky/trunk@3865 311d38ba-8fff-0310-9ca6-ca027cbcb966
Diffstat (limited to 'handbook/ref-structure.xml')
-rw-r--r--handbook/ref-structure.xml365
1 files changed, 365 insertions, 0 deletions
diff --git a/handbook/ref-structure.xml b/handbook/ref-structure.xml
new file mode 100644
index 0000000000..8a564e77b3
--- /dev/null
+++ b/handbook/ref-structure.xml
@@ -0,0 +1,365 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='ref-structure'>
5
6<title>Reference: Directory Structure</title>
7
8<para>
9 Poky consists of several components and understanding what these are
10 and where they're located is one of the keys to using it. This section walks
11 through the Poky directory structure giving information about the various
12 files and directories.
13</para>
14
15<section id='structure-core'>
16 <title>Top level core components</title>
17
18 <section id='structure-core-bitbake'>
19 <title><filename class="directory">bitbake/</filename></title>
20
21 <para>
22 A copy of BitBake is included within Poky for ease of use, and should
23 usually match the current BitBake stable release from the BitBake project.
24 Bitbake, a metadata interpreter, reads the Poky metadata and runs the tasks
25 defined in the Poky metadata. Failures are usually from the metadata, not
26 BitBake itself, so most users don't need to worry about BitBake. The
27 <filename class="directory">bitbake/bin/</filename> directory is placed
28 into the PATH environment variable by the <link
29 linkend="structure-core-script">poky-init-build-env</link> script.
30 </para>
31 <para>
32 For more information on BitBake please see the BitBake project site at
33 <ulink url="http://bitbake.berlios.de/"/>
34 and the BitBake on-line manual at <ulink url="http://bitbake.berlios.de/manual/"/>.
35 </para>
36 </section>
37
38 <section id='structure-core-build'>
39 <title><filename class="directory">build/</filename></title>
40
41 <para>
42 This directory contains user configuration files and the output
43 from Poky.
44 </para>
45 </section>
46
47 <section id='structure-core-meta'>
48 <title><filename class="directory">meta/</filename></title>
49
50 <para>
51 This directory contains the core metadata, a key part of Poky. Within this
52 directory there are definitions of the machines, the Poky distribution
53 and the packages that make up a given system.
54 </para>
55 </section>
56
57 <section id='structure-core-meta-extras'>
58 <title><filename class="directory">meta-extras/</filename></title>
59
60 <para>
61 This directory is similar to <filename class="directory">meta/</filename>,
62 and contains some extra metadata not included in standard Poky. These are
63 disabled by default, and are not supported as part of Poky.
64 </para>
65 </section>
66
67 <section id='structure-core-scripts'>
68 <title><filename class="directory">scripts/</filename></title>
69
70 <para>
71 This directory contains various integration scripts which implement
72 extra functionality in the Poky environment, such as the QEMU
73 scripts. This directory is appended to the PATH environment variable by the
74 <link linkend="structure-core-script">poky-init-build-env</link> script.
75 </para>
76 </section>
77
78 <section id='structure-core-sources'>
79 <title><filename class="directory">sources/</filename></title>
80
81 <para>
82 While not part of a checkout, Poky will create this directory as
83 part of any build. Any downloads are placed in this directory (as
84 specified by the <glossterm><link linkend='var-DL_DIR'>DL_DIR</link>
85 </glossterm> variable). This directory can be shared between Poky
86 builds to save downloading files multiple times. SCM checkouts are
87 also stored here as e.g. <filename class="directory">sources/svn/
88 </filename>, <filename class="directory">sources/cvs/</filename> or
89 <filename class="directory">sources/git/</filename> and the
90 sources directory may contain archives of checkouts for various
91 revisions or dates.
92 </para>
93
94 <para>
95 It's worth noting that BitBake creates <filename class="extension">.md5
96 </filename> stamp files for downloads. It uses these to mark downloads as
97 complete as well as for checksum and access accounting purposes. If you add
98 a file manually to the directory, you need to touch the corresponding
99 <filename class="extension">.md5</filename> file too.
100 </para>
101
102 <para>
103 This location can be overridden by setting <glossterm><link
104 linkend='var-DL_DIR'>DL_DIR</link></glossterm> in <filename>local.conf
105 </filename>. This directory can be shared between builds and even between
106 machines via NFS, so downloads are only made once, speeding up builds.
107 </para>
108
109 </section>
110
111 <section id='structure-core-script'>
112 <title><filename>poky-init-build-env</filename></title>
113
114 <para>
115 This script is used to setup the Poky build environment. Sourcing this file in
116 a shell makes changes to PATH and sets other core BitBake variables based on the
117 current working directory. You need to use this before running Poky commands.
118 Internally it uses scripts within the <filename class="directory">scripts/
119 </filename> directory to do the bulk of the work.
120 </para>
121 </section>
122</section>
123
124<section id='structure-build'>
125 <title><filename class="directory">build/</filename> - The Build Directory</title>
126
127 <section id='structure-build-conf-local.conf'>
128 <title><filename>build/conf/local.conf</filename></title>
129
130 <para>
131 This file contains all the local user configuration of Poky. If there
132 is no <filename>local.conf</filename> present, it is created from
133 <filename>local.conf.sample</filename>. The <filename>local.conf</filename>
134 file contains documentation on the various configuration options. Any
135 variable set here overrides any variable set elsewhere within Poky unless
136 that variable is hardcoded within Poky (e.g. by using '=' instead of '?=').
137 Some variables are hardcoded for various reasons but these variables are
138 relatively rare.
139 </para>
140
141 <para>
142 Edit this file to set the <glossterm><link linkend='var-MACHINE'>MACHINE</link></glossterm> for which you want to build, which package types you
143 wish to use (PACKAGE_CLASSES) or where downloaded files should go
144 (<glossterm><link linkend='var-DL_DIR'>DL_DIR</link></glossterm>).
145 </para>
146 </section>
147
148 <section id='structure-build-tmp'>
149 <title><filename class="directory">build/tmp/</filename></title>
150
151 <para>
152 This is created by BitBake if it doesn't exist and is where all the Poky output
153 is placed. To clean Poky and start a build from scratch (other than downloads),
154 you can wipe this directory. The <filename class="directory">tmp/
155 </filename> directory has some important sub-components detailed below.
156 </para>
157 </section>
158
159 <section id='structure-build-tmp-cache'>
160 <title><filename class="directory">build/tmp/cache/</filename></title>
161
162 <para>
163 When BitBake parses the metadata it creates a cache file of the result which can
164 be used when subsequently running commands. These are stored here on
165 a per machine basis.
166 </para>
167 </section>
168
169 <section id='structure-build-tmp-cross'>
170 <title><filename class="directory">build/tmp/cross/</filename></title>
171
172 <para>
173 The cross compiler when generated is placed into this directory and those
174 beneath it.
175 </para>
176 </section>
177
178 <section id='structure-build-tmp-deploy'>
179 <title><filename class="directory">build/tmp/deploy/</filename></title>
180
181 <para>Any 'end result' output from Poky is placed under here.</para>
182 </section>
183
184 <section id='structure-build-tmp-deploy-deb'>
185 <title><filename class="directory">build/tmp/deploy/deb/</filename></title>
186
187 <para>
188 Any .deb packages emitted by Poky are placed here, sorted into feeds for
189 different architecture types.
190 </para>
191 </section>
192
193 <section id='structure-build-tmp-deploy-images'>
194 <title><filename class="directory">build/tmp/deploy/images/</filename></title>
195
196 <para>
197 Complete filesystem images are placed here. If you want to flash the resulting
198 image from a build onto a device, look here for them.
199 </para>
200 </section>
201
202 <section id='structure-build-tmp-deploy-ipk'>
203 <title><filename class="directory">build/tmp/deploy/ipk/</filename></title>
204
205 <para>Any resulting .ipk packages emitted by Poky are placed here.</para>
206 </section>
207
208 <section id='structure-build-tmp-rootfs'>
209 <title><filename class="directory">build/tmp/rootfs/</filename></title>
210
211 <para>
212 This is a temporary scratch area used when creating filesystem images. It is run
213 under fakeroot and is not useful once that fakeroot session has ended as
214 information is lost. It is left around since it is still useful in debugging
215 image creation problems.
216 </para>
217 </section>
218
219 <section id='structure-build-tmp-staging'>
220 <title><filename class="directory">build/tmp/staging/</filename></title>
221
222 <para>
223 Any package needing to share output with other packages does so within staging.
224 This means it contains any shared header files and any shared libraries amongst
225 other data. It is subdivided by architecture so multiple builds can run within
226 the one build directory.
227 </para>
228 </section>
229
230 <section id='structure-build-tmp-stamps'>
231 <title><filename class="directory">build/tmp/stamps/</filename></title>
232
233 <para>
234 This is used by BitBake for accounting purposes to keep track of which tasks
235 have been run and when. It is also subdivided by architecture. The files are
236 empty and the important information is the filenames and timestamps.</para>
237 </section>
238
239 <section id='structure-build-tmp-work'>
240 <title><filename class="directory">build/tmp/work/</filename></title>
241
242 <para>
243 This directory contains various subdirectories for each architecture, and each package built by BitBake has its own work directory under the appropriate architecture subdirectory. All tasks are executed from this work directory. As an example, the source for a particular package will be unpacked, patched, configured and compiled all within its own work directory.
244 </para>
245
246 <para>
247 It is worth considering the structure of a typical work directory. An
248 example is the linux-rp kernel, version 2.6.20 r7 on the machine spitz
249 built within Poky. For this package a work directory of <filename
250 class="directory">tmp/work/spitz-poky-linux-gnueabi/linux-rp-2.6.20-r7/
251 </filename>, referred to as <glossterm><link linkend='var-WORKDIR'>WORKDIR
252 </link></glossterm>, is created. Within this directory, the source is
253 unpacked to linux-2.6.20 and then patched by quilt (see <link
254 linkend="usingpoky-modifying-packages-quilt">Section 3.5.1</link>).
255 Within the <filename class="directory">linux-2.6.20</filename> directory,
256 standard Quilt directories <filename class="directory">linux-2.6.20/patches</filename>
257 and <filename class="directory">linux-2.6.20/.pc</filename> are created,
258 and standard quilt commands can be used.
259 </para>
260
261 <para>
262 There are other directories generated within <glossterm><link
263 linkend='var-WORKDIR'>WORKDIR</link></glossterm>. The most important
264 is <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm><filename class="directory">/temp/</filename> which has log files for each
265 task (<filename>log.do_*.pid</filename>) and the scripts BitBake runs for
266 each task (<filename>run.do_*.pid</filename>). The <glossterm><link
267 linkend='var-WORKDIR'>WORKDIR</link></glossterm><filename
268 class="directory">/image/</filename> directory is where <command>make
269 install</command> places its output which is then split into subpackages
270 within <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm><filename class="directory">/install/</filename>.
271 </para>
272 </section>
273</section>
274
275<section id='structure-meta'>
276 <title><filename class="directory">meta/</filename> - The Metadata</title>
277
278 <para>
279 As mentioned previously, this is the core of Poky. It has several
280 important subdivisions:
281 </para>
282
283 <section id='structure-meta-classes'>
284 <title><filename class="directory">meta/classes/</filename></title>
285
286 <para>
287 Contains the <filename class="extension">*.bbclass</filename> files. Class
288 files are used to abstract common code allowing it to be reused by multiple
289 packages. The <filename>base.bbclass</filename> file is inherited by every
290 package. Examples of other important classes are
291 <filename>autotools.bbclass</filename> that in theory allows any
292 Autotool-enabled package to work with Poky with minimal effort, or
293 <filename>kernel.bbclass</filename> that contains common code and functions
294 for working with the linux kernel. Functions like image generation or
295 packaging also have their specific class files (<filename>image.bbclass
296 </filename>, <filename>rootfs_*.bbclass</filename> and
297 <filename>package*.bbclass</filename>).
298 </para>
299 </section>
300
301 <section id='structure-meta-conf'>
302 <title><filename class="directory">meta/conf/</filename></title>
303
304 <para>
305 This is the core set of configuration files which start from
306 <filename>bitbake.conf</filename> and from which all other configuration
307 files are included (see the includes at the end of the file, even
308 <filename>local.conf</filename> is loaded from there!). While
309 <filename>bitbake.conf</filename> sets up the defaults, these can often be
310 overridden by user (<filename>local.conf</filename>), machine or
311 distribution configuration files.
312 </para>
313 </section>
314
315 <section id='structure-meta-conf-machine'>
316 <title><filename class="directory">meta/conf/machine/</filename></title>
317
318 <para>
319 Contains all the machine configuration files. If you set MACHINE="spitz", the
320 end result is Poky looking for a <filename>spitz.conf</filename> file in this directory. The includes
321 directory contains various data common to multiple machines. If you want to add
322 support for a new machine to Poky, this is the directory to look in.
323 </para>
324 </section>
325
326 <section id='structure-meta-conf-distro'>
327 <title><filename class="directory">meta/conf/distro/</filename></title>
328
329 <para>
330 Any distribution specific configuration is controlled from here. OpenEmbedded
331 supports multiple distributions of which Poky is one. Poky only contains the
332 Poky distribution so poky.conf is the main file here. This includes the
333 versions and SRCDATES for applications which are configured here. An example of
334 an alternative configuration is poky-bleeding.conf although this mainly inherits
335 its configuration from Poky itself.
336 </para>
337 </section>
338
339 <section id='structure-meta-packages'>
340 <title><filename class="directory">meta/packages/</filename></title>
341
342 <para>
343 Each application (package) Poky can build has an associated .bb file which are
344 all stored under this directory. Poky finds them through the BBFILES variable
345 which defaults to packages/*/*.bb. Adding a new piece of software to Poky
346 consists of adding the appropriate .bb file. The .bb files from OpenEmbedded
347 upstream are usually compatible although they are not supported.
348 </para>
349 </section>
350
351 <section id='structure-meta-site'>
352 <title><filename class="directory">meta/site/</filename></title>
353
354 <para>
355 Certain autoconf test results cannot be determined when cross compiling since it
356 can't run tests on a live system. This directory therefore contains a list of
357 cached results for various architectures which is passed to autoconf.
358 </para>
359 </section>
360</section>
361
362</appendix>
363<!--
364vim: expandtab tw=80 ts=4
365-->