summaryrefslogtreecommitdiffstats
path: root/handbook/extendpoky.xml
diff options
context:
space:
mode:
Diffstat (limited to 'handbook/extendpoky.xml')
-rw-r--r--handbook/extendpoky.xml726
1 files changed, 726 insertions, 0 deletions
diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml
new file mode 100644
index 0000000000..18a7b66647
--- /dev/null
+++ b/handbook/extendpoky.xml
@@ -0,0 +1,726 @@
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 The simplest way to add a new package is to base it on a similar
30 pre-existing recipe. There are some examples below of how to add
31 standard types of packages:
32 </para>
33
34 <section id='usingpoky-extend-addpkg-singlec'>
35 <title>Single .c File Package (Hello World!)</title>
36
37 <para>
38 To build an application from a single file stored locally requires a
39 recipe which has the file listed in the <glossterm><link
40 linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. In addition
41 the <function>do_compile</function> and <function>do_install</function>
42 tasks need to be manually written. The <glossterm><link linkend='var-S'>
43 S</link></glossterm> variable defines the directory containing the source
44 code which in this case is set equal to <glossterm><link linkend='var-WORKDIR'>
45 WORKDIR</link></glossterm>, the directory BitBake uses for the build.
46 </para>
47 <programlisting>
48DESCRIPTION = "Simple helloworld application"
49SECTION = "examples"
50LICENSE = "MIT"
51
52SRC_URI = "file://helloworld.c"
53
54S = "${WORKDIR}"
55
56do_compile() {
57 ${CC} helloworld.c -o helloworld
58}
59
60do_install() {
61 install -d ${D}${bindir}
62 install -m 0755 helloworld ${D}${bindir}
63}
64 </programlisting>
65
66 <para>
67 As a result of the build process "helloworld" and "helloworld-dbg"
68 packages will be built.
69 </para>
70 </section>
71
72 <section id='usingpoky-extend-addpkg-autotools'>
73 <title>Autotooled Package</title>
74
75 <para>
76 Applications which use autotools (autoconf, automake)
77 require a recipe which has a source archive listed in
78 <glossterm><link
79 linkend='var-SRC_URI'>SRC_URI</link></glossterm> and
80 <command>inherit autotools</command> to instruct BitBake to use the
81 <filename>autotools.bbclass</filename> which has
82 definitions of all the steps
83 needed to build an autotooled application.
84 The result of the build will be automatically packaged and if
85 the application uses NLS to localise then packages with
86 locale information will be generated (one package per
87 language).
88 </para>
89
90 <programlisting>
91DESCRIPTION = "GNU Helloworld application"
92SECTION = "examples"
93LICENSE = "GPLv2"
94
95SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2"
96
97inherit autotools
98 </programlisting>
99
100 </section>
101
102 <section id='usingpoky-extend-addpkg-makefile'>
103 <title>Makefile-Based Package</title>
104
105 <para>
106 Applications which use GNU make require a recipe which has
107 the source archive listed in <glossterm><link
108 linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
109 Adding a <function>do_compile</function> step
110 is not needed as by default BitBake will start the "make"
111 command to compile the application. If there is a need for
112 additional options to make then they should be stored in the
113 <glossterm><link
114 linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable - BitBake
115 will pass them into the GNU
116 make invocation. A <function>do_install</function> task is required
117 - otherwise BitBake will run an empty <function>do_install</function>
118 task by default.
119 </para>
120
121 <para>
122 Some applications may require extra parameters to be passed to
123 the compiler, for example an additional header path. This can
124 be done buy adding to the <glossterm><link
125 linkend='var-CFLAGS'>CFLAGS</link></glossterm> variable, as in the example below.
126 </para>
127
128 <programlisting>
129DESCRIPTION = "Tools for managing memory technology devices."
130SECTION = "base"
131DEPENDS = "zlib"
132HOMEPAGE = "http://www.linux-mtd.infradead.org/"
133LICENSE = "GPLv2"
134
135SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz"
136
137CFLAGS_prepend = "-I ${S}/include "
138
139do_install() {
140 oe_runmake install DESTDIR=${D}
141}
142 </programlisting>
143
144 </section>
145
146 <section id='usingpoky-extend-addpkg-files'>
147 <title>Controlling packages content</title>
148
149 <para>
150 The variables <glossterm><link
151 linkend='var-PACKAGES'>PACKAGES</link></glossterm> and
152 <glossterm><link linkend='var-FILES'>FILES</link></glossterm> are used to split an
153 application into multiple packages.
154 </para>
155
156 <para>
157 Below the "libXpm" recipe is used as an example. By
158 default the "libXpm" recipe generates one package
159 which contains the library
160 and also a few binaries. The recipe can be adapted to
161 split the binaries into separate packages.
162 </para>
163
164 <programlisting>
165require xorg-lib-common.inc
166
167DESCRIPTION = "X11 Pixmap library"
168LICENSE = "X-BSD"
169DEPENDS += "libxext"
170PE = "1"
171
172XORG_PN = "libXpm"
173
174PACKAGES =+ "sxpm cxpm"
175FILES_cxpm = "${bindir}/cxpm"
176FILES_sxpm = "${bindir}/sxpm"
177 </programlisting>
178
179 <para>
180 In this example we want to ship the "sxpm" and "cxpm" binaries
181 in separate packages. Since "bindir" would be packaged into the
182 main <glossterm><link linkend='var-PN'>PN</link></glossterm>
183 package as standard we prepend the <glossterm><link
184 linkend='var-PACKAGES'>PACKAGES</link></glossterm> variable so
185 additional package names are added to the start of list. The
186 extra <glossterm><link linkend='var-PN'>FILES</link></glossterm>_*
187 variables then contain information to specify which files and
188 directories goes into which package.
189 </para>
190 </section>
191
192 <section id='usingpoky-extend-addpkg-postinstalls'>
193 <title>Post Install Scripts</title>
194
195 <para>
196 To add a post-installation script to a package, add
197 a <function>pkg_postinst_PACKAGENAME()</function>
198 function to the .bb file
199 where PACKAGENAME is the name of the package to attach
200 the postinst script to. A post-installation function has the following structure:
201 </para>
202 <programlisting>
203pkg_postinst_PACKAGENAME () {
204#!/bin/sh -e
205# Commands to carry out
206}
207 </programlisting>
208 <para>
209 The script defined in the post installation function
210 gets called when the rootfs is made. If the script succeeds,
211 the package is marked as installed. If the script fails,
212 the package is marked as unpacked and the script will be
213 executed again on the first boot of the image.
214 </para>
215
216 <para>
217 Sometimes it is necessary that the execution of a post-installation
218 script is delayed until the first boot, because the script
219 needs to be executed the device itself. To delay script execution
220 until boot time, the post-installation function should have the
221 following structure:
222 </para>
223
224 <programlisting>
225pkg_postinst_PACKAGENAME () {
226#!/bin/sh -e
227if [ x"$D" = "x" ]; then
228# Actions to carry out on the device go here
229else
230exit 1
231fi
232}
233 </programlisting>
234
235 <para>
236 The structure above delays execution until first boot
237 because the <glossterm><link
238 linkend='var-D'>D</link></glossterm> variable points
239 to the 'image'
240 directory when the rootfs is being made at build time but
241 is unset when executed on the first boot.
242 </para>
243 </section>
244
245 </section>
246
247 <section id='usingpoky-extend-customimage'>
248 <title>Customising Images</title>
249
250 <para>
251 Poky images can be customised to satisfy
252 particular requirements. Several methods are detailed below
253 along with guidelines of when to use them.
254 </para>
255
256 <section id='usingpoky-extend-customimage-custombb'>
257 <title>Customising Images through a custom image .bb files</title>
258
259 <para>
260 One way to get additional software into an image is by creating a
261 custom image. The recipe will contain two lines:
262 </para>
263
264 <programlisting>
265IMAGE_INSTALL = "task-poky-x11-base package1 package2"
266
267inherit poky-image
268 </programlisting>
269
270 <para>
271 By creating a custom image, a developer has total control
272 over the contents of the image. It is important use
273 the correct names of packages in the <glossterm><link
274 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> variable.
275 The names must be in
276 the OpenEmbedded notation instead of Debian notation, for example
277 "glibc-dev" instead of "libc6-dev" etc.
278 </para>
279
280 <para>
281 The other method of creating a new image is by modifying
282 an existing image. For example if a developer wants to add
283 "strace" into "poky-image-sato" the following recipe can
284 be used:
285 </para>
286
287 <programlisting>
288require poky-image-sato.bb
289
290IMAGE_INSTALL += "strace"
291 </programlisting>
292
293 </section>
294
295 <section id='usingpoky-extend-customimage-customtasks'>
296 <title>Customising Images through custom tasks</title>
297
298 <para>
299 For for complex custom images, the best approach is to create a custom
300 task package which is them used to build the image (or images). A good
301 example of a tasks package is <filename>meta/packages/tasks/task-poky.bb
302 </filename>. The <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm>
303 variable lists the task packages to build (along with the complimentary
304 -dbg and -dev packages). For each package added,
305 <glossterm><link linkend='var-PACKAGES'>RDEPENDS</link></glossterm> and
306 <glossterm><link linkend='var-PACKAGES'>RRECOMMENDS</link></glossterm>
307 entries can then be added each containing a list of packages the parent
308 task package should contain. An example would be:
309 </para>
310
311 <para>
312 <programlisting>
313DESCRIPTION = "My Custom Tasks"
314
315PACKAGES = "\
316 task-custom-apps \
317 task-custom-apps-dbg \
318 task-custom-apps-dev \
319 task-custom-tools \
320 task-custom-tools-dbg \
321 task-custom-tools-dev \
322 "
323
324RDEPENDS_task-custom-apps = "\
325 dropbear \
326 portmap \
327 psplash"
328
329RDEPENDS_task-custom-tools = "\
330 oprofile \
331 oprofileui-server \
332 lttng-control \
333 lttng-viewer"
334
335RRECOMMENDS_task-custom-tools = "\
336 kernel-module-oprofile"
337</programlisting>
338 </para>
339
340 <para>
341 In this example, two tasks packages are created, task-custom-apps and
342 task-custom-tools with the dependencies and recommended package dependencies
343 listed. To build an image using these task packages, you would then add
344 "task-custom-apps" and/or "task-custom-tools" to <glossterm><link
345 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> or other forms
346 of image dependencies as described in other areas of this section.
347 </para>
348 </section>
349
350 <section id='usingpoky-extend-customimage-imagefeatures'>
351 <title>Customising Images through custom <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm></title>
352
353 <para>
354 Ultimately users may want to add extra image "features" as used by Poky with the
355 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
356 variable. To create these, the best reference is <filename>meta/classes/poky-image.bbclass</filename>
357 which illustrates how poky achieves this. In summary, the file looks at the contents of the
358 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
359 variable and based on this generates the <glossterm><link linkend='var-IMAGE_INSTALL'>
360 IMAGE_INSTALL</link></glossterm> variable automatically. Extra features can be added by
361 extending the class or creating a custom class for use with specialised image .bb files.
362 </para>
363 </section>
364
365 <section id='usingpoky-extend-customimage-localconf'>
366 <title>Customising Images through local.conf</title>
367
368 <para>
369 It is possible to customise image contents by abusing
370 variables used by distribution maintainers in local.conf.
371 This method only allows the addition of packages and
372 is not recommended.
373 </para>
374
375 <para>
376 To add an "strace" package into the image the following is
377 added to local.conf:
378 </para>
379
380 <programlisting>
381DISTRO_EXTRA_RDEPENDS += "strace"
382 </programlisting>
383
384 <para>
385 However, since the <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
386 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable is for
387 distribution maintainers this method does not make
388 adding packages as simple as a custom .bb file. Using
389 this method, a few packages will need to be recreated
390 and the the image built.
391 </para>
392 <programlisting>
393bitbake -cclean task-boot task-base task-poky
394bitbake poky-image-sato
395 </programlisting>
396
397 <para>
398 Cleaning task-* packages is required because they use the
399 <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
400 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. There is no need to
401 build them by hand as Poky images depend on the packages they contain so
402 dependencies will be built automatically. For this reason we don't use the
403 "rebuild" task in this case since "rebuild" does not care about
404 dependencies - it only rebuilds the specified package.
405 </para>
406
407 </section>
408
409 </section>
410
411<section id="platdev-newmachine">
412 <title>Porting Poky to a new machine</title>
413 <para>
414 Adding a new machine to Poky is a straightforward process and
415 this section gives an idea of the changes that are needed. This guide is
416 meant to cover adding machines similar to those Poky already supports.
417 Adding a totally new architecture might require gcc/glibc changes as
418 well as updates to the site information and, whilst well within Poky's
419 capabilities, is outside the scope of this section.
420 </para>
421
422 <section id="platdev-newmachine-conffile">
423 <title>Adding the machine configuration file</title>
424 <para>
425 A .conf file needs to be added to conf/machine/ with details of the
426 device being added. The name of the file determines the name Poky will
427 use to reference this machine.
428 </para>
429
430 <para>
431 The most important variables to set in this file are <glossterm>
432 <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm>
433 (e.g. "arm"), <glossterm><link linkend='var-PREFERRED_PROVIDER'>
434 PREFERRED_PROVIDER</link></glossterm>_virtual/kernel (see below) and
435 <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES
436 </link></glossterm> (e.g. "kernel26 apm screen wifi"). Other variables
437 like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE
438 </link></glossterm> (e.g. "115200 ttyS0"), <glossterm>
439 <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link>
440 </glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'>
441 IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2") might also be
442 needed. Full details on what these variables do and the meaning of
443 their contents is available through the links.
444 </para>
445 </section>
446
447 <section id="platdev-newmachine-kernel">
448 <title>Adding a kernel for the machine</title>
449 <para>
450 Poky needs to be able to build a kernel for the machine. You need
451 to either create a new kernel recipe for this machine or extend an
452 existing recipe. There are plenty of kernel examples in the
453 packages/linux directory which can be used as references.
454 </para>
455 <para>
456 If creating a new recipe the "normal" recipe writing rules apply
457 for setting up a <glossterm><link linkend='var-SRC_URI'>SRC_URI
458 </link></glossterm> including any patches and setting <glossterm>
459 <link linkend='var-S'>S</link></glossterm> to point at the source
460 code. You will need to create a configure task which configures the
461 unpacked kernel with a defconfig be that through a "make defconfig"
462 command or more usually though copying in a suitable defconfig and
463 running "make oldconfig". By making use of "inherit kernel" and also
464 maybe some of the linux-*.inc files, most other functionality is
465 centralised and the the defaults of the class normally work well.
466 </para>
467 <para>
468 If extending an existing kernel it is usually a case of adding a
469 suitable defconfig file in a location similar to that used by other
470 machine's defconfig files in a given kernel, possibly listing it in
471 the SRC_URI and adding the machine to the expression in <glossterm>
472 <link linkend='var-COMPATIBLE_MACHINES'>COMPATIBLE_MACHINES</link>
473 </glossterm>.
474 </para>
475 </section>
476
477 <section id="platdev-newmachine-formfactor">
478 <title>Adding a formfactor configuration file</title>
479 <para>
480 A formfactor configuration file provides information about the
481 target hardware on which Poky is running, and that Poky cannot
482 obtain from other sources such as the kernel. Some examples of
483 information contained in a formfactor configuration file include
484 framebuffer orientation, whether or not the system has a keyboard,
485 the positioning of the keyboard in relation to the screen, and
486 screen resolution.
487 </para>
488 <para>
489 Sane defaults should be used in most cases, but if customisation is
490 necessary you need to create a <filename>machconfig</filename> file
491 under <filename>meta/packages/formfactor/files/MACHINENAME/</filename>
492 where <literal>MACHINENAME</literal> is the name for which this infomation
493 applies. For information about the settings available and the defaults, please see
494 <filename>meta/packages/formfactor/files/config</filename>.
495 </para>
496 </section>
497</section>
498
499<section id='usingpoky-changes'>
500 <title>Making and Maintaining Changes</title>
501
502 <para>
503 We recognise that people will want to extend/configure/optimise Poky for
504 their specific uses, especially due to the extreme configurability and
505 flexibility Poky offers. To ensure ease of keeping pace with future
506 changes in Poky we recommend making changes to Poky in a controlled way.
507 </para>
508 <para>
509 Poky supports the idea of <link
510 linkend='usingpoky-changes-collections'>"collections"</link> which when used
511 properly can massively ease future upgrades and allow segregation
512 between the Poky core and a given developer's changes. Some other advice on
513 managing changes to Poky is also given in the following section.
514 </para>
515
516 <section id="usingpoky-changes-collections">
517 <title>Bitbake Collections</title>
518
519 <para>
520 Often, people want to extend Poky either through adding packages
521 or overriding files contained within Poky to add their own
522 functionality. Bitbake has a powerful mechanism called
523 collections which provide a way to handle this which is fully
524 supported and actively encouraged within Poky.
525 </para>
526 <para>
527 In the standard tree, meta-extras is an example of how you can
528 do this. As standard the data in meta-extras is not used on a
529 Poky build but local.conf.sample shows how to enable it:
530 </para>
531 <para>
532 <literallayout class='monospaced'>
533BBFILES := "${OEROOT}/meta/packages/*/*.bb ${OEROOT}/meta-extras/packages/*/*.bb"
534BBFILE_COLLECTIONS = "normal extras"
535BBFILE_PATTERN_normal = "^${OEROOT}/meta/"
536BBFILE_PATTERN_extras = "^${OEROOT}/meta-extras/"
537BBFILE_PRIORITY_normal = "5"
538BBFILE_PRIORITY_extras = "5"</literallayout>
539 </para>
540 <para>
541 As can be seen, the extra recipes are added to BBFILES. The
542 BBFILE_COLLECTIONS variable is then set to contain a list of
543 collection names. The BBFILE_PATTERN variables are regular
544 expressions used to match files from BBFILES into a particular
545 collection in this case by using the base pathname.
546 The BBFILE_PRIORITY variable then assigns the different
547 priorities to the files in different collections. This is useful
548 in situations where the same package might appear in both
549 repositories and allows you to choose which collection should
550 'win'.
551 </para>
552 <para>
553 This works well for recipes. For bbclasses and configuration
554 files, you can use the BBPATH environment variable. In this
555 case, the first file with the matching name found in BBPATH is
556 the one that is used, just like the PATH variable for binaries.
557 </para>
558 </section>
559
560
561 <section id='usingpoky-changes-commits'>
562 <title>Committing Changes</title>
563
564 <para>
565 Modifications to Poky are often managed under some kind of source
566 revision control system. The policy for committing to such systems
567 is important as some simple policy can significantly improve
568 usability. The tips below are based on the policy that OpenedHand
569 uses for commits to Poky.
570 </para>
571
572 <para>
573 It helps to use a consistent style for commit messages when committing
574 changes. We've found a style where the first line of a commit message
575 summarises the change and starts with the name of any package affected
576 work well. Not all changes are to specific packages so the prefix could
577 also be a machine name or class name instead. If a change needs a longer
578 description this should follow the summary.
579 </para>
580
581 <para>
582 Any commit should be self contained in that it should leave the
583 metadata in a consistent state, buildable before and after the
584 commit. This helps ensure the autobuilder test results are valid
585 but is good practice regardless.
586 </para>
587 </section>
588
589 <section id='usingpoky-changes-prbump'>
590 <title>Package Revision Incrementing</title>
591
592 <para>
593 If a committed change will result in changing the package output
594 then the value of the <glossterm><link linkend='var-PR'>PR</link>
595 </glossterm> variable needs to be increased (commonly referred to
596 as 'bumped') as part of that commit. Only integer values are used
597 and <glossterm><link linkend='var-PR'>PR</link></glossterm> =
598 "r0" should not be added into new recipes as this is default value.
599 When upgrading the version of a package (<glossterm><link
600 linkend='var-PV'>PV</link></glossterm>), the <glossterm><link
601 linkend='var-PR'>PR</link></glossterm> variable should be removed.
602 </para>
603
604 <para>
605 The aim is that the package version will only ever increase. If
606 for some reason <glossterm><link linkend='var-PV'>PV</link></glossterm>
607 will change and but not increase, the <glossterm><link
608 linkend='var-PE'>PE</link></glossterm> (Package Epoch) can
609 be increased (it defaults to '0'). The version numbers aim to
610 follow the <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
611 Debian Version Field Policy Guidelines</ulink> which define how
612 versions are compared and hence what "increasing" means.
613 </para>
614
615 <para>
616 There are two reasons for doing this, the first is to ensure that
617 when a developer updates and rebuilds, they get all the changes to
618 the repository and don't have to remember to rebuild any sections.
619 The second is to ensure that target users are able to upgrade their
620 devices via their package manager such as with the <command>
621 ipkg update;ipkg upgrade</command> commands (or similar for
622 dpkg/apt or rpm based systems). The aim is to ensure Poky has
623 upgradable packages in all cases.
624 </para>
625 </section>
626 </section>
627
628 <section id='usingpoky-modifing-packages'>
629 <title>Modifying Package Source Code</title>
630
631 <para>
632 Poky is usually used to build software rather than modifying
633 it. However, there are ways Poky can be used to modify software.
634 </para>
635
636 <para>
637 During building, the sources are available in <glossterm><link
638 linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory.
639 Where exactly this is depends on the type of package and the
640 architecture of target device. For a standard recipe not
641 related to <glossterm><link
642 linkend='var-MACHINE'>MACHINE</link></glossterm> it will be
643 <filename>tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</filename>.
644 Target device dependent packages use <glossterm><link
645 linkend='var-MACHINE'>MACHINE
646 </link></glossterm>
647 instead of <glossterm><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH
648 </link></glossterm>
649 in the directory name.
650 </para>
651
652 <tip>
653 <para>
654 Check the package recipe sets the <glossterm><link
655 linkend='var-S'>S</link></glossterm> variable to something
656 other than standard <filename>WORKDIR/PN-PV/</filename> value.
657 </para>
658 </tip>
659 <para>
660 After building a package, a user can modify the package source code
661 without problem. The easiest way to test changes is by calling the
662 "compile" task:
663 </para>
664
665 <programlisting>
666bitbake --cmd compile --force NAME_OF_PACKAGE
667 </programlisting>
668
669 <para>
670 Other tasks may also be called this way.
671 </para>
672
673 <section id='usingpoky-modifying-packages-quilt'>
674 <title>Modifying Package Source Code with quilt</title>
675
676 <para>
677 By default Poky uses <ulink
678 url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink>
679 to manage patches in <function>do_patch</function> task.
680 It is a powerful tool which can be used to track all
681 modifications done to package sources.
682 </para>
683
684 <para>
685 Before modifying source code it is important to
686 notify quilt so it will track changes into new patch
687 file:
688 <programlisting>
689quilt new NAME-OF-PATCH.patch
690 </programlisting>
691
692 Then add all files which will be modified into that
693 patch:
694 <programlisting>
695quilt add file1 file2 file3
696 </programlisting>
697
698 Now start editing. At the end quilt needs to be used
699 to generate final patch which will contain all
700 modifications:
701 <programlisting>
702quilt refresh
703 </programlisting>
704
705 The resulting patch file can be found in the
706 <filename class="directory">patches/</filename> subdirectory of the source
707 (<glossterm><link linkend='var-S'>S</link></glossterm>) directory. For future builds it
708 should be copied into
709 Poky metadata and added into <glossterm><link
710 linkend='var-SRC_URI'>SRC_URI</link></glossterm> of a recipe:
711 <programlisting>
712SRC_URI += "file://NAME-OF-PATCH.patch;patch=1"
713 </programlisting>
714
715 This also requires a bump of <glossterm><link
716 linkend='var-PR'>PR</link></glossterm> value in the same recipe as we changed resulting packages.
717 </para>
718
719 </section>
720
721</section>
722
723</chapter>
724<!--
725vim: expandtab tw=80 ts=4
726-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-10 20:06:29 +0000