blob: 2bdb542ec1a779eedaae69c81c98144af6a96ed1 [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='migration'>
6<title>Migrating to a Newer Yocto Project Release</title>
7
8 <para>
9 This chapter provides information you can use to migrate work to a
10 newer Yocto Project release. You can find the same information in the
11 release notes for a given release.
12 </para>
13
14<section id='general-migration-considerations'>
15 <title>General Migration Considerations</title>
16
17 <para>
18 Some considerations are not tied to a specific Yocto Project
19 release.
20 This section presents information you should consider when
21 migrating to any new Yocto Project release.
22 <itemizedlist>
23 <listitem><para><emphasis>Dealing with Customized Recipes</emphasis>:
24 Issues could arise if you take older recipes that contain
25 customizations and simply copy them forward expecting them
26 to work after you migrate to new Yocto Project metadata.
27 For example, suppose you have a recipe in your layer that is
28 a customized version of a core recipe copied from the earlier
29 release, rather than through the use of an append file.
30 When you migrate to a newer version of Yocto Project, the
31 metadata (e.g. perhaps an include file used by the recipe)
32 could have changed in a way that would break the build.
33 Say, for example, a function is removed from an include file
34 and the customized recipe tries to call that function.
35 </para>
36
37 <para>You could "forward-port" all your customizations in your
38 recipe so that everything works for the new release.
39 However, this is not the optimal solution as you would have
40 to repeat this process with each new release if changes
41 occur that give rise to problems.</para>
42
43 <para>The better solution (where practical) is to use append
44 files (<filename>*.bbappend</filename>) to capture any
45 customizations you want to make to a recipe.
46 Doing so, isolates your changes from the main recipe making
47 them much more manageable.
48 However, sometimes it is not practical to use an append
49 file.
50 A good example of this is when introducing a newer or older
51 version of a recipe in another layer.</para>
52 </listitem>
53 <listitem><para><emphasis>Updating Append Files</emphasis>:
54 Since append files generally only contain your customizations,
55 they often do not need to be adjusted for new releases.
56 However, if the <filename>.bbappend</filename> file is
57 specific to a particular version of the recipe (i.e. its
58 name does not use the % wildcard) and the version of the
59 recipe to which it is appending has changed, then you will
60 at a minimum need to rename the append file to match the
61 name of the recipe file.
62 A mismatch between an append file and its corresponding
63 recipe file (<filename>.bb</filename>) will
64 trigger an error during parsing.</para>
65 <para>Depending on the type of customization the append file
66 applies, other incompatibilities might occur when you
67 upgrade.
68 For example, if your append file applies a patch and the
69 recipe to which it is appending is updated to a newer
70 version, the patch might no longer apply.
71 If this is the case and assuming the patch is still needed,
72 you must modify the patch file so that it does apply.
73 </para></listitem>
74 </itemizedlist>
75 </para>
76</section>
77
78<section id='moving-to-the-yocto-project-1.3-release'>
79 <title>Moving to the Yocto Project 1.3 Release</title>
80
81 <para>
82 This section provides migration information for moving to the
83 Yocto Project 1.3 Release from the prior release.
84 </para>
85
86 <section id='1.3-local-configuration'>
87 <title>Local Configuration</title>
88
89 <para>
90 Differences include changes for
91 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
92 and <filename>bblayers.conf</filename>.
93 </para>
94
95 <section id='migration-1.3-sstate-mirrors'>
96 <title>SSTATE_MIRRORS</title>
97
98 <para>
99 The shared state cache (sstate-cache), as pointed to by
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500100 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
101 by default now has two-character subdirectories to prevent
102 issues arising from too many files in the same directory.
103 Also, native sstate-cache packages, which are built to run
104 on the host system, will go into a subdirectory named using
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500105 the distro ID string.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500106 If you copy the newly structured sstate-cache to a mirror
107 location (either local or remote) and then point to it in
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500108 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
109 you need to append "PATH" to the end of the mirror URL so that
110 the path used by BitBake before the mirror substitution is
111 appended to the path used to access the mirror.
112 Here is an example:
113 <literallayout class='monospaced'>
114 SSTATE_MIRRORS = "file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH"
115 </literallayout>
116 </para>
117 </section>
118
119 <section id='migration-1.3-bblayers-conf'>
120 <title>bblayers.conf</title>
121
122 <para>
123 The <filename>meta-yocto</filename> layer consists of two parts
124 that correspond to the Poky reference distribution and the
125 reference hardware Board Support Packages (BSPs), respectively:
126 <filename>meta-yocto</filename> and
127 <filename>meta-yocto-bsp</filename>.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500128 When running BitBake for the first time after upgrading,
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500129 your <filename>conf/bblayers.conf</filename> file will be
130 updated to handle this change and you will be asked to
131 re-run or restart for the changes to take effect.
132 </para>
133 </section>
134 </section>
135
136 <section id='1.3-recipes'>
137 <title>Recipes</title>
138
139 <para>
140 Differences include changes for the following:
141 <itemizedlist>
142 <listitem><para>Python function whitespace</para></listitem>
143 <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem>
144 <listitem><para><filename>nativesdk</filename></para></listitem>
145 <listitem><para>Task recipes</para></listitem>
146 <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem>
147 <listitem><para>Removed recipes</para></listitem>
148 </itemizedlist>
149 </para>
150
151 <section id='migration-1.3-python-function-whitespace'>
152 <title>Python Function Whitespace</title>
153
154 <para>
155 All Python functions must now use four spaces for indentation.
156 Previously, an inconsistent mix of spaces and tabs existed,
157 which made extending these functions using
158 <filename>_append</filename> or <filename>_prepend</filename>
159 complicated given that Python treats whitespace as
160 syntactically significant.
161 If you are defining or extending any Python functions (e.g.
162 <filename>populate_packages</filename>, <filename>do_unpack</filename>,
163 <filename>do_patch</filename> and so forth) in custom recipes
164 or classes, you need to ensure you are using consistent
165 four-space indentation.
166 </para>
167 </section>
168
169 <section id='migration-1.3-proto=-in-src-uri'>
170 <title>proto= in SRC_URI</title>
171
172 <para>
173 Any use of <filename>proto=</filename> in
174 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
175 needs to be changed to <filename>protocol=</filename>.
176 In particular, this applies to the following URIs:
177 <itemizedlist>
178 <listitem><para><filename>svn://</filename></para></listitem>
179 <listitem><para><filename>bzr://</filename></para></listitem>
180 <listitem><para><filename>hg://</filename></para></listitem>
181 <listitem><para><filename>osc://</filename></para></listitem>
182 </itemizedlist>
183 Other URIs were already using <filename>protocol=</filename>.
184 This change improves consistency.
185 </para>
186 </section>
187
188 <section id='migration-1.3-nativesdk'>
189 <title>nativesdk</title>
190
191 <para>
192 The suffix <filename>nativesdk</filename> is now implemented
193 as a prefix, which simplifies a lot of the packaging code for
194 <filename>nativesdk</filename> recipes.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500195 All custom <filename>nativesdk</filename> recipes, which are
196 relocatable packages that are native to
197 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
198 and any references need to be updated to use
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500199 <filename>nativesdk-*</filename> instead of
200 <filename>*-nativesdk</filename>.
201 </para>
202 </section>
203
204 <section id='migration-1.3-task-recipes'>
205 <title>Task Recipes</title>
206
207 <para>
208 "Task" recipes are now known as "Package groups" and have
209 been renamed from <filename>task-*.bb</filename> to
210 <filename>packagegroup-*.bb</filename>.
211 Existing references to the previous <filename>task-*</filename>
212 names should work in most cases as there is an automatic
213 upgrade path for most packages.
214 However, you should update references in your own recipes and
215 configurations as they could be removed in future releases.
216 You should also rename any custom <filename>task-*</filename>
217 recipes to <filename>packagegroup-*</filename>, and change
218 them to inherit <filename>packagegroup</filename> instead of
219 <filename>task</filename>, as well as taking the opportunity
220 to remove anything now handled by
221 <filename>packagegroup.bbclass</filename>, such as providing
222 <filename>-dev</filename> and <filename>-dbg</filename>
223 packages, setting
224 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
225 and so forth.
226 See the
227 "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>"
228 section for further details.
229 </para>
230 </section>
231
232 <section id='migration-1.3-image-features'>
233 <title>IMAGE_FEATURES</title>
234
235 <para>
236 Image recipes that previously included "apps-console-core"
237 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
238 should now include "splash" instead to enable the boot-up
239 splash screen.
240 Retaining "apps-console-core" will still include the splash
241 screen but generates a warning.
242 The "apps-x11-core" and "apps-x11-games"
243 <filename>IMAGE_FEATURES</filename> features have been removed.
244 </para>
245 </section>
246
247 <section id='migration-1.3-removed-recipes'>
248 <title>Removed Recipes</title>
249
250 <para>
251 The following recipes have been removed.
252 For most of them, it is unlikely that you would have any
253 references to them in your own
254 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>.
255 However, you should check your metadata against this list to be sure:
256 <itemizedlist>
257 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
258 Replaced by <filename>libx11</filename>, which has a negligible
259 size difference with modern Xorg.</para></listitem>
260 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
261 Use <filename>xserver-xorg</filename>, which has a negligible
262 size difference when DRI and GLX modules are not installed.</para></listitem>
263 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
264 Effectively unmaintained for many years.</para></listitem>
265 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
266 No longer serves any purpose.</para></listitem>
267 <listitem><para><emphasis><filename>galago</filename></emphasis>:
268 Replaced by telepathy.</para></listitem>
269 <listitem><para><emphasis><filename>gail</filename></emphasis>:
270 Functionality was integrated into GTK+ 2.13.</para></listitem>
271 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
272 No longer needed.</para></listitem>
273 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
274 The build has been restructured to avoid the need for
275 this step.</para></listitem>
276 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
277 Unmaintained for many years.
278 Functionality now provided by
279 <filename>ofono</filename> instead.</para></listitem>
280 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
281 Largely unmaintained PIM application suite.
282 It has been moved to <filename>meta-gnome</filename>
283 in <filename>meta-openembedded</filename>.</para></listitem>
284 </itemizedlist>
285 In addition to the previously listed changes, the
286 <filename>meta-demoapps</filename> directory has also been removed
287 because the recipes in it were not being maintained and many
288 had become obsolete or broken.
289 Additionally, these recipes were not parsed in the default configuration.
290 Many of these recipes are already provided in an updated and
291 maintained form within the OpenEmbedded community layers such as
292 <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
293 For the remainder, you can now find them in the
294 <filename>meta-extras</filename> repository, which is in the
295 Yocto Project
296 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>.
297 </para>
298 </section>
299 </section>
300
301 <section id='1.3-linux-kernel-naming'>
302 <title>Linux Kernel Naming</title>
303
304 <para>
305 The naming scheme for kernel output binaries has been changed to
306 now include
307 <link linkend='var-PE'><filename>PE</filename></link> as part of the
308 filename:
309 <literallayout class='monospaced'>
310 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
311 </literallayout>
312 </para>
313
314 <para>
315 Because the <filename>PE</filename> variable is not set by default,
316 these binary files could result with names that include two dash
317 characters.
318 Here is an example:
319 <literallayout class='monospaced'>
320 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
321 </literallayout>
322 </para>
323 </section>
324</section>
325
326<section id='moving-to-the-yocto-project-1.4-release'>
327 <title>Moving to the Yocto Project 1.4 Release</title>
328
329 <para>
330 This section provides migration information for moving to the
331 Yocto Project 1.4 Release from the prior release.
332 </para>
333
334 <section id='migration-1.4-bitbake'>
335 <title>BitBake</title>
336
337 <para>
338 Differences include the following:
339 <itemizedlist>
340 <listitem><para><emphasis>Comment Continuation:</emphasis>
341 If a comment ends with a line continuation (\) character,
342 then the next line must also be a comment.
343 Any instance where this is not the case, now triggers
344 a warning.
345 You must either remove the continuation character, or be
346 sure the next line is a comment.
347 </para></listitem>
348 <listitem><para><emphasis>Package Name Overrides:</emphasis>
349 The runtime package specific variables
350 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
351 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
352 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
353 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
354 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
355 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
356 <link linkend='var-FILES'><filename>FILES</filename></link>,
357 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
358 and the pre, post, install, and uninstall script functions
359 <filename>pkg_preinst</filename>,
360 <filename>pkg_postinst</filename>,
361 <filename>pkg_prerm</filename>, and
362 <filename>pkg_postrm</filename> should always have a
363 package name override.
364 For example, use <filename>RDEPENDS_${PN}</filename> for
365 the main package instead of <filename>RDEPENDS</filename>.
366 BitBake uses more strict checks when it parses recipes.
367 </para></listitem>
368 </itemizedlist>
369 </para>
370 </section>
371
372 <section id='migration-1.4-build-behavior'>
373 <title>Build Behavior</title>
374
375 <para>
376 Differences include the following:
377 <itemizedlist>
378 <listitem><para><emphasis>Shared State Code:</emphasis>
379 The shared state code has been optimized to avoid running
380 unnecessary tasks.
381 For example, the following no longer populates the target
382 sysroot since that is not necessary:
383 <literallayout class='monospaced'>
384 $ bitbake -c rootfs <replaceable>some-image</replaceable>
385 </literallayout>
386 Instead, the system just needs to extract the output
387 package contents, re-create the packages, and construct
388 the root filesystem.
389 This change is unlikely to cause any problems unless
390 you have missing declared dependencies.
391 </para></listitem>
392 <listitem><para><emphasis>Scanning Directory Names:</emphasis>
393 When scanning for files in
394 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
395 the build system now uses
396 <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
397 instead of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
398 for the directory names.
399 In general, the values previously in
400 <filename>OVERRIDES</filename> are now in
401 <filename>FILESOVERRIDES</filename> as well.
402 However, if you relied upon an additional value
403 you previously added to <filename>OVERRIDES</filename>,
404 you might now need to add it to
405 <filename>FILESOVERRIDES</filename> unless you are already
406 adding it through the
407 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>
408 or <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
409 variables, as appropriate.
410 For more related changes, see the
411 "<link linkend='migration-1.4-variables'>Variables</link>"
412 section.
413 </para></listitem>
414 </itemizedlist>
415 </para>
416 </section>
417
418
419 <section id='migration-1.4-proxies-and-fetching-source'>
420 <title>Proxies and Fetching Source</title>
421
422 <para>
423 A new <filename>oe-git-proxy</filename> script has been added to
424 replace previous methods of handling proxies and fetching source
425 from Git.
426 See the <filename>meta-yocto/conf/site.conf.sample</filename> file
427 for information on how to use this script.
428 </para>
429 </section>
430
431 <section id='migration-1.4-custom-interfaces-file-netbase-change'>
432 <title>Custom Interfaces File (netbase change)</title>
433
434 <para>
435 If you have created your own custom
436 <filename>etc/network/interfaces</filename> file by creating
437 an append file for the <filename>netbase</filename> recipe,
438 you now need to create an append file for the
439 <filename>init-ifupdown</filename> recipe instead, which you can
440 find in the
441 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
442 at <filename>meta/recipes-core/init-ifupdown</filename>.
443 For information on how to use append files, see the
444 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
445 in the Yocto Project Development Manual.
446 </para>
447 </section>
448
449 <section id='migration-1.4-remote-debugging'>
450 <title>Remote Debugging</title>
451
452 <para>
453 Support for remote debugging with the Eclipse IDE is now
454 separated into an image feature
455 (<filename>eclipse-debug</filename>) that corresponds to the
456 <filename>packagegroup-core-eclipse-debug</filename> package group.
457 Previously, the debugging feature was included through the
458 <filename>tools-debug</filename> image feature, which corresponds
459 to the <filename>packagegroup-core-tools-debug</filename>
460 package group.
461 </para>
462 </section>
463
464 <section id='migration-1.4-variables'>
465 <title>Variables</title>
466
467 <para>
468 The following variables have changed:
469 <itemizedlist>
470 <listitem><para><emphasis><filename>SANITY_TESTED_DISTROS</filename>:</emphasis>
471 This variable now uses a distribution ID, which is composed
472 of the host distributor ID followed by the release.
473 Previously,
474 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
475 was composed of the description field.
476 For example, "Ubuntu 12.10" becomes "Ubuntu-12.10".
477 You do not need to worry about this change if you are not
478 specifically setting this variable, or if you are
479 specifically setting it to "".
480 </para></listitem>
481 <listitem><para><emphasis><filename>SRC_URI</filename>:</emphasis>
482 The <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>,
483 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>,
484 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>,
485 and <filename>FILE_DIRNAME</filename> directories have been
486 dropped from the default value of the
487 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
488 variable, which is used as the search path for finding files
489 referred to in
490 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
491 If you have a recipe that relied upon these directories,
492 which would be unusual, then you will need to add the
493 appropriate paths within the recipe or, alternatively,
494 rearrange the files.
495 The most common locations are still covered by
496 <filename>${BP}</filename>, <filename>${BPN}</filename>,
497 and "files", which all remain in the default value of
498 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
499 </para></listitem>
500 </itemizedlist>
501 </para>
502 </section>
503
504 <section id='migration-target-package-management-with-rpm'>
505 <title>Target Package Management with RPM</title>
506
507 <para>
508 If runtime package management is enabled and the RPM backend
509 is selected, Smart is now installed for package download, dependency
510 resolution, and upgrades instead of Zypper.
511 For more information on how to use Smart, run the following command
512 on the target:
513 <literallayout class='monospaced'>
514 smart --help
515 </literallayout>
516 </para>
517 </section>
518
519 <section id='migration-1.4-recipes-moved'>
520 <title>Recipes Moved</title>
521
522 <para>
523 The following recipes were moved from their previous locations
524 because they are no longer used by anything in
525 the OpenEmbedded-Core:
526 <itemizedlist>
527 <listitem><para><emphasis><filename>clutter-box2d</filename>:</emphasis>
528 Now resides in the <filename>meta-oe</filename> layer.
529 </para></listitem>
530 <listitem><para><emphasis><filename>evolution-data-server</filename>:</emphasis>
531 Now resides in the <filename>meta-gnome</filename> layer.
532 </para></listitem>
533 <listitem><para><emphasis><filename>gthumb</filename>:</emphasis>
534 Now resides in the <filename>meta-gnome</filename> layer.
535 </para></listitem>
536 <listitem><para><emphasis><filename>gtkhtml2</filename>:</emphasis>
537 Now resides in the <filename>meta-oe</filename> layer.
538 </para></listitem>
539 <listitem><para><emphasis><filename>gupnp</filename>:</emphasis>
540 Now resides in the <filename>meta-multimedia</filename> layer.
541 </para></listitem>
542 <listitem><para><emphasis><filename>gypsy</filename>:</emphasis>
543 Now resides in the <filename>meta-oe</filename> layer.
544 </para></listitem>
545 <listitem><para><emphasis><filename>libcanberra</filename>:</emphasis>
546 Now resides in the <filename>meta-gnome</filename> layer.
547 </para></listitem>
548 <listitem><para><emphasis><filename>libgdata</filename>:</emphasis>
549 Now resides in the <filename>meta-gnome</filename> layer.
550 </para></listitem>
551 <listitem><para><emphasis><filename>libmusicbrainz</filename>:</emphasis>
552 Now resides in the <filename>meta-multimedia</filename> layer.
553 </para></listitem>
554 <listitem><para><emphasis><filename>metacity</filename>:</emphasis>
555 Now resides in the <filename>meta-gnome</filename> layer.
556 </para></listitem>
557 <listitem><para><emphasis><filename>polkit</filename>:</emphasis>
558 Now resides in the <filename>meta-oe</filename> layer.
559 </para></listitem>
560 <listitem><para><emphasis><filename>zeroconf</filename>:</emphasis>
561 Now resides in the <filename>meta-networking</filename> layer.
562 </para></listitem>
563 </itemizedlist>
564 </para>
565 </section>
566
567 <section id='migration-1.4-removals-and-renames'>
568 <title>Removals and Renames</title>
569
570 <para>
571 The following list shows what has been removed or renamed:
572 <itemizedlist>
573 <listitem><para><emphasis><filename>evieext</filename>:</emphasis>
574 Removed because it has been removed from
575 <filename>xserver</filename> since 2008.
576 </para></listitem>
577 <listitem><para><emphasis>Gtk+ DirectFB:</emphasis>
578 Removed support because upstream Gtk+ no longer supports it
579 as of version 2.18.
580 </para></listitem>
581 <listitem><para><emphasis><filename>libxfontcache / xfontcacheproto</filename>:</emphasis>
582 Removed because they were removed from the Xorg server in 2008.
583 </para></listitem>
584 <listitem><para><emphasis><filename>libxp / libxprintapputil / libxprintutil / printproto</filename>:</emphasis>
585 Removed because the XPrint server was removed from
586 Xorg in 2008.
587 </para></listitem>
588 <listitem><para><emphasis><filename>libxtrap / xtrapproto</filename>:</emphasis>
589 Removed because their functionality was broken upstream.
590 </para></listitem>
591 <listitem><para><emphasis>linux-yocto 3.0 kernel:</emphasis>
592 Removed with linux-yocto 3.8 kernel being added.
593 The linux-yocto 3.2 and linux-yocto 3.4 kernels remain
594 as part of the release.
595 </para></listitem>
596 <listitem><para><emphasis><filename>lsbsetup</filename>:</emphasis>
597 Removed with functionality now provided by
598 <filename>lsbtest</filename>.
599 </para></listitem>
600 <listitem><para><emphasis><filename>matchbox-stroke</filename>:</emphasis>
601 Removed because it was never more than a proof-of-concept.
602 </para></listitem>
603 <listitem><para><emphasis><filename>matchbox-wm-2 / matchbox-theme-sato-2</filename>:</emphasis>
604 Removed because they are not maintained.
605 However, <filename>matchbox-wm</filename> and
606 <filename>matchbox-theme-sato</filename> are still
607 provided.
608 </para></listitem>
609 <listitem><para><emphasis><filename>mesa-dri</filename>:</emphasis>
610 Renamed to <filename>mesa</filename>.
611 </para></listitem>
612 <listitem><para><emphasis><filename>mesa-xlib</filename>:</emphasis>
613 Removed because it was no longer useful.
614 </para></listitem>
615 <listitem><para><emphasis><filename>mutter</filename>:</emphasis>
616 Removed because nothing ever uses it and the recipe is
617 very old.
618 </para></listitem>
619 <listitem><para><emphasis><filename>orinoco-conf</filename>:</emphasis>
620 Removed because it has become obsolete.
621 </para></listitem>
622 <listitem><para><emphasis><filename>update-modules</filename>:</emphasis>
623 Removed because it is no longer used.
624 The kernel module <filename>postinstall</filename> and
625 <filename>postrm</filename> scripts can now do the same
626 task without the use of this script.
627 </para></listitem>
628 <listitem><para><emphasis><filename>web</filename>:</emphasis>
629 Removed because it is not maintained. Superseded by
630 <filename>web-webkit</filename>.
631 </para></listitem>
632 <listitem><para><emphasis><filename>xf86bigfontproto</filename>:</emphasis>
633 Removed because upstream it has been disabled by default
634 since 2007.
635 Nothing uses <filename>xf86bigfontproto</filename>.
636 </para></listitem>
637 <listitem><para><emphasis><filename>xf86rushproto</filename>:</emphasis>
638 Removed because its dependency in
639 <filename>xserver</filename> was spurious and it was
640 removed in 2005.
641 </para></listitem>
642 <listitem><para><emphasis><filename>zypper / libzypp / sat-solver</filename>:</emphasis>
643 Removed and been functionally replaced with Smart
644 (<filename>python-smartpm</filename>) when RPM packaging
645 is used and package management is enabled on the target.
646 </para></listitem>
647 </itemizedlist>
648 </para>
649 </section>
650</section>
651
652<section id='moving-to-the-yocto-project-1.5-release'>
653 <title>Moving to the Yocto Project 1.5 Release</title>
654
655 <para>
656 This section provides migration information for moving to the
657 Yocto Project 1.5 Release from the prior release.
658 </para>
659
660 <section id='migration-1.5-host-dependency-changes'>
661 <title>Host Dependency Changes</title>
662
663 <para>
664 The OpenEmbedded build system now has some additional requirements
665 on the host system:
666 <itemizedlist>
667 <listitem><para>Python 2.7.3+</para></listitem>
668 <listitem><para>Tar 1.24+</para></listitem>
669 <listitem><para>Git 1.7.8+</para></listitem>
670 <listitem><para>Patched version of Make if you are using
671 3.82.
672 Most distributions that provide Make 3.82 use the patched
673 version.</para></listitem>
674 </itemizedlist>
675 If the Linux distribution you are using on your build host
676 does not provide packages for these, you can install and use
677 the Buildtools tarball, which provides an SDK-like environment
678 containing them.
679 </para>
680
681 <para>
682 For more information on this requirement, see the
683 "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
684 section.
685 </para>
686 </section>
687
688 <section id='migration-1.5-atom-pc-bsp'>
689 <title><filename>atom-pc</filename> Board Support Package (BSP)</title>
690
691 <para>
692 The <filename>atom-pc</filename> hardware reference BSP has been
693 replaced by a <filename>genericx86</filename> BSP.
694 This BSP is not necessarily guaranteed to work on all x86
695 hardware, but it will run on a wider range of systems than the
696 <filename>atom-pc</filename> did.
697 <note>
698 Additionally, a <filename>genericx86-64</filename> BSP has
699 been added for 64-bit Atom systems.
700 </note>
701 </para>
702 </section>
703
704 <section id='migration-1.5-bitbake'>
705 <title>BitBake</title>
706
707 <para>
708 The following changes have been made that relate to BitBake:
709 <itemizedlist>
710 <listitem><para>
711 BitBake now supports a <filename>_remove</filename>
712 operator.
713 The addition of this operator means you will have to
714 rename any items in recipe space (functions, variables)
715 whose names currently contain
716 <filename>_remove_</filename> or end with
717 <filename>_remove</filename> to avoid unexpected behavior.
718 </para></listitem>
719 <listitem><para>
720 BitBake's global method pool has been removed.
721 This method is not particularly useful and led to clashes
722 between recipes containing functions that had the
723 same name.</para></listitem>
724 <listitem><para>
725 The "none" server backend has been removed.
726 The "process" server backend has been serving well as the
727 default for a long time now.</para></listitem>
728 <listitem><para>
729 The <filename>bitbake-runtask</filename> script has been
730 removed.</para></listitem>
731 <listitem><para>
732 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>
733 and
734 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>
735 are no longer added to
736 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
737 by default in <filename>bitbake.conf</filename>.
738 These version-specific <filename>PROVIDES</filename>
739 items were seldom used.
740 Attempting to use them could result in two versions being
741 built simultaneously rather than just one version due to
742 the way BitBake resolves dependencies.</para></listitem>
743 </itemizedlist>
744 </para>
745 </section>
746
747 <section id='migration-1.5-qa-warnings'>
748 <title>QA Warnings</title>
749
750 <para>
751 The following changes have been made to the package QA checks:
752 <itemizedlist>
753 <listitem><para>
754 If you have customized
755 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
756 or <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link>
757 values in your configuration, check that they contain all of
758 the issues that you wish to be reported.
759 Previous Yocto Project versions contained a bug that meant
760 that any item not mentioned in <filename>ERROR_QA</filename>
761 or <filename>WARN_QA</filename> would be treated as a
762 warning.
763 Consequently, several important items were not already in
764 the default value of <filename>WARN_QA</filename>.
765 All of the possible QA checks are now documented in the
766 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
767 section.</para></listitem>
768 <listitem><para>
769 An additional QA check has been added to check if
770 <filename>/usr/share/info/dir</filename> is being installed.
771 Your recipe should delete this file within
772 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
773 if "make install" is installing it.
774 </para></listitem>
775 <listitem><para>
776 If you are using the buildhistory class, the check for the
777 package version going backwards is now controlled using a
778 standard QA check.
779 Thus, if you have customized your
780 <filename>ERROR_QA</filename> or
781 <filename>WARN_QA</filename> values and still wish to have
782 this check performed, you should add
783 "version-going-backwards" to your value for one or the
784 other variables depending on how you wish it to be handled.
785 See the documented QA checks in the
786 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
787 section.
788 </para></listitem>
789 </itemizedlist>
790 </para>
791 </section>
792
793 <section id='migration-1.5-directory-layout-changes'>
794 <title>Directory Layout Changes</title>
795
796 <para>
797 The following directory changes exist:
798 <itemizedlist>
799 <listitem><para>
800 Output SDK installer files are now named to include the
801 image name and tuning architecture through the
802 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
803 variable.</para></listitem>
804 <listitem><para>
805 Images and related files are now installed into a directory
806 that is specific to the machine, instead of a parent
807 directory containing output files for multiple machines.
808 The
809 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
810 variable continues to point to the directory containing
811 images for the current
812 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
813 and should be used anywhere there is a need to refer to
814 this directory.
815 The <filename>runqemu</filename> script now uses this
816 variable to find images and kernel binaries and will use
817 BitBake to determine the directory.
818 Alternatively, you can set the
819 <filename>DEPLOY_DIR_IMAGE</filename> variable in the
820 external environment.</para></listitem>
821 <listitem><para>
822 When buildhistory is enabled, its output is now written
823 under the
824 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
825 rather than
826 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>.
827 Doing so makes it easier to delete
828 <filename>TMPDIR</filename> and preserve the build history.
829 Additionally, data for produced SDKs is now split by
830 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>.
831 </para></listitem>
832 <listitem><para>
833 The <filename>pkgdata</filename> directory produced as
834 part of the packaging process has been collapsed into a
835 single machine-specific directory.
836 This directory is located under
837 <filename>sysroots</filename> and uses a machine-specific
838 name (i.e.
839 <filename>tmp/sysroots/<replaceable>machine</replaceable>/pkgdata</filename>).
840 </para></listitem>
841 </itemizedlist>
842 </para>
843 </section>
844
845 <section id='migration-1.5-shortened-git-srcrev-values'>
846 <title>Shortened Git <filename>SRCREV</filename> Values</title>
847
848 <para>
849 BitBake will now shorten revisions from Git repositories from the
850 normal 40 characters down to 10 characters within
851 <link linkend='var-SRCPV'><filename>SRCPV</filename></link>
852 for improved usability in path and file names.
853 This change should be safe within contexts where these revisions
854 are used because the chances of spatially close collisions
855 is very low.
856 Distant collisions are not a major issue in the way
857 the values are used.
858 </para>
859 </section>
860
861 <section id='migration-1.5-image-features'>
862 <title><filename>IMAGE_FEATURES</filename></title>
863
864 <para>
865 The following changes have been made that relate to
866 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
867 <itemizedlist>
868 <listitem><para>
869 The value of
870 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
871 is now validated to ensure invalid feature items are not
872 added.
873 Some users mistakenly add package names to this variable
874 instead of using
875 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
876 in order to have the package added to the image, which does
877 not work.
878 This change is intended to catch those kinds of situations.
879 Valid <filename>IMAGE_FEATURES</filename> are drawn from
880 <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
881 definitions,
882 <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link>
883 and a new "validitems" varflag on
884 <filename>IMAGE_FEATURES</filename>.
885 The "validitems" varflag change allows additional features
886 to be added if they are not provided using the previous
887 two mechanisms.
888 </para></listitem>
889 <listitem><para>
890 The previously deprecated "apps-console-core"
891 <filename>IMAGE_FEATURES</filename> item is no longer
892 supported.
893 Add "splash" to <filename>IMAGE_FEATURES</filename> if you
894 wish to have the splash screen enabled, since this is
895 all that apps-console-core was doing.</para></listitem>
896 </itemizedlist>
897 </para>
898 </section>
899
900 <section id='migration-1.5-run'>
901 <title><filename>/run</filename></title>
902
903 <para>
904 The <filename>/run</filename> directory from the Filesystem
905 Hierarchy Standard 3.0 has been introduced.
906 You can find some of the implications for this change
907 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873'>here</ulink>.
908 The change also means that recipes that install files to
909 <filename>/var/run</filename> must be changed.
910 You can find a guide on how to make these changes
911 <ulink url='http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530'>here</ulink>.
912 </para>
913 </section>
914
915 <section id='migration-1.5-removal-of-package-manager-database-within-image-recipes'>
916 <title>Removal of Package Manager Database Within Image Recipes</title>
917
918 <para>
919 The image <filename>core-image-minimal</filename> no longer adds
920 <filename>remove_packaging_data_files</filename> to
921 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
922 This addition is now handled automatically when "package-management"
923 is not in
924 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
925 If you have custom image recipes that make this addition,
926 you should remove the lines, as they are not needed and might
927 interfere with correct operation of postinstall scripts.
928 </para>
929 </section>
930
931 <section id='migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time'>
932 <title>Images Now Rebuild Only on Changes Instead of Every Time</title>
933
934 <para>
935 The
936 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
937 and other related image
938 construction tasks are no longer marked as "nostamp".
939 Consequently, they will only be re-executed when their inputs have
940 changed.
941 Previous versions of the OpenEmbedded build system always rebuilt
942 the image when requested rather when necessary.
943 </para>
944 </section>
945
946 <section id='migration-1.5-task-recipes'>
947 <title>Task Recipes</title>
948
949 <para>
950 The previously deprecated <filename>task.bbclass</filename> has
951 now been dropped.
952 For recipes that previously inherited from this class, you should
953 rename them from <filename>task-*</filename> to
954 <filename>packagegroup-*</filename> and inherit packagegroup
955 instead.
956 </para>
957
958 <para>
959 For more information, see the
960 "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>"
961 section.
962 </para>
963 </section>
964
965 <section id='migration-1.5-busybox'>
966 <title>BusyBox</title>
967
968 <para>
969 By default, we now split BusyBox into two binaries:
970 one that is suid root for those components that need it, and
971 another for the rest of the components.
972 Splitting BusyBox allows for optimization that eliminates the
973 <filename>tinylogin</filename> recipe as recommended by upstream.
974 You can disable this split by setting
975 <link linkend='var-BUSYBOX_SPLIT_SUID'><filename>BUSYBOX_SPLIT_SUID</filename></link>
976 to "0".
977 </para>
978 </section>
979
980 <section id='migration-1.5-automated-image-testing'>
981 <title>Automated Image Testing</title>
982
983 <para>
984 A new automated image testing framework has been added
985 through the
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500986 <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500987 class.
988 This framework replaces the older
989 <filename>imagetest-qemu</filename> framework.
990 </para>
991
992 <para>
993 You can learn more about performing automated image tests in the
994 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
995 section.
996 </para>
997 </section>
998
999 <section id='migration-1.5-build-history'>
1000 <title>Build History</title>
1001
1002 <para>
1003 Following are changes to Build History:
1004 <itemizedlist>
1005 <listitem><para>
1006 Installed package sizes:
1007 <filename>installed-package-sizes.txt</filename> for an
1008 image now records the size of the files installed by each
1009 package instead of the size of each compressed package
1010 archive file.</para></listitem>
1011 <listitem><para>
1012 The dependency graphs (<filename>depends*.dot</filename>)
1013 now use the actual package names instead of replacing
1014 dashes, dots and plus signs with underscores.
1015 </para></listitem>
1016 <listitem><para>
1017 The <filename>buildhistory-diff</filename> and
1018 <filename>buildhistory-collect-srcrevs</filename>
1019 utilities have improved command-line handling.
1020 Use the <filename>--help</filename> option for
1021 each utility for more information on the new syntax.
1022 </para></listitem>
1023 </itemizedlist>
1024 For more information on Build History, see the
1025 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
1026 section.
1027 </para>
1028 </section>
1029
1030 <section id='migration-1.5-udev'>
1031 <title><filename>udev</filename></title>
1032
1033 <para>
1034 Following are changes to <filename>udev</filename>:
1035 <itemizedlist>
1036 <listitem><para>
1037 <filename>udev</filename> no longer brings in
1038 <filename>udev-extraconf</filename> automatically
1039 through
1040 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1041 since this was originally intended to be optional.
1042 If you need the extra rules, then add
1043 <filename>udev-extraconf</filename> to your image.
1044 </para></listitem>
1045 <listitem><para>
1046 <filename>udev</filename> no longer brings in
1047 <filename>pciutils-ids</filename> or
1048 <filename>usbutils-ids</filename> through
1049 <filename>RRECOMMENDS</filename>.
1050 These are not needed by <filename>udev</filename> itself
1051 and removing them saves around 350KB.
1052 </para></listitem>
1053 </itemizedlist>
1054 </para>
1055 </section>
1056
1057 <section id='migration-1.5-removed-renamed-recipes'>
1058 <title>Removed and Renamed Recipes</title>
1059
1060 <itemizedlist>
1061 <listitem><para>
1062 The <filename>linux-yocto</filename> 3.2 kernel has been
1063 removed.</para></listitem>
1064 <listitem><para>
1065 <filename>libtool-nativesdk</filename> has been renamed to
1066 <filename>nativesdk-libtool</filename>.</para></listitem>
1067 <listitem><para>
1068 <filename>tinylogin</filename> has been removed.
1069 It has been replaced by a suid portion of Busybox.
1070 See the
1071 "<link linkend='migration-1.5-busybox'>BusyBox</link>" section
1072 for more information.</para></listitem>
1073 <listitem><para>
1074 <filename>external-python-tarball</filename> has been renamed
1075 to <filename>buildtools-tarball</filename>.
1076 </para></listitem>
1077 <listitem><para>
1078 <filename>web-webkit</filename> has been removed.
1079 It has been functionally replaced by
1080 <filename>midori</filename>.</para></listitem>
1081 <listitem><para>
1082 <filename>imake</filename> has been removed.
1083 It is no longer needed by any other recipe.
1084 </para></listitem>
1085 <listitem><para>
1086 <filename>transfig-native</filename> has been removed.
1087 It is no longer needed by any other recipe.
1088 </para></listitem>
1089 <listitem><para>
1090 <filename>anjuta-remote-run</filename> has been removed.
1091 Anjuta IDE integration has not been officially supported for
1092 several releases.</para></listitem>
1093 </itemizedlist>
1094 </section>
1095
1096 <section id='migration-1.5-other-changes'>
1097 <title>Other Changes</title>
1098
1099 <para>
1100 Following is a list of short entries describing other changes:
1101 <itemizedlist>
1102 <listitem><para>
1103 <filename>run-postinsts</filename>: Make this generic.
1104 </para></listitem>
1105 <listitem><para>
1106 <filename>base-files</filename>: Remove the unnecessary
1107 <filename>media/</filename><replaceable>xxx</replaceable> directories.
1108 </para></listitem>
1109 <listitem><para>
1110 <filename>alsa-state</filename>: Provide an empty
1111 <filename>asound.conf</filename> by default.
1112 </para></listitem>
1113 <listitem><para>
1114 <filename>classes/image</filename>: Ensure
1115 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1116 supports pre-renamed package names.</para></listitem>
1117 <listitem><para>
1118 <filename>classes/rootfs_rpm</filename>: Implement
1119 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1120 for RPM.</para></listitem>
1121 <listitem><para>
1122 <filename>systemd</filename>: Remove
1123 <filename>systemd_unitdir</filename> if
1124 <filename>systemd</filename> is not in
1125 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1126 </para></listitem>
1127 <listitem><para>
1128 <filename>systemd</filename>: Remove
1129 <filename>init.d</filename> dir if
1130 <filename>systemd</filename> unit file is present and
1131 <filename>sysvinit</filename> is not a distro feature.
1132 </para></listitem>
1133 <listitem><para>
1134 <filename>libpam</filename>: Deny all services for the
1135 <filename>OTHER</filename> entries.
1136 </para></listitem>
1137 <listitem><para>
1138 <filename>image.bbclass</filename>: Move
1139 <filename>runtime_mapping_rename</filename> to avoid
1140 conflict with <filename>multilib</filename>.
1141 See
1142 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993'><filename>YOCTO #4993</filename></ulink>
1143 in Bugzilla for more information.
1144 </para></listitem>
1145 <listitem><para>
1146 <filename>linux-dtb</filename>: Use kernel build system
1147 to generate the <filename>dtb</filename> files.
1148 </para></listitem>
1149 <listitem><para>
1150 <filename>kern-tools</filename>: Switch from guilt to
1151 new <filename>kgit-s2q</filename> tool.
1152 </para></listitem>
1153 </itemizedlist>
1154 </para>
1155 </section>
1156</section>
1157
1158<section id='moving-to-the-yocto-project-1.6-release'>
1159 <title>Moving to the Yocto Project 1.6 Release</title>
1160
1161 <para>
1162 This section provides migration information for moving to the
1163 Yocto Project 1.6 Release from the prior release.
1164 </para>
1165
1166
1167 <section id='migration-1.6-archiver-class'>
1168 <title><filename>archiver</filename> Class</title>
1169
1170 <para>
1171 The
1172 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
1173 class has been rewritten and its configuration has been simplified.
1174 For more details on the source archiver, see the
1175 "<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>"
1176 section in the Yocto Project Development Manual.
1177 </para>
1178 </section>
1179
1180 <section id='migration-1.6-packaging-changes'>
1181 <title>Packaging Changes</title>
1182
1183 <para>
1184 The following packaging changes have been made:
1185 <itemizedlist>
1186 <listitem><para>
1187 The <filename>binutils</filename> recipe no longer produces
1188 a <filename>binutils-symlinks</filename> package.
1189 <filename>update-alternatives</filename> is now used to
1190 handle the preferred <filename>binutils</filename>
1191 variant on the target instead.
1192 </para></listitem>
1193 <listitem><para>
1194 The tc (traffic control) utilities have been split out of
1195 the main <filename>iproute2</filename> package and put
1196 into the <filename>iproute2-tc</filename> package.
1197 </para></listitem>
1198 <listitem><para>
1199 The <filename>gtk-engines</filename> schemas have been
1200 moved to a dedicated
1201 <filename>gtk-engines-schemas</filename> package.
1202 </para></listitem>
1203 <listitem><para>
1204 The <filename>armv7a</filename> with thumb package
1205 architecture suffix has changed.
1206 The suffix for these packages with the thumb
1207 optimization enabled is "t2" as it should be.
1208 Use of this suffix was not the case in the 1.5 release.
1209 Architecture names will change within package feeds as a
1210 result.
1211 </para></listitem>
1212 </itemizedlist>
1213 </para>
1214 </section>
1215
1216 <section id='migration-1.6-bitbake'>
1217 <title>BitBake</title>
1218
1219 <para>
1220 The following changes have been made to
1221 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
1222 </para>
1223
1224 <section id='migration-1.6-matching-branch-requirement-for-git-fetching'>
1225 <title>Matching Branch Requirement for Git Fetching</title>
1226
1227 <para>
1228 When fetching source from a Git repository using
1229 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
1230 BitBake will now validate the
1231 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
1232 value against the branch.
1233 You can specify the branch using the following form:
1234 <literallayout class='monospaced'>
1235 SRC_URI = "git://server.name/repository;branch=<replaceable>branchname</replaceable>"
1236 </literallayout>
1237 If you do not specify a branch, BitBake looks
1238 in the default "master" branch.
1239 </para>
1240
1241 <para>
1242 Alternatively, if you need to bypass this check (e.g.
1243 if you are fetching a revision corresponding to a tag that
1244 is not on any branch), you can add ";nobranch=1" to
1245 the end of the URL within <filename>SRC_URI</filename>.
1246 </para>
1247 </section>
1248
1249 <section id='migration-1.6-bitbake-deps'>
1250 <title>Python Definition substitutions</title>
1251
1252 <para>
1253 BitBake had some previously deprecated Python definitions
1254 within its <filename>bb</filename> module removed.
1255 You should use their sub-module counterparts instead:
1256 <itemizedlist>
1257 <listitem><para><filename>bb.MalformedUrl</filename>:
1258 Use <filename>bb.fetch.MalformedUrl</filename>.
1259 </para></listitem>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001260 <listitem><para><filename>bb.encodeurl</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001261 Use <filename>bb.fetch.encodeurl</filename>.
1262 </para></listitem>
1263 <listitem><para><filename>bb.decodeurl</filename>:
1264 Use <filename>bb.fetch.decodeurl</filename>
1265 </para></listitem>
1266 <listitem><para><filename>bb.mkdirhier</filename>:
1267 Use <filename>bb.utils.mkdirhier</filename>.
1268 </para></listitem>
1269 <listitem><para><filename>bb.movefile</filename>:
1270 Use <filename>bb.utils.movefile</filename>.
1271 </para></listitem>
1272 <listitem><para><filename>bb.copyfile</filename>:
1273 Use <filename>bb.utils.copyfile</filename>.
1274 </para></listitem>
1275 <listitem><para><filename>bb.which</filename>:
1276 Use <filename>bb.utils.which</filename>.
1277 </para></listitem>
1278 <listitem><para><filename>bb.vercmp_string</filename>:
1279 Use <filename>bb.utils.vercmp_string</filename>.
1280 </para></listitem>
1281 <listitem><para><filename>bb.vercmp</filename>:
1282 Use <filename>bb.utils.vercmp</filename>.
1283 </para></listitem>
1284 </itemizedlist>
1285 </para>
1286 </section>
1287
1288 <section id='migration-1.6-bitbake-fetcher'>
1289 <title>SVK Fetcher</title>
1290
1291 <para>
1292 The SVK fetcher has been removed from BitBake.
1293 </para>
1294 </section>
1295
1296 <section id='migration-1.6-bitbake-console-output'>
1297 <title>Console Output Error Redirection</title>
1298
1299 <para>
1300 The BitBake console UI will now output errors to
1301 <filename>stderr</filename> instead of
1302 <filename>stdout</filename>.
1303 Consequently, if you are piping or redirecting the output of
1304 <filename>bitbake</filename> to somewhere else, and you wish
1305 to retain the errors, you will need to add
1306 <filename>2>&amp;1</filename> (or something similar) to the
1307 end of your <filename>bitbake</filename> command line.
1308 </para>
1309 </section>
1310
1311 <section id='migration-1.6-task-taskname-overrides'>
1312 <title><filename>task-</filename><replaceable>taskname</replaceable> Overrides</title>
1313
1314 <para>
1315 <filename>task-</filename><replaceable>taskname</replaceable> overrides have been
1316 adjusted so that tasks whose names contain underscores have the
1317 underscores replaced by hyphens for the override so that they
1318 now function properly.
1319 For example, the task override for
1320 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
1321 is <filename>task-populate-sdk</filename>.
1322 </para>
1323 </section>
1324 </section>
1325
1326 <section id='migration-1.6-variable-changes'>
1327 <title>Changes to Variables</title>
1328
1329 <para>
1330 The following variables have changed.
1331 For information on the OpenEmbedded build system variables, see the
1332 "<link linkend='ref-variables-glos'>Variables Glossary</link>" Chapter.
1333 </para>
1334
1335 <section id='migration-1.6-variable-changes-TMPDIR'>
1336 <title><filename>TMPDIR</filename></title>
1337
1338 <para>
1339 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1340 can no longer be on an NFS mount.
1341 NFS does not offer full POSIX locking and inode consistency
1342 and can cause unexpected issues if used to store
1343 <filename>TMPDIR</filename>.
1344 </para>
1345
1346 <para>
1347 The check for this occurs on startup.
1348 If <filename>TMPDIR</filename> is detected on an NFS mount,
1349 an error occurs.
1350 </para>
1351 </section>
1352
1353 <section id='migration-1.6-variable-changes-PRINC'>
1354 <title><filename>PRINC</filename></title>
1355
1356 <para>
1357 The <filename>PRINC</filename>
1358 variable has been deprecated and triggers a warning if
1359 detected during a build.
1360 For
1361 <link linkend='var-PR'><filename>PR</filename></link>
1362 increments on changes, use the PR service instead.
1363 You can find out more about this service in the
1364 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
1365 section in the Yocto Project Development Manual.
1366 </para>
1367 </section>
1368
1369 <section id='migration-1.6-variable-changes-IMAGE_TYPES'>
1370 <title><filename>IMAGE_TYPES</filename></title>
1371
1372 <para>
1373 The "sum.jffs2" option for
1374 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>
1375 has been replaced by the "jffs2.sum" option, which fits the
1376 processing order.
1377 </para>
1378 </section>
1379
1380 <section id='migration-1.6-variable-changes-COPY_LIC_MANIFEST'>
1381 <title><filename>COPY_LIC_MANIFEST</filename></title>
1382
1383 <para>
1384 The
1385 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1386 variable must
1387 now be set to "1" rather than any value in order to enable
1388 it.
1389 </para>
1390 </section>
1391
1392 <section id='migration-1.6-variable-changes-COPY_LIC_DIRS'>
1393 <title><filename>COPY_LIC_DIRS</filename></title>
1394
1395 <para>
1396 The
1397 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
1398 variable must
1399 now be set to "1" rather than any value in order to enable
1400 it.
1401 </para>
1402 </section>
1403
1404 <section id='migration-1.6-variable-changes-PACKAGE_GROUP'>
1405 <title><filename>PACKAGE_GROUP</filename></title>
1406
1407 <para>
1408 The
1409 <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
1410 variable has been renamed to
1411 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>
1412 to more accurately reflect its purpose.
1413 You can still use <filename>PACKAGE_GROUP</filename> but
1414 the OpenEmbedded build system produces a warning message when
1415 it encounters the variable.
1416 </para>
1417 </section>
1418
1419 <section id='migration-1.6-variable-changes-variable-entry-behavior'>
1420 <title>Preprocess and Post Process Command Variable Behavior</title>
1421
1422 <para>
1423 The following variables now expect a semicolon separated
1424 list of functions to call and not arbitrary shell commands:
1425 <literallayout class='monospaced'>
1426 <link linkend='var-ROOTFS_PREPROCESS_COMMAND'>ROOTFS_PREPROCESS_COMMAND</link>
1427 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'>ROOTFS_POSTPROCESS_COMMAND</link>
1428 <link linkend='var-SDK_POSTPROCESS_COMMAND'>SDK_POSTPROCESS_COMMAND</link>
1429 <link linkend='var-POPULATE_SDK_POST_TARGET_COMMAND'>POPULATE_SDK_POST_TARGET_COMMAND</link>
1430 <link linkend='var-POPULATE_SDK_POST_HOST_COMMAND'>POPULATE_SDK_POST_HOST_COMMAND</link>
1431 <link linkend='var-IMAGE_POSTPROCESS_COMMAND'>IMAGE_POSTPROCESS_COMMAND</link>
1432 <link linkend='var-IMAGE_PREPROCESS_COMMAND'>IMAGE_PREPROCESS_COMMAND</link>
1433 <link linkend='var-ROOTFS_POSTUNINSTALL_COMMAND'>ROOTFS_POSTUNINSTALL_COMMAND</link>
1434 <link linkend='var-ROOTFS_POSTINSTALL_COMMAND'>ROOTFS_POSTINSTALL_COMMAND</link>
1435 </literallayout>
1436 For migration purposes, you can simply wrap shell commands in
1437 a shell function and then call the function.
1438 Here is an example:
1439 <literallayout class='monospaced'>
1440 my_postprocess_function() {
1441 echo "hello" > ${IMAGE_ROOTFS}/hello.txt
1442 }
1443 ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "
1444 </literallayout>
1445 </para>
1446 </section>
1447 </section>
1448
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001449 <section id='migration-1.6-package-test-ptest'>
1450 <title>Package Test (ptest)</title>
1451
1452 <para>
1453 Package Tests (ptest) are built but not installed by default.
1454 For information on using Package Tests, see the
1455 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Setting up and running package test (ptest)</ulink>"
1456 section in the Yocto Project Development Manual.
1457 For information on the <filename>ptest</filename> class, see the
1458 "<link linkend='ref-classes-ptest'><filename>ptest.bbclass</filename></link>"
1459 section.
1460 </para>
1461 </section>
1462
1463 <section id='migration-1.6-build-changes'>
1464 <title>Build Changes</title>
1465
1466 <para>
1467 Separate build and source directories have been enabled
1468 by default for selected recipes where it is known to work
1469 (a whitelist) and for all recipes that inherit the
1470 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
1471 class.
1472 In future releases the
1473 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
1474 class will enable a separate build directory by default as
1475 well.
1476 Recipes building Autotools-based
1477 software that fails to build with a separate build directory
1478 should be changed to inherit from the
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001479 <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
1480 class instead of the <filename>autotools</filename> or
1481 <filename>autotools_stage</filename>classes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001482 </para>
1483 </section>
1484
1485 <section id='migration-1.6-building-qemu-native'>
1486 <title><filename>qemu-native</filename></title>
1487
1488 <para>
1489 <filename>qemu-native</filename> now builds without
1490 SDL-based graphical output support by default.
1491 The following additional lines are needed in your
1492 <filename>local.conf</filename> to enable it:
1493 <literallayout class='monospaced'>
1494 PACKAGECONFIG_pn-qemu-native = "sdl"
1495 ASSUME_PROVIDED += "libsdl-native"
1496 </literallayout>
1497 <note>
1498 The default <filename>local.conf</filename>
1499 contains these statements.
1500 Consequently, if you are building a headless system and using
1501 a default <filename>local.conf</filename> file, you will need
1502 comment these two lines out.
1503 </note>
1504 </para>
1505 </section>
1506
1507 <section id='migration-1.6-core-image-basic'>
1508 <title><filename>core-image-basic</filename></title>
1509
1510 <para>
1511 <filename>core-image-basic</filename> has been renamed to
1512 <filename>core-image-full-cmdline</filename>.
1513 </para>
1514
1515 <para>
1516 In addition to <filename>core-image-basic</filename> being renamed,
1517 <filename>packagegroup-core-basic</filename> has been renamed to
1518 <filename>packagegroup-core-full-cmdline</filename> to match.
1519 </para>
1520 </section>
1521
1522 <section id='migration-1.6-licensing'>
1523 <title>Licensing</title>
1524
1525 <para>
1526 The top-level <filename>LICENSE</filename> file has been changed
1527 to better describe the license of the various components of
1528 OE-Core.
1529 However, the licensing itself remains unchanged.
1530 </para>
1531
1532 <para>
1533 Normally, this change would not cause any side-effects.
1534 However, some recipes point to this file within
1535 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
1536 (as <filename>${COREBASE}/LICENSE</filename>) and thus the
1537 accompanying checksum must be changed from
1538 3f40d7994397109285ec7b81fdeb3b58 to
1539 4d92cd373abda3937c2bc47fbc49d690.
1540 A better alternative is to have
1541 <filename>LIC_FILES_CHKSUM</filename> point to a file
1542 describing the license that is distributed with the source
1543 that the recipe is building, if possible, rather than pointing
1544 to <filename>${COREBASE}/LICENSE</filename>.
1545 </para>
1546 </section>
1547
1548 <section id='migration-1.6-cflags-options'>
1549 <title><filename>CFLAGS</filename> Options</title>
1550
1551 <para>
1552 The "-fpermissive" option has been removed from the default
1553 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1554 value.
1555 You need to take action on individual recipes that fail when
1556 building with this option.
1557 You need to either patch the recipes to fix the issues reported by
1558 the compiler, or you need to add "-fpermissive" to
1559 <filename>CFLAGS</filename> in the recipes.
1560 </para>
1561 </section>
1562
1563 <section id='migration-1.6-custom-images'>
1564 <title>Custom Image Output Types</title>
1565
1566 <para>
1567 Custom image output types, as selected using
1568 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
1569 must declare their dependencies on other image types (if any) using
1570 a new
1571 <link linkend='var-IMAGE_TYPEDEP'><filename>IMAGE_TYPEDEP</filename></link>
1572 variable.
1573 </para>
1574 </section>
1575
1576 <section id='migration-1.6-do-package-write-task'>
1577 <title>Tasks</title>
1578
1579 <para>
1580 The <filename>do_package_write</filename> task has been removed.
1581 The task is no longer needed.
1582 </para>
1583 </section>
1584
1585 <section id='migration-1.6-update-alternatives-provider'>
1586 <title><filename>update-alternative</filename> Provider</title>
1587
1588 <para>
1589 The default <filename>update-alternatives</filename> provider has
1590 been changed from <filename>opkg</filename> to
1591 <filename>opkg-utils</filename>.
1592 This change resolves some troublesome circular dependencies.
1593 The runtime package has also been renamed from
1594 <filename>update-alternatives-cworth</filename>
1595 to <filename>update-alternatives-opkg</filename>.
1596 </para>
1597 </section>
1598
1599 <section id='migration-1.6-virtclass-overrides'>
1600 <title><filename>virtclass</filename> Overrides</title>
1601
1602 <para>
1603 The <filename>virtclass</filename> overrides are now deprecated.
1604 Use the equivalent class overrides instead (e.g.
1605 <filename>virtclass-native</filename> becomes
1606 <filename>class-native</filename>.)
1607 </para>
1608 </section>
1609
1610 <section id='migration-1.6-removed-renamed-recipes'>
1611 <title>Removed and Renamed Recipes</title>
1612
1613 <para>
1614 The following recipes have been removed:
1615 <itemizedlist>
1616 <listitem><para><filename>packagegroup-toolset-native</filename> -
1617 This recipe is largely unused.
1618 </para></listitem>
1619 <listitem><para><filename>linux-yocto-3.8</filename> -
1620 Support for the Linux yocto 3.8 kernel has been dropped.
1621 Support for the 3.10 and 3.14 kernels have been added
1622 with the <filename>linux-yocto-3.10</filename> and
1623 <filename>linux-yocto-3.14</filename> recipes.
1624 </para></listitem>
1625 <listitem><para><filename>ocf-linux</filename> -
1626 This recipe has been functionally replaced using
1627 <filename>cryptodev-linux</filename>.
1628 </para></listitem>
1629 <listitem><para><filename>genext2fs</filename> -
1630 <filename>genext2fs</filename> is no longer used by the
1631 build system and is unmaintained upstream.
1632 </para></listitem>
1633 <listitem><para><filename>js</filename> -
1634 This provided an ancient version of Mozilla's javascript
1635 engine that is no longer needed.
1636 </para></listitem>
1637 <listitem><para><filename>zaurusd</filename> -
1638 The recipe has been moved to the
1639 <filename>meta-handheld</filename> layer.
1640 </para></listitem>
1641 <listitem><para><filename>eglibc 2.17</filename> -
1642 Replaced by the <filename>eglibc 2.19</filename>
1643 recipe.
1644 </para></listitem>
1645 <listitem><para><filename>gcc 4.7.2</filename> -
1646 Replaced by the now stable
1647 <filename>gcc 4.8.2</filename>.
1648 </para></listitem>
1649 <listitem><para><filename>external-sourcery-toolchain</filename> -
1650 this recipe is now maintained in the
1651 <filename>meta-sourcery</filename> layer.
1652 </para></listitem>
1653 <listitem><para><filename>linux-libc-headers-yocto 3.4+git</filename> -
1654 Now using version 3.10 of the
1655 <filename>linux-libc-headers</filename> by default.
1656 </para></listitem>
1657 <listitem><para><filename>meta-toolchain-gmae</filename> -
1658 This recipe is obsolete.
1659 </para></listitem>
1660 <listitem><para><filename>packagegroup-core-sdk-gmae</filename> -
1661 This recipe is obsolete.
1662 </para></listitem>
1663 <listitem><para><filename>packagegroup-core-standalone-gmae-sdk-target</filename> -
1664 This recipe is obsolete.
1665 </para></listitem>
1666 </itemizedlist>
1667 </para>
1668 </section>
1669
1670 <section id='migration-1.6-removed-classes'>
1671 <title>Removed Classes</title>
1672
1673 <para>
1674 The following classes have become obsolete and have been removed:
1675 <itemizedlist>
1676 <listitem><para><filename>module_strip</filename>
1677 </para></listitem>
1678 <listitem><para><filename>pkg_metainfo</filename>
1679 </para></listitem>
1680 <listitem><para><filename>pkg_distribute</filename>
1681 </para></listitem>
1682 <listitem><para><filename>image-empty</filename>
1683 </para></listitem>
1684 </itemizedlist>
1685 </para>
1686 </section>
1687
1688 <section id='migration-1.6-reference-bsps'>
1689 <title>Reference Board Support Packages (BSPs)</title>
1690
1691 <para>
1692 The following reference BSPs changes occurred:
1693 <itemizedlist>
1694 <listitem><para>The BeagleBoard
1695 (<filename>beagleboard</filename>) ARM reference hardware
1696 has been replaced by the BeagleBone
1697 (<filename>beaglebone</filename>) hardware.
1698 </para></listitem>
1699 <listitem><para>The RouterStation Pro
1700 (<filename>routerstationpro</filename>) MIPS reference
1701 hardware has been replaced by the EdgeRouter Lite
1702 (<filename>edgerouter</filename>) hardware.
1703 </para></listitem>
1704 </itemizedlist>
1705 The previous reference BSPs for the
1706 <filename>beagleboard</filename> and
1707 <filename>routerstationpro</filename> machines are still available
1708 in a new <filename>meta-yocto-bsp-old</filename> layer in the
1709 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
1710 at
1711 <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>.
1712 </para>
1713 </section>
1714</section>
1715
1716<section id='moving-to-the-yocto-project-1.7-release'>
1717 <title>Moving to the Yocto Project 1.7 Release</title>
1718
1719 <para>
1720 This section provides migration information for moving to the
1721 Yocto Project 1.7 Release from the prior release.
1722 </para>
1723
1724 <section id='migration-1.7-changes-to-setting-qemu-packageconfig-options'>
1725 <title>Changes to Setting QEMU <filename>PACKAGECONFIG</filename> Options in <filename>local.conf</filename></title>
1726
1727 <para>
1728 The QEMU recipe now uses a number of
1729 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
1730 options to enable various optional features.
1731 The method used to set defaults for these options means that
1732 existing
1733 <filename>local.conf</filename> files will need to be be
1734 modified to append to <filename>PACKAGECONFIG</filename> for
1735 <filename>qemu-native</filename> and
1736 <filename>nativesdk-qemu</filename> instead of setting it.
1737 In other words, to enable graphical output for QEMU, you should
1738 now have these lines in <filename>local.conf</filename>:
1739 <literallayout class='monospaced'>
1740 PACKAGECONFIG_append_pn-qemu-native = " sdl"
1741 PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
1742 </literallayout>
1743 </para>
1744 </section>
1745
1746 <section id='migration-1.7-minimum-git-version'>
1747 <title>Minimum Git version</title>
1748
1749 <para>
1750 The minimum
1751 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> version required
1752 on the build host is now 1.7.8 because the
1753 <filename>--list</filename> option is now required by
1754 BitBake's Git fetcher.
1755 As always, if your host distribution does not provide a version of
1756 Git that meets this requirement, you can use the
1757 <filename>buildtools-tarball</filename> that does.
1758 See the
1759 "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
1760 section for more information.
1761 </para>
1762 </section>
1763
1764 <section id='migration-1.7-autotools-class-changes'>
1765 <title>Autotools Class Changes</title>
1766
1767 <para>
1768 The following
1769 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
1770 class changes occurred:
1771 <itemizedlist>
1772 <listitem><para><emphasis>
1773 A separate build directory is now used by default:</emphasis>
1774 The <filename>autotools</filename> class has been changed
1775 to use a directory for building
1776 (<link linkend='var-B'><filename>B</filename></link>),
1777 which is separate from the source directory
1778 (<link linkend='var-S'><filename>S</filename></link>).
1779 This is commonly referred to as
1780 <filename>B != S</filename>, or an out-of-tree build.</para>
1781 <para>If the software being built is already capable of
1782 building in a directory separate from the source, you
1783 do not need to do anything.
1784 However, if the software is not capable of being built
1785 in this manner, you will
1786 need to either patch the software so that it can build
1787 separately, or you will need to change the recipe to
1788 inherit the
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001789 <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
1790 class instead of the <filename>autotools</filename> or
1791 <filename>autotools_stage</filename> classes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001792 </para></listitem>
1793 <listitem><para><emphasis>
1794 The <filename>--foreign</filename> option is
1795 no longer passed to <filename>automake</filename> when
1796 running <filename>autoconf</filename>:</emphasis>
1797 This option tells <filename>automake</filename> that a
1798 particular software package does not follow the GNU
1799 standards and therefore should not be expected
1800 to distribute certain files such as
1801 <filename>ChangeLog</filename>,
1802 <filename>AUTHORS</filename>, and so forth.
1803 Because the majority of upstream software packages already
1804 tell <filename>automake</filename> to enable foreign mode
1805 themselves, the option is mostly superfluous.
1806 However, some recipes will need patches for this change.
1807 You can easily make the change by patching
1808 <filename>configure.ac</filename> so that it passes
1809 "foreign" to <filename>AM_INIT_AUTOMAKE()</filename>.
1810 See
1811 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2'>this commit</ulink>
1812 for an example showing how to make the patch.
1813 </para></listitem>
1814 </itemizedlist>
1815 </para>
1816 </section>
1817
1818 <section id='migration-1.7-binary-configuration-scripts-disabled'>
1819 <title>Binary Configuration Scripts Disabled</title>
1820
1821 <para>
1822 Some of the core recipes that package binary configuration scripts
1823 now disable the scripts due to the
1824 scripts previously requiring error-prone path substitution.
1825 Software that links against these libraries using these scripts
1826 should use the much more robust <filename>pkg-config</filename>
1827 instead.
1828 The list of recipes changed in this version (and their
1829 configuration scripts) is as follows:
1830 <literallayout class='monospaced'>
1831 directfb (directfb-config)
1832 freetype (freetype-config)
1833 gpgme (gpgme-config)
1834 libassuan (libassuan-config)
1835 libcroco (croco-6.0-config)
1836 libgcrypt (libgcrypt-config)
1837 libgpg-error (gpg-error-config)
1838 libksba (ksba-config)
1839 libpcap (pcap-config)
1840 libpcre (pcre-config)
1841 libpng (libpng-config, libpng16-config)
1842 libsdl (sdl-config)
1843 libusb-compat (libusb-config)
1844 libxml2 (xml2-config)
1845 libxslt (xslt-config)
1846 ncurses (ncurses-config)
1847 neon (neon-config)
1848 npth (npth-config)
1849 pth (pth-config)
1850 taglib (taglib-config)
1851 </literallayout>
1852 Additionally, support for <filename>pkg-config</filename> has been
1853 added to some recipes in the previous list in the rare cases
1854 where the upstream software package does not already provide
1855 it.
1856 </para>
1857 </section>
1858
1859 <section id='migration-1.7-glibc-replaces-eglibc'>
1860 <title><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></title>
1861
1862 <para>
1863 Because <filename>eglibc</filename> and
1864 <filename>glibc</filename> were already fairly close, this
1865 replacement should not require any significant changes to other
1866 software that links to <filename>eglibc</filename>.
1867 However, there were a number of minor changes in
1868 <filename>glibc 2.20</filename> upstream that could require
1869 patching some software (e.g. the removal of the
1870 <filename>_BSD_SOURCE</filename> feature test macro).
1871 </para>
1872
1873 <para>
1874 <filename>glibc 2.20</filename> requires version 2.6.32 or greater
1875 of the Linux kernel.
1876 Thus, older kernels will no longer be usable in conjunction with it.
1877 </para>
1878
1879 <para>
1880 For full details on the changes in <filename>glibc 2.20</filename>,
1881 see the upstream release notes
1882 <ulink url='https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html'>here</ulink>.
1883 </para>
1884 </section>
1885
1886 <section id='migration-1.7-kernel-module-autoloading'>
1887 <title>Kernel Module Autoloading</title>
1888
1889 <para>
1890 The
1891 <link linkend='var-module_autoload'><filename>module_autoload_*</filename></link>
1892 variable is now deprecated and a new
1893 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
1894 variable should be used instead.
1895 Also,
1896 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
1897 must now be used in conjunction with a new
1898 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
1899 variable.
1900 The new variables no longer require you to specify the module name
1901 as part of the variable name.
1902 This change not only simplifies usage but also allows the values
1903 of these variables to be appropriately incorporated into task
1904 signatures and thus trigger the appropriate tasks to re-execute
1905 when changed.
1906 You should replace any references to
1907 <filename>module_autoload_*</filename> with
1908 <filename>KERNEL_MODULE_AUTOLOAD</filename>, and add any modules
1909 for which <filename>module_conf_*</filename> is specified to
1910 <filename>KERNEL_MODULE_PROBECONF</filename>.
1911 </para>
1912
1913 <para>
1914 For more information, see the
1915 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
1916 and
1917 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
1918 variables.
1919 </para>
1920 </section>
1921
1922 <section id='migration-1.7-qa-check-changes'>
1923 <title>QA Check Changes</title>
1924
1925 <para>
1926 The following changes have occurred to the QA check process:
1927 <itemizedlist>
1928 <listitem><para>
1929 Additional QA checks <filename>file-rdeps</filename>
1930 and <filename>build-deps</filename> have been added in
1931 order to verify that file dependencies are satisfied
1932 (e.g. package contains a script requiring
1933 <filename>/bin/bash</filename>) and build-time dependencies
1934 are declared, respectively.
1935 For more information, please see the
1936 "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>"
1937 chapter.
1938 </para></listitem>
1939 <listitem><para>
1940 Package QA checks are now performed during a new
1941 <link linkend='ref-tasks-package_qa'><filename>do_package_qa</filename></link>
1942 task rather than being part of the
1943 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
1944 task.
1945 This allows more parallel execution.
1946 This change is unlikely to be an issue except for highly
1947 customized recipes that disable packaging tasks themselves
1948 by marking them as <filename>noexec</filename>.
1949 For those packages, you will need to disable the
1950 <filename>do_package_qa</filename> task as well.
1951 </para></listitem>
1952 <listitem><para>
1953 Files being overwritten during the
1954 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
1955 task now trigger an error instead of a warning.
1956 Recipes should not be overwriting files written to the
1957 sysroot by other recipes.
1958 If you have these types of recipes, you need to alter them
1959 so that they do not overwrite these files.</para>
1960 <para>You might now receive this error after changes in
1961 configuration or metadata resulting in orphaned files
1962 being left in the sysroot.
1963 If you do receive this error, the way to resolve the issue
1964 is to delete your
1965 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1966 or to move it out of the way and then re-start the build.
1967 Anything that has been fully built up to that point and
1968 does not need rebuilding will be restored from the shared
1969 state cache and the rest of the build will be able to
1970 proceed as normal.
1971 </para></listitem>
1972 </itemizedlist>
1973 </para>
1974 </section>
1975
1976 <section id='migration-1.7-removed-recipes'>
1977 <title>Removed Recipes</title>
1978
1979 <para>
1980 The following recipes have been removed:
1981 <itemizedlist>
1982 <listitem><para>
1983 <filename>x-load</filename>:
1984 This recipe has been superseded by
1985 U-boot SPL for all Cortex-based TI SoCs.
1986 For legacy boards, the <filename>meta-ti</filename>
1987 layer, which contains a maintained recipe, should be used
1988 instead.
1989 </para></listitem>
1990 <listitem><para>
1991 <filename>ubootchart</filename>:
1992 This recipe is obsolete.
1993 A <filename>bootchart2</filename> recipe has been added
1994 to functionally replace it.
1995 </para></listitem>
1996 <listitem><para>
1997 <filename>linux-yocto 3.4</filename>:
1998 Support for the linux-yocto 3.4 kernel has been dropped.
1999 Support for the 3.10 and 3.14 kernels remains, while
2000 support for version 3.17 has been added.
2001 </para></listitem>
2002 <listitem><para>
2003 <filename>eglibc</filename> has been removed in favor of
2004 <filename>glibc</filename>.
2005 See the
2006 "<link linkend='migration-1.7-glibc-replaces-eglibc'><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></link>"
2007 section for more information.
2008 </para></listitem>
2009 </itemizedlist>
2010 </para>
2011 </section>
2012
2013 <section id='migration-1.7-miscellaneous-changes'>
2014 <title>Miscellaneous Changes</title>
2015
2016 <para>
2017 The following miscellaneous change occurred:
2018 <itemizedlist>
2019 <listitem><para>
2020 The build history feature now writes
2021 <filename>build-id.txt</filename> instead of
2022 <filename>build-id</filename>.
2023 Additionally, <filename>build-id.txt</filename>
2024 now contains the full build header as printed by
2025 BitBake upon starting the build.
2026 You should manually remove old "build-id" files from your
2027 existing build history repositories to avoid confusion.
2028 For information on the build history feature, see the
2029 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
2030 section.
2031 </para></listitem>
2032 </itemizedlist>
2033 </para>
2034 </section>
2035</section>
2036
2037<section id='moving-to-the-yocto-project-1.8-release'>
2038 <title>Moving to the Yocto Project 1.8 Release</title>
2039
2040 <para>
2041 This section provides migration information for moving to the
2042 Yocto Project 1.8 Release from the prior release.
2043 </para>
2044
2045 <section id='migration-1.8-removed-recipes'>
2046 <title>Removed Recipes</title>
2047
2048 <para>
2049 The following recipes have been removed:
2050 <itemizedlist>
2051 <listitem><para><filename>owl-video</filename>:
2052 Functionality replaced by <filename>gst-player</filename>.
2053 </para></listitem>
2054 <listitem><para><filename>gaku</filename>:
2055 Functionality replaced by <filename>gst-player</filename>.
2056 </para></listitem>
2057 <listitem><para><filename>gnome-desktop</filename>:
2058 This recipe is now available in
2059 <filename>meta-gnome</filename> and is no longer needed.
2060 </para></listitem>
2061 <listitem><para><filename>gsettings-desktop-schemas</filename>:
2062 This recipe is now available in
2063 <filename>meta-gnome</filename> and is no longer needed.
2064 </para></listitem>
2065 <listitem><para><filename>python-argparse</filename>:
2066 The <filename>argparse</filename> module is already
2067 provided in the default Python distribution in a
2068 package named <filename>python-argparse</filename>.
2069 Consequently, the separate
2070 <filename>python-argparse</filename> recipe is no
2071 longer needed.
2072 </para></listitem>
2073 <listitem><para><filename>telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control</filename>:
2074 All these recipes have moved to
2075 <filename>meta-oe</filename> and are consequently no
2076 longer needed by any recipes in OpenEmbedded-Core.
2077 </para></listitem>
2078 <listitem><para><filename>linux-yocto_3.10</filename> and <filename>linux-yocto_3.17</filename>:
2079 Support for the linux-yocto 3.10 and 3.17 kernels has been
2080 dropped.
2081 Support for the 3.14 kernel remains, while support for
2082 3.19 kernel has been added.
2083 </para></listitem>
2084 <listitem><para><filename>poky-feed-config-opkg</filename>:
2085 This recipe has become obsolete and is no longer needed.
2086 Use <filename>distro-feed-config</filename> from
2087 <filename>meta-oe</filename> instead.
2088 </para></listitem>
2089 <listitem><para><filename>libav 0.8.x</filename>:
2090 <filename>libav 9.x</filename> is now used.
2091 </para></listitem>
2092 <listitem><para><filename>sed-native</filename>:
2093 No longer needed.
2094 A working version of <filename>sed</filename> is expected
2095 to be provided by the host distribution.
2096 </para></listitem>
2097 </itemizedlist>
2098 </para>
2099 </section>
2100
2101 <section id='migration-1.8-bluez'>
2102 <title>BlueZ 4.x / 5.x Selection</title>
2103
2104 <para>
2105 Proper built-in support for selecting BlueZ 5.x in preference
2106 to the default of 4.x now exists.
2107 To use BlueZ 5.x, simply add "bluez5" to your
2108 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
2109 value.
2110 If you had previously added append files
2111 (<filename>*.bbappend</filename>) to make this selection, you can
2112 now remove them.
2113 </para>
2114
2115 <para>
2116 Additionally, a
2117 <link linkend='ref-classes-bluetooth'><filename>bluetooth</filename></link>
2118 class has been added to make selection of the appropriate bluetooth
2119 support within a recipe a little easier.
2120 If you wish to make use of this class in a recipe, add something
2121 such as the following:
2122 <literallayout class='monospaced'>
2123 inherit bluetooth
2124 PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}
2125 PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4"
2126 PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5"
2127 </literallayout>
2128 </para>
2129 </section>
2130
2131 <section id='migration-1.8-kernel-build-changes'>
2132 <title>Kernel Build Changes</title>
2133
2134 <para>
2135 The kernel build process was changed to place the source
2136 in a common shared work area and to place build artifacts
2137 separately in the source code tree.
2138 In theory, migration paths have been provided for most common
2139 usages in kernel recipes but this might not work in all cases.
2140 In particular, users need to ensure that
2141 <filename>${S}</filename> (source files) and
2142 <filename>${B}</filename> (build artifacts) are used
2143 correctly in functions such as
2144 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2145 and
2146 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
2147 For kernel recipes that do not inherit from
2148 <filename>kernel-yocto</filename> or include
2149 <filename>linux-yocto.inc</filename>, you might wish to
2150 refer to the <filename>linux.inc</filename> file in the
2151 <filename>meta-oe</filename> layer for the kinds of changes you
2152 need to make.
2153 For reference, here is the
2154 <ulink url='http://cgit.openembedded.org/meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee'>commit</ulink>
2155 where the <filename>linux.inc</filename> file in
2156 <filename>meta-oe</filename> was updated.
2157 </para>
2158
2159 <para>
2160 Recipes that rely on the kernel source code and do not inherit
2161 the module classes might need to add explicit dependencies on
2162 the <filename>do_shared_workdir</filename> kernel task, for example:
2163 <literallayout class='monospaced'>
2164 do_configure[depends] += "virtual/kernel:do_shared_workdir"
2165 </literallayout>
2166 </para>
2167 </section>
2168
2169 <section id='migration-1.8-ssl'>
2170 <title>SSL 3.0 is Now Disabled in OpenSSL</title>
2171
2172 <para>
2173 SSL 3.0 is now disabled when building OpenSSL.
2174 Disabling SSL 3.0 avoids any lingering instances of the POODLE
2175 vulnerability.
2176 If you feel you must re-enable SSL 3.0, then you can add an
2177 append file (<filename>*.bbappend</filename>) for the
2178 <filename>openssl</filename> recipe to remove "-no-ssl3"
2179 from
2180 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>.
2181 </para>
2182 </section>
2183
2184 <section id='migration-1.8-default-sysroot-poisoning'>
2185 <title>Default Sysroot Poisoning</title>
2186
2187 <para>
2188 <filename>gcc's</filename> default sysroot and include directories
2189 are now "poisoned".
2190 In other words, the sysroot and include directories are being
2191 redirected to a non-existent location in order to catch when
2192 host directories are being used due to the correct options not
2193 being passed.
2194 This poisoning applies both to the cross-compiler used within the
2195 build and to the cross-compiler produced in the SDK.
2196 </para>
2197
2198 <para>
2199 If this change causes something in the build to fail, it almost
2200 certainly means the various compiler flags and commands are not
2201 being passed correctly to the underlying piece of software.
2202 In such cases, you need to take corrective steps.
2203 </para>
2204 </section>
2205
2206 <section id='migration-1.8-rebuild-improvements'>
2207 <title>Rebuild Improvements</title>
2208
2209 <para>
2210 Changes have been made to the
2211 <link linkend='ref-classes-base'><filename>base</filename></link>,
2212 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>,
2213 and
2214 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
2215 classes to clean out generated files when the
2216 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2217 task needs to be re-executed.
2218 </para>
2219
2220 <para>
2221 One of the improvements is to attempt to run "make clean" during
2222 the <filename>do_configure</filename> task if a
2223 <filename>Makefile</filename> exists.
2224 Some software packages do not provide a working clean target
2225 within their make files.
2226 If you have such recipes, you need to set
2227 <link linkend='var-CLEANBROKEN'><filename>CLEANBROKEN</filename></link>
2228 to "1" within the recipe, for example:
2229 <literallayout class='monospaced'>
2230 CLEANBROKEN = "1"
2231 </literallayout>
2232 </para>
2233 </section>
2234
2235 <section id='migration-1.8-qa-check-and-validation-changes'>
2236 <title>QA Check and Validation Changes</title>
2237
2238 <para>
2239 The following QA Check and Validation Changes have occurred:
2240 <itemizedlist>
2241 <listitem><para>
2242 Usage of <filename>PRINC</filename>
2243 previously triggered a warning.
2244 It now triggers an error.
2245 You should remove any remaining usage of
2246 <filename>PRINC</filename> in any recipe or append file.
2247 </para></listitem>
2248 <listitem><para>
2249 An additional QA check has been added to detect usage of
2250 <filename>${D}</filename> in
2251 <link linkend='var-FILES'><filename>FILES</filename></link>
2252 values where
2253 <link linkend='var-D'><filename>D</filename></link> values
2254 should not be used at all.
2255 The same check ensures that <filename>$D</filename> is used
2256 in
2257 <filename>pkg_preinst/pkg_postinst/pkg_prerm/pkg_postrm</filename>
2258 functions instead of <filename>${D}</filename>.
2259 </para></listitem>
2260 <listitem><para>
2261 <link linkend='var-S'><filename>S</filename></link> now
2262 needs to be set to a valid value within a recipe.
2263 If <filename>S</filename> is not set in the recipe, the
2264 directory is not automatically created.
2265 If <filename>S</filename> does not point to a directory
2266 that exists at the time the
2267 <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
2268 task finishes, a warning will be shown.
2269 </para></listitem>
2270 <listitem><para>
2271 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2272 is now validated for correct formatting of multiple
2273 licenses.
2274 If the format is invalid (e.g. multiple licenses are
2275 specified with no operators to specify how the multiple
2276 licenses interact), then a warning will be shown.
2277 </para></listitem>
2278 </itemizedlist>
2279 </para>
2280 </section>
2281
2282 <section id='migration-1.8-miscellaneous-changes'>
2283 <title>Miscellaneous Changes</title>
2284
2285 <para>
2286 The following miscellaneous changes have occurred:
2287 <itemizedlist>
2288 <listitem><para>
2289 The <filename>send-error-report</filename> script now
2290 expects a "-s" option to be specified before the server
2291 address.
2292 This assumes a server address is being specified.
2293 </para></listitem>
2294 <listitem><para>
2295 The <filename>oe-pkgdata-util</filename> script now
2296 expects a "-p" option to be specified before the
2297 <filename>pkgdata</filename> directory, which is now
2298 optional.
2299 If the <filename>pkgdata</filename> directory is not
2300 specified, the script will run BitBake to query
2301 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
2302 from the build environment.
2303 </para></listitem>
2304 </itemizedlist>
2305 </para>
2306 </section>
2307</section>
2308
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002309<section id='moving-to-the-yocto-project-2.0-release'>
2310 <title>Moving to the Yocto Project 2.0 Release</title>
2311
2312 <para>
2313 This section provides migration information for moving to the
2314 Yocto Project 2.0 Release from the prior release.
2315 </para>
2316
2317 <section id='migration-2.0-gcc-5'>
2318 <title>GCC 5</title>
2319
2320 <para>
2321 The default compiler is now GCC 5.2.
2322 This change has required fixes for compilation errors in a number
2323 of other recipes.
2324 </para>
2325
2326 <para>
2327 One important example is a fix for when the Linux kernel freezes at
2328 boot time on ARM when built with GCC 5.
2329 If you are using your own kernel recipe or source tree and
2330 building for ARM, you will likely need to apply this
2331 <ulink url='https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit?id=a077224fd35b2f7fbc93f14cf67074fc792fbac2'>patch</ulink>.
2332 The standard <filename>linux-yocto</filename> kernel source tree
2333 already has a workaround for the same issue.
2334 </para>
2335
2336 <para>
2337 For further details, see
2338 <ulink url='https://gcc.gnu.org/gcc-5/changes.html'></ulink> and
2339 the porting guide at
2340 <ulink url='https://gcc.gnu.org/gcc-5/porting_to.html'></ulink>.
2341 </para>
2342
2343 <para>
2344 Alternatively, you can switch back to GCC 4.9 or 4.8 by
2345 setting <filename>GCCVERSION</filename> in your configuration,
2346 as follows:
2347 <literallayout class='monospaced'>
2348 GCCVERSION = "4.9%"
2349 </literallayout>
2350 </para>
2351 </section>
2352
2353 <section id='migration-2.0-Gstreamer-0.10-removed'>
2354 <title>Gstreamer 0.10 Removed</title>
2355
2356 <para>
2357 Gstreamer 0.10 has been removed in favor of Gstreamer 1.x.
2358 As part of the change, recipes for Gstreamer 0.10 and related
2359 software are now located
2360 in <filename>meta-multimedia</filename>.
2361 This change results in Qt4 having Phonon and Gstreamer
2362 support in QtWebkit disabled by default.
2363 </para>
2364 </section>
2365
2366 <section id='migration-2.0-removed-recipes'>
2367 <title>Removed Recipes</title>
2368
2369 <para>
2370 The following recipes have been moved or removed:
2371 <itemizedlist>
2372 <listitem><para>
2373 <filename>bluez4</filename>: The recipe is obsolete and
2374 has been moved due to <filename>bluez5</filename>
2375 becoming fully integrated.
2376 The <filename>bluez4</filename> recipe now resides in
2377 <filename>meta-oe</filename>.
2378 </para></listitem>
2379 <listitem><para>
2380 <filename>gamin</filename>: The recipe is obsolete and
2381 has been removed.
2382 </para></listitem>
2383 <listitem><para>
2384 <filename>gnome-icon-theme</filename>: The recipe's
2385 functionally has been replaced by
2386 <filename>adwaita-icon-theme</filename>.
2387 </para></listitem>
2388 <listitem><para>
2389 Gstreamer 0.10 Recipes: Recipes for Gstreamer 0.10 have
2390 been removed in favor of the recipes for Gstreamer 1.x.
2391 </para></listitem>
2392 <listitem><para>
2393 <filename>insserv</filename>: The recipe is obsolete and
2394 has been removed.
2395 </para></listitem>
2396 <listitem><para>
2397 <filename>libunique</filename>: The recipe is no longer
2398 used and has been moved to <filename>meta-oe</filename>.
2399 </para></listitem>
2400 <listitem><para>
2401 <filename>midori</filename>: The recipe's functionally
2402 has been replaced by <filename>epiphany</filename>.
2403 </para></listitem>
2404 <listitem><para>
2405 <filename>python-gst</filename>: The recipe is obsolete
2406 and has been removed since it only contains bindings for
2407 Gstreamer 0.10.
2408 </para></listitem>
2409 <listitem><para>
2410 <filename>qt-mobility</filename>: The recipe is obsolete and
2411 has been removed since it requires
2412 <filename>Gstreamer 0.10</filename>, which has been
2413 replaced.
2414 </para></listitem>
2415 <listitem><para>
2416 <filename>subversion</filename>: All 1.6.x versions of this
2417 recipe have been removed.
2418 </para></listitem>
2419 <listitem><para>
2420 <filename>webkit-gtk</filename>: The older 1.8.3 version
2421 of this recipe has been removed in favor of
2422 <filename>webkitgtk</filename>.
2423 </para></listitem>
2424 </itemizedlist>
2425 </para>
2426 </section>
2427
2428 <section id='migration-2.0-bitbake-datastore-improvements'>
2429 <title>BitBake datastore improvements</title>
2430
2431 <para>
2432 The method by which BitBake's datastore handles overrides has
2433 changed.
2434 Overrides are now applied dynamically and
2435 <filename>bb.data.update_data()</filename> is now a no-op.
2436 Thus, <filename>bb.data.update_data()</filename> is no longer
2437 required in order to apply the correct overrides.
2438 In practice, this change is unlikely to require any changes to
2439 Metadata.
2440 However, these minor changes in behavior exist:
2441 <itemizedlist>
2442 <listitem><para>
2443 All potential overrides are now visible in the variable
2444 history as seen when you run the following:
2445 <literallayout class='monospaced'>
2446 $ bitbake -e
2447 </literallayout>
2448 </para></listitem>
2449 <listitem><para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002450 <filename>d.delVar('</filename><replaceable>VARNAME</replaceable><filename>')</filename> and
2451 <filename>d.setVar('</filename><replaceable>VARNAME</replaceable><filename>', None)</filename>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002452 result in the variable and all of its overrides being
2453 cleared out.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002454 Before the change, only the non-overridden values
2455 were cleared.
2456 </para></listitem>
2457 </itemizedlist>
2458 </para>
2459 </section>
2460
2461 <section id='migration-2.0-shell-message-function-changes'>
2462 <title>Shell Message Function Changes</title>
2463
2464 <para>
2465 The shell versions of the BitBake message functions (i.e.
2466 <filename>bbdebug</filename>, <filename>bbnote</filename>,
2467 <filename>bbwarn</filename>, <filename>bbplain</filename>,
2468 <filename>bberror</filename>, and <filename>bbfatal</filename>)
2469 are now connected through to their BitBake equivalents
2470 <filename>bb.debug()</filename>, <filename>bb.note()</filename>,
2471 <filename>bb.warn()</filename>, <filename>bb.plain()</filename>,
2472 <filename>bb.error()</filename>, and
2473 <filename>bb.fatal()</filename>, respectively.
2474 Thus, those message functions that you would expect to be printed
2475 by the BitBake UI are now actually printed.
2476 In practice, this change means two things:
2477 <itemizedlist>
2478 <listitem><para>
2479 If you now see messages on the console that you did not
2480 previously see as a result of this change, you might
2481 need to clean up the calls to
2482 <filename>bbwarn</filename>, <filename>bberror</filename>,
2483 and so forth.
2484 Or, you might want to simply remove the calls.
2485 </para></listitem>
2486 <listitem><para>
2487 The <filename>bbfatal</filename> message function now
2488 suppresses the full error log in the UI, which means any
2489 calls to <filename>bbfatal</filename> where you still
2490 wish to see the full error log should be replaced by
2491 <filename>die</filename> or
2492 <filename>bbfatal_log</filename>.
2493 </para></listitem>
2494 </itemizedlist>
2495 </para>
2496 </section>
2497
2498 <section id='migration-2.0-extra-development-debug-package-cleanup'>
2499 <title>Extra Development/Debug Package Cleanup</title>
2500
2501 <para>
2502 The following recipes have had extra
2503 <filename>dev/dbg</filename> packages removed:
2504 <itemizedlist>
2505 <listitem><para>
2506 <filename>acl</filename>
2507 </para></listitem>
2508 <listitem><para>
2509 <filename>apmd</filename>
2510 </para></listitem>
2511 <listitem><para>
2512 <filename>aspell</filename>
2513 </para></listitem>
2514 <listitem><para>
2515 <filename>attr</filename>
2516 </para></listitem>
2517 <listitem><para>
2518 <filename>augeas</filename>
2519 </para></listitem>
2520 <listitem><para>
2521 <filename>bzip2</filename>
2522 </para></listitem>
2523 <listitem><para>
2524 <filename>cogl</filename>
2525 </para></listitem>
2526 <listitem><para>
2527 <filename>curl</filename>
2528 </para></listitem>
2529 <listitem><para>
2530 <filename>elfutils</filename>
2531 </para></listitem>
2532 <listitem><para>
2533 <filename>gcc-target</filename>
2534 </para></listitem>
2535 <listitem><para>
2536 <filename>libgcc</filename>
2537 </para></listitem>
2538 <listitem><para>
2539 <filename>libtool</filename>
2540 </para></listitem>
2541 <listitem><para>
2542 <filename>libxmu</filename>
2543 </para></listitem>
2544 <listitem><para>
2545 <filename>opkg</filename>
2546 </para></listitem>
2547 <listitem><para>
2548 <filename>pciutils</filename>
2549 </para></listitem>
2550 <listitem><para>
2551 <filename>rpm</filename>
2552 </para></listitem>
2553 <listitem><para>
2554 <filename>sysfsutils</filename>
2555 </para></listitem>
2556 <listitem><para>
2557 <filename>tiff</filename>
2558 </para></listitem>
2559 <listitem><para>
2560 <filename>xz</filename>
2561 </para></listitem>
2562 </itemizedlist>
2563 All of the above recipes now conform to the standard packaging
2564 scheme where a single <filename>-dev</filename>,
2565 <filename>-dbg</filename>, and <filename>-staticdev</filename>
2566 package exists per recipe.
2567 </para>
2568 </section>
2569
2570 <section id='migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core'>
2571 <title>Recipe Maintenance Tracking Data Moved to OE-Core</title>
2572
2573 <para>
2574 Maintenance tracking data for recipes that was previously part
2575 of <filename>meta-yocto</filename> has been moved to OE-Core.
2576 The change includes <filename>package_regex.inc</filename> and
2577 <filename>distro_alias.inc</filename>, which are typically enabled
2578 when using the
2579 <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link>
2580 class.
2581 Additionally, the contents of
2582 <filename>upstream_tracking.inc</filename> has now been split out
2583 to the relevant recipes.
2584 </para>
2585 </section>
2586
2587 <section id='migration-2.0-automatic-stale-sysroot-file-cleanup'>
2588 <title>Automatic Stale Sysroot File Cleanup</title>
2589
2590 <para>
2591 Stale files from recipes that no longer exist in the current
2592 configuration are now automatically removed from
2593 sysroot as well as removed from
2594 any other place managed by shared state.
2595 This automatic cleanup means that the build system now properly
2596 handles situations such as renaming the build system side of
2597 recipes, removal of layers from
2598 <filename>bblayers.conf</filename>, and
2599 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
2600 changes.
2601 </para>
2602
2603 <para>
2604 Additionally, work directories for old versions of recipes are
2605 now pruned.
2606 If you wish to disable pruning old work directories, you can set
2607 the following variable in your configuration:
2608 <literallayout class='monospaced'>
2609 SSTATE_PRUNE_OBSOLETEWORKDIR = "0"
2610 </literallayout>
2611 </para>
2612 </section>
2613
2614 <section id='migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source'>
2615 <title><filename>linux-yocto</filename> Kernel Metadata Repository Now Split from Source</title>
2616
2617 <para>
2618 The <filename>linux-yocto</filename> tree has up to now been a
2619 combined set of kernel changes and configuration (meta) data
2620 carried in a single tree.
2621 While this format is effective at keeping kernel configuration and
2622 source modifications synchronized, it is not always obvious to
2623 developers how to manipulate the Metadata as compared to the
2624 source.
2625 </para>
2626
2627 <para>
2628 Metadata processing has now been removed from the
2629 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
2630 class and the external Metadata repository
2631 <filename>yocto-kernel-cache</filename>, which has always been used
2632 to seed the <filename>linux-yocto</filename> "meta" branch.
2633 This separate <filename>linux-yocto</filename> cache repository
2634 is now the primary location for this data.
2635 Due to this change, <filename>linux-yocto</filename> is no longer
2636 able to process combined trees.
2637 Thus, if you need to have your own combined kernel repository,
2638 you must do the split there as well and update your recipes
2639 accordingly.
2640 See the <filename>meta/recipes-kernel/linux/linux-yocto_4.1.bb</filename>
2641 recipe for an example.
2642 </para>
2643 </section>
2644
2645 <section id='migration-2.0-additional-qa-checks'>
2646 <title>Additional QA checks</title>
2647
2648 <para>
2649 The following QA checks have been added:
2650 <itemizedlist>
2651 <listitem><para>
2652 Added a "host-user-contaminated" check for ownership
2653 issues for packaged files outside of
2654 <filename>/home</filename>.
2655 The check looks for files that are incorrectly owned by the
2656 user that ran BitBake instead of owned by a valid user in
2657 the target system.
2658 </para></listitem>
2659 <listitem><para>
2660 Added an "invalid-chars" check for invalid (non-UTF8)
2661 characters in recipe metadata variable values
2662 (i.e.
2663 <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>,
2664 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>,
2665 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>,
2666 and
2667 <link linkend='var-SECTION'><filename>SECTION</filename></link>).
2668 Some package managers do not support these characters.
2669 </para></listitem>
2670 <listitem><para>
2671 Added an "invalid-packageconfig" check for any options
2672 specified in
2673 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
2674 that do not match any <filename>PACKAGECONFIG</filename>
2675 option defined for the recipe.
2676 </para></listitem>
2677 </itemizedlist>
2678 </para>
2679 </section>
2680
2681 <section id='migration-2.0-miscellaneous'>
2682 <title>Miscellaneous Changes</title>
2683
2684 <para>
2685 These additional changes exist:
2686 <itemizedlist>
2687 <listitem><para>
2688 <filename>gtk-update-icon-cache</filename> has been
2689 renamed to <filename>gtk-icon-utils</filename>.
2690 </para></listitem>
2691 <listitem><para>
2692 The <filename>tools-profile</filename>
2693 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
2694 item as well as its corresponding packagegroup and
2695 <filename>packagegroup-core-tools-profile</filename> no
2696 longer bring in <filename>oprofile</filename>.
2697 Bringing in <filename>oprofile</filename> was originally
2698 added to aid compilation on resource-constrained
2699 targets.
2700 However, this aid has not been widely used and is not
2701 likely to be used going forward due to the more powerful
2702 target platforms and the existence of better
2703 cross-compilation tools.
2704 </para></listitem>
2705 <listitem><para>
2706 The
2707 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
2708 variable's default value now specifies
2709 <filename>ext4</filename> instead of
2710 <filename>ext3</filename>.
2711 </para></listitem>
2712 <listitem><para>
2713 All support for the <filename>PRINC</filename>
2714 variable has been removed.
2715 </para></listitem>
2716 <listitem><para>
2717 The <filename>packagegroup-core-full-cmdline</filename>
2718 packagegroup no longer brings in
2719 <filename>lighttpd</filename> due to the fact that
2720 bringing in <filename>lighttpd</filename> is not really in
2721 line with the packagegroup's purpose, which is to add full
2722 versions of command-line tools that by default are
2723 provided by <filename>busybox</filename>.
2724 </para></listitem>
2725 </itemizedlist>
2726 </para>
2727 </section>
2728</section>
2729
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002730<section id='moving-to-the-yocto-project-2.1-release'>
2731 <title>Moving to the Yocto Project 2.1 Release</title>
2732
2733 <para>
2734 This section provides migration information for moving to the
2735 Yocto Project 2.1 Release from the prior release.
2736 </para>
2737
2738 <section id='migration-2.1-variable-expansion-in-python-functions'>
2739 <title>Variable Expansion in Python Functions</title>
2740
2741 <para>
2742 Variable expressions, such as
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002743 <filename>${</filename><replaceable>VARNAME</replaceable><filename>}</filename>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002744 no longer expand automatically within Python functions.
2745 Suppressing expansion was done to allow Python functions to
2746 construct shell scripts or other code for situations in which you
2747 do not want such expressions expanded.
2748 For any existing code that relies on these expansions, you need to
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002749 change the expansions to expand the value of individual
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002750 variables through <filename>d.getVar()</filename>.
2751 To alternatively expand more complex expressions,
2752 use <filename>d.expand()</filename>.
2753 </para>
2754 </section>
2755
2756 <section id='migration-2.1-overrides-must-now-be-lower-case'>
2757 <title>Overrides Must Now be Lower-Case</title>
2758
2759 <para>
2760 The convention for overrides has always been for them to be
2761 lower-case characters.
2762 This practice is now a requirement as BitBake's datastore now
2763 assumes lower-case characters in order to give a slight performance
2764 boost during parsing.
2765 In practical terms, this requirement means that anything that ends
2766 up in
2767 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
2768 must now appear in lower-case characters (e.g. values for
2769 <filename>MACHINE</filename>, <filename>TARGET_ARCH</filename>,
2770 <filename>DISTRO</filename>, and also recipe names if
2771 <filename>_pn-</filename><replaceable>recipename</replaceable>
2772 overrides are to be effective).
2773 </para>
2774 </section>
2775
2776 <section id='migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory'>
2777 <title>Expand Parameter to <filename>getVar()</filename> and
2778 <filename>getVarFlag()</filename> is Now Mandatory</title>
2779
2780 <para>
2781 The expand parameter to <filename>getVar()</filename> and
2782 <filename>getVarFlag()</filename> previously defaulted to
2783 False if not specified.
2784 Now, however, no default exists so one must be specified.
2785 You must change any <filename>getVar()</filename> calls that
2786 do not specify the final expand parameter to calls that do specify
2787 the parameter.
2788 You can run the following <filename>sed</filename> command at the
2789 base of a layer to make this change:
2790 <literallayout class='monospaced'>
2791 sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
2792 sed -e 's:\(\.getVarFlag([^,()]*, [^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
2793 </literallayout>
2794 <note>
2795 The reason for this change is that it prepares the way for
2796 changing the default to True in a future Yocto Project release.
2797 This future change is a much more sensible default than False.
2798 However, the change needs to be made gradually as a sudden
2799 change of the default would potentially cause side-effects
2800 that would be difficult to detect.
2801 </note>
2802 </para>
2803 </section>
2804
2805 <section id='migration-2.1-makefile-environment-changes'>
2806 <title>Makefile Environment Changes</title>
2807
2808 <para>
2809 <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link>
2810 now defaults to "" instead of "-e MAKEFLAGS=".
2811 Setting <filename>EXTRA_OEMAKE</filename> to "-e MAKEFLAGS=" by
2812 default was a historical accident that has required many classes
2813 (e.g. <filename>autotools</filename>, <filename>module</filename>)
2814 and recipes to override this default in order to work with
2815 sensible build systems.
2816 When upgrading to the release, you must edit any recipe that
2817 relies upon this old default by either setting
2818 <filename>EXTRA_OEMAKE</filename> back to "-e MAKEFLAGS=" or by
2819 explicitly setting any required variable value overrides using
2820 <filename>EXTRA_OEMAKE</filename>, which is typically only needed
2821 when a Makefile sets a default value for a variable that is
2822 inappropriate for cross-compilation using the "=" operator rather
2823 than the "?=" operator.
2824 </para>
2825 </section>
2826
2827 <section id='migration-2.1-libexecdir-reverted-to-prefix-libexec'>
2828 <title><filename>libexecdir</filename> Reverted to <filename>${prefix}/libexec</filename></title>
2829
2830 <para>
2831 The use of <filename>${libdir}/${BPN}</filename> as
2832 <filename>libexecdir</filename> is different as compared to all
2833 other mainstream distributions, which either uses
2834 <filename>${prefix}/libexec</filename> or
2835 <filename>${libdir}</filename>.
2836 The use is also contrary to the GNU Coding Standards
2837 (i.e. <ulink url='https://www.gnu.org/prep/standards/html_node/Directory-Variables.html'></ulink>)
2838 that suggest <filename>${prefix}/libexec</filename> and also
2839 notes that any package-specific nesting should be done by the
2840 package itself.
2841 Finally, having <filename>libexecdir</filename> change between
2842 recipes makes it very difficult for different recipes to invoke
2843 binaries that have been installed into
2844 <filename>libexecdir</filename>.
2845 The Filesystem Hierarchy Standard
2846 (i.e. <ulink url='http://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html'></ulink>)
2847 now recognizes the use of <filename>${prefix}/libexec/</filename>,
2848 giving distributions the choice between
2849 <filename>${prefix}/lib</filename> or
2850 <filename>${prefix}/libexec</filename> without breaking FHS.
2851 </para>
2852 </section>
2853
2854 <section id='migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files'>
2855 <title><filename>ac_cv_sizeof_off_t</filename> is No Longer Cached in Site Files</title>
2856
2857 <para>
2858 For recipes inheriting the
2859 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2860 class, <filename>ac_cv_sizeof_off_t</filename> is no longer cached
2861 in the site files for <filename>autoconf</filename>.
2862 The reason for this change is because the
2863 <filename>ac_cv_sizeof_off_t</filename> value is not necessarily
2864 static per architecture as was previously assumed.
2865 Rather, the value changes based on whether large file support is
2866 enabled.
2867 For most software that uses <filename>autoconf</filename>, this
2868 change should not be a problem.
2869 However, if you have a recipe that bypasses the standard
2870 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2871 task from the <filename>autotools</filename> class and the software
2872 the recipe is building uses a very old version of
2873 <filename>autoconf</filename>, the recipe might be incapable of
2874 determining the correct size of <filename>off_t</filename> during
2875 <filename>do_configure</filename>.
2876 </para>
2877
2878 <para>
2879 The best course of action is to patch the software as necessary
2880 to allow the default implementation from the
2881 <filename>autotools</filename> class to work such that
2882 <filename>autoreconf</filename> succeeds and produces a working
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002883 configure script, and to remove the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002884 overridden <filename>do_configure</filename> task such that the
2885 default implementation does get used.
2886 </para>
2887 </section>
2888
2889 <section id='migration-2.1-image-generation-split-out-from-filesystem-generation'>
2890 <title>Image Generation is Now Split Out from Filesystem Generation</title>
2891
2892 <para>
2893 Previously, for image recipes the
2894 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
2895 task assembled the filesystem and then from that filesystem
2896 generated images.
2897 With this Yocto Project release, image generation is split into
2898 separate
2899 <link linkend='ref-tasks-image'><filename>do_image_*</filename></link>
2900 tasks for clarity both in operation and in the code.
2901 </para>
2902
2903 <para>
2904 For most cases, this change does not present any problems.
2905 However, if you have made customizations that directly modify the
2906 <filename>do_rootfs</filename> task or that mention
2907 <filename>do_rootfs</filename>, you might need to update those
2908 changes.
2909 In particular, if you had added any tasks after
2910 <filename>do_rootfs</filename>, you should make edits so that
2911 those tasks are after the
2912 <link linkend='ref-tasks-image-complete'><filename>do_image_complete</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002913 task rather than after <filename>do_rootfs</filename>
2914 so that the your added tasks
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002915 run at the correct time.
2916 </para>
2917
2918 <para>
2919 A minor part of this restructuring is that the post-processing
2920 definitions and functions have been moved from the
2921 <link linkend='ref-classes-image'><filename>image</filename></link>
2922 class to the
2923 <link linkend='ref-classes-rootfs*'><filename>rootfs-postcommands</filename></link>
2924 class.
2925 Functionally, however, they remain unchanged.
2926 </para>
2927 </section>
2928
2929 <section id='migration-2.1-removed-recipes'>
2930 <title>Removed Recipes</title>
2931
2932 <para>
2933 The following recipes have been removed in the 2.1 release:
2934 <itemizedlist>
2935 <listitem><para><filename>gcc</filename> version 4.8:
2936 Versions 4.9 and 5.3 remain.
2937 </para></listitem>
2938 <listitem><para><filename>qt4</filename>:
2939 All support for Qt 4.x has been moved out to a separate
2940 <filename>meta-qt4</filename> layer because Qt 4 is no
2941 longer supported upstream.
2942 </para></listitem>
2943 <listitem><para><filename>x11vnc</filename>:
2944 Moved to the <filename>meta-oe</filename> layer.
2945 </para></listitem>
2946 <listitem><para><filename>linux-yocto-3.14</filename>:
2947 No longer supported.
2948 </para></listitem>
2949 <listitem><para><filename>linux-yocto-3.19</filename>:
2950 No longer supported.
2951 </para></listitem>
2952 <listitem><para><filename>libjpeg</filename>:
2953 Replaced by the <filename>libjpeg-turbo</filename> recipe.
2954 </para></listitem>
2955 <listitem><para><filename>pth</filename>:
2956 Became obsolete.
2957 </para></listitem>
2958 <listitem><para><filename>liboil</filename>:
2959 Recipe is no longer needed and has been moved to the
2960 <filename>meta-multimedia</filename> layer.
2961 </para></listitem>
2962 <listitem><para><filename>gtk-theme-torturer</filename>:
2963 Recipe is no longer needed and has been moved to the
2964 <filename>meta-gnome</filename> layer.
2965 </para></listitem>
2966 <listitem><para><filename>gnome-mime-data</filename>:
2967 Recipe is no longer needed and has been moved to the
2968 <filename>meta-gnome</filename> layer.
2969 </para></listitem>
2970 <listitem><para><filename>udev</filename>:
2971 Replaced by the <filename>eudev</filename> recipe for
2972 compatibility when using <filename>sysvinit</filename>
2973 with newer kernels.
2974 </para></listitem>
2975 <listitem><para><filename>python-pygtk</filename>:
2976 Recipe became obsolete.
2977 </para></listitem>
2978 <listitem><para><filename>adt-installer</filename>:
2979 Recipe became obsolete.
2980 See the
2981 "<link linkend='migration-2.1-adt-removed'>ADT Removed</link>"
2982 section for more information.
2983 </para></listitem>
2984 </itemizedlist>
2985 </para>
2986 </section>
2987
2988 <section id='migration-2.1-class-changes'>
2989 <title>Class Changes</title>
2990
2991 <para>
2992 The following classes have changed:
2993 <itemizedlist>
2994 <listitem><para><filename>autotools_stage</filename>:
2995 Removed because the
2996 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2997 class now provides its functionality.
2998 Recipes that inherited from
2999 <filename>autotools_stage</filename> should now inherit
3000 from <filename>autotools</filename> instead.
3001 </para></listitem>
3002 <listitem><para><filename>boot-directdisk</filename>:
3003 Merged into the
3004 <link linkend='ref-classes-image-vm'><filename>image-vm</filename></link>
3005 class.
3006 The <filename>boot-directdisk</filename> class was rarely
3007 directly used.
3008 Consequently, this change should not cause any issues.
3009 </para></listitem>
3010 <listitem><para><filename>bootimg</filename>:
3011 Merged into the
3012 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
3013 class.
3014 The <filename>bootimg</filename> class was rarely
3015 directly used.
3016 Consequently, this change should not cause any issues.
3017 </para></listitem>
3018 <listitem><para><filename>packageinfo</filename>:
3019 Removed due to its limited use by the Hob UI, which has
3020 itself been removed.
3021 </para></listitem>
3022 </itemizedlist>
3023 </para>
3024 </section>
3025
3026 <section id='migration-2.1-build-system-ui-changes'>
3027 <title>Build System User Interface Changes</title>
3028
3029 <para>
3030 The following changes have been made to the build system user
3031 interface:
3032 <itemizedlist>
3033 <listitem><para><emphasis>Hob GTK+-based UI</emphasis>:
3034 Removed because it is unmaintained and based on the
3035 outdated GTK+ 2 library.
3036 The Toaster web-based UI is much more capable and is
3037 actively maintained.
3038 See the
3039 "<ulink url='&YOCTO_DOCS_TOAST_URL;#using-the-toaster-web-interface'>Using the Toaster Web Interface</ulink>"
3040 section in the Yocto Project Toaster User Manual for more
3041 information on this interface.
3042 </para></listitem>
3043 <listitem><para><emphasis>"puccho" BitBake UI</emphasis>:
3044 Removed because is unmaintained and no longer useful.
3045 </para></listitem>
3046 </itemizedlist>
3047 </para>
3048 </section>
3049
3050 <section id='migration-2.1-adt-removed'>
3051 <title>ADT Removed</title>
3052
3053 <para>
3054 The Application Development Toolkit (ADT) has been removed
3055 because its functionality almost completely overlapped with the
3056 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-using-the-standard-sdk'>standard SDK</ulink>
3057 and the
3058 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>.
3059 For information on these SDKs and how to build and use them, see the
3060 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003061 <note>
3062 The Yocto Project Eclipse IDE Plug-in is still supported and
3063 is not affected by this change.
3064 </note>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003065 </para>
3066 </section>
3067
3068 <section id='migration-2.1-poky-reference-distribution-changes'>
3069 <title>Poky Reference Distribution Changes</title>
3070
3071 <para>
3072 The following changes have been made for the Poky distribution:
3073 <itemizedlist>
3074 <listitem><para>
3075 The <filename>meta-yocto</filename> layer has been renamed
3076 to <filename>meta-poky</filename> to better match its
3077 purpose, which is to provide the Poky reference
3078 distribution.
3079 The <filename>meta-yocto-bsp</filename> layer retains its
3080 original name since it provides reference machines for
3081 the Yocto Project and it is otherwise unrelated to Poky.
3082 References to <filename>meta-yocto</filename> in your
3083 <filename>conf/bblayers.conf</filename> should
3084 automatically be updated, so you should not need to change
3085 anything unless you are relying on this naming elsewhere.
3086 </para></listitem>
3087 <listitem><para>
3088 The
3089 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
3090 class is now enabled by default in Poky.
3091 This class attempts to isolate the build system from the
3092 host distribution's C library and makes re-use of native
3093 shared state artifacts across different host distributions
3094 practical.
3095 With this class enabled, a tarball containing a pre-built
3096 C library is downloaded at the start of the build.</para>
3097
3098 <para>The <filename>uninative</filename> class is enabled
3099 through the
3100 <filename>meta/conf/distro/include/yocto-uninative.inc</filename>
3101 file, which for those not using the Poky distribution, can
3102 include to easily enable the same functionality.</para>
3103
3104 <para>Alternatively, if you wish to build your own
3105 <filename>uninative</filename> tarball, you can do so by
3106 building the <filename>uninative-tarball</filename> recipe,
3107 making it available to your build machines
3108 (e.g. over HTTP/HTTPS) and setting a similar configuration
3109 as the one set by <filename>yocto-uninative.inc</filename>.
3110 </para></listitem>
3111 <listitem><para>
3112 Static library generation, for most cases, is now disabled
3113 by default in the Poky distribution.
3114 Disabling this generation saves some build time as well
3115 as the size used for build output artifacts.</para>
3116
3117 <para>Disabling this library generation is accomplished
3118 through a
3119 <filename>meta/conf/distro/include/no-static-libs.inc</filename>,
3120 which for those not using the Poky distribution can
3121 easily include to enable the same functionality.</para>
3122
3123 <para>Any recipe that needs to opt-out of having the
3124 "--disable-static" option specified on the configure
3125 command line either because it is not a supported option
3126 for the configure script or because static libraries are
3127 needed should set the following variable:
3128 <literallayout class='monospaced'>
3129 DISABLE_STATIC = ""
3130 </literallayout>
3131 </para></listitem>
3132 <listitem><para>
3133 The separate <filename>poky-tiny</filename> distribution
3134 now uses the musl C library instead of a heavily pared
3135 down <filename>glibc</filename>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003136 Using musl results in a smaller
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003137 distribution and facilitates much greater maintainability
3138 because musl is designed to have a small footprint.</para>
3139
3140 <para>If you have used <filename>poky-tiny</filename> and
3141 have customized the <filename>glibc</filename>
3142 configuration you will need to redo those customizations
3143 with musl when upgrading to the new release.
3144 </para></listitem>
3145 </itemizedlist>
3146 </para>
3147 </section>
3148
3149 <section id='migration-2.1-packaging-changes'>
3150 <title>Packaging Changes</title>
3151
3152 <para>
3153 The following changes have been made to packaging:
3154 <itemizedlist>
3155 <listitem><para>
3156 The <filename>runuser</filename> and
3157 <filename>mountpoint</filename> binaries, which were
3158 previously in the main <filename>util-linux</filename>
3159 package, have been split out into the
3160 <filename>util-linux-runuser</filename> and
3161 <filename>util-linux-mountpoint</filename> packages,
3162 respectively.
3163 </para></listitem>
3164 <listitem><para>
3165 The <filename>python-elementtree</filename> package has
3166 been merged into the <filename>python-xml</filename>
3167 package.
3168 </para></listitem>
3169 </itemizedlist>
3170 </para>
3171 </section>
3172
3173 <section id='migration-2.1-tuning-file-changes'>
3174 <title>Tuning File Changes</title>
3175
3176 <para>
3177 The following changes have been made to the tuning files:
3178 <itemizedlist>
3179 <listitem><para>
3180 The "no-thumb-interwork" tuning feature has been dropped
3181 from the ARM tune include files.
3182 Because interworking is required for ARM EABI, attempting
3183 to disable it through a tuning feature no longer makes
3184 sense.
3185 <note>
3186 Support for ARM OABI was deprecated in gcc 4.7.
3187 </note>
3188 </para></listitem>
3189 <listitem><para>
3190 The <filename>tune-cortexm*.inc</filename> and
3191 <filename>tune-cortexr4.inc</filename> files have been
3192 removed because they are poorly tested.
3193 Until the OpenEmbedded build system officially gains
3194 support for CPUs without an MMU, these tuning files would
3195 probably be better maintained in a separate layer
3196 if needed.
3197 </para></listitem>
3198 </itemizedlist>
3199 </para>
3200 </section>
3201
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003202 <section id='migration-2.1-supporting-gobject-introspection'>
3203 <title>Supporting GObject Introspection</title>
3204
3205 <para>
3206 This release supports generation of GLib Introspective
3207 Repository (GIR) files through GObject introspection, which is
3208 the standard mechanism for accessing GObject-based software from
3209 runtime environments.
3210 You can enable, disable, and test the generation of this data.
3211 See the
3212 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-gobject-introspection-support'>Enabling GObject Introspection Support</ulink>"
3213 section for more information.
3214 </para>
3215 </section>
3216
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003217 <section id='migration-2.1-miscellaneous-changes'>
3218 <title>Miscellaneous Changes</title>
3219
3220 <para>
3221 These additional changes exist:
3222 <itemizedlist>
3223 <listitem><para>
3224 The minimum Git version has been increased to 1.8.3.1.
3225 If your host distribution does not provide a sufficiently
3226 recent version, you can install the buildtools, which
3227 will provide it.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003228 See the
3229 "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
3230 section for more information on the buildtools tarball.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003231 </para></listitem>
3232 <listitem><para>
3233 The buggy and incomplete support for the RPM version 4
3234 package manager has been removed.
3235 The well-tested and maintained support for RPM version 5
3236 remains.
3237 </para></listitem>
3238 <listitem><para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003239 Previously, the following list of packages were removed
3240 if package-management was not in
3241 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>,
3242 regardless of any dependencies:
3243 <literallayout class='monospaced'>
3244 update-rc.d
3245 base-passwd
3246 shadow
3247 update-alternatives
3248 run-postinsts
3249 </literallayout>
3250 With the Yocto Project 2.1 release, these packages are only
3251 removed if "read-only-rootfs" is in
3252 <filename>IMAGE_FEATURES</filename>, since they might
3253 still be needed for a read-write image even in the absence
3254 of a package manager (e.g. if users need to be added,
3255 modified, or removed at runtime).
3256 </para></listitem>
3257 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003258 The
3259 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'><filename>devtool modify</filename></ulink>
3260 command now defaults to extracting the source since that
3261 is most commonly expected.
3262 The "-x" or "--extract" options are now no-ops.
3263 If you wish to provide your own existing source tree, you
3264 will now need to specify either the "-n" or
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003265 "--no-extract" options when running
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003266 <filename>devtool modify</filename>.
3267 </para></listitem>
3268 <listitem><para>
3269 If the formfactor for a machine is either not supplied
3270 or does not specify whether a keyboard is attached, then
3271 the default is to assume a keyboard is attached rather
3272 than assume no keyboard.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003273 This change primarily affects the Sato UI.
3274 </para></listitem>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003275 <listitem><para>
3276 The <filename>.debug</filename> directory packaging is
3277 now automatic.
3278 If your recipe builds software that installs binaries into
3279 directories other than the standard ones, you no longer
3280 need to take care of setting
3281 <filename>FILES_${PN}-dbg</filename> to pick up the
3282 resulting <filename>.debug</filename> directories as these
3283 directories are automatically found and added.
3284 </para></listitem>
3285 <listitem><para>
3286 Inaccurate disk and CPU percentage data has been dropped
3287 from <filename>buildstats</filename> output.
3288 This data has been replaced with
3289 <filename>getrusage()</filename> data and corrected IO
3290 statistics.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003291 You will probably need to update any custom code that reads
3292 the <filename>buildstats</filename> data.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003293 </para></listitem>
3294 <listitem><para>
3295 The
3296 <filename>meta/conf/distro/include/package_regex.inc</filename>
3297 is now deprecated.
3298 The contents of this file have been moved to individual
3299 recipes.
3300 <note><title>Tip</title>
3301 Because this file will likely be removed in a future
3302 Yocto Project release, it is suggested that you remove
3303 any references to the file that might be in your
3304 configuration.
3305 </note>
3306 </para></listitem>
3307 <listitem><para>
3308 The <filename>v86d/uvesafb</filename> has been removed from
3309 the <filename>genericx86</filename> and
3310 <filename>genericx86-64</filename> reference machines,
3311 which are provided by the
3312 <filename>meta-yocto-bsp</filename> layer.
3313 Most modern x86 boards do not rely on this file and it only
3314 adds kernel error messages during startup.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003315 If you do still need to support
3316 <filename>uvesafb</filename>, you can
3317 simply add <filename>v86d</filename> to your image.
3318 </para></listitem>
3319 <listitem><para>
3320 Build sysroot paths are now removed from debug symbol
3321 files.
3322 Removing these paths means that remote GDB using an
3323 unstripped build system sysroot will no longer work
3324 (although this was never documented to work).
3325 The supported method to accomplish something similar is
3326 to set <filename>IMAGE_GEN_DEBUGFS</filename> to "1",
3327 which will generate a companion debug image
3328 containing unstripped binaries and associated debug
3329 sources alongside the image.
3330 </para></listitem>
3331 </itemizedlist>
3332 </para>
3333 </section>
3334</section>
3335
3336<section id='moving-to-the-yocto-project-2.2-release'>
3337 <title>Moving to the Yocto Project 2.2 Release</title>
3338
3339 <para>
3340 This section provides migration information for moving to the
3341 Yocto Project 2.2 Release from the prior release.
3342 </para>
3343
3344 <section id='migration-2.2-minimum-kernel-version'>
3345 <title>Minimum Kernel Version</title>
3346
3347 <para>
3348 The minimum kernel version for the target system and for SDK
3349 is now 3.2.0, due to the upgrade
3350 to <filename>glibc 2.24</filename>.
3351 Specifically, for AArch64-based targets the version is
3352 3.14.
3353 For Nios II-based targets, the minimum kernel version is 3.19.
3354 <note>
3355 For x86 and x86_64, you can reset
3356 <link linkend='var-OLDEST_KERNEL'><filename>OLDEST_KERNEL</filename></link>
3357 to anything down to 2.6.32 if desired.
3358 </note>
3359 </para>
3360 </section>
3361
3362 <section id='migration-2.2-staging-directories-in-sysroot-simplified'>
3363 <title>Staging Directories in Sysroot Has Been Simplified</title>
3364
3365 <para>
3366 The way directories are staged in sysroot has been simplified and
3367 introduces the new
3368 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>,
3369 <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>,
3370 and
3371 <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link>.
3372 See the
3373 <ulink url='http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html'>v2 patch series on the OE-Core Mailing List</ulink>
3374 for additional information.
3375 </para>
3376 </section>
3377
3378 <section id='migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled'>
3379 <title>Removal of Old Images and Other Files in <filename>tmp/deploy</filename> Now Enabled</title>
3380
3381 <para>
3382 Removal of old images and other files in
3383 <filename>tmp/deploy/</filename> is now enabled by default due
3384 to a new staging method used for those files.
3385 As a result of this change, the
3386 <filename>RM_OLD_IMAGE</filename> variable is now redundant.
3387 </para>
3388 </section>
3389
3390 <section id='migration-2.2-python-changes'>
3391 <title>Python Changes</title>
3392
3393 <para>
3394 The following changes for Python occurred:
3395 </para>
3396
3397 <section id='migration-2.2-bitbake-now-requires-python-3.4'>
3398 <title>BitBake Now Requires Python 3.4+</title>
3399
3400 <para>
3401 BitBake requires Python 3.4 or greater.
3402 </para>
3403 </section>
3404
3405 <section id='migration-2.2-utf-8-locale-required-on-build-host'>
3406 <title>UTF-8 Locale Required on Build Host</title>
3407
3408 <para>
3409 A UTF-8 locale is required on the build host due to Python 3.
3410 Since C.UTF-8 is not a standard, the default is en_US.UTF-8.
3411 </para>
3412 </section>
3413
3414 <section id='migration-2.2-metadata-now-must-use-python-3-syntax'>
3415 <title>Metadata Must Now Use Python 3 Syntax</title>
3416
3417 <para>
3418 The metadata is now required to use Python 3 syntax.
3419 For help preparing metadata, see any of the many Python 3 porting
3420 guides available.
3421 Alternatively, you can reference the conversion commits for Bitbake
3422 and you can use OE-Core as a guide for changes.
3423 Following are particular areas of interest:
3424 <literallayout class='monospaced'>
3425 * subprocess command-line pipes needing locale decoding
3426 * the syntax for octal values changed
3427 * the <filename>iter*()</filename> functions changed name
3428 * iterators now return views, not lists
3429 * changed names for Python modules
3430 </literallayout>
3431 </para>
3432 </section>
3433
3434 <section id='migration-2.2-target-python-recipes-switched-to-python-3'>
3435 <title>Target Python Recipes Switched to Python 3</title>
3436
3437 <para>
3438 Most target Python recipes have now been switched to Python 3.
3439 Unfortunately, systems using RPM as a package manager and
3440 providing online package-manager support through SMART still
3441 require Python 2.
3442 <note>
3443 Python 2 and recipes that use it can still be built for the
3444 target as with previous versions.
3445 </note>
3446 </para>
3447 </section>
3448
3449 <section id='migration-2.2-buildtools-tarball-includes-python-3'>
3450 <title><filename>buildtools-tarball</filename> Includes Python 3</title>
3451
3452 <para>
3453 <filename>buildtools-tarball</filename> now includes Python 3.
3454 </para>
3455 </section>
3456 </section>
3457
3458 <section id='migration-2.2-uclibc-replaced-by-musl'>
3459 <title>uClibc Replaced by musl</title>
3460
3461 <para>
3462 uClibc has been removed in favor of musl.
3463 Musl has matured, is better maintained, and is compatible with a
3464 wider range of applications as compared to uClibc.
3465 </para>
3466 </section>
3467
3468 <section id='migration-2.2-B-no-longer-default-working-directory-for-tasks'>
3469 <title><filename>${B}</filename> No Longer Default Working Directory for Tasks</title>
3470
3471 <para>
3472 <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>
3473 is no longer the default working directory for tasks.
3474 Consequently, any custom tasks you define now need to either
3475 have the
3476 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>dirs</filename></ulink><filename>]</filename> flag set, or the task needs to change into the
3477 appropriate working directory manually (e.g using
3478 <filename>cd</filename> for a shell task).
3479 <note>
3480 The preferred method is to use the
3481 <filename>[dirs]</filename> flag.
3482 </note>
3483 </para>
3484 </section>
3485
3486 <section id='migration-2.2-runqemu-ported-to-python'>
3487 <title><filename>runqemu</filename> Ported to Python</title>
3488
3489 <para>
3490 <filename>runqemu</filename> has been ported to Python and has
3491 changed behavior in some cases.
Brad Bishop37a0e4d2017-12-04 01:01:44 -05003492 Previous usage patterns continue to be supported.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003493 </para>
3494
3495 <para>
3496 The new <filename>runqemu</filename> is a Python script.
3497 Machine knowledge is no longer hardcoded into
3498 <filename>runqemu</filename>.
3499 You can choose to use the <filename>qemuboot</filename>
3500 configuration file to define the BSP's own arguments and to make
3501 it bootable with <filename>runqemu</filename>.
3502 If you use a configuration file, use the following form:
3503 <literallayout class='monospaced'>
3504 <replaceable>image-name</replaceable>-<replaceable>machine</replaceable>.qemuboot.conf
3505 </literallayout>
3506 The configuration file enables fine-grained tuning of options
3507 passed to QEMU without the <filename>runqemu</filename> script
3508 hard-coding any knowledge about different machines.
3509 Using a configuration file is particularly convenient when trying
3510 to use QEMU with machines other than the
3511 <filename>qemu*</filename> machines in OE-Core.
3512 The <filename>qemuboot.conf</filename> file is generated by the
3513 <filename>qemuboot</filename>
3514 class when the root filesystem is being build (i.e.
3515 build rootfs).
3516 QEMU boot arguments can be set in BSP's configuration file and
3517 the <filename>qemuboot</filename> class will save them to
3518 <filename>qemuboot.conf</filename>.
3519 </para>
3520
3521
3522 <para>
3523 If you want to use <filename>runqemu</filename> without a
3524 configuration file, use the following command form:
3525 <literallayout class='monospaced'>
3526 $ runqemu <replaceable>machine</replaceable> <replaceable>rootfs</replaceable> <replaceable>kernel</replaceable> [<replaceable>options</replaceable>]
3527 </literallayout>
3528 Supported <replaceable>machines</replaceable> are as follows:
3529 <literallayout class='monospaced'>
3530 qemuarm
3531 qemuarm64
3532 qemux86
3533 qemux86-64
3534 qemuppc
3535 qemumips
3536 qemumips64
3537 qemumipsel
3538 qemumips64el
3539 </literallayout>
3540 Consider the following example, which uses the
3541 <filename>qemux86-64</filename> machine,
3542 provides a root filesystem, provides an image, and uses
3543 the <filename>nographic</filename> option:
3544 <literallayout class='monospaced'>
3545$ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
3546 </literallayout>
3547 </para>
3548
3549 <para>
3550 Following is a list of variables that can be set in configuration
3551 files such as <filename>bsp.conf</filename> to enable the BSP
3552 to be booted by <filename>runqemu</filename>:
3553 <note>
3554 "QB" means "QEMU Boot".
3555 </note>
3556 <literallayout class='monospaced'>
3557 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
3558 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
3559 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
3560 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
3561 QB_MEM: Memory (e.g. "-m 512")
3562 QB_MACHINE: QEMU machine (e.g. "-machine virt")
3563 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
3564 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
3565 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
3566 option (e.g. "console=ttyS0 console=tty")
3567 QB_DTB: QEMU dtb name
3568 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
3569 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
3570 when QB_AUDIO_DRV is set.
3571 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
3572 QB_TAP_OPT: Network option for 'tap' mode (e.g.
3573 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
3574 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
3575 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
3576 QB_ROOTFS_OPT: Used as rootfs (e.g.
3577 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
3578 runqemu will replace "@ROOTFS@" with the one which is used, such as
3579 core-image-minimal-qemuarm64.ext4.
3580 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
3581 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
3582 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
3583 runqemu will replace "@PORT@" with the port number which is used.
3584 </literallayout>
3585 </para>
3586
3587 <para>
3588 To use <filename>runqemu</filename>, set
3589 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
3590 as follows and run <filename>runqemu</filename>:
3591 <note>
3592 For command-line syntax, use
3593 <filename>runqemu help</filename>.
3594 </note>
3595 <literallayout class='monospaced'>
3596 IMAGE_CLASSES += "qemuboot"
3597 </literallayout>
3598 </para>
3599 </section>
3600
3601 <section id='migration-2.2-default-linker-hash-style-changed'>
3602 <title>Default Linker Hash Style Changed</title>
3603
3604 <para>
3605 The default linker hash style for <filename>gcc-cross</filename>
3606 is now "sysv" in order to catch recipes that are building software
3607 without using the OpenEmbedded
3608 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>.
3609 This change could result in seeing some "No GNU_HASH in the elf
3610 binary" QA issues when building such recipes.
3611 You need to fix these recipes so that they use the expected
3612 <filename>LDFLAGS</filename>.
3613 Depending on how the software is built, the build system used by
3614 the software (e.g. a Makefile) might need to be patched.
3615 However, sometimes making this fix is as simple as adding the
3616 following to the recipe:
3617 <literallayout class='monospaced'>
3618 TARGET_CC_ARCH += "${LDFLAGS}"
3619 </literallayout>
3620 </para>
3621 </section>
3622
Brad Bishop37a0e4d2017-12-04 01:01:44 -05003623 <section id='migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype'>
3624 <title><filename>KERNEL_IMAGE_BASE_NAME</filename> no Longer Uses <filename>KERNEL_IMAGETYPE</filename></title>
3625
3626 <para>
3627 The
3628 <link linkend='var-KERNEL_IMAGE_BASE_NAME'><filename>KERNEL_IMAGE_BASE_NAME</filename></link>
3629 variable no longer uses the
3630 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
3631 variable to create the image's base name.
3632 Because the OpenEmbedded build system can now build multiple kernel
3633 image types, this part of the kernel image base name as been
3634 removed leaving only the following:
3635 <literallayout class='monospaced'>
3636 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}
3637 </literallayout>
3638 If you have recipes or classes that use
3639 <filename>KERNEL_IMAGE_BASE_NAME</filename> directly, you might
3640 need to update the references to ensure they continue to work.
3641 </para>
3642 </section>
3643
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003644 <section id='migration-2.2-bitbake-changes'>
3645 <title>BitBake Changes</title>
3646
3647 <para>
3648 The following changes took place for BitBake:
3649 <itemizedlist>
3650 <listitem><para>
3651 The "goggle" UI and standalone image-writer tool have
3652 been removed as they both require GTK+ 2.0 and
3653 were not being maintained.
3654 </para></listitem>
3655 <listitem><para>
3656 The Perforce fetcher now supports
3657 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
3658 for specifying the source revision to use, be it
3659 <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename>,
3660 changelist number, p4date, or label, in preference to
3661 separate
3662 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
3663 parameters to specify these.
3664 This change is more in-line with how the other fetchers
3665 work for source control systems.
3666 Recipes that fetch from Perforce will need to be updated
3667 to use <filename>SRCREV</filename> in place of specifying
3668 the source revision within
3669 <filename>SRC_URI</filename>.
3670 </para></listitem>
3671 <listitem><para>
3672 Some of BitBake's internal code structures for accessing
3673 the recipe cache needed to be changed to support the new
3674 multi-configuration functionality.
3675 These changes will affect external tools that use BitBake's
3676 tinfoil module.
3677 For information on these changes, see the changes made to
3678 the scripts supplied with OpenEmbedded-Core:
3679 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee'>1</ulink>
3680 and
3681 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67'>2</ulink>.
3682 </para></listitem>
3683 <listitem><para>
3684 The task management code has been rewritten to avoid using
3685 ID indirection in order to improve performance.
3686 This change is unlikely to cause any problems for most
3687 users.
3688 However, the setscene verification function as pointed to
3689 by <filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
3690 needed to change signature.
3691 Consequently, a new variable named
3692 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></ulink>
3693 has been added allowing multiple versions of BitBake
3694 to work with suitably written metadata, which includes
3695 OpenEmbedded-Core and Poky.
3696 Anyone with custom BitBake task scheduler code might also
3697 need to update the code to handle the new structure.
3698 </para></listitem>
3699 </itemizedlist>
3700 </para>
3701 </section>
3702
3703 <section id='migration-2.2-swabber-has-been-removed'>
3704 <title>Swabber has Been Removed</title>
3705
3706 <para>
3707 Swabber, a tool that was intended to detect host contamination in
3708 the build process, has been removed, as it has been unmaintained
3709 and unused for some time and was never particularly effective.
3710 The OpenEmbedded build system has since incorporated a number of
3711 mechanisms including enhanced QA checks that mean that there is
3712 less of a need for such a tool.
3713 </para>
3714 </section>
3715
3716 <section id='migration-2.2-removed-recipes'>
3717 <title>Removed Recipes</title>
3718
3719 <para>
3720 The following recipes have been removed:
3721 <itemizedlist>
3722 <listitem><para>
3723 <filename>augeas</filename>:
3724 No longer needed and has been moved to
3725 <filename>meta-oe</filename>.
3726 </para></listitem>
3727 <listitem><para>
3728 <filename>directfb</filename>:
3729 Unmaintained and has been moved to
3730 <filename>meta-oe</filename>.
3731 </para></listitem>
3732 <listitem><para>
3733 <filename>gcc</filename>:
3734 Removed 4.9 version.
3735 Versions 5.4 and 6.2 are still present.
3736 </para></listitem>
3737 <listitem><para>
3738 <filename>gnome-doc-utils</filename>:
3739 No longer needed.
3740 </para></listitem>
3741 <listitem><para>
3742 <filename>gtk-doc-stub</filename>:
3743 Replaced by <filename>gtk-doc</filename>.
3744 </para></listitem>
3745 <listitem><para>
3746 <filename>gtk-engines</filename>:
3747 No longer needed and has been moved to
3748 <filename>meta-gnome</filename>.
3749 </para></listitem>
3750 <listitem><para>
3751 <filename>gtk-sato-engine</filename>:
3752 Became obsolete.
3753 </para></listitem>
3754 <listitem><para>
3755 <filename>libglade</filename>:
3756 No longer needed and has been moved to
3757 <filename>meta-oe</filename>.
3758 </para></listitem>
3759 <listitem><para>
3760 <filename>libmad</filename>:
3761 Unmaintained and functionally replaced by
3762 <filename>libmpg123</filename>.
3763 <filename>libmad</filename> has been moved to
3764 <filename>meta-oe</filename>.
3765 </para></listitem>
3766 <listitem><para>
3767 <filename>libowl</filename>:
3768 Became obsolete.
3769 </para></listitem>
3770 <listitem><para>
3771 <filename>libxsettings-client</filename>:
3772 No longer needed.
3773 </para></listitem>
3774 <listitem><para>
3775 <filename>oh-puzzles</filename>:
3776 Functionally replaced by
3777 <filename>puzzles</filename>.
3778 </para></listitem>
3779 <listitem><para>
3780 <filename>oprofileui</filename>:
3781 Became obsolete.
3782 OProfile has been largely supplanted by perf.
3783 </para></listitem>
3784 <listitem><para>
3785 <filename>packagegroup-core-directfb.bb</filename>:
3786 Removed.
3787 </para></listitem>
3788 <listitem><para>
3789 <filename>core-image-directfb.bb</filename>:
3790 Removed.
3791 </para></listitem>
3792 <listitem><para>
3793 <filename>pointercal</filename>:
3794 No longer needed and has been moved to
3795 <filename>meta-oe</filename>.
3796 </para></listitem>
3797 <listitem><para>
3798 <filename>python-imaging</filename>:
3799 No longer needed and moved to
3800 <filename>meta-python</filename>
3801 </para></listitem>
3802 <listitem><para>
3803 <filename>python-pyrex</filename>:
3804 No longer needed and moved to
3805 <filename>meta-python</filename>.
3806 </para></listitem>
3807 <listitem><para>
3808 <filename>sato-icon-theme</filename>:
3809 Became obsolete.
3810 </para></listitem>
3811 <listitem><para>
3812 <filename>swabber-native</filename>:
3813 Swabber has been removed.
3814 See the
3815 <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>.
3816 </para></listitem>
3817 <listitem><para>
3818 <filename>tslib</filename>:
3819 No longer needed and has been moved to
3820 <filename>meta-oe</filename>.
3821 </para></listitem>
3822 <listitem><para>
3823 <filename>uclibc</filename>:
3824 Removed in favor of musl.
3825 </para></listitem>
3826 <listitem><para>
3827 <filename>xtscal</filename>:
3828 No longer needed and moved to
3829 <filename>meta-oe</filename>
3830 </para></listitem>
3831 </itemizedlist>
3832 </para>
3833 </section>
3834
3835 <section id='migration-2.2-removed-classes'>
3836 <title>Removed Classes</title>
3837
3838 <para>
3839 The following classes have been removed:
3840 <itemizedlist>
3841 <listitem><para>
3842 <filename>distutils-native-base</filename>:
3843 No longer needed.
3844 </para></listitem>
3845 <listitem><para>
3846 <filename>distutils3-native-base</filename>:
3847 No longer needed.
3848 </para></listitem>
3849 <listitem><para>
3850 <filename>sdl</filename>:
3851 Only set
3852 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
3853 and
3854 <link linkend='var-SECTION'><filename>SECTION</filename></link>,
3855 which are better set within the recipe instead.
3856 </para></listitem>
3857 <listitem><para>
3858 <filename>sip</filename>:
3859 Mostly unused.
3860 </para></listitem>
3861 <listitem><para>
3862 <filename>swabber</filename>:
3863 See the
3864 <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>.
3865 </para></listitem>
3866 </itemizedlist>
3867 </para>
3868 </section>
3869
3870 <section id='migration-2.2-minor-packaging-changes'>
3871 <title>Minor Packaging Changes</title>
3872
3873 <para>
3874 The following minor packaging changes have occurred:
3875 <itemizedlist>
3876 <listitem><para>
3877 <filename>grub</filename>:
3878 Split <filename>grub-editenv</filename> into its own
3879 package.
3880 </para></listitem>
3881 <listitem><para>
3882 <filename>systemd</filename>:
3883 Split container and vm related units into a new package,
3884 systemd-container.
3885 </para></listitem>
3886 <listitem><para>
3887 <filename>util-linux</filename>:
3888 Moved <filename>prlimit</filename> to a separate
3889 <filename>util-linux-prlimit</filename> package.
3890 </para></listitem>
3891 </itemizedlist>
3892 </para>
3893 </section>
3894
3895 <section id='migration-2.2-miscellaneous-changes'>
3896 <title>Miscellaneous Changes</title>
3897
3898 <para>
3899 The following miscellaneous changes have occurred:
3900 <itemizedlist>
3901 <listitem><para>
3902 <filename>package_regex.inc</filename>:
3903 Removed because the definitions
3904 <filename>package_regex.inc</filename> previously contained
3905 have been moved to their respective recipes.
3906 </para></listitem>
3907 <listitem><para>
3908 Both <filename>devtool add</filename> and
3909 <filename>recipetool create</filename> now use a fixed
3910 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
3911 by default when fetching from a Git repository.
3912 You can override this in either case to use
3913 <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename>
3914 instead by using the <filename>-a</filename> or
3915 <filename>&dash;&dash;autorev</filename> command-line
3916 option
3917 </para></listitem>
3918 <listitem><para>
3919 <filename>distcc</filename>:
3920 GTK+ UI is now disabled by default.
3921 </para></listitem>
3922 <listitem><para>
3923 <filename>packagegroup-core-tools-testapps</filename>:
3924 Removed Piglit.
3925 </para></listitem>
3926 <listitem><para>
3927 <filename>image.bbclass</filename>:
3928 Renamed COMPRESS(ION) to CONVERSION.
3929 This change means that
3930 <filename>COMPRESSIONTYPES</filename>,
3931 <filename>COMPRESS_DEPENDS</filename> and
3932 <filename>COMPRESS_CMD</filename> are deprecated in favor
3933 of <filename>CONVERSIONTYPES</filename>,
3934 <filename>CONVERSION_DEPENDS</filename> and
3935 <filename>CONVERSION_CMD</filename>.
3936 The <filename>COMPRESS*</filename> variable names will
3937 still work in the 2.2 release but metadata that does not
3938 need to be backwards-compatible should be changed to
3939 use the new names as the <filename>COMPRESS*</filename>
3940 ones will be removed in a future release.
3941 </para></listitem>
3942 <listitem><para>
3943 <filename>gtk-doc</filename>:
3944 A full version of <filename>gtk-doc</filename> is now
3945 made available.
3946 However, some old software might not be capable of using
3947 the current version of <filename>gtk-doc</filename>
3948 to build documentation.
3949 You need to change recipes that build such software so that
3950 they explicitly disable building documentation with
3951 <filename>gtk-doc</filename>.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003952 </para></listitem>
3953 </itemizedlist>
3954 </para>
3955 </section>
3956</section>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003957
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003958</chapter>
3959<!--
3960vim: expandtab tw=80 ts=4
3961-->