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