summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/migration.xml
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 14:30:32 (GMT)
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 12:56:17 (GMT)
commit43d07a285181e64c30d98d10ff93ef50391efe59 (patch)
tree78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/ref-manual/migration.xml
parent1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff)
downloadpoky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
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 d3d5b16..0000000
--- 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: