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.xml7301
1 files changed, 0 insertions, 7301 deletions
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
deleted file mode 100644
index d3d5b16bdd..0000000000
--- a/documentation/ref-manual/migration.xml
+++ /dev/null
@@ -1,7301 +0,0 @@
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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='migration'>
7<title>Migrating to a Newer Yocto Project Release</title>
8
9 <para>
10 This chapter provides information you can use to migrate work to a
11 newer Yocto Project release. You can find the same information in the
12 release notes for a given release.
13 </para>
14
15<section id='general-migration-considerations'>
16 <title>General Migration Considerations</title>
17
18 <para>
19 Some considerations are not tied to a specific Yocto Project
20 release.
21 This section presents information you should consider when
22 migrating to any new Yocto Project release.
23 <itemizedlist>
24 <listitem><para><emphasis>Dealing with Customized Recipes</emphasis>:
25 Issues could arise if you take older recipes that contain
26 customizations and simply copy them forward expecting them
27 to work after you migrate to new Yocto Project metadata.
28 For example, suppose you have a recipe in your layer that is
29 a customized version of a core recipe copied from the earlier
30 release, rather than through the use of an append file.
31 When you migrate to a newer version of Yocto Project, the
32 metadata (e.g. perhaps an include file used by the recipe)
33 could have changed in a way that would break the build.
34 Say, for example, a function is removed from an include file
35 and the customized recipe tries to call that function.
36 </para>
37
38 <para>You could "forward-port" all your customizations in your
39 recipe so that everything works for the new release.
40 However, this is not the optimal solution as you would have
41 to repeat this process with each new release if changes
42 occur that give rise to problems.</para>
43
44 <para>The better solution (where practical) is to use append
45 files (<filename>*.bbappend</filename>) to capture any
46 customizations you want to make to a recipe.
47 Doing so, isolates your changes from the main recipe making
48 them much more manageable.
49 However, sometimes it is not practical to use an append
50 file.
51 A good example of this is when introducing a newer or older
52 version of a recipe in another layer.</para>
53 </listitem>
54 <listitem><para><emphasis>Updating Append Files</emphasis>:
55 Since append files generally only contain your customizations,
56 they often do not need to be adjusted for new releases.
57 However, if the <filename>.bbappend</filename> file is
58 specific to a particular version of the recipe (i.e. its
59 name does not use the % wildcard) and the version of the
60 recipe to which it is appending has changed, then you will
61 at a minimum need to rename the append file to match the
62 name of the recipe file.
63 A mismatch between an append file and its corresponding
64 recipe file (<filename>.bb</filename>) will
65 trigger an error during parsing.</para>
66 <para>Depending on the type of customization the append file
67 applies, other incompatibilities might occur when you
68 upgrade.
69 For example, if your append file applies a patch and the
70 recipe to which it is appending is updated to a newer
71 version, the patch might no longer apply.
72 If this is the case and assuming the patch is still needed,
73 you must modify the patch file so that it does apply.
74 </para></listitem>
75 </itemizedlist>
76 </para>
77</section>
78
79<section id='moving-to-the-yocto-project-1.3-release'>
80 <title>Moving to the Yocto Project 1.3 Release</title>
81
82 <para>
83 This section provides migration information for moving to the
84 Yocto Project 1.3 Release from the prior release.
85 </para>
86
87 <section id='1.3-local-configuration'>
88 <title>Local Configuration</title>
89
90 <para>
91 Differences include changes for
92 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
93 and <filename>bblayers.conf</filename>.
94 </para>
95
96 <section id='migration-1.3-sstate-mirrors'>
97 <title>SSTATE_MIRRORS</title>
98
99 <para>
100 The shared state cache (sstate-cache), as pointed to by
101 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
102 by default now has two-character subdirectories to prevent
103 issues arising from too many files in the same directory.
104 Also, native sstate-cache packages, which are built to run
105 on the host system, will go into a subdirectory named using
106 the distro ID string.
107 If you copy the newly structured sstate-cache to a mirror
108 location (either local or remote) and then point to it in
109 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
110 you need to append "PATH" to the end of the mirror URL so that
111 the path used by BitBake before the mirror substitution is
112 appended to the path used to access the mirror.
113 Here is an example:
114 <literallayout class='monospaced'>
115 SSTATE_MIRRORS = "file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH"
116 </literallayout>
117 </para>
118 </section>
119
120 <section id='migration-1.3-bblayers-conf'>
121 <title>bblayers.conf</title>
122
123 <para>
124 The <filename>meta-yocto</filename> layer consists of two parts
125 that correspond to the Poky reference distribution and the
126 reference hardware Board Support Packages (BSPs), respectively:
127 <filename>meta-yocto</filename> and
128 <filename>meta-yocto-bsp</filename>.
129 When running BitBake for the first time after upgrading,
130 your <filename>conf/bblayers.conf</filename> file will be
131 updated to handle this change and you will be asked to
132 re-run or restart for the changes to take effect.
133 </para>
134 </section>
135 </section>
136
137 <section id='1.3-recipes'>
138 <title>Recipes</title>
139
140 <para>
141 Differences include changes for the following:
142 <itemizedlist>
143 <listitem><para>Python function whitespace</para></listitem>
144 <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem>
145 <listitem><para><filename>nativesdk</filename></para></listitem>
146 <listitem><para>Task recipes</para></listitem>
147 <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem>
148 <listitem><para>Removed recipes</para></listitem>
149 </itemizedlist>
150 </para>
151
152 <section id='migration-1.3-python-function-whitespace'>
153 <title>Python Function Whitespace</title>
154
155 <para>
156 All Python functions must now use four spaces for indentation.
157 Previously, an inconsistent mix of spaces and tabs existed,
158 which made extending these functions using
159 <filename>_append</filename> or <filename>_prepend</filename>
160 complicated given that Python treats whitespace as
161 syntactically significant.
162 If you are defining or extending any Python functions (e.g.
163 <filename>populate_packages</filename>, <filename>do_unpack</filename>,
164 <filename>do_patch</filename> and so forth) in custom recipes
165 or classes, you need to ensure you are using consistent
166 four-space indentation.
167 </para>
168 </section>
169
170 <section id='migration-1.3-proto=-in-src-uri'>
171 <title>proto= in SRC_URI</title>
172
173 <para>
174 Any use of <filename>proto=</filename> in
175 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
176 needs to be changed to <filename>protocol=</filename>.
177 In particular, this applies to the following URIs:
178 <itemizedlist>
179 <listitem><para><filename>svn://</filename></para></listitem>
180 <listitem><para><filename>bzr://</filename></para></listitem>
181 <listitem><para><filename>hg://</filename></para></listitem>
182 <listitem><para><filename>osc://</filename></para></listitem>
183 </itemizedlist>
184 Other URIs were already using <filename>protocol=</filename>.
185 This change improves consistency.
186 </para>
187 </section>
188
189 <section id='migration-1.3-nativesdk'>
190 <title>nativesdk</title>
191
192 <para>
193 The suffix <filename>nativesdk</filename> is now implemented
194 as a prefix, which simplifies a lot of the packaging code for
195 <filename>nativesdk</filename> recipes.
196 All custom <filename>nativesdk</filename> recipes, which are
197 relocatable packages that are native to
198 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
199 and any references need to be updated to use
200 <filename>nativesdk-*</filename> instead of
201 <filename>*-nativesdk</filename>.
202 </para>
203 </section>
204
205 <section id='migration-1.3-task-recipes'>
206 <title>Task Recipes</title>
207
208 <para>
209 "Task" recipes are now known as "Package groups" and have
210 been renamed from <filename>task-*.bb</filename> to
211 <filename>packagegroup-*.bb</filename>.
212 Existing references to the previous <filename>task-*</filename>
213 names should work in most cases as there is an automatic
214 upgrade path for most packages.
215 However, you should update references in your own recipes and
216 configurations as they could be removed in future releases.
217 You should also rename any custom <filename>task-*</filename>
218 recipes to <filename>packagegroup-*</filename>, and change
219 them to inherit <filename>packagegroup</filename> instead of
220 <filename>task</filename>, as well as taking the opportunity
221 to remove anything now handled by
222 <filename>packagegroup.bbclass</filename>, such as providing
223 <filename>-dev</filename> and <filename>-dbg</filename>
224 packages, setting
225 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
226 and so forth.
227 See the
228 "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>"
229 section for further details.
230 </para>
231 </section>
232
233 <section id='migration-1.3-image-features'>
234 <title>IMAGE_FEATURES</title>
235
236 <para>
237 Image recipes that previously included "apps-console-core"
238 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
239 should now include "splash" instead to enable the boot-up
240 splash screen.
241 Retaining "apps-console-core" will still include the splash
242 screen but generates a warning.
243 The "apps-x11-core" and "apps-x11-games"
244 <filename>IMAGE_FEATURES</filename> features have been removed.
245 </para>
246 </section>
247
248 <section id='migration-1.3-removed-recipes'>
249 <title>Removed Recipes</title>
250
251 <para>
252 The following recipes have been removed.
253 For most of them, it is unlikely that you would have any
254 references to them in your own
255 <link linkend='metadata'>Metadata</link>.
256 However, you should check your metadata against this list to be sure:
257 <itemizedlist>
258 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
259 Replaced by <filename>libx11</filename>, which has a negligible
260 size difference with modern Xorg.</para></listitem>
261 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
262 Use <filename>xserver-xorg</filename>, which has a negligible
263 size difference when DRI and GLX modules are not installed.</para></listitem>
264 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
265 Effectively unmaintained for many years.</para></listitem>
266 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
267 No longer serves any purpose.</para></listitem>
268 <listitem><para><emphasis><filename>galago</filename></emphasis>:
269 Replaced by telepathy.</para></listitem>
270 <listitem><para><emphasis><filename>gail</filename></emphasis>:
271 Functionality was integrated into GTK+ 2.13.</para></listitem>
272 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
273 No longer needed.</para></listitem>
274 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
275 The build has been restructured to avoid the need for
276 this step.</para></listitem>
277 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
278 Unmaintained for many years.
279 Functionality now provided by
280 <filename>ofono</filename> instead.</para></listitem>
281 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
282 Largely unmaintained PIM application suite.
283 It has been moved to <filename>meta-gnome</filename>
284 in <filename>meta-openembedded</filename>.</para></listitem>
285 </itemizedlist>
286 In addition to the previously listed changes, the
287 <filename>meta-demoapps</filename> directory has also been removed
288 because the recipes in it were not being maintained and many
289 had become obsolete or broken.
290 Additionally, these recipes were not parsed in the default configuration.
291 Many of these recipes are already provided in an updated and
292 maintained form within the OpenEmbedded community layers such as
293 <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
294 For the remainder, you can now find them in the
295 <filename>meta-extras</filename> repository, which is in the
296 Yocto Project
297 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>.
298 </para>
299 </section>
300 </section>
301
302 <section id='1.3-linux-kernel-naming'>
303 <title>Linux Kernel Naming</title>
304
305 <para>
306 The naming scheme for kernel output binaries has been changed to
307 now include
308 <link linkend='var-PE'><filename>PE</filename></link> as part of the
309 filename:
310 <literallayout class='monospaced'>
311 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
312 </literallayout>
313 </para>
314
315 <para>
316 Because the <filename>PE</filename> variable is not set by default,
317 these binary files could result with names that include two dash
318 characters.
319 Here is an example:
320 <literallayout class='monospaced'>
321 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
322 </literallayout>
323 </para>
324 </section>
325</section>
326
327<section id='moving-to-the-yocto-project-1.4-release'>
328 <title>Moving to the Yocto Project 1.4 Release</title>
329
330 <para>
331 This section provides migration information for moving to the
332 Yocto Project 1.4 Release from the prior release.
333 </para>
334
335 <section id='migration-1.4-bitbake'>
336 <title>BitBake</title>
337
338 <para>
339 Differences include the following:
340 <itemizedlist>
341 <listitem><para><emphasis>Comment Continuation:</emphasis>
342 If a comment ends with a line continuation (\) character,
343 then the next line must also be a comment.
344 Any instance where this is not the case, now triggers
345 a warning.
346 You must either remove the continuation character, or be
347 sure the next line is a comment.
348 </para></listitem>
349 <listitem><para><emphasis>Package Name Overrides:</emphasis>
350 The runtime package specific variables
351 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
352 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
353 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
354 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
355 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
356 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
357 <link linkend='var-FILES'><filename>FILES</filename></link>,
358 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
359 and the pre, post, install, and uninstall script functions
360 <filename>pkg_preinst</filename>,
361 <filename>pkg_postinst</filename>,
362 <filename>pkg_prerm</filename>, and
363 <filename>pkg_postrm</filename> should always have a
364 package name override.
365 For example, use <filename>RDEPENDS_${PN}</filename> for
366 the main package instead of <filename>RDEPENDS</filename>.
367 BitBake uses more strict checks when it parses recipes.
368 </para></listitem>
369 </itemizedlist>
370 </para>
371 </section>
372
373 <section id='migration-1.4-build-behavior'>
374 <title>Build Behavior</title>
375
376 <para>
377 Differences include the following:
378 <itemizedlist>
379 <listitem><para><emphasis>Shared State Code:</emphasis>
380 The shared state code has been optimized to avoid running
381 unnecessary tasks.
382 For example, the following no longer populates the target
383 sysroot since that is not necessary:
384 <literallayout class='monospaced'>
385 $ bitbake -c rootfs <replaceable>some-image</replaceable>
386 </literallayout>
387 Instead, the system just needs to extract the output
388 package contents, re-create the packages, and construct
389 the root filesystem.
390 This change is unlikely to cause any problems unless
391 you have missing declared dependencies.
392 </para></listitem>
393 <listitem><para><emphasis>Scanning Directory Names:</emphasis>
394 When scanning for files in
395 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
396 the build system now uses
397 <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
398 instead of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
399 for the directory names.
400 In general, the values previously in
401 <filename>OVERRIDES</filename> are now in
402 <filename>FILESOVERRIDES</filename> as well.
403 However, if you relied upon an additional value
404 you previously added to <filename>OVERRIDES</filename>,
405 you might now need to add it to
406 <filename>FILESOVERRIDES</filename> unless you are already
407 adding it through the
408 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>
409 or <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
410 variables, as appropriate.
411 For more related changes, see the
412 "<link linkend='migration-1.4-variables'>Variables</link>"
413 section.
414 </para></listitem>
415 </itemizedlist>
416 </para>
417 </section>
418
419
420 <section id='migration-1.4-proxies-and-fetching-source'>
421 <title>Proxies and Fetching Source</title>
422
423 <para>
424 A new <filename>oe-git-proxy</filename> script has been added to
425 replace previous methods of handling proxies and fetching source
426 from Git.
427 See the <filename>meta-yocto/conf/site.conf.sample</filename> file
428 for information on how to use this script.
429 </para>
430 </section>
431
432 <section id='migration-1.4-custom-interfaces-file-netbase-change'>
433 <title>Custom Interfaces File (netbase change)</title>
434
435 <para>
436 If you have created your own custom
437 <filename>etc/network/interfaces</filename> file by creating
438 an append file for the <filename>netbase</filename> recipe,
439 you now need to create an append file for the
440 <filename>init-ifupdown</filename> recipe instead, which you can
441 find in the
442 <link linkend='source-directory'>Source Directory</link>
443 at <filename>meta/recipes-core/init-ifupdown</filename>.
444 For information on how to use append files, see the
445 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
446 section in the Yocto Project Development Tasks Manual.
447 </para>
448 </section>
449
450 <section id='migration-1.4-remote-debugging'>
451 <title>Remote Debugging</title>
452
453 <para>
454 Support for remote debugging with the Eclipse IDE is now
455 separated into an image feature
456 (<filename>eclipse-debug</filename>) that corresponds to the
457 <filename>packagegroup-core-eclipse-debug</filename> package group.
458 Previously, the debugging feature was included through the
459 <filename>tools-debug</filename> image feature, which corresponds
460 to the <filename>packagegroup-core-tools-debug</filename>
461 package group.
462 </para>
463 </section>
464
465 <section id='migration-1.4-variables'>
466 <title>Variables</title>
467
468 <para>
469 The following variables have changed:
470 <itemizedlist>
471 <listitem><para><emphasis><filename>SANITY_TESTED_DISTROS</filename>:</emphasis>
472 This variable now uses a distribution ID, which is composed
473 of the host distributor ID followed by the release.
474 Previously,
475 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
476 was composed of the description field.
477 For example, "Ubuntu 12.10" becomes "Ubuntu-12.10".
478 You do not need to worry about this change if you are not
479 specifically setting this variable, or if you are
480 specifically setting it to "".
481 </para></listitem>
482 <listitem><para><emphasis><filename>SRC_URI</filename>:</emphasis>
483 The <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>,
484 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>,
485 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>,
486 and <filename>FILE_DIRNAME</filename> directories have been
487 dropped from the default value of the
488 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
489 variable, which is used as the search path for finding files
490 referred to in
491 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
492 If you have a recipe that relied upon these directories,
493 which would be unusual, then you will need to add the
494 appropriate paths within the recipe or, alternatively,
495 rearrange the files.
496 The most common locations are still covered by
497 <filename>${BP}</filename>, <filename>${BPN}</filename>,
498 and "files", which all remain in the default value of
499 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
500 </para></listitem>
501 </itemizedlist>
502 </para>
503 </section>
504
505 <section id='migration-target-package-management-with-rpm'>
506 <title>Target Package Management with RPM</title>
507
508 <para>
509 If runtime package management is enabled and the RPM backend
510 is selected, Smart is now installed for package download, dependency
511 resolution, and upgrades instead of Zypper.
512 For more information on how to use Smart, run the following command
513 on the target:
514 <literallayout class='monospaced'>
515 smart --help
516 </literallayout>
517 </para>
518 </section>
519
520 <section id='migration-1.4-recipes-moved'>
521 <title>Recipes Moved</title>
522
523 <para>
524 The following recipes were moved from their previous locations
525 because they are no longer used by anything in
526 the OpenEmbedded-Core:
527 <itemizedlist>
528 <listitem><para><emphasis><filename>clutter-box2d</filename>:</emphasis>
529 Now resides in the <filename>meta-oe</filename> layer.
530 </para></listitem>
531 <listitem><para><emphasis><filename>evolution-data-server</filename>:</emphasis>
532 Now resides in the <filename>meta-gnome</filename> layer.
533 </para></listitem>
534 <listitem><para><emphasis><filename>gthumb</filename>:</emphasis>
535 Now resides in the <filename>meta-gnome</filename> layer.
536 </para></listitem>
537 <listitem><para><emphasis><filename>gtkhtml2</filename>:</emphasis>
538 Now resides in the <filename>meta-oe</filename> layer.
539 </para></listitem>
540 <listitem><para><emphasis><filename>gupnp</filename>:</emphasis>
541 Now resides in the <filename>meta-multimedia</filename> layer.
542 </para></listitem>
543 <listitem><para><emphasis><filename>gypsy</filename>:</emphasis>
544 Now resides in the <filename>meta-oe</filename> layer.
545 </para></listitem>
546 <listitem><para><emphasis><filename>libcanberra</filename>:</emphasis>
547 Now resides in the <filename>meta-gnome</filename> layer.
548 </para></listitem>
549 <listitem><para><emphasis><filename>libgdata</filename>:</emphasis>
550 Now resides in the <filename>meta-gnome</filename> layer.
551 </para></listitem>
552 <listitem><para><emphasis><filename>libmusicbrainz</filename>:</emphasis>
553 Now resides in the <filename>meta-multimedia</filename> layer.
554 </para></listitem>
555 <listitem><para><emphasis><filename>metacity</filename>:</emphasis>
556 Now resides in the <filename>meta-gnome</filename> layer.
557 </para></listitem>
558 <listitem><para><emphasis><filename>polkit</filename>:</emphasis>
559 Now resides in the <filename>meta-oe</filename> layer.
560 </para></listitem>
561 <listitem><para><emphasis><filename>zeroconf</filename>:</emphasis>
562 Now resides in the <filename>meta-networking</filename> layer.
563 </para></listitem>
564 </itemizedlist>
565 </para>
566 </section>
567
568 <section id='migration-1.4-removals-and-renames'>
569 <title>Removals and Renames</title>
570
571 <para>
572 The following list shows what has been removed or renamed:
573 <itemizedlist>
574 <listitem><para><emphasis><filename>evieext</filename>:</emphasis>
575 Removed because it has been removed from
576 <filename>xserver</filename> since 2008.
577 </para></listitem>
578 <listitem><para><emphasis>Gtk+ DirectFB:</emphasis>
579 Removed support because upstream Gtk+ no longer supports it
580 as of version 2.18.
581 </para></listitem>
582 <listitem><para><emphasis><filename>libxfontcache / xfontcacheproto</filename>:</emphasis>
583 Removed because they were removed from the Xorg server in 2008.
584 </para></listitem>
585 <listitem><para><emphasis><filename>libxp / libxprintapputil / libxprintutil / printproto</filename>:</emphasis>
586 Removed because the XPrint server was removed from
587 Xorg in 2008.
588 </para></listitem>
589 <listitem><para><emphasis><filename>libxtrap / xtrapproto</filename>:</emphasis>
590 Removed because their functionality was broken upstream.
591 </para></listitem>
592 <listitem><para><emphasis>linux-yocto 3.0 kernel:</emphasis>
593 Removed with linux-yocto 3.8 kernel being added.
594 The linux-yocto 3.2 and linux-yocto 3.4 kernels remain
595 as part of the release.
596 </para></listitem>
597 <listitem><para><emphasis><filename>lsbsetup</filename>:</emphasis>
598 Removed with functionality now provided by
599 <filename>lsbtest</filename>.
600 </para></listitem>
601 <listitem><para><emphasis><filename>matchbox-stroke</filename>:</emphasis>
602 Removed because it was never more than a proof-of-concept.
603 </para></listitem>
604 <listitem><para><emphasis><filename>matchbox-wm-2 / matchbox-theme-sato-2</filename>:</emphasis>
605 Removed because they are not maintained.
606 However, <filename>matchbox-wm</filename> and
607 <filename>matchbox-theme-sato</filename> are still
608 provided.
609 </para></listitem>
610 <listitem><para><emphasis><filename>mesa-dri</filename>:</emphasis>
611 Renamed to <filename>mesa</filename>.
612 </para></listitem>
613 <listitem><para><emphasis><filename>mesa-xlib</filename>:</emphasis>
614 Removed because it was no longer useful.
615 </para></listitem>
616 <listitem><para><emphasis><filename>mutter</filename>:</emphasis>
617 Removed because nothing ever uses it and the recipe is
618 very old.
619 </para></listitem>
620 <listitem><para><emphasis><filename>orinoco-conf</filename>:</emphasis>
621 Removed because it has become obsolete.
622 </para></listitem>
623 <listitem><para><emphasis><filename>update-modules</filename>:</emphasis>
624 Removed because it is no longer used.
625 The kernel module <filename>postinstall</filename> and
626 <filename>postrm</filename> scripts can now do the same
627 task without the use of this script.
628 </para></listitem>
629 <listitem><para><emphasis><filename>web</filename>:</emphasis>
630 Removed because it is not maintained. Superseded by
631 <filename>web-webkit</filename>.
632 </para></listitem>
633 <listitem><para><emphasis><filename>xf86bigfontproto</filename>:</emphasis>
634 Removed because upstream it has been disabled by default
635 since 2007.
636 Nothing uses <filename>xf86bigfontproto</filename>.
637 </para></listitem>
638 <listitem><para><emphasis><filename>xf86rushproto</filename>:</emphasis>
639 Removed because its dependency in
640 <filename>xserver</filename> was spurious and it was
641 removed in 2005.
642 </para></listitem>
643 <listitem><para><emphasis><filename>zypper / libzypp / sat-solver</filename>:</emphasis>
644 Removed and been functionally replaced with Smart
645 (<filename>python-smartpm</filename>) when RPM packaging
646 is used and package management is enabled on the target.
647 </para></listitem>
648 </itemizedlist>
649 </para>
650 </section>
651</section>
652
653<section id='moving-to-the-yocto-project-1.5-release'>
654 <title>Moving to the Yocto Project 1.5 Release</title>
655
656 <para>
657 This section provides migration information for moving to the
658 Yocto Project 1.5 Release from the prior release.
659 </para>
660
661 <section id='migration-1.5-host-dependency-changes'>
662 <title>Host Dependency Changes</title>
663
664 <para>
665 The OpenEmbedded build system now has some additional requirements
666 on the host system:
667 <itemizedlist>
668 <listitem><para>Python 2.7.3+</para></listitem>
669 <listitem><para>Tar 1.24+</para></listitem>
670 <listitem><para>Git 1.7.8+</para></listitem>
671 <listitem><para>Patched version of Make if you are using
672 3.82.
673 Most distributions that provide Make 3.82 use the patched
674 version.</para></listitem>
675 </itemizedlist>
676 If the Linux distribution you are using on your build host
677 does not provide packages for these, you can install and use
678 the Buildtools tarball, which provides an SDK-like environment
679 containing them.
680 </para>
681
682 <para>
683 For more information on this requirement, see the
684 "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>"
685 section.
686 </para>
687 </section>
688
689 <section id='migration-1.5-atom-pc-bsp'>
690 <title><filename>atom-pc</filename> Board Support Package (BSP)</title>
691
692 <para>
693 The <filename>atom-pc</filename> hardware reference BSP has been
694 replaced by a <filename>genericx86</filename> BSP.
695 This BSP is not necessarily guaranteed to work on all x86
696 hardware, but it will run on a wider range of systems than the
697 <filename>atom-pc</filename> did.
698 <note>
699 Additionally, a <filename>genericx86-64</filename> BSP has
700 been added for 64-bit Atom systems.
701 </note>
702 </para>
703 </section>
704
705 <section id='migration-1.5-bitbake'>
706 <title>BitBake</title>
707
708 <para>
709 The following changes have been made that relate to BitBake:
710 <itemizedlist>
711 <listitem><para>
712 BitBake now supports a <filename>_remove</filename>
713 operator.
714 The addition of this operator means you will have to
715 rename any items in recipe space (functions, variables)
716 whose names currently contain
717 <filename>_remove_</filename> or end with
718 <filename>_remove</filename> to avoid unexpected behavior.
719 </para></listitem>
720 <listitem><para>
721 BitBake's global method pool has been removed.
722 This method is not particularly useful and led to clashes
723 between recipes containing functions that had the
724 same name.</para></listitem>
725 <listitem><para>
726 The "none" server backend has been removed.
727 The "process" server backend has been serving well as the
728 default for a long time now.</para></listitem>
729 <listitem><para>
730 The <filename>bitbake-runtask</filename> script has been
731 removed.</para></listitem>
732 <listitem><para>
733 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>
734 and
735 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>
736 are no longer added to
737 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
738 by default in <filename>bitbake.conf</filename>.
739 These version-specific <filename>PROVIDES</filename>
740 items were seldom used.
741 Attempting to use them could result in two versions being
742 built simultaneously rather than just one version due to
743 the way BitBake resolves dependencies.</para></listitem>
744 </itemizedlist>
745 </para>
746 </section>
747
748 <section id='migration-1.5-qa-warnings'>
749 <title>QA Warnings</title>
750
751 <para>
752 The following changes have been made to the package QA checks:
753 <itemizedlist>
754 <listitem><para>
755 If you have customized
756 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
757 or <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link>
758 values in your configuration, check that they contain all of
759 the issues that you wish to be reported.
760 Previous Yocto Project versions contained a bug that meant
761 that any item not mentioned in <filename>ERROR_QA</filename>
762 or <filename>WARN_QA</filename> would be treated as a
763 warning.
764 Consequently, several important items were not already in
765 the default value of <filename>WARN_QA</filename>.
766 All of the possible QA checks are now documented in the
767 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
768 section.</para></listitem>
769 <listitem><para>
770 An additional QA check has been added to check if
771 <filename>/usr/share/info/dir</filename> is being installed.
772 Your recipe should delete this file within
773 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
774 if "make install" is installing it.
775 </para></listitem>
776 <listitem><para>
777 If you are using the buildhistory class, the check for the
778 package version going backwards is now controlled using a
779 standard QA check.
780 Thus, if you have customized your
781 <filename>ERROR_QA</filename> or
782 <filename>WARN_QA</filename> values and still wish to have
783 this check performed, you should add
784 "version-going-backwards" to your value for one or the
785 other variables depending on how you wish it to be handled.
786 See the documented QA checks in the
787 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
788 section.
789 </para></listitem>
790 </itemizedlist>
791 </para>
792 </section>
793
794 <section id='migration-1.5-directory-layout-changes'>
795 <title>Directory Layout Changes</title>
796
797 <para>
798 The following directory changes exist:
799 <itemizedlist>
800 <listitem><para>
801 Output SDK installer files are now named to include the
802 image name and tuning architecture through the
803 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
804 variable.</para></listitem>
805 <listitem><para>
806 Images and related files are now installed into a directory
807 that is specific to the machine, instead of a parent
808 directory containing output files for multiple machines.
809 The
810 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
811 variable continues to point to the directory containing
812 images for the current
813 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
814 and should be used anywhere there is a need to refer to
815 this directory.
816 The <filename>runqemu</filename> script now uses this
817 variable to find images and kernel binaries and will use
818 BitBake to determine the directory.
819 Alternatively, you can set the
820 <filename>DEPLOY_DIR_IMAGE</filename> variable in the
821 external environment.</para></listitem>
822 <listitem><para>
823 When buildhistory is enabled, its output is now written
824 under the
825 <link linkend='build-directory'>Build Directory</link>
826 rather than
827 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>.
828 Doing so makes it easier to delete
829 <filename>TMPDIR</filename> and preserve the build history.
830 Additionally, data for produced SDKs is now split by
831 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>.
832 </para></listitem>
833 <listitem><para>
834 The <filename>pkgdata</filename> directory produced as
835 part of the packaging process has been collapsed into a
836 single machine-specific directory.
837 This directory is located under
838 <filename>sysroots</filename> and uses a machine-specific
839 name (i.e.
840 <filename>tmp/sysroots/<replaceable>machine</replaceable>/pkgdata</filename>).
841 </para></listitem>
842 </itemizedlist>
843 </para>
844 </section>
845
846 <section id='migration-1.5-shortened-git-srcrev-values'>
847 <title>Shortened Git <filename>SRCREV</filename> Values</title>
848
849 <para>
850 BitBake will now shorten revisions from Git repositories from the
851 normal 40 characters down to 10 characters within
852 <link linkend='var-SRCPV'><filename>SRCPV</filename></link>
853 for improved usability in path and file names.
854 This change should be safe within contexts where these revisions
855 are used because the chances of spatially close collisions
856 is very low.
857 Distant collisions are not a major issue in the way
858 the values are used.
859 </para>
860 </section>
861
862 <section id='migration-1.5-image-features'>
863 <title><filename>IMAGE_FEATURES</filename></title>
864
865 <para>
866 The following changes have been made that relate to
867 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
868 <itemizedlist>
869 <listitem><para>
870 The value of <filename>IMAGE_FEATURES</filename> is now
871 validated to ensure invalid feature items are not added.
872 Some users mistakenly add package names to this variable
873 instead of using
874 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
875 in order to have the package added to the image, which does
876 not work.
877 This change is intended to catch those kinds of situations.
878 Valid <filename>IMAGE_FEATURES</filename> are drawn from
879 <filename>PACKAGE_GROUP</filename> definitions,
880 <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link>
881 and a new "validitems" varflag on
882 <filename>IMAGE_FEATURES</filename>.
883 The "validitems" varflag change allows additional features
884 to be added if they are not provided using the previous
885 two mechanisms.
886 </para></listitem>
887 <listitem><para>
888 The previously deprecated "apps-console-core"
889 <filename>IMAGE_FEATURES</filename> item is no longer
890 supported.
891 Add "splash" to <filename>IMAGE_FEATURES</filename> if you
892 wish to have the splash screen enabled, since this is
893 all that apps-console-core was doing.</para></listitem>
894 </itemizedlist>
895 </para>
896 </section>
897
898 <section id='migration-1.5-run'>
899 <title><filename>/run</filename></title>
900
901 <para>
902 The <filename>/run</filename> directory from the Filesystem
903 Hierarchy Standard 3.0 has been introduced.
904 You can find some of the implications for this change
905 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873'>here</ulink>.
906 The change also means that recipes that install files to
907 <filename>/var/run</filename> must be changed.
908 You can find a guide on how to make these changes
909 <ulink url='http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530'>here</ulink>.
910 </para>
911 </section>
912
913 <section id='migration-1.5-removal-of-package-manager-database-within-image-recipes'>
914 <title>Removal of Package Manager Database Within Image Recipes</title>
915
916 <para>
917 The image <filename>core-image-minimal</filename> no longer adds
918 <filename>remove_packaging_data_files</filename> to
919 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
920 This addition is now handled automatically when "package-management"
921 is not in
922 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
923 If you have custom image recipes that make this addition,
924 you should remove the lines, as they are not needed and might
925 interfere with correct operation of postinstall scripts.
926 </para>
927 </section>
928
929 <section id='migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time'>
930 <title>Images Now Rebuild Only on Changes Instead of Every Time</title>
931
932 <para>
933 The
934 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
935 and other related image
936 construction tasks are no longer marked as "nostamp".
937 Consequently, they will only be re-executed when their inputs have
938 changed.
939 Previous versions of the OpenEmbedded build system always rebuilt
940 the image when requested rather when necessary.
941 </para>
942 </section>
943
944 <section id='migration-1.5-task-recipes'>
945 <title>Task Recipes</title>
946
947 <para>
948 The previously deprecated <filename>task.bbclass</filename> has
949 now been dropped.
950 For recipes that previously inherited from this class, you should
951 rename them from <filename>task-*</filename> to
952 <filename>packagegroup-*</filename> and inherit packagegroup
953 instead.
954 </para>
955
956 <para>
957 For more information, see the
958 "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>"
959 section.
960 </para>
961 </section>
962
963 <section id='migration-1.5-busybox'>
964 <title>BusyBox</title>
965
966 <para>
967 By default, we now split BusyBox into two binaries:
968 one that is suid root for those components that need it, and
969 another for the rest of the components.
970 Splitting BusyBox allows for optimization that eliminates the
971 <filename>tinylogin</filename> recipe as recommended by upstream.
972 You can disable this split by setting
973 <link linkend='var-BUSYBOX_SPLIT_SUID'><filename>BUSYBOX_SPLIT_SUID</filename></link>
974 to "0".
975 </para>
976 </section>
977
978 <section id='migration-1.5-automated-image-testing'>
979 <title>Automated Image Testing</title>
980
981 <para>
982 A new automated image testing framework has been added
983 through the
984 <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>
985 class.
986 This framework replaces the older
987 <filename>imagetest-qemu</filename> framework.
988 </para>
989
990 <para>
991 You can learn more about performing automated image tests in the
992 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
993 section in the Yocto Project Development Tasks Manual.
994 </para>
995 </section>
996
997 <section id='migration-1.5-build-history'>
998 <title>Build History</title>
999
1000 <para>
1001 Following are changes to Build History:
1002 <itemizedlist>
1003 <listitem><para>
1004 Installed package sizes:
1005 <filename>installed-package-sizes.txt</filename> for an
1006 image now records the size of the files installed by each
1007 package instead of the size of each compressed package
1008 archive file.</para></listitem>
1009 <listitem><para>
1010 The dependency graphs (<filename>depends*.dot</filename>)
1011 now use the actual package names instead of replacing
1012 dashes, dots and plus signs with underscores.
1013 </para></listitem>
1014 <listitem><para>
1015 The <filename>buildhistory-diff</filename> and
1016 <filename>buildhistory-collect-srcrevs</filename>
1017 utilities have improved command-line handling.
1018 Use the <filename>--help</filename> option for
1019 each utility for more information on the new syntax.
1020 </para></listitem>
1021 </itemizedlist>
1022 For more information on Build History, see the
1023 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
1024 section in the Yocto Project Development Tasks Manual.
1025 </para>
1026 </section>
1027
1028 <section id='migration-1.5-udev'>
1029 <title><filename>udev</filename></title>
1030
1031 <para>
1032 Following are changes to <filename>udev</filename>:
1033 <itemizedlist>
1034 <listitem><para>
1035 <filename>udev</filename> no longer brings in
1036 <filename>udev-extraconf</filename> automatically
1037 through
1038 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1039 since this was originally intended to be optional.
1040 If you need the extra rules, then add
1041 <filename>udev-extraconf</filename> to your image.
1042 </para></listitem>
1043 <listitem><para>
1044 <filename>udev</filename> no longer brings in
1045 <filename>pciutils-ids</filename> or
1046 <filename>usbutils-ids</filename> through
1047 <filename>RRECOMMENDS</filename>.
1048 These are not needed by <filename>udev</filename> itself
1049 and removing them saves around 350KB.
1050 </para></listitem>
1051 </itemizedlist>
1052 </para>
1053 </section>
1054
1055 <section id='migration-1.5-removed-renamed-recipes'>
1056 <title>Removed and Renamed Recipes</title>
1057
1058 <itemizedlist>
1059 <listitem><para>
1060 The <filename>linux-yocto</filename> 3.2 kernel has been
1061 removed.</para></listitem>
1062 <listitem><para>
1063 <filename>libtool-nativesdk</filename> has been renamed to
1064 <filename>nativesdk-libtool</filename>.</para></listitem>
1065 <listitem><para>
1066 <filename>tinylogin</filename> has been removed.
1067 It has been replaced by a suid portion of Busybox.
1068 See the
1069 "<link linkend='migration-1.5-busybox'>BusyBox</link>" section
1070 for more information.</para></listitem>
1071 <listitem><para>
1072 <filename>external-python-tarball</filename> has been renamed
1073 to <filename>buildtools-tarball</filename>.
1074 </para></listitem>
1075 <listitem><para>
1076 <filename>web-webkit</filename> has been removed.
1077 It has been functionally replaced by
1078 <filename>midori</filename>.</para></listitem>
1079 <listitem><para>
1080 <filename>imake</filename> has been removed.
1081 It is no longer needed by any other recipe.
1082 </para></listitem>
1083 <listitem><para>
1084 <filename>transfig-native</filename> has been removed.
1085 It is no longer needed by any other recipe.
1086 </para></listitem>
1087 <listitem><para>
1088 <filename>anjuta-remote-run</filename> has been removed.
1089 Anjuta IDE integration has not been officially supported for
1090 several releases.</para></listitem>
1091 </itemizedlist>
1092 </section>
1093
1094 <section id='migration-1.5-other-changes'>
1095 <title>Other Changes</title>
1096
1097 <para>
1098 Following is a list of short entries describing other changes:
1099 <itemizedlist>
1100 <listitem><para>
1101 <filename>run-postinsts</filename>: Make this generic.
1102 </para></listitem>
1103 <listitem><para>
1104 <filename>base-files</filename>: Remove the unnecessary
1105 <filename>media/</filename><replaceable>xxx</replaceable> directories.
1106 </para></listitem>
1107 <listitem><para>
1108 <filename>alsa-state</filename>: Provide an empty
1109 <filename>asound.conf</filename> by default.
1110 </para></listitem>
1111 <listitem><para>
1112 <filename>classes/image</filename>: Ensure
1113 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1114 supports pre-renamed package names.</para></listitem>
1115 <listitem><para>
1116 <filename>classes/rootfs_rpm</filename>: Implement
1117 <filename>BAD_RECOMMENDATIONS</filename> for RPM.
1118 </para></listitem>
1119 <listitem><para>
1120 <filename>systemd</filename>: Remove
1121 <filename>systemd_unitdir</filename> if
1122 <filename>systemd</filename> is not in
1123 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1124 </para></listitem>
1125 <listitem><para>
1126 <filename>systemd</filename>: Remove
1127 <filename>init.d</filename> dir if
1128 <filename>systemd</filename> unit file is present and
1129 <filename>sysvinit</filename> is not a distro feature.
1130 </para></listitem>
1131 <listitem><para>
1132 <filename>libpam</filename>: Deny all services for the
1133 <filename>OTHER</filename> entries.
1134 </para></listitem>
1135 <listitem><para>
1136 <filename>image.bbclass</filename>: Move
1137 <filename>runtime_mapping_rename</filename> to avoid
1138 conflict with <filename>multilib</filename>.
1139 See
1140 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993'><filename>YOCTO #4993</filename></ulink>
1141 in Bugzilla for more information.
1142 </para></listitem>
1143 <listitem><para>
1144 <filename>linux-dtb</filename>: Use kernel build system
1145 to generate the <filename>dtb</filename> files.
1146 </para></listitem>
1147 <listitem><para>
1148 <filename>kern-tools</filename>: Switch from guilt to
1149 new <filename>kgit-s2q</filename> tool.
1150 </para></listitem>
1151 </itemizedlist>
1152 </para>
1153 </section>
1154</section>
1155
1156<section id='moving-to-the-yocto-project-1.6-release'>
1157 <title>Moving to the Yocto Project 1.6 Release</title>
1158
1159 <para>
1160 This section provides migration information for moving to the
1161 Yocto Project 1.6 Release from the prior release.
1162 </para>
1163
1164
1165 <section id='migration-1.6-archiver-class'>
1166 <title><filename>archiver</filename> Class</title>
1167
1168 <para>
1169 The
1170 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
1171 class has been rewritten and its configuration has been simplified.
1172 For more details on the source archiver, see the
1173 "<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>"
1174 section in the Yocto Project Development Tasks Manual.
1175 </para>
1176 </section>
1177
1178 <section id='migration-1.6-packaging-changes'>
1179 <title>Packaging Changes</title>
1180
1181 <para>
1182 The following packaging changes have been made:
1183 <itemizedlist>
1184 <listitem><para>
1185 The <filename>binutils</filename> recipe no longer produces
1186 a <filename>binutils-symlinks</filename> package.
1187 <filename>update-alternatives</filename> is now used to
1188 handle the preferred <filename>binutils</filename>
1189 variant on the target instead.
1190 </para></listitem>
1191 <listitem><para>
1192 The tc (traffic control) utilities have been split out of
1193 the main <filename>iproute2</filename> package and put
1194 into the <filename>iproute2-tc</filename> package.
1195 </para></listitem>
1196 <listitem><para>
1197 The <filename>gtk-engines</filename> schemas have been
1198 moved to a dedicated
1199 <filename>gtk-engines-schemas</filename> package.
1200 </para></listitem>
1201 <listitem><para>
1202 The <filename>armv7a</filename> with thumb package
1203 architecture suffix has changed.
1204 The suffix for these packages with the thumb
1205 optimization enabled is "t2" as it should be.
1206 Use of this suffix was not the case in the 1.5 release.
1207 Architecture names will change within package feeds as a
1208 result.
1209 </para></listitem>
1210 </itemizedlist>
1211 </para>
1212 </section>
1213
1214 <section id='migration-1.6-bitbake'>
1215 <title>BitBake</title>
1216
1217 <para>
1218 The following changes have been made to
1219 <link linkend='bitbake-term'>BitBake</link>.
1220 </para>
1221
1222 <section id='migration-1.6-matching-branch-requirement-for-git-fetching'>
1223 <title>Matching Branch Requirement for Git Fetching</title>
1224
1225 <para>
1226 When fetching source from a Git repository using
1227 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
1228 BitBake will now validate the
1229 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
1230 value against the branch.
1231 You can specify the branch using the following form:
1232 <literallayout class='monospaced'>
1233 SRC_URI = "git://server.name/repository;branch=<replaceable>branchname</replaceable>"
1234 </literallayout>
1235 If you do not specify a branch, BitBake looks
1236 in the default "master" branch.
1237 </para>
1238
1239 <para>
1240 Alternatively, if you need to bypass this check (e.g.
1241 if you are fetching a revision corresponding to a tag that
1242 is not on any branch), you can add ";nobranch=1" to
1243 the end of the URL within <filename>SRC_URI</filename>.
1244 </para>
1245 </section>
1246
1247 <section id='migration-1.6-bitbake-deps'>
1248 <title>Python Definition substitutions</title>
1249
1250 <para>
1251 BitBake had some previously deprecated Python definitions
1252 within its <filename>bb</filename> module removed.
1253 You should use their sub-module counterparts instead:
1254 <itemizedlist>
1255 <listitem><para><filename>bb.MalformedUrl</filename>:
1256 Use <filename>bb.fetch.MalformedUrl</filename>.
1257 </para></listitem>
1258 <listitem><para><filename>bb.encodeurl</filename>:
1259 Use <filename>bb.fetch.encodeurl</filename>.
1260 </para></listitem>
1261 <listitem><para><filename>bb.decodeurl</filename>:
1262 Use <filename>bb.fetch.decodeurl</filename>
1263 </para></listitem>
1264 <listitem><para><filename>bb.mkdirhier</filename>:
1265 Use <filename>bb.utils.mkdirhier</filename>.
1266 </para></listitem>
1267 <listitem><para><filename>bb.movefile</filename>:
1268 Use <filename>bb.utils.movefile</filename>.
1269 </para></listitem>
1270 <listitem><para><filename>bb.copyfile</filename>:
1271 Use <filename>bb.utils.copyfile</filename>.
1272 </para></listitem>
1273 <listitem><para><filename>bb.which</filename>:
1274 Use <filename>bb.utils.which</filename>.
1275 </para></listitem>
1276 <listitem><para><filename>bb.vercmp_string</filename>:
1277 Use <filename>bb.utils.vercmp_string</filename>.
1278 </para></listitem>
1279 <listitem><para><filename>bb.vercmp</filename>:
1280 Use <filename>bb.utils.vercmp</filename>.
1281 </para></listitem>
1282 </itemizedlist>
1283 </para>
1284 </section>
1285
1286 <section id='migration-1.6-bitbake-fetcher'>
1287 <title>SVK Fetcher</title>
1288
1289 <para>
1290 The SVK fetcher has been removed from BitBake.
1291 </para>
1292 </section>
1293
1294 <section id='migration-1.6-bitbake-console-output'>
1295 <title>Console Output Error Redirection</title>
1296
1297 <para>
1298 The BitBake console UI will now output errors to
1299 <filename>stderr</filename> instead of
1300 <filename>stdout</filename>.
1301 Consequently, if you are piping or redirecting the output of
1302 <filename>bitbake</filename> to somewhere else, and you wish
1303 to retain the errors, you will need to add
1304 <filename>2>&amp;1</filename> (or something similar) to the
1305 end of your <filename>bitbake</filename> command line.
1306 </para>
1307 </section>
1308
1309 <section id='migration-1.6-task-taskname-overrides'>
1310 <title><filename>task-</filename><replaceable>taskname</replaceable> Overrides</title>
1311
1312 <para>
1313 <filename>task-</filename><replaceable>taskname</replaceable> overrides have been
1314 adjusted so that tasks whose names contain underscores have the
1315 underscores replaced by hyphens for the override so that they
1316 now function properly.
1317 For example, the task override for
1318 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
1319 is <filename>task-populate-sdk</filename>.
1320 </para>
1321 </section>
1322 </section>
1323
1324 <section id='migration-1.6-variable-changes'>
1325 <title>Changes to Variables</title>
1326
1327 <para>
1328 The following variables have changed.
1329 For information on the OpenEmbedded build system variables, see the
1330 "<link linkend='ref-variables-glos'>Variables Glossary</link>" Chapter.
1331 </para>
1332
1333 <section id='migration-1.6-variable-changes-TMPDIR'>
1334 <title><filename>TMPDIR</filename></title>
1335
1336 <para>
1337 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1338 can no longer be on an NFS mount.
1339 NFS does not offer full POSIX locking and inode consistency
1340 and can cause unexpected issues if used to store
1341 <filename>TMPDIR</filename>.
1342 </para>
1343
1344 <para>
1345 The check for this occurs on startup.
1346 If <filename>TMPDIR</filename> is detected on an NFS mount,
1347 an error occurs.
1348 </para>
1349 </section>
1350
1351 <section id='migration-1.6-variable-changes-PRINC'>
1352 <title><filename>PRINC</filename></title>
1353
1354 <para>
1355 The <filename>PRINC</filename>
1356 variable has been deprecated and triggers a warning if
1357 detected during a build.
1358 For
1359 <link linkend='var-PR'><filename>PR</filename></link>
1360 increments on changes, use the PR service instead.
1361 You can find out more about this service in the
1362 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
1363 section in the Yocto Project Development Tasks Manual.
1364 </para>
1365 </section>
1366
1367 <section id='migration-1.6-variable-changes-IMAGE_TYPES'>
1368 <title><filename>IMAGE_TYPES</filename></title>
1369
1370 <para>
1371 The "sum.jffs2" option for
1372 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>
1373 has been replaced by the "jffs2.sum" option, which fits the
1374 processing order.
1375 </para>
1376 </section>
1377
1378 <section id='migration-1.6-variable-changes-COPY_LIC_MANIFEST'>
1379 <title><filename>COPY_LIC_MANIFEST</filename></title>
1380
1381 <para>
1382 The
1383 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1384 variable must
1385 now be set to "1" rather than any value in order to enable
1386 it.
1387 </para>
1388 </section>
1389
1390 <section id='migration-1.6-variable-changes-COPY_LIC_DIRS'>
1391 <title><filename>COPY_LIC_DIRS</filename></title>
1392
1393 <para>
1394 The
1395 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
1396 variable must
1397 now be set to "1" rather than any value in order to enable
1398 it.
1399 </para>
1400 </section>
1401
1402 <section id='migration-1.6-variable-changes-PACKAGE_GROUP'>
1403 <title><filename>PACKAGE_GROUP</filename></title>
1404
1405 <para>
1406 The
1407 <filename>PACKAGE_GROUP</filename> 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
1416 <section id='migration-1.6-variable-changes-variable-entry-behavior'>
1417 <title>Preprocess and Post Process Command Variable Behavior</title>
1418
1419 <para>
1420 The following variables now expect a semicolon separated
1421 list of functions to call and not arbitrary shell commands:
1422 <literallayout class='monospaced'>
1423 <link linkend='var-ROOTFS_PREPROCESS_COMMAND'>ROOTFS_PREPROCESS_COMMAND</link>
1424 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'>ROOTFS_POSTPROCESS_COMMAND</link>
1425 <link linkend='var-SDK_POSTPROCESS_COMMAND'>SDK_POSTPROCESS_COMMAND</link>
1426 <link linkend='var-POPULATE_SDK_POST_TARGET_COMMAND'>POPULATE_SDK_POST_TARGET_COMMAND</link>
1427 <link linkend='var-POPULATE_SDK_POST_HOST_COMMAND'>POPULATE_SDK_POST_HOST_COMMAND</link>
1428 <link linkend='var-IMAGE_POSTPROCESS_COMMAND'>IMAGE_POSTPROCESS_COMMAND</link>
1429 <link linkend='var-IMAGE_PREPROCESS_COMMAND'>IMAGE_PREPROCESS_COMMAND</link>
1430 <link linkend='var-ROOTFS_POSTUNINSTALL_COMMAND'>ROOTFS_POSTUNINSTALL_COMMAND</link>
1431 <link linkend='var-ROOTFS_POSTINSTALL_COMMAND'>ROOTFS_POSTINSTALL_COMMAND</link>
1432 </literallayout>
1433 For migration purposes, you can simply wrap shell commands in
1434 a shell function and then call the function.
1435 Here is an example:
1436 <literallayout class='monospaced'>
1437 my_postprocess_function() {
1438 echo "hello" > ${IMAGE_ROOTFS}/hello.txt
1439 }
1440 ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "
1441 </literallayout>
1442 </para>
1443 </section>
1444 </section>
1445
1446 <section id='migration-1.6-package-test-ptest'>
1447 <title>Package Test (ptest)</title>
1448
1449 <para>
1450 Package Tests (ptest) are built but not installed by default.
1451 For information on using Package Tests, see the
1452 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages with ptest</ulink>"
1453 section in the Yocto Project Development Tasks Manual.
1454 For information on the <filename>ptest</filename> class, see the
1455 "<link linkend='ref-classes-ptest'><filename>ptest.bbclass</filename></link>"
1456 section.
1457 </para>
1458 </section>
1459
1460 <section id='migration-1.6-build-changes'>
1461 <title>Build Changes</title>
1462
1463 <para>
1464 Separate build and source directories have been enabled
1465 by default for selected recipes where it is known to work
1466 (a whitelist) and for all recipes that inherit the
1467 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
1468 class.
1469 In future releases the
1470 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
1471 class will enable a separate build directory by default as
1472 well.
1473 Recipes building Autotools-based
1474 software that fails to build with a separate build directory
1475 should be changed to inherit from the
1476 <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
1477 class instead of the <filename>autotools</filename> or
1478 <filename>autotools_stage</filename>classes.
1479 </para>
1480 </section>
1481
1482 <section id='migration-1.6-building-qemu-native'>
1483 <title><filename>qemu-native</filename></title>
1484
1485 <para>
1486 <filename>qemu-native</filename> now builds without
1487 SDL-based graphical output support by default.
1488 The following additional lines are needed in your
1489 <filename>local.conf</filename> to enable it:
1490 <literallayout class='monospaced'>
1491 PACKAGECONFIG_pn-qemu-native = "sdl"
1492 ASSUME_PROVIDED += "libsdl-native"
1493 </literallayout>
1494 <note>
1495 The default <filename>local.conf</filename>
1496 contains these statements.
1497 Consequently, if you are building a headless system and using
1498 a default <filename>local.conf</filename> file, you will need
1499 comment these two lines out.
1500 </note>
1501 </para>
1502 </section>
1503
1504 <section id='migration-1.6-core-image-basic'>
1505 <title><filename>core-image-basic</filename></title>
1506
1507 <para>
1508 <filename>core-image-basic</filename> has been renamed to
1509 <filename>core-image-full-cmdline</filename>.
1510 </para>
1511
1512 <para>
1513 In addition to <filename>core-image-basic</filename> being renamed,
1514 <filename>packagegroup-core-basic</filename> has been renamed to
1515 <filename>packagegroup-core-full-cmdline</filename> to match.
1516 </para>
1517 </section>
1518
1519 <section id='migration-1.6-licensing'>
1520 <title>Licensing</title>
1521
1522 <para>
1523 The top-level <filename>LICENSE</filename> file has been changed
1524 to better describe the license of the various components of
1525 <link linkend='oe-core'>OE-Core</link>.
1526 However, the licensing itself remains unchanged.
1527 </para>
1528
1529 <para>
1530 Normally, this change would not cause any side-effects.
1531 However, some recipes point to this file within
1532 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
1533 (as <filename>${COREBASE}/LICENSE</filename>) and thus the
1534 accompanying checksum must be changed from
1535 3f40d7994397109285ec7b81fdeb3b58 to
1536 4d92cd373abda3937c2bc47fbc49d690.
1537 A better alternative is to have
1538 <filename>LIC_FILES_CHKSUM</filename> point to a file
1539 describing the license that is distributed with the source
1540 that the recipe is building, if possible, rather than pointing
1541 to <filename>${COREBASE}/LICENSE</filename>.
1542 </para>
1543 </section>
1544
1545 <section id='migration-1.6-cflags-options'>
1546 <title><filename>CFLAGS</filename> Options</title>
1547
1548 <para>
1549 The "-fpermissive" option has been removed from the default
1550 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1551 value.
1552 You need to take action on individual recipes that fail when
1553 building with this option.
1554 You need to either patch the recipes to fix the issues reported by
1555 the compiler, or you need to add "-fpermissive" to
1556 <filename>CFLAGS</filename> in the recipes.
1557 </para>
1558 </section>
1559
1560 <section id='migration-1.6-custom-images'>
1561 <title>Custom Image Output Types</title>
1562
1563 <para>
1564 Custom image output types, as selected using
1565 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
1566 must declare their dependencies on other image types (if any) using
1567 a new
1568 <link linkend='var-IMAGE_TYPEDEP'><filename>IMAGE_TYPEDEP</filename></link>
1569 variable.
1570 </para>
1571 </section>
1572
1573 <section id='migration-1.6-do-package-write-task'>
1574 <title>Tasks</title>
1575
1576 <para>
1577 The <filename>do_package_write</filename> task has been removed.
1578 The task is no longer needed.
1579 </para>
1580 </section>
1581
1582 <section id='migration-1.6-update-alternatives-provider'>
1583 <title><filename>update-alternative</filename> Provider</title>
1584
1585 <para>
1586 The default <filename>update-alternatives</filename> provider has
1587 been changed from <filename>opkg</filename> to
1588 <filename>opkg-utils</filename>.
1589 This change resolves some troublesome circular dependencies.
1590 The runtime package has also been renamed from
1591 <filename>update-alternatives-cworth</filename>
1592 to <filename>update-alternatives-opkg</filename>.
1593 </para>
1594 </section>
1595
1596 <section id='migration-1.6-virtclass-overrides'>
1597 <title><filename>virtclass</filename> Overrides</title>
1598
1599 <para>
1600 The <filename>virtclass</filename> overrides are now deprecated.
1601 Use the equivalent class overrides instead (e.g.
1602 <filename>virtclass-native</filename> becomes
1603 <filename>class-native</filename>.)
1604 </para>
1605 </section>
1606
1607 <section id='migration-1.6-removed-renamed-recipes'>
1608 <title>Removed and Renamed Recipes</title>
1609
1610 <para>
1611 The following recipes have been removed:
1612 <itemizedlist>
1613 <listitem><para><filename>packagegroup-toolset-native</filename> -
1614 This recipe is largely unused.
1615 </para></listitem>
1616 <listitem><para><filename>linux-yocto-3.8</filename> -
1617 Support for the Linux yocto 3.8 kernel has been dropped.
1618 Support for the 3.10 and 3.14 kernels have been added
1619 with the <filename>linux-yocto-3.10</filename> and
1620 <filename>linux-yocto-3.14</filename> recipes.
1621 </para></listitem>
1622 <listitem><para><filename>ocf-linux</filename> -
1623 This recipe has been functionally replaced using
1624 <filename>cryptodev-linux</filename>.
1625 </para></listitem>
1626 <listitem><para><filename>genext2fs</filename> -
1627 <filename>genext2fs</filename> is no longer used by the
1628 build system and is unmaintained upstream.
1629 </para></listitem>
1630 <listitem><para><filename>js</filename> -
1631 This provided an ancient version of Mozilla's javascript
1632 engine that is no longer needed.
1633 </para></listitem>
1634 <listitem><para><filename>zaurusd</filename> -
1635 The recipe has been moved to the
1636 <filename>meta-handheld</filename> layer.
1637 </para></listitem>
1638 <listitem><para><filename>eglibc 2.17</filename> -
1639 Replaced by the <filename>eglibc 2.19</filename>
1640 recipe.
1641 </para></listitem>
1642 <listitem><para><filename>gcc 4.7.2</filename> -
1643 Replaced by the now stable
1644 <filename>gcc 4.8.2</filename>.
1645 </para></listitem>
1646 <listitem><para><filename>external-sourcery-toolchain</filename> -
1647 this recipe is now maintained in the
1648 <filename>meta-sourcery</filename> layer.
1649 </para></listitem>
1650 <listitem><para><filename>linux-libc-headers-yocto 3.4+git</filename> -
1651 Now using version 3.10 of the
1652 <filename>linux-libc-headers</filename> by default.
1653 </para></listitem>
1654 <listitem><para><filename>meta-toolchain-gmae</filename> -
1655 This recipe is obsolete.
1656 </para></listitem>
1657 <listitem><para><filename>packagegroup-core-sdk-gmae</filename> -
1658 This recipe is obsolete.
1659 </para></listitem>
1660 <listitem><para><filename>packagegroup-core-standalone-gmae-sdk-target</filename> -
1661 This recipe is obsolete.
1662 </para></listitem>
1663 </itemizedlist>
1664 </para>
1665 </section>
1666
1667 <section id='migration-1.6-removed-classes'>
1668 <title>Removed Classes</title>
1669
1670 <para>
1671 The following classes have become obsolete and have been removed:
1672 <itemizedlist>
1673 <listitem><para><filename>module_strip</filename>
1674 </para></listitem>
1675 <listitem><para><filename>pkg_metainfo</filename>
1676 </para></listitem>
1677 <listitem><para><filename>pkg_distribute</filename>
1678 </para></listitem>
1679 <listitem><para><filename>image-empty</filename>
1680 </para></listitem>
1681 </itemizedlist>
1682 </para>
1683 </section>
1684
1685 <section id='migration-1.6-reference-bsps'>
1686 <title>Reference Board Support Packages (BSPs)</title>
1687
1688 <para>
1689 The following reference BSPs changes occurred:
1690 <itemizedlist>
1691 <listitem><para>The BeagleBoard
1692 (<filename>beagleboard</filename>) ARM reference hardware
1693 has been replaced by the BeagleBone
1694 (<filename>beaglebone</filename>) hardware.
1695 </para></listitem>
1696 <listitem><para>The RouterStation Pro
1697 (<filename>routerstationpro</filename>) MIPS reference
1698 hardware has been replaced by the EdgeRouter Lite
1699 (<filename>edgerouter</filename>) hardware.
1700 </para></listitem>
1701 </itemizedlist>
1702 The previous reference BSPs for the
1703 <filename>beagleboard</filename> and
1704 <filename>routerstationpro</filename> machines are still available
1705 in a new <filename>meta-yocto-bsp-old</filename> layer in the
1706 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
1707 at
1708 <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>.
1709 </para>
1710 </section>
1711</section>
1712
1713<section id='moving-to-the-yocto-project-1.7-release'>
1714 <title>Moving to the Yocto Project 1.7 Release</title>
1715
1716 <para>
1717 This section provides migration information for moving to the
1718 Yocto Project 1.7 Release from the prior release.
1719 </para>
1720
1721 <section id='migration-1.7-changes-to-setting-qemu-packageconfig-options'>
1722 <title>Changes to Setting QEMU <filename>PACKAGECONFIG</filename> Options in <filename>local.conf</filename></title>
1723
1724 <para>
1725 The QEMU recipe now uses a number of
1726 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
1727 options to enable various optional features.
1728 The method used to set defaults for these options means that
1729 existing
1730 <filename>local.conf</filename> files will need to be be
1731 modified to append to <filename>PACKAGECONFIG</filename> for
1732 <filename>qemu-native</filename> and
1733 <filename>nativesdk-qemu</filename> instead of setting it.
1734 In other words, to enable graphical output for QEMU, you should
1735 now have these lines in <filename>local.conf</filename>:
1736 <literallayout class='monospaced'>
1737 PACKAGECONFIG_append_pn-qemu-native = " sdl"
1738 PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
1739 </literallayout>
1740 </para>
1741 </section>
1742
1743 <section id='migration-1.7-minimum-git-version'>
1744 <title>Minimum Git version</title>
1745
1746 <para>
1747 The minimum
1748 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> version
1749 required on the build host is now 1.7.8 because the
1750 <filename>--list</filename> option is now required by
1751 BitBake's Git fetcher.
1752 As always, if your host distribution does not provide a version of
1753 Git that meets this requirement, you can use the
1754 <filename>buildtools-tarball</filename> that does.
1755 See the
1756 "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>"
1757 section for more information.
1758 </para>
1759 </section>
1760
1761 <section id='migration-1.7-autotools-class-changes'>
1762 <title>Autotools Class Changes</title>
1763
1764 <para>
1765 The following
1766 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
1767 class changes occurred:
1768 <itemizedlist>
1769 <listitem><para><emphasis>
1770 A separate build directory is now used by default:</emphasis>
1771 The <filename>autotools</filename> class has been changed
1772 to use a directory for building
1773 (<link linkend='var-B'><filename>B</filename></link>),
1774 which is separate from the source directory
1775 (<link linkend='var-S'><filename>S</filename></link>).
1776 This is commonly referred to as
1777 <filename>B != S</filename>, or an out-of-tree build.</para>
1778 <para>If the software being built is already capable of
1779 building in a directory separate from the source, you
1780 do not need to do anything.
1781 However, if the software is not capable of being built
1782 in this manner, you will
1783 need to either patch the software so that it can build
1784 separately, or you will need to change the recipe to
1785 inherit the
1786 <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
1787 class instead of the <filename>autotools</filename> or
1788 <filename>autotools_stage</filename> classes.
1789 </para></listitem>
1790 <listitem><para><emphasis>
1791 The <filename>--foreign</filename> option is
1792 no longer passed to <filename>automake</filename> when
1793 running <filename>autoconf</filename>:</emphasis>
1794 This option tells <filename>automake</filename> that a
1795 particular software package does not follow the GNU
1796 standards and therefore should not be expected
1797 to distribute certain files such as
1798 <filename>ChangeLog</filename>,
1799 <filename>AUTHORS</filename>, and so forth.
1800 Because the majority of upstream software packages already
1801 tell <filename>automake</filename> to enable foreign mode
1802 themselves, the option is mostly superfluous.
1803 However, some recipes will need patches for this change.
1804 You can easily make the change by patching
1805 <filename>configure.ac</filename> so that it passes
1806 "foreign" to <filename>AM_INIT_AUTOMAKE()</filename>.
1807 See
1808 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2'>this commit</ulink>
1809 for an example showing how to make the patch.
1810 </para></listitem>
1811 </itemizedlist>
1812 </para>
1813 </section>
1814
1815 <section id='migration-1.7-binary-configuration-scripts-disabled'>
1816 <title>Binary Configuration Scripts Disabled</title>
1817
1818 <para>
1819 Some of the core recipes that package binary configuration scripts
1820 now disable the scripts due to the
1821 scripts previously requiring error-prone path substitution.
1822 Software that links against these libraries using these scripts
1823 should use the much more robust <filename>pkg-config</filename>
1824 instead.
1825 The list of recipes changed in this version (and their
1826 configuration scripts) is as follows:
1827 <literallayout class='monospaced'>
1828 directfb (directfb-config)
1829 freetype (freetype-config)
1830 gpgme (gpgme-config)
1831 libassuan (libassuan-config)
1832 libcroco (croco-6.0-config)
1833 libgcrypt (libgcrypt-config)
1834 libgpg-error (gpg-error-config)
1835 libksba (ksba-config)
1836 libpcap (pcap-config)
1837 libpcre (pcre-config)
1838 libpng (libpng-config, libpng16-config)
1839 libsdl (sdl-config)
1840 libusb-compat (libusb-config)
1841 libxml2 (xml2-config)
1842 libxslt (xslt-config)
1843 ncurses (ncurses-config)
1844 neon (neon-config)
1845 npth (npth-config)
1846 pth (pth-config)
1847 taglib (taglib-config)
1848 </literallayout>
1849 Additionally, support for <filename>pkg-config</filename> has been
1850 added to some recipes in the previous list in the rare cases
1851 where the upstream software package does not already provide
1852 it.
1853 </para>
1854 </section>
1855
1856 <section id='migration-1.7-glibc-replaces-eglibc'>
1857 <title><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></title>
1858
1859 <para>
1860 Because <filename>eglibc</filename> and
1861 <filename>glibc</filename> were already fairly close, this
1862 replacement should not require any significant changes to other
1863 software that links to <filename>eglibc</filename>.
1864 However, there were a number of minor changes in
1865 <filename>glibc 2.20</filename> upstream that could require
1866 patching some software (e.g. the removal of the
1867 <filename>_BSD_SOURCE</filename> feature test macro).
1868 </para>
1869
1870 <para>
1871 <filename>glibc 2.20</filename> requires version 2.6.32 or greater
1872 of the Linux kernel.
1873 Thus, older kernels will no longer be usable in conjunction with it.
1874 </para>
1875
1876 <para>
1877 For full details on the changes in <filename>glibc 2.20</filename>,
1878 see the upstream release notes
1879 <ulink url='https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html'>here</ulink>.
1880 </para>
1881 </section>
1882
1883 <section id='migration-1.7-kernel-module-autoloading'>
1884 <title>Kernel Module Autoloading</title>
1885
1886 <para>
1887 The
1888 <link linkend='var-module_autoload'><filename>module_autoload_*</filename></link>
1889 variable is now deprecated and a new
1890 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
1891 variable should be used instead.
1892 Also,
1893 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
1894 must now be used in conjunction with a new
1895 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
1896 variable.
1897 The new variables no longer require you to specify the module name
1898 as part of the variable name.
1899 This change not only simplifies usage but also allows the values
1900 of these variables to be appropriately incorporated into task
1901 signatures and thus trigger the appropriate tasks to re-execute
1902 when changed.
1903 You should replace any references to
1904 <filename>module_autoload_*</filename> with
1905 <filename>KERNEL_MODULE_AUTOLOAD</filename>, and add any modules
1906 for which <filename>module_conf_*</filename> is specified to
1907 <filename>KERNEL_MODULE_PROBECONF</filename>.
1908 </para>
1909 </section>
1910
1911 <section id='migration-1.7-qa-check-changes'>
1912 <title>QA Check Changes</title>
1913
1914 <para>
1915 The following changes have occurred to the QA check process:
1916 <itemizedlist>
1917 <listitem><para>
1918 Additional QA checks <filename>file-rdeps</filename>
1919 and <filename>build-deps</filename> have been added in
1920 order to verify that file dependencies are satisfied
1921 (e.g. package contains a script requiring
1922 <filename>/bin/bash</filename>) and build-time dependencies
1923 are declared, respectively.
1924 For more information, please see the
1925 "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>"
1926 chapter.
1927 </para></listitem>
1928 <listitem><para>
1929 Package QA checks are now performed during a new
1930 <link linkend='ref-tasks-package_qa'><filename>do_package_qa</filename></link>
1931 task rather than being part of the
1932 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
1933 task.
1934 This allows more parallel execution.
1935 This change is unlikely to be an issue except for highly
1936 customized recipes that disable packaging tasks themselves
1937 by marking them as <filename>noexec</filename>.
1938 For those packages, you will need to disable the
1939 <filename>do_package_qa</filename> task as well.
1940 </para></listitem>
1941 <listitem><para>
1942 Files being overwritten during the
1943 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
1944 task now trigger an error instead of a warning.
1945 Recipes should not be overwriting files written to the
1946 sysroot by other recipes.
1947 If you have these types of recipes, you need to alter them
1948 so that they do not overwrite these files.</para>
1949 <para>You might now receive this error after changes in
1950 configuration or metadata resulting in orphaned files
1951 being left in the sysroot.
1952 If you do receive this error, the way to resolve the issue
1953 is to delete your
1954 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1955 or to move it out of the way and then re-start the build.
1956 Anything that has been fully built up to that point and
1957 does not need rebuilding will be restored from the shared
1958 state cache and the rest of the build will be able to
1959 proceed as normal.
1960 </para></listitem>
1961 </itemizedlist>
1962 </para>
1963 </section>
1964
1965 <section id='migration-1.7-removed-recipes'>
1966 <title>Removed Recipes</title>
1967
1968 <para>
1969 The following recipes have been removed:
1970 <itemizedlist>
1971 <listitem><para>
1972 <filename>x-load</filename>:
1973 This recipe has been superseded by
1974 U-boot SPL for all Cortex-based TI SoCs.
1975 For legacy boards, the <filename>meta-ti</filename>
1976 layer, which contains a maintained recipe, should be used
1977 instead.
1978 </para></listitem>
1979 <listitem><para>
1980 <filename>ubootchart</filename>:
1981 This recipe is obsolete.
1982 A <filename>bootchart2</filename> recipe has been added
1983 to functionally replace it.
1984 </para></listitem>
1985 <listitem><para>
1986 <filename>linux-yocto 3.4</filename>:
1987 Support for the linux-yocto 3.4 kernel has been dropped.
1988 Support for the 3.10 and 3.14 kernels remains, while
1989 support for version 3.17 has been added.
1990 </para></listitem>
1991 <listitem><para>
1992 <filename>eglibc</filename> has been removed in favor of
1993 <filename>glibc</filename>.
1994 See the
1995 "<link linkend='migration-1.7-glibc-replaces-eglibc'><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></link>"
1996 section for more information.
1997 </para></listitem>
1998 </itemizedlist>
1999 </para>
2000 </section>
2001
2002 <section id='migration-1.7-miscellaneous-changes'>
2003 <title>Miscellaneous Changes</title>
2004
2005 <para>
2006 The following miscellaneous change occurred:
2007 <itemizedlist>
2008 <listitem><para>
2009 The build history feature now writes
2010 <filename>build-id.txt</filename> instead of
2011 <filename>build-id</filename>.
2012 Additionally, <filename>build-id.txt</filename>
2013 now contains the full build header as printed by
2014 BitBake upon starting the build.
2015 You should manually remove old "build-id" files from your
2016 existing build history repositories to avoid confusion.
2017 For information on the build history feature, see the
2018 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
2019 section in the Yocto Project Development Tasks Manual.
2020 </para></listitem>
2021 </itemizedlist>
2022 </para>
2023 </section>
2024</section>
2025
2026<section id='moving-to-the-yocto-project-1.8-release'>
2027 <title>Moving to the Yocto Project 1.8 Release</title>
2028
2029 <para>
2030 This section provides migration information for moving to the
2031 Yocto Project 1.8 Release from the prior release.
2032 </para>
2033
2034 <section id='migration-1.8-removed-recipes'>
2035 <title>Removed Recipes</title>
2036
2037 <para>
2038 The following recipes have been removed:
2039 <itemizedlist>
2040 <listitem><para><filename>owl-video</filename>:
2041 Functionality replaced by <filename>gst-player</filename>.
2042 </para></listitem>
2043 <listitem><para><filename>gaku</filename>:
2044 Functionality replaced by <filename>gst-player</filename>.
2045 </para></listitem>
2046 <listitem><para><filename>gnome-desktop</filename>:
2047 This recipe is now available in
2048 <filename>meta-gnome</filename> and is no longer needed.
2049 </para></listitem>
2050 <listitem><para><filename>gsettings-desktop-schemas</filename>:
2051 This recipe is now available in
2052 <filename>meta-gnome</filename> and is no longer needed.
2053 </para></listitem>
2054 <listitem><para><filename>python-argparse</filename>:
2055 The <filename>argparse</filename> module is already
2056 provided in the default Python distribution in a
2057 package named <filename>python-argparse</filename>.
2058 Consequently, the separate
2059 <filename>python-argparse</filename> recipe is no
2060 longer needed.
2061 </para></listitem>
2062 <listitem><para><filename>telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control</filename>:
2063 All these recipes have moved to
2064 <filename>meta-oe</filename> and are consequently no
2065 longer needed by any recipes in OpenEmbedded-Core.
2066 </para></listitem>
2067 <listitem><para><filename>linux-yocto_3.10</filename> and <filename>linux-yocto_3.17</filename>:
2068 Support for the linux-yocto 3.10 and 3.17 kernels has been
2069 dropped.
2070 Support for the 3.14 kernel remains, while support for
2071 3.19 kernel has been added.
2072 </para></listitem>
2073 <listitem><para><filename>poky-feed-config-opkg</filename>:
2074 This recipe has become obsolete and is no longer needed.
2075 Use <filename>distro-feed-config</filename> from
2076 <filename>meta-oe</filename> instead.
2077 </para></listitem>
2078 <listitem><para><filename>libav 0.8.x</filename>:
2079 <filename>libav 9.x</filename> is now used.
2080 </para></listitem>
2081 <listitem><para><filename>sed-native</filename>:
2082 No longer needed.
2083 A working version of <filename>sed</filename> is expected
2084 to be provided by the host distribution.
2085 </para></listitem>
2086 </itemizedlist>
2087 </para>
2088 </section>
2089
2090 <section id='migration-1.8-bluez'>
2091 <title>BlueZ 4.x / 5.x Selection</title>
2092
2093 <para>
2094 Proper built-in support for selecting BlueZ 5.x in preference
2095 to the default of 4.x now exists.
2096 To use BlueZ 5.x, simply add "bluez5" to your
2097 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
2098 value.
2099 If you had previously added append files
2100 (<filename>*.bbappend</filename>) to make this selection, you can
2101 now remove them.
2102 </para>
2103
2104 <para>
2105 Additionally, a <filename>bluetooth</filename> class has been added
2106 to make selection of the appropriate bluetooth support within a
2107 recipe a little easier.
2108 If you wish to make use of this class in a recipe, add something
2109 such as the following:
2110 <literallayout class='monospaced'>
2111 inherit bluetooth
2112 PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}"
2113 PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4"
2114 PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5"
2115 </literallayout>
2116 </para>
2117 </section>
2118
2119 <section id='migration-1.8-kernel-build-changes'>
2120 <title>Kernel Build Changes</title>
2121
2122 <para>
2123 The kernel build process was changed to place the source
2124 in a common shared work area and to place build artifacts
2125 separately in the source code tree.
2126 In theory, migration paths have been provided for most common
2127 usages in kernel recipes but this might not work in all cases.
2128 In particular, users need to ensure that
2129 <filename>${S}</filename> (source files) and
2130 <filename>${B}</filename> (build artifacts) are used
2131 correctly in functions such as
2132 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2133 and
2134 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
2135 For kernel recipes that do not inherit from
2136 <filename>kernel-yocto</filename> or include
2137 <filename>linux-yocto.inc</filename>, you might wish to
2138 refer to the <filename>linux.inc</filename> file in the
2139 <filename>meta-oe</filename> layer for the kinds of changes you
2140 need to make.
2141 For reference, here is the
2142 <ulink url='http://cgit.openembedded.org/meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee'>commit</ulink>
2143 where the <filename>linux.inc</filename> file in
2144 <filename>meta-oe</filename> was updated.
2145 </para>
2146
2147 <para>
2148 Recipes that rely on the kernel source code and do not inherit
2149 the module classes might need to add explicit dependencies on
2150 the <filename>do_shared_workdir</filename> kernel task, for example:
2151 <literallayout class='monospaced'>
2152 do_configure[depends] += "virtual/kernel:do_shared_workdir"
2153 </literallayout>
2154 </para>
2155 </section>
2156
2157 <section id='migration-1.8-ssl'>
2158 <title>SSL 3.0 is Now Disabled in OpenSSL</title>
2159
2160 <para>
2161 SSL 3.0 is now disabled when building OpenSSL.
2162 Disabling SSL 3.0 avoids any lingering instances of the POODLE
2163 vulnerability.
2164 If you feel you must re-enable SSL 3.0, then you can add an
2165 append file (<filename>*.bbappend</filename>) for the
2166 <filename>openssl</filename> recipe to remove "-no-ssl3"
2167 from
2168 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>.
2169 </para>
2170 </section>
2171
2172 <section id='migration-1.8-default-sysroot-poisoning'>
2173 <title>Default Sysroot Poisoning</title>
2174
2175 <para>
2176 <filename>gcc's</filename> default sysroot and include directories
2177 are now "poisoned".
2178 In other words, the sysroot and include directories are being
2179 redirected to a non-existent location in order to catch when
2180 host directories are being used due to the correct options not
2181 being passed.
2182 This poisoning applies both to the cross-compiler used within the
2183 build and to the cross-compiler produced in the SDK.
2184 </para>
2185
2186 <para>
2187 If this change causes something in the build to fail, it almost
2188 certainly means the various compiler flags and commands are not
2189 being passed correctly to the underlying piece of software.
2190 In such cases, you need to take corrective steps.
2191 </para>
2192 </section>
2193
2194 <section id='migration-1.8-rebuild-improvements'>
2195 <title>Rebuild Improvements</title>
2196
2197 <para>
2198 Changes have been made to the
2199 <link linkend='ref-classes-base'><filename>base</filename></link>,
2200 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>,
2201 and
2202 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
2203 classes to clean out generated files when the
2204 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2205 task needs to be re-executed.
2206 </para>
2207
2208 <para>
2209 One of the improvements is to attempt to run "make clean" during
2210 the <filename>do_configure</filename> task if a
2211 <filename>Makefile</filename> exists.
2212 Some software packages do not provide a working clean target
2213 within their make files.
2214 If you have such recipes, you need to set
2215 <link linkend='var-CLEANBROKEN'><filename>CLEANBROKEN</filename></link>
2216 to "1" within the recipe, for example:
2217 <literallayout class='monospaced'>
2218 CLEANBROKEN = "1"
2219 </literallayout>
2220 </para>
2221 </section>
2222
2223 <section id='migration-1.8-qa-check-and-validation-changes'>
2224 <title>QA Check and Validation Changes</title>
2225
2226 <para>
2227 The following QA Check and Validation Changes have occurred:
2228 <itemizedlist>
2229 <listitem><para>
2230 Usage of <filename>PRINC</filename>
2231 previously triggered a warning.
2232 It now triggers an error.
2233 You should remove any remaining usage of
2234 <filename>PRINC</filename> in any recipe or append file.
2235 </para></listitem>
2236 <listitem><para>
2237 An additional QA check has been added to detect usage of
2238 <filename>${D}</filename> in
2239 <link linkend='var-FILES'><filename>FILES</filename></link>
2240 values where
2241 <link linkend='var-D'><filename>D</filename></link> values
2242 should not be used at all.
2243 The same check ensures that <filename>$D</filename> is used
2244 in
2245 <filename>pkg_preinst/pkg_postinst/pkg_prerm/pkg_postrm</filename>
2246 functions instead of <filename>${D}</filename>.
2247 </para></listitem>
2248 <listitem><para>
2249 <link linkend='var-S'><filename>S</filename></link> now
2250 needs to be set to a valid value within a recipe.
2251 If <filename>S</filename> is not set in the recipe, the
2252 directory is not automatically created.
2253 If <filename>S</filename> does not point to a directory
2254 that exists at the time the
2255 <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
2256 task finishes, a warning will be shown.
2257 </para></listitem>
2258 <listitem><para>
2259 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2260 is now validated for correct formatting of multiple
2261 licenses.
2262 If the format is invalid (e.g. multiple licenses are
2263 specified with no operators to specify how the multiple
2264 licenses interact), then a warning will be shown.
2265 </para></listitem>
2266 </itemizedlist>
2267 </para>
2268 </section>
2269
2270 <section id='migration-1.8-miscellaneous-changes'>
2271 <title>Miscellaneous Changes</title>
2272
2273 <para>
2274 The following miscellaneous changes have occurred:
2275 <itemizedlist>
2276 <listitem><para>
2277 The <filename>send-error-report</filename> script now
2278 expects a "-s" option to be specified before the server
2279 address.
2280 This assumes a server address is being specified.
2281 </para></listitem>
2282 <listitem><para>
2283 The <filename>oe-pkgdata-util</filename> script now
2284 expects a "-p" option to be specified before the
2285 <filename>pkgdata</filename> directory, which is now
2286 optional.
2287 If the <filename>pkgdata</filename> directory is not
2288 specified, the script will run BitBake to query
2289 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
2290 from the build environment.
2291 </para></listitem>
2292 </itemizedlist>
2293 </para>
2294 </section>
2295</section>
2296
2297<section id='moving-to-the-yocto-project-2.0-release'>
2298 <title>Moving to the Yocto Project 2.0 Release</title>
2299
2300 <para>
2301 This section provides migration information for moving to the
2302 Yocto Project 2.0 Release from the prior release.
2303 </para>
2304
2305 <section id='migration-2.0-gcc-5'>
2306 <title>GCC 5</title>
2307
2308 <para>
2309 The default compiler is now GCC 5.2.
2310 This change has required fixes for compilation errors in a number
2311 of other recipes.
2312 </para>
2313
2314 <para>
2315 One important example is a fix for when the Linux kernel freezes at
2316 boot time on ARM when built with GCC 5.
2317 If you are using your own kernel recipe or source tree and
2318 building for ARM, you will likely need to apply this
2319 <ulink url='https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit?id=a077224fd35b2f7fbc93f14cf67074fc792fbac2'>patch</ulink>.
2320 The standard <filename>linux-yocto</filename> kernel source tree
2321 already has a workaround for the same issue.
2322 </para>
2323
2324 <para>
2325 For further details, see
2326 <ulink url='https://gcc.gnu.org/gcc-5/changes.html'></ulink> and
2327 the porting guide at
2328 <ulink url='https://gcc.gnu.org/gcc-5/porting_to.html'></ulink>.
2329 </para>
2330
2331 <para>
2332 Alternatively, you can switch back to GCC 4.9 or 4.8 by
2333 setting <filename>GCCVERSION</filename> in your configuration,
2334 as follows:
2335 <literallayout class='monospaced'>
2336 GCCVERSION = "4.9%"
2337 </literallayout>
2338 </para>
2339 </section>
2340
2341 <section id='migration-2.0-Gstreamer-0.10-removed'>
2342 <title>Gstreamer 0.10 Removed</title>
2343
2344 <para>
2345 Gstreamer 0.10 has been removed in favor of Gstreamer 1.x.
2346 As part of the change, recipes for Gstreamer 0.10 and related
2347 software are now located
2348 in <filename>meta-multimedia</filename>.
2349 This change results in Qt4 having Phonon and Gstreamer
2350 support in QtWebkit disabled by default.
2351 </para>
2352 </section>
2353
2354 <section id='migration-2.0-removed-recipes'>
2355 <title>Removed Recipes</title>
2356
2357 <para>
2358 The following recipes have been moved or removed:
2359 <itemizedlist>
2360 <listitem><para>
2361 <filename>bluez4</filename>: The recipe is obsolete and
2362 has been moved due to <filename>bluez5</filename>
2363 becoming fully integrated.
2364 The <filename>bluez4</filename> recipe now resides in
2365 <filename>meta-oe</filename>.
2366 </para></listitem>
2367 <listitem><para>
2368 <filename>gamin</filename>: The recipe is obsolete and
2369 has been removed.
2370 </para></listitem>
2371 <listitem><para>
2372 <filename>gnome-icon-theme</filename>: The recipe's
2373 functionally has been replaced by
2374 <filename>adwaita-icon-theme</filename>.
2375 </para></listitem>
2376 <listitem><para>
2377 Gstreamer 0.10 Recipes: Recipes for Gstreamer 0.10 have
2378 been removed in favor of the recipes for Gstreamer 1.x.
2379 </para></listitem>
2380 <listitem><para>
2381 <filename>insserv</filename>: The recipe is obsolete and
2382 has been removed.
2383 </para></listitem>
2384 <listitem><para>
2385 <filename>libunique</filename>: The recipe is no longer
2386 used and has been moved to <filename>meta-oe</filename>.
2387 </para></listitem>
2388 <listitem><para>
2389 <filename>midori</filename>: The recipe's functionally
2390 has been replaced by <filename>epiphany</filename>.
2391 </para></listitem>
2392 <listitem><para>
2393 <filename>python-gst</filename>: The recipe is obsolete
2394 and has been removed since it only contains bindings for
2395 Gstreamer 0.10.
2396 </para></listitem>
2397 <listitem><para>
2398 <filename>qt-mobility</filename>: The recipe is obsolete and
2399 has been removed since it requires
2400 <filename>Gstreamer 0.10</filename>, which has been
2401 replaced.
2402 </para></listitem>
2403 <listitem><para>
2404 <filename>subversion</filename>: All 1.6.x versions of this
2405 recipe have been removed.
2406 </para></listitem>
2407 <listitem><para>
2408 <filename>webkit-gtk</filename>: The older 1.8.3 version
2409 of this recipe has been removed in favor of
2410 <filename>webkitgtk</filename>.
2411 </para></listitem>
2412 </itemizedlist>
2413 </para>
2414 </section>
2415
2416 <section id='migration-2.0-bitbake-datastore-improvements'>
2417 <title>BitBake datastore improvements</title>
2418
2419 <para>
2420 The method by which BitBake's datastore handles overrides has
2421 changed.
2422 Overrides are now applied dynamically and
2423 <filename>bb.data.update_data()</filename> is now a no-op.
2424 Thus, <filename>bb.data.update_data()</filename> is no longer
2425 required in order to apply the correct overrides.
2426 In practice, this change is unlikely to require any changes to
2427 Metadata.
2428 However, these minor changes in behavior exist:
2429 <itemizedlist>
2430 <listitem><para>
2431 All potential overrides are now visible in the variable
2432 history as seen when you run the following:
2433 <literallayout class='monospaced'>
2434 $ bitbake -e
2435 </literallayout>
2436 </para></listitem>
2437 <listitem><para>
2438 <filename>d.delVar('</filename><replaceable>VARNAME</replaceable><filename>')</filename> and
2439 <filename>d.setVar('</filename><replaceable>VARNAME</replaceable><filename>', None)</filename>
2440 result in the variable and all of its overrides being
2441 cleared out.
2442 Before the change, only the non-overridden values
2443 were cleared.
2444 </para></listitem>
2445 </itemizedlist>
2446 </para>
2447 </section>
2448
2449 <section id='migration-2.0-shell-message-function-changes'>
2450 <title>Shell Message Function Changes</title>
2451
2452 <para>
2453 The shell versions of the BitBake message functions (i.e.
2454 <filename>bbdebug</filename>, <filename>bbnote</filename>,
2455 <filename>bbwarn</filename>, <filename>bbplain</filename>,
2456 <filename>bberror</filename>, and <filename>bbfatal</filename>)
2457 are now connected through to their BitBake equivalents
2458 <filename>bb.debug()</filename>, <filename>bb.note()</filename>,
2459 <filename>bb.warn()</filename>, <filename>bb.plain()</filename>,
2460 <filename>bb.error()</filename>, and
2461 <filename>bb.fatal()</filename>, respectively.
2462 Thus, those message functions that you would expect to be printed
2463 by the BitBake UI are now actually printed.
2464 In practice, this change means two things:
2465 <itemizedlist>
2466 <listitem><para>
2467 If you now see messages on the console that you did not
2468 previously see as a result of this change, you might
2469 need to clean up the calls to
2470 <filename>bbwarn</filename>, <filename>bberror</filename>,
2471 and so forth.
2472 Or, you might want to simply remove the calls.
2473 </para></listitem>
2474 <listitem><para>
2475 The <filename>bbfatal</filename> message function now
2476 suppresses the full error log in the UI, which means any
2477 calls to <filename>bbfatal</filename> where you still
2478 wish to see the full error log should be replaced by
2479 <filename>die</filename> or
2480 <filename>bbfatal_log</filename>.
2481 </para></listitem>
2482 </itemizedlist>
2483 </para>
2484 </section>
2485
2486 <section id='migration-2.0-extra-development-debug-package-cleanup'>
2487 <title>Extra Development/Debug Package Cleanup</title>
2488
2489 <para>
2490 The following recipes have had extra
2491 <filename>dev/dbg</filename> packages removed:
2492 <itemizedlist>
2493 <listitem><para>
2494 <filename>acl</filename>
2495 </para></listitem>
2496 <listitem><para>
2497 <filename>apmd</filename>
2498 </para></listitem>
2499 <listitem><para>
2500 <filename>aspell</filename>
2501 </para></listitem>
2502 <listitem><para>
2503 <filename>attr</filename>
2504 </para></listitem>
2505 <listitem><para>
2506 <filename>augeas</filename>
2507 </para></listitem>
2508 <listitem><para>
2509 <filename>bzip2</filename>
2510 </para></listitem>
2511 <listitem><para>
2512 <filename>cogl</filename>
2513 </para></listitem>
2514 <listitem><para>
2515 <filename>curl</filename>
2516 </para></listitem>
2517 <listitem><para>
2518 <filename>elfutils</filename>
2519 </para></listitem>
2520 <listitem><para>
2521 <filename>gcc-target</filename>
2522 </para></listitem>
2523 <listitem><para>
2524 <filename>libgcc</filename>
2525 </para></listitem>
2526 <listitem><para>
2527 <filename>libtool</filename>
2528 </para></listitem>
2529 <listitem><para>
2530 <filename>libxmu</filename>
2531 </para></listitem>
2532 <listitem><para>
2533 <filename>opkg</filename>
2534 </para></listitem>
2535 <listitem><para>
2536 <filename>pciutils</filename>
2537 </para></listitem>
2538 <listitem><para>
2539 <filename>rpm</filename>
2540 </para></listitem>
2541 <listitem><para>
2542 <filename>sysfsutils</filename>
2543 </para></listitem>
2544 <listitem><para>
2545 <filename>tiff</filename>
2546 </para></listitem>
2547 <listitem><para>
2548 <filename>xz</filename>
2549 </para></listitem>
2550 </itemizedlist>
2551 All of the above recipes now conform to the standard packaging
2552 scheme where a single <filename>-dev</filename>,
2553 <filename>-dbg</filename>, and <filename>-staticdev</filename>
2554 package exists per recipe.
2555 </para>
2556 </section>
2557
2558 <section id='migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core'>
2559 <title>Recipe Maintenance Tracking Data Moved to OE-Core</title>
2560
2561 <para>
2562 Maintenance tracking data for recipes that was previously part
2563 of <filename>meta-yocto</filename> has been moved to
2564 <link linkend='oe-core'>OE-Core</link>.
2565 The change includes <filename>package_regex.inc</filename> and
2566 <filename>distro_alias.inc</filename>, which are typically enabled
2567 when using the <filename>distrodata</filename> class.
2568 Additionally, the contents of
2569 <filename>upstream_tracking.inc</filename> has now been split out
2570 to the relevant recipes.
2571 </para>
2572 </section>
2573
2574 <section id='migration-2.0-automatic-stale-sysroot-file-cleanup'>
2575 <title>Automatic Stale Sysroot File Cleanup</title>
2576
2577 <para>
2578 Stale files from recipes that no longer exist in the current
2579 configuration are now automatically removed from
2580 sysroot as well as removed from
2581 any other place managed by shared state.
2582 This automatic cleanup means that the build system now properly
2583 handles situations such as renaming the build system side of
2584 recipes, removal of layers from
2585 <filename>bblayers.conf</filename>, and
2586 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
2587 changes.
2588 </para>
2589
2590 <para>
2591 Additionally, work directories for old versions of recipes are
2592 now pruned.
2593 If you wish to disable pruning old work directories, you can set
2594 the following variable in your configuration:
2595 <literallayout class='monospaced'>
2596 SSTATE_PRUNE_OBSOLETEWORKDIR = "0"
2597 </literallayout>
2598 </para>
2599 </section>
2600
2601 <section id='migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source'>
2602 <title><filename>linux-yocto</filename> Kernel Metadata Repository Now Split from Source</title>
2603
2604 <para>
2605 The <filename>linux-yocto</filename> tree has up to now been a
2606 combined set of kernel changes and configuration (meta) data
2607 carried in a single tree.
2608 While this format is effective at keeping kernel configuration and
2609 source modifications synchronized, it is not always obvious to
2610 developers how to manipulate the Metadata as compared to the
2611 source.
2612 </para>
2613
2614 <para>
2615 Metadata processing has now been removed from the
2616 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
2617 class and the external Metadata repository
2618 <filename>yocto-kernel-cache</filename>, which has always been used
2619 to seed the <filename>linux-yocto</filename> "meta" branch.
2620 This separate <filename>linux-yocto</filename> cache repository
2621 is now the primary location for this data.
2622 Due to this change, <filename>linux-yocto</filename> is no longer
2623 able to process combined trees.
2624 Thus, if you need to have your own combined kernel repository,
2625 you must do the split there as well and update your recipes
2626 accordingly.
2627 See the <filename>meta/recipes-kernel/linux/linux-yocto_4.1.bb</filename>
2628 recipe for an example.
2629 </para>
2630 </section>
2631
2632 <section id='migration-2.0-additional-qa-checks'>
2633 <title>Additional QA checks</title>
2634
2635 <para>
2636 The following QA checks have been added:
2637 <itemizedlist>
2638 <listitem><para>
2639 Added a "host-user-contaminated" check for ownership
2640 issues for packaged files outside of
2641 <filename>/home</filename>.
2642 The check looks for files that are incorrectly owned by the
2643 user that ran BitBake instead of owned by a valid user in
2644 the target system.
2645 </para></listitem>
2646 <listitem><para>
2647 Added an "invalid-chars" check for invalid (non-UTF8)
2648 characters in recipe metadata variable values
2649 (i.e.
2650 <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>,
2651 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>,
2652 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>,
2653 and
2654 <link linkend='var-SECTION'><filename>SECTION</filename></link>).
2655 Some package managers do not support these characters.
2656 </para></listitem>
2657 <listitem><para>
2658 Added an "invalid-packageconfig" check for any options
2659 specified in
2660 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
2661 that do not match any <filename>PACKAGECONFIG</filename>
2662 option defined for the recipe.
2663 </para></listitem>
2664 </itemizedlist>
2665 </para>
2666 </section>
2667
2668 <section id='migration-2.0-miscellaneous'>
2669 <title>Miscellaneous Changes</title>
2670
2671 <para>
2672 These additional changes exist:
2673 <itemizedlist>
2674 <listitem><para>
2675 <filename>gtk-update-icon-cache</filename> has been
2676 renamed to <filename>gtk-icon-utils</filename>.
2677 </para></listitem>
2678 <listitem><para>
2679 The <filename>tools-profile</filename>
2680 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
2681 item as well as its corresponding packagegroup and
2682 <filename>packagegroup-core-tools-profile</filename> no
2683 longer bring in <filename>oprofile</filename>.
2684 Bringing in <filename>oprofile</filename> was originally
2685 added to aid compilation on resource-constrained
2686 targets.
2687 However, this aid has not been widely used and is not
2688 likely to be used going forward due to the more powerful
2689 target platforms and the existence of better
2690 cross-compilation tools.
2691 </para></listitem>
2692 <listitem><para>
2693 The
2694 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
2695 variable's default value now specifies
2696 <filename>ext4</filename> instead of
2697 <filename>ext3</filename>.
2698 </para></listitem>
2699 <listitem><para>
2700 All support for the <filename>PRINC</filename>
2701 variable has been removed.
2702 </para></listitem>
2703 <listitem><para>
2704 The <filename>packagegroup-core-full-cmdline</filename>
2705 packagegroup no longer brings in
2706 <filename>lighttpd</filename> due to the fact that
2707 bringing in <filename>lighttpd</filename> is not really in
2708 line with the packagegroup's purpose, which is to add full
2709 versions of command-line tools that by default are
2710 provided by <filename>busybox</filename>.
2711 </para></listitem>
2712 </itemizedlist>
2713 </para>
2714 </section>
2715</section>
2716
2717<section id='moving-to-the-yocto-project-2.1-release'>
2718 <title>Moving to the Yocto Project 2.1 Release</title>
2719
2720 <para>
2721 This section provides migration information for moving to the
2722 Yocto Project 2.1 Release from the prior release.
2723 </para>
2724
2725 <section id='migration-2.1-variable-expansion-in-python-functions'>
2726 <title>Variable Expansion in Python Functions</title>
2727
2728 <para>
2729 Variable expressions, such as
2730 <filename>${</filename><replaceable>VARNAME</replaceable><filename>}</filename>
2731 no longer expand automatically within Python functions.
2732 Suppressing expansion was done to allow Python functions to
2733 construct shell scripts or other code for situations in which you
2734 do not want such expressions expanded.
2735 For any existing code that relies on these expansions, you need to
2736 change the expansions to expand the value of individual
2737 variables through <filename>d.getVar()</filename>.
2738 To alternatively expand more complex expressions,
2739 use <filename>d.expand()</filename>.
2740 </para>
2741 </section>
2742
2743 <section id='migration-2.1-overrides-must-now-be-lower-case'>
2744 <title>Overrides Must Now be Lower-Case</title>
2745
2746 <para>
2747 The convention for overrides has always been for them to be
2748 lower-case characters.
2749 This practice is now a requirement as BitBake's datastore now
2750 assumes lower-case characters in order to give a slight performance
2751 boost during parsing.
2752 In practical terms, this requirement means that anything that ends
2753 up in
2754 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
2755 must now appear in lower-case characters (e.g. values for
2756 <filename>MACHINE</filename>, <filename>TARGET_ARCH</filename>,
2757 <filename>DISTRO</filename>, and also recipe names if
2758 <filename>_pn-</filename><replaceable>recipename</replaceable>
2759 overrides are to be effective).
2760 </para>
2761 </section>
2762
2763 <section id='migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory'>
2764 <title>Expand Parameter to <filename>getVar()</filename> and
2765 <filename>getVarFlag()</filename> is Now Mandatory</title>
2766
2767 <para>
2768 The expand parameter to <filename>getVar()</filename> and
2769 <filename>getVarFlag()</filename> previously defaulted to
2770 False if not specified.
2771 Now, however, no default exists so one must be specified.
2772 You must change any <filename>getVar()</filename> calls that
2773 do not specify the final expand parameter to calls that do specify
2774 the parameter.
2775 You can run the following <filename>sed</filename> command at the
2776 base of a layer to make this change:
2777 <literallayout class='monospaced'>
2778 sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
2779 sed -e 's:\(\.getVarFlag([^,()]*, [^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
2780 </literallayout>
2781 <note>
2782 The reason for this change is that it prepares the way for
2783 changing the default to True in a future Yocto Project release.
2784 This future change is a much more sensible default than False.
2785 However, the change needs to be made gradually as a sudden
2786 change of the default would potentially cause side-effects
2787 that would be difficult to detect.
2788 </note>
2789 </para>
2790 </section>
2791
2792 <section id='migration-2.1-makefile-environment-changes'>
2793 <title>Makefile Environment Changes</title>
2794
2795 <para>
2796 <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link>
2797 now defaults to "" instead of "-e MAKEFLAGS=".
2798 Setting <filename>EXTRA_OEMAKE</filename> to "-e MAKEFLAGS=" by
2799 default was a historical accident that has required many classes
2800 (e.g. <filename>autotools</filename>, <filename>module</filename>)
2801 and recipes to override this default in order to work with
2802 sensible build systems.
2803 When upgrading to the release, you must edit any recipe that
2804 relies upon this old default by either setting
2805 <filename>EXTRA_OEMAKE</filename> back to "-e MAKEFLAGS=" or by
2806 explicitly setting any required variable value overrides using
2807 <filename>EXTRA_OEMAKE</filename>, which is typically only needed
2808 when a Makefile sets a default value for a variable that is
2809 inappropriate for cross-compilation using the "=" operator rather
2810 than the "?=" operator.
2811 </para>
2812 </section>
2813
2814 <section id='migration-2.1-libexecdir-reverted-to-prefix-libexec'>
2815 <title><filename>libexecdir</filename> Reverted to <filename>${prefix}/libexec</filename></title>
2816
2817 <para>
2818 The use of <filename>${libdir}/${BPN}</filename> as
2819 <filename>libexecdir</filename> is different as compared to all
2820 other mainstream distributions, which either uses
2821 <filename>${prefix}/libexec</filename> or
2822 <filename>${libdir}</filename>.
2823 The use is also contrary to the GNU Coding Standards
2824 (i.e. <ulink url='https://www.gnu.org/prep/standards/html_node/Directory-Variables.html'></ulink>)
2825 that suggest <filename>${prefix}/libexec</filename> and also
2826 notes that any package-specific nesting should be done by the
2827 package itself.
2828 Finally, having <filename>libexecdir</filename> change between
2829 recipes makes it very difficult for different recipes to invoke
2830 binaries that have been installed into
2831 <filename>libexecdir</filename>.
2832 The Filesystem Hierarchy Standard
2833 (i.e. <ulink url='http://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html'></ulink>)
2834 now recognizes the use of <filename>${prefix}/libexec/</filename>,
2835 giving distributions the choice between
2836 <filename>${prefix}/lib</filename> or
2837 <filename>${prefix}/libexec</filename> without breaking FHS.
2838 </para>
2839 </section>
2840
2841 <section id='migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files'>
2842 <title><filename>ac_cv_sizeof_off_t</filename> is No Longer Cached in Site Files</title>
2843
2844 <para>
2845 For recipes inheriting the
2846 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2847 class, <filename>ac_cv_sizeof_off_t</filename> is no longer cached
2848 in the site files for <filename>autoconf</filename>.
2849 The reason for this change is because the
2850 <filename>ac_cv_sizeof_off_t</filename> value is not necessarily
2851 static per architecture as was previously assumed.
2852 Rather, the value changes based on whether large file support is
2853 enabled.
2854 For most software that uses <filename>autoconf</filename>, this
2855 change should not be a problem.
2856 However, if you have a recipe that bypasses the standard
2857 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2858 task from the <filename>autotools</filename> class and the software
2859 the recipe is building uses a very old version of
2860 <filename>autoconf</filename>, the recipe might be incapable of
2861 determining the correct size of <filename>off_t</filename> during
2862 <filename>do_configure</filename>.
2863 </para>
2864
2865 <para>
2866 The best course of action is to patch the software as necessary
2867 to allow the default implementation from the
2868 <filename>autotools</filename> class to work such that
2869 <filename>autoreconf</filename> succeeds and produces a working
2870 configure script, and to remove the
2871 overridden <filename>do_configure</filename> task such that the
2872 default implementation does get used.
2873 </para>
2874 </section>
2875
2876 <section id='migration-2.1-image-generation-split-out-from-filesystem-generation'>
2877 <title>Image Generation is Now Split Out from Filesystem Generation</title>
2878
2879 <para>
2880 Previously, for image recipes the
2881 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
2882 task assembled the filesystem and then from that filesystem
2883 generated images.
2884 With this Yocto Project release, image generation is split into
2885 separate
2886 <link linkend='ref-tasks-image'><filename>do_image_*</filename></link>
2887 tasks for clarity both in operation and in the code.
2888 </para>
2889
2890 <para>
2891 For most cases, this change does not present any problems.
2892 However, if you have made customizations that directly modify the
2893 <filename>do_rootfs</filename> task or that mention
2894 <filename>do_rootfs</filename>, you might need to update those
2895 changes.
2896 In particular, if you had added any tasks after
2897 <filename>do_rootfs</filename>, you should make edits so that
2898 those tasks are after the
2899 <link linkend='ref-tasks-image-complete'><filename>do_image_complete</filename></link>
2900 task rather than after <filename>do_rootfs</filename>
2901 so that the your added tasks
2902 run at the correct time.
2903 </para>
2904
2905 <para>
2906 A minor part of this restructuring is that the post-processing
2907 definitions and functions have been moved from the
2908 <link linkend='ref-classes-image'><filename>image</filename></link>
2909 class to the
2910 <link linkend='ref-classes-rootfs*'><filename>rootfs-postcommands</filename></link>
2911 class.
2912 Functionally, however, they remain unchanged.
2913 </para>
2914 </section>
2915
2916 <section id='migration-2.1-removed-recipes'>
2917 <title>Removed Recipes</title>
2918
2919 <para>
2920 The following recipes have been removed in the 2.1 release:
2921 <itemizedlist>
2922 <listitem><para><filename>gcc</filename> version 4.8:
2923 Versions 4.9 and 5.3 remain.
2924 </para></listitem>
2925 <listitem><para><filename>qt4</filename>:
2926 All support for Qt 4.x has been moved out to a separate
2927 <filename>meta-qt4</filename> layer because Qt 4 is no
2928 longer supported upstream.
2929 </para></listitem>
2930 <listitem><para><filename>x11vnc</filename>:
2931 Moved to the <filename>meta-oe</filename> layer.
2932 </para></listitem>
2933 <listitem><para><filename>linux-yocto-3.14</filename>:
2934 No longer supported.
2935 </para></listitem>
2936 <listitem><para><filename>linux-yocto-3.19</filename>:
2937 No longer supported.
2938 </para></listitem>
2939 <listitem><para><filename>libjpeg</filename>:
2940 Replaced by the <filename>libjpeg-turbo</filename> recipe.
2941 </para></listitem>
2942 <listitem><para><filename>pth</filename>:
2943 Became obsolete.
2944 </para></listitem>
2945 <listitem><para><filename>liboil</filename>:
2946 Recipe is no longer needed and has been moved to the
2947 <filename>meta-multimedia</filename> layer.
2948 </para></listitem>
2949 <listitem><para><filename>gtk-theme-torturer</filename>:
2950 Recipe is no longer needed and has been moved to the
2951 <filename>meta-gnome</filename> layer.
2952 </para></listitem>
2953 <listitem><para><filename>gnome-mime-data</filename>:
2954 Recipe is no longer needed and has been moved to the
2955 <filename>meta-gnome</filename> layer.
2956 </para></listitem>
2957 <listitem><para><filename>udev</filename>:
2958 Replaced by the <filename>eudev</filename> recipe for
2959 compatibility when using <filename>sysvinit</filename>
2960 with newer kernels.
2961 </para></listitem>
2962 <listitem><para><filename>python-pygtk</filename>:
2963 Recipe became obsolete.
2964 </para></listitem>
2965 <listitem><para><filename>adt-installer</filename>:
2966 Recipe became obsolete.
2967 See the
2968 "<link linkend='migration-2.1-adt-removed'>ADT Removed</link>"
2969 section for more information.
2970 </para></listitem>
2971 </itemizedlist>
2972 </para>
2973 </section>
2974
2975 <section id='migration-2.1-class-changes'>
2976 <title>Class Changes</title>
2977
2978 <para>
2979 The following classes have changed:
2980 <itemizedlist>
2981 <listitem><para><filename>autotools_stage</filename>:
2982 Removed because the
2983 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2984 class now provides its functionality.
2985 Recipes that inherited from
2986 <filename>autotools_stage</filename> should now inherit
2987 from <filename>autotools</filename> instead.
2988 </para></listitem>
2989 <listitem><para><filename>boot-directdisk</filename>:
2990 Merged into the <filename>image-vm</filename>
2991 class.
2992 The <filename>boot-directdisk</filename> class was rarely
2993 directly used.
2994 Consequently, this change should not cause any issues.
2995 </para></listitem>
2996 <listitem><para><filename>bootimg</filename>:
2997 Merged into the
2998 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
2999 class.
3000 The <filename>bootimg</filename> class was rarely
3001 directly used.
3002 Consequently, this change should not cause any issues.
3003 </para></listitem>
3004 <listitem><para><filename>packageinfo</filename>:
3005 Removed due to its limited use by the Hob UI, which has
3006 itself been removed.
3007 </para></listitem>
3008 </itemizedlist>
3009 </para>
3010 </section>
3011
3012 <section id='migration-2.1-build-system-ui-changes'>
3013 <title>Build System User Interface Changes</title>
3014
3015 <para>
3016 The following changes have been made to the build system user
3017 interface:
3018 <itemizedlist>
3019 <listitem><para><emphasis>Hob GTK+-based UI</emphasis>:
3020 Removed because it is unmaintained and based on the
3021 outdated GTK+ 2 library.
3022 The Toaster web-based UI is much more capable and is
3023 actively maintained.
3024 See the
3025 "<ulink url='&YOCTO_DOCS_TOAST_URL;#using-the-toaster-web-interface'>Using the Toaster Web Interface</ulink>"
3026 section in the Toaster User Manual for more
3027 information on this interface.
3028 </para></listitem>
3029 <listitem><para><emphasis>"puccho" BitBake UI</emphasis>:
3030 Removed because is unmaintained and no longer useful.
3031 </para></listitem>
3032 </itemizedlist>
3033 </para>
3034 </section>
3035
3036 <section id='migration-2.1-adt-removed'>
3037 <title>ADT Removed</title>
3038
3039 <para>
3040 The Application Development Toolkit (ADT) has been removed
3041 because its functionality almost completely overlapped with the
3042 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-using-the-standard-sdk'>standard SDK</ulink>
3043 and the
3044 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>.
3045 For information on these SDKs and how to build and use them, see the
3046 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
3047 manual.
3048 <note>
3049 The Yocto Project Eclipse IDE Plug-in is still supported and
3050 is not affected by this change.
3051 </note>
3052 </para>
3053 </section>
3054
3055 <section id='migration-2.1-poky-reference-distribution-changes'>
3056 <title>Poky Reference Distribution Changes</title>
3057
3058 <para>
3059 The following changes have been made for the Poky distribution:
3060 <itemizedlist>
3061 <listitem><para>
3062 The <filename>meta-yocto</filename> layer has been renamed
3063 to <filename>meta-poky</filename> to better match its
3064 purpose, which is to provide the Poky reference
3065 distribution.
3066 The <filename>meta-yocto-bsp</filename> layer retains its
3067 original name since it provides reference machines for
3068 the Yocto Project and it is otherwise unrelated to Poky.
3069 References to <filename>meta-yocto</filename> in your
3070 <filename>conf/bblayers.conf</filename> should
3071 automatically be updated, so you should not need to change
3072 anything unless you are relying on this naming elsewhere.
3073 </para></listitem>
3074 <listitem><para>
3075 The
3076 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
3077 class is now enabled by default in Poky.
3078 This class attempts to isolate the build system from the
3079 host distribution's C library and makes re-use of native
3080 shared state artifacts across different host distributions
3081 practical.
3082 With this class enabled, a tarball containing a pre-built
3083 C library is downloaded at the start of the build.</para>
3084
3085 <para>The <filename>uninative</filename> class is enabled
3086 through the
3087 <filename>meta/conf/distro/include/yocto-uninative.inc</filename>
3088 file, which for those not using the Poky distribution, can
3089 include to easily enable the same functionality.</para>
3090
3091 <para>Alternatively, if you wish to build your own
3092 <filename>uninative</filename> tarball, you can do so by
3093 building the <filename>uninative-tarball</filename> recipe,
3094 making it available to your build machines
3095 (e.g. over HTTP/HTTPS) and setting a similar configuration
3096 as the one set by <filename>yocto-uninative.inc</filename>.
3097 </para></listitem>
3098 <listitem><para>
3099 Static library generation, for most cases, is now disabled
3100 by default in the Poky distribution.
3101 Disabling this generation saves some build time as well
3102 as the size used for build output artifacts.</para>
3103
3104 <para>Disabling this library generation is accomplished
3105 through a
3106 <filename>meta/conf/distro/include/no-static-libs.inc</filename>,
3107 which for those not using the Poky distribution can
3108 easily include to enable the same functionality.</para>
3109
3110 <para>Any recipe that needs to opt-out of having the
3111 "--disable-static" option specified on the configure
3112 command line either because it is not a supported option
3113 for the configure script or because static libraries are
3114 needed should set the following variable:
3115 <literallayout class='monospaced'>
3116 DISABLE_STATIC = ""
3117 </literallayout>
3118 </para></listitem>
3119 <listitem><para>
3120 The separate <filename>poky-tiny</filename> distribution
3121 now uses the musl C library instead of a heavily pared
3122 down <filename>glibc</filename>.
3123 Using musl results in a smaller
3124 distribution and facilitates much greater maintainability
3125 because musl is designed to have a small footprint.</para>
3126
3127 <para>If you have used <filename>poky-tiny</filename> and
3128 have customized the <filename>glibc</filename>
3129 configuration you will need to redo those customizations
3130 with musl when upgrading to the new release.
3131 </para></listitem>
3132 </itemizedlist>
3133 </para>
3134 </section>
3135
3136 <section id='migration-2.1-packaging-changes'>
3137 <title>Packaging Changes</title>
3138
3139 <para>
3140 The following changes have been made to packaging:
3141 <itemizedlist>
3142 <listitem><para>
3143 The <filename>runuser</filename> and
3144 <filename>mountpoint</filename> binaries, which were
3145 previously in the main <filename>util-linux</filename>
3146 package, have been split out into the
3147 <filename>util-linux-runuser</filename> and
3148 <filename>util-linux-mountpoint</filename> packages,
3149 respectively.
3150 </para></listitem>
3151 <listitem><para>
3152 The <filename>python-elementtree</filename> package has
3153 been merged into the <filename>python-xml</filename>
3154 package.
3155 </para></listitem>
3156 </itemizedlist>
3157 </para>
3158 </section>
3159
3160 <section id='migration-2.1-tuning-file-changes'>
3161 <title>Tuning File Changes</title>
3162
3163 <para>
3164 The following changes have been made to the tuning files:
3165 <itemizedlist>
3166 <listitem><para>
3167 The "no-thumb-interwork" tuning feature has been dropped
3168 from the ARM tune include files.
3169 Because interworking is required for ARM EABI, attempting
3170 to disable it through a tuning feature no longer makes
3171 sense.
3172 <note>
3173 Support for ARM OABI was deprecated in gcc 4.7.
3174 </note>
3175 </para></listitem>
3176 <listitem><para>
3177 The <filename>tune-cortexm*.inc</filename> and
3178 <filename>tune-cortexr4.inc</filename> files have been
3179 removed because they are poorly tested.
3180 Until the OpenEmbedded build system officially gains
3181 support for CPUs without an MMU, these tuning files would
3182 probably be better maintained in a separate layer
3183 if needed.
3184 </para></listitem>
3185 </itemizedlist>
3186 </para>
3187 </section>
3188
3189 <section id='migration-2.1-supporting-gobject-introspection'>
3190 <title>Supporting GObject Introspection</title>
3191
3192 <para>
3193 This release supports generation of GLib Introspective
3194 Repository (GIR) files through GObject introspection, which is
3195 the standard mechanism for accessing GObject-based software from
3196 runtime environments.
3197 You can enable, disable, and test the generation of this data.
3198 See the
3199 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-gobject-introspection-support'>Enabling GObject Introspection Support</ulink>"
3200 section in the Yocto Project Development Tasks Manual
3201 for more information.
3202 </para>
3203 </section>
3204
3205 <section id='migration-2.1-miscellaneous-changes'>
3206 <title>Miscellaneous Changes</title>
3207
3208 <para>
3209 These additional changes exist:
3210 <itemizedlist>
3211 <listitem><para>
3212 The minimum Git version has been increased to 1.8.3.1.
3213 If your host distribution does not provide a sufficiently
3214 recent version, you can install the buildtools, which
3215 will provide it.
3216 See the
3217 "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>"
3218 section for more information on the buildtools tarball.
3219 </para></listitem>
3220 <listitem><para>
3221 The buggy and incomplete support for the RPM version 4
3222 package manager has been removed.
3223 The well-tested and maintained support for RPM version 5
3224 remains.
3225 </para></listitem>
3226 <listitem><para>
3227 Previously, the following list of packages were removed
3228 if package-management was not in
3229 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>,
3230 regardless of any dependencies:
3231 <literallayout class='monospaced'>
3232 update-rc.d
3233 base-passwd
3234 shadow
3235 update-alternatives
3236 run-postinsts
3237 </literallayout>
3238 With the Yocto Project 2.1 release, these packages are only
3239 removed if "read-only-rootfs" is in
3240 <filename>IMAGE_FEATURES</filename>, since they might
3241 still be needed for a read-write image even in the absence
3242 of a package manager (e.g. if users need to be added,
3243 modified, or removed at runtime).
3244 </para></listitem>
3245 <listitem><para>
3246 The
3247 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'><filename>devtool modify</filename></ulink>
3248 command now defaults to extracting the source since that
3249 is most commonly expected.
3250 The "-x" or "--extract" options are now no-ops.
3251 If you wish to provide your own existing source tree, you
3252 will now need to specify either the "-n" or
3253 "--no-extract" options when running
3254 <filename>devtool modify</filename>.
3255 </para></listitem>
3256 <listitem><para>
3257 If the formfactor for a machine is either not supplied
3258 or does not specify whether a keyboard is attached, then
3259 the default is to assume a keyboard is attached rather
3260 than assume no keyboard.
3261 This change primarily affects the Sato UI.
3262 </para></listitem>
3263 <listitem><para>
3264 The <filename>.debug</filename> directory packaging is
3265 now automatic.
3266 If your recipe builds software that installs binaries into
3267 directories other than the standard ones, you no longer
3268 need to take care of setting
3269 <filename>FILES_${PN}-dbg</filename> to pick up the
3270 resulting <filename>.debug</filename> directories as these
3271 directories are automatically found and added.
3272 </para></listitem>
3273 <listitem><para>
3274 Inaccurate disk and CPU percentage data has been dropped
3275 from <filename>buildstats</filename> output.
3276 This data has been replaced with
3277 <filename>getrusage()</filename> data and corrected IO
3278 statistics.
3279 You will probably need to update any custom code that reads
3280 the <filename>buildstats</filename> data.
3281 </para></listitem>
3282 <listitem><para>
3283 The
3284 <filename>meta/conf/distro/include/package_regex.inc</filename>
3285 is now deprecated.
3286 The contents of this file have been moved to individual
3287 recipes.
3288 <note><title>Tip</title>
3289 Because this file will likely be removed in a future
3290 Yocto Project release, it is suggested that you remove
3291 any references to the file that might be in your
3292 configuration.
3293 </note>
3294 </para></listitem>
3295 <listitem><para>
3296 The <filename>v86d/uvesafb</filename> has been removed from
3297 the <filename>genericx86</filename> and
3298 <filename>genericx86-64</filename> reference machines,
3299 which are provided by the
3300 <filename>meta-yocto-bsp</filename> layer.
3301 Most modern x86 boards do not rely on this file and it only
3302 adds kernel error messages during startup.
3303 If you do still need to support
3304 <filename>uvesafb</filename>, you can
3305 simply add <filename>v86d</filename> to your image.
3306 </para></listitem>
3307 <listitem><para>
3308 Build sysroot paths are now removed from debug symbol
3309 files.
3310 Removing these paths means that remote GDB using an
3311 unstripped build system sysroot will no longer work
3312 (although this was never documented to work).
3313 The supported method to accomplish something similar is
3314 to set <filename>IMAGE_GEN_DEBUGFS</filename> to "1",
3315 which will generate a companion debug image
3316 containing unstripped binaries and associated debug
3317 sources alongside the image.
3318 </para></listitem>
3319 </itemizedlist>
3320 </para>
3321 </section>
3322</section>
3323
3324<section id='moving-to-the-yocto-project-2.2-release'>
3325 <title>Moving to the Yocto Project 2.2 Release</title>
3326
3327 <para>
3328 This section provides migration information for moving to the
3329 Yocto Project 2.2 Release from the prior release.
3330 </para>
3331
3332 <section id='migration-2.2-minimum-kernel-version'>
3333 <title>Minimum Kernel Version</title>
3334
3335 <para>
3336 The minimum kernel version for the target system and for SDK
3337 is now 3.2.0, due to the upgrade
3338 to <filename>glibc 2.24</filename>.
3339 Specifically, for AArch64-based targets the version is
3340 3.14.
3341 For Nios II-based targets, the minimum kernel version is 3.19.
3342 <note>
3343 For x86 and x86_64, you can reset
3344 <link linkend='var-OLDEST_KERNEL'><filename>OLDEST_KERNEL</filename></link>
3345 to anything down to 2.6.32 if desired.
3346 </note>
3347 </para>
3348 </section>
3349
3350 <section id='migration-2.2-staging-directories-in-sysroot-simplified'>
3351 <title>Staging Directories in Sysroot Has Been Simplified</title>
3352
3353 <para>
3354 The way directories are staged in sysroot has been simplified and
3355 introduces the new
3356 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>,
3357 <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>,
3358 and
3359 <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link>.
3360 See the
3361 <ulink url='http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html'>v2 patch series on the OE-Core Mailing List</ulink>
3362 for additional information.
3363 </para>
3364 </section>
3365
3366 <section id='migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled'>
3367 <title>Removal of Old Images and Other Files in <filename>tmp/deploy</filename> Now Enabled</title>
3368
3369 <para>
3370 Removal of old images and other files in
3371 <filename>tmp/deploy/</filename> is now enabled by default due
3372 to a new staging method used for those files.
3373 As a result of this change, the
3374 <filename>RM_OLD_IMAGE</filename> variable is now redundant.
3375 </para>
3376 </section>
3377
3378 <section id='migration-2.2-python-changes'>
3379 <title>Python Changes</title>
3380
3381 <para>
3382 The following changes for Python occurred:
3383 </para>
3384
3385 <section id='migration-2.2-bitbake-now-requires-python-3.4'>
3386 <title>BitBake Now Requires Python 3.4+</title>
3387
3388 <para>
3389 BitBake requires Python 3.4 or greater.
3390 </para>
3391 </section>
3392
3393 <section id='migration-2.2-utf-8-locale-required-on-build-host'>
3394 <title>UTF-8 Locale Required on Build Host</title>
3395
3396 <para>
3397 A UTF-8 locale is required on the build host due to Python 3.
3398 Since C.UTF-8 is not a standard, the default is en_US.UTF-8.
3399 </para>
3400 </section>
3401
3402 <section id='migration-2.2-metadata-now-must-use-python-3-syntax'>
3403 <title>Metadata Must Now Use Python 3 Syntax</title>
3404
3405 <para>
3406 The metadata is now required to use Python 3 syntax.
3407 For help preparing metadata, see any of the many Python 3 porting
3408 guides available.
3409 Alternatively, you can reference the conversion commits for Bitbake
3410 and you can use
3411 <link linkend='oe-core'>OE-Core</link> as a guide for changes.
3412 Following are particular areas of interest:
3413 <literallayout class='monospaced'>
3414 * subprocess command-line pipes needing locale decoding
3415 * the syntax for octal values changed
3416 * the <filename>iter*()</filename> functions changed name
3417 * iterators now return views, not lists
3418 * changed names for Python modules
3419 </literallayout>
3420 </para>
3421 </section>
3422
3423 <section id='migration-2.2-target-python-recipes-switched-to-python-3'>
3424 <title>Target Python Recipes Switched to Python 3</title>
3425
3426 <para>
3427 Most target Python recipes have now been switched to Python 3.
3428 Unfortunately, systems using RPM as a package manager and
3429 providing online package-manager support through SMART still
3430 require Python 2.
3431 <note>
3432 Python 2 and recipes that use it can still be built for the
3433 target as with previous versions.
3434 </note>
3435 </para>
3436 </section>
3437
3438 <section id='migration-2.2-buildtools-tarball-includes-python-3'>
3439 <title><filename>buildtools-tarball</filename> Includes Python 3</title>
3440
3441 <para>
3442 <filename>buildtools-tarball</filename> now includes Python 3.
3443 </para>
3444 </section>
3445 </section>
3446
3447 <section id='migration-2.2-uclibc-replaced-by-musl'>
3448 <title>uClibc Replaced by musl</title>
3449
3450 <para>
3451 uClibc has been removed in favor of musl.
3452 Musl has matured, is better maintained, and is compatible with a
3453 wider range of applications as compared to uClibc.
3454 </para>
3455 </section>
3456
3457 <section id='migration-2.2-B-no-longer-default-working-directory-for-tasks'>
3458 <title><filename>${B}</filename> No Longer Default Working Directory for Tasks</title>
3459
3460 <para>
3461 <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>
3462 is no longer the default working directory for tasks.
3463 Consequently, any custom tasks you define now need to either
3464 have the
3465 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>dirs</filename></ulink><filename>]</filename> flag set, or the task needs to change into the
3466 appropriate working directory manually (e.g using
3467 <filename>cd</filename> for a shell task).
3468 <note>
3469 The preferred method is to use the
3470 <filename>[dirs]</filename> flag.
3471 </note>
3472 </para>
3473 </section>
3474
3475 <section id='migration-2.2-runqemu-ported-to-python'>
3476 <title><filename>runqemu</filename> Ported to Python</title>
3477
3478 <para>
3479 <filename>runqemu</filename> has been ported to Python and has
3480 changed behavior in some cases.
3481 Previous usage patterns continue to be supported.
3482 </para>
3483
3484 <para>
3485 The new <filename>runqemu</filename> is a Python script.
3486 Machine knowledge is no longer hardcoded into
3487 <filename>runqemu</filename>.
3488 You can choose to use the <filename>qemuboot</filename>
3489 configuration file to define the BSP's own arguments and to make
3490 it bootable with <filename>runqemu</filename>.
3491 If you use a configuration file, use the following form:
3492 <literallayout class='monospaced'>
3493 <replaceable>image-name</replaceable>-<replaceable>machine</replaceable>.qemuboot.conf
3494 </literallayout>
3495 The configuration file enables fine-grained tuning of options
3496 passed to QEMU without the <filename>runqemu</filename> script
3497 hard-coding any knowledge about different machines.
3498 Using a configuration file is particularly convenient when trying
3499 to use QEMU with machines other than the
3500 <filename>qemu*</filename> machines in
3501 <link linkend='oe-core'>OE-Core</link>.
3502 The <filename>qemuboot.conf</filename> file is generated by the
3503 <filename>qemuboot</filename>
3504 class when the root filesystem is being build (i.e.
3505 build rootfs).
3506 QEMU boot arguments can be set in BSP's configuration file and
3507 the <filename>qemuboot</filename> class will save them to
3508 <filename>qemuboot.conf</filename>.
3509 </para>
3510
3511
3512 <para>
3513 If you want to use <filename>runqemu</filename> without a
3514 configuration file, use the following command form:
3515 <literallayout class='monospaced'>
3516 $ runqemu <replaceable>machine</replaceable> <replaceable>rootfs</replaceable> <replaceable>kernel</replaceable> [<replaceable>options</replaceable>]
3517 </literallayout>
3518 Supported <replaceable>machines</replaceable> are as follows:
3519 <literallayout class='monospaced'>
3520 qemuarm
3521 qemuarm64
3522 qemux86
3523 qemux86-64
3524 qemuppc
3525 qemumips
3526 qemumips64
3527 qemumipsel
3528 qemumips64el
3529 </literallayout>
3530 Consider the following example, which uses the
3531 <filename>qemux86-64</filename> machine,
3532 provides a root filesystem, provides an image, and uses
3533 the <filename>nographic</filename> option:
3534 <literallayout class='monospaced'>
3535$ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
3536 </literallayout>
3537 </para>
3538
3539 <para>
3540 Following is a list of variables that can be set in configuration
3541 files such as <filename>bsp.conf</filename> to enable the BSP
3542 to be booted by <filename>runqemu</filename>:
3543 <note>
3544 "QB" means "QEMU Boot".
3545 </note>
3546 <literallayout class='monospaced'>
3547 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
3548 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
3549 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
3550 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
3551 QB_MEM: Memory (e.g. "-m 512")
3552 QB_MACHINE: QEMU machine (e.g. "-machine virt")
3553 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
3554 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
3555 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
3556 option (e.g. "console=ttyS0 console=tty")
3557 QB_DTB: QEMU dtb name
3558 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
3559 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
3560 when QB_AUDIO_DRV is set.
3561 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
3562 QB_TAP_OPT: Network option for 'tap' mode (e.g.
3563 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
3564 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
3565 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
3566 QB_ROOTFS_OPT: Used as rootfs (e.g.
3567 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
3568 runqemu will replace "@ROOTFS@" with the one which is used, such as
3569 core-image-minimal-qemuarm64.ext4.
3570 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
3571 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
3572 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
3573 runqemu will replace "@PORT@" with the port number which is used.
3574 </literallayout>
3575 </para>
3576
3577 <para>
3578 To use <filename>runqemu</filename>, set
3579 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
3580 as follows and run <filename>runqemu</filename>:
3581 <note>
3582 For command-line syntax, use
3583 <filename>runqemu help</filename>.
3584 </note>
3585 <literallayout class='monospaced'>
3586 IMAGE_CLASSES += "qemuboot"
3587 </literallayout>
3588 </para>
3589 </section>
3590
3591 <section id='migration-2.2-default-linker-hash-style-changed'>
3592 <title>Default Linker Hash Style Changed</title>
3593
3594 <para>
3595 The default linker hash style for <filename>gcc-cross</filename>
3596 is now "sysv" in order to catch recipes that are building software
3597 without using the OpenEmbedded
3598 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>.
3599 This change could result in seeing some "No GNU_HASH in the elf
3600 binary" QA issues when building such recipes.
3601 You need to fix these recipes so that they use the expected
3602 <filename>LDFLAGS</filename>.
3603 Depending on how the software is built, the build system used by
3604 the software (e.g. a Makefile) might need to be patched.
3605 However, sometimes making this fix is as simple as adding the
3606 following to the recipe:
3607 <literallayout class='monospaced'>
3608 TARGET_CC_ARCH += "${LDFLAGS}"
3609 </literallayout>
3610 </para>
3611 </section>
3612
3613 <section id='migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype'>
3614 <title><filename>KERNEL_IMAGE_BASE_NAME</filename> no Longer Uses <filename>KERNEL_IMAGETYPE</filename></title>
3615
3616 <para>
3617 The
3618 <filename>KERNEL_IMAGE_BASE_NAME</filename>
3619 variable no longer uses the
3620 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
3621 variable to create the image's base name.
3622 Because the OpenEmbedded build system can now build multiple kernel
3623 image types, this part of the kernel image base name as been
3624 removed leaving only the following:
3625 <literallayout class='monospaced'>
3626 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
3627 </literallayout>
3628 If you have recipes or classes that use
3629 <filename>KERNEL_IMAGE_BASE_NAME</filename> directly, you might
3630 need to update the references to ensure they continue to work.
3631 </para>
3632 </section>
3633
3634 <section id='migration-2.2-bitbake-changes'>
3635 <title>BitBake Changes</title>
3636
3637 <para>
3638 The following changes took place for BitBake:
3639 <itemizedlist>
3640 <listitem><para>
3641 The "goggle" UI and standalone image-writer tool have
3642 been removed as they both require GTK+ 2.0 and
3643 were not being maintained.
3644 </para></listitem>
3645 <listitem><para>
3646 The Perforce fetcher now supports
3647 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
3648 for specifying the source revision to use, be it
3649 <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename>,
3650 changelist number, p4date, or label, in preference to
3651 separate
3652 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
3653 parameters to specify these.
3654 This change is more in-line with how the other fetchers
3655 work for source control systems.
3656 Recipes that fetch from Perforce will need to be updated
3657 to use <filename>SRCREV</filename> in place of specifying
3658 the source revision within
3659 <filename>SRC_URI</filename>.
3660 </para></listitem>
3661 <listitem><para>
3662 Some of BitBake's internal code structures for accessing
3663 the recipe cache needed to be changed to support the new
3664 multi-configuration functionality.
3665 These changes will affect external tools that use BitBake's
3666 tinfoil module.
3667 For information on these changes, see the changes made to
3668 the scripts supplied with OpenEmbedded-Core:
3669 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee'>1</ulink>
3670 and
3671 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67'>2</ulink>.
3672 </para></listitem>
3673 <listitem><para>
3674 The task management code has been rewritten to avoid using
3675 ID indirection in order to improve performance.
3676 This change is unlikely to cause any problems for most
3677 users.
3678 However, the setscene verification function as pointed to
3679 by <filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
3680 needed to change signature.
3681 Consequently, a new variable named
3682 <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename>
3683 has been added allowing multiple versions of BitBake
3684 to work with suitably written metadata, which includes
3685 OpenEmbedded-Core and Poky.
3686 Anyone with custom BitBake task scheduler code might also
3687 need to update the code to handle the new structure.
3688 </para></listitem>
3689 </itemizedlist>
3690 </para>
3691 </section>
3692
3693 <section id='migration-2.2-swabber-has-been-removed'>
3694 <title>Swabber has Been Removed</title>
3695
3696 <para>
3697 Swabber, a tool that was intended to detect host contamination in
3698 the build process, has been removed, as it has been unmaintained
3699 and unused for some time and was never particularly effective.
3700 The OpenEmbedded build system has since incorporated a number of
3701 mechanisms including enhanced QA checks that mean that there is
3702 less of a need for such a tool.
3703 </para>
3704 </section>
3705
3706 <section id='migration-2.2-removed-recipes'>
3707 <title>Removed Recipes</title>
3708
3709 <para>
3710 The following recipes have been removed:
3711 <itemizedlist>
3712 <listitem><para>
3713 <filename>augeas</filename>:
3714 No longer needed and has been moved to
3715 <filename>meta-oe</filename>.
3716 </para></listitem>
3717 <listitem><para>
3718 <filename>directfb</filename>:
3719 Unmaintained and has been moved to
3720 <filename>meta-oe</filename>.
3721 </para></listitem>
3722 <listitem><para>
3723 <filename>gcc</filename>:
3724 Removed 4.9 version.
3725 Versions 5.4 and 6.2 are still present.
3726 </para></listitem>
3727 <listitem><para>
3728 <filename>gnome-doc-utils</filename>:
3729 No longer needed.
3730 </para></listitem>
3731 <listitem><para>
3732 <filename>gtk-doc-stub</filename>:
3733 Replaced by <filename>gtk-doc</filename>.
3734 </para></listitem>
3735 <listitem><para>
3736 <filename>gtk-engines</filename>:
3737 No longer needed and has been moved to
3738 <filename>meta-gnome</filename>.
3739 </para></listitem>
3740 <listitem><para>
3741 <filename>gtk-sato-engine</filename>:
3742 Became obsolete.
3743 </para></listitem>
3744 <listitem><para>
3745 <filename>libglade</filename>:
3746 No longer needed and has been moved to
3747 <filename>meta-oe</filename>.
3748 </para></listitem>
3749 <listitem><para>
3750 <filename>libmad</filename>:
3751 Unmaintained and functionally replaced by
3752 <filename>libmpg123</filename>.
3753 <filename>libmad</filename> has been moved to
3754 <filename>meta-oe</filename>.
3755 </para></listitem>
3756 <listitem><para>
3757 <filename>libowl</filename>:
3758 Became obsolete.
3759 </para></listitem>
3760 <listitem><para>
3761 <filename>libxsettings-client</filename>:
3762 No longer needed.
3763 </para></listitem>
3764 <listitem><para>
3765 <filename>oh-puzzles</filename>:
3766 Functionally replaced by
3767 <filename>puzzles</filename>.
3768 </para></listitem>
3769 <listitem><para>
3770 <filename>oprofileui</filename>:
3771 Became obsolete.
3772 OProfile has been largely supplanted by perf.
3773 </para></listitem>
3774 <listitem><para>
3775 <filename>packagegroup-core-directfb.bb</filename>:
3776 Removed.
3777 </para></listitem>
3778 <listitem><para>
3779 <filename>core-image-directfb.bb</filename>:
3780 Removed.
3781 </para></listitem>
3782 <listitem><para>
3783 <filename>pointercal</filename>:
3784 No longer needed and has been moved to
3785 <filename>meta-oe</filename>.
3786 </para></listitem>
3787 <listitem><para>
3788 <filename>python-imaging</filename>:
3789 No longer needed and moved to
3790 <filename>meta-python</filename>
3791 </para></listitem>
3792 <listitem><para>
3793 <filename>python-pyrex</filename>:
3794 No longer needed and moved to
3795 <filename>meta-python</filename>.
3796 </para></listitem>
3797 <listitem><para>
3798 <filename>sato-icon-theme</filename>:
3799 Became obsolete.
3800 </para></listitem>
3801 <listitem><para>
3802 <filename>swabber-native</filename>:
3803 Swabber has been removed.
3804 See the
3805 <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>.
3806 </para></listitem>
3807 <listitem><para>
3808 <filename>tslib</filename>:
3809 No longer needed and has been moved to
3810 <filename>meta-oe</filename>.
3811 </para></listitem>
3812 <listitem><para>
3813 <filename>uclibc</filename>:
3814 Removed in favor of musl.
3815 </para></listitem>
3816 <listitem><para>
3817 <filename>xtscal</filename>:
3818 No longer needed and moved to
3819 <filename>meta-oe</filename>
3820 </para></listitem>
3821 </itemizedlist>
3822 </para>
3823 </section>
3824
3825 <section id='migration-2.2-removed-classes'>
3826 <title>Removed Classes</title>
3827
3828 <para>
3829 The following classes have been removed:
3830 <itemizedlist>
3831 <listitem><para>
3832 <filename>distutils-native-base</filename>:
3833 No longer needed.
3834 </para></listitem>
3835 <listitem><para>
3836 <filename>distutils3-native-base</filename>:
3837 No longer needed.
3838 </para></listitem>
3839 <listitem><para>
3840 <filename>sdl</filename>:
3841 Only set
3842 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
3843 and
3844 <link linkend='var-SECTION'><filename>SECTION</filename></link>,
3845 which are better set within the recipe instead.
3846 </para></listitem>
3847 <listitem><para>
3848 <filename>sip</filename>:
3849 Mostly unused.
3850 </para></listitem>
3851 <listitem><para>
3852 <filename>swabber</filename>:
3853 See the
3854 <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>.
3855 </para></listitem>
3856 </itemizedlist>
3857 </para>
3858 </section>
3859
3860 <section id='migration-2.2-minor-packaging-changes'>
3861 <title>Minor Packaging Changes</title>
3862
3863 <para>
3864 The following minor packaging changes have occurred:
3865 <itemizedlist>
3866 <listitem><para>
3867 <filename>grub</filename>:
3868 Split <filename>grub-editenv</filename> into its own
3869 package.
3870 </para></listitem>
3871 <listitem><para>
3872 <filename>systemd</filename>:
3873 Split container and vm related units into a new package,
3874 systemd-container.
3875 </para></listitem>
3876 <listitem><para>
3877 <filename>util-linux</filename>:
3878 Moved <filename>prlimit</filename> to a separate
3879 <filename>util-linux-prlimit</filename> package.
3880 </para></listitem>
3881 </itemizedlist>
3882 </para>
3883 </section>
3884
3885 <section id='migration-2.2-miscellaneous-changes'>
3886 <title>Miscellaneous Changes</title>
3887
3888 <para>
3889 The following miscellaneous changes have occurred:
3890 <itemizedlist>
3891 <listitem><para>
3892 <filename>package_regex.inc</filename>:
3893 Removed because the definitions
3894 <filename>package_regex.inc</filename> previously contained
3895 have been moved to their respective recipes.
3896 </para></listitem>
3897 <listitem><para>
3898 Both <filename>devtool add</filename> and
3899 <filename>recipetool create</filename> now use a fixed
3900 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
3901 by default when fetching from a Git repository.
3902 You can override this in either case to use
3903 <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename>
3904 instead by using the <filename>-a</filename> or
3905 <filename>&dash;&dash;autorev</filename> command-line
3906 option
3907 </para></listitem>
3908 <listitem><para>
3909 <filename>distcc</filename>:
3910 GTK+ UI is now disabled by default.
3911 </para></listitem>
3912 <listitem><para>
3913 <filename>packagegroup-core-tools-testapps</filename>:
3914 Removed Piglit.
3915 </para></listitem>
3916 <listitem><para>
3917 <filename>image.bbclass</filename>:
3918 Renamed COMPRESS(ION) to CONVERSION.
3919 This change means that
3920 <filename>COMPRESSIONTYPES</filename>,
3921 <filename>COMPRESS_DEPENDS</filename> and
3922 <filename>COMPRESS_CMD</filename> are deprecated in favor
3923 of <filename>CONVERSIONTYPES</filename>,
3924 <filename>CONVERSION_DEPENDS</filename> and
3925 <filename>CONVERSION_CMD</filename>.
3926 The <filename>COMPRESS*</filename> variable names will
3927 still work in the 2.2 release but metadata that does not
3928 need to be backwards-compatible should be changed to
3929 use the new names as the <filename>COMPRESS*</filename>
3930 ones will be removed in a future release.
3931 </para></listitem>
3932 <listitem><para>
3933 <filename>gtk-doc</filename>:
3934 A full version of <filename>gtk-doc</filename> is now
3935 made available.
3936 However, some old software might not be capable of using
3937 the current version of <filename>gtk-doc</filename>
3938 to build documentation.
3939 You need to change recipes that build such software so that
3940 they explicitly disable building documentation with
3941 <filename>gtk-doc</filename>.
3942 </para></listitem>
3943 </itemizedlist>
3944 </para>
3945 </section>
3946</section>
3947
3948<section id='moving-to-the-yocto-project-2.3-release'>
3949 <title>Moving to the Yocto Project 2.3 Release</title>
3950
3951 <para>
3952 This section provides migration information for moving to the
3953 Yocto Project 2.3 Release from the prior release.
3954 </para>
3955
3956 <section id='migration-2.3-recipe-specific-sysroots'>
3957 <title>Recipe-specific Sysroots</title>
3958
3959 <para>
3960 The OpenEmbedded build system now uses one sysroot per
3961 recipe to resolve long-standing issues with configuration
3962 script auto-detection of undeclared dependencies.
3963 Consequently, you might find that some of your previously
3964 written custom recipes are missing declared dependencies,
3965 particularly those dependencies that are incidentally built
3966 earlier in a typical build process and thus are already likely
3967 to be present in the shared sysroot in previous releases.
3968 </para>
3969
3970 <para>
3971 Consider the following:
3972 <itemizedlist>
3973 <listitem><para>
3974 <emphasis>Declare Build-Time Dependencies:</emphasis>
3975 Because of this new feature, you must explicitly
3976 declare all build-time dependencies for your recipe.
3977 If you do not declare these dependencies, they are not
3978 populated into the sysroot for the recipe.
3979 </para></listitem>
3980 <listitem><para>
3981 <emphasis>Specify Pre-Installation and Post-Installation
3982 Native Tool Dependencies:</emphasis>
3983 You must specifically specify any special native tool
3984 dependencies of <filename>pkg_preinst</filename> and
3985 <filename>pkg_postinst</filename> scripts by using the
3986 <link linkend='var-PACKAGE_WRITE_DEPS'><filename>PACKAGE_WRITE_DEPS</filename></link>
3987 variable.
3988 Specifying these dependencies ensures that these tools
3989 are available if these scripts need to be run on the
3990 build host during the
3991 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
3992 task.</para>
3993
3994 <para>As an example, see the <filename>dbus</filename>
3995 recipe.
3996 You will see that this recipe has a
3997 <filename>pkg_postinst</filename> that calls
3998 <filename>systemctl</filename> if "systemd" is in
3999 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
4000 In the example,
4001 <filename>systemd-systemctl-native</filename> is added to
4002 <filename>PACKAGE_WRITE_DEPS</filename>, which is also
4003 conditional on "systemd" being in
4004 <filename>DISTRO_FEATURES</filename>.
4005 </para></listitem>
4006 <listitem><para>
4007 <emphasis>Examine Recipes that Use
4008 <filename>SSTATEPOSTINSTFUNCS</filename>:</emphasis>
4009 You need to examine any recipe that uses
4010 <filename>SSTATEPOSTINSTFUNCS</filename> and determine
4011 steps to take.</para>
4012
4013 <para>Functions added to
4014 <filename>SSTATEPOSTINSTFUNCS</filename> are still
4015 called as they were in previous Yocto Project releases.
4016 However, since a separate sysroot is now being populated
4017 for every recipe and if existing functions being called
4018 through <filename>SSTATEPOSTINSTFUNCS</filename> are
4019 doing relocation, then you will need to change these
4020 to use a post-installation script that is installed by a
4021 function added to
4022 <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link>.
4023 </para>
4024
4025 <para>For an example, see the
4026 <filename>pixbufcache</filename> class in
4027 <filename>meta/classes/</filename> in the Yocto Project
4028 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>.
4029 <note>
4030 The <filename>SSTATEPOSTINSTFUNCS</filename> variable
4031 itself is now deprecated in favor of the
4032 <filename>do_populate_sysroot[postfuncs]</filename>
4033 task.
4034 Consequently, if you do still have any function or
4035 functions that need to be called after the sysroot
4036 component is created for a recipe, then you would be
4037 well advised to take steps to use a post installation
4038 script as described previously.
4039 Taking these steps prepares your code for when
4040 <filename>SSTATEPOSTINSTFUNCS</filename> is
4041 removed in a future Yocto Project release.
4042 </note>
4043 </para></listitem>
4044 <listitem><para>
4045 <emphasis>Specify the Sysroot when Using Certain
4046 External Scripts:</emphasis>
4047 Because the shared sysroot is now gone, the scripts
4048 <filename>oe-find-native-sysroot</filename> and
4049 <filename>oe-run-native</filename> have been changed such
4050 that you need to specify which recipe's
4051 <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>
4052 is used.
4053 </para></listitem>
4054 </itemizedlist>
4055 <note>
4056 You can find more information on how recipe-specific sysroots
4057 work in the
4058 "<link linkend='ref-classes-staging'><filename>staging.bbclass</filename></link>"
4059 section.
4060 </note>
4061 </para>
4062 </section>
4063
4064 <section id='migration-2.3-path-variable'>
4065 <title><filename>PATH</filename> Variable</title>
4066
4067 <para>
4068 Within the environment used to run build tasks, the environment
4069 variable <filename>PATH</filename> is now sanitized such that
4070 the normal native binary paths
4071 (<filename>/bin</filename>, <filename>/sbin</filename>,
4072 <filename>/usr/bin</filename> and so forth) are
4073 removed and a directory containing symbolic links linking only
4074 to the binaries from the host mentioned in the
4075 <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>
4076 and
4077 <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>
4078 variables is added to <filename>PATH</filename>.
4079 </para>
4080
4081 <para>
4082 Consequently, any native binaries provided by the host that you
4083 need to call needs to be in one of these two variables at
4084 the configuration level.
4085 </para>
4086
4087 <para>
4088 Alternatively, you can add a native recipe (i.e.
4089 <filename>-native</filename>) that provides the
4090 binary to the recipe's
4091 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
4092 value.
4093 <note>
4094 <filename>PATH</filename> is not sanitized in the same way
4095 within <filename>devshell</filename>.
4096 If it were, you would have difficulty running host tools for
4097 development and debugging within the shell.
4098 </note>
4099 </para>
4100 </section>
4101
4102 <section id='migration-2.3-scripts'>
4103 <title>Changes to Scripts</title>
4104
4105 <para>
4106 The following changes to scripts took place:
4107 <itemizedlist>
4108 <listitem><para>
4109 <emphasis><filename>oe-find-native-sysroot</filename>:</emphasis>
4110 The usage for the
4111 <filename>oe-find-native-sysroot</filename> script has
4112 changed to the following:
4113 <literallayout class='monospaced'>
4114 $ . oe-find-native-sysroot <replaceable>recipe</replaceable>
4115 </literallayout>
4116 You must now supply a recipe for
4117 <replaceable>recipe</replaceable> as part of the command.
4118 Prior to the Yocto Project &DISTRO; release, it was not
4119 necessary to provide the script with the command.
4120 </para></listitem>
4121 <listitem><para>
4122 <emphasis><filename>oe-run-native</filename>:</emphasis>
4123 The usage for the
4124 <filename>oe-run-native</filename> script has changed
4125 to the following:
4126 <literallayout class='monospaced'>
4127 $ oe-run-native <replaceable>native_recipe</replaceable> <replaceable>tool</replaceable>
4128 </literallayout>
4129 You must supply the name of the native recipe and the tool
4130 you want to run as part of the command.
4131 Prior to the Yocto Project &DISTRO; release, it was not
4132 necessary to provide the native recipe with the command.
4133 </para></listitem>
4134 <listitem><para>
4135 <emphasis><filename>cleanup-workdir</filename>:</emphasis>
4136 The <filename>cleanup-workdir</filename> script has been
4137 removed because the script was found to be deleting
4138 files it should not have, which lead to broken build
4139 trees.
4140 Rather than trying to delete portions of
4141 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
4142 and getting it wrong, it is recommended that you
4143 delete <filename>TMPDIR</filename> and have it restored
4144 from shared state (sstate) on subsequent builds.
4145 </para></listitem>
4146 <listitem><para>
4147 <emphasis><filename>wipe-sysroot</filename>:</emphasis>
4148 The <filename>wipe-sysroot</filename> script has been
4149 removed as it is no longer needed with recipe-specific
4150 sysroots.
4151 </para></listitem>
4152 </itemizedlist>
4153 </para>
4154 </section>
4155
4156 <section id='migration-2.3-functions'>
4157 <title>Changes to Functions</title>
4158
4159 <para>
4160 The previously deprecated
4161 <filename>bb.data.getVar()</filename>,
4162 <filename>bb.data.setVar()</filename>, and
4163 related functions have been removed in favor of
4164 <filename>d.getVar()</filename>,
4165 <filename>d.setVar()</filename>, and so forth.
4166 </para>
4167
4168 <para>
4169 You need to fix any references to these old functions.
4170 </para>
4171 </section>
4172
4173 <section id='migration-2.3-bitbake-changes'>
4174 <title>BitBake Changes</title>
4175
4176 <para>
4177 The following changes took place for BitBake:
4178 <itemizedlist>
4179 <listitem><para>
4180 <emphasis>BitBake's Graphical Dependency Explorer UI Replaced:</emphasis>
4181 BitBake's graphical dependency explorer UI
4182 <filename>depexp</filename> was replaced by
4183 <filename>taskexp</filename> ("Task Explorer"), which
4184 provides a graphical way of exploring the
4185 <filename>task-depends.dot</filename> file.
4186 The data presented by Task Explorer is much more
4187 accurate than the data that was presented by
4188 <filename>depexp</filename>.
4189 Being able to visualize the data is an often requested
4190 feature as standard <filename>*.dot</filename> file
4191 viewers cannot usual cope with the size of
4192 the <filename>task-depends.dot</filename> file.
4193 </para></listitem>
4194 <listitem><para>
4195 <emphasis>BitBake "-g" Output Changes:</emphasis>
4196 The <filename>package-depends.dot</filename> and
4197 <filename>pn-depends.dot</filename> files as previously
4198 generated using the <filename>bitbake -g</filename> command
4199 have been removed.
4200 A <filename>recipe-depends.dot</filename> file
4201 is now generated as a collapsed version of
4202 <filename>task-depends.dot</filename> instead.
4203 </para>
4204
4205 <para>The reason for this change is because
4206 <filename>package-depends.dot</filename> and
4207 <filename>pn-depends.dot</filename> largely date back
4208 to a time before task-based execution and do not take
4209 into account task-level dependencies between recipes,
4210 which could be misleading.
4211 </para></listitem>
4212 <listitem><para>
4213 <emphasis>Mirror Variable Splitting Changes:</emphasis>
4214 Mirror variables including
4215 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>,
4216 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
4217 and
4218 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
4219 can now separate values entirely with spaces.
4220 Consequently, you no longer need "\\n".
4221 BitBake looks for pairs of values, which simplifies usage.
4222 There should be no change required to existing mirror
4223 variable values themselves.
4224 </para></listitem>
4225 <listitem><para>
4226 <emphasis>The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an "rsh" Parameter:</emphasis>
4227 The SVN fetcher now takes an "ssh" parameter instead of an
4228 "rsh" parameter.
4229 This new optional parameter is used when the "protocol"
4230 parameter is set to "svn+ssh".
4231 You can only use the new parameter to specify the
4232 <filename>ssh</filename> program used by SVN.
4233 The SVN fetcher passes the new parameter through the
4234 <filename>SVN_SSH</filename> environment variable during
4235 the
4236 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
4237 task.</para>
4238
4239 <para>See the
4240 "<ulink url='&YOCTO_DOCS_BB_URL;#svn-fetcher'>Subversion (SVN) Fetcher (svn://)</ulink>"
4241 section in the BitBake User Manual for additional
4242 information.
4243 </para></listitem>
4244 <listitem><para>
4245 <emphasis><filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
4246 and <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename>
4247 Removed:</emphasis>
4248 Because the mechanism they were part of is no longer
4249 necessary with recipe-specific sysroots, the
4250 <filename>BB_SETSCENE_VERIFY_FUNCTION</filename> and
4251 <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename>
4252 variables have been removed.
4253 </para></listitem>
4254 </itemizedlist>
4255 </para>
4256 </section>
4257
4258 <section id='migration-2.3-absolute-symlinks'>
4259 <title>Absolute Symbolic Links</title>
4260
4261 <para>
4262 Absolute symbolic links (symlinks) within staged files are no
4263 longer permitted and now trigger an error.
4264 Any explicit creation of symlinks can use the
4265 <filename>lnr</filename> script, which is a replacement for
4266 <filename>ln -r</filename>.
4267 </para>
4268
4269 <para>
4270 If the build scripts in the software that the recipe is building
4271 are creating a number of absolute symlinks that need to be
4272 corrected, you can inherit
4273 <filename>relative_symlinks</filename> within the recipe to turn
4274 those absolute symlinks into relative symlinks.
4275 </para>
4276 </section>
4277
4278 <section id='migration-2.3-gplv2-and-gplv3-moves'>
4279 <title>GPLv2 Versions of GPLv3 Recipes Moved</title>
4280
4281 <para>
4282 Older GPLv2 versions of GPLv3 recipes have moved to a
4283 separate <filename>meta-gplv2</filename> layer.
4284 </para>
4285
4286 <para>
4287 If you use
4288 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>
4289 to exclude GPLv3 or set
4290 <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
4291 to substitute a GPLv2 version of a GPLv3 recipe, then you must add
4292 the <filename>meta-gplv2</filename> layer to your configuration.
4293 <note>
4294 You can find <filename>meta-gplv2</filename> layer in the
4295 OpenEmbedded layer index at
4296 <ulink url='https://layers.openembedded.org/layerindex/branch/master/layer/meta-gplv2/'></ulink>.
4297 </note>
4298 </para>
4299
4300 <para>
4301 These relocated GPLv2 recipes do not receive the same level of
4302 maintenance as other core recipes.
4303 The recipes do not get security fixes and upstream no longer
4304 maintains them.
4305 In fact, the upstream community is actively hostile towards people
4306 that use the old versions of the recipes.
4307 Moving these recipes into a separate layer both makes the different
4308 needs of the recipes clearer and clearly identifies the number of
4309 these recipes.
4310 <note>
4311 The long-term solution might be to move to BSD-licensed
4312 replacements of the GPLv3 components for those that need to
4313 exclude GPLv3-licensed components from the target system.
4314 This solution will be investigated for future Yocto
4315 Project releases.
4316 </note>
4317 </para>
4318 </section>
4319
4320 <section id='migration-2.3-package-management-changes'>
4321 <title>Package Management Changes</title>
4322
4323 <para>
4324 The following package management changes took place:
4325 <itemizedlist>
4326 <listitem><para>
4327 Smart package manager is replaced by DNF package manager.
4328 Smart has become unmaintained upstream, is not ported
4329 to Python 3.x.
4330 Consequently, Smart needed to be replaced.
4331 DNF is the only feasible candidate.</para>
4332 <para>The change in functionality is that the on-target
4333 runtime package management from remote package feeds is
4334 now done with a different tool that has a
4335 different set of command-line options.
4336 If you have scripts that call the
4337 tool directly, or use its API, they need to be fixed.</para>
4338 <para>For more information, see the
4339 <ulink url='http://dnf.readthedocs.io/en/latest/'>DNF Documentation</ulink>.
4340 </para></listitem>
4341 <listitem><para>
4342 Rpm 5.x is replaced with Rpm 4.x.
4343 This is done for two major reasons:
4344 <itemizedlist>
4345 <listitem><para>
4346 DNF is API-incompatible with Rpm 5.x and porting
4347 it and maintaining the port is non-trivial.
4348 </para></listitem>
4349 <listitem><para>
4350 Rpm 5.x itself has limited maintenance upstream,
4351 and the Yocto Project is one of the very few
4352 remaining users.
4353 </para></listitem>
4354 </itemizedlist>
4355 </para></listitem>
4356 <listitem><para>
4357 Berkeley DB 6.x is removed and Berkeley DB 5.x becomes
4358 the default:
4359 <itemizedlist>
4360 <listitem><para>
4361 Version 6.x of Berkeley DB has largely been
4362 rejected by the open source community due to its
4363 AGPLv3 license.
4364 As a result, most mainstream open source projects
4365 that require DB are still developed and tested with
4366 DB 5.x.
4367 </para></listitem>
4368 <listitem><para>
4369 In OE-core, the only thing that was requiring
4370 DB 6.x was Rpm 5.x.
4371 Thus, no reason exists to continue carrying DB 6.x
4372 in OE-core.
4373 </para></listitem>
4374 </itemizedlist>
4375 </para></listitem>
4376 <listitem><para>
4377 <filename>createrepo</filename> is replaced with
4378 <filename>createrepo_c</filename>.</para>
4379 <para><filename>createrepo_c</filename> is the current
4380 incarnation of the tool that generates remote repository
4381 metadata.
4382 It is written in C as compared to
4383 <filename>createrepo</filename>, which is written in
4384 Python.
4385 <filename>createrepo_c</filename> is faster and is
4386 maintained.
4387 </para></listitem>
4388 <listitem><para>
4389 Architecture-independent RPM packages are "noarch"
4390 instead of "all".</para>
4391 <para>This change was made because too many places in
4392 DNF/RPM4 stack already make that assumption.
4393 Only the filenames and the architecture tag has changed.
4394 Nothing else has changed in OE-core system, particularly
4395 in the
4396 <link linkend='ref-classes-allarch'><filename>allarch.bbclass</filename></link>
4397 class.
4398 </para></listitem>
4399 <listitem><para>
4400 Signing of remote package feeds using
4401 <filename>PACKAGE_FEED_SIGN</filename>
4402 is not currently supported.
4403 This issue will be fully addressed in a future
4404 Yocto Project release.
4405 See <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209'>defect 11209</ulink>
4406 for more information on a solution to package feed
4407 signing with RPM in the Yocto Project 2.3 release.
4408 </para></listitem>
4409 <listitem><para>
4410 OPKG now uses the libsolv backend for resolving package
4411 dependencies by default.
4412 This is vastly superior to OPKG's internal ad-hoc solver
4413 that was previously used.
4414 This change does have a small impact on disk (around
4415 500 KB) and memory footprint.
4416 <note>
4417 For further details on this change, see the
4418 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?
4419id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>.
4420 </note>
4421 </para></listitem>
4422 </itemizedlist>
4423 </para>
4424 </section>
4425
4426 <section id='migration-2.3-removed-recipes'>
4427 <title>Removed Recipes</title>
4428
4429 <para>
4430 The following recipes have been removed:
4431 <itemizedlist>
4432 <listitem><para>
4433 <emphasis><filename>linux-yocto 4.8:</filename></emphasis>
4434 Version 4.8 has been removed.
4435 Versions 4.1 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10
4436 are now present.
4437 </para></listitem>
4438 <listitem><para>
4439 <emphasis><filename>python-smartpm:</filename></emphasis>
4440 Functionally replaced by <filename>dnf</filename>.
4441 </para></listitem>
4442 <listitem><para>
4443 <emphasis><filename>createrepo:</filename></emphasis>
4444 Replaced by the <filename>createrepo-c</filename> recipe.
4445 </para></listitem>
4446 <listitem><para>
4447 <emphasis><filename>rpmresolve:</filename></emphasis>
4448 No longer needed with the move to RPM 4 as RPM itself is
4449 used instead.
4450 </para></listitem>
4451 <listitem><para>
4452 <emphasis><filename>gstreamer:</filename></emphasis>
4453 Removed the GStreamer Git version recipes as they have
4454 been stale.
4455 <filename>1.10.</filename><replaceable>x</replaceable>
4456 recipes are still present.
4457 </para></listitem>
4458 <listitem><para>
4459 <emphasis><filename>alsa-conf-base:</filename></emphasis>
4460 Merged into <filename>alsa-conf</filename> since
4461 <filename>libasound</filename> depended on both.
4462 Essentially, no way existed to install only one of these.
4463 </para></listitem>
4464 <listitem><para>
4465 <emphasis><filename>tremor:</filename></emphasis>
4466 Moved to <filename>meta-multimedia</filename>.
4467 Fixed-integer Vorbis decoding is not
4468 needed by current hardware.
4469 Thus, GStreamer's ivorbis plugin has been disabled
4470 by default eliminating the need for the
4471 <filename>tremor</filename> recipe in
4472 <link linkend='oe-core'>OE-Core</link>.
4473 </para></listitem>
4474 <listitem><para>
4475 <emphasis><filename>gummiboot:</filename></emphasis>
4476 Replaced by <filename>systemd-boot</filename>.
4477 </para></listitem>
4478 </itemizedlist>
4479 </para>
4480 </section>
4481
4482 <section id='migration-2.3-wic-changes'>
4483 <title>Wic Changes</title>
4484
4485 <para>
4486 The following changes have been made to Wic:
4487 <note>
4488 For more information on Wic, see the
4489 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
4490 section in the Yocto Project Development Tasks Manual.
4491 </note>
4492 <itemizedlist>
4493 <listitem><para>
4494 <emphasis>Default Output Directory Changed:</emphasis>
4495 Wic's default output directory is now the current directory
4496 by default instead of the unusual
4497 <filename>/var/tmp/wic</filename>.</para>
4498
4499 <para>The "-o" and "--outdir" options remain unchanged
4500 and are used to specify your preferred output directory
4501 if you do not want to use the default directory.
4502 </para></listitem>
4503 <listitem><para>
4504 <emphasis>fsimage Plug-in Removed:</emphasis>
4505 The Wic fsimage plugin has been removed as it duplicates
4506 functionality of the rawcopy plugin.
4507 </para></listitem>
4508 </itemizedlist>
4509 </para>
4510 </section>
4511
4512 <section id='migration-2.3-qa-changes'>
4513 <title>QA Changes</title>
4514
4515 <para>
4516 The following QA checks have changed:
4517 <itemizedlist>
4518 <listitem><para>
4519 <emphasis><filename>unsafe-references-in-binaries</filename>:</emphasis>
4520 The <filename>unsafe-references-in-binaries</filename>
4521 QA check, which was disabled by default, has now been
4522 removed.
4523 This check was intended to detect binaries in
4524 <filename>/bin</filename> that link to libraries in
4525 <filename>/usr/lib</filename> and have the case where
4526 the user has <filename>/usr</filename> on a separate
4527 filesystem to <filename>/</filename>.</para>
4528
4529 <para>The removed QA check was buggy.
4530 Additionally, <filename>/usr</filename> residing on a
4531 separate partition from <filename>/</filename> is now
4532 a rare configuration.
4533 Consequently,
4534 <filename>unsafe-references-in-binaries</filename> was
4535 removed.
4536 </para></listitem>
4537 <listitem><para>
4538 <emphasis><filename>file-rdeps</filename>:</emphasis>
4539 The <filename>file-rdeps</filename> QA check is now an
4540 error by default instead of a warning.
4541 Because it is an error instead of a warning, you need to
4542 address missing runtime dependencies.</para>
4543
4544 <para>For additional information, see the
4545 <link linkend='ref-classes-insane'><filename>insane</filename></link>
4546 class and the
4547 "<link linkend='qa-errors-and-warnings'>Errors and Warnings</link>"
4548 section.
4549 </para></listitem>
4550 </itemizedlist>
4551 </para>
4552 </section>
4553
4554 <section id='migration-2.3-miscellaneous-changes'>
4555 <title>Miscellaneous Changes</title>
4556
4557 <para>
4558 The following miscellaneous changes have occurred:
4559 <itemizedlist>
4560 <listitem><para>
4561 In this release, a number of recipes have been changed to
4562 ignore the <filename>largefile</filename>
4563 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
4564 item, enabling large file support unconditionally.
4565 This feature has always been enabled by default.
4566 Disabling the feature has not been widely tested.
4567 <note>
4568 Future releases of the Yocto Project will remove
4569 entirely the ability to disable the
4570 <filename>largefile</filename> feature,
4571 which would make it unconditionally enabled everywhere.
4572 </note>
4573 </para></listitem>
4574 <listitem><para>
4575 If the
4576 <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link>
4577 value contains the value of the
4578 <link linkend='var-DATE'><filename>DATE</filename></link>
4579 variable, which is the default between Poky releases,
4580 the <filename>DATE</filename> value is explicitly excluded
4581 from <filename>/etc/issue</filename> and
4582 <filename>/etc/issue.net</filename>, which is displayed at
4583 the login prompt, in order to avoid conflicts with
4584 Multilib enabled.
4585 Regardless, the <filename>DATE</filename> value is
4586 inaccurate if the <filename>base-files</filename>
4587 recipe is restored from shared state (sstate) rather
4588 than rebuilt.</para>
4589
4590 <para>If you need the build date recorded in
4591 <filename>/etc/issue*</filename> or anywhere else in your
4592 image, a better method is to define a post-processing
4593 function to do it and have the function called from
4594 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
4595 Doing so ensures the value is always up-to-date with the
4596 created image.
4597 </para></listitem>
4598 <listitem><para>
4599 Dropbear's <filename>init</filename> script now disables
4600 DSA host keys by default.
4601 This change is in line with the systemd service
4602 file, which supports RSA keys only, and with recent
4603 versions of OpenSSH, which deprecates DSA host keys.
4604 </para></listitem>
4605 <listitem><para>
4606 The
4607 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
4608 class now correctly uses tabs as separators between all
4609 columns in <filename>installed-package-sizes.txt</filename>
4610 in order to aid import into other tools.
4611 </para></listitem>
4612 <listitem><para>
4613 The <filename>USE_LDCONFIG</filename> variable has been
4614 replaced with the "ldconfig"
4615 <filename>DISTRO_FEATURES</filename> feature.
4616 Distributions that previously set:
4617 <literallayout class='monospaced'>
4618 USE_LDCONFIG = "0"
4619 </literallayout>
4620 should now instead use the following:
4621 <literallayout class='monospaced'>
4622 DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig"
4623 </literallayout>
4624 </para></listitem>
4625 <listitem><para>
4626 The default value of
4627 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
4628 now includes all versions of AGPL licenses in addition
4629 to GPL and LGPL.
4630 <note>
4631 The default list is not intended to be guaranteed
4632 as a complete safe list.
4633 You should seek legal advice based on what you are
4634 distributing if you are unsure.
4635 </note>
4636 </para></listitem>
4637 <listitem><para>
4638 Kernel module packages are now suffixed with the kernel
4639 version in order to allow module packages from multiple
4640 kernel versions to co-exist on a target system.
4641 If you wish to return to the previous naming scheme
4642 that does not include the version suffix, use the
4643 following:
4644 <literallayout class='monospaced'>
4645 KERNEL_MODULE_PACKAGE_SUFFIX to ""
4646 </literallayout>
4647 </para></listitem>
4648 <listitem><para>
4649 Removal of <filename>libtool</filename>
4650 <filename>*.la</filename> files is now enabled by default.
4651 The <filename>*.la</filename> files are not actually
4652 needed on Linux and relocating them is an unnecessary
4653 burden.</para>
4654
4655 <para>If you need to preserve these
4656 <filename>.la</filename> files (e.g. in a custom
4657 distribution), you must change
4658 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
4659 such that "remove-libtool" is not included in the value.
4660 </para></listitem>
4661 <listitem><para>
4662 Extensible SDKs built for GCC 5+ now refuse to install on a
4663 distribution where the host GCC version is 4.8 or 4.9.
4664 This change resulted from the fact that the installation
4665 is known to fail due to the way the
4666 <filename>uninative</filename> shared state (sstate)
4667 package is built.
4668 See the
4669 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
4670 class for additional information.
4671 </para></listitem>
4672 <listitem><para>
4673 All native and nativesdk recipes now use a separate
4674 <filename>DISTRO_FEATURES</filename> value instead of
4675 sharing the value used by recipes for the target, in order
4676 to avoid unnecessary rebuilds.</para>
4677
4678 <para>The <filename>DISTRO_FEATURES</filename> for
4679 <filename>native</filename> recipes is
4680 <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link>
4681 added to an intersection of
4682 <filename>DISTRO_FEATURES</filename> and
4683 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>.
4684 </para>
4685
4686 <para>For nativesdk recipes, the
4687 corresponding variables are
4688 <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link>
4689 and
4690 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>.
4691 </para></listitem>
4692 <listitem><para>
4693 The <filename>FILESDIR</filename>
4694 variable, which was previously deprecated and rarely used,
4695 has now been removed.
4696 You should change any recipes that set
4697 <filename>FILESDIR</filename> to set
4698 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4699 instead.
4700 </para></listitem>
4701 <listitem><para>
4702 The <filename>MULTIMACH_HOST_SYS</filename>
4703 variable has been removed as it is no longer needed
4704 with recipe-specific sysroots.
4705 </para></listitem>
4706 </itemizedlist>
4707 </para>
4708 </section>
4709</section>
4710
4711<section id='moving-to-the-yocto-project-2.4-release'>
4712 <title>Moving to the Yocto Project 2.4 Release</title>
4713
4714 <para>
4715 This section provides migration information for moving to the
4716 Yocto Project 2.4 Release from the prior release.
4717 </para>
4718
4719 <section id='migration-2.4-memory-resident-mode'>
4720 <title>Memory Resident Mode</title>
4721
4722 <para>
4723 A persistent mode is now available in BitBake's default operation,
4724 replacing its previous "memory resident mode" (i.e.
4725 <filename>oe-init-build-env-memres</filename>).
4726 Now you only need to set
4727 <link linkend='var-BB_SERVER_TIMEOUT'><filename>BB_SERVER_TIMEOUT</filename></link>
4728 to a timeout (in seconds) and BitBake's server stays resident for
4729 that amount of time between invocations.
4730 The <filename>oe-init-build-env-memres</filename> script has been
4731 removed since a separate environment setup script is no longer
4732 needed.
4733 </para>
4734 </section>
4735
4736 <section id='migration-2.4-packaging-changes'>
4737 <title>Packaging Changes</title>
4738
4739 <para>
4740 This section provides information about packaging changes that have
4741 occurred:
4742 <itemizedlist>
4743 <listitem><para>
4744 <emphasis><filename>python3</filename> Changes:</emphasis>
4745 <itemizedlist>
4746 <listitem><para>
4747 The main "python3" package now brings in all of the
4748 standard Python 3 distribution rather than a subset.
4749 This behavior matches what is expected based on
4750 traditional Linux distributions.
4751 If you wish to install a subset of Python 3, specify
4752 <filename>python-core</filename> plus one or more of
4753 the individual packages that are still produced.
4754 </para></listitem>
4755 <listitem><para>
4756 <emphasis><filename>python3</filename>:</emphasis>
4757 The <filename>bz2.py</filename>,
4758 <filename>lzma.py</filename>, and
4759 <filename>_compression.py</filename> scripts have
4760 been moved from the
4761 <filename>python3-misc</filename> package to
4762 the <filename>python3-compression</filename> package.
4763 </para></listitem>
4764 </itemizedlist>
4765 </para></listitem>
4766 <listitem><para>
4767 <emphasis><filename>binutils</filename>:</emphasis>
4768 The <filename>libbfd</filename> library is now packaged in
4769 a separate "libbfd" package.
4770 This packaging saves space when certain tools
4771 (e.g. <filename>perf</filename>) are installed.
4772 In such cases, the tools only need
4773 <filename>libbfd</filename> rather than all the packages in
4774 <filename>binutils</filename>.
4775 </para></listitem>
4776 <listitem><para>
4777 <emphasis><filename>util-linux</filename> Changes:</emphasis>
4778 <itemizedlist>
4779 <listitem><para>
4780 The <filename>su</filename> program is now packaged
4781 in a separate "util-linux-su" package, which is only
4782 built when "pam" is listed in the
4783 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
4784 variable.
4785 <filename>util-linux</filename> should not be
4786 installed unless it is needed because
4787 <filename>su</filename> is normally provided through
4788 the shadow file format.
4789 The main <filename>util-linux</filename> package has
4790 runtime dependencies (i.e.
4791 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
4792 on the <filename>util-linux-su</filename> package
4793 when "pam" is in
4794 <filename>DISTRO_FEATURES</filename>.
4795 </para></listitem>
4796 <listitem><para>
4797 The <filename>switch_root</filename> program is now
4798 packaged in a separate "util-linux-switch-root"
4799 package for small initramfs images that do not need
4800 the whole <filename>util-linux</filename> package or
4801 the busybox binary, which are both much larger than
4802 <filename>switch_root</filename>.
4803 The main <filename>util-linux</filename> package has
4804 a recommended runtime dependency (i.e.
4805 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
4806 on the <filename>util-linux-switch-root</filename> package.
4807 </para></listitem>
4808 <listitem><para>
4809 The <filename>ionice</filename> program is now
4810 packaged in a separate "util-linux-ionice" package.
4811 The main <filename>util-linux</filename> package has
4812 a recommended runtime dependency (i.e.
4813 <filename>RRECOMMENDS</filename>)
4814 on the <filename>util-linux-ionice</filename> package.
4815 </para></listitem>
4816 </itemizedlist>
4817 </para></listitem>
4818 <listitem><para>
4819 <emphasis><filename>initscripts</filename>:</emphasis>
4820 The <filename>sushell</filename> program is now packaged in
4821 a separate "initscripts-sushell" package.
4822 This packaging change allows systems to pull
4823 <filename>sushell</filename> in when
4824 <filename>selinux</filename> is enabled.
4825 The change also eliminates needing to pull in the entire
4826 <filename>initscripts</filename> package.
4827 The main <filename>initscripts</filename> package has a
4828 runtime dependency (i.e. <filename>RDEPENDS</filename>)
4829 on the <filename>sushell</filename> package when
4830 "selinux" is in <filename>DISTRO_FEATURES</filename>.
4831 </para></listitem>
4832 <listitem><para>
4833 <emphasis><filename>glib-2.0</filename>:</emphasis>
4834 The <filename>glib-2.0</filename> package now has a
4835 recommended runtime dependency (i.e.
4836 <filename>RRECOMMENDS</filename>) on the
4837 <filename>shared-mime-info</filename> package, since large
4838 portions of GIO are not useful without the MIME database.
4839 You can remove the dependency by using the
4840 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
4841 variable if <filename>shared-mime-info</filename> is too
4842 large and is not required.
4843 </para></listitem>
4844 <listitem><para>
4845 <emphasis>Go Standard Runtime:</emphasis>
4846 The Go standard runtime has been split out from the main
4847 <filename>go</filename> recipe into a separate
4848 <filename>go-runtime</filename> recipe.
4849 </para></listitem>
4850 </itemizedlist>
4851 </para>
4852 </section>
4853
4854 <section id='migration-2.4-removed-recipes'>
4855 <title>Removed Recipes</title>
4856
4857 <para>
4858 The following recipes have been removed:
4859 <itemizedlist>
4860 <listitem><para>
4861 <emphasis><filename>acpitests</filename>:</emphasis>
4862 This recipe is not maintained.
4863 </para></listitem>
4864 <listitem><para>
4865 <emphasis><filename>autogen-native</filename>:</emphasis>
4866 No longer required by Grub, oe-core, or meta-oe.
4867 </para></listitem>
4868 <listitem><para>
4869 <emphasis><filename>bdwgc</filename>:</emphasis>
4870 Nothing in OpenEmbedded-Core requires this recipe.
4871 It has moved to meta-oe.
4872 </para></listitem>
4873 <listitem><para>
4874 <emphasis><filename>byacc</filename>:</emphasis>
4875 This recipe was only needed by rpm 5.x and has moved to
4876 meta-oe.
4877 </para></listitem>
4878 <listitem><para>
4879 <emphasis><filename>gcc (5.4)</filename>:</emphasis>
4880 The 5.4 series dropped the recipe in favor of 6.3 / 7.2.
4881 </para></listitem>
4882 <listitem><para>
4883 <emphasis><filename>gnome-common</filename>:</emphasis>
4884 Deprecated upstream and no longer needed.
4885 </para></listitem>
4886 <listitem><para>
4887 <emphasis><filename>go-bootstrap-native</filename>:</emphasis>
4888 Go 1.9 does its own bootstrapping so this recipe has been
4889 removed.
4890 </para></listitem>
4891 <listitem><para>
4892 <emphasis><filename>guile</filename>:</emphasis>
4893 This recipe was only needed by
4894 <filename>autogen-native</filename> and
4895 <filename>remake</filename>.
4896 The recipe is no longer needed by either of these programs.
4897 </para></listitem>
4898 <listitem><para>
4899 <emphasis><filename>libclass-isa-perl</filename>:</emphasis>
4900 This recipe was previously needed for LSB 4, no longer
4901 needed.
4902 </para></listitem>
4903 <listitem><para>
4904 <emphasis><filename>libdumpvalue-perl</filename>:</emphasis>
4905 This recipe was previously needed for LSB 4, no longer
4906 needed.
4907 </para></listitem>
4908 <listitem><para>
4909 <emphasis><filename>libenv-perl</filename>:</emphasis>
4910 This recipe was previously needed for LSB 4, no longer
4911 needed.
4912 </para></listitem>
4913 <listitem><para>
4914 <emphasis><filename>libfile-checktree-perl</filename>:</emphasis>
4915 This recipe was previously needed for LSB 4, no longer
4916 needed.
4917 </para></listitem>
4918 <listitem><para>
4919 <emphasis><filename>libi18n-collate-perl</filename>:</emphasis>
4920 This recipe was previously needed for LSB 4, no longer
4921 needed.
4922 </para></listitem>
4923 <listitem><para>
4924 <emphasis><filename>libiconv</filename>:</emphasis>
4925 This recipe was only needed for <filename>uclibc</filename>,
4926 which was removed in the previous release.
4927 <filename>glibc</filename> and <filename>musl</filename>
4928 have their own implementations.
4929 <filename>meta-mingw</filename> still needs
4930 <filename>libiconv</filename>, so it has
4931 been moved to <filename>meta-mingw</filename>.
4932 </para></listitem>
4933 <listitem><para>
4934 <emphasis><filename>libpng12</filename>:</emphasis>
4935 This recipe was previously needed for LSB. The current
4936 <filename>libpng</filename> is 1.6.x.
4937 </para></listitem>
4938 <listitem><para>
4939 <emphasis><filename>libpod-plainer-perl</filename>:</emphasis>
4940 This recipe was previously needed for LSB 4, no longer
4941 needed.
4942 </para></listitem>
4943 <listitem><para>
4944 <emphasis><filename>linux-yocto (4.1)</filename>:</emphasis>
4945 This recipe was removed in favor of 4.4, 4.9, 4.10 and 4.12.
4946 </para></listitem>
4947 <listitem><para>
4948 <emphasis><filename>mailx</filename>:</emphasis>
4949 This recipe was previously only needed for LSB
4950 compatibility, and upstream is defunct.
4951 </para></listitem>
4952 <listitem><para>
4953 <emphasis><filename>mesa (git version only)</filename>:</emphasis>
4954 The git version recipe was stale with respect to the release
4955 version.
4956 </para></listitem>
4957 <listitem><para>
4958 <emphasis><filename>ofono (git version only)</filename>:</emphasis>
4959 The git version recipe was stale with respect to the release
4960 version.
4961 </para></listitem>
4962 <listitem><para>
4963 <emphasis><filename>portmap</filename>:</emphasis>
4964 This recipe is obsolete and is superseded by
4965 <filename>rpcbind</filename>.
4966 </para></listitem>
4967 <listitem><para>
4968 <emphasis><filename>python3-pygpgme</filename>:</emphasis>
4969 This recipe is old and unmaintained. It was previously
4970 required by <filename>dnf</filename>, which has switched
4971 to official <filename>gpgme</filename> Python bindings.
4972 </para></listitem>
4973 <listitem><para>
4974 <emphasis><filename>python-async</filename>:</emphasis>
4975 This recipe has been removed in favor of the Python 3
4976 version.
4977 </para></listitem>
4978 <listitem><para>
4979 <emphasis><filename>python-gitdb</filename>:</emphasis>
4980 This recipe has been removed in favor of the Python 3
4981 version.
4982 </para></listitem>
4983 <listitem><para>
4984 <emphasis><filename>python-git</filename>:</emphasis>
4985 This recipe was removed in favor of the Python 3
4986 version.
4987 </para></listitem>
4988 <listitem><para>
4989 <emphasis><filename>python-mako</filename>:</emphasis>
4990 This recipe was removed in favor of the Python 3
4991 version.
4992 </para></listitem>
4993 <listitem><para>
4994 <emphasis><filename>python-pexpect</filename>:</emphasis>
4995 This recipe was removed in favor of the Python 3 version.
4996 </para></listitem>
4997 <listitem><para>
4998 <emphasis><filename>python-ptyprocess</filename>:</emphasis>
4999 This recipe was removed in favor of Python the 3 version.
5000 </para></listitem>
5001 <listitem><para>
5002 <emphasis><filename>python-pycurl</filename>:</emphasis>
5003 Nothing is using this recipe in OpenEmbedded-Core
5004 (i.e. <filename>meta-oe</filename>).
5005 </para></listitem>
5006 <listitem><para>
5007 <emphasis><filename>python-six</filename>:</emphasis>
5008 This recipe was removed in favor of the Python 3 version.
5009 </para></listitem>
5010 <listitem><para>
5011 <emphasis><filename>python-smmap</filename>:</emphasis>
5012 This recipe was removed in favor of the Python 3 version.
5013 </para></listitem>
5014 <listitem><para>
5015 <emphasis><filename>remake</filename>:</emphasis>
5016 Using <filename>remake</filename> as the provider of
5017 <filename>virtual/make</filename> is broken.
5018 Consequently, this recipe is not needed in OpenEmbedded-Core.
5019 </para></listitem>
5020 </itemizedlist>
5021 </para>
5022 </section>
5023
5024 <section id='migration-2.4-kernel-device-tree-move'>
5025 <title>Kernel Device Tree Move</title>
5026
5027 <para>
5028 Kernel Device Tree support is now easier to enable in a kernel
5029 recipe.
5030 The Device Tree code has moved to a
5031 <link linkend='ref-classes-kernel-devicetree'><filename>kernel-devicetree</filename></link>
5032 class.
5033 Functionality is automatically enabled for any recipe that inherits
5034 the
5035 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
5036 class and sets the
5037 <link linkend='var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></link>
5038 variable.
5039 The previous mechanism for doing this,
5040 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>,
5041 is still available to avoid breakage, but triggers a
5042 deprecation warning.
5043 Future releases of the Yocto Project will remove
5044 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>.
5045 It is advisable to remove any <filename>require</filename>
5046 statements that request
5047 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>
5048 from any custom kernel recipes you might have.
5049 This will avoid breakage in post 2.4 releases.
5050 </para>
5051 </section>
5052
5053 <section id='migration-2.4-package-qa-changes'>
5054 <title>Package QA Changes</title>
5055
5056 <para>
5057 The following package QA changes took place:
5058 <itemizedlist>
5059 <listitem><para>
5060 The "unsafe-references-in-scripts" QA check has been
5061 removed.
5062 </para></listitem>
5063 <listitem><para>
5064 If you refer to <filename>${COREBASE}/LICENSE</filename>
5065 within
5066 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
5067 you receive a warning because this file is a description of
5068 the license for OE-Core.
5069 Use <filename>${COMMON_LICENSE_DIR}/MIT</filename>
5070 if your recipe is MIT-licensed and you cannot use the
5071 preferred method of referring to a file within the source
5072 tree.
5073 </para></listitem>
5074 </itemizedlist>
5075 </para>
5076 </section>
5077
5078 <section id='migration-2.4-readme-changes'>
5079 <title><filename>README</filename> File Changes</title>
5080
5081 <para>
5082 The following are changes to <filename>README</filename> files:
5083 <itemizedlist>
5084 <listitem><para>
5085 The main Poky <filename>README</filename> file has been
5086 moved to the <filename>meta-poky</filename> layer and
5087 has been renamed <filename>README.poky</filename>.
5088 A symlink has been created so that references to the old
5089 location work.
5090 </para></listitem>
5091 <listitem><para>
5092 The <filename>README.hardware</filename> file has been moved
5093 to <filename>meta-yocto-bsp</filename>.
5094 A symlink has been created so that references to the old
5095 location work.
5096 </para></listitem>
5097 <listitem><para>
5098 A <filename>README.qemu</filename> file has been created
5099 with coverage of the <filename>qemu*</filename> machines.
5100 </para></listitem>
5101 </itemizedlist>
5102 </para>
5103 </section>
5104
5105 <section id='migration-2.4-miscellaneous-changes'>
5106 <title>Miscellaneous Changes</title>
5107
5108 <para>
5109 The following are additional changes:
5110 <itemizedlist>
5111 <listitem><para>
5112 The <filename>ROOTFS_PKGMANAGE_BOOTSTRAP</filename>
5113 variable and any references to it have been removed.
5114 You should remove this variable from any custom recipes.
5115 </para></listitem>
5116 <listitem><para>
5117 The <filename>meta-yocto</filename> directory has been
5118 removed.
5119 <note>
5120 In the Yocto Project 2.1 release
5121 <filename>meta-yocto</filename> was renamed to
5122 <filename>meta-poky</filename> and the
5123 <filename>meta-yocto</filename> subdirectory remained
5124 to avoid breaking existing configurations.
5125 </note>
5126 </para></listitem>
5127 <listitem><para>
5128 The <filename>maintainers.inc</filename> file, which tracks
5129 maintainers by listing a primary person responsible for each
5130 recipe in OE-Core, has been moved from
5131 <filename>meta-poky</filename> to OE-Core (i.e. from
5132 <filename>meta-poky/conf/distro/include</filename> to
5133 <filename>meta/conf/distro/include</filename>).
5134 </para></listitem>
5135 <listitem><para>
5136 The
5137 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
5138 class now makes a single commit per build rather than one
5139 commit per subdirectory in the repository.
5140 This behavior assumes the commits are enabled with
5141 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
5142 = "1", which is typical.
5143 Previously, the <filename>buildhistory</filename> class made
5144 one commit per subdirectory in the repository in order to
5145 make it easier to see the changes for a particular
5146 subdirectory.
5147 To view a particular change, specify that subdirectory as
5148 the last parameter on the <filename>git show</filename>
5149 or <filename>git diff</filename> commands.
5150 </para></listitem>
5151 <listitem><para>
5152 The <filename>x86-base.inc</filename> file, which is
5153 included by all x86-based machine configurations, now sets
5154 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
5155 using <filename>?=</filename> to "live" rather than
5156 appending with <filename>+=</filename>.
5157 This change makes the default easier to override.
5158 </para></listitem>
5159 <listitem><para>
5160 BitBake fires multiple "BuildStarted" events when
5161 multiconfig is enabled (one per configuration).
5162 For more information, see the
5163 "<ulink url='&YOCTO_DOCS_BB_URL;#events'>Events</ulink>"
5164 section in the BitBake User Manual.
5165 </para></listitem>
5166 <listitem><para>
5167 By default, the <filename>security_flags.inc</filename> file
5168 sets a
5169 <link linkend='var-GCCPIE'><filename>GCCPIE</filename></link>
5170 variable with an option to enable Position Independent
5171 Executables (PIE) within <filename>gcc</filename>.
5172 Enabling PIE in the GNU C Compiler (GCC), makes Return
5173 Oriented Programming (ROP) attacks much more difficult to
5174 execute.
5175 </para></listitem>
5176 <listitem><para>
5177 OE-Core now provides a
5178 <filename>bitbake-layers</filename> plugin that implements
5179 a "create-layer" subcommand.
5180 The implementation of this subcommand has resulted in the
5181 <filename>yocto-layer</filename> script being deprecated and
5182 will likely be removed in the next Yocto Project release.
5183 </para></listitem>
5184 <listitem><para>
5185 The <filename>vmdk</filename>, <filename>vdi</filename>,
5186 and <filename>qcow2</filename> image file types are now
5187 used in conjunction with the "wic" image type through
5188 <filename>CONVERSION_CMD</filename>.
5189 Consequently, the equivalent image types are now
5190 <filename>wic.vmdk</filename>, <filename>wic.vdi</filename>,
5191 and <filename>wic.qcow2</filename>, respectively.
5192 </para></listitem>
5193 <listitem><para>
5194 <filename>do_image_&lt;type&gt;[depends]</filename> has
5195 replaced <filename>IMAGE_DEPENDS_&lt;type&gt;</filename>.
5196 If you have your own classes that implement custom image
5197 types, then you need to update them.
5198 </para></listitem>
5199 <listitem><para>
5200 OpenSSL 1.1 has been introduced.
5201 However, the default is still 1.0.x through the
5202 <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
5203 variable.
5204 This preference is set is due to the remaining compatibility
5205 issues with other software.
5206 The
5207 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
5208 variable in the openssl 1.0 recipe now includes "openssl10"
5209 as a marker that can be used in
5210 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
5211 within recipes that build software that still depend on
5212 OpenSSL 1.0.
5213 </para></listitem>
5214 <listitem><para>
5215 To ensure consistent behavior, BitBake's "-r" and "-R"
5216 options (i.e. prefile and postfile), which are used to
5217 read or post-read additional configuration files from the
5218 command line, now only affect the current BitBake command.
5219 Before these BitBake changes, these options would "stick"
5220 for future executions.
5221 </para></listitem>
5222 </itemizedlist>
5223 </para>
5224 </section>
5225</section>
5226
5227<section id='moving-to-the-yocto-project-2.5-release'>
5228 <title>Moving to the Yocto Project 2.5 Release</title>
5229
5230 <para>
5231 This section provides migration information for moving to the
5232 Yocto Project 2.5 Release from the prior release.
5233 </para>
5234
5235 <section id='migration-2.5-packaging-changes'>
5236 <title>Packaging Changes</title>
5237
5238 <para>
5239 This section provides information about packaging changes that have
5240 occurred:
5241 <itemizedlist>
5242 <listitem><para>
5243 <emphasis><filename>bind-libs</filename>:</emphasis>
5244 The libraries packaged by the bind recipe are in a
5245 separate <filename>bind-libs</filename> package.
5246 </para></listitem>
5247 <listitem><para>
5248 <emphasis><filename>libfm-gtk</filename>:</emphasis>
5249 The <filename>libfm</filename> GTK+ bindings are split into
5250 a separate <filename>libfm-gtk</filename> package.
5251 </para></listitem>
5252 <listitem><para>
5253 <emphasis><filename>flex-libfl</filename>:</emphasis>
5254 The flex recipe splits out libfl into a separate
5255 <filename>flex-libfl</filename> package to avoid too many
5256 dependencies being pulled in where only the library is
5257 needed.
5258 </para></listitem>
5259 <listitem><para>
5260 <emphasis><filename>grub-efi</filename>:</emphasis>
5261 The <filename>grub-efi</filename> configuration is split
5262 into a separate <filename>grub-bootconf</filename>
5263 recipe.
5264 However, the dependency relationship from
5265 <filename>grub-efi</filename> is through a
5266 virtual/grub-bootconf provider making it possible to have
5267 your own recipe provide the dependency.
5268 Alternatively, you can use a BitBake append file to bring
5269 the configuration back into the
5270 <filename>grub-efi</filename> recipe.
5271 </para></listitem>
5272 <listitem><para>
5273 <emphasis>armv7a Legacy Package Feed Support:</emphasis>
5274 Legacy support is removed for transitioning from
5275 <filename>armv7a</filename> to
5276 <filename>armv7a-vfp-neon</filename> in package feeds,
5277 which was previously enabled by setting
5278 <filename>PKGARCHCOMPAT_ARMV7A</filename>.
5279 This transition occurred in 2011 and active package feeds
5280 should by now be updated to the new naming.
5281 </para></listitem>
5282 </itemizedlist>
5283 </para>
5284 </section>
5285
5286 <section id='migration-2.5-removed-recipes'>
5287 <title>Removed Recipes</title>
5288
5289 <para>
5290 The following recipes have been removed:
5291 <itemizedlist>
5292 <listitem><para>
5293 <emphasis><filename>gcc</filename>:</emphasis>
5294 The version 6.4 recipes are replaced by 7.x.
5295 </para></listitem>
5296 <listitem><para>
5297 <emphasis><filename>gst-player</filename>:</emphasis>
5298 Renamed to <filename>gst-examples</filename> as per
5299 upstream.
5300 </para></listitem>
5301 <listitem><para>
5302 <emphasis><filename>hostap-utils</filename>:</emphasis>
5303 This software package is obsolete.
5304 </para></listitem>
5305 <listitem><para>
5306 <emphasis><filename>latencytop</filename>:</emphasis>
5307 This recipe is no longer maintained upstream.
5308 The last release was in 2009.
5309 </para></listitem>
5310 <listitem><para>
5311 <emphasis><filename>libpfm4</filename>:</emphasis>
5312 The only file that requires this recipe is
5313 <filename>oprofile</filename>, which has been removed.
5314 </para></listitem>
5315 <listitem><para>
5316 <emphasis><filename>linux-yocto</filename>:</emphasis>
5317 The version 4.4, 4.9, and 4.10 recipes have been removed.
5318 Versions 4.12, 4.14, and 4.15 remain.
5319 </para></listitem>
5320 <listitem><para>
5321 <emphasis><filename>man</filename>:</emphasis>
5322 This recipe has been replaced by modern
5323 <filename>man-db</filename>
5324 </para></listitem>
5325 <listitem><para>
5326 <emphasis><filename>mkelfimage</filename>:</emphasis>
5327 This tool has been removed in the upstream coreboot project,
5328 and is no longer needed with the removal of the ELF image
5329 type.
5330 </para></listitem>
5331 <listitem><para>
5332 <emphasis><filename>nativesdk-postinst-intercept</filename>:</emphasis>
5333 This recipe is not maintained.
5334 </para></listitem>
5335 <listitem><para>
5336 <emphasis><filename>neon</filename>:</emphasis>
5337 This software package is no longer maintained upstream and
5338 is no longer needed by anything in OpenEmbedded-Core.
5339 </para></listitem>
5340 <listitem><para>
5341 <emphasis><filename>oprofile</filename>:</emphasis>
5342 The functionality of this recipe is replaced by
5343 <filename>perf</filename> and keeping compatibility on
5344 an ongoing basis with <filename>musl</filename> is
5345 difficult.
5346 </para></listitem>
5347 <listitem><para>
5348 <emphasis><filename>pax</filename>:</emphasis>
5349 This software package is obsolete.
5350 </para></listitem>
5351 <listitem><para>
5352 <emphasis><filename>stat</filename>:</emphasis>
5353 This software package is not maintained upstream.
5354 <filename>coreutils</filename> provides a modern stat binary.
5355 </para></listitem>
5356 <listitem><para>
5357 <emphasis><filename>zisofs-tools-native</filename>:</emphasis>
5358 This recipe is no longer needed because the compressed
5359 ISO image feature has been removed.
5360 </para></listitem>
5361 </itemizedlist>
5362 </para>
5363 </section>
5364
5365 <section id='migration-2.5-scripts-and-tools-changes'>
5366 <title>Scripts and Tools Changes</title>
5367
5368 <para>
5369 The following are changes to scripts and tools:
5370 <itemizedlist>
5371 <listitem><para>
5372 <emphasis><filename>yocto-bsp</filename>,
5373 <filename>yocto-kernel</filename>, and
5374 <filename>yocto-layer</filename></emphasis>:
5375 The <filename>yocto-bsp</filename>,
5376 <filename>yocto-kernel</filename>, and
5377 <filename>yocto-layer</filename> scripts previously shipped
5378 with poky but not in OpenEmbedded-Core have been removed.
5379 These scripts are not maintained and are outdated.
5380 In many cases, they are also limited in scope.
5381 The <filename>bitbake-layers create-layer</filename> command
5382 is a direct replacement for <filename>yocto-layer</filename>.
5383 See the documentation to create a BSP or kernel recipe in
5384 the
5385 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-kernel-recipe-example'>BSP Kernel Recipe Example</ulink>"
5386 section.
5387 </para></listitem>
5388 <listitem><para>
5389 <emphasis><filename>devtool finish</filename>:</emphasis>
5390 <filename>devtool finish</filename> now exits with an error
5391 if there are uncommitted changes or a rebase/am in progress
5392 in the recipe's source repository.
5393 If this error occurs, there might be uncommitted changes
5394 that will not be included in updates to the patches applied
5395 by the recipe.
5396 A -f/--force option is provided for situations that the
5397 uncommitted changes are inconsequential and you want to
5398 proceed regardless.
5399 </para></listitem>
5400 <listitem><para>
5401 <emphasis><filename>scripts/oe-setup-rpmrepo</filename> script:</emphasis>
5402 The functionality of
5403 <filename>scripts/oe-setup-rpmrepo</filename> is replaced by
5404 <filename>bitbake package-index</filename>.
5405 </para></listitem>
5406 <listitem><para>
5407 <emphasis><filename>scripts/test-dependencies.sh</filename> script:</emphasis>
5408 The script is largely made obsolete by the
5409 recipe-specific sysroots functionality introduced in the
5410 previous release.
5411 </para></listitem>
5412 </itemizedlist>
5413 </para>
5414 </section>
5415
5416 <section id='migration-2.5-bitbake-changes'>
5417 <title>BitBake Changes</title>
5418
5419 <para>
5420 The following are BitBake changes:
5421 <itemizedlist>
5422 <listitem><para>
5423 The <filename>--runall</filename> option has changed.
5424 There are two different behaviors people might want:
5425 <itemizedlist>
5426 <listitem><para>
5427 <emphasis>Behavior A:</emphasis>
5428 For a given target (or set of targets) look through
5429 the task graph and run task X only if it is present
5430 and will be built.
5431 </para></listitem>
5432 <listitem><para>
5433 <emphasis>Behavior B:</emphasis>
5434 For a given target (or set of targets) look through
5435 the task graph and run task X if any recipe in the
5436 taskgraph has such a target, even if it is not in
5437 the original task graph.
5438 </para></listitem>
5439 </itemizedlist>
5440 The <filename>--runall</filename> option now performs
5441 "Behavior B".
5442 Previously <filename>--runall</filename> behaved like
5443 "Behavior A".
5444 A <filename>--runonly</filename> option has been added to
5445 retain the ability to perform "Behavior A".
5446 </para></listitem>
5447 <listitem><para>
5448 Several explicit "run this task for all recipes in the
5449 dependency tree" tasks have been removed (e.g.
5450 <filename>fetchall</filename>,
5451 <filename>checkuriall</filename>, and the
5452 <filename>*all</filename> tasks provided by the
5453 <filename>distrodata</filename> and
5454 <filename>archiver</filename> classes).
5455 There is a BitBake option to complete this for any arbitrary
5456 task. For example:
5457 <literallayout class='monospaced'>
5458 bitbake &lt;target&gt; -c fetchall
5459 </literallayout>
5460 should now be replaced with:
5461 <literallayout class='monospaced'>
5462 bitbake &lt;target&gt; --runall=fetch
5463 </literallayout>
5464 </para></listitem>
5465 </itemizedlist>
5466 </para>
5467 </section>
5468
5469 <section id='migration-2.5-python-and-python3-changes'>
5470 <title>Python and Python 3 Changes</title>
5471
5472 <para>
5473 The following are auto-packaging changes to Python and Python 3:
5474 </para>
5475 <para>
5476 The script-managed <filename>python-*-manifest.inc</filename> files
5477 that were previously used to generate Python and Python 3
5478 packages have been replaced with a JSON-based file that is
5479 easier to read and maintain.
5480 A new task is available for maintainers of the Python recipes to
5481 update the JSON file when upgrading to new Python versions.
5482 You can now edit the file directly instead of having to edit a
5483 script and run it to update the file.
5484 </para>
5485 <para>
5486 One particular change to note is that the Python recipes no longer
5487 have build-time provides for their packages.
5488 This assumes <filename>python-foo</filename> is one of the packages
5489 provided by the Python recipe.
5490 You can no longer run <filename>bitbake python-foo</filename> or
5491 have a <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> on
5492 <filename>python-foo</filename>, but doing either of the following
5493 causes the package to work as expected:
5494 <literallayout class='monospaced'>
5495 IMAGE_INSTALL_append = " python-foo"
5496 </literallayout>
5497 or
5498 <literallayout class='monospaced'>
5499 RDEPENDS_${PN} = "python-foo"
5500 </literallayout>
5501 The earlier build-time provides behavior was a quirk of the way the
5502 Python manifest file was created.
5503 For more information on this change please see
5504 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce'>this commit</ulink>.
5505 </para>
5506 </section>
5507
5508 <section id='migration-2.5-miscellaneous-changes'>
5509 <title>Miscellaneous Changes</title>
5510
5511 <para>
5512 The following are additional changes:
5513 <itemizedlist>
5514 <listitem><para>
5515 The <filename>kernel</filename> class supports building
5516 packages for multiple kernels.
5517 If your kernel recipe or <filename>.bbappend</filename> file
5518 mentions packaging at all, you should replace references to
5519 the kernel in package names with
5520 <filename>${KERNEL_PACKAGE_NAME}</filename>.
5521 For example, if you disable automatic installation of the
5522 kernel image using
5523 <filename>RDEPENDS_kernel-base = ""</filename> you can avoid
5524 warnings using
5525 <filename>RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""</filename>
5526 instead.
5527 </para></listitem>
5528 <listitem><para>
5529 The <filename>buildhistory</filename> class commits changes
5530 to the repository by default so you no longer need to set
5531 <filename>BUILDHISTORY_COMMIT = "1"</filename>.
5532 If you want to disable commits you need to set
5533 <filename>BUILDHISTORY_COMMIT = "0"</filename> in your
5534 configuration.
5535 </para></listitem>
5536 <listitem><para>
5537 The <filename>beaglebone</filename> reference machine has
5538 been renamed to <filename>beaglebone-yocto</filename>.
5539 The <filename>beaglebone-yocto</filename> BSP is a reference
5540 implementation using only mainline components available in
5541 OpenEmbedded-Core and <filename>meta-yocto-bsp</filename>,
5542 whereas Texas Instruments maintains a full-featured BSP in
5543 the <filename>meta-ti</filename> layer.
5544 This rename avoids the previous name clash that existed
5545 between the two BSPs.
5546 </para></listitem>
5547 <listitem><para>
5548 The <filename>update-alternatives</filename> class no longer
5549 works with SysV <filename>init</filename> scripts because
5550 this usage has been problematic.
5551 Also, the <filename>sysklogd</filename> recipe no longer
5552 uses <filename>update-alternatives</filename> because it is
5553 incompatible with other implementations.
5554 </para></listitem>
5555 <listitem><para>
5556 By default, the
5557 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
5558 class uses <filename>ninja</filename> instead of
5559 <filename>make</filename> for building.
5560 This improves build performance.
5561 If a recipe is broken with <filename>ninja</filename>, then
5562 the recipe can set
5563 <filename>OECMAKE_GENERATOR = "Unix Makefiles"</filename>
5564 to change back to <filename>make</filename>.
5565 </para></listitem>
5566 <listitem><para>
5567 The previously deprecated <filename>base_*</filename>
5568 functions have been removed in favor of their replacements
5569 in <filename>meta/lib/oe</filename> and
5570 <filename>bitbake/lib/bb</filename>.
5571 These are typically used from recipes and classes.
5572 Any references to the old functions must be updated.
5573 The following table shows the removed functions and their
5574 replacements:
5575
5576 <literallayout class='monospaced'>
5577 <emphasis>Removed</emphasis> <emphasis>Replacement</emphasis>
5578 ============================ ============================
5579 base_path_join() oe.path.join()
5580 base_path_relative() oe.path.relative()
5581 base_path_out() oe.path.format_display()
5582 base_read_file() oe.utils.read_file()
5583 base_ifelse() oe.utils.ifelse()
5584 base_conditional() oe.utils.conditional()
5585 base_less_or_equal() oe.utils.less_or_equal()
5586 base_version_less_or_equal() oe.utils.version_less_or_equal()
5587 base_contains() bb.utils.contains()
5588 base_both_contain() oe.utils.both_contain()
5589 base_prune_suffix() oe.utils.prune_suffix()
5590 oe_filter() oe.utils.str_filter()
5591 oe_filter_out() oe.utils.str_filter_out() (or use the _remove operator).
5592 </literallayout>
5593 </para></listitem>
5594 <listitem><para>
5595 Using <filename>exit 1</filename> to explicitly defer a
5596 postinstall script until first boot is now deprecated since
5597 it is not an obvious mechanism and can mask actual errors.
5598 If you want to explicitly defer a postinstall to first boot
5599 on the target rather than at <filename>rootfs</filename>
5600 creation time, use
5601 <filename>pkg_postinst_ontarget()</filename>
5602 or call
5603 <filename>postinst_intercept delay_to_first_boot</filename>
5604 from <filename>pkg_postinst()</filename>.
5605 Any failure of a <filename>pkg_postinst()</filename>
5606 script (including <filename>exit 1</filename>)
5607 will trigger a warning during
5608 <filename>do_rootfs</filename>.</para>
5609
5610 <para>For more information, see the
5611 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
5612 section in the Yocto Project Development Tasks Manual.
5613 </para></listitem>
5614 <listitem><para>
5615 The <filename>elf</filename> image type has been removed.
5616 This image type was removed because the
5617 <filename>mkelfimage</filename> tool
5618 that was required to create it is no longer provided by
5619 coreboot upstream and required updating every time
5620 <filename>binutils</filename> updated.
5621 </para></listitem>
5622 <listitem><para>
5623 Support for .iso image compression (previously enabled
5624 through <filename>COMPRESSISO = "1"</filename>) has been
5625 removed.
5626 The userspace tools (<filename>zisofs-tools</filename>) are
5627 unmaintained and <filename>squashfs</filename> provides
5628 better performance and compression.
5629 In order to build a live image with squashfs+lz4 compression
5630 enabled you should now set
5631 <filename>LIVE_ROOTFS_TYPE = "squashfs-lz4"</filename>
5632 and ensure that <filename>live</filename>
5633 is in <filename>IMAGE_FSTYPES</filename>.
5634 </para></listitem>
5635 <listitem><para>
5636 Recipes with an unconditional dependency on
5637 <filename>libpam</filename> are only buildable with
5638 <filename>pam</filename> in
5639 <filename>DISTRO_FEATURES</filename>.
5640 If the dependency is truly optional then it is recommended
5641 that the dependency be conditional upon
5642 <filename>pam</filename> being in
5643 <filename>DISTRO_FEATURES</filename>.
5644 </para></listitem>
5645 <listitem><para>
5646 For EFI-based machines, the bootloader
5647 (<filename>grub-efi</filename> by default) is installed into
5648 the image at /boot.
5649 Wic can be used to split the bootloader into separate boot
5650 and rootfs partitions if necessary.
5651 </para></listitem>
5652 <listitem><para>
5653 Patches whose context does not match exactly (i.e. where
5654 patch reports "fuzz" when applying) will generate a
5655 warning.
5656 For an example of this see
5657 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57'>this commit</ulink>.
5658 </para></listitem>
5659 <listitem><para>
5660 Layers are expected to set
5661 <filename>LAYERSERIES_COMPAT_layername</filename>
5662 to match the version(s) of OpenEmbedded-Core they are
5663 compatible with.
5664 This is specified as codenames using spaces to separate
5665 multiple values (e.g. "rocko sumo").
5666 If a layer does not set
5667 <filename>LAYERSERIES_COMPAT_layername</filename>, a warning
5668 will is shown.
5669 If a layer sets a value that does not include the current
5670 version ("sumo" for the 2.5 release), then an error will be
5671 produced.
5672 </para></listitem>
5673 <listitem><para>
5674 The <filename>TZ</filename> environment variable is set to
5675 "UTC" within the build environment in order to fix
5676 reproducibility problems in some recipes.
5677 </para></listitem>
5678 </itemizedlist>
5679 </para>
5680 </section>
5681</section>
5682
5683<section id='moving-to-the-yocto-project-2.6-release'>
5684 <title>Moving to the Yocto Project 2.6 Release</title>
5685
5686 <para>
5687 This section provides migration information for moving to the
5688 Yocto Project 2.6 Release from the prior release.
5689 </para>
5690
5691 <section id='migration-2.6-gcc-changes'>
5692 <title>GCC 8.2 is Now Used by Default</title>
5693
5694 <para>
5695 The GNU Compiler Collection version 8.2 is now used by default
5696 for compilation.
5697 For more information on what has changed in the GCC 8.x release,
5698 see
5699 <ulink url='https://gcc.gnu.org/gcc-8/changes.html'></ulink>.
5700 </para>
5701
5702 <para>
5703 If you still need to compile with version 7.x, GCC 7.3 is
5704 also provided.
5705 You can select this version by setting the
5706 and can be selected by setting the
5707 <link linkend='var-GCCVERSION'><filename>GCCVERSION</filename></link>
5708 variable to "7.%" in your configuration.
5709 </para>
5710 </section>
5711
5712 <section id='migration-2.6-removed-recipes'>
5713 <title>Removed Recipes</title>
5714
5715 <para>
5716 The following recipes have been removed:
5717 <literallayout class='monospaced'>
5718 <emphasis><filename>beecrypt</filename>:</emphasis> No longer needed since moving to RPM 4.
5719 <emphasis><filename>bigreqsproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5720 <emphasis><filename>calibrateproto</filename>:</emphasis> Removed in favor of <filename>xinput</filename>.
5721 <emphasis><filename>compositeproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5722 <emphasis><filename>damageproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5723 <emphasis><filename>dmxproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5724 <emphasis><filename>dri2proto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5725 <emphasis><filename>dri3proto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5726 <emphasis><filename>eee-acpi-scripts</filename>:</emphasis> Became obsolete.
5727 <emphasis><filename>fixesproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5728 <emphasis><filename>fontsproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5729 <emphasis><filename>fstests</filename>:</emphasis> Became obsolete.
5730 <emphasis><filename>gccmakedep</filename>:</emphasis> No longer used.
5731 <emphasis><filename>glproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5732 <emphasis><filename>gnome-desktop3</filename>:</emphasis> No longer needed. This recipe has moved to <filename>meta-oe</filename>.
5733 <emphasis><filename>icon-naming-utils</filename>:</emphasis> No longer used since the Sato theme was removed in 2016.
5734 <emphasis><filename>inputproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5735 <emphasis><filename>kbproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5736 <emphasis><filename>libusb-compat</filename>:</emphasis> Became obsolete.
5737 <emphasis><filename>libuser</filename>:</emphasis> Became obsolete.
5738 <emphasis><filename>libnfsidmap</filename>:</emphasis> No longer an external requirement since <filename>nfs-utils</filename> 2.2.1. <filename>libnfsidmap</filename> is now integrated.
5739 <emphasis><filename>libxcalibrate</filename>:</emphasis> No longer needed with <filename>xinput</filename>
5740 <emphasis><filename>mktemp</filename>:</emphasis> Became obsolete. The <filename>mktemp</filename> command is provided by both <filename>busybox</filename> and <filename>coreutils</filename>.
5741 <emphasis><filename>ossp-uuid</filename>:</emphasis> Is not being maintained and has mostly been replaced by <filename>uuid.h</filename> in <filename>util-linux</filename>.
5742 <emphasis><filename>pax-utils</filename>:</emphasis> No longer needed. Previous QA tests that did use this recipe are now done at build time.
5743 <emphasis><filename>pcmciautils</filename>:</emphasis> Became obsolete.
5744 <emphasis><filename>pixz</filename>:</emphasis> No longer needed. <filename>xz</filename> now supports multi-threaded compression.
5745 <emphasis><filename>presentproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5746 <emphasis><filename>randrproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5747 <emphasis><filename>recordproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5748 <emphasis><filename>renderproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5749 <emphasis><filename>resourceproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5750 <emphasis><filename>scrnsaverproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5751 <emphasis><filename>trace-cmd</filename>:</emphasis> Became obsolete. <filename>perf</filename> replaced this recipe's functionally.
5752 <emphasis><filename>videoproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5753 <emphasis><filename>wireless-tools</filename>:</emphasis> Became obsolete. Superseded by <filename>iw</filename>.
5754 <emphasis><filename>xcmiscproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5755 <emphasis><filename>xextproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5756 <emphasis><filename>xf86dgaproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5757 <emphasis><filename>xf86driproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5758 <emphasis><filename>xf86miscproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5759 <emphasis><filename>xf86-video-omapfb</filename>:</emphasis> Became obsolete. Use kernel modesetting driver instead.
5760 <emphasis><filename>xf86-video-omap</filename>:</emphasis> Became obsolete. Use kernel modesetting driver instead.
5761 <emphasis><filename>xf86vidmodeproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5762 <emphasis><filename>xineramaproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5763 <emphasis><filename>xproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5764 <emphasis><filename>yasm</filename>:</emphasis> No longer needed since previous usages are now satisfied by <filename>nasm</filename>.
5765 </literallayout>
5766 </para>
5767 </section>
5768
5769 <section id='migration-2.6-packaging-changes'>
5770 <title>Packaging Changes</title>
5771
5772 <para>
5773 The following packaging changes have been made:
5774 <itemizedlist>
5775 <listitem><para>
5776 <emphasis><filename>cmake</filename>:</emphasis>
5777 <filename>cmake.m4</filename> and
5778 <filename>toolchain</filename> files have been moved to the
5779 main package.
5780 </para></listitem>
5781 <listitem><para>
5782 <emphasis><filename>iptables</filename>:</emphasis>
5783 The <filename>iptables</filename> modules have been split
5784 into separate packages.
5785 </para></listitem>
5786 <listitem><para>
5787 <emphasis><filename>alsa-lib</filename>:</emphasis>
5788 <filename>libasound</filename> is now in the main
5789 <filename>alsa-lib</filename> package instead of
5790 <filename>libasound</filename>.
5791 </para></listitem>
5792 <listitem><para>
5793 <emphasis><filename>glibc</filename>:</emphasis>
5794 <filename>libnss-db</filename> is now in its own package
5795 along with a <filename>/var/db/makedbs.sh</filename>
5796 script to update databases.
5797 </para></listitem>
5798 <listitem><para>
5799 <emphasis><filename>python</filename> and <filename>python3</filename>:</emphasis>
5800 The main package has been removed from the recipe.
5801 You must install specific packages or
5802 <filename>python-modules</filename> /
5803 <filename>python3-modules</filename> for everything.
5804 </para></listitem>
5805 <listitem><para>
5806 <emphasis><filename>systemtap</filename>:</emphasis>
5807 Moved <filename>systemtap-exporter</filename> into its own
5808 package.
5809 </para></listitem>
5810 </itemizedlist>
5811 </para>
5812 </section>
5813
5814 <section id='migration-2.6-xorg-protocol-dependencies'>
5815 <title>XOrg Protocol dependencies</title>
5816
5817 <para>
5818 The "*proto" upstream repositories have been combined into one
5819 "xorgproto" repository.
5820 Thus, the corresponding recipes have also been combined into a
5821 single <filename>xorgproto</filename> recipe.
5822 Any recipes that depend upon the older <filename>*proto</filename>
5823 recipes need to be changed to depend on the newer
5824 <filename>xorgproto</filename> recipe instead.
5825 </para>
5826
5827 <para>
5828 For names of recipes removed because of this repository change,
5829 see the
5830 <link linkend="migration-2.6-removed-recipes">Removed Recipes</link>
5831 section.
5832 </para>
5833 </section>
5834
5835 <section id='migration-2.6-distutils-distutils3-fetching-dependencies'>
5836 <title><filename>distutils</filename> and <filename>distutils3</filename> Now Prevent Fetching Dependencies During the <filename>do_configure</filename> Task</title>
5837
5838 <para>
5839 Previously, it was possible for Python recipes that inherited
5840 the
5841 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>
5842 and
5843 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>
5844 classes to fetch code during the
5845 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
5846 task to satisfy dependencies mentioned in
5847 <filename>setup.py</filename> if those dependencies were not
5848 provided in the sysroot (i.e. recipes providing the dependencies
5849 were missing from
5850 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>).
5851 <note>
5852 This change affects classes beyond just the two mentioned
5853 (i.e. <filename>distutils</filename> and
5854 <filename>distutils3</filename>).
5855 Any recipe that inherits <filename>distutils*</filename>
5856 classes are affected.
5857 For example, the <filename>setuptools</filename> and
5858 <filename>setuptools3</filename> recipes are affected since
5859 they inherit the <filename>distutils*</filename> classes.
5860 </note>
5861 </para>
5862
5863 <para>
5864 Fetching these types of dependencies that are not provided in the
5865 sysroot negatively affects the ability to reproduce builds.
5866 This type of fetching is now explicitly disabled.
5867 Consequently, any missing dependencies in Python recipes that
5868 use these classes now result in an error during the
5869 <filename>do_configure</filename> task.
5870 </para>
5871 </section>
5872
5873 <section id='migration-2.6-linux-yocto-configuration-audit-issues-now-correctly-reported'>
5874 <title><filename>linux-yocto</filename> Configuration Audit Issues Now Correctly Reported</title>
5875
5876 <para>
5877 Due to a bug, the kernel configuration audit functionality was
5878 not writing out any resulting warnings during the build.
5879 This issue is now corrected.
5880 You might notice these warnings now if you have a custom kernel
5881 configuration with a <filename>linux-yocto</filename> style
5882 kernel recipe.
5883 </para>
5884 </section>
5885
5886 <section id='migration-2.6-image-kernel-artifact-naming-changes'>
5887 <title>Image/Kernel Artifact Naming Changes</title>
5888
5889 <para>
5890 The following changes have been made:
5891 <itemizedlist>
5892 <listitem><para>
5893 Name variables (e.g.
5894 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>)
5895 use a new <filename>IMAGE_VERSION_SUFFIX</filename>
5896 variable instead of
5897 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>.
5898 Using <filename>IMAGE_VERSION_SUFFIX</filename> allows
5899 easier and more direct changes.</para>
5900
5901 <para>The <filename>IMAGE_VERSION_SUFFIX</filename>
5902 variable is set in the
5903 <filename>bitbake.conf</filename> configuration file as
5904 follows:
5905 <literallayout class='monospaced'>
5906 IMAGE_VERSION_SUFFIX = "-${DATETIME}"
5907 </literallayout>
5908 </para></listitem>
5909 <listitem><para>
5910 Several variables have changed names for consistency:
5911 <literallayout class='monospaced'>
5912 Old Variable Name New Variable Name
5913 ========================================================
5914 KERNEL_IMAGE_BASE_NAME <link linkend='var-KERNEL_IMAGE_NAME'>KERNEL_IMAGE_NAME</link>
5915 KERNEL_IMAGE_SYMLINK_NAME <link linkend='var-KERNEL_IMAGE_LINK_NAME'>KERNEL_IMAGE_LINK_NAME</link>
5916 MODULE_TARBALL_BASE_NAME <link linkend='var-MODULE_TARBALL_NAME'>MODULE_TARBALL_NAME</link>
5917 MODULE_TARBALL_SYMLINK_NAME <link linkend='var-MODULE_TARBALL_LINK_NAME'>MODULE_TARBALL_LINK_NAME</link>
5918 INITRAMFS_BASE_NAME <link linkend='var-INITRAMFS_NAME'>INITRAMFS_NAME</link>
5919 </literallayout>
5920 </para></listitem>
5921 <listitem><para>
5922 The <filename>MODULE_IMAGE_BASE_NAME</filename> variable
5923 has been removed.
5924 The module tarball name is now controlled directly with the
5925 <link linkend='var-MODULE_TARBALL_NAME'><filename>MODULE_TARBALL_NAME</filename></link>
5926 variable.
5927 </para></listitem>
5928 <listitem><para>
5929 The
5930 <link linkend='var-KERNEL_DTB_NAME'><filename>KERNEL_DTB_NAME</filename></link>
5931 and
5932 <link linkend='var-KERNEL_DTB_LINK_NAME'><filename>KERNEL_DTB_LINK_NAME</filename></link>
5933 variables have been introduced to control kernel Device
5934 Tree Binary (DTB) artifact names instead of mangling
5935 <filename>KERNEL_IMAGE_*</filename> variables.
5936 </para></listitem>
5937 <listitem><para>
5938 The
5939 <link linkend='var-KERNEL_FIT_NAME'><filename>KERNEL_FIT_NAME</filename></link>
5940 and
5941 <link linkend='var-KERNEL_FIT_LINK_NAME'><filename>KERNEL_FIT_LINK_NAME</filename></link>
5942 variables have been introduced to specify the name of
5943 flattened image tree (FIT) kernel images similar to other
5944 deployed artifacts.
5945 </para></listitem>
5946 <listitem><para>
5947 The
5948 <link linkend='var-MODULE_TARBALL_NAME'><filename>MODULE_TARBALL_NAME</filename></link>
5949 and
5950 <link linkend='var-MODULE_TARBALL_LINK_NAME'><filename>MODULE_TARBALL_LINK_NAME</filename></link>
5951 variable values no longer include the "module-" prefix or
5952 ".tgz" suffix.
5953 These parts are now hardcoded so that the values are
5954 consistent with other artifact naming variables.
5955 </para></listitem>
5956 <listitem><para>
5957 Added the
5958 <link linkend='var-INITRAMFS_LINK_NAME'><filename>INITRAMFS_LINK_NAME</filename></link>
5959 variable so that the symlink can be controlled similarly
5960 to other artifact types.
5961 </para></listitem>
5962 <listitem><para>
5963 <link linkend='var-INITRAMFS_NAME'><filename>INITRAMFS_NAME</filename></link>
5964 now uses
5965 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
5966 instead of
5967 "${PV}-${PR}-${MACHINE}-${DATETIME}", which
5968 makes it consistent with other variables.
5969 </para></listitem>
5970 </itemizedlist>
5971 </para>
5972 </section>
5973
5974 <section id='migration-2.6-serial-console-deprecated'>
5975 <title><filename>SERIAL_CONSOLE</filename> Deprecated</title>
5976
5977 <para>
5978 The
5979 <link linkend='var-SERIAL_CONSOLE'><filename>SERIAL_CONSOLE</filename></link>
5980 variable has been functionally replaced by the
5981 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
5982 variable for some time.
5983 With the Yocto Project 2.6 release,
5984 <filename>SERIAL_CONSOLE</filename> has been officially deprecated.
5985 </para>
5986
5987 <para>
5988 <filename>SERIAL_CONSOLE</filename> will continue to work as
5989 before for the 2.6 release.
5990 However, for the sake of future compatibility, it is recommended
5991 that you replace all instances of
5992 <filename>SERIAL_CONSOLE</filename> with
5993 <filename>SERIAL_CONSOLES</filename>.
5994 <note>
5995 The only difference in usage is that
5996 <filename>SERIAL_CONSOLES</filename> expects entries to be
5997 separated using semicolons as compared to
5998 <filename>SERIAL_CONSOLE</filename>, which expects spaces.
5999 </note>
6000 </para>
6001 </section>
6002
6003 <section id='migration-2.6-poky-sets-unknown-configure-option-to-qa-error'>
6004 <title>Configure Script Reports Unknown Options as Errors</title>
6005
6006 <para>
6007 If the configure script reports an unknown option, this now
6008 triggers a QA error instead of a warning.
6009 Any recipes that previously got away with specifying such unknown
6010 options now need to be fixed.
6011 </para>
6012 </section>
6013
6014 <section id='migration-2.6-override-changes'>
6015 <title>Override Changes</title>
6016
6017 <para>
6018 The following changes have occurred:
6019 <itemizedlist>
6020 <listitem><para>
6021 <emphasis>The <filename>virtclass-native</filename> and
6022 <filename>virtclass-nativesdk</filename> Overrides Have
6023 Been Removed:</emphasis>
6024 The <filename>virtclass-native</filename> and
6025 <filename>virtclass-nativesdk</filename> overrides have
6026 been deprecated since 2012 in favor of
6027 <filename>class-native</filename> and
6028 <filename>class-nativesdk</filename>, respectively.
6029 Both <filename>virtclass-native</filename> and
6030 <filename>virtclass-nativesdk</filename> are now dropped.
6031 <note>
6032 The <filename>virtclass-multilib-</filename> overrides
6033 for multilib are still valid.
6034 </note>
6035 </para></listitem>
6036 <listitem><para>
6037 <emphasis>The <filename>forcevariable</filename>
6038 Override Now Has a Higher Priority Than
6039 <filename>libc</filename> Overrides:</emphasis>
6040 The <filename>forcevariable</filename> override is
6041 documented to be the highest priority override.
6042 However, due to a long-standing quirk of how
6043 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
6044 is set, the <filename>libc</filename> overrides (e.g.
6045 <filename>libc-glibc</filename>,
6046 <filename>libc-musl</filename>, and so forth) erroneously
6047 had a higher priority.
6048 This issue is now corrected.</para>
6049
6050 <para>It is likely this change will not cause any
6051 problems.
6052 However, it is possible with some unusual configurations
6053 that you might see a change in behavior if you were
6054 relying on the previous behavior.
6055 Be sure to check how you use
6056 <filename>forcevariable</filename> and
6057 <filename>libc-*</filename> overrides in your custom
6058 layers and configuration files to ensure they make sense.
6059 </para></listitem>
6060 <listitem><para>
6061 <emphasis>The <filename>build-${BUILD_OS}</filename>
6062 Override Has Been Removed:</emphasis>
6063 The <filename>build-${BUILD_OS}</filename>, which is
6064 typically <filename>build-linux</filename>, override has
6065 been removed because building on a host operating system
6066 other than a recent version of Linux is neither supported
6067 nor recommended.
6068 Dropping the override avoids giving the impression that
6069 other host operating systems might be supported.
6070 </para></listitem>
6071 <listitem><para>
6072 The "_remove" operator now preserves whitespace.
6073 Consequently, when specifying list items to remove, be
6074 aware that leading and trailing whitespace resulting from
6075 the removal is retained.</para>
6076
6077 <para>See the
6078 "<ulink url='&YOCTO_DOCS_BB_URL;#removing-override-style-syntax'>Removal (Override Style Syntax)</ulink>"
6079 section in the BitBake User Manual for a detailed example.
6080 </para></listitem>
6081 </itemizedlist>
6082 </para>
6083 </section>
6084
6085 <section id='migration-2.6-systemd-configuration-now-split-out-to-system-conf'>
6086 <title><filename>systemd</filename> Configuration is Now Split Into <filename>systemd-conf</filename></title>
6087
6088 <para>
6089 The configuration for the <filename>systemd</filename> recipe
6090 has been moved into a <filename>system-conf</filename> recipe.
6091 Moving this configuration to a separate recipe avoids the
6092 <filename>systemd</filename> recipe from becoming machine-specific
6093 for cases where machine-specific configurations need to be applied
6094 (e.g. for <filename>qemu*</filename> machines).
6095 </para>
6096
6097 <para>
6098 Currently, the new recipe packages the following files:
6099 <literallayout class='monospaced'>
6100 ${sysconfdir}/machine-id
6101 ${sysconfdir}/systemd/coredump.conf
6102 ${sysconfdir}/systemd/journald.conf
6103 ${sysconfdir}/systemd/logind.conf
6104 ${sysconfdir}/systemd/system.conf
6105 ${sysconfdir}/systemd/user.conf
6106 </literallayout>
6107 If you previously used bbappend files to append the
6108 <filename>systemd</filename> recipe to change any of the
6109 listed files, you must do so for the
6110 <filename>systemd-conf</filename> recipe instead.
6111 </para>
6112 </section>
6113
6114 <section id='migration-2.6-automatic-testing-changes'>
6115 <title>Automatic Testing Changes</title>
6116
6117 <para>
6118 This section provides information about automatic testing
6119 changes:
6120 <itemizedlist>
6121 <listitem><para>
6122 <emphasis><filename>TEST_IMAGE</filename> Variable Removed:</emphasis>
6123 Prior to this release, you set the
6124 <filename>TEST_IMAGE</filename> variable to "1" to
6125 enable automatic testing for successfully built images.
6126 The <filename>TEST_IMAGE</filename> variable no longer
6127 exists and has been replaced by the
6128 <link linkend='var-TESTIMAGE_AUTO'><filename>TESTIMAGE_AUTO</filename></link>
6129 variable.
6130 </para></listitem>
6131 <listitem><para>
6132 <emphasis>Inheriting the <filename>testimage</filename> and
6133 <filename>testsdk</filename> Classes:</emphasis>
6134 Best practices now dictate that you use the
6135 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
6136 variable rather than the
6137 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
6138 variable when you inherit the
6139 <link linkend='ref-classes-testimage*'><filename>testimage</filename></link>
6140 and
6141 <link linkend='ref-classes-testsdk'><filename>testsdk</filename></link>
6142 classes used for automatic testing.
6143 </para></listitem>
6144 </itemizedlist>
6145 </para>
6146 </section>
6147
6148 <section id='migration-2.6-openssl-changes'>
6149 <title>OpenSSL Changes</title>
6150
6151 <para>
6152 <ulink url='https://www.openssl.org/'>OpenSSL</ulink> has been
6153 upgraded from 1.0 to 1.1.
6154 By default, this upgrade could cause problems for recipes that
6155 have both versions in their dependency chains.
6156 The problem is that both versions cannot be installed together
6157 at build time.
6158 <note>
6159 It is possible to have both versions of the library at runtime.
6160 </note>
6161 </para>
6162 </section>
6163
6164 <section id='migration-2.6-bitbake-changes'>
6165 <title>BitBake Changes</title>
6166
6167 <para>
6168 The server logfile <filename>bitbake-cookerdaemon.log</filename> is
6169 now always placed in the
6170 <link linkend='build-directory'>Build Directory</link>
6171 instead of the current directory.
6172 </para>
6173 </section>
6174
6175 <section id='migration-2.6-security-changes'>
6176 <title>Security Changes</title>
6177
6178 <para>
6179 The Poky distribution now uses security compiler flags by
6180 default.
6181 Inclusion of these flags could cause new failures due to stricter
6182 checking for various potential security issues in code.
6183 </para>
6184 </section>
6185
6186 <section id='migration-2.6-post-installation-changes'>
6187 <title>Post Installation Changes</title>
6188
6189 <para>
6190 You must explicitly mark post installs to defer to the target.
6191 If you want to explicitly defer a postinstall to first boot on
6192 the target rather than at rootfs creation time, use
6193 <filename>pkg_postinst_ontarget()</filename> or call
6194 <filename>postinst_intercept delay_to_first_boot</filename> from
6195 <filename>pkg_postinst()</filename>.
6196 Any failure of a <filename>pkg_postinst()</filename> script
6197 (including exit 1) triggers an error during the
6198 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> task.
6199 </para>
6200
6201 <para>
6202 For more information on post-installation behavior, see the
6203 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
6204 section in the Yocto Project Development Tasks Manual.
6205 </para>
6206 </section>
6207
6208 <section id='migration-2.6-python-3-profile-guided-optimizations'>
6209 <title>Python 3 Profile-Guided Optimization</title>
6210
6211 <para>
6212 The <filename>python3</filename> recipe now enables profile-guided
6213 optimization.
6214 Using this optimization requires a little extra build time in
6215 exchange for improved performance on the target at runtime.
6216 Additionally, the optimization is only enabled if the current
6217 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
6218 has support for user-mode emulation in QEMU (i.e. "qemu-usermode"
6219 is in
6220 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>,
6221 which it is by default).
6222 </para>
6223
6224 <para>
6225 If you wish to disable Python profile-guided optimization
6226 regardless of the value of
6227 <filename>MACHINE_FEATURES</filename>, then ensure that
6228 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
6229 for the <filename>python3</filename> recipe does not contain "pgo".
6230 You could accomplish the latter using the following at the
6231 configuration level:
6232 <literallayout class='monospaced'>
6233 PACKAGECONFIG_remove_pn-python3 = "pgo"
6234 </literallayout>
6235 Alternatively, you can set
6236 <filename>PACKAGECONFIG</filename> using an append file for the
6237 <filename>python3</filename> recipe.
6238 </para>
6239 </section>
6240
6241 <section id='migration-2.6-miscellaneous-changes'>
6242 <title>Miscellaneous Changes</title>
6243
6244 <para>
6245 The following miscellaneous changes occurred:
6246 <itemizedlist>
6247 <listitem><para>
6248 Default to using the Thumb-2 instruction set for armv7a
6249 and above.
6250 If you have any custom recipes that build software that
6251 needs to be built with the ARM instruction set, change the
6252 recipe to set the instruction set as follows:
6253 <literallayout class='monospaced'>
6254 ARM_INSTRUCTION_SET = "arm"
6255 </literallayout>
6256 </para></listitem>
6257 <listitem><para>
6258 <filename>run-postinsts</filename> no longer uses
6259 <filename>/etc/*-postinsts</filename> for
6260 <filename>dpkg/opkg</filename> in favor of built-in
6261 postinst support.
6262 RPM behavior remains unchanged.
6263 </para></listitem>
6264 <listitem><para>
6265 The <filename>NOISO</filename> and
6266 <filename>NOHDD</filename> variables are no longer used.
6267 You now control building <filename>*.iso</filename> and
6268 <filename>*.hddimg</filename> image types directly
6269 by using the
6270 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6271 variable.
6272 </para></listitem>
6273 <listitem><para>
6274 The <filename>scripts/contrib/mkefidisk.sh</filename>
6275 has been removed in favor of Wic.
6276 </para></listitem>
6277 <listitem><para>
6278 <filename>kernel-modules</filename> has been removed from
6279 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
6280 for <filename>qemumips</filename> and
6281 <filename>qemumips64</filename> machines.
6282 Removal also impacts the <filename>x86-base.inc</filename>
6283 file.
6284 <note>
6285 <filename>genericx86</filename> and
6286 <filename>genericx86-64</filename> retain
6287 <filename>kernel-modules</filename> as part of the
6288 <filename>RRECOMMENDS</filename> variable setting.
6289 </note>
6290 </para></listitem>
6291 <listitem><para>
6292 The <filename>LGPLv2_WHITELIST_GPL-3.0</filename>
6293 variable has been removed.
6294 If you are setting this variable in your configuration,
6295 set or append it to the
6296 <filename>WHITELIST_GPL-3.0</filename> variable instead.
6297 </para></listitem>
6298 <listitem><para>
6299 <filename>${ASNEEDED}</filename> is now included in
6300 the
6301 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
6302 variable directly.
6303 The remaining definitions from
6304 <filename>meta/conf/distro/include/as-needed.inc</filename>
6305 have been moved to corresponding recipes.
6306 </para></listitem>
6307 <listitem><para>
6308 Support for DSA host keys has been dropped from the
6309 OpenSSH recipes.
6310 If you are still using DSA keys, you must switch over to a
6311 more secure algorithm as recommended by OpenSSH upstream.
6312 </para></listitem>
6313 <listitem><para>
6314 The <filename>dhcp</filename> recipe now uses the
6315 <filename>dhcpd6.conf</filename> configuration file in
6316 <filename>dhcpd6.service</filename> for IPv6 DHCP rather
6317 than re-using <filename>dhcpd.conf</filename>, which is
6318 now reserved for IPv4.
6319 </para></listitem>
6320 </itemizedlist>
6321 </para>
6322 </section>
6323</section>
6324
6325<section id='moving-to-the-yocto-project-2.7-release'>
6326 <title>Moving to the Yocto Project 2.7 Release</title>
6327
6328 <para>
6329 This section provides migration information for moving to the
6330 Yocto Project 2.7 Release from the prior release.
6331 </para>
6332
6333 <section id='migration-2.7-bitbake-changes'>
6334 <title>BitBake Changes</title>
6335
6336 <para>
6337 The following changes have been made to BitBake:
6338 <itemizedlist>
6339 <listitem><para>
6340 BitBake now checks anonymous Python functions and pure
6341 Python functions (e.g. <filename>def funcname:</filename>)
6342 in the metadata for tab indentation.
6343 If found, BitBake produces a warning.
6344 </para></listitem>
6345 <listitem><para>
6346 Bitbake now checks
6347 <link linkend='var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></link>
6348 for duplicate entries and triggers an error if any are
6349 found.
6350 </para></listitem>
6351 </itemizedlist>
6352 </para>
6353 </section>
6354
6355 <section id='migration-2.7-eclipse-support-dropped'>
6356 <title><trademark class='trade'>Eclipse</trademark> Support Removed</title>
6357
6358 <para>
6359 Support for the Eclipse IDE has been removed.
6360 Support continues for those releases prior to 2.7 that did include
6361 support.
6362 The 2.7 release does not include the Eclipse Yocto plugin.
6363 </para>
6364 </section>
6365
6366 <section id='migration-2.7-qemu-native-splits-system-and-user-mode-parts'>
6367 <title><filename>qemu-native</filename> Splits the System and User-Mode Parts</title>
6368
6369 <para>
6370 The system and user-mode parts of <filename>qemu-native</filename>
6371 are now split.
6372 <filename>qemu-native</filename> provides the user-mode components
6373 and <filename>qemu-system-native</filename> provides the system
6374 components.
6375 If you have recipes that depend on QEMU's system emulation
6376 functionality at build time, they should now depend upon
6377 <filename>qemu-system-native</filename> instead of
6378 <filename>qemu-native</filename>.
6379 </para>
6380 </section>
6381
6382 <section id='migration-2.7-upstream-tracking.inc-removed'>
6383 <title>The <filename>upstream-tracking.inc</filename> File Has Been Removed</title>
6384
6385 <para>
6386 The previously deprecated <filename>upstream-tracking.inc</filename>
6387 file is now removed.
6388 Any <filename>UPSTREAM_TRACKING*</filename> variables are now set
6389 in the corresponding recipes instead.
6390 </para>
6391
6392 <para>
6393 Remove any references you have to the
6394 <filename>upstream-tracking.inc</filename> file in your
6395 configuration.
6396 </para>
6397 </section>
6398
6399 <section id='migration-2.7-distro-features-libc-removed'>
6400 <title>The <filename>DISTRO_FEATURES_LIBC</filename> Variable Has Been Removed</title>
6401
6402 <para>
6403 The <filename>DISTRO_FEATURES_LIBC</filename> variable is no
6404 longer used.
6405 The ability to configure glibc using kconfig has been removed
6406 for quite some time making the <filename>libc-*</filename> features
6407 set no longer effective.
6408 </para>
6409
6410 <para>
6411 Remove any references you have to
6412 <filename>DISTRO_FEATURES_LIBC</filename> in your own layers.
6413 </para>
6414 </section>
6415
6416 <section id='migration-2.7-license-values'>
6417 <title>License Value Corrections</title>
6418
6419 <para>
6420 The following corrections have been made to the
6421 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
6422 values set by recipes:
6423 <literallayout class='monospaced'>
6424 <emphasis>socat</emphasis>: Corrected <filename>LICENSE</filename> to be "GPLv2" rather than
6425 "GPLv2+".
6426
6427 <emphasis>libgfortran</emphasis>: Set license to "GPL-3.0-with-GCC-exception".
6428
6429 <emphasis>elfutils</emphasis>: Removed "Elfutils-Exception" and set to "GPLv2" for shared
6430 libraries
6431 </literallayout>
6432 </para>
6433 </section>
6434
6435 <section id='migration-2.7-packaging-changes'>
6436 <title>Packaging Changes</title>
6437
6438 <para>
6439 This section provides information about packaging changes.
6440 <itemizedlist>
6441 <listitem><para>
6442 <filename>bind</filename>: The
6443 <filename>nsupdate</filename> binary has been moved to
6444 the <filename>bind-utils</filename> package.
6445 </para></listitem>
6446 <listitem><para>
6447 Debug split: The default debug split has been changed to
6448 create separate source packages (i.e.
6449 <replaceable>package_name</replaceable><filename>-dbg</filename>
6450 and
6451 <replaceable>package_name</replaceable><filename>-src</filename>).
6452 If you are currently using <filename>dbg-pkgs</filename>
6453 in
6454 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
6455 to bring in debug symbols and you still need the sources,
6456 you must now also add <filename>src-pkgs</filename> to
6457 <filename>IMAGE_FEATURES</filename>.
6458 Source packages remain in the target portion of the SDK
6459 by default, unless you have set your own value for
6460 <link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>
6461 that does not include <filename>src-pkgs</filename>.
6462 </para></listitem>
6463 <listitem><para>
6464 Mount all using <filename>util-linux</filename>:
6465 <filename>/etc/default/mountall</filename> has
6466 moved into the -mount sub-package.
6467 </para></listitem>
6468 <listitem><para>
6469 Splitting binaries using <filename>util-linux</filename>:
6470 <filename>util-linux</filename> now splits each binary into
6471 its own package for fine-grained control.
6472 The main <filename>util-linux</filename> package pulls in
6473 the individual binary packages using the
6474 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
6475 and
6476 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
6477 variables.
6478 As a result, existing images should not see any changes
6479 assuming
6480 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
6481 is not set.
6482 </para></listitem>
6483 <listitem><para>
6484 <filename>netbase/base-files</filename>:
6485 <filename>/etc/hosts</filename> has moved from
6486 <filename>netbase</filename> to
6487 <filename>base-files</filename>.
6488 </para></listitem>
6489 <listitem><para>
6490 <filename>tzdata</filename>: The main package has been
6491 converted to an empty meta package that pulls in all
6492 <filename>tzdata</filename> packages by default.
6493 </para></listitem>
6494 <listitem><para>
6495 <filename>lrzsz</filename>: This package has been removed
6496 from <filename>packagegroup-self-hosted</filename> and
6497 <filename>packagegroup-core-tools-testapps</filename>.
6498 The X/Y/ZModem support is less likely to be needed on
6499 modern systems.
6500 If you are relying on these packagegroups to include the
6501 <filename>lrzsz</filename> package in your image, you
6502 now need to explicitly add the package.
6503 </para></listitem>
6504 </itemizedlist>
6505 </para>
6506 </section>
6507
6508 <section id='migration-2.7-removed-recipes'>
6509 <title>Removed Recipes</title>
6510
6511 <para>
6512 The following recipes have been removed:
6513 <literallayout class='monospaced'>
6514 <emphasis>gcc</emphasis>: Drop version 7.3 recipes. Version 8.3 now remains.
6515
6516 <emphasis>linux-yocto</emphasis>: Drop versions 4.14 and 4.18 recipes. Versions 4.19 and 5.0 remain.
6517
6518 <emphasis>go</emphasis>: Drop version 1.9 recipes. Versions 1.11 and 1.12 remain.
6519
6520 <emphasis>xvideo-tests</emphasis>: Became obsolete.
6521
6522 <emphasis>libart-lgpl</emphasis>: Became obsolete.
6523
6524 <emphasis>gtk-icon-utils-native</emphasis>: These tools are now provided by gtk+3-native
6525
6526 <emphasis>gcc-cross-initial</emphasis>: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
6527
6528 <emphasis>gcc-crosssdk-initial</emphasis>: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
6529
6530 <emphasis>glibc-initial</emphasis>: Removed because the benefits of having it for site_config are
6531 currently outweighed by the cost of building the recipe.
6532 </literallayout>
6533 </para>
6534 </section>
6535
6536 <section id='migration-2.7-removed-classes'>
6537 <title>Removed Classes</title>
6538
6539 <para>
6540 The following classes have been removed:
6541 <literallayout class='monospaced'>
6542 <emphasis>distutils-tools</emphasis>: This class was never used.
6543
6544 <emphasis>bugzilla.bbclass</emphasis>: Became obsolete.
6545
6546 <emphasis>distrodata</emphasis>: This functionally has been replaced by a more modern
6547 tinfoil-based implementation.
6548 </literallayout>
6549 </para>
6550 </section>
6551
6552 <section id='migration-2.7-miscellaneous-changes'>
6553 <title>Miscellaneous Changes</title>
6554
6555 <para>
6556 The following miscellaneous changes occurred:
6557 <itemizedlist>
6558 <listitem><para>
6559 The <filename>distro</filename> subdirectory of the Poky
6560 repository has been removed from the top-level
6561 <filename>scripts</filename> directory.
6562 </para></listitem>
6563 <listitem><para>
6564 Perl now builds for the target using
6565 <ulink url='http://arsv.github.io/perl-cross/'><filename>perl-cross</filename></ulink>
6566 for better maintainability and improved build performance.
6567 This change should not present any problems unless you have
6568 heavily customized your Perl recipe.
6569 </para></listitem>
6570 <listitem><para>
6571 <filename>arm-tunes</filename>: Removed the "-march"
6572 option if mcpu is already added.
6573 </para></listitem>
6574 <listitem><para>
6575 <filename>update-alternatives</filename>: Convert file
6576 renames to
6577 <link linkend='var-PACKAGE_PREPROCESS_FUNCS'><filename>PACKAGE_PREPROCESS_FUNCS</filename></link>
6578 </para></listitem>
6579 <listitem><para>
6580 <filename>base/pixbufcache</filename>: Obsolete
6581 <filename>sstatecompletions</filename> code has been
6582 removed.
6583 </para></listitem>
6584 <listitem><para>
6585 <link linkend='ref-classes-native'><filename>native</filename></link>
6586 class:
6587 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
6588 handling has been enabled.
6589 </para></listitem>
6590 <listitem><para>
6591 <filename>inetutils</filename>: This recipe has rsh
6592 disabled.
6593 </para></listitem>
6594 </itemizedlist>
6595 </para>
6596 </section>
6597</section>
6598
6599<section id='moving-to-the-yocto-project-3.0-release'>
6600 <title>Moving to the Yocto Project 3.0 Release</title>
6601
6602 <para>
6603 This section provides migration information for moving to the
6604 Yocto Project 3.0 Release from the prior release.
6605 </para>
6606
6607 <section id='migration-3.0-init-system-selection'>
6608 <title>Init System Selection</title>
6609
6610 <para>
6611 Changing the init system manager previously required setting a
6612 number of different variables.
6613 You can now change the manager by setting the
6614 <filename>INIT_MANAGER</filename> variable and the corresponding
6615 include files
6616 (i.e. <filename>conf/distro/include/init-manager-*.conf</filename>).
6617 Include files are provided for four values: "none", "sysvinit",
6618 "systemd", and "mdev-busybox".
6619 The default value, "none", for <filename>INIT_MANAGER</filename>
6620 should allow your current settings to continue working.
6621 However, it is advisable to explicitly set
6622 <filename>INIT_MANAGER</filename>.
6623 </para>
6624 </section>
6625
6626 <section id='migration-3.0-lsb-support-removed'>
6627 <title>LSB Support Removed</title>
6628
6629 <para>
6630 Linux Standard Base (LSB) as a standard is not current, and
6631 is not well suited for embedded applications.
6632 Support can be continued in a separate layer if needed.
6633 However, presently LSB support has been removed from the core.
6634 </para>
6635
6636 <para>
6637 As a result of this change, the <filename>poky-lsb</filename>
6638 derivative distribution configuration that was also used for
6639 testing alternative configurations has been replaced with a
6640 <filename>poky-altcfg</filename> distribution that has LSB
6641 parts removed.
6642 </para>
6643 </section>
6644
6645 <section id='migration-3.0-removed-recipes'>
6646 <title>Removed Recipes</title>
6647
6648 <para>
6649 The following recipes have been removed.
6650 <itemizedlist>
6651 <listitem><para>
6652 <filename>core-image-lsb-dev</filename>: Part of removed
6653 LSB support.
6654 </para></listitem>
6655 <listitem><para>
6656 <filename>core-image-lsb</filename>: Part of removed
6657 LSB support.
6658 </para></listitem>
6659 <listitem><para>
6660 <filename>core-image-lsb-sdk</filename>: Part of removed
6661 LSB support.
6662 </para></listitem>
6663 <listitem><para>
6664 <filename>cve-check-tool</filename>: Functionally replaced
6665 by the <filename>cve-update-db</filename> recipe and
6666 <filename>cve-check</filename> class.
6667 </para></listitem>
6668 <listitem><para>
6669 <filename>eglinfo</filename>: No longer maintained.
6670 <filename>eglinfo</filename> from
6671 <filename>mesa-demos</filename> is an adequate and
6672 maintained alternative.
6673 </para></listitem>
6674 <listitem><para>
6675 <filename>gcc-8.3</filename>: Version 8.3 removed.
6676 Replaced by 9.2.
6677 </para></listitem>
6678 <listitem><para>
6679 <filename>gnome-themes-standard</filename>: Only needed
6680 by gtk+ 2.x, which has been removed.
6681 </para></listitem>
6682 <listitem><para>
6683 <filename>gtk+</filename>: GTK+ 2 is obsolete and has been
6684 replaced by gtk+3.
6685 </para></listitem>
6686 <listitem><para>
6687 <filename>irda-utils</filename>: Has become obsolete.
6688 IrDA support has been removed from the Linux kernel in
6689 version 4.17 and later.
6690 </para></listitem>
6691 <listitem><para>
6692 <filename>libnewt-python</filename>:
6693 <filename>libnewt</filename> Python support merged into
6694 main <filename>libnewt</filename> recipe.
6695 </para></listitem>
6696 <listitem><para>
6697 <filename>libsdl</filename>: Replaced by newer
6698 <filename>libsdl2</filename>.
6699 </para></listitem>
6700 <listitem><para>
6701 <filename>libx11-diet</filename>: Became obsolete.
6702 </para></listitem>
6703 <listitem><para>
6704 <filename>libxx86dga</filename>: Removed obsolete client
6705 library.
6706 </para></listitem>
6707 <listitem><para>
6708 <filename>libxx86misc</filename>: Removed. Library is
6709 redundant.
6710 </para></listitem>
6711 <listitem><para>
6712 <filename>linux-yocto</filename>: Version 5.0 removed,
6713 which is now redundant (5.2 / 4.19 present).
6714 </para></listitem>
6715 <listitem><para>
6716 <filename>lsbinitscripts</filename>: Part of removed LSB
6717 support.
6718 </para></listitem>
6719 <listitem><para>
6720 <filename>lsb</filename>: Part of removed LSB support.
6721 </para></listitem>
6722 <listitem><para>
6723 <filename>lsbtest</filename>: Part of removed LSB support.
6724 </para></listitem>
6725 <listitem><para>
6726 <filename>openssl10</filename>: Replaced by newer
6727 <filename>openssl</filename> version 1.1.
6728 </para></listitem>
6729 <listitem><para>
6730 <filename>packagegroup-core-lsb</filename>: Part of removed
6731 LSB support.
6732 </para></listitem>
6733 <listitem><para>
6734 <filename>python-nose</filename>: Removed the Python 2.x
6735 version of the recipe.
6736 </para></listitem>
6737 <listitem><para>
6738 <filename>python-numpy</filename>: Removed the Python 2.x
6739 version of the recipe.
6740 </para></listitem>
6741 <listitem><para>
6742 <filename>python-scons</filename>: Removed the Python 2.x
6743 version of the recipe.
6744 </para></listitem>
6745 <listitem><para>
6746 <filename>source-highlight</filename>: No longer needed.
6747 </para></listitem>
6748 <listitem><para>
6749 <filename>stress</filename>: Replaced by
6750 <filename>stress-ng</filename>.
6751 </para></listitem>
6752 <listitem><para>
6753 <filename>vulkan</filename>: Split into
6754 <filename>vulkan-loader</filename>,
6755 <filename>vulkan-headers</filename>, and
6756 <filename>vulkan-tools</filename>.
6757 </para></listitem>
6758 <listitem><para>
6759 <filename>weston-conf</filename>: Functionality moved to
6760 <filename>weston-init</filename>.
6761 </para></listitem>
6762 </itemizedlist>
6763 </para>
6764 </section>
6765
6766 <section id='migration-3.0-packaging-changes'>
6767 <title>Packaging Changes</title>
6768
6769 <para>
6770 The following packaging changes have occurred.
6771 <itemizedlist>
6772 <listitem><para>
6773 The
6774 <ulink url='https://en.wikipedia.org/wiki/GNOME_Web'>Epiphany</ulink>
6775 browser has been dropped from
6776 <filename>packagegroup-self-hosted</filename> as it has
6777 not been needed inside
6778 <filename>build-appliance-image</filename> for
6779 quite some time and was causing resource problems.
6780 </para></listitem>
6781 <listitem><para>
6782 <filename>libcap-ng</filename> Python support has been
6783 moved to a separate <filename>libcap-ng-python</filename>
6784 recipe to streamline the build process when the Python
6785 bindings are not needed.
6786 </para></listitem>
6787 <listitem><para>
6788 <filename>libdrm</filename> now packages the file
6789 <filename>amdgpu.ids</filename> into a separate
6790 <filename>libdrm-amdgpu</filename> package.
6791 </para></listitem>
6792 <listitem><para>
6793 <filename>python3</filename>: The
6794 <filename>runpy</filename> module is now in the
6795 <filename>python3-core</filename> package as it is
6796 required to support the common "python3 -m" command usage.
6797 </para></listitem>
6798 <listitem><para>
6799 <filename>distcc</filename> now provides separate
6800 <filename>distcc-client</filename> and
6801 <filename>distcc-server</filename> packages as typically
6802 one or the other are needed, rather than both.
6803 </para></listitem>
6804 <listitem><para>
6805 <filename>python*-setuptools</filename> recipes now
6806 separately package the <filename>pkg_resources</filename>
6807 module in a <filename>python-pkg-resources</filename> /
6808 <filename>python3-pkg-resources</filename> package as
6809 the module is useful independent of the rest of the
6810 setuptools package.
6811 The main <filename>python-setuptools</filename> /
6812 <filename>python3-setuptools</filename> package depends
6813 on this new package so you should only need to update
6814 dependencies unless you want to take advantage of the
6815 increased granularity.
6816 </para></listitem>
6817 </itemizedlist>
6818 </para>
6819 </section>
6820
6821 <section id='migration-3.0-cve-checking'>
6822 <title>CVE Checking</title>
6823
6824 <para>
6825 <filename>cve-check-tool</filename> has been functionally replaced
6826 by a new <filename>cve-update-db</filename> recipe and
6827 functionality built into the <filename>cve-check</filename> class.
6828 The result uses NVD JSON data feeds rather than the deprecated
6829 XML feeds that <filename>cve-check-tool</filename> was using,
6830 supports CVSSv3 scoring, and makes other improvements.
6831 </para>
6832
6833 <para>
6834 Additionally, the <filename>CVE_CHECK_CVE_WHITELIST</filename>
6835 variable has been replaced by
6836 <filename>CVE_CHECK_WHITELIST</filename>.
6837 </para>
6838 </section>
6839
6840 <section id='migration-3.0-bitbake-changes'>
6841 <title>Bitbake Changes</title>
6842
6843 <para>
6844 The following BitBake changes have occurred.
6845 <itemizedlist>
6846 <listitem><para>
6847 <filename>addtask</filename> statements now properly
6848 validate dependent tasks.
6849 Previously, an invalid task was silently ignored.
6850 With this change, the invalid task generates a warning.
6851 </para></listitem>
6852 <listitem><para>
6853 Other invalid <filename>addtask</filename> and
6854 <filename>deltask</filename> usages now trigger these
6855 warnings: "multiple target tasks arguments with
6856 addtask / deltask", and "multiple before/after clauses".
6857 </para></listitem>
6858 <listitem><para>
6859 The "multiconfig" prefix is now shortened to "mc".
6860 "multiconfig" will continue to work, however it may be
6861 removed in a future release.
6862 </para></listitem>
6863 <listitem><para>
6864 The <filename>bitbake -g</filename> command no longer
6865 generates a <filename>recipe-depends.dot</filename> file
6866 as the contents (i.e. a reprocessed version of
6867 <filename>task-depends.dot</filename>) were confusing.
6868 </para></listitem>
6869 <listitem><para>
6870 The <filename>bb.build.FuncFailed</filename> exception,
6871 previously raised by
6872 <filename>bb.build.exec_func()</filename> when certain
6873 other exceptions have occurred, has been removed.
6874 The real underlying exceptions will be raised instead.
6875 If you have calls to
6876 <filename>bb.build.exec_func()</filename> in custom classes
6877 or <filename>tinfoil-using</filename> scripts, any
6878 references to <filename>bb.build.FuncFailed</filename>
6879 should be cleaned up.
6880 </para></listitem>
6881 <listitem><para>
6882 Additionally, the
6883 <filename>bb.build.exec_func()</filename> no longer accepts
6884 the "pythonexception" parameter.
6885 The function now always raises exceptions.
6886 Remove this argument in any calls to
6887 <filename>bb.build.exec_func()</filename> in custom classes
6888 or scripts.
6889 </para></listitem>
6890 <listitem><para>
6891 The
6892 <ulink url='&YOCTO_DOCS_BB_URL;#var-bb-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></ulink>
6893 is no longer used.
6894 In the unlikely event that you have any references to it,
6895 they should be removed.
6896 </para></listitem>
6897 <listitem><para>
6898 The <filename>RunQueueExecuteScenequeue</filename> and
6899 <filename>RunQueueExecuteTasks</filename> events have been
6900 removed since setscene tasks are now executed as part of
6901 the normal runqueue.
6902 Any event handling code in custom classes or scripts that
6903 handles these two events need to be updated.
6904 </para></listitem>
6905 <listitem><para>
6906 The arguments passed to functions used with
6907 <ulink url='&YOCTO_DOCS_BB_URL;#var-bb-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink>
6908 have changed.
6909 If you are using your own custom hash check function, see
6910 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725'></ulink>
6911 for details.
6912 </para></listitem>
6913 <listitem><para>
6914 Task specifications in <filename>BB_TASKDEPDATA</filename>
6915 and class implementations used in signature generator
6916 classes now use "&lt;fn&gt;:&lt;task&gt;" everywhere rather than
6917 the "." delimiter that was being used in some places.
6918 This change makes it consistent with all areas in the code.
6919 Custom signature generator classes and code that reads
6920 <filename>BB_TASKDEPDATA</filename> need to be updated to
6921 use ':' as a separator rather than '.'.
6922 </para></listitem>
6923 </itemizedlist>
6924 </para>
6925 </section>
6926
6927 <section id='migration-3.0-sanity-checks'>
6928 <title>Sanity Checks</title>
6929
6930 <para>
6931 The following sanity check changes occurred.
6932 <itemizedlist>
6933 <listitem><para>
6934 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
6935 is now checked for usage of two problematic items:
6936 <itemizedlist>
6937 <listitem><para>
6938 "${PN}" prefix/suffix use - Warnings always appear
6939 if ${PN} is used.
6940 You must fix the issue regardless of whether
6941 multiconfig or anything else that would cause
6942 prefixing/suffixing to happen.
6943 </para></listitem>
6944 <listitem><para>
6945 Github archive tarballs - these are not guaranteed
6946 to be stable.
6947 Consequently, it is likely that the tarballs will
6948 be refreshed and thus the SRC_URI checksums
6949 will fail to apply.
6950 It is recommended that you fetch either an official
6951 release tarball or a specific revision from the
6952 actual Git repository instead.
6953 </para></listitem>
6954 </itemizedlist>
6955 Either one of these items now trigger a warning by default.
6956 If you wish to disable this check, remove
6957 <filename>src-uri-bad</filename> from
6958 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link>.
6959 </para></listitem>
6960 <listitem><para>
6961 The <filename>file-rdeps</filename> runtime dependency
6962 check no longer expands
6963 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
6964 recursively as there is no mechanism to ensure they can be
6965 fully computed, and thus races sometimes result in errors
6966 either showing up or not.
6967 Thus, you might now see errors for missing runtime
6968 dependencies that were previously satisfied recursively.
6969 Here is an example: package A contains a shell script
6970 starting with <filename>#!/bin/bash</filename> but has no
6971 dependency on bash.
6972 However, package A depends on package B, which does depend
6973 on bash.
6974 You need to add the missing dependency or dependencies to
6975 resolve the warning.
6976 </para></listitem>
6977 <listitem><para>
6978 Setting <filename>DEPENDS_${PN}</filename> anywhere
6979 (i.e. typically in a recipe) now triggers an error.
6980 The error is triggered because
6981 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
6982 is not a package-specific variable unlike RDEPENDS.
6983 You should set <filename>DEPENDS</filename> instead.
6984 </para></listitem>
6985 <listitem><para>
6986 systemd currently does not work well with the musl C
6987 library because only upstream officially supports linking
6988 the library with glibc.
6989 Thus, a warning is shown when building systemd in
6990 conjunction with musl.
6991 </para></listitem>
6992 </itemizedlist>
6993 </para>
6994 </section>
6995
6996 <section id='migration-3.0-miscellaneous-changes'>
6997 <title>Miscellaneous Changes</title>
6998
6999 <para>
7000 The following miscellaneous changes have occurred.
7001 <itemizedlist>
7002 <listitem><para>
7003 The <filename>gnome</filename>
7004 class has been removed because it now does very little.
7005 You should update recipes that previously inherited this
7006 class to do the following:
7007 <literallayout class='monospaced'>
7008 inherit gnomebase gtk-icon-cache gconf mime
7009 </literallayout>
7010 </para></listitem>
7011 <listitem><para>
7012 The
7013 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>
7014 file has been removed.
7015 This file was previously deprecated in favor of setting
7016 <link linkend='var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></link>
7017 in any kernel recipe and only produced a warning.
7018 Remove any <filename>include</filename> or
7019 <filename>require</filename> statements pointing to this
7020 file.
7021 </para></listitem>
7022 <listitem><para>
7023 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>,
7024 <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link>,
7025 <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link>,
7026 and
7027 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
7028 are no longer exported to the external environment.
7029 This change did not require any changes to core recipes,
7030 which is a good indicator that no changes will be
7031 required.
7032 However, if for some reason the software being built by one
7033 of your recipes is expecting these variables to be set,
7034 then building the recipe will fail.
7035 In such cases, you must either export the variable or
7036 variables in the recipe or change the scripts so that
7037 exporting is not necessary.
7038 </para></listitem>
7039 <listitem><para>
7040 You must change the host distro identifier used in
7041 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
7042 to use all lowercase characters even if it does not contain
7043 a version number.
7044 This change is necessary only if you are not using
7045 <filename>uninative</filename> and
7046 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>.
7047 </para></listitem>
7048 <listitem><para>
7049 In the <filename>base-files</filename> recipe, writing the
7050 hostname into <filename>/etc/hosts</filename> and
7051 <filename>/etc/hostname</filename> is now done within the
7052 main
7053 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
7054 function rather than in the
7055 <filename>do_install_basefilesissue</filename> function.
7056 The reason for the change is because
7057 <filename>do_install_basefilesissue</filename> is more
7058 easily overridden without having to duplicate the hostname
7059 functionality.
7060 If you have done the latter (e.g. in a
7061 <filename>base-files</filename> bbappend), then you should
7062 remove it from your customized
7063 <filename>do_install_basefilesissue</filename> function.
7064 </para></listitem>
7065 <listitem><para>
7066 The <filename>wic --expand</filename> command now uses
7067 commas to separate "key:value" pairs rather than hyphens.
7068 <note>
7069 The wic command-line help is not updated.
7070 </note>
7071 You must update any scripts or commands where you use
7072 <filename>wic --expand</filename> with multiple
7073 "key:value" pairs.
7074 </para></listitem>
7075 <listitem><para>
7076 UEFI image variable settings have been moved from various
7077 places to a central
7078 <filename>conf/image-uefi.conf</filename>.
7079 This change should not influence any existing configuration
7080 as the <filename>meta/conf/image-uefi.conf</filename>
7081 in the core metadata sets defaults that can be overridden
7082 in the same manner as before.
7083 </para></listitem>
7084 <listitem><para>
7085 <filename>conf/distro/include/world-broken.inc</filename>
7086 has been removed.
7087 For cases where certain recipes need to be disabled when
7088 using the musl C library, these recipes now have
7089 <filename>COMPATIBLE_HOST_libc-musl</filename> set with a
7090 comment that explains why.
7091 </para></listitem>
7092 </itemizedlist>
7093 </para>
7094 </section>
7095</section>
7096
7097
7098<section id='moving-to-the-yocto-project-3.1-release'>
7099 <title>Moving to the Yocto Project 3.1 Release</title>
7100
7101 <para>
7102 This section provides migration information for moving to the
7103 Yocto Project 3.1 Release from the prior release.
7104 </para>
7105
7106 <section id='migration-3.1-minimum-system-requirements'>
7107 <title>Minimum system requirements</title>
7108
7109 <para>
7110 The following versions / requirements of build host components have been updated:
7111 <itemizedlist>
7112 <listitem><para>gcc 5.0</para></listitem>
7113 <listitem><para>python 3.5</para></listitem>
7114 <listitem><para>tar 1.28</para></listitem>
7115 <listitem><para><filename>rpcgen</filename> is now required on the host (part of the <filename>libc-dev-bin</filename> package on Ubuntu, Debian and related distributions, and the <filename>glibc</filename> package on RPM-based distributions).</para></listitem>
7116 </itemizedlist>
7117
7118 Additionally, the <filename>makeinfo</filename> and <filename>pod2man</filename>
7119 tools are <emphasis>no longer</emphasis> required on the host.
7120 </para>
7121 </section>
7122
7123 <section id='migration-3.1-mpc8315e-rdb-removed'>
7124 <title>mpc8315e-rdb machine removed</title>
7125
7126 <para>
7127 The MPC8315E-RDB machine is old/obsolete and unobtainable, thus given the maintenance burden
7128 the <filename>mpc8315e-rdb</filename> machine configuration that supported it has been removed
7129 in this release. The removal does leave a gap in official PowerPC reference hardware
7130 support; this may change in future if a suitable machine with accompanying support resources
7131 is found.
7132 </para>
7133 </section>
7134
7135 <section id='migration-3.1-python-2-removed'>
7136 <title>Python 2 removed</title>
7137
7138 <para>
7139 Due to the expiration of upstream support in January 2020, support for Python 2 has now been removed; it is recommended that you use Python 3 instead. If absolutely needed there is a meta-python2 community layer containing Python 2, related classes and various Python 2-based modules, however it should not be considered as supported.
7140 </para>
7141 </section>
7142
7143 <section id='migration-3.1-reproducible-builds'>
7144 <title>Reproducible builds now enabled by default</title>
7145
7146 <para>
7147 In order to avoid unnecessary differences in output files (aiding binary reproducibility), the Poky distribution configuration (<filename><link linkend='var-DISTRO'>DISTRO</link> = "poky"</filename>) now inherits the <filename>reproducible_build</filename> class by default.
7148 </para>
7149 </section>
7150
7151 <section id='migration-3.1-ptest-feature-impact'>
7152 <title>Impact of ptest feature is now more significant</title>
7153
7154 <para>
7155 The Poky distribution configuration (<filename><link linkend='var-DISTRO'>DISTRO</link> = "poky"</filename>) enables ptests by default to enable runtime testing of various components. In this release, a dependency needed to be added that has resulted in a significant increase in the number of components that will be built just when building a simple image such as core-image-minimal. If you do not need runtime tests enabled for core components, then it is recommended that you remove "ptest" from <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> to save a significant amount of build time e.g. by adding the following in your configuration:
7156
7157 <literallayout class='monospaced'>
7158 DISTRO_FEATURES_remove = "ptest"
7159 </literallayout>
7160 </para>
7161 </section>
7162
7163 <section id='migration-3.1-removed-recipes'>
7164 <title>Removed recipes</title>
7165
7166 <para>
7167 The following recipes have been removed:
7168
7169 <itemizedlist>
7170 <listitem><para><filename>chkconfig</filename>: obsolete</para></listitem>
7171 <listitem><para><filename>console-tools</filename>: obsolete</para></listitem>
7172 <listitem><para><filename>enchant</filename>: replaced by <filename>enchant2</filename></para></listitem>
7173 <listitem><para><filename>foomatic-filters</filename>: obsolete</para></listitem>
7174 <listitem><para><filename>libidn</filename>: no longer needed, moved to meta-oe</para></listitem>
7175 <listitem><para><filename>libmodulemd</filename>: replaced by <filename>libmodulemd-v1</filename></para></listitem>
7176 <listitem><para><filename>linux-yocto</filename>: drop 4.19, 5.2 version recipes (5.4 now provided)</para></listitem>
7177 <listitem><para><filename>nspr</filename>: no longer needed, moved to meta-oe</para></listitem>
7178 <listitem><para><filename>nss</filename>: no longer needed, moved to meta-oe</para></listitem>
7179 <listitem><para><filename>python</filename>: Python 2 removed (Python 3 preferred)</para></listitem>
7180 <listitem><para><filename>python-setuptools</filename>: Python 2 version removed (python3-setuptools preferred)</para></listitem>
7181 <listitem><para><filename>sysprof</filename>: no longer needed, moved to meta-oe</para></listitem>
7182 <listitem><para><filename>texi2html</filename>: obsolete</para></listitem>
7183 <listitem><para><filename>u-boot-fw-utils</filename>: functionally replaced by <filename>libubootenv</filename></para></listitem>
7184 </itemizedlist>
7185 </para>
7186 </section>
7187
7188 <section id='migration-3.1-features-check'>
7189 <title>features_check class replaces distro_features_check</title>
7190
7191 <para>
7192 The <filename>distro_features_check</filename> class has had its functionality expanded, now supporting <filename>ANY_OF_MACHINE_FEATURES</filename>, <filename>REQUIRED_MACHINE_FEATURES</filename>, <filename>CONFLICT_MACHINE_FEATURES</filename>, <filename>ANY_OF_COMBINED_FEATURES</filename>, <filename>REQUIRED_COMBINED_FEATURES</filename>, <filename>CONFLICT_COMBINED_FEATURES</filename>. As a result the class has now been renamed to <filename>features_check</filename>; the <filename>distro_features_check</filename> class still exists but generates a warning and redirects to the new class. In preparation for a future removal of the old class it is recommended that you update recipes currently inheriting <filename>distro_features_check</filename> to inherit <filename>features_check</filename> instead.
7193 </para>
7194 </section>
7195
7196 <section id='migration-3.1-removed-classes'>
7197 <title>Removed classes</title>
7198
7199 <para>
7200 The following classes have been removed:
7201
7202 <itemizedlist>
7203 <listitem><para><filename>distutils-base</filename>: moved to meta-python2</para></listitem>
7204 <listitem><para><filename>distutils</filename>: moved to meta-python2</para></listitem>
7205 <listitem><para><filename>libc-common</filename>: merged into the glibc recipe as nothing else used it.</para></listitem>
7206 <listitem><para><filename>python-dir</filename>: moved to meta-python2</para></listitem>
7207 <listitem><para><filename>pythonnative</filename>: moved to meta-python2</para></listitem>
7208 <listitem><para><filename>setuptools</filename>: moved to meta-python2</para></listitem>
7209 <listitem><para><filename>tinderclient</filename>: dropped as it was obsolete.</para></listitem>
7210 </itemizedlist>
7211 </para>
7212 </section>
7213
7214 <section id='migration-3.1-src-uri-checksums'>
7215 <title>SRC_URI checksum behaviour</title>
7216
7217 <para>
7218 Previously, recipes by tradition included both SHA256 and MD5 checksums for remotely fetched files in <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>, even though only one is actually mandated. However, the MD5 checksum does not add much given its inherent weakness; thus when a checksum fails only the SHA256 sum will now be printed. The md5sum will still be verified if it is specified.
7219 </para>
7220 </section>
7221
7222
7223 <section id='migration-3.1-npm'>
7224 <title>npm fetcher changes</title>
7225
7226 <para>
7227 The npm fetcher has been completely reworked in this release. The npm fetcher now only fetches the package source itself and no longer the dependencies; there is now also an npmsw fetcher which explicitly fetches the shrinkwrap file and the dependencies. This removes the slightly awkward <filename>NPM_LOCKDOWN</filename> and <filename>NPM_SHRINKWRAP</filename> variables which pointed to local files; the lockdown file is no longer needed at all. Additionally, the package name in <filename>npm://</filename> entries in <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> is now specified using a <filename>package</filename> parameter instead of the earlier <filename>name</filename> which overlapped with the generic <filename>name</filename> parameter. All recipes using the npm fetcher will need to be changed as a result.
7228 </para>
7229 <para>
7230 An example of the new scheme:
7231 <literallayout class='monospaced'>
7232SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \
7233 npmsw://${THISDIR}/npm-shrinkwrap.json"
7234 </literallayout>
7235 Another example where the sources are fetched from git rather than an npm repository:
7236 <literallayout class='monospaced'>
7237SRC_URI = "git://github.com/foo/bar.git;protocol=https \
7238 npmsw://${THISDIR}/npm-shrinkwrap.json"
7239 </literallayout>
7240 </para>
7241 <para>
7242 devtool and recipetool have also been updated to match with the npm fetcher changes. Other than producing working and more complete recipes for npm sources, there is also a minor change to the command line for devtool: the <filename>--fetch-dev</filename> option has been renamed to <filename>--npm-dev</filename> as it is npm-specific.
7243 </para>
7244 </section>
7245
7246
7247 <section id='migration-3.1-packaging-changes'>
7248 <title>Packaging changes</title>
7249
7250 <para>
7251 <itemizedlist>
7252 <listitem><para><filename>intltool</filename> has been removed from <filename>packagegroup-core-sdk</filename> as it is rarely needed to build modern software - gettext can do most of the things it used to be needed for. <filename>intltool</filename> has also been removed from <filename>packagegroup-core-self-hosted</filename> as it is not needed to for standard builds.</para></listitem>
7253 <listitem><para>git: <filename>git-am</filename>, <filename>git-difftool</filename>, <filename>git-submodule</filename>, and <filename>git-request-pull</filename> are no longer perl-based, so are now installed with the main <filename>git</filename> package instead of within <filename>git-perltools</filename>.</para></listitem>
7254 <listitem><para>The <filename>ldconfig</filename> binary built as part of glibc has now been moved to its own <filename>ldconfig</filename> package (note no <filename>glibc-</filename> prefix). This package is in the <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> of the main <filename>glibc</filename> package if <filename>ldconfig</filename> is present in <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.</para></listitem>
7255 <listitem><para><filename>libevent</filename> now splits each shared library into its own package (as Debian does). Since these are shared libraries and will be pulled in through the normal shared library dependency handling, there should be no impact to existing configurations other than less unnecessary libraries being installed in some cases.</para></listitem>
7256 <listitem><para>linux-firmware now has a new package for <filename>bcm4366c</filename> and includes available NVRAM config files into the <filename>bcm43340</filename>, <filename>bcm43362</filename>, <filename>bcm43430</filename> and <filename>bcm4356-pcie</filename> packages.</para></listitem>
7257 <listitem><para><filename>harfbuzz</filename> now splits the new <filename>libharfbuzz-subset.so</filename> library into its own package to reduce the main package size in cases where <filename>libharfbuzz-subset.so</filename> is not needed.</para></listitem>
7258 </itemizedlist>
7259 </para>
7260 </section>
7261
7262 <section id='migration-3.1-package-qa-warnings'>
7263 <title>Additional warnings</title>
7264
7265 <para>
7266 Warnings will now be shown at <filename>do_package_qa</filename> time in the following circumstances:
7267
7268 <itemizedlist>
7269 <listitem><para>A recipe installs <filename>.desktop</filename> files containing <filename>MimeType</filename> keys but does not inherit the new <filename>mime-xdg</filename> class</para></listitem>
7270 <listitem><para>A recipe installs <filename>.xml</filename> files into <filename>${datadir}/mime/packages</filename> but does not inherit the <filename>mime</filename> class</para></listitem>
7271 </itemizedlist>
7272 </para>
7273 </section>
7274
7275 <section id='migration-3.1-x86-live-wic'>
7276 <title><filename>wic</filename> image type now used instead of <filename>live</filename> by default for x86</title>
7277
7278 <para>
7279 <filename>conf/machine/include/x86-base.inc</filename> (inherited by most x86 machine configurations) now specifies <filename>wic</filename> instead of <filename>live</filename> by default in <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>. The <filename>live</filename> image type will likely be removed in a future release so it is recommended that you use <filename>wic</filename> instead.
7280 </para>
7281 </section>
7282
7283 <section id='migration-3.1-misc'>
7284 <title>Miscellaneous changes</title>
7285
7286 <para>
7287 <itemizedlist>
7288 <listitem><para>The undocumented <filename>SRC_DISTRIBUTE_LICENSES</filename> variable has now been removed in favour of a new <filename>AVAILABLE_LICENSES</filename> variable which is dynamically set based upon license files found in <filename>${COMMON_LICENSE_DIR}</filename> and <filename>${LICENSE_PATH}</filename>.</para></listitem>
7289 <listitem><para>The tune definition for big-endian microblaze machines is now <filename>microblaze</filename> instead of <filename>microblazeeb</filename>.</para></listitem>
7290 <listitem><para><filename>newlib</filename> no longer has built-in syscalls. <filename>libgloss</filename> should then provide the syscalls, <filename>crt0.o</filename> and other functions that are no longer part of <filename>newlib</filename> itself. If you are using <filename>TCLIBC = "newlib"</filename> this now means that you must link applications with both <filename>newlib</filename> and <filename>libgloss</filename>, whereas before <filename>newlib</filename> would run in many configurations by itself.</para></listitem>
7291 </itemizedlist>
7292 </para>
7293 </section>
7294
7295</section>
7296
7297
7298</chapter>
7299<!--
7300vim: expandtab tw=80 ts=4
7301-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 09:24:14 +0000