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