summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual/extendpoky.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-08-18 15:26:48 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-08-23 18:47:03 -0700
commit10ddfd6f513e359114d5a11f6495168574bac80f (patch)
tree6255641ebd223104cb9c4b4d4a5bf64f702d407f /documentation/poky-ref-manual/extendpoky.xml
parent776834d63b655fcb160b9352bc18e4a4c4d4de0f (diff)
downloadpoky-10ddfd6f513e359114d5a11f6495168574bac80f.tar.gz
documentation/poky-ref-manual/extendpoky.xml: scrubbed for Poky
Converted to Yocto Project from Poky. (From yocto-docs rev: 0263e8b29efeff051184ce1700da9559ea511faf) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/poky-ref-manual/extendpoky.xml')
-rw-r--r--documentation/poky-ref-manual/extendpoky.xml1162
1 files changed, 642 insertions, 520 deletions
diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml
index 512cd9f647..e624340f10 100644
--- a/documentation/poky-ref-manual/extendpoky.xml
+++ b/documentation/poky-ref-manual/extendpoky.xml
@@ -6,202 +6,215 @@
6<title>Extending the Yocto Project</title> 6<title>Extending the Yocto Project</title>
7 <para> 7 <para>
8 This chapter provides information about how to extend the functionality 8 This chapter provides information about how to extend the functionality
9 already present in Poky. 9 already present in the Yocto Project.
10 The chapter also documents standard tasks such as adding new 10 The chapter also documents standard tasks such as adding new
11 software packages, extending or customizing images or porting Poky to 11 software packages, extending or customizing images or porting the Yocto Project to
12 new hardware (adding a new machine). 12 new hardware (adding a new machine).
13 Finally, the chapter contains advice about how to make changes to Poky to achieve the best results. 13 Finally, the chapter contains advice about how to make changes to the
14 Yocto Project 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>
19
18 <para> 20 <para>
19 To add a package into Poky you need to write a recipe for it. 21 To add a package into the Yocto Project you need to write a recipe for it.
20 Writing a recipe means creating a <filename>.bb</filename> file that sets some 22 Writing a recipe means creating a <filename>.bb</filename> file that sets some
21 variables. 23 variables.
22 For information on variables that are useful for recipes and for information about recipe naming 24 For information on variables that are useful for recipes and for information about recipe naming
23 issues, see the <link linkend='ref-varlocality-recipe-required'>Recipe Variables - Required</link> 25 issues, see the
24 appendix. 26 <link linkend='ref-varlocality-recipe-required'>Recipe Variables - Required</link> section.
25 </para> 27 </para>
28
26 <para> 29 <para>
27 Before writing a recipe from scratch it is often useful to check 30 Before writing a recipe from scratch, it is often useful to check
28 whether someone else has written one already. 31 whether someone else has written one already.
29 OpenEmbedded is a good place to look as it has a wider scope and range of packages. 32 OpenEmbedded is a good place to look as it has a wider scope and range of packages.
30 Because Poky aims to be compatible with OpenEmbedded, most recipes should 33 Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes
31 simply work in Poky. 34 you find there should work in Yocto Project.
32 </para> 35 </para>
36
33 <para> 37 <para>
34 For new packages, the simplest way to add a recipe is to base it on a similar 38 For new packages, the simplest way to add a recipe is to base it on a similar
35 pre-existing recipe. 39 pre-existing recipe.
36 Following are some examples showing how to add standard types of packages: 40 The sections that follow provide some examples that show how to add standard
41 types of packages.
37 </para> 42 </para>
38 43
39 <section id='usingpoky-extend-addpkg-singlec'> 44 <section id='usingpoky-extend-addpkg-singlec'>
40 <title>Single .c File Package (Hello World!)</title> 45 <title>Single .c File Package (Hello World!)</title>
46
41 <para> 47 <para>
42 Building an application from a single file that is stored locally (e.g. under 48 Building an application from a single file that is stored locally (e.g. under
43 <filename>files/</filename>) requires a recipe that has the file listed in 49 <filename>files/</filename>) requires a recipe that has the file listed in
44 the <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. 50 the <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> variable.
45 Additionally, you need to manually write the "do_compile" and 51 Additionally, you need to manually write the <filename>do_compile</filename> and
46 "do_install" tasks. 52 <filename>do_install</filename> tasks.
47 The <glossterm><link linkend='var-S'>S</link></glossterm> variable defines the 53 The <filename><link linkend='var-S'>S</link></filename> variable defines the
48 directory containing the source code, which is set to <glossterm><link linkend='var-WORKDIR'> 54 directory containing the source code, which is set to <filename><link linkend='var-WORKDIR'>
49 WORKDIR</link></glossterm> in this case - the directory BitBake uses for the build. 55 WORKDIR</link></filename> in this case - the directory BitBake uses for the build.
50 </para> 56 <literallayout class='monospaced'>
51 <programlisting> 57 DESCRIPTION = "Simple helloworld application"
52DESCRIPTION = "Simple helloworld application" 58 SECTION = "examples"
53SECTION = "examples" 59 LICENSE = "MIT"
54LICENSE = "MIT" 60 PR = "r0"
55PR = "r0"
56 61
57SRC_URI = "file://helloworld.c" 62 SRC_URI = "file://helloworld.c"
58 63
59S = "${WORKDIR}" 64 S = "${WORKDIR}"
60 65
61do_compile() { 66 do_compile() {
62 ${CC} helloworld.c -o helloworld 67 ${CC} helloworld.c -o helloworld
63} 68 }
69
70 do_install() {
71 install -d ${D}${bindir}
72 install -m 0755 helloworld ${D}${bindir}
73 }
74 </literallayout>
75 </para>
64 76
65do_install() {
66 install -d ${D}${bindir}
67 install -m 0755 helloworld ${D}${bindir}
68}
69 </programlisting>
70 <para> 77 <para>
71 By default, the "helloworld", "helloworld-dbg" and "helloworld-dev" 78 By default, the <filename>helloworld</filename>, <filename>helloworld-dbg</filename>,
72 packages are built. 79 and <filename>helloworld-dev</filename> packages are built.
73 For information on how to customize the packaging process, see 80 For information on how to customize the packaging process, see the
74 <link linkend='usingpoky-extend-addpkg-files'>Controlling Package Content</link>. 81 <link linkend='usingpoky-extend-addpkg-files'>Controlling Package Content</link> section.
75 </para> 82 </para>
76 </section> 83 </section>
77 84
78 <section id='usingpoky-extend-addpkg-autotools'> 85 <section id='usingpoky-extend-addpkg-autotools'>
79 <title>Autotooled Package</title> 86 <title>Autotooled Package</title>
80 <para> 87 <para>
81 Applications that use autotools such as <filename>autoconf</filename> and 88 Applications that use Autotools such as <filename>autoconf</filename> and
82 <filename>automake</filename> require a recipe that has a source archive listed in 89 <filename>automake</filename> require a recipe that has a source archive listed in
83 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> and 90 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> and
84 also inherits autotools, which instructs BitBake to use the 91 also inherits Autotools, which instructs BitBake to use the
85 <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps 92 <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps
86 needed to build an autotooled application. 93 needed to build an Autotool-based application.
87 The result of the build is automatically packaged. 94 The result of the build is automatically packaged.
88 And, if the application uses NLS for localization, packages with local information are 95 And, if the application uses NLS for localization, packages with local information are
89 generated (one package per language). 96 generated (one package per language).
90 Following is one example: (<filename>hello_2.3.bb</filename>) 97 Following is one example: (<filename>hello_2.3.bb</filename>)
91 </para> 98 <literallayout class='monospaced'>
92 <programlisting> 99 DESCRIPTION = "GNU Helloworld application"
93DESCRIPTION = "GNU Helloworld application" 100 SECTION = "examples"
94SECTION = "examples" 101 LICENSE = "GPLv2+"
95LICENSE = "GPLv2+" 102 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
96LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" 103 PR = "r0"
97PR = "r0"
98 104
99SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" 105 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
100 106
101inherit autotools gettext 107 inherit autotools gettext
102 </programlisting> 108 </literallayout>
103 <para>
104 The variable <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
105 </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
106 track source license changes</link>.
107 You can quickly create autotool-based recipes in a manner similar to the previous example.
108 </para> 109 </para>
109 110
111 <para>
112 The variable <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
113 </filename> is used to track source license changes as described in the
114 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>Track License Change</link>
115 section.
116 You can quickly create Autotool-based recipes in a manner similar to the previous example.
117 </para>
110 </section> 118 </section>
111 119
112 <section id='usingpoky-extend-addpkg-makefile'> 120 <section id='usingpoky-extend-addpkg-makefile'>
113 <title>Makefile-Based Package</title> 121 <title>Makefile-Based Package</title>
122
114 <para> 123 <para>
115 Applications that use GNU <filename>make</filename> also require a recipe that has 124 Applications that use GNU <filename>make</filename> also require a recipe that has
116 the source archive listed in <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. 125 the source archive listed in <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>.
117 You do not need to add a "do_compile" step since by default BitBake 126 You do not need to add a <filename>do_compile</filename> step since by default BitBake
118 starts the <filename>make</filename> command to compile the application. 127 starts the <filename>make</filename> command to compile the application.
119 If you need additional <filename>make</filename> options you should store them in the 128 If you need additional <filename>make</filename> options you should store them in the
120 <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable. 129 <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
121 BitBake passes these options into the <filename>make</filename> GNU invocation. 130 BitBake passes these options into the <filename>make</filename> GNU invocation.
122 Note that a "do_install" task is still required. 131 Note that a <filename>do_install</filename> task is still required.
123 Otherwise BitBake runs an empty "do_install" task by default. 132 Otherwise BitBake runs an empty <filename>do_install</filename> task by default.
124 </para> 133 </para>
134
125 <para> 135 <para>
126 Some applications might require extra parameters to be passed to the compiler. 136 Some applications might require extra parameters to be passed to the compiler.
127 For example the application might need an additional header path. 137 For example, the application might need an additional header path.
128 You can accomplish this by adding to the <glossterm><link linkend='var-CFLAGS'>CFLAGS</link> 138 You can accomplish this by adding to the <filename><link linkend='var-CFLAGS'>CFLAGS</link>
129 </glossterm> variable. 139 </filename> variable.
130 The following example shows this: 140 The following example shows this:
141 <literallayout class='monospaced'>
142 CFLAGS_prepend = "-I ${S}/include "
143 </literallayout>
131 </para> 144 </para>
132 <programlisting> 145
133CFLAGS_prepend = "-I ${S}/include "
134 </programlisting>
135 <para> 146 <para>
136 In the following example <filename>mtd-utils</filename> is a makefile-based package: 147 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
148 <literallayout class='monospaced'>
149 DESCRIPTION = "Tools for managing memory technology devices."
150 SECTION = "base"
151 DEPENDS = "zlib lzo e2fsprogs util-linux"
152 HOMEPAGE = "http://www.linux-mtd.infradead.org/"
153 LICENSE = "GPLv2"
154
155 SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=v${PV}"
156
157 S = "${WORKDIR}/git/"
158
159 EXTRA_OEMAKE = "'CC=${CC}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' \
160 'BUILDDIR=${S}'"
161
162 do_install () {
163 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
164 INCLUDEDIR=${includedir}
165 install -d ${D}${includedir}/mtd/
166 for f in ${S}/include/mtd/*.h; do
167 install -m 0644 $f ${D}${includedir}/mtd/
168 done
169 }
170 </literallayout>
137 </para> 171 </para>
138 <programlisting>
139DESCRIPTION = "Tools for managing memory technology devices."
140SECTION = "base"
141DEPENDS = "zlib lzo e2fsprogs util-linux"
142HOMEPAGE = "http://www.linux-mtd.infradead.org/"
143LICENSE = "GPLv2"
144
145SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=v${PV}"
146
147S = "${WORKDIR}/git/"
148
149EXTRA_OEMAKE = "'CC=${CC}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' \
150 'BUILDDIR=${S}'"
151
152do_install () {
153 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
154 INCLUDEDIR=${includedir}
155 install -d ${D}${includedir}/mtd/
156 for f in ${S}/include/mtd/*.h; do
157 install -m 0644 $f ${D}${includedir}/mtd/
158 done
159}
160 </programlisting>
161
162 </section> 172 </section>
163 173
164 <section id='usingpoky-extend-addpkg-files'> 174 <section id='usingpoky-extend-addpkg-files'>
165 <title>Controlling Package Content</title> 175 <title>Controlling Package Content</title>
176
166 <para> 177 <para>
167 You can use the variables <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm> and 178 You can use the variables <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> and
168 <glossterm><link linkend='var-FILES'>FILES</link></glossterm> to split an application into 179 <filename><link linkend='var-FILES'>FILES</link></filename> to split an application into
169 multiple packages. 180 multiple packages.
170 </para> 181 </para>
182
171 <para> 183 <para>
172 Following is an example that uses the "libXpm" recipe (<filename>libxpm_3.5.7.bb</filename>). 184 Following is an example that uses the <filename>libXpm</filename> recipe.
173 By default, the "libXpm" recipe generates a single package that contains the library along 185 By default, this recipe generates a single package that contains the library along
174 with a few binaries. 186 with a few binaries.
175 You can modify the recipe to split the binaries into separate packages: 187 You can modify the recipe to split the binaries into separate packages:
176 </para> 188 <literallayout class='monospaced'>
177 <programlisting> 189 require xorg-lib-common.inc
178require xorg-lib-common.inc 190
191 DESCRIPTION = "X11 Pixmap library"
192 LICENSE = "X-BSD"
193 DEPENDS += "libxext libsm libxt"
194 PR = "r3"
195 PE = "1"
179 196
180DESCRIPTION = "X11 Pixmap library" 197 XORG_PN = "libXpm"
181LICENSE = "X-BSD"
182DEPENDS += "libxext libsm libxt"
183PR = "r3"
184PE = "1"
185 198
186XORG_PN = "libXpm" 199 PACKAGES =+ "sxpm cxpm"
200 FILES_cxpm = "${bindir}/cxpm"
201 FILES_sxpm = "${bindir}/sxpm"
202 </literallayout>
203 </para>
187 204
188PACKAGES =+ "sxpm cxpm"
189FILES_cxpm = "${bindir}/cxpm"
190FILES_sxpm = "${bindir}/sxpm"
191 </programlisting>
192 <para> 205 <para>
193 In the previous example we want to ship the "sxpm" and "cxpm" binaries 206 In the previous example, we want to ship the <filename>sxpm</filename>
194 in separate packages. 207 and <filename>cxpm</filename> binaries in separate packages.
195 Since "bindir" would be packaged into the main 208 Since <filename>bindir</filename> would be packaged into the main
196 <glossterm><link linkend='var-PN'>PN</link></glossterm> 209 <filename><link linkend='var-PN'>PN</link></filename>
197 package by default, we prepend the <glossterm><link linkend='var-PACKAGES'>PACKAGES</link> 210 package by default, we prepend the <filename><link linkend='var-PACKAGES'>PACKAGES</link>
198 </glossterm> variable so additional package names are added to the start of list. 211 </filename> variable so additional package names are added to the start of list.
199 This results in the extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_* 212 This results in the extra <filename><link linkend='var-FILES'>FILES</link></filename>_*
200 variables then containing information that define which files and 213 variables then containing information that define which files and
201 directories go into which packages. 214 directories go into which packages.
202 Files included by earlier packages are skipped by latter packages. 215 Files included by earlier packages are skipped by latter packages.
203 Thus, the main <glossterm><link linkend='var-PN'>PN</link></glossterm> package does not include 216 Thus, the main <filename><link linkend='var-PN'>PN</link></filename> package
204 the above listed files. 217 does not include the above listed files.
205 </para> 218 </para>
206 </section> 219 </section>
207 220
@@ -213,43 +226,47 @@ FILES_sxpm = "${bindir}/sxpm"
213 </filename> function to the <filename>.bb</filename> file and use 226 </filename> function to the <filename>.bb</filename> file and use
214 <filename>PACKAGENAME</filename> as the name of the package you want to attach to the 227 <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
215 <filename>postinst</filename> script. 228 <filename>postinst</filename> script.
216 Normally <glossterm><link linkend='var-PN'>PN</link></glossterm> can be used, which 229 Normally <filename><link linkend='var-PN'>PN</link></filename> can be used, which
217 automatically expands to PACKAGENAME. 230 automatically expands to PACKAGENAME.
218 A post-installation function has the following structure: 231 A post-installation function has the following structure:
232 <literallayout class='monospaced'>
233 pkg_postinst_PACKAGENAME () {
234 #!/bin/sh -e
235 # Commands to carry out
236 }
237 </literallayout>
219 </para> 238 </para>
220 <programlisting> 239
221pkg_postinst_PACKAGENAME () {
222#!/bin/sh -e
223# Commands to carry out
224}
225 </programlisting>
226 <para> 240 <para>
227 The script defined in the post-installation function is called when the rootfs is made. 241 The script defined in the post-installation function is called when the
242 root filesystem is created.
228 If the script succeeds, the package is marked as installed. 243 If the script succeeds, the package is marked as installed.
229 If the script fails, the package is marked as unpacked and the script is 244 If the script fails, the package is marked as unpacked and the script is
230 executed when the image boots again. 245 executed when the image boots again.
231 </para> 246 </para>
247
232 <para> 248 <para>
233 Sometimes it is necessary for the execution of a post-installation 249 Sometimes it is necessary for the execution of a post-installation
234 script to be delayed until the first boot. 250 script to be delayed until the first boot.
235 For example, the script might need to be executed on the device itself. 251 For example, the script might need to be executed on the device itself.
236 To delay script execution until boot time, use the following structure in the 252 To delay script execution until boot time, use the following structure in the
237 post-installation script: 253 post-installation script:
254 <literallayout class='monospaced'>
255 pkg_postinst_PACKAGENAME () {
256 #!/bin/sh -e
257 if [ x"$D" = "x" ]; then
258 # Actions to carry out on the device go here
259 else
260 exit 1
261 fi
262 }
263 </literallayout>
238 </para> 264 </para>
239 <programlisting> 265
240pkg_postinst_PACKAGENAME () {
241#!/bin/sh -e
242if [ x"$D" = "x" ]; then
243 # Actions to carry out on the device go here
244else
245 exit 1
246fi
247}
248 </programlisting>
249 <para> 266 <para>
250 The previous example delays execution until the image boots again because the 267 The previous example delays execution until the image boots again because the
251 <glossterm><link linkend='var-D'>D</link></glossterm> variable points 268 <filename><link linkend='var-D'>D</link></filename> variable points
252 to the 'image' directory when the rootfs is being made at build time but 269 to the directory containing the image when the root filesystem is created at build time but
253 is unset when executed on the first boot. 270 is unset when executed on the first boot.
254 </para> 271 </para>
255 </section> 272 </section>
@@ -257,199 +274,236 @@ fi
257 274
258 <section id='usingpoky-extend-customimage'> 275 <section id='usingpoky-extend-customimage'>
259 <title>Customizing Images</title> 276 <title>Customizing Images</title>
277
260 <para> 278 <para>
261 You can customize Poky images to satisfy particular requirements. 279 You can customize Yocto Project images to satisfy particular requirements.
262 This section describes several methods and provides guidelines for each. 280 This section describes several methods and provides guidelines for each.
263 </para> 281 </para>
264 282
265 <section id='usingpoky-extend-customimage-custombb'> 283 <section id='usingpoky-extend-customimage-custombb'>
266 <title>Customizing Images Using Custom .bb Files</title> 284 <title>Customizing Images Using Custom .bb Files</title>
285
267 <para> 286 <para>
268 One way to get additional software into an image is to create a custom image. 287 One way to get additional software into an image is to create a custom image.
269 The following example shows the form for the two lines you need: 288 The following example shows the form for the two lines you need:
289 <literallayout class='monospaced'>
290 IMAGE_INSTALL = "task-core-x11-base package1 package2"
291
292 inherit core-image
293 </literallayout>
270 </para> 294 </para>
271 <programlisting>
272IMAGE_INSTALL = "task-core-x11-base package1 package2"
273 295
274inherit core-image
275 </programlisting>
276 <para> 296 <para>
277 By creating a custom image, a developer has total control 297 By creating a custom image, a developer has total control
278 over the contents of the image. 298 over the contents of the image.
279 It is important to use the correct names of packages in the 299 It is important to use the correct names of packages in the
280 <glossterm><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> variable. 300 <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename> variable.
281 You must use the OpenEmbedded notation and not the Debian notation for the names 301 You must use the OpenEmbedded notation and not the Debian notation for the names
282 (e.g. "glibc-dev" instead of "libc6-dev"). 302 (e.g. <filename>glibc-dev</filename> instead of <filename>libc6-dev</filename>).
283 </para> 303 </para>
304
284 <para> 305 <para>
285 The other method for creating a custom image is to modify an existing image. 306 The other method for creating a custom image is to modify an existing image.
286 For example, if a developer wants to add "strace" into "core-image-sato", they can use 307 For example, if a developer wants to add <filename>strace</filename> into
287 the following recipe: 308 the <filename>core-image-sato</filename> image, they can use the following recipe:
288 </para> 309 <literallayout class='monospaced'>
289 <programlisting> 310 require core-image-sato.bb
290require core-image-sato.bb
291 311
292IMAGE_INSTALL += "strace" 312 IMAGE_INSTALL += "strace"
293 </programlisting> 313 </literallayout>
314 </para>
294 </section> 315 </section>
295 316
296 <section id='usingpoky-extend-customimage-customtasks'> 317 <section id='usingpoky-extend-customimage-customtasks'>
297 <title>Customizing Images Using Custom Tasks</title> 318 <title>Customizing Images Using Custom Tasks</title>
319
298 <para> 320 <para>
299 For complex custom images, the best approach is to create a custom task package 321 For complex custom images, the best approach is to create a custom task package
300 that is used to build the image or images. 322 that is used to build the image or images.
301 A good example of a tasks package is 323 A good example of a tasks package is
302 <filename>meta/recipes-sato/tasks/task-poky.bb</filename>. 324 <filename>meta/recipes-sato/tasks/task-poky.bb</filename>.
303 The <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm> 325 The <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
304 variable lists the task packages to build along with the complementary 326 variable lists the task packages to build along with the complementary
305 -dbg and -dev packages. 327 <filename>-dbg</filename> and <filename>-dev</filename> packages.
306 For each package added, you can use 328 For each package added, you can use
307 <glossterm><link linkend='var-RDEPENDS'>RDEPENDS</link></glossterm> 329 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
308 and <glossterm><link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></glossterm> 330 and <filename><link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
309 entries to provide a list of packages the parent task package should contain. 331 entries to provide a list of packages the parent task package should contain.
310 Following is an example: 332 Following is an example:
333 <literallayout class='monospaced'>
334 DESCRIPTION = "My Custom Tasks"
335
336 PACKAGES = "\
337 task-custom-apps \
338 task-custom-apps-dbg \
339 task-custom-apps-dev \
340 task-custom-tools \
341 task-custom-tools-dbg \
342 task-custom-tools-dev \
343 "
344
345 RDEPENDS_task-custom-apps = "\
346 dropbear \
347 portmap \
348 psplash"
349
350 RDEPENDS_task-custom-tools = "\
351 oprofile \
352 oprofileui-server \
353 lttng-control \
354 lttng-viewer"
355
356 RRECOMMENDS_task-custom-tools = "\
357 kernel-module-oprofile"
358 </literallayout>
311 </para> 359 </para>
312 <para> 360
313 <programlisting>
314DESCRIPTION = "My Custom Tasks"
315
316PACKAGES = "\
317 task-custom-apps \
318 task-custom-apps-dbg \
319 task-custom-apps-dev \
320 task-custom-tools \
321 task-custom-tools-dbg \
322 task-custom-tools-dev \
323 "
324
325RDEPENDS_task-custom-apps = "\
326 dropbear \
327 portmap \
328 psplash"
329
330RDEPENDS_task-custom-tools = "\
331 oprofile \
332 oprofileui-server \
333 lttng-control \
334 lttng-viewer"
335
336RRECOMMENDS_task-custom-tools = "\
337 kernel-module-oprofile"
338 </programlisting>
339 </para>
340 <para> 361 <para>
341 In the previous example, two task packages are created with their dependencies and their 362 In the previous example, two task packages are created with their dependencies and their
342 recommended package dependencies listed: <filename>task-custom-apps</filename>, and 363 recommended package dependencies listed: <filename>task-custom-apps</filename>, and
343 <filename>task-custom-tools</filename>. 364 <filename>task-custom-tools</filename>.
344 To build an image using these task packages, you need to add 365 To build an image using these task packages, you need to add
345 "task-custom-apps" and/or "task-custom-tools" to <glossterm><link 366 <filename>task-custom-apps</filename> and/or
346 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm>. 367 <filename>task-custom-tools</filename> to
368 <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>.
347 For other forms of image dependencies see the other areas of this section. 369 For other forms of image dependencies see the other areas of this section.
348 </para> 370 </para>
349 </section> 371 </section>
350 372
351 <section id='usingpoky-extend-customimage-imagefeatures'> 373 <section id='usingpoky-extend-customimage-imagefeatures'>
352 <title>Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES</title> 374 <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
375 <filename>EXTRA_IMAGE_FEATURES</filename></title>
376
353 <para> 377 <para>
354 Ultimately users might want to add extra image "features" to the set used by Poky with the 378 Ultimately users might want to add extra image features to the set used by
355 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> 379 Yocto Project with the
380 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
356 variable. 381 variable.
357 To create these features, the best reference is 382 To create these features, the best reference is
358 <filename>meta/classes/core-image.bbclass</filename>, which shows how poky achieves this. 383 <filename>meta/classes/core-image.bbclass</filename>, which shows how the
384 Yocto Project achieves this.
359 In summary, the file looks at the contents of the 385 In summary, the file looks at the contents of the
360 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> 386 <filename>IMAGE_FEATURES</filename>
361 variable and then maps that into a set of tasks or packages. 387 variable and then maps that into a set of tasks or packages.
362 Based on this information the <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link> 388 Based on this information the
363 </glossterm> variable is generated automatically. 389 <filename><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link></filename> variable
390 is generated automatically.
364 Users can add extra features by extending the class or creating a custom class for use 391 Users can add extra features by extending the class or creating a custom class for use
365 with specialized image <filename>.bb</filename> files. 392 with specialized image <filename>.bb</filename> files.
366 You can also add more features by configuring the 393 You can also add more features by configuring the
367 <glossterm><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></glossterm> 394 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
368 variable in the <filename>local.conf</filename> file. 395 variable in the <filename>local.conf</filename> file found in the Yocto Project
396 files located in the build directory.
369 </para> 397 </para>
398
370 <para> 399 <para>
371 Poky ships with two SSH servers you can use in your images: Dropbear and OpenSSH. 400 The Yocto Project ships with two SSH servers you can use in your images:
401 Dropbear and OpenSSH.
372 Dropbear is a minimal SSH server appropriate for resource-constrained environments, 402 Dropbear is a minimal SSH server appropriate for resource-constrained environments,
373 while OpenSSH is a well-known standard SSH server implementation. 403 while OpenSSH is a well-known standard SSH server implementation.
374 By default, core-image-sato is configured to use Dropbear. 404 By default, the <filename>core-image-sato</filename> image is configured to use Dropbear.
375 The core-image-basic and core-image-lsb images both include OpenSSH. 405 The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename>
406 images both include OpenSSH.
376 To change these defaults, edit the <filename>IMAGE_FEATURES</filename> variable 407 To change these defaults, edit the <filename>IMAGE_FEATURES</filename> variable
377 so that it sets the image you are working with to include ssh-server-dropbear 408 so that it sets the image you are working with to include
378 or ssh-server-openssh. 409 <filename>ssh-server-dropbear</filename> or <filename>ssh-server-openssh</filename>.
379 </para> 410 </para>
380 </section> 411 </section>
381 412
382 <section id='usingpoky-extend-customimage-localconf'> 413 <section id='usingpoky-extend-customimage-localconf'>
383 <title>Customizing Images Using local.conf</title> 414 <title>Customizing Images Using <filename>local.conf</filename></title>
415
384 <para> 416 <para>
385 It is possible to customize image contents by using variables used by distribution 417 It is possible to customize image contents by using variables used by distribution
386 maintainers in the <filename>local.conf</filename>. 418 maintainers in the <filename>local.conf</filename> found in the Yocto Project
419 build directory.
387 This method only allows the addition of packages and is not recommended. 420 This method only allows the addition of packages and is not recommended.
388 </para> 421 </para>
422
389 <para> 423 <para>
390 For example, to add the "strace" package into the image you would add this package to the 424 For example, to add the <filename>strace</filename> package into the image,
391 <filename>local.conf</filename> file: 425 you would add this package to the <filename>local.conf</filename> file:
426 <literallayout class='monospaced'>
427 DISTRO_EXTRA_RDEPENDS += "strace"
428 </literallayout>
392 </para> 429 </para>
393 <programlisting> 430
394DISTRO_EXTRA_RDEPENDS += "strace"
395 </programlisting>
396 <para> 431 <para>
397 However, since the <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'> 432 However, since the
398 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable is for 433 <filename><link linkend='var-DISTRO_EXTRA_RDEPENDS'>DISTRO_EXTRA_RDEPENDS</link></filename>
434 variable is for
399 distribution maintainers, adding packages using this method is not as simple as adding 435 distribution maintainers, adding packages using this method is not as simple as adding
400 them using a custom <filename>.bb</filename> file. 436 them using a custom <filename>.bb</filename> file.
401 Using the <filename>local.conf</filename> file method could result in some packages 437 Using the <filename>local.conf</filename> file method could result in some packages
402 needing to be recreated. 438 needing to be recreated.
403 For example, if packages were previously created and the image was rebuilt then the packages 439 For example, if packages were previously created and the image was rebuilt, then the packages
404 would need to be recreated. 440 would need to be recreated.
405 </para> 441 </para>
442
406 <para> 443 <para>
407 Cleaning task-* packages are required because they use the 444 Cleaning <filename>task-*</filename> packages are required because they use the
408 <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'> 445 <filename>DISTRO_EXTRA_RDEPENDS</filename> variable.
409 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. 446 You do not have to build them by hand because Yocto Project images depend on the
410 You do not have to build them by hand because Poky images depend on the packages they contain. 447 packages they contain.
411 This means dependencies are automatically built when the image builds. 448 This means dependencies are automatically built when the image builds.
412 For this reason we don't use the "rebuild" task. 449 For this reason we do not use the <filename>rebuild</filename> task.
413 In this case the "rebuild" task does not care about 450 In this case the <filename>rebuild</filename> task does not care about
414 dependencies - it only rebuilds the specified package. 451 dependencies - it only rebuilds the specified package.
452 <literallayout class='monospaced'>
453 $ bitbake -c clean task-boot task-base task-poky
454 $ bitbake core-image-sato
455 </literallayout>
415 </para> 456 </para>
416 <programlisting>
417$ bitbake -c clean task-boot task-base task-poky
418$ bitbake core-image-sato
419 </programlisting>
420 </section> 457 </section>
421
422 </section> 458 </section>
423 459
424 <section id="platdev-newmachine"> 460 <section id="platdev-newmachine">
425 <title>Porting Poky to a New Machine</title> 461 <title>Porting the Yocto Project to a New Machine</title>
462
426 <para> 463 <para>
427 Adding a new machine to Poky is a straightforward process. 464 Adding a new machine to the Yocto Project is a straightforward process.
428 This section provides information that gives you an idea of the changes you must make. 465 This section provides information that gives you an idea of the changes you must make.
429 The information covers adding machines similar to those Poky already supports. 466 The information covers adding machines similar to those the Yocto Project already supports.
430 Although well within the capabilities of Poky, adding a totally new architecture might require 467 Although well within the capabilities of the Yocto Project, adding a totally new architecture
468 might require
431 changes to <filename>gcc/glibc</filename> and to the site information, which is 469 changes to <filename>gcc/glibc</filename> and to the site information, which is
432 beyond the scope of this manual. 470 beyond the scope of this manual.
433 </para> 471 </para>
434 472
435 <section id="platdev-newmachine-conffile"> 473 <section id="platdev-newmachine-conffile">
436 <title>Adding the Machine Configuration File</title> 474 <title>Adding the Machine Configuration File</title>
475
437 <para> 476 <para>
438 To add a machine configuration you need to add a <filename>.conf</filename> file 477 To add a machine configuration you need to add a <filename>.conf</filename> file
439 with details of the device being added to the <filename>conf/machine/</filename> file. 478 with details of the device being added to the <filename>conf/machine/</filename> file.
440 The name of the file determines the name Poky uses to reference the new machine. 479 The name of the file determines the name the Yocto Project uses to reference the new machine.
441 </para> 480 </para>
481
442 <para> 482 <para>
443 The most important variables to set in this file are <glossterm> 483 The most important variables to set in this file are as follows:
444 <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm> (e.g. "arm"), 484 <itemizedlist>
445 <glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm>_virtual/kernel 485 <listitem><para><filename><link linkend='var-TARGET_ARCH'>
446 (see below) and <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></glossterm> 486 TARGET_ARCH</link></filename> (e.g. "arm")</para></listitem>
447 (e.g. "kernel26 apm screen wifi"). 487 <listitem><para><filename><link linkend='var-PREFERRED_PROVIDER'>
448 You might also need other variables like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE 488 PREFERRED_PROVIDER</link></filename>_virtual/kernel (see below)</para></listitem>
449 </link></glossterm> (e.g. "115200 ttyS0"), <glossterm> 489 <listitem><para><filename><link linkend='var-MACHINE_FEATURES'>
450 <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link> 490 MACHINE_FEATURES</link></filename> (e.g. "kernel26 apm screen wifi")</para></listitem>
451 </glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'> 491 </itemizedlist>
452 IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2"). 492 </para>
493
494 <para>
495 You might also need these variables:
496 <itemizedlist>
497 <listitem><para><filename><link linkend='var-SERIAL_CONSOLE'>
498 SERIAL_CONSOLE</link></filename> (e.g. "115200 ttyS0")</para></listitem>
499 <listitem><para><filename><link linkend='var-KERNEL_IMAGETYPE'>
500 KERNEL_IMAGETYPE</link></filename> (e.g. "zImage")</para></listitem>
501 <listitem><para><filename><link linkend='var-IMAGE_FSTYPES'>
502 IMAGE_FSTYPES</link></filename> (e.g. "tar.gz jffs2")</para></listitem>
503 </itemizedlist>
504 </para>
505
506 <para>
453 You can find full details on these variables in the reference section. 507 You can find full details on these variables in the reference section.
454 You can leverage many existing machine <filename>.conf</filename> files from 508 You can leverage many existing machine <filename>.conf</filename> files from
455 <filename>meta/conf/machine/</filename>. 509 <filename>meta/conf/machine/</filename>.
@@ -458,219 +512,237 @@ $ bitbake core-image-sato
458 512
459 <section id="platdev-newmachine-kernel"> 513 <section id="platdev-newmachine-kernel">
460 <title>Adding a Kernel for the Machine</title> 514 <title>Adding a Kernel for the Machine</title>
515
461 <para> 516 <para>
462 Poky needs to be able to build a kernel for the machine. 517 The Yocto Project needs to be able to build a kernel for the machine.
463 You need to either create a new kernel recipe for this machine, or extend an 518 You need to either create a new kernel recipe for this machine, or extend an
464 existing recipe. 519 existing recipe.
465 You can find several kernel examples in the <filename>meta/recipes-kernel/linux</filename> 520 You can find several kernel examples in the
466 directory that can be used as references. 521 Yocto Project file's <filename>meta/recipes-kernel/linux</filename>
522 directory that you can use as references.
467 </para> 523 </para>
524
468 <para> 525 <para>
469 If you are creating a new recipe, the "normal" recipe-writing rules apply for setting 526 If you are creating a new recipe, normal recipe-writing rules apply for setting
470 up a <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. 527 up a <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>.
471 This means specifying any necessary patches and setting <glossterm> 528 Thus, you need to specify any necessary patches and set
472 <link linkend='var-S'>S</link></glossterm> to point at the source code. 529 <filename><link linkend='var-S'>S</link></filename> to point at the source code.
473 You need to create a "configure" task that configures the unpacked kernel with a defconfig. 530 You need to create a <filename>configure</filename> task that configures the
474 You can do this by using a <filename>make defconfig</filename> command or 531 unpacked kernel with a defconfig.
475 more commonly by copying in a suitable <filename>defconfig</filename> file and and then running 532 You can do this by using a <filename>make defconfig</filename> command or,
533 more commonly, by copying in a suitable <filename>defconfig</filename> file and and then running
476 <filename>make oldconfig</filename>. 534 <filename>make oldconfig</filename>.
477 By making use of "inherit kernel" and potentially some of the 535 By making use of <filename>inherit kernel</filename> and potentially some of the
478 <filename>linux-*.inc</filename> files, most other functionality is 536 <filename>linux-*.inc</filename> files, most other functionality is
479 centralized and the the defaults of the class normally work well. 537 centralized and the the defaults of the class normally work well.
480 </para> 538 </para>
539
481 <para> 540 <para>
482 If you are extending an existing kernel, it is usually a matter of adding a 541 If you are extending an existing kernel, it is usually a matter of adding a
483 suitable <filename>defconfig</filename> file. 542 suitable defconfig file.
484 The file needs to be added into a location similar to <filename>defconfig</filename> files 543 The file needs to be added into a location similar to defconfig files
485 used for other machines in a given kernel. 544 used for other machines in a given kernel.
486 A possible way to do this is by listing the file in the 545 A possible way to do this is by listing the file in the
487 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> 546 <filename>SRC_URI</filename> and adding the machine to the expression in
488 and adding the machine to the expression in 547 <filename><link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link></filename>:
489 <glossterm><link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link></glossterm>: 548 <literallayout class='monospaced'>
549 COMPATIBLE_MACHINE = '(qemux86|qemumips)'
550 </literallayout>
490 </para> 551 </para>
491 <programlisting>
492COMPATIBLE_MACHINE = '(qemux86|qemumips)'
493 </programlisting>
494 </section> 552 </section>
495 553
496 <section id="platdev-newmachine-formfactor"> 554 <section id="platdev-newmachine-formfactor">
497 <title>Adding a Formfactor Configuration File</title> 555 <title>Adding a Formfactor Configuration File</title>
556
498 <para> 557 <para>
499 A formfactor configuration file provides information about the 558 A formfactor configuration file provides information about the
500 target hardware on which Poky is running and information that Poky cannot 559 target hardware for which the Yocto Project is building and information that
501 obtain from other sources such as the kernel. 560 the Yocto Project cannot obtain from other sources such as the kernel.
502 Some examples of information contained in a formfactor configuration file include 561 Some examples of information contained in a formfactor configuration file include
503 framebuffer orientation, whether or not the system has a keyboard, 562 framebuffer orientation, whether or not the system has a keyboard,
504 the positioning of the keyboard in relation to the screen, and 563 the positioning of the keyboard in relation to the screen, and
505 the screen resolution. 564 the screen resolution.
506 </para> 565 </para>
566
507 <para> 567 <para>
508 Reasonable defaults are used in most cases, but if customization is 568 The Yocto Project uses reasonable defaults in most cases, but if customization is
509 necessary you need to create a <filename>machconfig</filename> file 569 necessary you need to create a <filename>machconfig</filename> file
510 under <filename>meta/packages/formfactor/files/MACHINENAME/</filename>, 570 in the Yocto Project file's <filename>meta/recipes-bsp/formfactor/files</filename>
511 where <filename>MACHINENAME</filename> is the name for which this information 571 directory.
512 applies. 572 This directory contains directories for specific machines such as
513 For information about the settings available and the defaults, see 573 <filename>qemuarm</filename> and <filename>qemux86</filename>.
514 <filename>meta/recipes-bsp/formfactor/files/config</filename>. 574 For information about the settings available and the defaults, see the
575 <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
576 same area.
515 Following is an example for qemuarm: 577 Following is an example for qemuarm:
578 <literallayout class='monospaced'>
579 HAVE_TOUCHSCREEN=1
580 HAVE_KEYBOARD=1
581
582 DISPLAY_CAN_ROTATE=0
583 DISPLAY_ORIENTATION=0
584 #DISPLAY_WIDTH_PIXELS=640
585 #DISPLAY_HEIGHT_PIXELS=480
586 #DISPLAY_BPP=16
587 DISPLAY_DPI=150
588 DISPLAY_SUBPIXEL_ORDER=vrgb
589 </literallayout>
516 </para> 590 </para>
517 <programlisting>
518HAVE_TOUCHSCREEN=1
519HAVE_KEYBOARD=1
520
521DISPLAY_CAN_ROTATE=0
522DISPLAY_ORIENTATION=0
523#DISPLAY_WIDTH_PIXELS=640
524#DISPLAY_HEIGHT_PIXELS=480
525#DISPLAY_BPP=16
526DISPLAY_DPI=150
527DISPLAY_SUBPIXEL_ORDER=vrgb
528 </programlisting>
529 </section> 591 </section>
530 </section> 592 </section>
531 593
532 <section id="usingpoky-changes"> 594 <section id="usingpoky-changes">
533 <title>Making and Maintaining Changes</title> 595 <title>Making and Maintaining Changes</title>
534 <para> 596 <para>
535 Because Poky is extremely configurable and flexible, we recognize that people will want 597 Because the Yocto Project is extremely configurable and flexible,
536 to extend, configure or optimize Poky for their specific uses. 598 we recognize that developers will want
537 To best keep pace with future Poky changes we recommend you make controlled changes to Poky. 599 to extend, configure or optimize it for their specific uses.
600 To best keep pace with future Yocto Project changes,
601 we recommend you make controlled changes to the Yocto Project.
538 </para> 602 </para>
603
539 <para> 604 <para>
540 Poky supports the idea of <link linkend='usingpoky-changes-layers'>"layers"</link>. 605 The Yocto Project supports a <link linkend='usingpoky-changes-layers'>"layers"</link> concept.
541 If you use layers properly you can ease future upgrades and allow segregation 606 If you use layers properly, you can ease future upgrades and allow segregation
542 between the Poky core and a given developer's changes. 607 between the Yocto Project core and a given developer's changes.
543 The following section provides more advice on managing changes to Poky. 608 The following section provides more advice on managing changes to the Yocto Project.
544 </para> 609 </para>
545 610
546 <section id="usingpoky-changes-layers"> 611 <section id="usingpoky-changes-layers">
547 <title>BitBake Layers</title> 612 <title>BitBake Layers</title>
548 <para> 613 <para>
549 Often, people want to extend Poky either by adding packages 614 Often, developers want to extend the Yocto Project either by adding packages
550 or by overriding files contained within Poky to add their own 615 or by overriding files contained within the Yocto Project to add their own
551 functionality. 616 functionality.
552 BitBake has a powerful mechanism called 617 BitBake has a powerful mechanism called
553 "layers", which provides a way to handle this extension in a fully 618 "layers", which provides a way to handle this extension in a fully
554 supported and non-invasive fashion. 619 supported and non-invasive fashion.
555 </para> 620 </para>
621
556 <para> 622 <para>
557 The Poky tree includes several additional layers such as meta-emenlow and meta-extras 623 The Yocto Project files include several additional layers such as
624 <filename>meta-rt</filename> and <filename>meta-yocto</filename>
558 that demonstrate this functionality. 625 that demonstrate this functionality.
559 The meta-emenlow layer is an example layer that, by default, is enabled. 626 The <filename>meta-rt</filename> layer is not enabled by default.
560 However, the meta-extras repository is not enabled by default. 627 However, the <filename>meta-yocto</filename> layer is.
561 It is easy though to enable any layer. 628 </para>
562 You simply add the layer's path to the 629
563 <glossterm><link linkend='var-BBLAYERS'>BBLAYERS</link></glossterm> variable in your 630 <para>
564 <filename>bblayers.conf</filename> file. 631 To enable a layer, you simply add the layer's path to the
565 The following example shows how to enable meta-extras in the Poky build: 632 <filename><link linkend='var-BBLAYERS'>BBLAYERS</link></filename> variable in your
566 </para> 633 <filename>bblayers.conf</filename> file, which is found in the Yocto Project file's
567 <para> 634 build directory.
568 <programlisting> 635 The following example shows how to enable the <filename>meta-rt</filename>:
569LCONF_VERSION = "1" 636 <literallayout class='monospaced'>
570 637 LCONF_VERSION = "1"
571BBFILES ?= "" 638
572BBLAYERS = " \ 639 BBFILES ?= ""
573 /path/to/poky/meta \ 640 BBLAYERS = " \
574 /path/to/poky/meta-emenlow \ 641 /path/to/poky/meta \
575 /path/to/poky/meta-extras \ 642 /path/to/poky/meta-yocto \
576 " 643 /path/to/poky/meta-rt \
577 </programlisting> 644 "
645 </literallayout>
578 </para> 646 </para>
579 647
580 <para> 648 <para>
581 BitBake parses each <filename>conf/layer.conf</filename> file for each layer in BBLAYERS 649 BitBake parses each <filename>conf/layer.conf</filename> file for each layer in
582 and adds the recipes, classes and configuration contained within the layer to Poky. 650 <filename>BBLAYERS</filename>
583 To create your own layer, independent of the main Poky repository, 651 and adds the recipes, classes and configurations contained within the layer to
652 the Yocto Project.
653 To create your own layer, independent of the Yocto Project files,
584 simply create a directory with a <filename>conf/layer.conf</filename> file and 654 simply create a directory with a <filename>conf/layer.conf</filename> file and
585 add the directory to your <filename>bblayers.conf</filename> file. 655 add the directory to your <filename>bblayers.conf</filename> file.
586 </para> 656 </para>
657
587 <para> 658 <para>
588 The <filename>meta-emenlow/conf/layer.conf</filename> file demonstrates the required syntax: 659 The <filename>meta-yocto/conf/layer.conf</filename> file demonstrates the
589 <programlisting> 660 required syntax:
590# We have a conf and classes directory, add to BBPATH 661 <literallayout class='monospaced'>
591BBPATH := "${BBPATH}:${LAYERDIR}" 662 # We have a conf and classes directory, add to BBPATH
592 663 BBPATH := "${BBPATH}:${LAYERDIR}"
593# We have a recipes directory containing both .bb and .bbappend files, add to BBFILES 664
594BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ 665 # We have a packages directory, add to BBFILES
595 ${LAYERDIR}/recipes/*/*.bbappend" 666 BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
596 667 ${LAYERDIR}/recipes-*/*/*.bbappend"
597BBFILE_COLLECTIONS += "emenlow" 668
598BBFILE_PATTERN_emenlow := "^${LAYERDIR}/" 669 BBFILE_COLLECTIONS += "yocto"
599BBFILE_PRIORITY_emenlow = "6" 670 BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
600 </programlisting> 671 BBFILE_PRIORITY_yocto = "5"
672 </literallayout>
601 </para> 673 </para>
674
602 <para> 675 <para>
603 In the previous example, the recipes for the layers are added to 676 In the previous example, the recipes for the layers are added to
604 <glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm>. 677 <filename><link linkend='var-BBFILES'>BBFILES</link></filename>.
605 The <glossterm><link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link></glossterm> 678 The <filename><link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link></filename>
606 variable is then appended with the layer name. 679 variable is then appended with the layer name.
607 The <glossterm><link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN</link></glossterm> variable 680 The <filename><link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN</link></filename> variable
608 immediately expands with a regular expression used to match files from BBFILES into 681 immediately expands with a regular expression used to match files from
682 <filename>BBFILES</filename> into
609 a particular layer, in this case by using the base pathname. 683 a particular layer, in this case by using the base pathname.
610 The <glossterm><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></glossterm> variable 684 The <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename> variable
611 then assigns different priorities to the files in different layers. 685 then assigns different priorities to the files in different layers.
612 Applying priorities is useful in situations where the same package might appear in multiple 686 Applying priorities is useful in situations where the same package might appear in multiple
613 layers and allows you to choose what layer should take precedence. 687 layers and allows you to choose what layer should take precedence.
614 </para> 688 </para>
689
615 <para> 690 <para>
616 Note the use of the <glossterm><link linkend='var-LAYERDIR'>LAYERDIR</link></glossterm> 691 Note the use of the <filename><link linkend='var-LAYERDIR'>LAYERDIR</link></filename>
617 variable with the immediate expansion operator. 692 variable with the immediate expansion operator.
618 The LAYERDIR variable expands to the directory of the current layer and 693 The <filename>LAYERDIR</filename> variable expands to the directory of the current layer and
619 requires the immediate expansion operator so that BitBake does not wait to expand the variable 694 requires the immediate expansion operator so that BitBake does not wait to expand the variable
620 when it's parsing a different directory. 695 when it's parsing a different directory.
621 </para> 696 </para>
697
622 <para> 698 <para>
623 BitBake can locate where other bbclass and configuration files are applied through 699 BitBake can locate where other <filename>.bbclass</filename> and configuration files
624 the <glossterm><link linkend='var-BBPATH'>BBPATH</link></glossterm> 700 are applied through the <filename>BBPATH</filename> environment variable.
625 environment variable. 701 For these cases, BitBake uses the first file with the matching name found in
626 For these cases, BitBake uses the first file with the matching name found in BBPATH. 702 <filename>BBPATH</filename>.
627 This is similar to the way the PATH variable is used for binaries. 703 This is similar to the way the <filename>PATH</filename> variable is used for binaries.
628 We recommend, therefore, that you use unique bbclass and configuration file names in your 704 We recommend, therefore, that you use unique <filename>.bbclass</filename>
629 custom layer. 705 and configuration file names in your custom layer.
630 </para> 706 </para>
707
631 <para> 708 <para>
632 We also recommend the following: 709 We also recommend the following:
633 <itemizedlist> 710 <itemizedlist>
634 <listitem><para>Store custom layers in a git repository that uses the 711 <listitem><para>Store custom layers in a Git repository that uses the
635 meta-prvt-XXXX format.</para></listitem> 712 <filename>meta-prvt-XXXX</filename> format.</para></listitem>
636 <listitem><para>Clone the repository alongside other meta directories in the Poky 713 <listitem><para>Clone the repository alongside other <filename>meta</filename>
637 tree.</para></listitem> 714 directories in the Yocto Project source files area.</para></listitem>
638 </itemizedlist> 715 </itemizedlist>
639 Following these recommendations keeps your Poky tree and its configuration entirely 716 Following these recommendations keeps your Yocto Project files area and
640 inside COREBASE. 717 its configuration entirely inside the Yocto Project's core base.
641 </para> 718 </para>
642 </section> 719 </section>
643 720
644 <section id="usingpoky-changes-commits"> 721 <section id="usingpoky-changes-commits">
645 <title>Committing Changes</title> 722 <title>Committing Changes</title>
723
646 <para> 724 <para>
647 Modifications to Poky are often managed under some kind of source 725 Modifications to the Yocto Project are often managed under some kind of source
648 revision control system. 726 revision control system.
649 Because some simple practices can significantly improve usability, policy for committing changes 727 Because some simple practices can significantly improve usability, policy for committing changes
650 is important. 728 is important.
651 It helps to use a consistent documentation style when committing changes. 729 It helps to use a consistent documentation style when committing changes.
652 We have found the following style works well. 730 The Yocto Project development team has found the following practices work well:
653 </para>
654 <para>
655 Following are suggestions for committing changes to the Poky core:
656 </para>
657
658 <para>
659 <itemizedlist> 731 <itemizedlist>
660 <listitem><para>The first line of the commit summarizes the change and begins with the 732 <listitem><para>The first line of the commit summarizes the change and begins with the
661 name of the affected package or packages. 733 name of the affected package or packages.
662 However, not all changes apply to specific packages. 734 However, not all changes apply to specific packages.
663 Consequently, the prefix could also be a machine name or class name for 735 Consequently, the prefix could also be a machine name or class name.</para></listitem>
664 example.</para></listitem>
665 <listitem><para>The second part of the commit (if needed) is a longer more detailed 736 <listitem><para>The second part of the commit (if needed) is a longer more detailed
666 description of the changes. Placing a blank line between the first and second parts 737 description of the changes.
667 helps with readability.</para></listitem> 738 Placing a blank line between the first and second parts helps with
739 readability.</para></listitem>
668 </itemizedlist> 740 </itemizedlist>
669 </para> 741 </para>
742
670 <para> 743 <para>
671 Following is an example commit: 744 Following is an example commit:
672 </para> 745 <literallayout class='monospaced'>
673 <literallayout class='monospaced'>
674 bitbake/data.py: Add emit_func() and generate_dependencies() functions 746 bitbake/data.py: Add emit_func() and generate_dependencies() functions
675 747
676 These functions allow generation of dependency data between functions and 748 These functions allow generation of dependency data between functions and
@@ -678,88 +750,107 @@ BBFILE_PRIORITY_emenlow = "6"
678 use of the dependency information in other parts of BitBake. 750 use of the dependency information in other parts of BitBake.
679 751
680 Signed-off-by: Richard Purdie richard.purdie@linuxfoundation.org 752 Signed-off-by: Richard Purdie richard.purdie@linuxfoundation.org
681 </literallayout> 753 </literallayout>
754 </para>
682 755
683 <para> 756 <para>
684 All commits should be self-contained such that they leave the 757 All commits should be self-contained such that they leave the
685 metadata in a consistent state that builds both before and after the 758 metadata in a consistent state that builds both before and after the
686 commit is made. 759 commit is made.
687 Besides being a good policy to follow, this helps ensure the autobuilder test results 760 Besides being a good practice to follow, it helps ensure autobuilder test results
688 are valid. 761 are valid.
689 </para> 762 </para>
690 </section> 763 </section>
691 764
692 <section id="usingpoky-changes-prbump"> 765 <section id="usingpoky-changes-prbump">
693 <title>Package Revision Incrementing</title> 766 <title>Package Revision Incrementing</title>
767
694 <para> 768 <para>
695 If a committed change results in changing the package output 769 If a committed change results in changing the package output,
696 then the value of the <glossterm><link linkend='var-PR'>PR</link> 770 then the value of the
697 </glossterm> variable needs to be increased (or 'bumped') as part of that commit. 771 <filename><link linkend='var-PR'>PR</link></filename> variable needs to be increased
698 This means that for new recipes you must be sure to add the PR variable and set its initial value 772 (or "bumped") as part of that commit.
699 equal to "r0". 773 This means that for new recipes you must be sure to add the <filename>PR</filename>
700 Failing to define PR makes it easy to miss when you bump a package. 774 variable and set its initial value equal to "r0".
701 Note that you can only use integer values following the "r" in the PR variable. 775 Failing to define <filename>PR</filename> makes it easy to miss when you bump a package.
776 Note that you can only use integer values following the "r" in the
777 <filename>PR</filename> variable.
702 </para> 778 </para>
779
703 <para> 780 <para>
704 If you are sharing a common .inc file with multiple recipes, you can also use the 781 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
705 <glossterm><link linkend='var-INC_PR'>INC_PR</link></glossterm> variable to ensure that 782 you can also use the
706 the recipes sharing the .inc file are rebuilt when the .inc file itself is changed. The 783 <filename><link linkend='var-INC_PR'>INC_PR</link></filename> variable to ensure that
707 .inc file must set INC_PR (initially to "r0"), and all recipes referring to it should set PR to 784 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
708 "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. If the 785 <filename>.inc</filename> file itself is changed.
709 .inc file is changed then its INC_PR should be incremented. 786 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
787 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
788 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
789 If the <filename>.inc</filename> file is changed then its
790 <filename>INC_PR</filename> should be incremented.
710 </para> 791 </para>
792
711 <para> 793 <para>
712 When upgrading the version of a package, assuming the <glossterm><link 794 When upgrading the version of a package, assuming the
713 linkend='var-PV'>PV</link></glossterm> changes, the PR variable should be reset to "r0" 795 <filename><link linkend='var-PV'>PV</link></filename> changes,
714 (or "$(INC_PR).0" if you are using INC_PR). 796 the <filename>PR</filename> variable should be reset to "r0"
797 (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
715 </para> 798 </para>
799
716 <para> 800 <para>
717 Usually, version increases occur only to packages. 801 Usually, version increases occur only to packages.
718 However, if for some reason PV changes but does not increase, you can increase the 802 However, if for some reason <filename>PV</filename> changes but does not
719 <glossterm><link linkend='var-PE'>PE</link></glossterm> variable (Package Epoch). 803 increase, you can increase the
720 The PE variable defaults to "0". 804 <filename><link linkend='var-PE'>PE</link></filename> variable (Package Epoch).
805 The <filename>PE</filename> variable defaults to "0".
721 </para> 806 </para>
807
722 <para> 808 <para>
723 Version numbering strives to follow the 809 Version numbering strives to follow the
724 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'> 810 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
725 Debian Version Field Policy Guidelines</ulink>. 811 Debian Version Field Policy Guidelines</ulink>.
726 These guidelines define how versions are compared and what "increasing" a version means. 812 These guidelines define how versions are compared and what "increasing" a version means.
727 </para> 813 </para>
814
728 <para> 815 <para>
729 There are two reasons for following these guidelines. 816 There are two reasons for following the previously mentioned guidelines.
730 First, to ensure that when a developer updates and rebuilds, they get all the changes to 817 First, to ensure that when a developer updates and rebuilds, they get all the changes to
731 the repository and don't have to remember to rebuild any sections. 818 the repository and do not have to remember to rebuild any sections.
732 Second, to ensure that target users are able to upgrade their 819 Second, to ensure that target users are able to upgrade their
733 devices using package manager commands such as <filename>opkg upgrade</filename> 820 devices using package manager commands such as <filename>opkg upgrade</filename>
734 (or similar commands for dpkg/apt or rpm-based systems). 821 (or similar commands for dpkg/apt or rpm-based systems).
735 </para> 822 </para>
823
736 <para> 824 <para>
737 The goal is to ensure Poky has upgradeable packages in all cases. 825 The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
738 </para> 826 </para>
739 </section> 827 </section>
740 828
741 <section id="usingpoky-changes-collaborate"> 829 <section id="usingpoky-changes-collaborate">
742 <title>Using Poky in a Team Environment</title> 830 <title>Using The Yocto Project in a Team Environment</title>
831
743 <para> 832 <para>
744 It might not be immediately clear how you can use Poky in a team environment, 833 It might not be immediately clear how you can use the Yocto Project in a team environment,
745 or scale it for a large team of developers. 834 or scale it for a large team of developers.
746 The specifics of any situation determine the best solution. 835 The specifics of any situation determine the best solution.
747 Granted that Poky offers immense flexibility regarding this, practices do exist 836 Granted that the Yocto Project offers immense flexibility regarding this, practices do exist
748 that experience has shown work well. 837 that experience has shown work well.
749 </para> 838 </para>
839
750 <para> 840 <para>
751 The core component of any development effort with Poky is often an 841 The core component of any development effort with the Yocto Project is often an
752 automated build testing framework and an image generation process. 842 automated build and testing framework along with an image generation process.
753 You can use these core components to check that the metadata can be built, 843 You can use these core components to check that the metadata can be built,
754 highlight when commits break the build, and provide up-to-date images that 844 highlight when commits break the build, and provide up-to-date images that
755 allow people to test the end result and use it as a base platform for further 845 allow developers to test the end result and use it as a base platform for further
756 development. 846 development.
757 Experience shows that buildbot is a good fit for this role. 847 Experience shows that buildbot is a good fit for this role.
758 What works well is to configure buildbot to make two types of builds: 848 What works well is to configure buildbot to make two types of builds:
759 incremental and full (from scratch). 849 incremental and full (from scratch).
760 See <ulink url='http://autobuilder.yoctoproject.org:8010'>poky autobuilder</ulink> 850 See <ulink url='http://autobuilder.yoctoproject.org:8010'>the buildbot for the
761 for an example implementation that uses buildbot. 851 Yocto Project</ulink> for an example implementation that uses buildbot.
762 </para> 852 </para>
853
763 <para> 854 <para>
764 You can tie incremental builds to a commit hook that triggers the build 855 You can tie incremental builds to a commit hook that triggers the build
765 each time a commit is made to the metadata. 856 each time a commit is made to the metadata.
@@ -768,28 +859,32 @@ BBFILE_PRIORITY_emenlow = "6"
768 Associating a build to a commit can catch a lot of simple errors. 859 Associating a build to a commit can catch a lot of simple errors.
769 Furthermore, the tests are fast so developers can get quick feedback on changes. 860 Furthermore, the tests are fast so developers can get quick feedback on changes.
770 </para> 861 </para>
862
771 <para> 863 <para>
772 Full builds build and test everything from the ground up. 864 Full builds build and test everything from the ground up.
773 They usually happen at predetermined times like during the night when the machine 865 These types of builds usually happen at predetermined times like during the
774 load is low. 866 night when the machine load is low.
775 </para> 867 </para>
868
776 <para> 869 <para>
777 Most teams have many pieces of software undergoing active development at any given time. 870 Most teams have many pieces of software undergoing active development at any given time.
778 You can derive large benefits by putting these pieces under the control of a source 871 You can derive large benefits by putting these pieces under the control of a source
779 control system that is compatible with Poky (i.e. git or svn). 872 control system that is compatible with the Yocto Project (i.e. Git or Subversion (SVN).
780 You can then set the autobuilder to pull the latest revisions of the packages 873 You can then set the autobuilder to pull the latest revisions of the packages
781 and test the latest commits by the builds. 874 and test the latest commits by the builds.
782 This practice quickly highlights issues. 875 This practice quickly highlights issues.
783 Poky easily supports testing configurations that use both a stable known good revision 876 The Yocto Project easily supports testing configurations that use both a
784 and a floating revision. 877 stable known good revision and a floating revision.
785 Poky can also take just the changes from specific source control branches. 878 The Yocto Project can also take just the changes from specific source control branches.
786 This capability allows you to track and test specific changes. 879 This capability allows you to track and test specific changes.
787 </para> 880 </para>
881
788 <para> 882 <para>
789 Perhaps the hardest part of setting this up is defining the software project or 883 Perhaps the hardest part of setting this up is defining the software project or
790 Poky metadata policies that surround the different source control systems. 884 the Yocto Project metadata policies that surround the different source control systems.
791 Of course circumstances will be different in each case. 885 Of course circumstances will be different in each case.
792 However, this situation reveals one of Poky's advantages - the system itself does not 886 However, this situation reveals one of the Yocto Project's advantages -
887 the system itself does not
793 force any particular policy on users, unlike a lot of build systems. 888 force any particular policy on users, unlike a lot of build systems.
794 The system allows the best policies to be chosen for the given circumstances. 889 The system allows the best policies to be chosen for the given circumstances.
795 </para> 890 </para>
@@ -797,165 +892,186 @@ BBFILE_PRIORITY_emenlow = "6"
797 892
798 <section id="usingpoky-changes-updatingimages"> 893 <section id="usingpoky-changes-updatingimages">
799 <title>Updating Existing Images</title> 894 <title>Updating Existing Images</title>
895
800 <para> 896 <para>
801 Often, rather than re-flashing a new image you might wish to install updated 897 Often, rather than re-flashing a new image, you might wish to install updated
802 packages into an existing running system. 898 packages into an existing running system.
803 You can do this by first sharing the 899 You can do this by first sharing the <filename>tmp/deploy/ipk/</filename> directory
804 <filename class="directory">tmp/deploy/ipk/</filename> directory
805 through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename> 900 through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename>
806 to point at the shared server. 901 to point at the shared server.
807 Following is an example: 902 Following is an example:
903 <literallayout class='monospaced'>
904 $ src/gz all http://www.mysite.com/somedir/deploy/ipk/all
905 $ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
906 $ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
907 </literallayout>
808 </para> 908 </para>
809 <literallayout class='monospaced'>
810 src/gz all http://www.mysite.com/somedir/deploy/ipk/all
811 src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
812 src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
813 </literallayout>
814 </section> 909 </section>
815 </section> 910 </section>
816 911
817 <section id="usingpoky-modifing-packages"> 912 <section id="usingpoky-modifing-packages">
818 <title>Modifying Package Source Code</title> 913 <title>Modifying Package Source Code</title>
819 <para> 914 <para>
820 Although Poky is usually used to build software, you can use it to modify software. 915 Although the Yocto Project is usually used to build software, you can use it to modify software.
821 </para> 916 </para>
917
822 <para> 918 <para>
823 During a build, source is available in the 919 During a build, source is available in the
824 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory. 920 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename> directory.
825 The actual location depends on the type of package and the architecture of the target device. 921 The actual location depends on the type of package and the architecture of the target device.
826 For a standard recipe not related to 922 For a standard recipe not related to
827 <glossterm><link linkend='var-MACHINE'>MACHINE</link></glossterm> the location is 923 <filename><link linkend='var-MACHINE'>MACHINE</link></filename>, the location is
828 <filename>tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</filename>. 924 <filename>tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</filename>.
829 For target device-dependent packages you should use the <filename>MACHINE</filename> 925 For target device-dependent packages, you should use the <filename>MACHINE</filename>
830 variable instead of 926 variable instead of
831 <glossterm><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></glossterm> 927 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>
832 in the directory name. 928 in the directory name.
833 </para> 929 </para>
930
834 <tip> 931 <tip>
835 <para> 932 Be sure the package recipe sets the
836 Be sure the package recipe sets the 933 <filename><link linkend='var-S'>S</link></filename> variable to something
837 <glossterm><link linkend='var-S'>S</link></glossterm> variable to something 934 other than the standard <filename>WORKDIR/PN-PV/</filename> value.
838 other than the standard <filename>WORKDIR/PN-PV/</filename> value.
839 </para>
840 </tip> 935 </tip>
936
841 <para> 937 <para>
842 After building a package, you can modify the package source code without problems. 938 After building a package, you can modify the package source code without problems.
843 The easiest way to test your changes is by calling the "compile" task as shown in the 939 The easiest way to test your changes is by calling the
844 following example: 940 <filename>compile</filename> task as shown in the following example:
845 </para> 941 <literallayout class='monospaced'>
846
847 <literallayout class='monospaced'>
848 $ bitbake -c compile -f NAME_OF_PACKAGE 942 $ bitbake -c compile -f NAME_OF_PACKAGE
849 </literallayout> 943 </literallayout>
944 </para>
850 945
851 <para> 946 <para>
852 The "-f" or "--force" option forces re-execution of the specified task. 947 The <filename>-f</filename> or <filename>--force</filename>
948 option forces re-execution of the specified task.
853 You can call other tasks this way as well. 949 You can call other tasks this way as well.
854 But note that all the modifications in 950 But note that all the modifications in
855 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> 951 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>
856 are gone once you execute "-c clean" for a package. 952 are gone once you execute <filename>-c clean</filename> for a package.
857 </para> 953 </para>
954 </section>
858 955
859 <section id="usingpoky-modifying-packages-quilt"> 956 <section id="usingpoky-modifying-packages-quilt">
860 <title>Modifying Package Source Code with quilt</title> 957 <title>Modifying Package Source Code with Quilt</title>
861 <para> 958
862 By default Poky uses <ulink url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink> 959 <para>
863 to manage patches in the "do_patch" task. 960 By default Poky uses <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
864 This is a powerful tool that you can use to track all modifications to package sources. 961 to manage patches in the <filename>do_patch</filename> task.
865 </para> 962 This is a powerful tool that you can use to track all modifications to package sources.
866 <para> 963 </para>
867 Before modifying source code, it is important to notify quilt so it can track the changes
868 into the new patch file:
869 964
870 <literallayout class='monospaced'> 965 <para>
871 quilt new NAME-OF-PATCH.patch 966 Before modifying source code, it is important to notify Quilt so it can track the changes
872 </literallayout> 967 into the new patch file:
968 <literallayout class='monospaced'>
969 $ quilt new NAME-OF-PATCH.patch
970 </literallayout>
971 </para>
873 972
874 After notifying quilt, add all modified files into that patch: 973 <para>
875 <literallayout class='monospaced'> 974 After notifying Quilt, add all modified files into that patch:
876 quilt add file1 file2 file3 975 <literallayout class='monospaced'>
877 </literallayout> 976 $ quilt add file1 file2 file3
977 </literallayout>
978 </para>
878 979
879 You can now start editing. 980 <para>
880 Once you are done editing, you need to use quilt to generate the final patch that 981 You can now start editing.
881 will contain all your modifications. 982 Once you are done editing, you need to use Quilt to generate the final patch that
882 <literallayout class='monospaced'> 983 will contain all your modifications.
883 quilt refresh 984 <literallayout class='monospaced'>
884 </literallayout> 985 $ quilt refresh
986 </literallayout>
987 </para>
885 988
886 You can find the resulting patch file in the 989 <para>
887 <filename>patches/</filename> subdirectory of the source 990 You can find the resulting patch file in the
888 (<glossterm><link linkend='var-S'>S</link></glossterm>) directory. 991 <filename>patches/</filename> subdirectory of the source
889 For future builds you should copy the patch into Poky metadata and add it into the 992 (<filename><link linkend='var-S'>S</link></filename>) directory.
890 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> of a recipe. 993 For future builds, you should copy the patch into the Yocto Project metadata and add it into the
891 Here is an example: 994 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> of a recipe.
892 <programlisting> 995 Here is an example:
893SRC_URI += "file://NAME-OF-PATCH.patch" 996 <literallayout class='monospaced'>
894 </programlisting> 997 SRC_URI += "file://NAME-OF-PATCH.patch"
895 Finally, don't forget to 'bump' the 998 </literallayout>
896 <glossterm><link linkend='var-PR'>PR</link></glossterm> value in the same recipe since 999 </para>
897 the resulting packages have changed.
898 </para>
899 </section>
900 1000
1001 <para>
1002 Finally, don't forget to 'bump' the
1003 <glossterm><link linkend='var-PR'>PR</link></glossterm> value in the same recipe since
1004 the resulting packages have changed.
1005 </para>
901 </section> 1006 </section>
902 1007
903 <section id="usingpoky-configuring-LIC_FILES_CHKSUM"> 1008 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
904 <title>Track License Change</title> 1009 <title>Track License Change</title>
1010
905 <para> 1011 <para>
906 The license of an upstream project might change in the future. 1012 The license of an upstream project might change in the future.
907 Poky uses the <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable 1013 The Yocto Project uses the
908 to track license changes. 1014 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename> variable
1015 to track license changes.
909 </para> 1016 </para>
910 1017
911 <section id="usingpoky-specifying-LIC_FILES_CHKSUM"> 1018 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
912 <title>Specifying the LIC_FILES_CHKSUM Variable</title> 1019 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
1020
913 <para> 1021 <para>
914 The <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> 1022 The <filename>LIC_FILES_CHKSUM</filename>
915 variable contains checksums of the license text in the recipe source code. 1023 variable contains checksums of the license text in the recipe source code.
916 Poky uses this to track changes in the license text of the source code files. 1024 The Yocto Project uses checksums to track changes in the license text of the
917 Following is an example of LIC_FILES_CHKSUM: 1025 source code files.
1026 Following is an example of <filename>LIC_FILES_CHKSUM</filename>:
1027 <literallayout class='monospaced'>
1028 LIC_FILES_CHKSUM = "file://COPYING; md5=xxxx \
1029 file://licfile1.txt; beginline=5; endline=29;md5=yyyy \
1030 file://licfile2.txt; endline=50;md5=zzzz \
1031 ..."
1032 </literallayout>
918 </para> 1033 </para>
919 <programlisting> 1034
920LIC_FILES_CHKSUM = "file://COPYING; md5=xxxx \
921 file://licfile1.txt; beginline=5; endline=29;md5=yyyy \
922 file://licfile2.txt; endline=50;md5=zzzz \
923 ..."
924 </programlisting>
925 <para> 1035 <para>
926 Poky uses the <glossterm><link linkend='var-S'>S</link></glossterm> variable as the 1036 The Yocto Project uses the
927 default directory used when searching files listed in LIC_FILES_CHKSUM. 1037 <filename><link linkend='var-S'>S</link></filename> variable as the
1038 default directory used when searching files listed in
1039 <filename>LIC_FILES_CHKSUM</filename>.
928 The previous example employs the default directory. 1040 The previous example employs the default directory.
929 </para> 1041 </para>
1042
930 <para> 1043 <para>
931 You can also use relative paths as shown in the following example: 1044 You can also use relative paths as shown in the following example:
1045 <literallayout class='monospaced'>
1046 LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
1047 md5=bb14ed3c4cda583abc85401304b5cd4e"
1048 LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
1049 </literallayout>
932 </para> 1050 </para>
933 <programlisting> 1051
934LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
935 md5=bb14ed3c4cda583abc85401304b5cd4e"
936LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
937 </programlisting>
938 <para> 1052 <para>
939 In this example the first line locates a file in 1053 In this example, the first line locates a file in
940 <glossterm><link linkend='var-S'>S</link></glossterm><filename>/src/ls.c</filename>. 1054 <filename><link linkend='var-S'>S</link>/src/ls.c</filename>.
941 The second line refers to a file in 1055 The second line refers to a file in
942 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>, which is the parent 1056 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent
943 of <glossterm><link linkend='var-S'>S</link></glossterm>. 1057 of <filename>S</filename>.
944 </para> 1058 </para>
945 </section> 1059 </section>
946 1060
947 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"> 1061 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
948 <title>Explanation of Syntax</title> 1062 <title>Explanation of Syntax</title>
949 <para> 1063 <para>
950 As mentioned in the previous section the LIC_FILES_CHKSUM variable lists all the 1064 As mentioned in the previous section, the
1065 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
951 important files that contain the license text for the source code. 1066 important files that contain the license text for the source code.
952 Using this variable you can specify the line on which the license text starts and ends 1067 Using this variable, you can specify the line on which the license text starts and ends
953 by supplying "beginline" and "endline" parameters. 1068 by supplying "beginline" and "endline" parameters.
954 If you do not use the "beginline" parameter then it is assumed that the text begins on the 1069 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
955 first line of the file. 1070 first line of the file.
956 Similarly, if you do not use the "endline" parameter it is assumed that the license text 1071 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
957 ends as the last line of the file. 1072 ends as the last line of the file.
958 </para> 1073 </para>
1074
959 <para> 1075 <para>
960 The "md5" parameter stores the md5 checksum of the license text. 1076 The "md5" parameter stores the md5 checksum of the license text.
961 If the license text changes in any way as compared to this parameter 1077 If the license text changes in any way as compared to this parameter
@@ -963,20 +1079,25 @@ LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
963 This mismatch triggers a build failure and notifies the developer. 1079 This mismatch triggers a build failure and notifies the developer.
964 Notification allows the developer to review and address the license text changes. 1080 Notification allows the developer to review and address the license text changes.
965 Also note that if a mis-match occurs during the build, the correct md5 1081 Also note that if a mis-match occurs during the build, the correct md5
966 checksum is placed in the build log and can be easily copied to a .bb file. 1082 checksum is placed in the build log and can be easily copied to a
1083 <filename>.bb</filename> file.
967 </para> 1084 </para>
1085
968 <para> 1086 <para>
969 There is no limit to how many files you can specify using the LIC_FILES_CHKSUM variable. 1087 There is no limit to how many files you can specify using the
1088 <filename>LIC_FILES_CHKSUM</filename> variable.
970 Generally, however, every project requires a few specifications for license tracking. 1089 Generally, however, every project requires a few specifications for license tracking.
971 Many projects have a "COPYING" file that stores the license information for all the source 1090 Many projects have a "COPYING" file that stores the license information for all the source
972 code files. 1091 code files.
973 This practice allow you to just track the "COPYING" file as long as it is kept up to date. 1092 This practice allow you to just track the "COPYING" file as long as it is kept up to date.
974 </para> 1093 </para>
1094
975 <tip> 1095 <tip>
976 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match 1096 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
977 error and displays the correct "md5" parameter value during the build. The correct parameter 1097 error and displays the correct "md5" parameter value during the build.
978 is also captured in the build log. 1098 The correct parameter is also captured in the build log.
979 </tip> 1099 </tip>
1100
980 <tip> 1101 <tip>
981 If the whole file contains only license text, you do not need to use the "beginline" and 1102 If the whole file contains only license text, you do not need to use the "beginline" and
982 "endline" parameters. 1103 "endline" parameters.
@@ -985,43 +1106,44 @@ LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
985 </section> 1106 </section>
986 1107
987 <section id="usingpoky-configuring-DISTRO_PN_ALIAS"> 1108 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
988 <title>Handling Package Name Alias</title> 1109 <title>Handling a Package Name Alias</title>
989 <para> 1110 <para>
990 Sometimes a package name you are using might exist under an alias or as a similarly named 1111 Sometimes a package name you are using might exist under an alias or as a similarly named
991 package in a different distribution. 1112 package in a different distribution.
992 Poky implements a "distro_check" task that automatically connects to major distributions 1113 The Yocto Project implements a <filename>distro_check</filename>
1114 task that automatically connects to major distributions
993 and checks for these situations. 1115 and checks for these situations.
994 If the package exists under a different name in a different distribution you get a 1116 If the package exists under a different name in a different distribution, you get a
995 distro_check mismatch. 1117 <filename>distro_check</filename> mismatch.
996 You can resolve this problem by defining a per-distro recipe name alias using the 1118 You can resolve this problem by defining a per-distro recipe name alias using the
997 <glossterm><link linkend='var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</link></glossterm> variable. 1119 <filename><link linkend='var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</link></filename> variable.
998 </para> 1120 </para>
999 1121
1000 <section id="usingpoky-specifying-DISTRO_PN_ALIAS"> 1122 <para>
1001 <title>Specifying the DISTRO_PN_ALIAS Variable</title> 1123 Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename>
1002 <para> 1124 variable:
1003 Following is an example that shows how you specify the DISTRO_PN_ALIAS variable: 1125 <literallayout class='monospaced'>
1004 <programlisting> 1126 DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
1005DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ 1127 distro2=package_name_alias2 \
1006 distro2=package_name_alias2 \ 1128 distro3=package_name_alias3 \
1007 distro3=package_name_alias3 \ 1129 ..."
1008 ..." 1130 </literallayout>
1009 </programlisting> 1131 </para>
1010 </para> 1132
1011 <para> 1133 <para>
1012 If you have more than one distribution alias, separate them with a space. 1134 If you have more than one distribution alias, separate them with a space.
1013 Note that Poky currently automatically checks the Fedora, OpenSuSE, Debian, Ubuntu, 1135 Note that the Yocto Project currently automatically checks the
1014 and Mandriva distributions for source package recipes without having to specify them 1136 Fedora, OpenSuSE, Debian, Ubuntu,
1015 using the DISTRO_PN_ALIAS variable. 1137 and Mandriva distributions for source package recipes without having to specify them
1016 For example, the following command generates a report that lists the Linux distributions 1138 using the <filename>DISTRO_PN_ALIAS</filename> variable.
1017 that include the sources for each of the Poky recipes. 1139 For example, the following command generates a report that lists the Linux distributions
1018 <literallayout class='monospaced'> 1140 that include the sources for each of the Yocto Project recipes.
1141 <literallayout class='monospaced'>
1019 $ bitbake world -f -c distro_check 1142 $ bitbake world -f -c distro_check
1020 </literallayout> 1143 </literallayout>
1021 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename> 1144 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
1022 file. 1145 file found in the Yocto Project files area.
1023 </para> 1146 </para>
1024 </section>
1025 </section> 1147 </section>
1026</chapter> 1148</chapter>
1027 1149
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-02 00:10:02 +0000