summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/migration.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/migration.xml')
-rw-r--r--documentation/ref-manual/migration.xml1697
1 files changed, 1697 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
new file mode 100644
index 0000000..d51bc4d
--- /dev/null
+++ b/documentation/ref-manual/migration.xml
@@ -0,0 +1,1697 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='migration'>
6<title>Migrating to a Newer Yocto Project Release</title>
7
8 <para>
9 This chapter provides information you can use to migrate work to a
10 newer Yocto Project release. You can find the same information in the
11 release notes for a given release.
12 </para>
13
14<section id='general-migration-considerations'>
15 <title>General Migration Considerations</title>
16
17 <para>
18 Some considerations are not tied to a specific Yocto Project
19 release.
20 This section presents information you should consider when
21 migrating to any new Yocto Project release.
22 <itemizedlist>
23 <listitem><para><emphasis>Dealing with Customized Recipes</emphasis>:
24 Issues could arise if you take older recipes that contain
25 customizations and simply copy them forward expecting them
26 to work after you migrate to new Yocto Project metadata.
27 For example, suppose you have a recipe in your layer that is
28 a customized version of a core recipe copied from the earlier
29 release, rather than through the use of an append file.
30 When you migrate to a newer version of Yocto Project, the
31 metadata (e.g. perhaps an include file used by the recipe)
32 could have changed in a way that would break the build.
33 Say, for example, a function is removed from an include file
34 and the customized recipe tries to call that function.
35 </para>
36
37 <para>You could "forward-port" all your customizations in your
38 recipe so that everything works for the new release.
39 However, this is not the optimal solution as you would have
40 to repeat this process with each new release if changes
41 occur that give rise to problems.</para>
42
43 <para>The better solution (where practical) is to use append
44 files (<filename>*.bbappend</filename>) to capture any
45 customizations you want to make to a recipe.
46 Doing so, isolates your changes from the main recipe making
47 them much more manageable.
48 However, sometimes it is not practical to use an append
49 file.
50 A good example of this is when introducing a newer or older
51 version of a recipe in another layer.</para>
52 </listitem>
53 <listitem><para><emphasis>Updating Append Files</emphasis>:
54 Since append files generally only contain your customizations,
55 they often do not need to be adjusted for new releases.
56 However, if the <filename>.bbappend</filename> file is
57 specific to a particular version of the recipe (i.e. its
58 name does not use the % wildcard) and the version of the
59 recipe to which it is appending has changed, then you will
60 at a minimum need to rename the append file to match the
61 name of the recipe file.
62 A mismatch between an append file and its corresponding
63 recipe file (<filename>.bb</filename>) will
64 trigger an error during parsing.</para>
65 <para>Depending on the type of customization the append file
66 applies, other incompatibilities might occur when you
67 upgrade.
68 For example, if your append file applies a patch and the
69 recipe to which it is appending is updated to a newer
70 version, the patch might no longer apply.
71 If this is the case and assuming the patch is still needed,
72 you must modify the patch file so that it does apply.
73 </para></listitem>
74 </itemizedlist>
75 </para>
76</section>
77
78<section id='moving-to-the-yocto-project-1.3-release'>
79 <title>Moving to the Yocto Project 1.3 Release</title>
80
81 <para>
82 This section provides migration information for moving to the
83 Yocto Project 1.3 Release from the prior release.
84 </para>
85
86 <section id='1.3-local-configuration'>
87 <title>Local Configuration</title>
88
89 <para>
90 Differences include changes for
91 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
92 and <filename>bblayers.conf</filename>.
93 </para>
94
95 <section id='migration-1.3-sstate-mirrors'>
96 <title>SSTATE_MIRRORS</title>
97
98 <para>
99 The shared state cache (sstate-cache), as pointed to by
100 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, by default
101 now has two-character subdirectories to prevent issues arising
102 from too many files in the same directory.
103 Also, native sstate-cache packages will go into a subdirectory named using
104 the distro ID string.
105 If you copy the newly structured sstate-cache to a mirror location
106 (either local or remote) and then point to it in
107 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
108 you need to append "PATH" to the end of the mirror URL so that
109 the path used by BitBake before the mirror substitution is
110 appended to the path used to access the mirror.
111 Here is an example:
112 <literallayout class='monospaced'>
113 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
114 </literallayout>
115 </para>
116 </section>
117
118 <section id='migration-1.3-bblayers-conf'>
119 <title>bblayers.conf</title>
120
121 <para>
122 The <filename>meta-yocto</filename> layer consists of two parts
123 that correspond to the Poky reference distribution and the
124 reference hardware Board Support Packages (BSPs), respectively:
125 <filename>meta-yocto</filename> and
126 <filename>meta-yocto-bsp</filename>.
127 When running BitBake or Hob for the first time after upgrading,
128 your <filename>conf/bblayers.conf</filename> file will be
129 updated to handle this change and you will be asked to
130 re-run or restart for the changes to take effect.
131 </para>
132 </section>
133 </section>
134
135 <section id='1.3-recipes'>
136 <title>Recipes</title>
137
138 <para>
139 Differences include changes for the following:
140 <itemizedlist>
141 <listitem><para>Python function whitespace</para></listitem>
142 <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem>
143 <listitem><para><filename>nativesdk</filename></para></listitem>
144 <listitem><para>Task recipes</para></listitem>
145 <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem>
146 <listitem><para>Removed recipes</para></listitem>
147 </itemizedlist>
148 </para>
149
150 <section id='migration-1.3-python-function-whitespace'>
151 <title>Python Function Whitespace</title>
152
153 <para>
154 All Python functions must now use four spaces for indentation.
155 Previously, an inconsistent mix of spaces and tabs existed,
156 which made extending these functions using
157 <filename>_append</filename> or <filename>_prepend</filename>
158 complicated given that Python treats whitespace as
159 syntactically significant.
160 If you are defining or extending any Python functions (e.g.
161 <filename>populate_packages</filename>, <filename>do_unpack</filename>,
162 <filename>do_patch</filename> and so forth) in custom recipes
163 or classes, you need to ensure you are using consistent
164 four-space indentation.
165 </para>
166 </section>
167
168 <section id='migration-1.3-proto=-in-src-uri'>
169 <title>proto= in SRC_URI</title>
170
171 <para>
172 Any use of <filename>proto=</filename> in
173 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
174 needs to be changed to <filename>protocol=</filename>.
175 In particular, this applies to the following URIs:
176 <itemizedlist>
177 <listitem><para><filename>svn://</filename></para></listitem>
178 <listitem><para><filename>bzr://</filename></para></listitem>
179 <listitem><para><filename>hg://</filename></para></listitem>
180 <listitem><para><filename>osc://</filename></para></listitem>
181 </itemizedlist>
182 Other URIs were already using <filename>protocol=</filename>.
183 This change improves consistency.
184 </para>
185 </section>
186
187 <section id='migration-1.3-nativesdk'>
188 <title>nativesdk</title>
189
190 <para>
191 The suffix <filename>nativesdk</filename> is now implemented
192 as a prefix, which simplifies a lot of the packaging code for
193 <filename>nativesdk</filename> recipes.
194 All custom <filename>nativesdk</filename> recipes and any
195 references need to be updated to use
196 <filename>nativesdk-*</filename> instead of
197 <filename>*-nativesdk</filename>.
198 </para>
199 </section>
200
201 <section id='migration-1.3-task-recipes'>
202 <title>Task Recipes</title>
203
204 <para>
205 "Task" recipes are now known as "Package groups" and have
206 been renamed from <filename>task-*.bb</filename> to
207 <filename>packagegroup-*.bb</filename>.
208 Existing references to the previous <filename>task-*</filename>
209 names should work in most cases as there is an automatic
210 upgrade path for most packages.
211 However, you should update references in your own recipes and
212 configurations as they could be removed in future releases.
213 You should also rename any custom <filename>task-*</filename>
214 recipes to <filename>packagegroup-*</filename>, and change
215 them to inherit <filename>packagegroup</filename> instead of
216 <filename>task</filename>, as well as taking the opportunity
217 to remove anything now handled by
218 <filename>packagegroup.bbclass</filename>, such as providing
219 <filename>-dev</filename> and <filename>-dbg</filename>
220 packages, setting
221 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
222 and so forth.
223 See the
224 "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>"
225 section for further details.
226 </para>
227 </section>
228
229 <section id='migration-1.3-image-features'>
230 <title>IMAGE_FEATURES</title>
231
232 <para>
233 Image recipes that previously included "apps-console-core"
234 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
235 should now include "splash" instead to enable the boot-up
236 splash screen.
237 Retaining "apps-console-core" will still include the splash
238 screen but generates a warning.
239 The "apps-x11-core" and "apps-x11-games"
240 <filename>IMAGE_FEATURES</filename> features have been removed.
241 </para>
242 </section>
243
244 <section id='migration-1.3-removed-recipes'>
245 <title>Removed Recipes</title>
246
247 <para>
248 The following recipes have been removed.
249 For most of them, it is unlikely that you would have any
250 references to them in your own
251 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>.
252 However, you should check your metadata against this list to be sure:
253 <itemizedlist>
254 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
255 Replaced by <filename>libx11</filename>, which has a negligible
256 size difference with modern Xorg.</para></listitem>
257 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
258 Use <filename>xserver-xorg</filename>, which has a negligible
259 size difference when DRI and GLX modules are not installed.</para></listitem>
260 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
261 Effectively unmaintained for many years.</para></listitem>
262 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
263 No longer serves any purpose.</para></listitem>
264 <listitem><para><emphasis><filename>galago</filename></emphasis>:
265 Replaced by telepathy.</para></listitem>
266 <listitem><para><emphasis><filename>gail</filename></emphasis>:
267 Functionality was integrated into GTK+ 2.13.</para></listitem>
268 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
269 No longer needed.</para></listitem>
270 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
271 The build has been restructured to avoid the need for
272 this step.</para></listitem>
273 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
274 Unmaintained for many years.
275 Functionality now provided by
276 <filename>ofono</filename> instead.</para></listitem>
277 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
278 Largely unmaintained PIM application suite.
279 It has been moved to <filename>meta-gnome</filename>
280 in <filename>meta-openembedded</filename>.</para></listitem>
281 </itemizedlist>
282 In addition to the previously listed changes, the
283 <filename>meta-demoapps</filename> directory has also been removed
284 because the recipes in it were not being maintained and many
285 had become obsolete or broken.
286 Additionally, these recipes were not parsed in the default configuration.
287 Many of these recipes are already provided in an updated and
288 maintained form within the OpenEmbedded community layers such as
289 <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
290 For the remainder, you can now find them in the
291 <filename>meta-extras</filename> repository, which is in the
292 Yocto Project
293 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>.
294 </para>
295 </section>
296 </section>
297
298 <section id='1.3-linux-kernel-naming'>
299 <title>Linux Kernel Naming</title>
300
301 <para>
302 The naming scheme for kernel output binaries has been changed to
303 now include
304 <link linkend='var-PE'><filename>PE</filename></link> as part of the
305 filename:
306 <literallayout class='monospaced'>
307 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
308 </literallayout>
309 </para>
310
311 <para>
312 Because the <filename>PE</filename> variable is not set by default,
313 these binary files could result with names that include two dash
314 characters.
315 Here is an example:
316 <literallayout class='monospaced'>
317 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
318 </literallayout>
319 </para>
320 </section>
321</section>
322
323<section id='moving-to-the-yocto-project-1.4-release'>
324 <title>Moving to the Yocto Project 1.4 Release</title>
325
326 <para>
327 This section provides migration information for moving to the
328 Yocto Project 1.4 Release from the prior release.
329 </para>
330
331 <section id='migration-1.4-bitbake'>
332 <title>BitBake</title>
333
334 <para>
335 Differences include the following:
336 <itemizedlist>
337 <listitem><para><emphasis>Comment Continuation:</emphasis>
338 If a comment ends with a line continuation (\) character,
339 then the next line must also be a comment.
340 Any instance where this is not the case, now triggers
341 a warning.
342 You must either remove the continuation character, or be
343 sure the next line is a comment.
344 </para></listitem>
345 <listitem><para><emphasis>Package Name Overrides:</emphasis>
346 The runtime package specific variables
347 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
348 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
349 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
350 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
351 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
352 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
353 <link linkend='var-FILES'><filename>FILES</filename></link>,
354 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
355 and the pre, post, install, and uninstall script functions
356 <filename>pkg_preinst</filename>,
357 <filename>pkg_postinst</filename>,
358 <filename>pkg_prerm</filename>, and
359 <filename>pkg_postrm</filename> should always have a
360 package name override.
361 For example, use <filename>RDEPENDS_${PN}</filename> for
362 the main package instead of <filename>RDEPENDS</filename>.
363 BitBake uses more strict checks when it parses recipes.
364 </para></listitem>
365 </itemizedlist>
366 </para>
367 </section>
368
369 <section id='migration-1.4-build-behavior'>
370 <title>Build Behavior</title>
371
372 <para>
373 Differences include the following:
374 <itemizedlist>
375 <listitem><para><emphasis>Shared State Code:</emphasis>
376 The shared state code has been optimized to avoid running
377 unnecessary tasks.
378 For example,
379 <filename>bitbake -c rootfs some-image</filename> from
380 shared state no longer populates the target sysroot
381 since that is not necessary.
382 Instead, the system just needs to extract the output
383 package contents, re-create the packages, and construct
384 the root filesystem.
385 This change is unlikely to cause any problems unless
386 you have missing declared dependencies.
387 </para></listitem>
388 <listitem><para><emphasis>Scanning Directory Names:</emphasis>
389 When scanning for files in
390 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
391 the build system now uses
392 <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
393 instead of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
394 for the directory names.
395 In general, the values previously in
396 <filename>OVERRIDES</filename> are now in
397 <filename>FILESOVERRIDES</filename> as well.
398 However, if you relied upon an additional value
399 you previously added to <filename>OVERRIDES</filename>,
400 you might now need to add it to
401 <filename>FILESOVERRIDES</filename> unless you are already
402 adding it through the
403 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>
404 or <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
405 variables, as appropriate.
406 For more related changes, see the
407 "<link linkend='migration-1.4-variables'>Variables</link>"
408 section.
409 </para></listitem>
410 </itemizedlist>
411 </para>
412 </section>
413
414
415 <section id='migration-1.4-proxies-and-fetching-source'>
416 <title>Proxies and Fetching Source</title>
417
418 <para>
419 A new <filename>oe-git-proxy</filename> script has been added to
420 replace previous methods of handling proxies and fetching source
421 from Git.
422 See the <filename>meta-yocto/conf/site.conf.sample</filename> file
423 for information on how to use this script.
424 </para>
425 </section>
426
427 <section id='migration-1.4-custom-interfaces-file-netbase-change'>
428 <title>Custom Interfaces File (netbase change)</title>
429
430 <para>
431 If you have created your own custom
432 <filename>etc/network/interfaces</filename> file by creating
433 an append file for the <filename>netbase</filename> recipe,
434 you now need to create an append file for the
435 <filename>init-ifupdown</filename> recipe instead, which you can
436 find in the
437 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
438 at <filename>meta/recipes-core/init-ifupdown</filename>.
439 For information on how to use append files, see the
440 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
441 in the Yocto Project Development Manual.
442 </para>
443 </section>
444
445 <section id='migration-1.4-remote-debugging'>
446 <title>Remote Debugging</title>
447
448 <para>
449 Support for remote debugging with the Eclipse IDE is now
450 separated into an image feature
451 (<filename>eclipse-debug</filename>) that corresponds to the
452 <filename>packagegroup-core-eclipse-debug</filename> package group.
453 Previously, the debugging feature was included through the
454 <filename>tools-debug</filename> image feature, which corresponds
455 to the <filename>packagegroup-core-tools-debug</filename>
456 package group.
457 </para>
458 </section>
459
460 <section id='migration-1.4-variables'>
461 <title>Variables</title>
462
463 <para>
464 The following variables have changed:
465 <itemizedlist>
466 <listitem><para><emphasis><filename>SANITY_TESTED_DISTROS</filename>:</emphasis>
467 This variable now uses a distribution ID, which is composed
468 of the host distributor ID followed by the release.
469 Previously,
470 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
471 was composed of the description field.
472 For example, "Ubuntu 12.10" becomes "Ubuntu-12.10".
473 You do not need to worry about this change if you are not
474 specifically setting this variable, or if you are
475 specifically setting it to "".
476 </para></listitem>
477 <listitem><para><emphasis><filename>SRC_URI</filename>:</emphasis>
478 The <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>,
479 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>,
480 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>,
481 and <filename>FILE_DIRNAME</filename> directories have been
482 dropped from the default value of the
483 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
484 variable, which is used as the search path for finding files
485 referred to in
486 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
487 If you have a recipe that relied upon these directories,
488 which would be unusual, then you will need to add the
489 appropriate paths within the recipe or, alternatively,
490 rearrange the files.
491 The most common locations are still covered by
492 <filename>${BP}</filename>, <filename>${BPN}</filename>,
493 and "files", which all remain in the default value of
494 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
495 </para></listitem>
496 </itemizedlist>
497 </para>
498 </section>
499
500 <section id='migration-target-package-management-with-rpm'>
501 <title>Target Package Management with RPM</title>
502
503 <para>
504 If runtime package management is enabled and the RPM backend
505 is selected, Smart is now installed for package download, dependency
506 resolution, and upgrades instead of Zypper.
507 For more information on how to use Smart, run the following command
508 on the target:
509 <literallayout class='monospaced'>
510 smart --help
511 </literallayout>
512 </para>
513 </section>
514
515 <section id='migration-1.4-recipes-moved'>
516 <title>Recipes Moved</title>
517
518 <para>
519 The following recipes were moved from their previous locations
520 because they are no longer used by anything in
521 the OpenEmbedded-Core:
522 <itemizedlist>
523 <listitem><para><emphasis><filename>clutter-box2d</filename>:</emphasis>
524 Now resides in the <filename>meta-oe</filename> layer.
525 </para></listitem>
526 <listitem><para><emphasis><filename>evolution-data-server</filename>:</emphasis>
527 Now resides in the <filename>meta-gnome</filename> layer.
528 </para></listitem>
529 <listitem><para><emphasis><filename>gthumb</filename>:</emphasis>
530 Now resides in the <filename>meta-gnome</filename> layer.
531 </para></listitem>
532 <listitem><para><emphasis><filename>gtkhtml2</filename>:</emphasis>
533 Now resides in the <filename>meta-oe</filename> layer.
534 </para></listitem>
535 <listitem><para><emphasis><filename>gupnp</filename>:</emphasis>
536 Now resides in the <filename>meta-multimedia</filename> layer.
537 </para></listitem>
538 <listitem><para><emphasis><filename>gypsy</filename>:</emphasis>
539 Now resides in the <filename>meta-oe</filename> layer.
540 </para></listitem>
541 <listitem><para><emphasis><filename>libcanberra</filename>:</emphasis>
542 Now resides in the <filename>meta-gnome</filename> layer.
543 </para></listitem>
544 <listitem><para><emphasis><filename>libgdata</filename>:</emphasis>
545 Now resides in the <filename>meta-gnome</filename> layer.
546 </para></listitem>
547 <listitem><para><emphasis><filename>libmusicbrainz</filename>:</emphasis>
548 Now resides in the <filename>meta-multimedia</filename> layer.
549 </para></listitem>
550 <listitem><para><emphasis><filename>metacity</filename>:</emphasis>
551 Now resides in the <filename>meta-gnome</filename> layer.
552 </para></listitem>
553 <listitem><para><emphasis><filename>polkit</filename>:</emphasis>
554 Now resides in the <filename>meta-oe</filename> layer.
555 </para></listitem>
556 <listitem><para><emphasis><filename>zeroconf</filename>:</emphasis>
557 Now resides in the <filename>meta-networking</filename> layer.
558 </para></listitem>
559 </itemizedlist>
560 </para>
561 </section>
562
563 <section id='migration-1.4-removals-and-renames'>
564 <title>Removals and Renames</title>
565
566 <para>
567 The following list shows what has been removed or renamed:
568 <itemizedlist>
569 <listitem><para><emphasis><filename>evieext</filename>:</emphasis>
570 Removed because it has been removed from
571 <filename>xserver</filename> since 2008.
572 </para></listitem>
573 <listitem><para><emphasis>Gtk+ DirectFB:</emphasis>
574 Removed support because upstream Gtk+ no longer supports it
575 as of version 2.18.
576 </para></listitem>
577 <listitem><para><emphasis><filename>libxfontcache / xfontcacheproto</filename>:</emphasis>
578 Removed because they were removed from the Xorg server in 2008.
579 </para></listitem>
580 <listitem><para><emphasis><filename>libxp / libxprintapputil / libxprintutil / printproto</filename>:</emphasis>
581 Removed because the XPrint server was removed from
582 Xorg in 2008.
583 </para></listitem>
584 <listitem><para><emphasis><filename>libxtrap / xtrapproto</filename>:</emphasis>
585 Removed because their functionality was broken upstream.
586 </para></listitem>
587 <listitem><para><emphasis>linux-yocto 3.0 kernel:</emphasis>
588 Removed with linux-yocto 3.8 kernel being added.
589 The linux-yocto 3.2 and linux-yocto 3.4 kernels remain
590 as part of the release.
591 </para></listitem>
592 <listitem><para><emphasis><filename>lsbsetup</filename>:</emphasis>
593 Removed with functionality now provided by
594 <filename>lsbtest</filename>.
595 </para></listitem>
596 <listitem><para><emphasis><filename>matchbox-stroke</filename>:</emphasis>
597 Removed because it was never more than a proof-of-concept.
598 </para></listitem>
599 <listitem><para><emphasis><filename>matchbox-wm-2 / matchbox-theme-sato-2</filename>:</emphasis>
600 Removed because they are not maintained.
601 However, <filename>matchbox-wm</filename> and
602 <filename>matchbox-theme-sato</filename> are still
603 provided.
604 </para></listitem>
605 <listitem><para><emphasis><filename>mesa-dri</filename>:</emphasis>
606 Renamed to <filename>mesa</filename>.
607 </para></listitem>
608 <listitem><para><emphasis><filename>mesa-xlib</filename>:</emphasis>
609 Removed because it was no longer useful.
610 </para></listitem>
611 <listitem><para><emphasis><filename>mutter</filename>:</emphasis>
612 Removed because nothing ever uses it and the recipe is
613 very old.
614 </para></listitem>
615 <listitem><para><emphasis><filename>orinoco-conf</filename>:</emphasis>
616 Removed because it has become obsolete.
617 </para></listitem>
618 <listitem><para><emphasis><filename>update-modules</filename>:</emphasis>
619 Removed because it is no longer used.
620 The kernel module <filename>postinstall</filename> and
621 <filename>postrm</filename> scripts can now do the same
622 task without the use of this script.
623 </para></listitem>
624 <listitem><para><emphasis><filename>web</filename>:</emphasis>
625 Removed because it is not maintained. Superseded by
626 <filename>web-webkit</filename>.
627 </para></listitem>
628 <listitem><para><emphasis><filename>xf86bigfontproto</filename>:</emphasis>
629 Removed because upstream it has been disabled by default
630 since 2007.
631 Nothing uses <filename>xf86bigfontproto</filename>.
632 </para></listitem>
633 <listitem><para><emphasis><filename>xf86rushproto</filename>:</emphasis>
634 Removed because its dependency in
635 <filename>xserver</filename> was spurious and it was
636 removed in 2005.
637 </para></listitem>
638 <listitem><para><emphasis><filename>zypper / libzypp / sat-solver</filename>:</emphasis>
639 Removed and been functionally replaced with Smart
640 (<filename>python-smartpm</filename>) when RPM packaging
641 is used and package management is enabled on the target.
642 </para></listitem>
643 </itemizedlist>
644 </para>
645 </section>
646</section>
647
648<section id='moving-to-the-yocto-project-1.5-release'>
649 <title>Moving to the Yocto Project 1.5 Release</title>
650
651 <para>
652 This section provides migration information for moving to the
653 Yocto Project 1.5 Release from the prior release.
654 </para>
655
656 <section id='migration-1.5-host-dependency-changes'>
657 <title>Host Dependency Changes</title>
658
659 <para>
660 The OpenEmbedded build system now has some additional requirements
661 on the host system:
662 <itemizedlist>
663 <listitem><para>Python 2.7.3+</para></listitem>
664 <listitem><para>Tar 1.24+</para></listitem>
665 <listitem><para>Git 1.7.5+</para></listitem>
666 <listitem><para>Patched version of Make if you are using
667 3.82.
668 Most distributions that provide Make 3.82 use the patched
669 version.</para></listitem>
670 </itemizedlist>
671 If the Linux distribution you are using on your build host
672 does not provide packages for these, you can install and use
673 the Buildtools tarball, which provides an SDK-like environment
674 containing them.
675 </para>
676
677 <para>
678 For more information on this requirement, see the
679 "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
680 section.
681 </para>
682 </section>
683
684 <section id='migration-1.5-atom-pc-bsp'>
685 <title><filename>atom-pc</filename> Board Support Package (BSP)</title>
686
687 <para>
688 The <filename>atom-pc</filename> hardware reference BSP has been
689 replaced by a <filename>genericx86</filename> BSP.
690 This BSP is not necessarily guaranteed to work on all x86
691 hardware, but it will run on a wider range of systems than the
692 <filename>atom-pc</filename> did.
693 <note>
694 Additionally, a <filename>genericx86-64</filename> BSP has
695 been added for 64-bit Atom systems.
696 </note>
697 </para>
698 </section>
699
700 <section id='migration-1.5-bitbake'>
701 <title>BitBake</title>
702
703 <para>
704 The following changes have been made that relate to BitBake:
705 <itemizedlist>
706 <listitem><para>
707 BitBake now supports a <filename>_remove</filename>
708 operator.
709 The addition of this operator means you will have to
710 rename any items in recipe space (functions, variables)
711 whose names currently contain
712 <filename>_remove_</filename> or end with
713 <filename>_remove</filename> to avoid unexpected behavior.
714 </para></listitem>
715 <listitem><para>
716 BitBake's global method pool has been removed.
717 This method is not particularly useful and led to clashes
718 between recipes containing functions that had the
719 same name.</para></listitem>
720 <listitem><para>
721 The "none" server backend has been removed.
722 The "process" server backend has been serving well as the
723 default for a long time now.</para></listitem>
724 <listitem><para>
725 The <filename>bitbake-runtask</filename> script has been
726 removed.</para></listitem>
727 <listitem><para>
728 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>
729 and
730 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>
731 are no longer added to
732 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
733 by default in <filename>bitbake.conf</filename>.
734 These version-specific <filename>PROVIDES</filename>
735 items were seldom used.
736 Attempting to use them could result in two versions being
737 built simultaneously rather than just one version due to
738 the way BitBake resolves dependencies.</para></listitem>
739 </itemizedlist>
740 </para>
741 </section>
742
743 <section id='migration-1.5-qa-warnings'>
744 <title>QA Warnings</title>
745
746 <para>
747 The following changes have been made to the package QA checks:
748 <itemizedlist>
749 <listitem><para>
750 If you have customized
751 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
752 or <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link>
753 values in your configuration, check that they contain all of
754 the issues that you wish to be reported.
755 Previous Yocto Project versions contained a bug that meant
756 that any item not mentioned in <filename>ERROR_QA</filename>
757 or <filename>WARN_QA</filename> would be treated as a
758 warning.
759 Consequently, several important items were not already in
760 the default value of <filename>WARN_QA</filename>.
761 All of the possible QA checks are now documented in the
762 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
763 section.</para></listitem>
764 <listitem><para>
765 An additional QA check has been added to check if
766 <filename>/usr/share/info/dir</filename> is being installed.
767 Your recipe should delete this file within
768 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
769 if "make install" is installing it.
770 </para></listitem>
771 <listitem><para>
772 If you are using the buildhistory class, the check for the
773 package version going backwards is now controlled using a
774 standard QA check.
775 Thus, if you have customized your
776 <filename>ERROR_QA</filename> or
777 <filename>WARN_QA</filename> values and still wish to have
778 this check performed, you should add
779 "version-going-backwards" to your value for one or the
780 other variables depending on how you wish it to be handled.
781 See the documented QA checks in the
782 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
783 section.
784 </para></listitem>
785 </itemizedlist>
786 </para>
787 </section>
788
789 <section id='migration-1.5-directory-layout-changes'>
790 <title>Directory Layout Changes</title>
791
792 <para>
793 The following directory changes exist:
794 <itemizedlist>
795 <listitem><para>
796 Output SDK installer files are now named to include the
797 image name and tuning architecture through the
798 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
799 variable.</para></listitem>
800 <listitem><para>
801 Images and related files are now installed into a directory
802 that is specific to the machine, instead of a parent
803 directory containing output files for multiple machines.
804 The
805 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
806 variable continues to point to the directory containing
807 images for the current
808 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
809 and should be used anywhere there is a need to refer to
810 this directory.
811 The <filename>runqemu</filename> script now uses this
812 variable to find images and kernel binaries and will use
813 BitBake to determine the directory.
814 Alternatively, you can set the
815 <filename>DEPLOY_DIR_IMAGE</filename> variable in the
816 external environment.</para></listitem>
817 <listitem><para>
818 When buildhistory is enabled, its output is now written
819 under the
820 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
821 rather than
822 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>.
823 Doing so makes it easier to delete
824 <filename>TMPDIR</filename> and preserve the build history.
825 Additionally, data for produced SDKs is now split by
826 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>.
827 </para></listitem>
828 <listitem><para>
829 The <filename>pkgdata</filename> directory produced as
830 part of the packaging process has been collapsed into a
831 single machine-specific directory.
832 This directory is located under
833 <filename>sysroots</filename> and uses a machine-specific
834 name (i.e.
835 <filename>tmp/sysroots/&lt;machine&gt;/pkgdata</filename>).
836 </para></listitem>
837 </itemizedlist>
838 </para>
839 </section>
840
841 <section id='migration-1.5-shortened-git-srcrev-values'>
842 <title>Shortened Git <filename>SRCREV</filename> Values</title>
843
844 <para>
845 BitBake will now shorten revisions from Git repositories from the
846 normal 40 characters down to 10 characters within
847 <link linkend='var-SRCPV'><filename>SRCPV</filename></link>
848 for improved usability in path and file names.
849 This change should be safe within contexts where these revisions
850 are used because the chances of spatially close collisions
851 is very low.
852 Distant collisions are not a major issue in the way
853 the values are used.
854 </para>
855 </section>
856
857 <section id='migration-1.5-image-features'>
858 <title><filename>IMAGE_FEATURES</filename></title>
859
860 <para>
861 The following changes have been made that relate to
862 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
863 <itemizedlist>
864 <listitem><para>
865 The value of
866 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
867 is now validated to ensure invalid feature items are not
868 added.
869 Some users mistakenly add package names to this variable
870 instead of using
871 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
872 in order to have the package added to the image, which does
873 not work.
874 This change is intended to catch those kinds of situations.
875 Valid <filename>IMAGE_FEATURES</filename> are drawn from
876 <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
877 definitions,
878 <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link>
879 and a new "validitems" varflag on
880 <filename>IMAGE_FEATURES</filename>.
881 The "validitems" varflag change allows additional features
882 to be added if they are not provided using the previous
883 two mechanisms.
884 </para></listitem>
885 <listitem><para>
886 The previously deprecated "apps-console-core"
887 <filename>IMAGE_FEATURES</filename> item is no longer
888 supported.
889 Add "splash" to <filename>IMAGE_FEATURES</filename> if you
890 wish to have the splash screen enabled, since this is
891 all that apps-console-core was doing.</para></listitem>
892 </itemizedlist>
893 </para>
894 </section>
895
896 <section id='migration-1.5-run'>
897 <title><filename>/run</filename></title>
898
899 <para>
900 The <filename>/run</filename> directory from the Filesystem
901 Hierarchy Standard 3.0 has been introduced.
902 You can find some of the implications for this change
903 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873'>here</ulink>.
904 The change also means that recipes that install files to
905 <filename>/var/run</filename> must be changed.
906 You can find a guide on how to make these changes
907 <ulink url='http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530'>here</ulink>.
908 </para>
909 </section>
910
911 <section id='migration-1.5-removal-of-package-manager-database-within-image-recipes'>
912 <title>Removal of Package Manager Database Within Image Recipes</title>
913
914 <para>
915 The image <filename>core-image-minimal</filename> no longer adds
916 <filename>remove_packaging_data_files</filename> to
917 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
918 This addition is now handled automatically when "package-management"
919 is not in
920 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
921 If you have custom image recipes that make this addition,
922 you should remove the lines, as they are not needed and might
923 interfere with correct operation of postinstall scripts.
924 </para>
925 </section>
926
927 <section id='migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time'>
928 <title>Images Now Rebuild Only on Changes Instead of Every Time</title>
929
930 <para>
931 The
932 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
933 and other related image
934 construction tasks are no longer marked as "nostamp".
935 Consequently, they will only be re-executed when their inputs have
936 changed.
937 Previous versions of the OpenEmbedded build system always rebuilt
938 the image when requested rather when necessary.
939 </para>
940 </section>
941
942 <section id='migration-1.5-task-recipes'>
943 <title>Task Recipes</title>
944
945 <para>
946 The previously deprecated <filename>task.bbclass</filename> has
947 now been dropped.
948 For recipes that previously inherited from this class, you should
949 rename them from <filename>task-*</filename> to
950 <filename>packagegroup-*</filename> and inherit packagegroup
951 instead.
952 </para>
953
954 <para>
955 For more information, see the
956 "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>"
957 section.
958 </para>
959 </section>
960
961 <section id='migration-1.5-busybox'>
962 <title>BusyBox</title>
963
964 <para>
965 By default, we now split BusyBox into two binaries:
966 one that is suid root for those components that need it, and
967 another for the rest of the components.
968 Splitting BusyBox allows for optimization that eliminates the
969 <filename>tinylogin</filename> recipe as recommended by upstream.
970 You can disable this split by setting
971 <link linkend='var-BUSYBOX_SPLIT_SUID'><filename>BUSYBOX_SPLIT_SUID</filename></link>
972 to "0".
973 </para>
974 </section>
975
976 <section id='migration-1.5-automated-image-testing'>
977 <title>Automated Image Testing</title>
978
979 <para>
980 A new automated image testing framework has been added
981 through the
982 <link linkend='ref-classes-testimage'><filename>testimage*.bbclass</filename></link>
983 class.
984 This framework replaces the older
985 <filename>imagetest-qemu</filename> framework.
986 </para>
987
988 <para>
989 You can learn more about performing automated image tests in the
990 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
991 section.
992 </para>
993 </section>
994
995 <section id='migration-1.5-build-history'>
996 <title>Build History</title>
997
998 <para>
999 Following are changes to Build History:
1000 <itemizedlist>
1001 <listitem><para>
1002 Installed package sizes:
1003 <filename>installed-package-sizes.txt</filename> for an
1004 image now records the size of the files installed by each
1005 package instead of the size of each compressed package
1006 archive file.</para></listitem>
1007 <listitem><para>
1008 The dependency graphs (<filename>depends*.dot</filename>)
1009 now use the actual package names instead of replacing
1010 dashes, dots and plus signs with underscores.
1011 </para></listitem>
1012 <listitem><para>
1013 The <filename>buildhistory-diff</filename> and
1014 <filename>buildhistory-collect-srcrevs</filename>
1015 utilities have improved command-line handling.
1016 Use the <filename>&dash;&dash;help</filename> option for
1017 each utility for more information on the new syntax.
1018 </para></listitem>
1019 </itemizedlist>
1020 For more information on Build History, see the
1021 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
1022 section.
1023 </para>
1024 </section>
1025
1026 <section id='migration-1.5-udev'>
1027 <title><filename>udev</filename></title>
1028
1029 <para>
1030 Following are changes to <filename>udev</filename>:
1031 <itemizedlist>
1032 <listitem><para>
1033 <filename>udev</filename> no longer brings in
1034 <filename>udev-extraconf</filename> automatically
1035 through
1036 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1037 since this was originally intended to be optional.
1038 If you need the extra rules, then add
1039 <filename>udev-extraconf</filename> to your image.
1040 </para></listitem>
1041 <listitem><para>
1042 <filename>udev</filename> no longer brings in
1043 <filename>pciutils-ids</filename> or
1044 <filename>usbutils-ids</filename> through
1045 <filename>RRECOMMENDS</filename>.
1046 These are not needed by <filename>udev</filename> itself
1047 and removing them saves around 350KB.
1048 </para></listitem>
1049 </itemizedlist>
1050 </para>
1051 </section>
1052
1053 <section id='migration-1.5-removed-renamed-recipes'>
1054 <title>Removed and Renamed Recipes</title>
1055
1056 <itemizedlist>
1057 <listitem><para>
1058 The <filename>linux-yocto</filename> 3.2 kernel has been
1059 removed.</para></listitem>
1060 <listitem><para>
1061 <filename>libtool-nativesdk</filename> has been renamed to
1062 <filename>nativesdk-libtool</filename>.</para></listitem>
1063 <listitem><para>
1064 <filename>tinylogin</filename> has been removed.
1065 It has been replaced by a suid portion of Busybox.
1066 See the
1067 "<link linkend='migration-1.5-busybox'>BusyBox</link>" section
1068 for more information.</para></listitem>
1069 <listitem><para>
1070 <filename>external-python-tarball</filename> has been renamed
1071 to <filename>buildtools-tarball</filename>.
1072 </para></listitem>
1073 <listitem><para>
1074 <filename>web-webkit</filename> has been removed.
1075 It has been functionally replaced by
1076 <filename>midori</filename>.</para></listitem>
1077 <listitem><para>
1078 <filename>imake</filename> has been removed.
1079 It is no longer needed by any other recipe.
1080 </para></listitem>
1081 <listitem><para>
1082 <filename>transfig-native</filename> has been removed.
1083 It is no longer needed by any other recipe.
1084 </para></listitem>
1085 <listitem><para>
1086 <filename>anjuta-remote-run</filename> has been removed.
1087 Anjuta IDE integration has not been officially supported for
1088 several releases.</para></listitem>
1089 </itemizedlist>
1090 </section>
1091
1092 <section id='migration-1.5-other-changes'>
1093 <title>Other Changes</title>
1094
1095 <para>
1096 Following is a list of short entries describing other changes:
1097 <itemizedlist>
1098 <listitem><para>
1099 <filename>run-postinsts</filename>: Make this generic.
1100 </para></listitem>
1101 <listitem><para>
1102 <filename>base-files</filename>: Remove the unnecessary
1103 <filename>media/xxx</filename> directories.
1104 </para></listitem>
1105 <listitem><para>
1106 <filename>alsa-state</filename>: Provide an empty
1107 <filename>asound.conf</filename> by default.
1108 </para></listitem>
1109 <listitem><para>
1110 <filename>classes/image</filename>: Ensure
1111 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1112 supports pre-renamed package names.</para></listitem>
1113 <listitem><para>
1114 <filename>classes/rootfs_rpm</filename>: Implement
1115 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1116 for RPM.</para></listitem>
1117 <listitem><para>
1118 <filename>systemd</filename>: Remove
1119 <filename>systemd_unitdir</filename> if
1120 <filename>systemd</filename> is not in
1121 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1122 </para></listitem>
1123 <listitem><para>
1124 <filename>systemd</filename>: Remove
1125 <filename>init.d</filename> dir if
1126 <filename>systemd</filename> unit file is present and
1127 <filename>sysvinit</filename> is not a distro feature.
1128 </para></listitem>
1129 <listitem><para>
1130 <filename>libpam</filename>: Deny all services for the
1131 <filename>OTHER</filename> entries.
1132 </para></listitem>
1133 <listitem><para>
1134 <filename>image.bbclass</filename>: Move
1135 <filename>runtime_mapping_rename</filename> to avoid
1136 conflict with <filename>multilib</filename>.
1137 See
1138 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993'><filename>YOCTO #4993</filename></ulink>
1139 in Bugzilla for more information.
1140 </para></listitem>
1141 <listitem><para>
1142 <filename>linux-dtb</filename>: Use kernel build system
1143 to generate the <filename>dtb</filename> files.
1144 </para></listitem>
1145 <listitem><para>
1146 <filename>kern-tools</filename>: Switch from guilt to
1147 new <filename>kgit-s2q</filename> tool.
1148 </para></listitem>
1149 </itemizedlist>
1150 </para>
1151 </section>
1152</section>
1153
1154<section id='moving-to-the-yocto-project-1.6-release'>
1155 <title>Moving to the Yocto Project 1.6 Release</title>
1156
1157 <para>
1158 This section provides migration information for moving to the
1159 Yocto Project 1.6 Release from the prior release.
1160 </para>
1161
1162
1163 <section id='migration-1.6-archiver-class'>
1164 <title><filename>archiver</filename> Class</title>
1165
1166 <para>
1167 The
1168 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
1169 class has been rewritten and its configuration has been simplified.
1170 For more details on the source archiver, see the
1171 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
1172 section in the Yocto Project Development Manual.
1173 </para>
1174 </section>
1175
1176 <section id='migration-1.6-packaging-changes'>
1177 <title>Packaging Changes</title>
1178
1179 <para>
1180 The following packaging changes have been made:
1181 <itemizedlist>
1182 <listitem><para>
1183 The <filename>binutils</filename> recipe no longer produces
1184 a <filename>binutils-symlinks</filename> package.
1185 <filename>update-alternatives</filename> is now used to
1186 handle the preferred <filename>binutils</filename>
1187 variant on the target instead.
1188 </para></listitem>
1189 <listitem><para>
1190 The tc (traffic control) utilities have been split out of
1191 the main <filename>iproute2</filename> package and put
1192 into the <filename>iproute2-tc</filename> package.
1193 </para></listitem>
1194 <listitem><para>
1195 The <filename>gtk-engines</filename> schemas have been
1196 moved to a dedicated
1197 <filename>gtk-engines-schemas</filename> package.
1198 </para></listitem>
1199 <listitem><para>
1200 The <filename>armv7a</filename> with thumb package
1201 architecture suffix has changed.
1202 The suffix for these packages with the thumb
1203 optimization enabled is "t2" as it should be.
1204 Use of this suffix was not the case in the 1.5 release.
1205 Architecture names will change within package feeds as a
1206 result.
1207 </para></listitem>
1208 </itemizedlist>
1209 </para>
1210 </section>
1211
1212 <section id='migration-1.6-bitbake'>
1213 <title>BitBake</title>
1214
1215 <para>
1216 The following changes have been made to
1217 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
1218 </para>
1219
1220 <section id='migration-1.6-matching-branch-requirement-for-git-fetching'>
1221 <title>Matching Branch Requirement for Git Fetching</title>
1222
1223 <para>
1224 When fetching source from a Git repository using
1225 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
1226 BitBake will now validate the
1227 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
1228 value against the branch.
1229 You can specify the branch using the following form:
1230 <literallayout class='monospaced'>
1231 SRC_URI = "git://server.name/repository;branch=&lt;branchname&gt;"
1232 </literallayout>
1233 If you do not specify a branch, BitBake looks
1234 in the default "master" branch.
1235 </para>
1236
1237 <para>
1238 Alternatively, if you need to bypass this check (e.g.
1239 if you are fetching a revision corresponding to a tag that
1240 is not on any branch), you can add ";nobranch=1" to
1241 the end of the URL within <filename>SRC_URI</filename>.
1242 </para>
1243 </section>
1244
1245 <section id='migration-1.6-bitbake-deps'>
1246 <title>Python Definition substitutions</title>
1247
1248 <para>
1249 BitBake had some previously deprecated Python definitions
1250 within its <filename>bb</filename> module removed.
1251 You should use their sub-module counterparts instead:
1252 <itemizedlist>
1253 <listitem><para><filename>bb.MalformedUrl</filename>:
1254 Use <filename>bb.fetch.MalformedUrl</filename>.
1255 </para></listitem>
1256 <listitem><para><filename>bb.fetch.encodeurl</filename>:
1257 Use <filename>bb.fetch.encodeurl</filename>.
1258 </para></listitem>
1259 <listitem><para><filename>bb.decodeurl</filename>:
1260 Use <filename>bb.fetch.decodeurl</filename>
1261 </para></listitem>
1262 <listitem><para><filename>bb.mkdirhier</filename>:
1263 Use <filename>bb.utils.mkdirhier</filename>.
1264 </para></listitem>
1265 <listitem><para><filename>bb.movefile</filename>:
1266 Use <filename>bb.utils.movefile</filename>.
1267 </para></listitem>
1268 <listitem><para><filename>bb.copyfile</filename>:
1269 Use <filename>bb.utils.copyfile</filename>.
1270 </para></listitem>
1271 <listitem><para><filename>bb.which</filename>:
1272 Use <filename>bb.utils.which</filename>.
1273 </para></listitem>
1274 <listitem><para><filename>bb.vercmp_string</filename>:
1275 Use <filename>bb.utils.vercmp_string</filename>.
1276 </para></listitem>
1277 <listitem><para><filename>bb.vercmp</filename>:
1278 Use <filename>bb.utils.vercmp</filename>.
1279 </para></listitem>
1280 </itemizedlist>
1281 </para>
1282 </section>
1283
1284 <section id='migration-1.6-bitbake-fetcher'>
1285 <title>SVK Fetcher</title>
1286
1287 <para>
1288 The SVK fetcher has been removed from BitBake.
1289 </para>
1290 </section>
1291
1292 <section id='migration-1.6-bitbake-console-output'>
1293 <title>Console Output Error Redirection</title>
1294
1295 <para>
1296 The BitBake console UI will now output errors to
1297 <filename>stderr</filename> instead of
1298 <filename>stdout</filename>.
1299 Consequently, if you are piping or redirecting the output of
1300 <filename>bitbake</filename> to somewhere else, and you wish
1301 to retain the errors, you will need to add
1302 <filename>2>&amp;1</filename> (or something similar) to the
1303 end of your <filename>bitbake</filename> command line.
1304 </para>
1305 </section>
1306
1307 <section id='migration-1.6-task-taskname-overrides'>
1308 <title><filename>task-&lt;taskname&gt;</filename> Overrides</title>
1309
1310 <para>
1311 <filename>task-&lt;taskname&gt;</filename> overrides have been
1312 adjusted so that tasks whose names contain underscores have the
1313 underscores replaced by hyphens for the override so that they
1314 now function properly.
1315 For example, the task override for
1316 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
1317 is <filename>task-populate-sdk</filename>.
1318 </para>
1319 </section>
1320 </section>
1321
1322 <section id='migration-1.6-variable-changes'>
1323 <title>Changes to Variables</title>
1324
1325 <para>
1326 The following variables have changed.
1327 For information on the OpenEmbedded build system variables, see the
1328 "<link linkend='ref-variables-glos'>Variables Glossary</link>" Chapter.
1329 </para>
1330
1331 <section id='migration-1.6-variable-changes-TMPDIR'>
1332 <title><filename>TMPDIR</filename></title>
1333
1334 <para>
1335 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1336 can no longer be on an NFS mount.
1337 NFS does not offer full POSIX locking and inode consistency
1338 and can cause unexpected issues if used to store
1339 <filename>TMPDIR</filename>.
1340 </para>
1341
1342 <para>
1343 The check for this occurs on startup.
1344 If <filename>TMPDIR</filename> is detected on an NFS mount,
1345 an error occurs.
1346 </para>
1347 </section>
1348
1349 <section id='migration-1.6-variable-changes-PRINC'>
1350 <title><filename>PRINC</filename></title>
1351
1352 <para>
1353 The
1354 <link linkend='var-PRINC'><filename>PRINC</filename></link>
1355 variable has been deprecated and triggers a warning if
1356 detected during a build.
1357 For
1358 <link linkend='var-PR'><filename>PR</filename></link>
1359 increments on changes, use the PR service instead.
1360 You can find out more about this service in the
1361 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
1362 section in the Yocto Project Development Manual.
1363 </para>
1364 </section>
1365
1366 <section id='migration-1.6-variable-changes-IMAGE_TYPES'>
1367 <title><filename>IMAGE_TYPES</filename></title>
1368
1369 <para>
1370 The "sum.jffs2" option for
1371 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>
1372 has been replaced by the "jffs2.sum" option, which fits the
1373 processing order.
1374 </para>
1375 </section>
1376
1377 <section id='migration-1.6-variable-changes-COPY_LIC_MANIFEST'>
1378 <title><filename>COPY_LIC_MANIFEST</filename></title>
1379
1380 <para>
1381 The
1382 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1383 variable must
1384 now be set to "1" rather than any value in order to enable
1385 it.
1386 </para>
1387 </section>
1388
1389 <section id='migration-1.6-variable-changes-COPY_LIC_DIRS'>
1390 <title><filename>COPY_LIC_DIRS</filename></title>
1391
1392 <para>
1393 The
1394 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
1395 variable must
1396 now be set to "1" rather than any value in order to enable
1397 it.
1398 </para>
1399 </section>
1400
1401 <section id='migration-1.6-variable-changes-PACKAGE_GROUP'>
1402 <title><filename>PACKAGE_GROUP</filename></title>
1403
1404 <para>
1405 The
1406 <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
1407 variable has been renamed to
1408 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>
1409 to more accurately reflect its purpose.
1410 You can still use <filename>PACKAGE_GROUP</filename> but
1411 the OpenEmbedded build system produces a warning message when
1412 it encounters the variable.
1413 </para>
1414 </section>
1415 </section>
1416
1417 <section id='migration-1.6-directory-layout-changes'>
1418 <title>Directory Layout Changes</title>
1419
1420 <para>
1421 The <filename>meta-hob</filename> layer has been removed from
1422 the top-level of the
1423 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1424 The contents of this layer are no longer needed by the Hob
1425 user interface for building images and toolchains.
1426 </para>
1427 </section>
1428
1429 <section id='migration-1.6-package-test-ptest'>
1430 <title>Package Test (ptest)</title>
1431
1432 <para>
1433 Package Tests (ptest) are built but not installed by default.
1434 For information on using Package Tests, see the
1435 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Setting up and running package test (ptest)</ulink>"
1436 section in the Yocto Project Development Manual.
1437 For information on the <filename>ptest</filename> class, see the
1438 "<link linkend='ref-classes-ptest'><filename>ptest.bbclass</filename></link>"
1439 section.
1440 </para>
1441 </section>
1442
1443 <section id='migration-1.6-build-changes'>
1444 <title>Build Changes</title>
1445
1446 <para>
1447 Separate build and source directories have been enabled
1448 by default for selected recipes where it is known to work
1449 (a whitelist) and for all recipes that inherit the
1450 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
1451 class.
1452 In future releases the
1453 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
1454 class will enable a separate build directory by default as
1455 well.
1456 Recipes building Autotools-based
1457 software that fails to build with a separate build directory
1458 should be changed to inherit from the
1459 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
1460 class instead of the <filename>autotools</filename> class.
1461 </para>
1462 </section>
1463
1464 <section id='migration-1.6-building-qemu-native'>
1465 <title><filename>qemu-native</filename></title>
1466
1467 <para>
1468 <filename>qemu-native</filename> now builds without
1469 SDL-based graphical output support by default.
1470 The following additional lines are needed in your
1471 <filename>local.conf</filename> to enable it:
1472 <literallayout class='monospaced'>
1473 PACKAGECONFIG_pn-qemu-native = "sdl"
1474 ASSUME_PROVIDED += "libsdl-native"
1475 </literallayout>
1476 <note>
1477 The default <filename>local.conf</filename>
1478 contains these statements.
1479 Consequently, if you are building a headless system and using
1480 a default <filename>local.conf</filename> file, you will need
1481 comment these two lines out.
1482 </note>
1483 </para>
1484 </section>
1485
1486 <section id='migration-1.6-core-image-basic'>
1487 <title><filename>core-image-basic</filename></title>
1488
1489 <para>
1490 <filename>core-image-basic</filename> has been renamed to
1491 <filename>core-image-full-cmdline</filename>.
1492 </para>
1493
1494 <para>
1495 In addition to <filename>core-image-basic</filename> being renamed,
1496 <filename>packagegroup-core-basic</filename> has been renamed to
1497 <filename>packagegroup-core-full-cmdline</filename> to match.
1498 </para>
1499 </section>
1500
1501 <section id='migration-1.6-licensing'>
1502 <title>Licensing</title>
1503
1504 <para>
1505 The top-level <filename>LICENSE</filename> file has been changed
1506 to better describe the license of the various components of
1507 OE-Core.
1508 However, the licensing itself remains unchanged.
1509 </para>
1510
1511 <para>
1512 Normally, this change would not cause any side-effects.
1513 However, some recipes point to this file within
1514 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
1515 (as <filename>${COREBASE}/LICENSE</filename>) and thus the
1516 accompanying checksum must be changed from
1517 3f40d7994397109285ec7b81fdeb3b58 to
1518 4d92cd373abda3937c2bc47fbc49d690.
1519 A better alternative is to have
1520 <filename>LIC_FILES_CHKSUM</filename> point to a file
1521 describing the license that is distributed with the source
1522 that the recipe is building, if possible, rather than pointing
1523 to <filename>${COREBASE}/LICENSE</filename>.
1524 </para>
1525 </section>
1526
1527 <section id='migration-1.6-cflags-options'>
1528 <title><filename>CFLAGS</filename> Options</title>
1529
1530 <para>
1531 The "-fpermissive" option has been removed from the default
1532 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1533 value.
1534 You need to take action on individual recipes that fail when
1535 building with this option.
1536 You need to either patch the recipes to fix the issues reported by
1537 the compiler, or you need to add "-fpermissive" to
1538 <filename>CFLAGS</filename> in the recipes.
1539 </para>
1540 </section>
1541
1542 <section id='migration-1.6-custom-images'>
1543 <title>Custom Image Output Types</title>
1544
1545 <para>
1546 Custom image output types, as selected using
1547 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
1548 must declare their dependencies on other image types (if any) using
1549 a new
1550 <link linkend='var-IMAGE_TYPEDEP'><filename>IMAGE_TYPEDEP</filename></link>
1551 variable.
1552 </para>
1553 </section>
1554
1555 <section id='migration-1.6-do-package-write-task'>
1556 <title>Tasks</title>
1557
1558 <para>
1559 The <filename>do_package_write</filename> task has been removed.
1560 The task is no longer needed.
1561 </para>
1562 </section>
1563
1564 <section id='migration-1.6-update-alternatives-provider'>
1565 <title><filename>update-alternative</filename> Provider</title>
1566
1567 <para>
1568 The default <filename>update-alternatives</filename> provider has
1569 been changed from <filename>opkg</filename> to
1570 <filename>opkg-utils</filename>.
1571 This change resolves some troublesome circular dependencies.
1572 The runtime package has also been renamed from
1573 <filename>update-alternatives-cworth</filename>
1574 to <filename>update-alternatives-opkg</filename>.
1575 </para>
1576 </section>
1577
1578 <section id='migration-1.6-virtclass-overrides'>
1579 <title><filename>virtclass</filename> Overrides</title>
1580
1581 <para>
1582 The <filename>virtclass</filename> overrides are now deprecated.
1583 Use the equivalent class overrides instead (e.g.
1584 <filename>virtclass-native</filename> becomes
1585 <filename>class-native</filename>.)
1586 </para>
1587 </section>
1588
1589 <section id='migration-1.6-removed-renamed-recipes'>
1590 <title>Removed and Renamed Recipes</title>
1591
1592 <para>
1593 The following recipes have been removed:
1594 <itemizedlist>
1595 <listitem><para><filename>packagegroup-toolset-native</filename> -
1596 This recipe is largely unused.
1597 </para></listitem>
1598 <listitem><para><filename>linux-yocto-3.8</filename> -
1599 Support for the Linux yocto 3.8 kernel has been dropped.
1600 Support for the 3.10 and 3.14 kernels have been added
1601 with the <filename>linux-yocto-3.10</filename> and
1602 <filename>linux-yocto-3.14</filename> recipes.
1603 </para></listitem>
1604 <listitem><para><filename>ocf-linux</filename> -
1605 This recipe has been functionally replaced using
1606 <filename>cryptodev-linux</filename>.
1607 </para></listitem>
1608 <listitem><para><filename>genext2fs</filename> -
1609 <filename>genext2fs</filename> is no longer used by the
1610 build system and is unmaintained upstream.
1611 </para></listitem>
1612 <listitem><para><filename>js</filename> -
1613 This provided an ancient version of Mozilla's javascript
1614 engine that is no longer needed.
1615 </para></listitem>
1616 <listitem><para><filename>zaurusd</filename> -
1617 The recipe has been moved to the
1618 <filename>meta-handheld</filename> layer.
1619 </para></listitem>
1620 <listitem><para><filename>eglibc 2.17</filename> -
1621 Replaced by the <filename>eglibc 2.19</filename>
1622 recipe.
1623 </para></listitem>
1624 <listitem><para><filename>gcc 4.7.2</filename> -
1625 Replaced by the now stable
1626 <filename>gcc 4.8.2</filename>.
1627 </para></listitem>
1628 <listitem><para><filename>external-sourcery-toolchain</filename> -
1629 this recipe is now maintained in the
1630 <filename>meta-sourcery</filename> layer.
1631 </para></listitem>
1632 <listitem><para><filename>linux-libc-headers-yocto 3.4+git</filename> -
1633 Now using version 3.10 of the
1634 <filename>linux-libc-headers</filename> by default.
1635 </para></listitem>
1636 <listitem><para><filename>meta-toolchain-gmae</filename> -
1637 This recipe is obsolete.
1638 </para></listitem>
1639 <listitem><para><filename>packagegroup-core-sdk-gmae</filename> -
1640 This recipe is obsolete.
1641 </para></listitem>
1642 <listitem><para><filename>packagegroup-core-standalone-gmae-sdk-target</filename> -
1643 This recipe is obsolete.
1644 </para></listitem>
1645 </itemizedlist>
1646 </para>
1647 </section>
1648
1649 <section id='migration-1.6-removed-classes'>
1650 <title>Removed Classes</title>
1651
1652 <para>
1653 The following classes have become obsolete and have been removed:
1654 <itemizedlist>
1655 <listitem><para><filename>module_strip</filename>
1656 </para></listitem>
1657 <listitem><para><filename>pkg_metainfo</filename>
1658 </para></listitem>
1659 <listitem><para><filename>pkg_distribute</filename>
1660 </para></listitem>
1661 <listitem><para><filename>image-empty</filename>
1662 </para></listitem>
1663 </itemizedlist>
1664 </para>
1665 </section>
1666
1667 <section id='migration-1.6-reference-bsps'>
1668 <title>Reference Board Support Packages (BSPs)</title>
1669
1670 <para>
1671 The following reference BSPs changes occurred:
1672 <itemizedlist>
1673 <listitem><para>The BeagleBoard
1674 (<filename>beagleboard</filename>) ARM reference hardware
1675 has been replaced by the BeagleBone
1676 (<filename>beaglebone</filename>) hardware.
1677 </para></listitem>
1678 <listitem><para>The RouterStation Pro
1679 (<filename>routerstationpro</filename>) MIPS reference
1680 hardware has been replaced by the EdgeRouter Lite
1681 (<filename>edgerouter</filename>) hardware.
1682 </para></listitem>
1683 </itemizedlist>
1684 The previous reference BSPs for the
1685 <filename>beagleboard</filename> and
1686 <filename>routerstationpro</filename> machines are still available
1687 in a new <filename>meta-yocto-bsp-old</filename> layer in the
1688 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
1689 at
1690 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/'>http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/</ulink>.
1691 </para>
1692 </section>
1693</section>
1694</chapter>
1695<!--
1696vim: expandtab tw=80 ts=4
1697-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-13 03:38:37 +0000