summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2010-10-28 14:29:17 -0700
committerRichard Purdie <rpurdie@linux.intel.com>2010-11-04 20:20:06 +0000
commit4b7f1eee28dafcb237f54e1739a9936fdd80ebc4 (patch)
treed1effcc12a6d0fd878a57b1034bf3ddb74c5eb6f /documentation
parent30e92723e12558cf26c941fcdeb18b7e6ac427e3 (diff)
downloadpoky-4b7f1eee28dafcb237f54e1739a9936fdd80ebc4.tar.gz
General edits to the using poky and Extending Poky chapters.
I completed general edits to the second chapter of the poky reference manual. These edits went from section 2.4.5 through the end of the chapter. They consist of text rewrites for more active voice and follow general technical writing principles. I completed the same types of edits in the third chapter of the manual from the beginning through section 3.3.2. Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/poky-ref-manual/extendpoky.xml448
-rw-r--r--documentation/poky-ref-manual/usingpoky.xml38
2 files changed, 221 insertions, 265 deletions
diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml
index aedd7c1c68..763670e17c 100644
--- a/documentation/poky-ref-manual/extendpoky.xml
+++ b/documentation/poky-ref-manual/extendpoky.xml
@@ -4,53 +4,50 @@
4<chapter id='extendpoky'> 4<chapter id='extendpoky'>
5 5
6<title>Extending Poky</title> 6<title>Extending Poky</title>
7
8 <para> 7 <para>
9 This section gives information about how to extend the functionality 8 This section provides information about how to extend the functionality
10 already present in Poky, documenting standard tasks such as adding new 9 already present in Poky.
11 software packages, extending or customising images or porting poky to 10 The section also documents standard tasks such as adding new
12 new hardware (adding a new machine). It also contains advice about how 11 software packages, extending or customizing images or porting Poky to
13 to manage the process of making changes to Poky to achieve best results. 12 new hardware (adding a new machine).
13 Finally, the section contains advice about how
14 to make changes to Poky to achieve the best results.
14 </para> 15 </para>
15 16
16 <section id='usingpoky-extend-addpkg'> 17 <section id='usingpoky-extend-addpkg'>
17 <title>Adding a Package</title> 18 <title>Adding a Package</title>
18
19 <para> 19 <para>
20 To add package into Poky you need to write a recipe for it. 20 To add a package into Poky you need to write a recipe for it.
21 Writing a recipe means creating a .bb file which sets various 21 Writing a recipe means creating a <filename>.bb</filename> file that sets some
22 variables. The variables 22 variables.
23 useful for recipes are detailed in the <link linkend='ref-varlocality-recipe-required'> 23 For information on variables that are useful for recipes and for information about recipe naming
24 recipe reference</link> section along with more detailed information 24 issues, see <link linkend='ref-varlocality-recipe-required'>Recipe Variables - Required</link>
25 about issues such as recipe naming. 25 appendix.
26 </para> 26 </para>
27
28 <para> 27 <para>
29 Before writing a recipe from scratch it is often useful to check 28 Before writing a recipe from scratch it is often useful to check
30 whether someone else has written one already. OpenEmbedded is a good place 29 whether someone else has written one already.
31 to look as it has a wider scope and hence a wider range of packages. 30 OpenEmbedded is a good place to look as it has a wider scope and range of packages.
32 Poky aims to be compatible with OpenEmbedded so most recipes should 31 Because Poky aims to be compatible with OpenEmbedded, most recipes should
33 just work in Poky. 32 just work in Poky.
34 </para> 33 </para>
35
36 <para> 34 <para>
37 For new packages, the simplest way to add a recipe is to base it on a similar 35 For new packages, the simplest way to add a recipe is to base it on a similar
38 pre-existing recipe. There are some examples below of how to add 36 pre-existing recipe.
39 standard types of packages: 37 Following are some examples showing how to add standard types of packages:
40 </para> 38 </para>
41 39
42 <section id='usingpoky-extend-addpkg-singlec'> 40 <section id='usingpoky-extend-addpkg-singlec'>
43 <title>Single .c File Package (Hello World!)</title> 41 <title>Single .c File Package (Hello World!)</title>
44
45 <para> 42 <para>
46 To build an application from a single file stored locally (e.g. under "files/") 43 Building an application from a single file that is stored locally (e.g. under
47 requires a recipe which has the file listed in the <glossterm><link 44 <filename>files/</filename>) requires a recipe that has the file listed in
48 linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. In addition 45 the <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable.
49 the <function>do_compile</function> and <function>do_install</function> 46 Additionally, you need to manually write the <function>do_compile</function> and
50 tasks need to be manually written. The <glossterm><link linkend='var-S'> 47 <function>do_install</function> tasks.
51 S</link></glossterm> variable defines the directory containing the source 48 The <glossterm><link linkend='var-S'>S</link></glossterm> variable defines the
52 code which in this case is set equal to <glossterm><link linkend='var-WORKDIR'> 49 directory containing the source code, which is set to <glossterm><link linkend='var-WORKDIR'>
53 WORKDIR</link></glossterm>, the directory BitBake uses for the build. 50 WORKDIR</link></glossterm> in this case - the directory BitBake uses for the build.
54 </para> 51 </para>
55 <programlisting> 52 <programlisting>
56DESCRIPTION = "Simple helloworld application" 53DESCRIPTION = "Simple helloworld application"
@@ -71,32 +68,28 @@ do_install() {
71 install -m 0755 helloworld ${D}${bindir} 68 install -m 0755 helloworld ${D}${bindir}
72} 69}
73 </programlisting> 70 </programlisting>
74
75 <para> 71 <para>
76 As a result of the build process "helloworld", "helloworld-dbg" and "hellworld-dev" 72 By default, the "helloworld", "helloworld-dbg" and "hellworld-dev"
77 packages will be built by default. It is possible to<link linkend='usingpoky-extend-addpkg-files'> 73 packages are built.
78 customise the packaging process</link>. 74 For information on how to customize the packaging process, see
75 <link linkend='usingpoky-extend-addpkg-files'>Controlling Package Content</link>.
79 </para> 76 </para>
80 </section> 77 </section>
81 78
82 <section id='usingpoky-extend-addpkg-autotools'> 79 <section id='usingpoky-extend-addpkg-autotools'>
83 <title>Autotooled Package</title> 80 <title>Autotooled Package</title>
84
85 <para> 81 <para>
86 Applications which use autotools (autoconf, automake) 82 Applications that use autotools such as <filename>autoconf</filename> and
87 require a recipe which has a source archive listed in 83 <filename>automake</filename> require a recipe that has a source archive listed in
88 <glossterm><link 84 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> and
89 linkend='var-SRC_URI'>SRC_URI</link></glossterm> and 85 <filename>also inherits autotools</filename>, which instructs BitBake to use the
90 <command>inherit autotools</command> to instruct BitBake to use the 86 <filename>autotools.bbclass</filename> containing the definitions of all the steps
91 <filename>autotools.bbclass</filename> which has
92 definitions of all the steps
93 needed to build an autotooled application. 87 needed to build an autotooled application.
94 The result of the build will be automatically packaged and if 88 The result of the build is automatically packaged.
95 the application uses NLS to localise then packages with 89 And, if the application uses NLS for localization, packages with local information are
96 locale information will be generated (one package per 90 generated (one package per language).
97 language). Below is one example (hello_2.2.bb) 91 Following is one example (<filename>hello_2.2.bb</filename>)
98 </para> 92 </para>
99
100 <programlisting> 93 <programlisting>
101DESCRIPTION = "GNU Helloworld application" 94DESCRIPTION = "GNU Helloworld application"
102SECTION = "examples" 95SECTION = "examples"
@@ -108,50 +101,40 @@ SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
108 101
109inherit autotools gettext 102inherit autotools gettext
110 </programlisting> 103 </programlisting>
111
112 <para> 104 <para>
113 <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link> 105 <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
114 </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'> 106 </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
115 track source license change</link>. Autotool based recipe can be quickly 107 track source license change</link>.
116 created this way like above example. 108 You can quickly create autotool-based recipes in a manner similar to the previous example.
117 </para> 109 </para>
118 110
119 </section> 111 </section>
120
121 <section id='usingpoky-extend-addpkg-makefile'> 112 <section id='usingpoky-extend-addpkg-makefile'>
122 <title>Makefile-Based Package</title> 113 <title>Makefile-Based Package</title>
123
124 <para> 114 <para>
125 Applications which use GNU make require a recipe which has 115 Applications that use GNU <filename>make</filename> also require a recipe that has
126 the source archive listed in <glossterm><link 116 the source archive listed in <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
127 linkend='var-SRC_URI'>SRC_URI</link></glossterm>. 117 You do not need to add a <function>do_compile</function> step since by default BitBake
128 Adding a <function>do_compile</function> step 118 starts the <filename>make</filename> command to compile the application.
129 is not needed as by default BitBake will start the "make" 119 If you need additional <filename>make</filename> options you should store them in the
130 command to compile the application. If there is a need for 120 <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable.
131 additional options to make then they should be stored in the 121 Bitbake passes these options into the <filename>make</filename> GNU invocation.
132 <glossterm><link 122 Note that a <function>do_install</function> task is still required.
133 linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable - BitBake 123 Otherwise BitBake runs an empty <function>do_install</function> task by default.
134 will pass them into the GNU
135 make invocation. A <function>do_install</function> task is required
136 - otherwise BitBake will run an empty <function>do_install</function>
137 task by default.
138 </para> 124 </para>
139
140 <para> 125 <para>
141 Some applications may require extra parameters to be passed to 126 Some applications might require extra parameters to be passed to the compiler.
142 the compiler, for example an additional header path. This can 127 For example the application might need an additional header path.
143 be done buy adding to the <glossterm><link 128 You can accomplish this by adding to the <glossterm><link linkend='var-CFLAGS'>CFLAGS</link>
144 linkend='var-CFLAGS'>CFLAGS</link></glossterm> variable, as in the example below: 129 </glossterm> variable.
130 The following example shows this:
145 </para> 131 </para>
146
147 <programlisting> 132 <programlisting>
148CFLAGS_prepend = "-I ${S}/include " 133CFLAGS_prepend = "-I ${S}/include "
149 </programlisting> 134 </programlisting>
150
151 <para> 135 <para>
152 mtd-utils is an example as Makefile-based: 136 In the following example <filename>mtd-utils</filename> is a Makefile-based package:
153 </para> 137 </para>
154
155 <programlisting> 138 <programlisting>
156DESCRIPTION = "Tools for managing memory technology devices." 139DESCRIPTION = "Tools for managing memory technology devices."
157SECTION = "base" 140SECTION = "base"
@@ -177,25 +160,19 @@ do_install () {
177 </programlisting> 160 </programlisting>
178 161
179 </section> 162 </section>
180
181 <section id='usingpoky-extend-addpkg-files'> 163 <section id='usingpoky-extend-addpkg-files'>
182 <title>Controlling packages content</title> 164 <title>Controlling Package Content</title>
183
184 <para> 165 <para>
185 The variables <glossterm><link 166 You can use the variables <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm> and
186 linkend='var-PACKAGES'>PACKAGES</link></glossterm> and 167 <glossterm><link linkend='var-FILES'>FILES</link></glossterm> to split an application into
187 <glossterm><link linkend='var-FILES'>FILES</link></glossterm> are used to split an 168 multiple packages.
188 application into multiple packages.
189 </para> 169 </para>
190
191 <para> 170 <para>
192 Below the "libXpm" recipe (libxpm_3.5.7.bb) is used as an example. By 171 Following is an example that uses the "libXpm" recipe (<filename>libxpm_3.5.7.bb</filename>).
193 default the "libXpm" recipe generates one package 172 By default, the "libXpm" recipe generates a single package containing the library, along
194 which contains the library 173 with a few binaries.
195 and also a few binaries. The recipe can be adapted to 174 You can modify the recipe to split the binaries into separate packages:
196 split the binaries into separate packages.
197 </para> 175 </para>
198
199 <programlisting> 176 <programlisting>
200require xorg-lib-common.inc 177require xorg-lib-common.inc
201 178
@@ -211,20 +188,19 @@ PACKAGES =+ "sxpm cxpm"
211FILES_cxpm = "${bindir}/cxpm" 188FILES_cxpm = "${bindir}/cxpm"
212FILES_sxpm = "${bindir}/sxpm" 189FILES_sxpm = "${bindir}/sxpm"
213 </programlisting> 190 </programlisting>
214
215 <para> 191 <para>
216 In this example we want to ship the "sxpm" and "cxpm" binaries 192 In the previous example we want to ship the "sxpm" and "cxpm" binaries
217 in separate packages. Since "bindir" would be packaged into the 193 in separate packages.
218 main <glossterm><link linkend='var-PN'>PN</link></glossterm> 194 Since "bindir" would be packaged into the main
219 package as standard we prepend the <glossterm><link 195 <glossterm><link linkend='var-PN'>PN</link></glossterm>
220 linkend='var-PACKAGES'>PACKAGES</link></glossterm> variable so 196 package by default, we prepend the <glossterm><link linkend='var-PACKAGES'>PACKAGES</link>
221 additional package names are added to the start of list. The 197 </glossterm> variable so additional package names are added to the start of list.
222 extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_* 198 This results in the extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_*
223 variables then contain information to specify which files and 199 variables then containing information defining which files and
224 directories goes into which package. Files included by earlier 200 directories go into which package.
225 package are skipped by latter packages, and thus main <glossterm> 201 Files included by earlier packages are skipped by latter packages.
226 <link linkend='var-PN'>PN</link></glossterm> will not include 202 Thus, the main <glossterm><link linkend='var-PN'>PN</link></glossterm> package does not include
227 above listed files 203 the above listed files.
228 </para> 204 </para>
229 </section> 205 </section>
230 206
@@ -232,14 +208,13 @@ FILES_sxpm = "${bindir}/sxpm"
232 <title>Post Install Scripts</title> 208 <title>Post Install Scripts</title>
233 209
234 <para> 210 <para>
235 To add a post-installation script to a package, add 211 To add a post-installation script to a package, add a <function>pkg_postinst_PACKAGENAME()
236 a <function>pkg_postinst_PACKAGENAME()</function> 212 </function> function to the <filename>.bb</filename> file and use
237 function to the .bb file 213 <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
238 where PACKAGENAME is the name of the package to attach 214 <filename>postinst</filename> script.
239 the postinst script to. Normally <glossterm><link 215 Normally <glossterm><link linkend='var-PN'>PN</link></glossterm> can be used, which
240 linkend='var-PN'>PN</link></glossterm> can be used which expands 216 automatically expands to PACKAGENAME.
241 to PACKAGENAME automatically. A post-installation function has the 217 A post-installation function has the following structure:
242 following structure:
243 </para> 218 </para>
244 <programlisting> 219 <programlisting>
245pkg_postinst_PACKAGENAME () { 220pkg_postinst_PACKAGENAME () {
@@ -248,21 +223,18 @@ pkg_postinst_PACKAGENAME () {
248} 223}
249 </programlisting> 224 </programlisting>
250 <para> 225 <para>
251 The script defined in the post installation function 226 The script defined in the post-installation function is called when the rootfs is made.
252 gets called when the rootfs is made. If the script succeeds, 227 If the script succeeds, the package is marked as installed.
253 the package is marked as installed. If the script fails, 228 If the script fails, the package is marked as unpacked and the script is
254 the package is marked as unpacked and the script will be 229 executed when the image boots again.
255 executed again on the first boot of the image.
256 </para> 230 </para>
257
258 <para> 231 <para>
259 Sometimes it is necessary that the execution of a post-installation 232 Sometimes it is necessary for the execution of a post-installation
260 script is delayed until the first boot, because the script 233 script to be delayed until the first boot.
261 needs to be executed on the device itself. To delay script execution 234 For example, the script might need to be executed on the device itself.
262 until boot time, the post-installation function should have the 235 To delay script execution until boot time, use the following structure for the
263 following structure: 236 post-installation script:
264 </para> 237 </para>
265
266 <programlisting> 238 <programlisting>
267pkg_postinst_PACKAGENAME () { 239pkg_postinst_PACKAGENAME () {
268#!/bin/sh -e 240#!/bin/sh -e
@@ -273,83 +245,69 @@ else
273fi 245fi
274} 246}
275 </programlisting> 247 </programlisting>
276
277 <para> 248 <para>
278 The structure above delays execution until first boot 249 The previous example delays execution until the image boots again because the
279 because the <glossterm><link 250 <glossterm><link linkend='var-D'>D</link></glossterm> variable points
280 linkend='var-D'>D</link></glossterm> variable points 251 to the 'image' directory when the rootfs is being made at build time but
281 to the 'image'
282 directory when the rootfs is being made at build time but
283 is unset when executed on the first boot. 252 is unset when executed on the first boot.
284 </para> 253 </para>
285 </section> 254 </section>
286
287 </section> 255 </section>
288 256
289 <section id='usingpoky-extend-customimage'> 257 <section id='usingpoky-extend-customimage'>
290 <title>Customising Images</title> 258 <title>Customising Images</title>
291
292 <para> 259 <para>
293 Poky images can be customised to satisfy 260 You can customize Poky images to satisfy particular requirements.
294 particular requirements. Several methods are detailed below 261 This section describes several methods and provides guidelines for each.
295 along with guidelines of when to use them.
296 </para> 262 </para>
297 263
298 <section id='usingpoky-extend-customimage-custombb'> 264 <section id='usingpoky-extend-customimage-custombb'>
299 <title>Customising Images through a custom image .bb files</title> 265 <title>Customising Images Using Custom .bb Files</title>
300
301 <para> 266 <para>
302 One way to get additional software into an image is by creating a 267 One way to get additional software into an image is to create a custom image.
303 custom image. The recipe will contain two lines: 268 The following example shows the form for the two lines you need:
304 </para> 269 </para>
305
306 <programlisting> 270 <programlisting>
307IMAGE_INSTALL = "task-poky-x11-base package1 package2" 271IMAGE_INSTALL = "task-poky-x11-base package1 package2"
308 272
309inherit poky-image 273inherit poky-image
310 </programlisting> 274 </programlisting>
311
312 <para> 275 <para>
313 By creating a custom image, a developer has total control 276 By creating a custom image, a developer has total control
314 over the contents of the image. It is important to use 277 over the contents of the image.
315 the correct names of packages in the <glossterm><link 278 It is important to use the correct names of packages in the
316 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> variable. 279 <glossterm><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> variable.
317 The names must be in 280 You must use the OpenEmbedded notation and not the Debian notation for the names
318 the OpenEmbedded notation instead of Debian notation, for example 281 (e.g. "glibc-dev" instead of "libc6-dev").
319 "glibc-dev" instead of "libc6-dev" etc.
320 </para> 282 </para>
321
322 <para> 283 <para>
323 The other method of creating a new image is by modifying 284 The other method for creating a custom image is to modify an existing image.
324 an existing image. For example if a developer wants to add 285 For example, if a developer wants to add "strace" into "poky-image-sato", they can use
325 "strace" into "poky-image-sato" the following recipe can 286 the following recipe:
326 be used:
327 </para> 287 </para>
328
329 <programlisting> 288 <programlisting>
330require poky-image-sato.bb 289require poky-image-sato.bb
331 290
332IMAGE_INSTALL += "strace" 291IMAGE_INSTALL += "strace"
333 </programlisting> 292 </programlisting>
334
335 </section> 293 </section>
336 294
337 <section id='usingpoky-extend-customimage-customtasks'> 295 <section id='usingpoky-extend-customimage-customtasks'>
338 <title>Customising Images through custom tasks</title> 296 <title>Customising Images Using Custom Tasks</title>
339 297 <para>
340 <para> 298 For complex custom images, the best approach is to create a custom task package
341 For complex custom images, the best approach is to create a custom 299 that is used to build the image or images.
342 task package which is then used to build the image (or images). A good 300 A good example of a tasks package is <filename>meta/recipes-sato/tasks/task-poky.bb
343 example of a tasks package is <filename>meta/packages/tasks/task-poky.bb 301 </filename>.
344 </filename>. The <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm> 302 The <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm>
345 variable lists the task packages to build (along with the complementary 303 variable lists the task packages to build along with the complementary
346 -dbg and -dev packages). For each package added, 304 -dbg and -dev packages.
347 <glossterm><link linkend='var-PACKAGES'>RDEPENDS</link></glossterm> and 305 For each package added, you can use
348 <glossterm><link linkend='var-PACKAGES'>RRECOMMENDS</link></glossterm> 306 <glossterm><link linkend='var-PACKAGES'>RDEPENDS</link></glossterm>
349 entries can then be added each containing a list of packages the parent 307 and <glossterm><link linkend='var-PACKAGES'>RRECOMMENDS</link></glossterm>
350 task package should contain. An example would be: 308 entries to provide a list of packages the parent task package should contain.
309 Following is an example:
351 </para> 310 </para>
352
353 <para> 311 <para>
354 <programlisting> 312 <programlisting>
355DESCRIPTION = "My Custom Tasks" 313DESCRIPTION = "My Custom Tasks"
@@ -378,11 +336,11 @@ RRECOMMENDS_task-custom-tools = "\
378 kernel-module-oprofile" 336 kernel-module-oprofile"
379</programlisting> 337</programlisting>
380 </para> 338 </para>
381
382 <para> 339 <para>
383 In this example, two task packages are created, task-custom-apps and 340 In the previous example, two task packages are created with their dependencies and their
384 task-custom-tools with the dependencies and recommended package dependencies 341 recommended package dependencies listed: <filename>task-custom-apps</filename>, and
385 listed. To build an image using these task packages, you would then add 342 <filename>task-custom-tools</filename>.
343 To build an image using these task packages, you need to add
386 "task-custom-apps" and/or "task-custom-tools" to <glossterm><link 344 "task-custom-apps" and/or "task-custom-tools" to <glossterm><link
387 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> or other forms 345 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> or other forms
388 of image dependencies as described in other areas of this section. 346 of image dependencies as described in other areas of this section.
@@ -390,131 +348,133 @@ RRECOMMENDS_task-custom-tools = "\
390 </section> 348 </section>
391 349
392 <section id='usingpoky-extend-customimage-imagefeatures'> 350 <section id='usingpoky-extend-customimage-imagefeatures'>
393 <title>Customising Images through custom <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm></title> 351 <title>Customising Images Using Custom <glossterm>
394 352 <link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm></title>
395 <para> 353 <para>
396 Ultimately users may want to add extra image "features" as used by Poky with the 354 Ultimately users might want to add extra image "features" as used by Poky with the
397 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> 355 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
398 variable. To create these, the best reference is <filename>meta/classes/poky-image.bbclass</filename> 356 variable.
399 which illustrates how poky achieves this. In summary, the file looks at the contents of the 357 To create these features, the best reference is
358 <filename>meta/classes/poky-image.bbclass</filename>, which shows how poky achieves this.
359 In summary, the file looks at the contents of the
400 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> 360 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
401 variable and then maps this into a set of tasks or packages. Based on this then the 361 variable and then maps them into a set of tasks or packages.
402 <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link></glossterm> 362 Based on this information the <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link>
403 variable is generated automatically. Extra features can be added by 363 </glossterm> variable is generated automatically.
404 extending the class or creating a custom class for use with specialised image .bb files. 364 Users can add extra features by extending the class or creating a custom class for use
365 with specialized image <filename>.bb</filename> files.
405 </para> 366 </para>
406 </section> 367 </section>
407 368
408 <section id='usingpoky-extend-customimage-localconf'> 369 <section id='usingpoky-extend-customimage-localconf'>
409 <title>Customising Images through local.conf</title> 370 <title>Customising Images Using local.conf</title>
410
411 <para> 371 <para>
412 It is possible to customise image contents by abusing 372 It is possible to customise image contents by abusing variables used by distribution
413 variables used by distribution maintainers in local.conf. 373 maintainers in local.conf.
414 This method only allows the addition of packages and 374 This method only allows the addition of packages and is not recommended.
415 is not recommended.
416 </para> 375 </para>
417
418 <para> 376 <para>
419 To add an "strace" package into the image the following is 377 For example, to add the "strace" package into the image the you would add this to the
420 added to local.conf: 378 <filename>local.conf</filename> file:
421 </para> 379 </para>
422
423 <programlisting> 380 <programlisting>
424DISTRO_EXTRA_RDEPENDS += "strace" 381DISTRO_EXTRA_RDEPENDS += "strace"
425 </programlisting> 382 </programlisting>
426
427 <para> 383 <para>
428 However, since the <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'> 384 However, since the <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
429 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable is for 385 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable is for
430 distribution maintainers this method does not make 386 distribution maintainers, adding packages using this method is not as simple as adding
431 adding packages as simple as a custom .bb file. Using 387 them using a custom <filename>.bb</filename> file.
432 this method, a few packages will need to be recreated if they have been 388 Using the <filename>local.conf</filename> file method could result in some packages
433 created before and then the image is rebuilt. 389 requiring recreation.
390 For example, if packages were previously created and the image was rebuilt then the packages
391 would need to be recreated.
434 </para> 392 </para>
435 <programlisting>
436bitbake -c clean task-boot task-base task-poky
437bitbake poky-image-sato
438 </programlisting>
439
440 <para> 393 <para>
441 Cleaning task-* packages is required because they use the 394 Cleaning task-* packages is required because they use the
442 <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'> 395 <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
443 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. There is no need to 396 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable.
444 build them by hand as Poky images depend on the packages they contain so 397 You do not have to build them by hand because Poky images depend on the packages they contain.
445 dependencies will be built automatically when building the image. For this reason we don't use the 398 This means dependencies are automatically built when the image builds.
446 "rebuild" task in this case since "rebuild" does not care about 399 For this reason we don't use the "rebuild" task.
400 In this case the "rebuild" task does does not care about
447 dependencies - it only rebuilds the specified package. 401 dependencies - it only rebuilds the specified package.
448 </para> 402 </para>
449 403 <programlisting>
404bitbake -c clean task-boot task-base task-poky
405bitbake poky-image-sato
406 </programlisting>
450 </section> 407 </section>
451 408
452 </section> 409 </section>
453 410
454<section id="platdev-newmachine"> 411<section id="platdev-newmachine">
455 <title>Porting Poky to a new machine</title> 412 <title>Porting Poky to a New Machine</title>
456 <para> 413 <para>
457 Adding a new machine to Poky is a straightforward process and 414 Adding a new machine to Poky is a straightforward process.
458 this section gives an idea of the changes that are needed. This guide is 415 This section provides information that gives you an idea of the changes you must make.
459 meant to cover adding machines similar to those Poky already supports. 416 The information covers adding machines similar to those Poky already supports.
460 Adding a totally new architecture might require gcc/glibc changes as 417 Although well within the capabilities of Poky, adding a totally new architecture might require
461 well as updates to the site information and, whilst well within Poky's 418 changes to <filename>gcc/glibc</filename> and to the site information.
462 capabilities, is outside the scope of this section. 419 Consequently, the information is beyond the scope of this manual.
463 </para> 420 </para>
464 421
465 <section id="platdev-newmachine-conffile"> 422 <section id="platdev-newmachine-conffile">
466 <title>Adding the machine configuration file</title> 423 <title>Adding the Machine Configuration File</title>
467 <para> 424 <para>
468 A .conf file needs to be added to conf/machine/ with details of the 425 To add a machine configuration you need to add a <filename>.conf</filename> file
469 device being added. The name of the file determines the name Poky will 426 with details of the device being added to <filename>conf/machine/</filename>.
470 use to reference this machine. 427 The name of the file determines the name Poky uses to reference the new machine.
471 </para> 428 </para>
472
473 <para> 429 <para>
474 The most important variables to set in this file are <glossterm> 430 The most important variables to set in this file are <glossterm>
475 <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm> 431 <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm>
476 (e.g. "arm"), <glossterm><link linkend='var-PREFERRED_PROVIDER'> 432 (e.g. "arm"), <glossterm><link linkend='var-PREFERRED_PROVIDER'>
477 PREFERRED_PROVIDER</link></glossterm>_virtual/kernel (see below) and 433 PREFERRED_PROVIDER</link></glossterm>_virtual/kernel (see below) and
478 <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES 434 <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES
479 </link></glossterm> (e.g. "kernel26 apm screen wifi"). Other variables 435 </link></glossterm> (e.g. "kernel26 apm screen wifi").
480 like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE 436 You might also need other variables like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE
481 </link></glossterm> (e.g. "115200 ttyS0"), <glossterm> 437 </link></glossterm> (e.g. "115200 ttyS0"), <glossterm>
482 <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link> 438 <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link>
483 </glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'> 439 </glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'>
484 IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2") might also be 440 IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2").
485 needed. Full details on what these variables do and the meaning of 441 You can find full details on these variables in the reference section.
486 their contents is available through the links. There're lots of existing 442 You can leverage many existing machine <filename>.conf</filename> files from
487 machine .conf files which can be easily leveraged from meta/conf/machine/. 443 <filename>meta/conf/machine/</filename>.
488 </para> 444 </para>
489 </section> 445 </section>
490 446
491 <section id="platdev-newmachine-kernel"> 447 <section id="platdev-newmachine-kernel">
492 <title>Adding a kernel for the machine</title> 448 <title>Adding a Kernel for the Machine</title>
493 <para> 449 <para>
494 Poky needs to be able to build a kernel for the machine. You need 450 Poky needs to be able to build a kernel for the machine.
495 to either create a new kernel recipe for this machine or extend an 451 You need to either create a new kernel recipe for this machine, or extend an
496 existing recipe. There are plenty of kernel examples in the 452 existing recipe.
497 meta/recipes-kernel/linux directory which can be used as references. 453 You can find several kernel examples in the <filename>meta/recipes-kernel/linux</filename>
454 directory that can be used as references.
498 </para> 455 </para>
499 <para> 456 <para>
500 If creating a new recipe the "normal" recipe writing rules apply 457 If you are creating a new recipe, the "normal" recipe-writing rules apply for setting
501 for setting up a <glossterm><link linkend='var-SRC_URI'>SRC_URI 458 up a <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
502 </link></glossterm> including any patches and setting <glossterm> 459 This means specifying any necessary patches and setting <glossterm>
503 <link linkend='var-S'>S</link></glossterm> to point at the source 460 <link linkend='var-S'>S</link></glossterm> to point at the source code.
504 code. You will need to create a configure task which configures the 461 You need to create a "configure" task that configures the unpacked kernel with a defconfig.
505 unpacked kernel with a defconfig be that through a "make defconfig" 462 You can do this by using a <filename>make defconfig</filename> command or
506 command or more usually though copying in a suitable defconfig and 463 more commonly by copying in a suitable defconfig and and then running
507 running "make oldconfig". By making use of "inherit kernel" and also 464 <filename>make oldconfig</filename>.
508 maybe some of the linux-*.inc files, most other functionality is 465 By making use of "inherit kernel" and potentially some of the
509 centralised and the the defaults of the class normally work well. 466 <filename>linux-*.inc</filename> files, most other functionality is
467 centralized and the the defaults of the class normally work well.
510 </para> 468 </para>
511 <para> 469 <para>
512 If extending an existing kernel it is usually a case of adding a 470 If you are extending an existing kernel, it is usually a matter of adding a
513 suitable defconfig file in a location similar to that used by other 471 suitable <filename>defconfig</filename> file.
514 machine's defconfig files in a given kernel, possibly listing it in 472 The file needs to be added into a location similar to <filename>defconfig</filename> files
515 the SRC_URI and adding the machine to the expression in <glossterm> 473 used for other machines in a given kernel.
516 <link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link> 474 A possible way to do this is by listing the file in the
517 </glossterm>: 475 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>
476 and adding the machine to the expression in
477 <glossterm><link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link></glossterm>:
518 </para> 478 </para>
519 <programlisting> 479 <programlisting>
520COMPATIBLE_MACHINE = '(qemux86|qemumips)' 480COMPATIBLE_MACHINE = '(qemux86|qemumips)'
@@ -522,7 +482,7 @@ COMPATIBLE_MACHINE = '(qemux86|qemumips)'
522 </section> 482 </section>
523 483
524 <section id="platdev-newmachine-formfactor"> 484 <section id="platdev-newmachine-formfactor">
525 <title>Adding a formfactor configuration file</title> 485 <title>Adding a Formfactor Configuration File</title>
526 <para> 486 <para>
527 A formfactor configuration file provides information about the 487 A formfactor configuration file provides information about the
528 target hardware on which Poky is running, and that Poky cannot 488 target hardware on which Poky is running, and that Poky cannot
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
index c2e102ce37..4f75e1a279 100644
--- a/documentation/poky-ref-manual/usingpoky.xml
+++ b/documentation/poky-ref-manual/usingpoky.xml
@@ -205,7 +205,7 @@ $ bitbake &lt;target&gt;
205 </section> 205 </section>
206 206
207 <section id='usingpoky-debugging-taskrunning'> 207 <section id='usingpoky-debugging-taskrunning'>
208 <title>Running specific tasks</title> 208 <title>Running Specific Tasks</title>
209 209
210 <para> Any given package consists of a set of tasks. 210 <para> Any given package consists of a set of tasks.
211 In most cases the series is: fetch, unpack, patch, configure, 211 In most cases the series is: fetch, unpack, patch, configure,
@@ -287,24 +287,20 @@ $ bitbake matchbox-desktop -c
287 </section> 287 </section>
288 288
289 <section id='usingpoky-debugging-buildfile'> 289 <section id='usingpoky-debugging-buildfile'>
290 <title>Building with no dependencies</title> 290 <title>Building with No Dependencies</title>
291
292 <para> 291 <para>
293 If you really want to build a specific .bb file, you can use 292 If you really want to build a specific <filename>.bb</filename> file, you can use
294 the form <command>bitbake -b somepath/somefile.bb</command>. Note that this 293 the command form <filename>bitbake -b somepath/somefile.bb</filename>.
295 will not check the dependencies so this option should only 294 This command form does not check for dependencies so you should use it
296 be used when you know its dependencies already exist. You 295 only when you know its dependencies already exist.
297 can specify fragments of the filename and bitbake will see 296 You can also specify fragments of the filename and bitbake checks for a unique match.
298 if it can find a unique match.
299 </para> 297 </para>
300
301 </section> 298 </section>
302 299
303 <section id='usingpoky-debugging-variables'> 300 <section id='usingpoky-debugging-variables'>
304 <title>Variables</title> 301 <title>Variables</title>
305
306 <para> 302 <para>
307 The "-e" option will dump the resulting environment for 303 The "-e" option dumps the resulting environment for
308 either the configuration (no package specified) or for a 304 either the configuration (no package specified) or for a
309 specific package when specified with the "-b" option. 305 specific package when specified with the "-b" option.
310 </para> 306 </para>
@@ -312,23 +308,23 @@ $ bitbake matchbox-desktop -c
312 308
313 <section id='usingpoky-debugging-others'> 309 <section id='usingpoky-debugging-others'>
314 <title>Other Tips</title> 310 <title>Other Tips</title>
315
316 <tip> 311 <tip>
317 <para>When adding new packages it is worth keeping an eye open for bad 312 <para>
318 things creeping into compiler commandlines such as references to local 313 When adding new packages it is worth watching for undesireable items making their way
319 system files (<filename>/usr/lib/</filename> or <filename>/usr/include/</filename> etc.). 314 into compiler command lines.
315 For example, you do not want references to local system files like
316 <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
320 </para> 317 </para>
321 </tip> 318 </tip>
322
323 <tip> 319 <tip>
324 <para> 320 <para>
325 If you want to remove the psplash boot splashscreen, add "psplash=false" 321 If you want to remove the psplash boot splashscreen, add "psplash=false"
326 to the kernel commandline and psplash won't load allowing you to see 322 to the kernel command line.
327 the console. It's also possible to switch out of the splashscreen by 323 Doing so prevents psplash from loading thus allowing you to see the console.
328 switching virtual console (Fn+Left or Fn+Right on a Zaurus). 324 It is also possible to switch out of the splashscreen by
325 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
329 </para> 326 </para>
330 </tip> 327 </tip>
331
332 </section> 328 </section>
333</section> 329</section>
334 330