blob: c648d8d4422b8e9a4d0ca337f383a94b8efc389f [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
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500254 <link linkend='metadata'>Metadata</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500255 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
Brad Bishop316dfdd2018-06-25 12:45:53 -0400296 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500297 </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
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500441 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500442 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>"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400445 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500446 </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
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500824 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500825 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>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400869 The value of <filename>IMAGE_FEATURES</filename> is now
870 validated to ensure invalid feature items are not added.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500871 Some users mistakenly add package names to this variable
872 instead of using
873 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
874 in order to have the package added to the image, which does
875 not work.
876 This change is intended to catch those kinds of situations.
877 Valid <filename>IMAGE_FEATURES</filename> are drawn from
878 <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
879 definitions,
880 <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link>
881 and a new "validitems" varflag on
882 <filename>IMAGE_FEATURES</filename>.
883 The "validitems" varflag change allows additional features
884 to be added if they are not provided using the previous
885 two mechanisms.
886 </para></listitem>
887 <listitem><para>
888 The previously deprecated "apps-console-core"
889 <filename>IMAGE_FEATURES</filename> item is no longer
890 supported.
891 Add "splash" to <filename>IMAGE_FEATURES</filename> if you
892 wish to have the splash screen enabled, since this is
893 all that apps-console-core was doing.</para></listitem>
894 </itemizedlist>
895 </para>
896 </section>
897
898 <section id='migration-1.5-run'>
899 <title><filename>/run</filename></title>
900
901 <para>
902 The <filename>/run</filename> directory from the Filesystem
903 Hierarchy Standard 3.0 has been introduced.
904 You can find some of the implications for this change
905 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873'>here</ulink>.
906 The change also means that recipes that install files to
907 <filename>/var/run</filename> must be changed.
908 You can find a guide on how to make these changes
909 <ulink url='http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530'>here</ulink>.
910 </para>
911 </section>
912
913 <section id='migration-1.5-removal-of-package-manager-database-within-image-recipes'>
914 <title>Removal of Package Manager Database Within Image Recipes</title>
915
916 <para>
917 The image <filename>core-image-minimal</filename> no longer adds
918 <filename>remove_packaging_data_files</filename> to
919 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
920 This addition is now handled automatically when "package-management"
921 is not in
922 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
923 If you have custom image recipes that make this addition,
924 you should remove the lines, as they are not needed and might
925 interfere with correct operation of postinstall scripts.
926 </para>
927 </section>
928
929 <section id='migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time'>
930 <title>Images Now Rebuild Only on Changes Instead of Every Time</title>
931
932 <para>
933 The
934 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
935 and other related image
936 construction tasks are no longer marked as "nostamp".
937 Consequently, they will only be re-executed when their inputs have
938 changed.
939 Previous versions of the OpenEmbedded build system always rebuilt
940 the image when requested rather when necessary.
941 </para>
942 </section>
943
944 <section id='migration-1.5-task-recipes'>
945 <title>Task Recipes</title>
946
947 <para>
948 The previously deprecated <filename>task.bbclass</filename> has
949 now been dropped.
950 For recipes that previously inherited from this class, you should
951 rename them from <filename>task-*</filename> to
952 <filename>packagegroup-*</filename> and inherit packagegroup
953 instead.
954 </para>
955
956 <para>
957 For more information, see the
958 "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>"
959 section.
960 </para>
961 </section>
962
963 <section id='migration-1.5-busybox'>
964 <title>BusyBox</title>
965
966 <para>
967 By default, we now split BusyBox into two binaries:
968 one that is suid root for those components that need it, and
969 another for the rest of the components.
970 Splitting BusyBox allows for optimization that eliminates the
971 <filename>tinylogin</filename> recipe as recommended by upstream.
972 You can disable this split by setting
973 <link linkend='var-BUSYBOX_SPLIT_SUID'><filename>BUSYBOX_SPLIT_SUID</filename></link>
974 to "0".
975 </para>
976 </section>
977
978 <section id='migration-1.5-automated-image-testing'>
979 <title>Automated Image Testing</title>
980
981 <para>
982 A new automated image testing framework has been added
983 through the
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500984 <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500985 class.
986 This framework replaces the older
987 <filename>imagetest-qemu</filename> framework.
988 </para>
989
990 <para>
991 You can learn more about performing automated image tests in the
992 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500993 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500994 </para>
995 </section>
996
997 <section id='migration-1.5-build-history'>
998 <title>Build History</title>
999
1000 <para>
1001 Following are changes to Build History:
1002 <itemizedlist>
1003 <listitem><para>
1004 Installed package sizes:
1005 <filename>installed-package-sizes.txt</filename> for an
1006 image now records the size of the files installed by each
1007 package instead of the size of each compressed package
1008 archive file.</para></listitem>
1009 <listitem><para>
1010 The dependency graphs (<filename>depends*.dot</filename>)
1011 now use the actual package names instead of replacing
1012 dashes, dots and plus signs with underscores.
1013 </para></listitem>
1014 <listitem><para>
1015 The <filename>buildhistory-diff</filename> and
1016 <filename>buildhistory-collect-srcrevs</filename>
1017 utilities have improved command-line handling.
1018 Use the <filename>--help</filename> option for
1019 each utility for more information on the new syntax.
1020 </para></listitem>
1021 </itemizedlist>
1022 For more information on Build History, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04001023 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
1024 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001025 </para>
1026 </section>
1027
1028 <section id='migration-1.5-udev'>
1029 <title><filename>udev</filename></title>
1030
1031 <para>
1032 Following are changes to <filename>udev</filename>:
1033 <itemizedlist>
1034 <listitem><para>
1035 <filename>udev</filename> no longer brings in
1036 <filename>udev-extraconf</filename> automatically
1037 through
1038 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1039 since this was originally intended to be optional.
1040 If you need the extra rules, then add
1041 <filename>udev-extraconf</filename> to your image.
1042 </para></listitem>
1043 <listitem><para>
1044 <filename>udev</filename> no longer brings in
1045 <filename>pciutils-ids</filename> or
1046 <filename>usbutils-ids</filename> through
1047 <filename>RRECOMMENDS</filename>.
1048 These are not needed by <filename>udev</filename> itself
1049 and removing them saves around 350KB.
1050 </para></listitem>
1051 </itemizedlist>
1052 </para>
1053 </section>
1054
1055 <section id='migration-1.5-removed-renamed-recipes'>
1056 <title>Removed and Renamed Recipes</title>
1057
1058 <itemizedlist>
1059 <listitem><para>
1060 The <filename>linux-yocto</filename> 3.2 kernel has been
1061 removed.</para></listitem>
1062 <listitem><para>
1063 <filename>libtool-nativesdk</filename> has been renamed to
1064 <filename>nativesdk-libtool</filename>.</para></listitem>
1065 <listitem><para>
1066 <filename>tinylogin</filename> has been removed.
1067 It has been replaced by a suid portion of Busybox.
1068 See the
1069 "<link linkend='migration-1.5-busybox'>BusyBox</link>" section
1070 for more information.</para></listitem>
1071 <listitem><para>
1072 <filename>external-python-tarball</filename> has been renamed
1073 to <filename>buildtools-tarball</filename>.
1074 </para></listitem>
1075 <listitem><para>
1076 <filename>web-webkit</filename> has been removed.
1077 It has been functionally replaced by
1078 <filename>midori</filename>.</para></listitem>
1079 <listitem><para>
1080 <filename>imake</filename> has been removed.
1081 It is no longer needed by any other recipe.
1082 </para></listitem>
1083 <listitem><para>
1084 <filename>transfig-native</filename> has been removed.
1085 It is no longer needed by any other recipe.
1086 </para></listitem>
1087 <listitem><para>
1088 <filename>anjuta-remote-run</filename> has been removed.
1089 Anjuta IDE integration has not been officially supported for
1090 several releases.</para></listitem>
1091 </itemizedlist>
1092 </section>
1093
1094 <section id='migration-1.5-other-changes'>
1095 <title>Other Changes</title>
1096
1097 <para>
1098 Following is a list of short entries describing other changes:
1099 <itemizedlist>
1100 <listitem><para>
1101 <filename>run-postinsts</filename>: Make this generic.
1102 </para></listitem>
1103 <listitem><para>
1104 <filename>base-files</filename>: Remove the unnecessary
1105 <filename>media/</filename><replaceable>xxx</replaceable> directories.
1106 </para></listitem>
1107 <listitem><para>
1108 <filename>alsa-state</filename>: Provide an empty
1109 <filename>asound.conf</filename> by default.
1110 </para></listitem>
1111 <listitem><para>
1112 <filename>classes/image</filename>: Ensure
1113 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1114 supports pre-renamed package names.</para></listitem>
1115 <listitem><para>
1116 <filename>classes/rootfs_rpm</filename>: Implement
Brad Bishop316dfdd2018-06-25 12:45:53 -04001117 <filename>BAD_RECOMMENDATIONS</filename> for RPM.
1118 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001119 <listitem><para>
1120 <filename>systemd</filename>: Remove
1121 <filename>systemd_unitdir</filename> if
1122 <filename>systemd</filename> is not in
1123 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1124 </para></listitem>
1125 <listitem><para>
1126 <filename>systemd</filename>: Remove
1127 <filename>init.d</filename> dir if
1128 <filename>systemd</filename> unit file is present and
1129 <filename>sysvinit</filename> is not a distro feature.
1130 </para></listitem>
1131 <listitem><para>
1132 <filename>libpam</filename>: Deny all services for the
1133 <filename>OTHER</filename> entries.
1134 </para></listitem>
1135 <listitem><para>
1136 <filename>image.bbclass</filename>: Move
1137 <filename>runtime_mapping_rename</filename> to avoid
1138 conflict with <filename>multilib</filename>.
1139 See
1140 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993'><filename>YOCTO #4993</filename></ulink>
1141 in Bugzilla for more information.
1142 </para></listitem>
1143 <listitem><para>
1144 <filename>linux-dtb</filename>: Use kernel build system
1145 to generate the <filename>dtb</filename> files.
1146 </para></listitem>
1147 <listitem><para>
1148 <filename>kern-tools</filename>: Switch from guilt to
1149 new <filename>kgit-s2q</filename> tool.
1150 </para></listitem>
1151 </itemizedlist>
1152 </para>
1153 </section>
1154</section>
1155
1156<section id='moving-to-the-yocto-project-1.6-release'>
1157 <title>Moving to the Yocto Project 1.6 Release</title>
1158
1159 <para>
1160 This section provides migration information for moving to the
1161 Yocto Project 1.6 Release from the prior release.
1162 </para>
1163
1164
1165 <section id='migration-1.6-archiver-class'>
1166 <title><filename>archiver</filename> Class</title>
1167
1168 <para>
1169 The
1170 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
1171 class has been rewritten and its configuration has been simplified.
1172 For more details on the source archiver, see the
1173 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001174 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001175 </para>
1176 </section>
1177
1178 <section id='migration-1.6-packaging-changes'>
1179 <title>Packaging Changes</title>
1180
1181 <para>
1182 The following packaging changes have been made:
1183 <itemizedlist>
1184 <listitem><para>
1185 The <filename>binutils</filename> recipe no longer produces
1186 a <filename>binutils-symlinks</filename> package.
1187 <filename>update-alternatives</filename> is now used to
1188 handle the preferred <filename>binutils</filename>
1189 variant on the target instead.
1190 </para></listitem>
1191 <listitem><para>
1192 The tc (traffic control) utilities have been split out of
1193 the main <filename>iproute2</filename> package and put
1194 into the <filename>iproute2-tc</filename> package.
1195 </para></listitem>
1196 <listitem><para>
1197 The <filename>gtk-engines</filename> schemas have been
1198 moved to a dedicated
1199 <filename>gtk-engines-schemas</filename> package.
1200 </para></listitem>
1201 <listitem><para>
1202 The <filename>armv7a</filename> with thumb package
1203 architecture suffix has changed.
1204 The suffix for these packages with the thumb
1205 optimization enabled is "t2" as it should be.
1206 Use of this suffix was not the case in the 1.5 release.
1207 Architecture names will change within package feeds as a
1208 result.
1209 </para></listitem>
1210 </itemizedlist>
1211 </para>
1212 </section>
1213
1214 <section id='migration-1.6-bitbake'>
1215 <title>BitBake</title>
1216
1217 <para>
1218 The following changes have been made to
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001219 <link linkend='bitbake-term'>BitBake</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001220 </para>
1221
1222 <section id='migration-1.6-matching-branch-requirement-for-git-fetching'>
1223 <title>Matching Branch Requirement for Git Fetching</title>
1224
1225 <para>
1226 When fetching source from a Git repository using
1227 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
1228 BitBake will now validate the
1229 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
1230 value against the branch.
1231 You can specify the branch using the following form:
1232 <literallayout class='monospaced'>
1233 SRC_URI = "git://server.name/repository;branch=<replaceable>branchname</replaceable>"
1234 </literallayout>
1235 If you do not specify a branch, BitBake looks
1236 in the default "master" branch.
1237 </para>
1238
1239 <para>
1240 Alternatively, if you need to bypass this check (e.g.
1241 if you are fetching a revision corresponding to a tag that
1242 is not on any branch), you can add ";nobranch=1" to
1243 the end of the URL within <filename>SRC_URI</filename>.
1244 </para>
1245 </section>
1246
1247 <section id='migration-1.6-bitbake-deps'>
1248 <title>Python Definition substitutions</title>
1249
1250 <para>
1251 BitBake had some previously deprecated Python definitions
1252 within its <filename>bb</filename> module removed.
1253 You should use their sub-module counterparts instead:
1254 <itemizedlist>
1255 <listitem><para><filename>bb.MalformedUrl</filename>:
1256 Use <filename>bb.fetch.MalformedUrl</filename>.
1257 </para></listitem>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001258 <listitem><para><filename>bb.encodeurl</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001259 Use <filename>bb.fetch.encodeurl</filename>.
1260 </para></listitem>
1261 <listitem><para><filename>bb.decodeurl</filename>:
1262 Use <filename>bb.fetch.decodeurl</filename>
1263 </para></listitem>
1264 <listitem><para><filename>bb.mkdirhier</filename>:
1265 Use <filename>bb.utils.mkdirhier</filename>.
1266 </para></listitem>
1267 <listitem><para><filename>bb.movefile</filename>:
1268 Use <filename>bb.utils.movefile</filename>.
1269 </para></listitem>
1270 <listitem><para><filename>bb.copyfile</filename>:
1271 Use <filename>bb.utils.copyfile</filename>.
1272 </para></listitem>
1273 <listitem><para><filename>bb.which</filename>:
1274 Use <filename>bb.utils.which</filename>.
1275 </para></listitem>
1276 <listitem><para><filename>bb.vercmp_string</filename>:
1277 Use <filename>bb.utils.vercmp_string</filename>.
1278 </para></listitem>
1279 <listitem><para><filename>bb.vercmp</filename>:
1280 Use <filename>bb.utils.vercmp</filename>.
1281 </para></listitem>
1282 </itemizedlist>
1283 </para>
1284 </section>
1285
1286 <section id='migration-1.6-bitbake-fetcher'>
1287 <title>SVK Fetcher</title>
1288
1289 <para>
1290 The SVK fetcher has been removed from BitBake.
1291 </para>
1292 </section>
1293
1294 <section id='migration-1.6-bitbake-console-output'>
1295 <title>Console Output Error Redirection</title>
1296
1297 <para>
1298 The BitBake console UI will now output errors to
1299 <filename>stderr</filename> instead of
1300 <filename>stdout</filename>.
1301 Consequently, if you are piping or redirecting the output of
1302 <filename>bitbake</filename> to somewhere else, and you wish
1303 to retain the errors, you will need to add
1304 <filename>2>&amp;1</filename> (or something similar) to the
1305 end of your <filename>bitbake</filename> command line.
1306 </para>
1307 </section>
1308
1309 <section id='migration-1.6-task-taskname-overrides'>
1310 <title><filename>task-</filename><replaceable>taskname</replaceable> Overrides</title>
1311
1312 <para>
1313 <filename>task-</filename><replaceable>taskname</replaceable> overrides have been
1314 adjusted so that tasks whose names contain underscores have the
1315 underscores replaced by hyphens for the override so that they
1316 now function properly.
1317 For example, the task override for
1318 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
1319 is <filename>task-populate-sdk</filename>.
1320 </para>
1321 </section>
1322 </section>
1323
1324 <section id='migration-1.6-variable-changes'>
1325 <title>Changes to Variables</title>
1326
1327 <para>
1328 The following variables have changed.
1329 For information on the OpenEmbedded build system variables, see the
1330 "<link linkend='ref-variables-glos'>Variables Glossary</link>" Chapter.
1331 </para>
1332
1333 <section id='migration-1.6-variable-changes-TMPDIR'>
1334 <title><filename>TMPDIR</filename></title>
1335
1336 <para>
1337 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1338 can no longer be on an NFS mount.
1339 NFS does not offer full POSIX locking and inode consistency
1340 and can cause unexpected issues if used to store
1341 <filename>TMPDIR</filename>.
1342 </para>
1343
1344 <para>
1345 The check for this occurs on startup.
1346 If <filename>TMPDIR</filename> is detected on an NFS mount,
1347 an error occurs.
1348 </para>
1349 </section>
1350
1351 <section id='migration-1.6-variable-changes-PRINC'>
1352 <title><filename>PRINC</filename></title>
1353
1354 <para>
1355 The <filename>PRINC</filename>
1356 variable has been deprecated and triggers a warning if
1357 detected during a build.
1358 For
1359 <link linkend='var-PR'><filename>PR</filename></link>
1360 increments on changes, use the PR service instead.
1361 You can find out more about this service in the
1362 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001363 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001364 </para>
1365 </section>
1366
1367 <section id='migration-1.6-variable-changes-IMAGE_TYPES'>
1368 <title><filename>IMAGE_TYPES</filename></title>
1369
1370 <para>
1371 The "sum.jffs2" option for
1372 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>
1373 has been replaced by the "jffs2.sum" option, which fits the
1374 processing order.
1375 </para>
1376 </section>
1377
1378 <section id='migration-1.6-variable-changes-COPY_LIC_MANIFEST'>
1379 <title><filename>COPY_LIC_MANIFEST</filename></title>
1380
1381 <para>
1382 The
1383 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1384 variable must
1385 now be set to "1" rather than any value in order to enable
1386 it.
1387 </para>
1388 </section>
1389
1390 <section id='migration-1.6-variable-changes-COPY_LIC_DIRS'>
1391 <title><filename>COPY_LIC_DIRS</filename></title>
1392
1393 <para>
1394 The
1395 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
1396 variable must
1397 now be set to "1" rather than any value in order to enable
1398 it.
1399 </para>
1400 </section>
1401
1402 <section id='migration-1.6-variable-changes-PACKAGE_GROUP'>
1403 <title><filename>PACKAGE_GROUP</filename></title>
1404
1405 <para>
1406 The
1407 <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
1408 variable has been renamed to
1409 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>
1410 to more accurately reflect its purpose.
1411 You can still use <filename>PACKAGE_GROUP</filename> but
1412 the OpenEmbedded build system produces a warning message when
1413 it encounters the variable.
1414 </para>
1415 </section>
1416
1417 <section id='migration-1.6-variable-changes-variable-entry-behavior'>
1418 <title>Preprocess and Post Process Command Variable Behavior</title>
1419
1420 <para>
1421 The following variables now expect a semicolon separated
1422 list of functions to call and not arbitrary shell commands:
1423 <literallayout class='monospaced'>
1424 <link linkend='var-ROOTFS_PREPROCESS_COMMAND'>ROOTFS_PREPROCESS_COMMAND</link>
1425 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'>ROOTFS_POSTPROCESS_COMMAND</link>
1426 <link linkend='var-SDK_POSTPROCESS_COMMAND'>SDK_POSTPROCESS_COMMAND</link>
1427 <link linkend='var-POPULATE_SDK_POST_TARGET_COMMAND'>POPULATE_SDK_POST_TARGET_COMMAND</link>
1428 <link linkend='var-POPULATE_SDK_POST_HOST_COMMAND'>POPULATE_SDK_POST_HOST_COMMAND</link>
1429 <link linkend='var-IMAGE_POSTPROCESS_COMMAND'>IMAGE_POSTPROCESS_COMMAND</link>
1430 <link linkend='var-IMAGE_PREPROCESS_COMMAND'>IMAGE_PREPROCESS_COMMAND</link>
1431 <link linkend='var-ROOTFS_POSTUNINSTALL_COMMAND'>ROOTFS_POSTUNINSTALL_COMMAND</link>
1432 <link linkend='var-ROOTFS_POSTINSTALL_COMMAND'>ROOTFS_POSTINSTALL_COMMAND</link>
1433 </literallayout>
1434 For migration purposes, you can simply wrap shell commands in
1435 a shell function and then call the function.
1436 Here is an example:
1437 <literallayout class='monospaced'>
1438 my_postprocess_function() {
1439 echo "hello" > ${IMAGE_ROOTFS}/hello.txt
1440 }
1441 ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "
1442 </literallayout>
1443 </para>
1444 </section>
1445 </section>
1446
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001447 <section id='migration-1.6-package-test-ptest'>
1448 <title>Package Test (ptest)</title>
1449
1450 <para>
1451 Package Tests (ptest) are built but not installed by default.
1452 For information on using Package Tests, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04001453 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages with ptest</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001454 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001455 For information on the <filename>ptest</filename> class, see the
1456 "<link linkend='ref-classes-ptest'><filename>ptest.bbclass</filename></link>"
1457 section.
1458 </para>
1459 </section>
1460
1461 <section id='migration-1.6-build-changes'>
1462 <title>Build Changes</title>
1463
1464 <para>
1465 Separate build and source directories have been enabled
1466 by default for selected recipes where it is known to work
1467 (a whitelist) and for all recipes that inherit the
1468 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
1469 class.
1470 In future releases the
1471 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
1472 class will enable a separate build directory by default as
1473 well.
1474 Recipes building Autotools-based
1475 software that fails to build with a separate build directory
1476 should be changed to inherit from the
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001477 <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
1478 class instead of the <filename>autotools</filename> or
1479 <filename>autotools_stage</filename>classes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001480 </para>
1481 </section>
1482
1483 <section id='migration-1.6-building-qemu-native'>
1484 <title><filename>qemu-native</filename></title>
1485
1486 <para>
1487 <filename>qemu-native</filename> now builds without
1488 SDL-based graphical output support by default.
1489 The following additional lines are needed in your
1490 <filename>local.conf</filename> to enable it:
1491 <literallayout class='monospaced'>
1492 PACKAGECONFIG_pn-qemu-native = "sdl"
1493 ASSUME_PROVIDED += "libsdl-native"
1494 </literallayout>
1495 <note>
1496 The default <filename>local.conf</filename>
1497 contains these statements.
1498 Consequently, if you are building a headless system and using
1499 a default <filename>local.conf</filename> file, you will need
1500 comment these two lines out.
1501 </note>
1502 </para>
1503 </section>
1504
1505 <section id='migration-1.6-core-image-basic'>
1506 <title><filename>core-image-basic</filename></title>
1507
1508 <para>
1509 <filename>core-image-basic</filename> has been renamed to
1510 <filename>core-image-full-cmdline</filename>.
1511 </para>
1512
1513 <para>
1514 In addition to <filename>core-image-basic</filename> being renamed,
1515 <filename>packagegroup-core-basic</filename> has been renamed to
1516 <filename>packagegroup-core-full-cmdline</filename> to match.
1517 </para>
1518 </section>
1519
1520 <section id='migration-1.6-licensing'>
1521 <title>Licensing</title>
1522
1523 <para>
1524 The top-level <filename>LICENSE</filename> file has been changed
1525 to better describe the license of the various components of
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001526 <link linkend='oe-core'>OE-Core</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001527 However, the licensing itself remains unchanged.
1528 </para>
1529
1530 <para>
1531 Normally, this change would not cause any side-effects.
1532 However, some recipes point to this file within
1533 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
1534 (as <filename>${COREBASE}/LICENSE</filename>) and thus the
1535 accompanying checksum must be changed from
1536 3f40d7994397109285ec7b81fdeb3b58 to
1537 4d92cd373abda3937c2bc47fbc49d690.
1538 A better alternative is to have
1539 <filename>LIC_FILES_CHKSUM</filename> point to a file
1540 describing the license that is distributed with the source
1541 that the recipe is building, if possible, rather than pointing
1542 to <filename>${COREBASE}/LICENSE</filename>.
1543 </para>
1544 </section>
1545
1546 <section id='migration-1.6-cflags-options'>
1547 <title><filename>CFLAGS</filename> Options</title>
1548
1549 <para>
1550 The "-fpermissive" option has been removed from the default
1551 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1552 value.
1553 You need to take action on individual recipes that fail when
1554 building with this option.
1555 You need to either patch the recipes to fix the issues reported by
1556 the compiler, or you need to add "-fpermissive" to
1557 <filename>CFLAGS</filename> in the recipes.
1558 </para>
1559 </section>
1560
1561 <section id='migration-1.6-custom-images'>
1562 <title>Custom Image Output Types</title>
1563
1564 <para>
1565 Custom image output types, as selected using
1566 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
1567 must declare their dependencies on other image types (if any) using
1568 a new
1569 <link linkend='var-IMAGE_TYPEDEP'><filename>IMAGE_TYPEDEP</filename></link>
1570 variable.
1571 </para>
1572 </section>
1573
1574 <section id='migration-1.6-do-package-write-task'>
1575 <title>Tasks</title>
1576
1577 <para>
1578 The <filename>do_package_write</filename> task has been removed.
1579 The task is no longer needed.
1580 </para>
1581 </section>
1582
1583 <section id='migration-1.6-update-alternatives-provider'>
1584 <title><filename>update-alternative</filename> Provider</title>
1585
1586 <para>
1587 The default <filename>update-alternatives</filename> provider has
1588 been changed from <filename>opkg</filename> to
1589 <filename>opkg-utils</filename>.
1590 This change resolves some troublesome circular dependencies.
1591 The runtime package has also been renamed from
1592 <filename>update-alternatives-cworth</filename>
1593 to <filename>update-alternatives-opkg</filename>.
1594 </para>
1595 </section>
1596
1597 <section id='migration-1.6-virtclass-overrides'>
1598 <title><filename>virtclass</filename> Overrides</title>
1599
1600 <para>
1601 The <filename>virtclass</filename> overrides are now deprecated.
1602 Use the equivalent class overrides instead (e.g.
1603 <filename>virtclass-native</filename> becomes
1604 <filename>class-native</filename>.)
1605 </para>
1606 </section>
1607
1608 <section id='migration-1.6-removed-renamed-recipes'>
1609 <title>Removed and Renamed Recipes</title>
1610
1611 <para>
1612 The following recipes have been removed:
1613 <itemizedlist>
1614 <listitem><para><filename>packagegroup-toolset-native</filename> -
1615 This recipe is largely unused.
1616 </para></listitem>
1617 <listitem><para><filename>linux-yocto-3.8</filename> -
1618 Support for the Linux yocto 3.8 kernel has been dropped.
1619 Support for the 3.10 and 3.14 kernels have been added
1620 with the <filename>linux-yocto-3.10</filename> and
1621 <filename>linux-yocto-3.14</filename> recipes.
1622 </para></listitem>
1623 <listitem><para><filename>ocf-linux</filename> -
1624 This recipe has been functionally replaced using
1625 <filename>cryptodev-linux</filename>.
1626 </para></listitem>
1627 <listitem><para><filename>genext2fs</filename> -
1628 <filename>genext2fs</filename> is no longer used by the
1629 build system and is unmaintained upstream.
1630 </para></listitem>
1631 <listitem><para><filename>js</filename> -
1632 This provided an ancient version of Mozilla's javascript
1633 engine that is no longer needed.
1634 </para></listitem>
1635 <listitem><para><filename>zaurusd</filename> -
1636 The recipe has been moved to the
1637 <filename>meta-handheld</filename> layer.
1638 </para></listitem>
1639 <listitem><para><filename>eglibc 2.17</filename> -
1640 Replaced by the <filename>eglibc 2.19</filename>
1641 recipe.
1642 </para></listitem>
1643 <listitem><para><filename>gcc 4.7.2</filename> -
1644 Replaced by the now stable
1645 <filename>gcc 4.8.2</filename>.
1646 </para></listitem>
1647 <listitem><para><filename>external-sourcery-toolchain</filename> -
1648 this recipe is now maintained in the
1649 <filename>meta-sourcery</filename> layer.
1650 </para></listitem>
1651 <listitem><para><filename>linux-libc-headers-yocto 3.4+git</filename> -
1652 Now using version 3.10 of the
1653 <filename>linux-libc-headers</filename> by default.
1654 </para></listitem>
1655 <listitem><para><filename>meta-toolchain-gmae</filename> -
1656 This recipe is obsolete.
1657 </para></listitem>
1658 <listitem><para><filename>packagegroup-core-sdk-gmae</filename> -
1659 This recipe is obsolete.
1660 </para></listitem>
1661 <listitem><para><filename>packagegroup-core-standalone-gmae-sdk-target</filename> -
1662 This recipe is obsolete.
1663 </para></listitem>
1664 </itemizedlist>
1665 </para>
1666 </section>
1667
1668 <section id='migration-1.6-removed-classes'>
1669 <title>Removed Classes</title>
1670
1671 <para>
1672 The following classes have become obsolete and have been removed:
1673 <itemizedlist>
1674 <listitem><para><filename>module_strip</filename>
1675 </para></listitem>
1676 <listitem><para><filename>pkg_metainfo</filename>
1677 </para></listitem>
1678 <listitem><para><filename>pkg_distribute</filename>
1679 </para></listitem>
1680 <listitem><para><filename>image-empty</filename>
1681 </para></listitem>
1682 </itemizedlist>
1683 </para>
1684 </section>
1685
1686 <section id='migration-1.6-reference-bsps'>
1687 <title>Reference Board Support Packages (BSPs)</title>
1688
1689 <para>
1690 The following reference BSPs changes occurred:
1691 <itemizedlist>
1692 <listitem><para>The BeagleBoard
1693 (<filename>beagleboard</filename>) ARM reference hardware
1694 has been replaced by the BeagleBone
1695 (<filename>beaglebone</filename>) hardware.
1696 </para></listitem>
1697 <listitem><para>The RouterStation Pro
1698 (<filename>routerstationpro</filename>) MIPS reference
1699 hardware has been replaced by the EdgeRouter Lite
1700 (<filename>edgerouter</filename>) hardware.
1701 </para></listitem>
1702 </itemizedlist>
1703 The previous reference BSPs for the
1704 <filename>beagleboard</filename> and
1705 <filename>routerstationpro</filename> machines are still available
1706 in a new <filename>meta-yocto-bsp-old</filename> layer in the
1707 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
1708 at
1709 <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>.
1710 </para>
1711 </section>
1712</section>
1713
1714<section id='moving-to-the-yocto-project-1.7-release'>
1715 <title>Moving to the Yocto Project 1.7 Release</title>
1716
1717 <para>
1718 This section provides migration information for moving to the
1719 Yocto Project 1.7 Release from the prior release.
1720 </para>
1721
1722 <section id='migration-1.7-changes-to-setting-qemu-packageconfig-options'>
1723 <title>Changes to Setting QEMU <filename>PACKAGECONFIG</filename> Options in <filename>local.conf</filename></title>
1724
1725 <para>
1726 The QEMU recipe now uses a number of
1727 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
1728 options to enable various optional features.
1729 The method used to set defaults for these options means that
1730 existing
1731 <filename>local.conf</filename> files will need to be be
1732 modified to append to <filename>PACKAGECONFIG</filename> for
1733 <filename>qemu-native</filename> and
1734 <filename>nativesdk-qemu</filename> instead of setting it.
1735 In other words, to enable graphical output for QEMU, you should
1736 now have these lines in <filename>local.conf</filename>:
1737 <literallayout class='monospaced'>
1738 PACKAGECONFIG_append_pn-qemu-native = " sdl"
1739 PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
1740 </literallayout>
1741 </para>
1742 </section>
1743
1744 <section id='migration-1.7-minimum-git-version'>
1745 <title>Minimum Git version</title>
1746
1747 <para>
1748 The minimum
Brad Bishop316dfdd2018-06-25 12:45:53 -04001749 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> version
1750 required on the build host is now 1.7.8 because the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001751 <filename>--list</filename> option is now required by
1752 BitBake's Git fetcher.
1753 As always, if your host distribution does not provide a version of
1754 Git that meets this requirement, you can use the
1755 <filename>buildtools-tarball</filename> that does.
1756 See the
1757 "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
1758 section for more information.
1759 </para>
1760 </section>
1761
1762 <section id='migration-1.7-autotools-class-changes'>
1763 <title>Autotools Class Changes</title>
1764
1765 <para>
1766 The following
1767 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
1768 class changes occurred:
1769 <itemizedlist>
1770 <listitem><para><emphasis>
1771 A separate build directory is now used by default:</emphasis>
1772 The <filename>autotools</filename> class has been changed
1773 to use a directory for building
1774 (<link linkend='var-B'><filename>B</filename></link>),
1775 which is separate from the source directory
1776 (<link linkend='var-S'><filename>S</filename></link>).
1777 This is commonly referred to as
1778 <filename>B != S</filename>, or an out-of-tree build.</para>
1779 <para>If the software being built is already capable of
1780 building in a directory separate from the source, you
1781 do not need to do anything.
1782 However, if the software is not capable of being built
1783 in this manner, you will
1784 need to either patch the software so that it can build
1785 separately, or you will need to change the recipe to
1786 inherit the
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001787 <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
1788 class instead of the <filename>autotools</filename> or
1789 <filename>autotools_stage</filename> classes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001790 </para></listitem>
1791 <listitem><para><emphasis>
1792 The <filename>--foreign</filename> option is
1793 no longer passed to <filename>automake</filename> when
1794 running <filename>autoconf</filename>:</emphasis>
1795 This option tells <filename>automake</filename> that a
1796 particular software package does not follow the GNU
1797 standards and therefore should not be expected
1798 to distribute certain files such as
1799 <filename>ChangeLog</filename>,
1800 <filename>AUTHORS</filename>, and so forth.
1801 Because the majority of upstream software packages already
1802 tell <filename>automake</filename> to enable foreign mode
1803 themselves, the option is mostly superfluous.
1804 However, some recipes will need patches for this change.
1805 You can easily make the change by patching
1806 <filename>configure.ac</filename> so that it passes
1807 "foreign" to <filename>AM_INIT_AUTOMAKE()</filename>.
1808 See
1809 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2'>this commit</ulink>
1810 for an example showing how to make the patch.
1811 </para></listitem>
1812 </itemizedlist>
1813 </para>
1814 </section>
1815
1816 <section id='migration-1.7-binary-configuration-scripts-disabled'>
1817 <title>Binary Configuration Scripts Disabled</title>
1818
1819 <para>
1820 Some of the core recipes that package binary configuration scripts
1821 now disable the scripts due to the
1822 scripts previously requiring error-prone path substitution.
1823 Software that links against these libraries using these scripts
1824 should use the much more robust <filename>pkg-config</filename>
1825 instead.
1826 The list of recipes changed in this version (and their
1827 configuration scripts) is as follows:
1828 <literallayout class='monospaced'>
1829 directfb (directfb-config)
1830 freetype (freetype-config)
1831 gpgme (gpgme-config)
1832 libassuan (libassuan-config)
1833 libcroco (croco-6.0-config)
1834 libgcrypt (libgcrypt-config)
1835 libgpg-error (gpg-error-config)
1836 libksba (ksba-config)
1837 libpcap (pcap-config)
1838 libpcre (pcre-config)
1839 libpng (libpng-config, libpng16-config)
1840 libsdl (sdl-config)
1841 libusb-compat (libusb-config)
1842 libxml2 (xml2-config)
1843 libxslt (xslt-config)
1844 ncurses (ncurses-config)
1845 neon (neon-config)
1846 npth (npth-config)
1847 pth (pth-config)
1848 taglib (taglib-config)
1849 </literallayout>
1850 Additionally, support for <filename>pkg-config</filename> has been
1851 added to some recipes in the previous list in the rare cases
1852 where the upstream software package does not already provide
1853 it.
1854 </para>
1855 </section>
1856
1857 <section id='migration-1.7-glibc-replaces-eglibc'>
1858 <title><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></title>
1859
1860 <para>
1861 Because <filename>eglibc</filename> and
1862 <filename>glibc</filename> were already fairly close, this
1863 replacement should not require any significant changes to other
1864 software that links to <filename>eglibc</filename>.
1865 However, there were a number of minor changes in
1866 <filename>glibc 2.20</filename> upstream that could require
1867 patching some software (e.g. the removal of the
1868 <filename>_BSD_SOURCE</filename> feature test macro).
1869 </para>
1870
1871 <para>
1872 <filename>glibc 2.20</filename> requires version 2.6.32 or greater
1873 of the Linux kernel.
1874 Thus, older kernels will no longer be usable in conjunction with it.
1875 </para>
1876
1877 <para>
1878 For full details on the changes in <filename>glibc 2.20</filename>,
1879 see the upstream release notes
1880 <ulink url='https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html'>here</ulink>.
1881 </para>
1882 </section>
1883
1884 <section id='migration-1.7-kernel-module-autoloading'>
1885 <title>Kernel Module Autoloading</title>
1886
1887 <para>
1888 The
1889 <link linkend='var-module_autoload'><filename>module_autoload_*</filename></link>
1890 variable is now deprecated and a new
1891 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
1892 variable should be used instead.
1893 Also,
1894 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
1895 must now be used in conjunction with a new
1896 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
1897 variable.
1898 The new variables no longer require you to specify the module name
1899 as part of the variable name.
1900 This change not only simplifies usage but also allows the values
1901 of these variables to be appropriately incorporated into task
1902 signatures and thus trigger the appropriate tasks to re-execute
1903 when changed.
1904 You should replace any references to
1905 <filename>module_autoload_*</filename> with
1906 <filename>KERNEL_MODULE_AUTOLOAD</filename>, and add any modules
1907 for which <filename>module_conf_*</filename> is specified to
1908 <filename>KERNEL_MODULE_PROBECONF</filename>.
1909 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001910 </section>
1911
1912 <section id='migration-1.7-qa-check-changes'>
1913 <title>QA Check Changes</title>
1914
1915 <para>
1916 The following changes have occurred to the QA check process:
1917 <itemizedlist>
1918 <listitem><para>
1919 Additional QA checks <filename>file-rdeps</filename>
1920 and <filename>build-deps</filename> have been added in
1921 order to verify that file dependencies are satisfied
1922 (e.g. package contains a script requiring
1923 <filename>/bin/bash</filename>) and build-time dependencies
1924 are declared, respectively.
1925 For more information, please see the
1926 "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>"
1927 chapter.
1928 </para></listitem>
1929 <listitem><para>
1930 Package QA checks are now performed during a new
1931 <link linkend='ref-tasks-package_qa'><filename>do_package_qa</filename></link>
1932 task rather than being part of the
1933 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
1934 task.
1935 This allows more parallel execution.
1936 This change is unlikely to be an issue except for highly
1937 customized recipes that disable packaging tasks themselves
1938 by marking them as <filename>noexec</filename>.
1939 For those packages, you will need to disable the
1940 <filename>do_package_qa</filename> task as well.
1941 </para></listitem>
1942 <listitem><para>
1943 Files being overwritten during the
1944 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
1945 task now trigger an error instead of a warning.
1946 Recipes should not be overwriting files written to the
1947 sysroot by other recipes.
1948 If you have these types of recipes, you need to alter them
1949 so that they do not overwrite these files.</para>
1950 <para>You might now receive this error after changes in
1951 configuration or metadata resulting in orphaned files
1952 being left in the sysroot.
1953 If you do receive this error, the way to resolve the issue
1954 is to delete your
1955 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1956 or to move it out of the way and then re-start the build.
1957 Anything that has been fully built up to that point and
1958 does not need rebuilding will be restored from the shared
1959 state cache and the rest of the build will be able to
1960 proceed as normal.
1961 </para></listitem>
1962 </itemizedlist>
1963 </para>
1964 </section>
1965
1966 <section id='migration-1.7-removed-recipes'>
1967 <title>Removed Recipes</title>
1968
1969 <para>
1970 The following recipes have been removed:
1971 <itemizedlist>
1972 <listitem><para>
1973 <filename>x-load</filename>:
1974 This recipe has been superseded by
1975 U-boot SPL for all Cortex-based TI SoCs.
1976 For legacy boards, the <filename>meta-ti</filename>
1977 layer, which contains a maintained recipe, should be used
1978 instead.
1979 </para></listitem>
1980 <listitem><para>
1981 <filename>ubootchart</filename>:
1982 This recipe is obsolete.
1983 A <filename>bootchart2</filename> recipe has been added
1984 to functionally replace it.
1985 </para></listitem>
1986 <listitem><para>
1987 <filename>linux-yocto 3.4</filename>:
1988 Support for the linux-yocto 3.4 kernel has been dropped.
1989 Support for the 3.10 and 3.14 kernels remains, while
1990 support for version 3.17 has been added.
1991 </para></listitem>
1992 <listitem><para>
1993 <filename>eglibc</filename> has been removed in favor of
1994 <filename>glibc</filename>.
1995 See the
1996 "<link linkend='migration-1.7-glibc-replaces-eglibc'><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></link>"
1997 section for more information.
1998 </para></listitem>
1999 </itemizedlist>
2000 </para>
2001 </section>
2002
2003 <section id='migration-1.7-miscellaneous-changes'>
2004 <title>Miscellaneous Changes</title>
2005
2006 <para>
2007 The following miscellaneous change occurred:
2008 <itemizedlist>
2009 <listitem><para>
2010 The build history feature now writes
2011 <filename>build-id.txt</filename> instead of
2012 <filename>build-id</filename>.
2013 Additionally, <filename>build-id.txt</filename>
2014 now contains the full build header as printed by
2015 BitBake upon starting the build.
2016 You should manually remove old "build-id" files from your
2017 existing build history repositories to avoid confusion.
2018 For information on the build history feature, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04002019 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
2020 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002021 </para></listitem>
2022 </itemizedlist>
2023 </para>
2024 </section>
2025</section>
2026
2027<section id='moving-to-the-yocto-project-1.8-release'>
2028 <title>Moving to the Yocto Project 1.8 Release</title>
2029
2030 <para>
2031 This section provides migration information for moving to the
2032 Yocto Project 1.8 Release from the prior release.
2033 </para>
2034
2035 <section id='migration-1.8-removed-recipes'>
2036 <title>Removed Recipes</title>
2037
2038 <para>
2039 The following recipes have been removed:
2040 <itemizedlist>
2041 <listitem><para><filename>owl-video</filename>:
2042 Functionality replaced by <filename>gst-player</filename>.
2043 </para></listitem>
2044 <listitem><para><filename>gaku</filename>:
2045 Functionality replaced by <filename>gst-player</filename>.
2046 </para></listitem>
2047 <listitem><para><filename>gnome-desktop</filename>:
2048 This recipe is now available in
2049 <filename>meta-gnome</filename> and is no longer needed.
2050 </para></listitem>
2051 <listitem><para><filename>gsettings-desktop-schemas</filename>:
2052 This recipe is now available in
2053 <filename>meta-gnome</filename> and is no longer needed.
2054 </para></listitem>
2055 <listitem><para><filename>python-argparse</filename>:
2056 The <filename>argparse</filename> module is already
2057 provided in the default Python distribution in a
2058 package named <filename>python-argparse</filename>.
2059 Consequently, the separate
2060 <filename>python-argparse</filename> recipe is no
2061 longer needed.
2062 </para></listitem>
2063 <listitem><para><filename>telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control</filename>:
2064 All these recipes have moved to
2065 <filename>meta-oe</filename> and are consequently no
2066 longer needed by any recipes in OpenEmbedded-Core.
2067 </para></listitem>
2068 <listitem><para><filename>linux-yocto_3.10</filename> and <filename>linux-yocto_3.17</filename>:
2069 Support for the linux-yocto 3.10 and 3.17 kernels has been
2070 dropped.
2071 Support for the 3.14 kernel remains, while support for
2072 3.19 kernel has been added.
2073 </para></listitem>
2074 <listitem><para><filename>poky-feed-config-opkg</filename>:
2075 This recipe has become obsolete and is no longer needed.
2076 Use <filename>distro-feed-config</filename> from
2077 <filename>meta-oe</filename> instead.
2078 </para></listitem>
2079 <listitem><para><filename>libav 0.8.x</filename>:
2080 <filename>libav 9.x</filename> is now used.
2081 </para></listitem>
2082 <listitem><para><filename>sed-native</filename>:
2083 No longer needed.
2084 A working version of <filename>sed</filename> is expected
2085 to be provided by the host distribution.
2086 </para></listitem>
2087 </itemizedlist>
2088 </para>
2089 </section>
2090
2091 <section id='migration-1.8-bluez'>
2092 <title>BlueZ 4.x / 5.x Selection</title>
2093
2094 <para>
2095 Proper built-in support for selecting BlueZ 5.x in preference
2096 to the default of 4.x now exists.
2097 To use BlueZ 5.x, simply add "bluez5" to your
2098 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
2099 value.
2100 If you had previously added append files
2101 (<filename>*.bbappend</filename>) to make this selection, you can
2102 now remove them.
2103 </para>
2104
2105 <para>
2106 Additionally, a
2107 <link linkend='ref-classes-bluetooth'><filename>bluetooth</filename></link>
2108 class has been added to make selection of the appropriate bluetooth
2109 support within a recipe a little easier.
2110 If you wish to make use of this class in a recipe, add something
2111 such as the following:
2112 <literallayout class='monospaced'>
2113 inherit bluetooth
2114 PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}
2115 PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4"
2116 PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5"
2117 </literallayout>
2118 </para>
2119 </section>
2120
2121 <section id='migration-1.8-kernel-build-changes'>
2122 <title>Kernel Build Changes</title>
2123
2124 <para>
2125 The kernel build process was changed to place the source
2126 in a common shared work area and to place build artifacts
2127 separately in the source code tree.
2128 In theory, migration paths have been provided for most common
2129 usages in kernel recipes but this might not work in all cases.
2130 In particular, users need to ensure that
2131 <filename>${S}</filename> (source files) and
2132 <filename>${B}</filename> (build artifacts) are used
2133 correctly in functions such as
2134 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2135 and
2136 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
2137 For kernel recipes that do not inherit from
2138 <filename>kernel-yocto</filename> or include
2139 <filename>linux-yocto.inc</filename>, you might wish to
2140 refer to the <filename>linux.inc</filename> file in the
2141 <filename>meta-oe</filename> layer for the kinds of changes you
2142 need to make.
2143 For reference, here is the
2144 <ulink url='http://cgit.openembedded.org/meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee'>commit</ulink>
2145 where the <filename>linux.inc</filename> file in
2146 <filename>meta-oe</filename> was updated.
2147 </para>
2148
2149 <para>
2150 Recipes that rely on the kernel source code and do not inherit
2151 the module classes might need to add explicit dependencies on
2152 the <filename>do_shared_workdir</filename> kernel task, for example:
2153 <literallayout class='monospaced'>
2154 do_configure[depends] += "virtual/kernel:do_shared_workdir"
2155 </literallayout>
2156 </para>
2157 </section>
2158
2159 <section id='migration-1.8-ssl'>
2160 <title>SSL 3.0 is Now Disabled in OpenSSL</title>
2161
2162 <para>
2163 SSL 3.0 is now disabled when building OpenSSL.
2164 Disabling SSL 3.0 avoids any lingering instances of the POODLE
2165 vulnerability.
2166 If you feel you must re-enable SSL 3.0, then you can add an
2167 append file (<filename>*.bbappend</filename>) for the
2168 <filename>openssl</filename> recipe to remove "-no-ssl3"
2169 from
2170 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>.
2171 </para>
2172 </section>
2173
2174 <section id='migration-1.8-default-sysroot-poisoning'>
2175 <title>Default Sysroot Poisoning</title>
2176
2177 <para>
2178 <filename>gcc's</filename> default sysroot and include directories
2179 are now "poisoned".
2180 In other words, the sysroot and include directories are being
2181 redirected to a non-existent location in order to catch when
2182 host directories are being used due to the correct options not
2183 being passed.
2184 This poisoning applies both to the cross-compiler used within the
2185 build and to the cross-compiler produced in the SDK.
2186 </para>
2187
2188 <para>
2189 If this change causes something in the build to fail, it almost
2190 certainly means the various compiler flags and commands are not
2191 being passed correctly to the underlying piece of software.
2192 In such cases, you need to take corrective steps.
2193 </para>
2194 </section>
2195
2196 <section id='migration-1.8-rebuild-improvements'>
2197 <title>Rebuild Improvements</title>
2198
2199 <para>
2200 Changes have been made to the
2201 <link linkend='ref-classes-base'><filename>base</filename></link>,
2202 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>,
2203 and
2204 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
2205 classes to clean out generated files when the
2206 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2207 task needs to be re-executed.
2208 </para>
2209
2210 <para>
2211 One of the improvements is to attempt to run "make clean" during
2212 the <filename>do_configure</filename> task if a
2213 <filename>Makefile</filename> exists.
2214 Some software packages do not provide a working clean target
2215 within their make files.
2216 If you have such recipes, you need to set
2217 <link linkend='var-CLEANBROKEN'><filename>CLEANBROKEN</filename></link>
2218 to "1" within the recipe, for example:
2219 <literallayout class='monospaced'>
2220 CLEANBROKEN = "1"
2221 </literallayout>
2222 </para>
2223 </section>
2224
2225 <section id='migration-1.8-qa-check-and-validation-changes'>
2226 <title>QA Check and Validation Changes</title>
2227
2228 <para>
2229 The following QA Check and Validation Changes have occurred:
2230 <itemizedlist>
2231 <listitem><para>
2232 Usage of <filename>PRINC</filename>
2233 previously triggered a warning.
2234 It now triggers an error.
2235 You should remove any remaining usage of
2236 <filename>PRINC</filename> in any recipe or append file.
2237 </para></listitem>
2238 <listitem><para>
2239 An additional QA check has been added to detect usage of
2240 <filename>${D}</filename> in
2241 <link linkend='var-FILES'><filename>FILES</filename></link>
2242 values where
2243 <link linkend='var-D'><filename>D</filename></link> values
2244 should not be used at all.
2245 The same check ensures that <filename>$D</filename> is used
2246 in
2247 <filename>pkg_preinst/pkg_postinst/pkg_prerm/pkg_postrm</filename>
2248 functions instead of <filename>${D}</filename>.
2249 </para></listitem>
2250 <listitem><para>
2251 <link linkend='var-S'><filename>S</filename></link> now
2252 needs to be set to a valid value within a recipe.
2253 If <filename>S</filename> is not set in the recipe, the
2254 directory is not automatically created.
2255 If <filename>S</filename> does not point to a directory
2256 that exists at the time the
2257 <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
2258 task finishes, a warning will be shown.
2259 </para></listitem>
2260 <listitem><para>
2261 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2262 is now validated for correct formatting of multiple
2263 licenses.
2264 If the format is invalid (e.g. multiple licenses are
2265 specified with no operators to specify how the multiple
2266 licenses interact), then a warning will be shown.
2267 </para></listitem>
2268 </itemizedlist>
2269 </para>
2270 </section>
2271
2272 <section id='migration-1.8-miscellaneous-changes'>
2273 <title>Miscellaneous Changes</title>
2274
2275 <para>
2276 The following miscellaneous changes have occurred:
2277 <itemizedlist>
2278 <listitem><para>
2279 The <filename>send-error-report</filename> script now
2280 expects a "-s" option to be specified before the server
2281 address.
2282 This assumes a server address is being specified.
2283 </para></listitem>
2284 <listitem><para>
2285 The <filename>oe-pkgdata-util</filename> script now
2286 expects a "-p" option to be specified before the
2287 <filename>pkgdata</filename> directory, which is now
2288 optional.
2289 If the <filename>pkgdata</filename> directory is not
2290 specified, the script will run BitBake to query
2291 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
2292 from the build environment.
2293 </para></listitem>
2294 </itemizedlist>
2295 </para>
2296 </section>
2297</section>
2298
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002299<section id='moving-to-the-yocto-project-2.0-release'>
2300 <title>Moving to the Yocto Project 2.0 Release</title>
2301
2302 <para>
2303 This section provides migration information for moving to the
2304 Yocto Project 2.0 Release from the prior release.
2305 </para>
2306
2307 <section id='migration-2.0-gcc-5'>
2308 <title>GCC 5</title>
2309
2310 <para>
2311 The default compiler is now GCC 5.2.
2312 This change has required fixes for compilation errors in a number
2313 of other recipes.
2314 </para>
2315
2316 <para>
2317 One important example is a fix for when the Linux kernel freezes at
2318 boot time on ARM when built with GCC 5.
2319 If you are using your own kernel recipe or source tree and
2320 building for ARM, you will likely need to apply this
2321 <ulink url='https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit?id=a077224fd35b2f7fbc93f14cf67074fc792fbac2'>patch</ulink>.
2322 The standard <filename>linux-yocto</filename> kernel source tree
2323 already has a workaround for the same issue.
2324 </para>
2325
2326 <para>
2327 For further details, see
2328 <ulink url='https://gcc.gnu.org/gcc-5/changes.html'></ulink> and
2329 the porting guide at
2330 <ulink url='https://gcc.gnu.org/gcc-5/porting_to.html'></ulink>.
2331 </para>
2332
2333 <para>
2334 Alternatively, you can switch back to GCC 4.9 or 4.8 by
2335 setting <filename>GCCVERSION</filename> in your configuration,
2336 as follows:
2337 <literallayout class='monospaced'>
2338 GCCVERSION = "4.9%"
2339 </literallayout>
2340 </para>
2341 </section>
2342
2343 <section id='migration-2.0-Gstreamer-0.10-removed'>
2344 <title>Gstreamer 0.10 Removed</title>
2345
2346 <para>
2347 Gstreamer 0.10 has been removed in favor of Gstreamer 1.x.
2348 As part of the change, recipes for Gstreamer 0.10 and related
2349 software are now located
2350 in <filename>meta-multimedia</filename>.
2351 This change results in Qt4 having Phonon and Gstreamer
2352 support in QtWebkit disabled by default.
2353 </para>
2354 </section>
2355
2356 <section id='migration-2.0-removed-recipes'>
2357 <title>Removed Recipes</title>
2358
2359 <para>
2360 The following recipes have been moved or removed:
2361 <itemizedlist>
2362 <listitem><para>
2363 <filename>bluez4</filename>: The recipe is obsolete and
2364 has been moved due to <filename>bluez5</filename>
2365 becoming fully integrated.
2366 The <filename>bluez4</filename> recipe now resides in
2367 <filename>meta-oe</filename>.
2368 </para></listitem>
2369 <listitem><para>
2370 <filename>gamin</filename>: The recipe is obsolete and
2371 has been removed.
2372 </para></listitem>
2373 <listitem><para>
2374 <filename>gnome-icon-theme</filename>: The recipe's
2375 functionally has been replaced by
2376 <filename>adwaita-icon-theme</filename>.
2377 </para></listitem>
2378 <listitem><para>
2379 Gstreamer 0.10 Recipes: Recipes for Gstreamer 0.10 have
2380 been removed in favor of the recipes for Gstreamer 1.x.
2381 </para></listitem>
2382 <listitem><para>
2383 <filename>insserv</filename>: The recipe is obsolete and
2384 has been removed.
2385 </para></listitem>
2386 <listitem><para>
2387 <filename>libunique</filename>: The recipe is no longer
2388 used and has been moved to <filename>meta-oe</filename>.
2389 </para></listitem>
2390 <listitem><para>
2391 <filename>midori</filename>: The recipe's functionally
2392 has been replaced by <filename>epiphany</filename>.
2393 </para></listitem>
2394 <listitem><para>
2395 <filename>python-gst</filename>: The recipe is obsolete
2396 and has been removed since it only contains bindings for
2397 Gstreamer 0.10.
2398 </para></listitem>
2399 <listitem><para>
2400 <filename>qt-mobility</filename>: The recipe is obsolete and
2401 has been removed since it requires
2402 <filename>Gstreamer 0.10</filename>, which has been
2403 replaced.
2404 </para></listitem>
2405 <listitem><para>
2406 <filename>subversion</filename>: All 1.6.x versions of this
2407 recipe have been removed.
2408 </para></listitem>
2409 <listitem><para>
2410 <filename>webkit-gtk</filename>: The older 1.8.3 version
2411 of this recipe has been removed in favor of
2412 <filename>webkitgtk</filename>.
2413 </para></listitem>
2414 </itemizedlist>
2415 </para>
2416 </section>
2417
2418 <section id='migration-2.0-bitbake-datastore-improvements'>
2419 <title>BitBake datastore improvements</title>
2420
2421 <para>
2422 The method by which BitBake's datastore handles overrides has
2423 changed.
2424 Overrides are now applied dynamically and
2425 <filename>bb.data.update_data()</filename> is now a no-op.
2426 Thus, <filename>bb.data.update_data()</filename> is no longer
2427 required in order to apply the correct overrides.
2428 In practice, this change is unlikely to require any changes to
2429 Metadata.
2430 However, these minor changes in behavior exist:
2431 <itemizedlist>
2432 <listitem><para>
2433 All potential overrides are now visible in the variable
2434 history as seen when you run the following:
2435 <literallayout class='monospaced'>
2436 $ bitbake -e
2437 </literallayout>
2438 </para></listitem>
2439 <listitem><para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002440 <filename>d.delVar('</filename><replaceable>VARNAME</replaceable><filename>')</filename> and
2441 <filename>d.setVar('</filename><replaceable>VARNAME</replaceable><filename>', None)</filename>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002442 result in the variable and all of its overrides being
2443 cleared out.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002444 Before the change, only the non-overridden values
2445 were cleared.
2446 </para></listitem>
2447 </itemizedlist>
2448 </para>
2449 </section>
2450
2451 <section id='migration-2.0-shell-message-function-changes'>
2452 <title>Shell Message Function Changes</title>
2453
2454 <para>
2455 The shell versions of the BitBake message functions (i.e.
2456 <filename>bbdebug</filename>, <filename>bbnote</filename>,
2457 <filename>bbwarn</filename>, <filename>bbplain</filename>,
2458 <filename>bberror</filename>, and <filename>bbfatal</filename>)
2459 are now connected through to their BitBake equivalents
2460 <filename>bb.debug()</filename>, <filename>bb.note()</filename>,
2461 <filename>bb.warn()</filename>, <filename>bb.plain()</filename>,
2462 <filename>bb.error()</filename>, and
2463 <filename>bb.fatal()</filename>, respectively.
2464 Thus, those message functions that you would expect to be printed
2465 by the BitBake UI are now actually printed.
2466 In practice, this change means two things:
2467 <itemizedlist>
2468 <listitem><para>
2469 If you now see messages on the console that you did not
2470 previously see as a result of this change, you might
2471 need to clean up the calls to
2472 <filename>bbwarn</filename>, <filename>bberror</filename>,
2473 and so forth.
2474 Or, you might want to simply remove the calls.
2475 </para></listitem>
2476 <listitem><para>
2477 The <filename>bbfatal</filename> message function now
2478 suppresses the full error log in the UI, which means any
2479 calls to <filename>bbfatal</filename> where you still
2480 wish to see the full error log should be replaced by
2481 <filename>die</filename> or
2482 <filename>bbfatal_log</filename>.
2483 </para></listitem>
2484 </itemizedlist>
2485 </para>
2486 </section>
2487
2488 <section id='migration-2.0-extra-development-debug-package-cleanup'>
2489 <title>Extra Development/Debug Package Cleanup</title>
2490
2491 <para>
2492 The following recipes have had extra
2493 <filename>dev/dbg</filename> packages removed:
2494 <itemizedlist>
2495 <listitem><para>
2496 <filename>acl</filename>
2497 </para></listitem>
2498 <listitem><para>
2499 <filename>apmd</filename>
2500 </para></listitem>
2501 <listitem><para>
2502 <filename>aspell</filename>
2503 </para></listitem>
2504 <listitem><para>
2505 <filename>attr</filename>
2506 </para></listitem>
2507 <listitem><para>
2508 <filename>augeas</filename>
2509 </para></listitem>
2510 <listitem><para>
2511 <filename>bzip2</filename>
2512 </para></listitem>
2513 <listitem><para>
2514 <filename>cogl</filename>
2515 </para></listitem>
2516 <listitem><para>
2517 <filename>curl</filename>
2518 </para></listitem>
2519 <listitem><para>
2520 <filename>elfutils</filename>
2521 </para></listitem>
2522 <listitem><para>
2523 <filename>gcc-target</filename>
2524 </para></listitem>
2525 <listitem><para>
2526 <filename>libgcc</filename>
2527 </para></listitem>
2528 <listitem><para>
2529 <filename>libtool</filename>
2530 </para></listitem>
2531 <listitem><para>
2532 <filename>libxmu</filename>
2533 </para></listitem>
2534 <listitem><para>
2535 <filename>opkg</filename>
2536 </para></listitem>
2537 <listitem><para>
2538 <filename>pciutils</filename>
2539 </para></listitem>
2540 <listitem><para>
2541 <filename>rpm</filename>
2542 </para></listitem>
2543 <listitem><para>
2544 <filename>sysfsutils</filename>
2545 </para></listitem>
2546 <listitem><para>
2547 <filename>tiff</filename>
2548 </para></listitem>
2549 <listitem><para>
2550 <filename>xz</filename>
2551 </para></listitem>
2552 </itemizedlist>
2553 All of the above recipes now conform to the standard packaging
2554 scheme where a single <filename>-dev</filename>,
2555 <filename>-dbg</filename>, and <filename>-staticdev</filename>
2556 package exists per recipe.
2557 </para>
2558 </section>
2559
2560 <section id='migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core'>
2561 <title>Recipe Maintenance Tracking Data Moved to OE-Core</title>
2562
2563 <para>
2564 Maintenance tracking data for recipes that was previously part
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002565 of <filename>meta-yocto</filename> has been moved to
2566 <link linkend='oe-core'>OE-Core</link>.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002567 The change includes <filename>package_regex.inc</filename> and
2568 <filename>distro_alias.inc</filename>, which are typically enabled
2569 when using the
2570 <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link>
2571 class.
2572 Additionally, the contents of
2573 <filename>upstream_tracking.inc</filename> has now been split out
2574 to the relevant recipes.
2575 </para>
2576 </section>
2577
2578 <section id='migration-2.0-automatic-stale-sysroot-file-cleanup'>
2579 <title>Automatic Stale Sysroot File Cleanup</title>
2580
2581 <para>
2582 Stale files from recipes that no longer exist in the current
2583 configuration are now automatically removed from
2584 sysroot as well as removed from
2585 any other place managed by shared state.
2586 This automatic cleanup means that the build system now properly
2587 handles situations such as renaming the build system side of
2588 recipes, removal of layers from
2589 <filename>bblayers.conf</filename>, and
2590 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
2591 changes.
2592 </para>
2593
2594 <para>
2595 Additionally, work directories for old versions of recipes are
2596 now pruned.
2597 If you wish to disable pruning old work directories, you can set
2598 the following variable in your configuration:
2599 <literallayout class='monospaced'>
2600 SSTATE_PRUNE_OBSOLETEWORKDIR = "0"
2601 </literallayout>
2602 </para>
2603 </section>
2604
2605 <section id='migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source'>
2606 <title><filename>linux-yocto</filename> Kernel Metadata Repository Now Split from Source</title>
2607
2608 <para>
2609 The <filename>linux-yocto</filename> tree has up to now been a
2610 combined set of kernel changes and configuration (meta) data
2611 carried in a single tree.
2612 While this format is effective at keeping kernel configuration and
2613 source modifications synchronized, it is not always obvious to
2614 developers how to manipulate the Metadata as compared to the
2615 source.
2616 </para>
2617
2618 <para>
2619 Metadata processing has now been removed from the
2620 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
2621 class and the external Metadata repository
2622 <filename>yocto-kernel-cache</filename>, which has always been used
2623 to seed the <filename>linux-yocto</filename> "meta" branch.
2624 This separate <filename>linux-yocto</filename> cache repository
2625 is now the primary location for this data.
2626 Due to this change, <filename>linux-yocto</filename> is no longer
2627 able to process combined trees.
2628 Thus, if you need to have your own combined kernel repository,
2629 you must do the split there as well and update your recipes
2630 accordingly.
2631 See the <filename>meta/recipes-kernel/linux/linux-yocto_4.1.bb</filename>
2632 recipe for an example.
2633 </para>
2634 </section>
2635
2636 <section id='migration-2.0-additional-qa-checks'>
2637 <title>Additional QA checks</title>
2638
2639 <para>
2640 The following QA checks have been added:
2641 <itemizedlist>
2642 <listitem><para>
2643 Added a "host-user-contaminated" check for ownership
2644 issues for packaged files outside of
2645 <filename>/home</filename>.
2646 The check looks for files that are incorrectly owned by the
2647 user that ran BitBake instead of owned by a valid user in
2648 the target system.
2649 </para></listitem>
2650 <listitem><para>
2651 Added an "invalid-chars" check for invalid (non-UTF8)
2652 characters in recipe metadata variable values
2653 (i.e.
2654 <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>,
2655 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>,
2656 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>,
2657 and
2658 <link linkend='var-SECTION'><filename>SECTION</filename></link>).
2659 Some package managers do not support these characters.
2660 </para></listitem>
2661 <listitem><para>
2662 Added an "invalid-packageconfig" check for any options
2663 specified in
2664 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
2665 that do not match any <filename>PACKAGECONFIG</filename>
2666 option defined for the recipe.
2667 </para></listitem>
2668 </itemizedlist>
2669 </para>
2670 </section>
2671
2672 <section id='migration-2.0-miscellaneous'>
2673 <title>Miscellaneous Changes</title>
2674
2675 <para>
2676 These additional changes exist:
2677 <itemizedlist>
2678 <listitem><para>
2679 <filename>gtk-update-icon-cache</filename> has been
2680 renamed to <filename>gtk-icon-utils</filename>.
2681 </para></listitem>
2682 <listitem><para>
2683 The <filename>tools-profile</filename>
2684 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
2685 item as well as its corresponding packagegroup and
2686 <filename>packagegroup-core-tools-profile</filename> no
2687 longer bring in <filename>oprofile</filename>.
2688 Bringing in <filename>oprofile</filename> was originally
2689 added to aid compilation on resource-constrained
2690 targets.
2691 However, this aid has not been widely used and is not
2692 likely to be used going forward due to the more powerful
2693 target platforms and the existence of better
2694 cross-compilation tools.
2695 </para></listitem>
2696 <listitem><para>
2697 The
2698 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
2699 variable's default value now specifies
2700 <filename>ext4</filename> instead of
2701 <filename>ext3</filename>.
2702 </para></listitem>
2703 <listitem><para>
2704 All support for the <filename>PRINC</filename>
2705 variable has been removed.
2706 </para></listitem>
2707 <listitem><para>
2708 The <filename>packagegroup-core-full-cmdline</filename>
2709 packagegroup no longer brings in
2710 <filename>lighttpd</filename> due to the fact that
2711 bringing in <filename>lighttpd</filename> is not really in
2712 line with the packagegroup's purpose, which is to add full
2713 versions of command-line tools that by default are
2714 provided by <filename>busybox</filename>.
2715 </para></listitem>
2716 </itemizedlist>
2717 </para>
2718 </section>
2719</section>
2720
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002721<section id='moving-to-the-yocto-project-2.1-release'>
2722 <title>Moving to the Yocto Project 2.1 Release</title>
2723
2724 <para>
2725 This section provides migration information for moving to the
2726 Yocto Project 2.1 Release from the prior release.
2727 </para>
2728
2729 <section id='migration-2.1-variable-expansion-in-python-functions'>
2730 <title>Variable Expansion in Python Functions</title>
2731
2732 <para>
2733 Variable expressions, such as
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002734 <filename>${</filename><replaceable>VARNAME</replaceable><filename>}</filename>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002735 no longer expand automatically within Python functions.
2736 Suppressing expansion was done to allow Python functions to
2737 construct shell scripts or other code for situations in which you
2738 do not want such expressions expanded.
2739 For any existing code that relies on these expansions, you need to
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002740 change the expansions to expand the value of individual
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002741 variables through <filename>d.getVar()</filename>.
2742 To alternatively expand more complex expressions,
2743 use <filename>d.expand()</filename>.
2744 </para>
2745 </section>
2746
2747 <section id='migration-2.1-overrides-must-now-be-lower-case'>
2748 <title>Overrides Must Now be Lower-Case</title>
2749
2750 <para>
2751 The convention for overrides has always been for them to be
2752 lower-case characters.
2753 This practice is now a requirement as BitBake's datastore now
2754 assumes lower-case characters in order to give a slight performance
2755 boost during parsing.
2756 In practical terms, this requirement means that anything that ends
2757 up in
2758 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
2759 must now appear in lower-case characters (e.g. values for
2760 <filename>MACHINE</filename>, <filename>TARGET_ARCH</filename>,
2761 <filename>DISTRO</filename>, and also recipe names if
2762 <filename>_pn-</filename><replaceable>recipename</replaceable>
2763 overrides are to be effective).
2764 </para>
2765 </section>
2766
2767 <section id='migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory'>
2768 <title>Expand Parameter to <filename>getVar()</filename> and
2769 <filename>getVarFlag()</filename> is Now Mandatory</title>
2770
2771 <para>
2772 The expand parameter to <filename>getVar()</filename> and
2773 <filename>getVarFlag()</filename> previously defaulted to
2774 False if not specified.
2775 Now, however, no default exists so one must be specified.
2776 You must change any <filename>getVar()</filename> calls that
2777 do not specify the final expand parameter to calls that do specify
2778 the parameter.
2779 You can run the following <filename>sed</filename> command at the
2780 base of a layer to make this change:
2781 <literallayout class='monospaced'>
2782 sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
2783 sed -e 's:\(\.getVarFlag([^,()]*, [^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
2784 </literallayout>
2785 <note>
2786 The reason for this change is that it prepares the way for
2787 changing the default to True in a future Yocto Project release.
2788 This future change is a much more sensible default than False.
2789 However, the change needs to be made gradually as a sudden
2790 change of the default would potentially cause side-effects
2791 that would be difficult to detect.
2792 </note>
2793 </para>
2794 </section>
2795
2796 <section id='migration-2.1-makefile-environment-changes'>
2797 <title>Makefile Environment Changes</title>
2798
2799 <para>
2800 <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link>
2801 now defaults to "" instead of "-e MAKEFLAGS=".
2802 Setting <filename>EXTRA_OEMAKE</filename> to "-e MAKEFLAGS=" by
2803 default was a historical accident that has required many classes
2804 (e.g. <filename>autotools</filename>, <filename>module</filename>)
2805 and recipes to override this default in order to work with
2806 sensible build systems.
2807 When upgrading to the release, you must edit any recipe that
2808 relies upon this old default by either setting
2809 <filename>EXTRA_OEMAKE</filename> back to "-e MAKEFLAGS=" or by
2810 explicitly setting any required variable value overrides using
2811 <filename>EXTRA_OEMAKE</filename>, which is typically only needed
2812 when a Makefile sets a default value for a variable that is
2813 inappropriate for cross-compilation using the "=" operator rather
2814 than the "?=" operator.
2815 </para>
2816 </section>
2817
2818 <section id='migration-2.1-libexecdir-reverted-to-prefix-libexec'>
2819 <title><filename>libexecdir</filename> Reverted to <filename>${prefix}/libexec</filename></title>
2820
2821 <para>
2822 The use of <filename>${libdir}/${BPN}</filename> as
2823 <filename>libexecdir</filename> is different as compared to all
2824 other mainstream distributions, which either uses
2825 <filename>${prefix}/libexec</filename> or
2826 <filename>${libdir}</filename>.
2827 The use is also contrary to the GNU Coding Standards
2828 (i.e. <ulink url='https://www.gnu.org/prep/standards/html_node/Directory-Variables.html'></ulink>)
2829 that suggest <filename>${prefix}/libexec</filename> and also
2830 notes that any package-specific nesting should be done by the
2831 package itself.
2832 Finally, having <filename>libexecdir</filename> change between
2833 recipes makes it very difficult for different recipes to invoke
2834 binaries that have been installed into
2835 <filename>libexecdir</filename>.
2836 The Filesystem Hierarchy Standard
2837 (i.e. <ulink url='http://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html'></ulink>)
2838 now recognizes the use of <filename>${prefix}/libexec/</filename>,
2839 giving distributions the choice between
2840 <filename>${prefix}/lib</filename> or
2841 <filename>${prefix}/libexec</filename> without breaking FHS.
2842 </para>
2843 </section>
2844
2845 <section id='migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files'>
2846 <title><filename>ac_cv_sizeof_off_t</filename> is No Longer Cached in Site Files</title>
2847
2848 <para>
2849 For recipes inheriting the
2850 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2851 class, <filename>ac_cv_sizeof_off_t</filename> is no longer cached
2852 in the site files for <filename>autoconf</filename>.
2853 The reason for this change is because the
2854 <filename>ac_cv_sizeof_off_t</filename> value is not necessarily
2855 static per architecture as was previously assumed.
2856 Rather, the value changes based on whether large file support is
2857 enabled.
2858 For most software that uses <filename>autoconf</filename>, this
2859 change should not be a problem.
2860 However, if you have a recipe that bypasses the standard
2861 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2862 task from the <filename>autotools</filename> class and the software
2863 the recipe is building uses a very old version of
2864 <filename>autoconf</filename>, the recipe might be incapable of
2865 determining the correct size of <filename>off_t</filename> during
2866 <filename>do_configure</filename>.
2867 </para>
2868
2869 <para>
2870 The best course of action is to patch the software as necessary
2871 to allow the default implementation from the
2872 <filename>autotools</filename> class to work such that
2873 <filename>autoreconf</filename> succeeds and produces a working
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002874 configure script, and to remove the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002875 overridden <filename>do_configure</filename> task such that the
2876 default implementation does get used.
2877 </para>
2878 </section>
2879
2880 <section id='migration-2.1-image-generation-split-out-from-filesystem-generation'>
2881 <title>Image Generation is Now Split Out from Filesystem Generation</title>
2882
2883 <para>
2884 Previously, for image recipes the
2885 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
2886 task assembled the filesystem and then from that filesystem
2887 generated images.
2888 With this Yocto Project release, image generation is split into
2889 separate
2890 <link linkend='ref-tasks-image'><filename>do_image_*</filename></link>
2891 tasks for clarity both in operation and in the code.
2892 </para>
2893
2894 <para>
2895 For most cases, this change does not present any problems.
2896 However, if you have made customizations that directly modify the
2897 <filename>do_rootfs</filename> task or that mention
2898 <filename>do_rootfs</filename>, you might need to update those
2899 changes.
2900 In particular, if you had added any tasks after
2901 <filename>do_rootfs</filename>, you should make edits so that
2902 those tasks are after the
2903 <link linkend='ref-tasks-image-complete'><filename>do_image_complete</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002904 task rather than after <filename>do_rootfs</filename>
2905 so that the your added tasks
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002906 run at the correct time.
2907 </para>
2908
2909 <para>
2910 A minor part of this restructuring is that the post-processing
2911 definitions and functions have been moved from the
2912 <link linkend='ref-classes-image'><filename>image</filename></link>
2913 class to the
2914 <link linkend='ref-classes-rootfs*'><filename>rootfs-postcommands</filename></link>
2915 class.
2916 Functionally, however, they remain unchanged.
2917 </para>
2918 </section>
2919
2920 <section id='migration-2.1-removed-recipes'>
2921 <title>Removed Recipes</title>
2922
2923 <para>
2924 The following recipes have been removed in the 2.1 release:
2925 <itemizedlist>
2926 <listitem><para><filename>gcc</filename> version 4.8:
2927 Versions 4.9 and 5.3 remain.
2928 </para></listitem>
2929 <listitem><para><filename>qt4</filename>:
2930 All support for Qt 4.x has been moved out to a separate
2931 <filename>meta-qt4</filename> layer because Qt 4 is no
2932 longer supported upstream.
2933 </para></listitem>
2934 <listitem><para><filename>x11vnc</filename>:
2935 Moved to the <filename>meta-oe</filename> layer.
2936 </para></listitem>
2937 <listitem><para><filename>linux-yocto-3.14</filename>:
2938 No longer supported.
2939 </para></listitem>
2940 <listitem><para><filename>linux-yocto-3.19</filename>:
2941 No longer supported.
2942 </para></listitem>
2943 <listitem><para><filename>libjpeg</filename>:
2944 Replaced by the <filename>libjpeg-turbo</filename> recipe.
2945 </para></listitem>
2946 <listitem><para><filename>pth</filename>:
2947 Became obsolete.
2948 </para></listitem>
2949 <listitem><para><filename>liboil</filename>:
2950 Recipe is no longer needed and has been moved to the
2951 <filename>meta-multimedia</filename> layer.
2952 </para></listitem>
2953 <listitem><para><filename>gtk-theme-torturer</filename>:
2954 Recipe is no longer needed and has been moved to the
2955 <filename>meta-gnome</filename> layer.
2956 </para></listitem>
2957 <listitem><para><filename>gnome-mime-data</filename>:
2958 Recipe is no longer needed and has been moved to the
2959 <filename>meta-gnome</filename> layer.
2960 </para></listitem>
2961 <listitem><para><filename>udev</filename>:
2962 Replaced by the <filename>eudev</filename> recipe for
2963 compatibility when using <filename>sysvinit</filename>
2964 with newer kernels.
2965 </para></listitem>
2966 <listitem><para><filename>python-pygtk</filename>:
2967 Recipe became obsolete.
2968 </para></listitem>
2969 <listitem><para><filename>adt-installer</filename>:
2970 Recipe became obsolete.
2971 See the
2972 "<link linkend='migration-2.1-adt-removed'>ADT Removed</link>"
2973 section for more information.
2974 </para></listitem>
2975 </itemizedlist>
2976 </para>
2977 </section>
2978
2979 <section id='migration-2.1-class-changes'>
2980 <title>Class Changes</title>
2981
2982 <para>
2983 The following classes have changed:
2984 <itemizedlist>
2985 <listitem><para><filename>autotools_stage</filename>:
2986 Removed because the
2987 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2988 class now provides its functionality.
2989 Recipes that inherited from
2990 <filename>autotools_stage</filename> should now inherit
2991 from <filename>autotools</filename> instead.
2992 </para></listitem>
2993 <listitem><para><filename>boot-directdisk</filename>:
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002994 Merged into the <filename>image-vm</filename>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002995 class.
2996 The <filename>boot-directdisk</filename> class was rarely
2997 directly used.
2998 Consequently, this change should not cause any issues.
2999 </para></listitem>
3000 <listitem><para><filename>bootimg</filename>:
3001 Merged into the
3002 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
3003 class.
3004 The <filename>bootimg</filename> class was rarely
3005 directly used.
3006 Consequently, this change should not cause any issues.
3007 </para></listitem>
3008 <listitem><para><filename>packageinfo</filename>:
3009 Removed due to its limited use by the Hob UI, which has
3010 itself been removed.
3011 </para></listitem>
3012 </itemizedlist>
3013 </para>
3014 </section>
3015
3016 <section id='migration-2.1-build-system-ui-changes'>
3017 <title>Build System User Interface Changes</title>
3018
3019 <para>
3020 The following changes have been made to the build system user
3021 interface:
3022 <itemizedlist>
3023 <listitem><para><emphasis>Hob GTK+-based UI</emphasis>:
3024 Removed because it is unmaintained and based on the
3025 outdated GTK+ 2 library.
3026 The Toaster web-based UI is much more capable and is
3027 actively maintained.
3028 See the
3029 "<ulink url='&YOCTO_DOCS_TOAST_URL;#using-the-toaster-web-interface'>Using the Toaster Web Interface</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04003030 section in the Toaster User Manual for more
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003031 information on this interface.
3032 </para></listitem>
3033 <listitem><para><emphasis>"puccho" BitBake UI</emphasis>:
3034 Removed because is unmaintained and no longer useful.
3035 </para></listitem>
3036 </itemizedlist>
3037 </para>
3038 </section>
3039
3040 <section id='migration-2.1-adt-removed'>
3041 <title>ADT Removed</title>
3042
3043 <para>
3044 The Application Development Toolkit (ADT) has been removed
3045 because its functionality almost completely overlapped with the
3046 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-using-the-standard-sdk'>standard SDK</ulink>
3047 and the
3048 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>.
3049 For information on these SDKs and how to build and use them, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003050 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
3051 manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003052 <note>
3053 The Yocto Project Eclipse IDE Plug-in is still supported and
3054 is not affected by this change.
3055 </note>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003056 </para>
3057 </section>
3058
3059 <section id='migration-2.1-poky-reference-distribution-changes'>
3060 <title>Poky Reference Distribution Changes</title>
3061
3062 <para>
3063 The following changes have been made for the Poky distribution:
3064 <itemizedlist>
3065 <listitem><para>
3066 The <filename>meta-yocto</filename> layer has been renamed
3067 to <filename>meta-poky</filename> to better match its
3068 purpose, which is to provide the Poky reference
3069 distribution.
3070 The <filename>meta-yocto-bsp</filename> layer retains its
3071 original name since it provides reference machines for
3072 the Yocto Project and it is otherwise unrelated to Poky.
3073 References to <filename>meta-yocto</filename> in your
3074 <filename>conf/bblayers.conf</filename> should
3075 automatically be updated, so you should not need to change
3076 anything unless you are relying on this naming elsewhere.
3077 </para></listitem>
3078 <listitem><para>
3079 The
3080 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
3081 class is now enabled by default in Poky.
3082 This class attempts to isolate the build system from the
3083 host distribution's C library and makes re-use of native
3084 shared state artifacts across different host distributions
3085 practical.
3086 With this class enabled, a tarball containing a pre-built
3087 C library is downloaded at the start of the build.</para>
3088
3089 <para>The <filename>uninative</filename> class is enabled
3090 through the
3091 <filename>meta/conf/distro/include/yocto-uninative.inc</filename>
3092 file, which for those not using the Poky distribution, can
3093 include to easily enable the same functionality.</para>
3094
3095 <para>Alternatively, if you wish to build your own
3096 <filename>uninative</filename> tarball, you can do so by
3097 building the <filename>uninative-tarball</filename> recipe,
3098 making it available to your build machines
3099 (e.g. over HTTP/HTTPS) and setting a similar configuration
3100 as the one set by <filename>yocto-uninative.inc</filename>.
3101 </para></listitem>
3102 <listitem><para>
3103 Static library generation, for most cases, is now disabled
3104 by default in the Poky distribution.
3105 Disabling this generation saves some build time as well
3106 as the size used for build output artifacts.</para>
3107
3108 <para>Disabling this library generation is accomplished
3109 through a
3110 <filename>meta/conf/distro/include/no-static-libs.inc</filename>,
3111 which for those not using the Poky distribution can
3112 easily include to enable the same functionality.</para>
3113
3114 <para>Any recipe that needs to opt-out of having the
3115 "--disable-static" option specified on the configure
3116 command line either because it is not a supported option
3117 for the configure script or because static libraries are
3118 needed should set the following variable:
3119 <literallayout class='monospaced'>
3120 DISABLE_STATIC = ""
3121 </literallayout>
3122 </para></listitem>
3123 <listitem><para>
3124 The separate <filename>poky-tiny</filename> distribution
3125 now uses the musl C library instead of a heavily pared
3126 down <filename>glibc</filename>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003127 Using musl results in a smaller
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003128 distribution and facilitates much greater maintainability
3129 because musl is designed to have a small footprint.</para>
3130
3131 <para>If you have used <filename>poky-tiny</filename> and
3132 have customized the <filename>glibc</filename>
3133 configuration you will need to redo those customizations
3134 with musl when upgrading to the new release.
3135 </para></listitem>
3136 </itemizedlist>
3137 </para>
3138 </section>
3139
3140 <section id='migration-2.1-packaging-changes'>
3141 <title>Packaging Changes</title>
3142
3143 <para>
3144 The following changes have been made to packaging:
3145 <itemizedlist>
3146 <listitem><para>
3147 The <filename>runuser</filename> and
3148 <filename>mountpoint</filename> binaries, which were
3149 previously in the main <filename>util-linux</filename>
3150 package, have been split out into the
3151 <filename>util-linux-runuser</filename> and
3152 <filename>util-linux-mountpoint</filename> packages,
3153 respectively.
3154 </para></listitem>
3155 <listitem><para>
3156 The <filename>python-elementtree</filename> package has
3157 been merged into the <filename>python-xml</filename>
3158 package.
3159 </para></listitem>
3160 </itemizedlist>
3161 </para>
3162 </section>
3163
3164 <section id='migration-2.1-tuning-file-changes'>
3165 <title>Tuning File Changes</title>
3166
3167 <para>
3168 The following changes have been made to the tuning files:
3169 <itemizedlist>
3170 <listitem><para>
3171 The "no-thumb-interwork" tuning feature has been dropped
3172 from the ARM tune include files.
3173 Because interworking is required for ARM EABI, attempting
3174 to disable it through a tuning feature no longer makes
3175 sense.
3176 <note>
3177 Support for ARM OABI was deprecated in gcc 4.7.
3178 </note>
3179 </para></listitem>
3180 <listitem><para>
3181 The <filename>tune-cortexm*.inc</filename> and
3182 <filename>tune-cortexr4.inc</filename> files have been
3183 removed because they are poorly tested.
3184 Until the OpenEmbedded build system officially gains
3185 support for CPUs without an MMU, these tuning files would
3186 probably be better maintained in a separate layer
3187 if needed.
3188 </para></listitem>
3189 </itemizedlist>
3190 </para>
3191 </section>
3192
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003193 <section id='migration-2.1-supporting-gobject-introspection'>
3194 <title>Supporting GObject Introspection</title>
3195
3196 <para>
3197 This release supports generation of GLib Introspective
3198 Repository (GIR) files through GObject introspection, which is
3199 the standard mechanism for accessing GObject-based software from
3200 runtime environments.
3201 You can enable, disable, and test the generation of this data.
3202 See the
3203 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-gobject-introspection-support'>Enabling GObject Introspection Support</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003204 section in the Yocto Project Development Tasks Manual
3205 for more information.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003206 </para>
3207 </section>
3208
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003209 <section id='migration-2.1-miscellaneous-changes'>
3210 <title>Miscellaneous Changes</title>
3211
3212 <para>
3213 These additional changes exist:
3214 <itemizedlist>
3215 <listitem><para>
3216 The minimum Git version has been increased to 1.8.3.1.
3217 If your host distribution does not provide a sufficiently
3218 recent version, you can install the buildtools, which
3219 will provide it.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003220 See the
3221 "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
3222 section for more information on the buildtools tarball.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003223 </para></listitem>
3224 <listitem><para>
3225 The buggy and incomplete support for the RPM version 4
3226 package manager has been removed.
3227 The well-tested and maintained support for RPM version 5
3228 remains.
3229 </para></listitem>
3230 <listitem><para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003231 Previously, the following list of packages were removed
3232 if package-management was not in
3233 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>,
3234 regardless of any dependencies:
3235 <literallayout class='monospaced'>
3236 update-rc.d
3237 base-passwd
3238 shadow
3239 update-alternatives
3240 run-postinsts
3241 </literallayout>
3242 With the Yocto Project 2.1 release, these packages are only
3243 removed if "read-only-rootfs" is in
3244 <filename>IMAGE_FEATURES</filename>, since they might
3245 still be needed for a read-write image even in the absence
3246 of a package manager (e.g. if users need to be added,
3247 modified, or removed at runtime).
3248 </para></listitem>
3249 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003250 The
3251 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'><filename>devtool modify</filename></ulink>
3252 command now defaults to extracting the source since that
3253 is most commonly expected.
3254 The "-x" or "--extract" options are now no-ops.
3255 If you wish to provide your own existing source tree, you
3256 will now need to specify either the "-n" or
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003257 "--no-extract" options when running
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003258 <filename>devtool modify</filename>.
3259 </para></listitem>
3260 <listitem><para>
3261 If the formfactor for a machine is either not supplied
3262 or does not specify whether a keyboard is attached, then
3263 the default is to assume a keyboard is attached rather
3264 than assume no keyboard.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003265 This change primarily affects the Sato UI.
3266 </para></listitem>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003267 <listitem><para>
3268 The <filename>.debug</filename> directory packaging is
3269 now automatic.
3270 If your recipe builds software that installs binaries into
3271 directories other than the standard ones, you no longer
3272 need to take care of setting
3273 <filename>FILES_${PN}-dbg</filename> to pick up the
3274 resulting <filename>.debug</filename> directories as these
3275 directories are automatically found and added.
3276 </para></listitem>
3277 <listitem><para>
3278 Inaccurate disk and CPU percentage data has been dropped
3279 from <filename>buildstats</filename> output.
3280 This data has been replaced with
3281 <filename>getrusage()</filename> data and corrected IO
3282 statistics.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003283 You will probably need to update any custom code that reads
3284 the <filename>buildstats</filename> data.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003285 </para></listitem>
3286 <listitem><para>
3287 The
3288 <filename>meta/conf/distro/include/package_regex.inc</filename>
3289 is now deprecated.
3290 The contents of this file have been moved to individual
3291 recipes.
3292 <note><title>Tip</title>
3293 Because this file will likely be removed in a future
3294 Yocto Project release, it is suggested that you remove
3295 any references to the file that might be in your
3296 configuration.
3297 </note>
3298 </para></listitem>
3299 <listitem><para>
3300 The <filename>v86d/uvesafb</filename> has been removed from
3301 the <filename>genericx86</filename> and
3302 <filename>genericx86-64</filename> reference machines,
3303 which are provided by the
3304 <filename>meta-yocto-bsp</filename> layer.
3305 Most modern x86 boards do not rely on this file and it only
3306 adds kernel error messages during startup.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003307 If you do still need to support
3308 <filename>uvesafb</filename>, you can
3309 simply add <filename>v86d</filename> to your image.
3310 </para></listitem>
3311 <listitem><para>
3312 Build sysroot paths are now removed from debug symbol
3313 files.
3314 Removing these paths means that remote GDB using an
3315 unstripped build system sysroot will no longer work
3316 (although this was never documented to work).
3317 The supported method to accomplish something similar is
3318 to set <filename>IMAGE_GEN_DEBUGFS</filename> to "1",
3319 which will generate a companion debug image
3320 containing unstripped binaries and associated debug
3321 sources alongside the image.
3322 </para></listitem>
3323 </itemizedlist>
3324 </para>
3325 </section>
3326</section>
3327
3328<section id='moving-to-the-yocto-project-2.2-release'>
3329 <title>Moving to the Yocto Project 2.2 Release</title>
3330
3331 <para>
3332 This section provides migration information for moving to the
3333 Yocto Project 2.2 Release from the prior release.
3334 </para>
3335
3336 <section id='migration-2.2-minimum-kernel-version'>
3337 <title>Minimum Kernel Version</title>
3338
3339 <para>
3340 The minimum kernel version for the target system and for SDK
3341 is now 3.2.0, due to the upgrade
3342 to <filename>glibc 2.24</filename>.
3343 Specifically, for AArch64-based targets the version is
3344 3.14.
3345 For Nios II-based targets, the minimum kernel version is 3.19.
3346 <note>
3347 For x86 and x86_64, you can reset
3348 <link linkend='var-OLDEST_KERNEL'><filename>OLDEST_KERNEL</filename></link>
3349 to anything down to 2.6.32 if desired.
3350 </note>
3351 </para>
3352 </section>
3353
3354 <section id='migration-2.2-staging-directories-in-sysroot-simplified'>
3355 <title>Staging Directories in Sysroot Has Been Simplified</title>
3356
3357 <para>
3358 The way directories are staged in sysroot has been simplified and
3359 introduces the new
3360 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>,
3361 <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>,
3362 and
3363 <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link>.
3364 See the
3365 <ulink url='http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html'>v2 patch series on the OE-Core Mailing List</ulink>
3366 for additional information.
3367 </para>
3368 </section>
3369
3370 <section id='migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled'>
3371 <title>Removal of Old Images and Other Files in <filename>tmp/deploy</filename> Now Enabled</title>
3372
3373 <para>
3374 Removal of old images and other files in
3375 <filename>tmp/deploy/</filename> is now enabled by default due
3376 to a new staging method used for those files.
3377 As a result of this change, the
3378 <filename>RM_OLD_IMAGE</filename> variable is now redundant.
3379 </para>
3380 </section>
3381
3382 <section id='migration-2.2-python-changes'>
3383 <title>Python Changes</title>
3384
3385 <para>
3386 The following changes for Python occurred:
3387 </para>
3388
3389 <section id='migration-2.2-bitbake-now-requires-python-3.4'>
3390 <title>BitBake Now Requires Python 3.4+</title>
3391
3392 <para>
3393 BitBake requires Python 3.4 or greater.
3394 </para>
3395 </section>
3396
3397 <section id='migration-2.2-utf-8-locale-required-on-build-host'>
3398 <title>UTF-8 Locale Required on Build Host</title>
3399
3400 <para>
3401 A UTF-8 locale is required on the build host due to Python 3.
3402 Since C.UTF-8 is not a standard, the default is en_US.UTF-8.
3403 </para>
3404 </section>
3405
3406 <section id='migration-2.2-metadata-now-must-use-python-3-syntax'>
3407 <title>Metadata Must Now Use Python 3 Syntax</title>
3408
3409 <para>
3410 The metadata is now required to use Python 3 syntax.
3411 For help preparing metadata, see any of the many Python 3 porting
3412 guides available.
3413 Alternatively, you can reference the conversion commits for Bitbake
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003414 and you can use
3415 <link linkend='oe-core'>OE-Core</link> as a guide for changes.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003416 Following are particular areas of interest:
3417 <literallayout class='monospaced'>
3418 * subprocess command-line pipes needing locale decoding
3419 * the syntax for octal values changed
3420 * the <filename>iter*()</filename> functions changed name
3421 * iterators now return views, not lists
3422 * changed names for Python modules
3423 </literallayout>
3424 </para>
3425 </section>
3426
3427 <section id='migration-2.2-target-python-recipes-switched-to-python-3'>
3428 <title>Target Python Recipes Switched to Python 3</title>
3429
3430 <para>
3431 Most target Python recipes have now been switched to Python 3.
3432 Unfortunately, systems using RPM as a package manager and
3433 providing online package-manager support through SMART still
3434 require Python 2.
3435 <note>
3436 Python 2 and recipes that use it can still be built for the
3437 target as with previous versions.
3438 </note>
3439 </para>
3440 </section>
3441
3442 <section id='migration-2.2-buildtools-tarball-includes-python-3'>
3443 <title><filename>buildtools-tarball</filename> Includes Python 3</title>
3444
3445 <para>
3446 <filename>buildtools-tarball</filename> now includes Python 3.
3447 </para>
3448 </section>
3449 </section>
3450
3451 <section id='migration-2.2-uclibc-replaced-by-musl'>
3452 <title>uClibc Replaced by musl</title>
3453
3454 <para>
3455 uClibc has been removed in favor of musl.
3456 Musl has matured, is better maintained, and is compatible with a
3457 wider range of applications as compared to uClibc.
3458 </para>
3459 </section>
3460
3461 <section id='migration-2.2-B-no-longer-default-working-directory-for-tasks'>
3462 <title><filename>${B}</filename> No Longer Default Working Directory for Tasks</title>
3463
3464 <para>
3465 <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>
3466 is no longer the default working directory for tasks.
3467 Consequently, any custom tasks you define now need to either
3468 have the
3469 <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
3470 appropriate working directory manually (e.g using
3471 <filename>cd</filename> for a shell task).
3472 <note>
3473 The preferred method is to use the
3474 <filename>[dirs]</filename> flag.
3475 </note>
3476 </para>
3477 </section>
3478
3479 <section id='migration-2.2-runqemu-ported-to-python'>
3480 <title><filename>runqemu</filename> Ported to Python</title>
3481
3482 <para>
3483 <filename>runqemu</filename> has been ported to Python and has
3484 changed behavior in some cases.
Brad Bishop37a0e4d2017-12-04 01:01:44 -05003485 Previous usage patterns continue to be supported.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003486 </para>
3487
3488 <para>
3489 The new <filename>runqemu</filename> is a Python script.
3490 Machine knowledge is no longer hardcoded into
3491 <filename>runqemu</filename>.
3492 You can choose to use the <filename>qemuboot</filename>
3493 configuration file to define the BSP's own arguments and to make
3494 it bootable with <filename>runqemu</filename>.
3495 If you use a configuration file, use the following form:
3496 <literallayout class='monospaced'>
3497 <replaceable>image-name</replaceable>-<replaceable>machine</replaceable>.qemuboot.conf
3498 </literallayout>
3499 The configuration file enables fine-grained tuning of options
3500 passed to QEMU without the <filename>runqemu</filename> script
3501 hard-coding any knowledge about different machines.
3502 Using a configuration file is particularly convenient when trying
3503 to use QEMU with machines other than the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003504 <filename>qemu*</filename> machines in
3505 <link linkend='oe-core'>OE-Core</link>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003506 The <filename>qemuboot.conf</filename> file is generated by the
3507 <filename>qemuboot</filename>
3508 class when the root filesystem is being build (i.e.
3509 build rootfs).
3510 QEMU boot arguments can be set in BSP's configuration file and
3511 the <filename>qemuboot</filename> class will save them to
3512 <filename>qemuboot.conf</filename>.
3513 </para>
3514
3515
3516 <para>
3517 If you want to use <filename>runqemu</filename> without a
3518 configuration file, use the following command form:
3519 <literallayout class='monospaced'>
3520 $ runqemu <replaceable>machine</replaceable> <replaceable>rootfs</replaceable> <replaceable>kernel</replaceable> [<replaceable>options</replaceable>]
3521 </literallayout>
3522 Supported <replaceable>machines</replaceable> are as follows:
3523 <literallayout class='monospaced'>
3524 qemuarm
3525 qemuarm64
3526 qemux86
3527 qemux86-64
3528 qemuppc
3529 qemumips
3530 qemumips64
3531 qemumipsel
3532 qemumips64el
3533 </literallayout>
3534 Consider the following example, which uses the
3535 <filename>qemux86-64</filename> machine,
3536 provides a root filesystem, provides an image, and uses
3537 the <filename>nographic</filename> option:
3538 <literallayout class='monospaced'>
3539$ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
3540 </literallayout>
3541 </para>
3542
3543 <para>
3544 Following is a list of variables that can be set in configuration
3545 files such as <filename>bsp.conf</filename> to enable the BSP
3546 to be booted by <filename>runqemu</filename>:
3547 <note>
3548 "QB" means "QEMU Boot".
3549 </note>
3550 <literallayout class='monospaced'>
3551 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
3552 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
3553 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
3554 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
3555 QB_MEM: Memory (e.g. "-m 512")
3556 QB_MACHINE: QEMU machine (e.g. "-machine virt")
3557 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
3558 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
3559 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
3560 option (e.g. "console=ttyS0 console=tty")
3561 QB_DTB: QEMU dtb name
3562 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
3563 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
3564 when QB_AUDIO_DRV is set.
3565 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
3566 QB_TAP_OPT: Network option for 'tap' mode (e.g.
3567 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
3568 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
3569 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
3570 QB_ROOTFS_OPT: Used as rootfs (e.g.
3571 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
3572 runqemu will replace "@ROOTFS@" with the one which is used, such as
3573 core-image-minimal-qemuarm64.ext4.
3574 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
3575 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
3576 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
3577 runqemu will replace "@PORT@" with the port number which is used.
3578 </literallayout>
3579 </para>
3580
3581 <para>
3582 To use <filename>runqemu</filename>, set
3583 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
3584 as follows and run <filename>runqemu</filename>:
3585 <note>
3586 For command-line syntax, use
3587 <filename>runqemu help</filename>.
3588 </note>
3589 <literallayout class='monospaced'>
3590 IMAGE_CLASSES += "qemuboot"
3591 </literallayout>
3592 </para>
3593 </section>
3594
3595 <section id='migration-2.2-default-linker-hash-style-changed'>
3596 <title>Default Linker Hash Style Changed</title>
3597
3598 <para>
3599 The default linker hash style for <filename>gcc-cross</filename>
3600 is now "sysv" in order to catch recipes that are building software
3601 without using the OpenEmbedded
3602 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>.
3603 This change could result in seeing some "No GNU_HASH in the elf
3604 binary" QA issues when building such recipes.
3605 You need to fix these recipes so that they use the expected
3606 <filename>LDFLAGS</filename>.
3607 Depending on how the software is built, the build system used by
3608 the software (e.g. a Makefile) might need to be patched.
3609 However, sometimes making this fix is as simple as adding the
3610 following to the recipe:
3611 <literallayout class='monospaced'>
3612 TARGET_CC_ARCH += "${LDFLAGS}"
3613 </literallayout>
3614 </para>
3615 </section>
3616
Brad Bishop37a0e4d2017-12-04 01:01:44 -05003617 <section id='migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype'>
3618 <title><filename>KERNEL_IMAGE_BASE_NAME</filename> no Longer Uses <filename>KERNEL_IMAGETYPE</filename></title>
3619
3620 <para>
3621 The
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08003622 <filename>KERNEL_IMAGE_BASE_NAME</filename>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05003623 variable no longer uses the
3624 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
3625 variable to create the image's base name.
3626 Because the OpenEmbedded build system can now build multiple kernel
3627 image types, this part of the kernel image base name as been
3628 removed leaving only the following:
3629 <literallayout class='monospaced'>
3630 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}
3631 </literallayout>
3632 If you have recipes or classes that use
3633 <filename>KERNEL_IMAGE_BASE_NAME</filename> directly, you might
3634 need to update the references to ensure they continue to work.
3635 </para>
3636 </section>
3637
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003638 <section id='migration-2.2-bitbake-changes'>
3639 <title>BitBake Changes</title>
3640
3641 <para>
3642 The following changes took place for BitBake:
3643 <itemizedlist>
3644 <listitem><para>
3645 The "goggle" UI and standalone image-writer tool have
3646 been removed as they both require GTK+ 2.0 and
3647 were not being maintained.
3648 </para></listitem>
3649 <listitem><para>
3650 The Perforce fetcher now supports
3651 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
3652 for specifying the source revision to use, be it
3653 <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename>,
3654 changelist number, p4date, or label, in preference to
3655 separate
3656 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
3657 parameters to specify these.
3658 This change is more in-line with how the other fetchers
3659 work for source control systems.
3660 Recipes that fetch from Perforce will need to be updated
3661 to use <filename>SRCREV</filename> in place of specifying
3662 the source revision within
3663 <filename>SRC_URI</filename>.
3664 </para></listitem>
3665 <listitem><para>
3666 Some of BitBake's internal code structures for accessing
3667 the recipe cache needed to be changed to support the new
3668 multi-configuration functionality.
3669 These changes will affect external tools that use BitBake's
3670 tinfoil module.
3671 For information on these changes, see the changes made to
3672 the scripts supplied with OpenEmbedded-Core:
3673 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee'>1</ulink>
3674 and
3675 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67'>2</ulink>.
3676 </para></listitem>
3677 <listitem><para>
3678 The task management code has been rewritten to avoid using
3679 ID indirection in order to improve performance.
3680 This change is unlikely to cause any problems for most
3681 users.
3682 However, the setscene verification function as pointed to
3683 by <filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
3684 needed to change signature.
3685 Consequently, a new variable named
Brad Bishop6e60e8b2018-02-01 10:27:11 -05003686 <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003687 has been added allowing multiple versions of BitBake
3688 to work with suitably written metadata, which includes
3689 OpenEmbedded-Core and Poky.
3690 Anyone with custom BitBake task scheduler code might also
3691 need to update the code to handle the new structure.
3692 </para></listitem>
3693 </itemizedlist>
3694 </para>
3695 </section>
3696
3697 <section id='migration-2.2-swabber-has-been-removed'>
3698 <title>Swabber has Been Removed</title>
3699
3700 <para>
3701 Swabber, a tool that was intended to detect host contamination in
3702 the build process, has been removed, as it has been unmaintained
3703 and unused for some time and was never particularly effective.
3704 The OpenEmbedded build system has since incorporated a number of
3705 mechanisms including enhanced QA checks that mean that there is
3706 less of a need for such a tool.
3707 </para>
3708 </section>
3709
3710 <section id='migration-2.2-removed-recipes'>
3711 <title>Removed Recipes</title>
3712
3713 <para>
3714 The following recipes have been removed:
3715 <itemizedlist>
3716 <listitem><para>
3717 <filename>augeas</filename>:
3718 No longer needed and has been moved to
3719 <filename>meta-oe</filename>.
3720 </para></listitem>
3721 <listitem><para>
3722 <filename>directfb</filename>:
3723 Unmaintained and has been moved to
3724 <filename>meta-oe</filename>.
3725 </para></listitem>
3726 <listitem><para>
3727 <filename>gcc</filename>:
3728 Removed 4.9 version.
3729 Versions 5.4 and 6.2 are still present.
3730 </para></listitem>
3731 <listitem><para>
3732 <filename>gnome-doc-utils</filename>:
3733 No longer needed.
3734 </para></listitem>
3735 <listitem><para>
3736 <filename>gtk-doc-stub</filename>:
3737 Replaced by <filename>gtk-doc</filename>.
3738 </para></listitem>
3739 <listitem><para>
3740 <filename>gtk-engines</filename>:
3741 No longer needed and has been moved to
3742 <filename>meta-gnome</filename>.
3743 </para></listitem>
3744 <listitem><para>
3745 <filename>gtk-sato-engine</filename>:
3746 Became obsolete.
3747 </para></listitem>
3748 <listitem><para>
3749 <filename>libglade</filename>:
3750 No longer needed and has been moved to
3751 <filename>meta-oe</filename>.
3752 </para></listitem>
3753 <listitem><para>
3754 <filename>libmad</filename>:
3755 Unmaintained and functionally replaced by
3756 <filename>libmpg123</filename>.
3757 <filename>libmad</filename> has been moved to
3758 <filename>meta-oe</filename>.
3759 </para></listitem>
3760 <listitem><para>
3761 <filename>libowl</filename>:
3762 Became obsolete.
3763 </para></listitem>
3764 <listitem><para>
3765 <filename>libxsettings-client</filename>:
3766 No longer needed.
3767 </para></listitem>
3768 <listitem><para>
3769 <filename>oh-puzzles</filename>:
3770 Functionally replaced by
3771 <filename>puzzles</filename>.
3772 </para></listitem>
3773 <listitem><para>
3774 <filename>oprofileui</filename>:
3775 Became obsolete.
3776 OProfile has been largely supplanted by perf.
3777 </para></listitem>
3778 <listitem><para>
3779 <filename>packagegroup-core-directfb.bb</filename>:
3780 Removed.
3781 </para></listitem>
3782 <listitem><para>
3783 <filename>core-image-directfb.bb</filename>:
3784 Removed.
3785 </para></listitem>
3786 <listitem><para>
3787 <filename>pointercal</filename>:
3788 No longer needed and has been moved to
3789 <filename>meta-oe</filename>.
3790 </para></listitem>
3791 <listitem><para>
3792 <filename>python-imaging</filename>:
3793 No longer needed and moved to
3794 <filename>meta-python</filename>
3795 </para></listitem>
3796 <listitem><para>
3797 <filename>python-pyrex</filename>:
3798 No longer needed and moved to
3799 <filename>meta-python</filename>.
3800 </para></listitem>
3801 <listitem><para>
3802 <filename>sato-icon-theme</filename>:
3803 Became obsolete.
3804 </para></listitem>
3805 <listitem><para>
3806 <filename>swabber-native</filename>:
3807 Swabber has been removed.
3808 See the
3809 <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>.
3810 </para></listitem>
3811 <listitem><para>
3812 <filename>tslib</filename>:
3813 No longer needed and has been moved to
3814 <filename>meta-oe</filename>.
3815 </para></listitem>
3816 <listitem><para>
3817 <filename>uclibc</filename>:
3818 Removed in favor of musl.
3819 </para></listitem>
3820 <listitem><para>
3821 <filename>xtscal</filename>:
3822 No longer needed and moved to
3823 <filename>meta-oe</filename>
3824 </para></listitem>
3825 </itemizedlist>
3826 </para>
3827 </section>
3828
3829 <section id='migration-2.2-removed-classes'>
3830 <title>Removed Classes</title>
3831
3832 <para>
3833 The following classes have been removed:
3834 <itemizedlist>
3835 <listitem><para>
3836 <filename>distutils-native-base</filename>:
3837 No longer needed.
3838 </para></listitem>
3839 <listitem><para>
3840 <filename>distutils3-native-base</filename>:
3841 No longer needed.
3842 </para></listitem>
3843 <listitem><para>
3844 <filename>sdl</filename>:
3845 Only set
3846 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
3847 and
3848 <link linkend='var-SECTION'><filename>SECTION</filename></link>,
3849 which are better set within the recipe instead.
3850 </para></listitem>
3851 <listitem><para>
3852 <filename>sip</filename>:
3853 Mostly unused.
3854 </para></listitem>
3855 <listitem><para>
3856 <filename>swabber</filename>:
3857 See the
3858 <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>.
3859 </para></listitem>
3860 </itemizedlist>
3861 </para>
3862 </section>
3863
3864 <section id='migration-2.2-minor-packaging-changes'>
3865 <title>Minor Packaging Changes</title>
3866
3867 <para>
3868 The following minor packaging changes have occurred:
3869 <itemizedlist>
3870 <listitem><para>
3871 <filename>grub</filename>:
3872 Split <filename>grub-editenv</filename> into its own
3873 package.
3874 </para></listitem>
3875 <listitem><para>
3876 <filename>systemd</filename>:
3877 Split container and vm related units into a new package,
3878 systemd-container.
3879 </para></listitem>
3880 <listitem><para>
3881 <filename>util-linux</filename>:
3882 Moved <filename>prlimit</filename> to a separate
3883 <filename>util-linux-prlimit</filename> package.
3884 </para></listitem>
3885 </itemizedlist>
3886 </para>
3887 </section>
3888
3889 <section id='migration-2.2-miscellaneous-changes'>
3890 <title>Miscellaneous Changes</title>
3891
3892 <para>
3893 The following miscellaneous changes have occurred:
3894 <itemizedlist>
3895 <listitem><para>
3896 <filename>package_regex.inc</filename>:
3897 Removed because the definitions
3898 <filename>package_regex.inc</filename> previously contained
3899 have been moved to their respective recipes.
3900 </para></listitem>
3901 <listitem><para>
3902 Both <filename>devtool add</filename> and
3903 <filename>recipetool create</filename> now use a fixed
3904 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
3905 by default when fetching from a Git repository.
3906 You can override this in either case to use
3907 <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename>
3908 instead by using the <filename>-a</filename> or
3909 <filename>&dash;&dash;autorev</filename> command-line
3910 option
3911 </para></listitem>
3912 <listitem><para>
3913 <filename>distcc</filename>:
3914 GTK+ UI is now disabled by default.
3915 </para></listitem>
3916 <listitem><para>
3917 <filename>packagegroup-core-tools-testapps</filename>:
3918 Removed Piglit.
3919 </para></listitem>
3920 <listitem><para>
3921 <filename>image.bbclass</filename>:
3922 Renamed COMPRESS(ION) to CONVERSION.
3923 This change means that
3924 <filename>COMPRESSIONTYPES</filename>,
3925 <filename>COMPRESS_DEPENDS</filename> and
3926 <filename>COMPRESS_CMD</filename> are deprecated in favor
3927 of <filename>CONVERSIONTYPES</filename>,
3928 <filename>CONVERSION_DEPENDS</filename> and
3929 <filename>CONVERSION_CMD</filename>.
3930 The <filename>COMPRESS*</filename> variable names will
3931 still work in the 2.2 release but metadata that does not
3932 need to be backwards-compatible should be changed to
3933 use the new names as the <filename>COMPRESS*</filename>
3934 ones will be removed in a future release.
3935 </para></listitem>
3936 <listitem><para>
3937 <filename>gtk-doc</filename>:
3938 A full version of <filename>gtk-doc</filename> is now
3939 made available.
3940 However, some old software might not be capable of using
3941 the current version of <filename>gtk-doc</filename>
3942 to build documentation.
3943 You need to change recipes that build such software so that
3944 they explicitly disable building documentation with
3945 <filename>gtk-doc</filename>.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003946 </para></listitem>
3947 </itemizedlist>
3948 </para>
3949 </section>
3950</section>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003951
Brad Bishop6e60e8b2018-02-01 10:27:11 -05003952<section id='moving-to-the-yocto-project-2.3-release'>
3953 <title>Moving to the Yocto Project 2.3 Release</title>
3954
3955 <para>
3956 This section provides migration information for moving to the
3957 Yocto Project 2.3 Release from the prior release.
3958 </para>
3959
3960 <section id='migration-2.3-recipe-specific-sysroots'>
3961 <title>Recipe-specific Sysroots</title>
3962
3963 <para>
3964 The OpenEmbedded build system now uses one sysroot per
3965 recipe to resolve long-standing issues with configuration
3966 script auto-detection of undeclared dependencies.
3967 Consequently, you might find that some of your previously
3968 written custom recipes are missing declared dependencies,
3969 particularly those dependencies that are incidentally built
3970 earlier in a typical build process and thus are already likely
3971 to be present in the shared sysroot in previous releases.
3972 </para>
3973
3974 <para>
3975 Consider the following:
3976 <itemizedlist>
3977 <listitem><para>
3978 <emphasis>Declare Build-Time Dependencies:</emphasis>
3979 Because of this new feature, you must explicitly
3980 declare all build-time dependencies for your recipe.
3981 If you do not declare these dependencies, they are not
3982 populated into the sysroot for the recipe.
3983 </para></listitem>
3984 <listitem><para>
3985 <emphasis>Specify Pre-Installation and Post-Installation
3986 Native Tool Dependencies:</emphasis>
3987 You must specifically specify any special native tool
3988 dependencies of <filename>pkg_preinst</filename> and
3989 <filename>pkg_postinst</filename> scripts by using the
3990 <link linkend='var-PACKAGE_WRITE_DEPS'><filename>PACKAGE_WRITE_DEPS</filename></link>
3991 variable.
3992 Specifying these dependencies ensures that these tools
3993 are available if these scripts need to be run on the
3994 build host during the
3995 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
3996 task.</para>
3997
3998 <para>As an example, see the <filename>dbus</filename>
3999 recipe.
4000 You will see that this recipe has a
4001 <filename>pkg_postinst</filename> that calls
4002 <filename>systemctl</filename> if "systemd" is in
4003 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
4004 In the example,
4005 <filename>systemd-systemctl-native</filename> is added to
4006 <filename>PACKAGE_WRITE_DEPS</filename>, which is also
4007 conditional on "systemd" being in
4008 <filename>DISTRO_FEATURES</filename>.
4009 </para></listitem>
4010 <listitem><para>
4011 <emphasis>Examine Recipes that Use
4012 <filename>SSTATEPOSTINSTFUNCS</filename>:</emphasis>
4013 You need to examine any recipe that uses
4014 <filename>SSTATEPOSTINSTFUNCS</filename> and determine
4015 steps to take.</para>
4016
4017 <para>Functions added to
4018 <filename>SSTATEPOSTINSTFUNCS</filename> are still
4019 called as they were in previous Yocto Project releases.
4020 However, since a separate sysroot is now being populated
4021 for every recipe and if existing functions being called
4022 through <filename>SSTATEPOSTINSTFUNCS</filename> are
4023 doing relocation, then you will need to change these
4024 to use a post-installation script that is installed by a
4025 function added to
4026 <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link>.
4027 </para>
4028
4029 <para>For an example, see the
4030 <filename>pixbufcache</filename> class in
4031 <filename>meta/classes/</filename> in the Yocto Project
Brad Bishop316dfdd2018-06-25 12:45:53 -04004032 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>.
Brad Bishop6e60e8b2018-02-01 10:27:11 -05004033 <note>
4034 The <filename>SSTATEPOSTINSTFUNCS</filename> variable
4035 itself is now deprecated in favor of the
4036 <filename>do_populate_sysroot[postfuncs]</filename>
4037 task.
4038 Consequently, if you do still have any function or
4039 functions that need to be called after the sysroot
4040 component is created for a recipe, then you would be
4041 well advised to take steps to use a post installation
4042 script as described previously.
4043 Taking these steps prepares your code for when
4044 <filename>SSTATEPOSTINSTFUNCS</filename> is
4045 removed in a future Yocto Project release.
4046 </note>
4047 </para></listitem>
4048 <listitem><para>
4049 <emphasis>Specify the Sysroot when Using Certain
4050 External Scripts:</emphasis>
4051 Because the shared sysroot is now gone, the scripts
4052 <filename>oe-find-native-sysroot</filename> and
4053 <filename>oe-run-native</filename> have been changed such
4054 that you need to specify which recipe's
4055 <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>
4056 is used.
4057 </para></listitem>
4058 </itemizedlist>
4059 <note>
4060 You can find more information on how recipe-specific sysroots
4061 work in the
4062 "<link linkend='ref-classes-staging'><filename>staging.bbclass</filename></link>"
4063 section.
4064 </note>
4065 </para>
4066 </section>
4067
4068 <section id='migration-2.3-path-variable'>
4069 <title><filename>PATH</filename> Variable</title>
4070
4071 <para>
4072 Within the environment used to run build tasks, the environment
4073 variable <filename>PATH</filename> is now sanitized such that
4074 the normal native binary paths
4075 (<filename>/bin</filename>, <filename>/sbin</filename>,
4076 <filename>/usr/bin</filename> and so forth) are
4077 removed and a directory containing symbolic links linking only
4078 to the binaries from the host mentioned in the
4079 <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>
4080 and
4081 <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>
4082 variables is added to <filename>PATH</filename>.
4083 </para>
4084
4085 <para>
4086 Consequently, any native binaries provided by the host that you
4087 need to call needs to be in one of these two variables at
4088 the configuration level.
4089 </para>
4090
4091 <para>
4092 Alternatively, you can add a native recipe (i.e.
4093 <filename>-native</filename>) that provides the
4094 binary to the recipe's
4095 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
4096 value.
4097 <note>
4098 <filename>PATH</filename> is not sanitized in the same way
4099 within <filename>devshell</filename>.
4100 If it were, you would have difficulty running host tools for
4101 development and debugging within the shell.
4102 </note>
4103 </para>
4104 </section>
4105
4106 <section id='migration-2.3-scripts'>
4107 <title>Changes to Scripts</title>
4108
4109 <para>
4110 The following changes to scripts took place:
4111 <itemizedlist>
4112 <listitem><para>
4113 <emphasis><filename>oe-find-native-sysroot</filename>:</emphasis>
4114 The usage for the
4115 <filename>oe-find-native-sysroot</filename> script has
4116 changed to the following:
4117 <literallayout class='monospaced'>
4118 $ . oe-find-native-sysroot <replaceable>recipe</replaceable>
4119 </literallayout>
4120 You must now supply a recipe for
4121 <replaceable>recipe</replaceable> as part of the command.
4122 Prior to the Yocto Project &DISTRO; release, it was not
4123 necessary to provide the script with the command.
4124 </para></listitem>
4125 <listitem><para>
4126 <emphasis><filename>oe-run-native</filename>:</emphasis>
4127 The usage for the
4128 <filename>oe-run-native</filename> script has changed
4129 to the following:
4130 <literallayout class='monospaced'>
4131 $ oe-run-native <replaceable>native_recipe</replaceable> <replaceable>tool</replaceable>
4132 </literallayout>
4133 You must supply the name of the native recipe and the tool
4134 you want to run as part of the command.
4135 Prior to the Yocto Project &DISTRO; release, it was not
4136 necessary to provide the native recipe with the command.
4137 </para></listitem>
4138 <listitem><para>
4139 <emphasis><filename>cleanup-workdir</filename>:</emphasis>
4140 The <filename>cleanup-workdir</filename> script has been
4141 removed because the script was found to be deleting
4142 files it should not have, which lead to broken build
4143 trees.
4144 Rather than trying to delete portions of
4145 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
4146 and getting it wrong, it is recommended that you
4147 delete <filename>TMPDIR</filename> and have it restored
4148 from shared state (sstate) on subsequent builds.
4149 </para></listitem>
4150 <listitem><para>
4151 <emphasis><filename>wipe-sysroot</filename>:</emphasis>
4152 The <filename>wipe-sysroot</filename> script has been
4153 removed as it is no longer needed with recipe-specific
4154 sysroots.
4155 </para></listitem>
4156 </itemizedlist>
4157 </para>
4158 </section>
4159
4160 <section id='migration-2.3-functions'>
4161 <title>Changes to Functions</title>
4162
4163 <para>
4164 The previously deprecated
4165 <filename>bb.data.getVar()</filename>,
4166 <filename>bb.data.setVar()</filename>, and
4167 related functions have been removed in favor of
4168 <filename>d.getVar()</filename>,
4169 <filename>d.setVar()</filename>, and so forth.
4170 </para>
4171
4172 <para>
4173 You need to fix any references to these old functions.
4174 </para>
4175 </section>
4176
4177 <section id='migration-2.3-bitbake-changes'>
4178 <title>BitBake Changes</title>
4179
4180 <para>
4181 The following changes took place for BitBake:
4182 <itemizedlist>
4183 <listitem><para>
4184 <emphasis>BitBake's Graphical Dependency Explorer UI Replaced:</emphasis>
4185 BitBake's graphical dependency explorer UI
4186 <filename>depexp</filename> was replaced by
4187 <filename>taskexp</filename> ("Task Explorer"), which
4188 provides a graphical way of exploring the
4189 <filename>task-depends.dot</filename> file.
4190 The data presented by Task Explorer is much more
4191 accurate than the data that was presented by
4192 <filename>depexp</filename>.
4193 Being able to visualize the data is an often requested
4194 feature as standard <filename>*.dot</filename> file
4195 viewers cannot usual cope with the size of
4196 the <filename>task-depends.dot</filename> file.
4197 </para></listitem>
4198 <listitem><para>
4199 <emphasis>BitBake "-g" Output Changes:</emphasis>
4200 The <filename>package-depends.dot</filename> and
4201 <filename>pn-depends.dot</filename> files as previously
4202 generated using the <filename>bitbake -g</filename> command
4203 have been removed.
4204 A <filename>recipe-depends.dot</filename> file
4205 is now generated as a collapsed version of
4206 <filename>task-depends.dot</filename> instead.
4207 </para>
4208
4209 <para>The reason for this change is because
4210 <filename>package-depends.dot</filename> and
4211 <filename>pn-depends.dot</filename> largely date back
4212 to a time before task-based execution and do not take
4213 into account task-level dependencies between recipes,
4214 which could be misleading.
4215 </para></listitem>
4216 <listitem><para>
4217 <emphasis>Mirror Variable Splitting Changes:</emphasis>
4218 Mirror variables including
4219 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>,
4220 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
4221 and
4222 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
4223 can now separate values entirely with spaces.
4224 Consequently, you no longer need "\\n".
4225 BitBake looks for pairs of values, which simplifies usage.
4226 There should be no change required to existing mirror
4227 variable values themselves.
4228 </para></listitem>
4229 <listitem><para>
4230 <emphasis>The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an "rsh" Parameter:</emphasis>
4231 The SVN fetcher now takes an "ssh" parameter instead of an
4232 "rsh" parameter.
4233 This new optional parameter is used when the "protocol"
4234 parameter is set to "svn+ssh".
4235 You can only use the new parameter to specify the
4236 <filename>ssh</filename> program used by SVN.
4237 The SVN fetcher passes the new parameter through the
4238 <filename>SVN_SSH</filename> environment variable during
4239 the
4240 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
4241 task.</para>
4242
4243 <para>See the
4244 "<ulink url='&YOCTO_DOCS_BB_URL;#svn-fetcher'>Subversion (SVN) Fetcher (svn://)</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04004245 section in the BitBake User Manual for additional
4246 information.
Brad Bishop6e60e8b2018-02-01 10:27:11 -05004247 </para></listitem>
4248 <listitem><para>
4249 <emphasis><filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
4250 and <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename>
4251 Removed:</emphasis>
4252 Because the mechanism they were part of is no longer
4253 necessary with recipe-specific sysroots, the
4254 <filename>BB_SETSCENE_VERIFY_FUNCTION</filename> and
4255 <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename>
4256 variables have been removed.
4257 </para></listitem>
4258 </itemizedlist>
4259 </para>
4260 </section>
4261
4262 <section id='migration-2.3-absolute-symlinks'>
4263 <title>Absolute Symbolic Links</title>
4264
4265 <para>
4266 Absolute symbolic links (symlinks) within staged files are no
4267 longer permitted and now trigger an error.
4268 Any explicit creation of symlinks can use the
4269 <filename>lnr</filename> script, which is a replacement for
4270 <filename>ln -r</filename>.
4271 </para>
4272
4273 <para>
4274 If the build scripts in the software that the recipe is building
4275 are creating a number of absolute symlinks that need to be
4276 corrected, you can inherit
4277 <filename>relative_symlinks</filename> within the recipe to turn
4278 those absolute symlinks into relative symlinks.
4279 </para>
4280 </section>
4281
4282 <section id='migration-2.3-gplv2-and-gplv3-moves'>
4283 <title>GPLv2 Versions of GPLv3 Recipes Moved</title>
4284
4285 <para>
4286 Older GPLv2 versions of GPLv3 recipes have moved to a
4287 separate <filename>meta-gplv2</filename> layer.
4288 </para>
4289
4290 <para>
4291 If you use
4292 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>
4293 to exclude GPLv3 or set
4294 <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
4295 to substitute a GPLv2 version of a GPLv3 recipe, then you must add
4296 the <filename>meta-gplv2</filename> layer to your configuration.
4297 <note>
4298 You can find <filename>meta-gplv2</filename> layer in the
4299 OpenEmbedded layer index at
4300 <ulink url='https://layers.openembedded.org/layerindex/branch/master/layer/meta-gplv2/'></ulink>.
4301 </note>
4302 </para>
4303
4304 <para>
4305 These relocated GPLv2 recipes do not receive the same level of
4306 maintenance as other core recipes.
4307 The recipes do not get security fixes and upstream no longer
4308 maintains them.
4309 In fact, the upstream community is actively hostile towards people
4310 that use the old versions of the recipes.
4311 Moving these recipes into a separate layer both makes the different
4312 needs of the recipes clearer and clearly identifies the number of
4313 these recipes.
4314 <note>
4315 The long-term solution might be to move to BSD-licensed
4316 replacements of the GPLv3 components for those that need to
4317 exclude GPLv3-licensed components from the target system.
4318 This solution will be investigated for future Yocto
4319 Project releases.
4320 </note>
4321 </para>
4322 </section>
4323
4324 <section id='migration-2.3-package-management-changes'>
4325 <title>Package Management Changes</title>
4326
4327 <para>
4328 The following package management changes took place:
4329 <itemizedlist>
4330 <listitem><para>
4331 Smart package manager is replaced by DNF package manager.
4332 Smart has become unmaintained upstream, is not ported
4333 to Python 3.x.
4334 Consequently, Smart needed to be replaced.
4335 DNF is the only feasible candidate.</para>
4336 <para>The change in functionality is that the on-target
4337 runtime package management from remote package feeds is
4338 now done with a different tool that has a
4339 different set of command-line options.
4340 If you have scripts that call the
4341 tool directly, or use its API, they need to be fixed.</para>
4342 <para>For more information, see the
4343 <ulink url='http://dnf.readthedocs.io/en/latest/'>DNF Documentation</ulink>.
4344 </para></listitem>
4345 <listitem><para>
4346 Rpm 5.x is replaced with Rpm 4.x.
4347 This is done for two major reasons:
4348 <itemizedlist>
4349 <listitem><para>
4350 DNF is API-incompatible with Rpm 5.x and porting
4351 it and maintaining the port is non-trivial.
4352 </para></listitem>
4353 <listitem><para>
4354 Rpm 5.x itself has limited maintenance upstream,
4355 and the Yocto Project is one of the very few
4356 remaining users.
4357 </para></listitem>
4358 </itemizedlist>
4359 </para></listitem>
4360 <listitem><para>
4361 Berkeley DB 6.x is removed and Berkeley DB 5.x becomes
4362 the default:
4363 <itemizedlist>
4364 <listitem><para>
4365 Version 6.x of Berkeley DB has largely been
4366 rejected by the open source community due to its
4367 AGPLv3 license.
4368 As a result, most mainstream open source projects
4369 that require DB are still developed and tested with
4370 DB 5.x.
4371 </para></listitem>
4372 <listitem><para>
4373 In OE-core, the only thing that was requiring
4374 DB 6.x was Rpm 5.x.
4375 Thus, no reason exists to continue carrying DB 6.x
4376 in OE-core.
4377 </para></listitem>
4378 </itemizedlist>
4379 </para></listitem>
4380 <listitem><para>
4381 <filename>createrepo</filename> is replaced with
4382 <filename>createrepo_c</filename>.</para>
4383 <para><filename>createrepo_c</filename> is the current
4384 incarnation of the tool that generates remote repository
4385 metadata.
4386 It is written in C as compared to
4387 <filename>createrepo</filename>, which is written in
4388 Python.
4389 <filename>createrepo_c</filename> is faster and is
4390 maintained.
4391 </para></listitem>
4392 <listitem><para>
4393 Architecture-independent RPM packages are "noarch"
4394 instead of "all".</para>
4395 <para>This change was made because too many places in
4396 DNF/RPM4 stack already make that assumption.
4397 Only the filenames and the architecture tag has changed.
4398 Nothing else has changed in OE-core system, particularly
4399 in the
4400 <link linkend='ref-classes-allarch'><filename>allarch.bbclass</filename></link>
4401 class.
4402 </para></listitem>
4403 <listitem><para>
4404 Signing of remote package feeds using
4405 <filename>PACKAGE_FEED_SIGN</filename>
4406 is not currently supported.
4407 This issue will be fully addressed in a future
4408 Yocto Project release.
4409 See <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209'>defect 11209</ulink>
4410 for more information on a solution to package feed
4411 signing with RPM in the Yocto Project 2.3 release.
4412 </para></listitem>
4413 <listitem><para>
4414 OPKG now uses the libsolv backend for resolving package
4415 dependencies by default.
4416 This is vastly superior to OPKG's internal ad-hoc solver
4417 that was previously used.
4418 This change does have a small impact on disk (around
4419 500 KB) and memory footprint.
4420 <note>
4421 For further details on this change, see the
4422 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?
4423id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>.
4424 </note>
4425 </para></listitem>
4426 </itemizedlist>
4427 </para>
4428 </section>
4429
4430 <section id='migration-2.3-removed-recipes'>
4431 <title>Removed Recipes</title>
4432
4433 <para>
4434 The following recipes have been removed:
4435 <itemizedlist>
4436 <listitem><para>
4437 <emphasis><filename>linux-yocto 4.8:</filename></emphasis>
4438 Version 4.8 has been removed.
4439 Versions 4.1 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10
4440 are now present.
4441 </para></listitem>
4442 <listitem><para>
4443 <emphasis><filename>python-smartpm:</filename></emphasis>
4444 Functionally replaced by <filename>dnf</filename>.
4445 </para></listitem>
4446 <listitem><para>
4447 <emphasis><filename>createrepo:</filename></emphasis>
4448 Replaced by the <filename>createrepo-c</filename> recipe.
4449 </para></listitem>
4450 <listitem><para>
4451 <emphasis><filename>rpmresolve:</filename></emphasis>
4452 No longer needed with the move to RPM 4 as RPM itself is
4453 used instead.
4454 </para></listitem>
4455 <listitem><para>
4456 <emphasis><filename>gstreamer:</filename></emphasis>
4457 Removed the GStreamer Git version recipes as they have
4458 been stale.
4459 <filename>1.10.</filename><replaceable>x</replaceable>
4460 recipes are still present.
4461 </para></listitem>
4462 <listitem><para>
4463 <emphasis><filename>alsa-conf-base:</filename></emphasis>
4464 Merged into <filename>alsa-conf</filename> since
4465 <filename>libasound</filename> depended on both.
4466 Essentially, no way existed to install only one of these.
4467 </para></listitem>
4468 <listitem><para>
4469 <emphasis><filename>tremor:</filename></emphasis>
4470 Moved to <filename>meta-multimedia</filename>.
4471 Fixed-integer Vorbis decoding is not
4472 needed by current hardware.
4473 Thus, GStreamer's ivorbis plugin has been disabled
4474 by default eliminating the need for the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004475 <filename>tremor</filename> recipe in
4476 <link linkend='oe-core'>OE-Core</link>.
Brad Bishop6e60e8b2018-02-01 10:27:11 -05004477 </para></listitem>
4478 <listitem><para>
4479 <emphasis><filename>gummiboot:</filename></emphasis>
4480 Replaced by <filename>systemd-boot</filename>.
4481 </para></listitem>
4482 </itemizedlist>
4483 </para>
4484 </section>
4485
4486 <section id='migration-2.3-wic-changes'>
4487 <title>Wic Changes</title>
4488
4489 <para>
4490 The following changes have been made to Wic:
4491 <note>
4492 For more information on Wic, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004493 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
4494 section in the Yocto Project Development Tasks Manual.
Brad Bishop6e60e8b2018-02-01 10:27:11 -05004495 </note>
4496 <itemizedlist>
4497 <listitem><para>
4498 <emphasis>Default Output Directory Changed:</emphasis>
4499 Wic's default output directory is now the current directory
4500 by default instead of the unusual
4501 <filename>/var/tmp/wic</filename>.</para>
4502
4503 <para>The "-o" and "--outdir" options remain unchanged
4504 and are used to specify your preferred output directory
4505 if you do not want to use the default directory.
4506 </para></listitem>
4507 <listitem><para>
4508 <emphasis>fsimage Plug-in Removed:</emphasis>
4509 The Wic fsimage plug-in has been removed as it duplicates
4510 functionality of the rawcopy plug-in.
4511 </para></listitem>
4512 </itemizedlist>
4513 </para>
4514 </section>
4515
4516 <section id='migration-2.3-qa-changes'>
4517 <title>QA Changes</title>
4518
4519 <para>
4520 The following QA checks have changed:
4521 <itemizedlist>
4522 <listitem><para>
4523 <emphasis><filename>unsafe-references-in-binaries</filename>:</emphasis>
4524 The <filename>unsafe-references-in-binaries</filename>
4525 QA check, which was disabled by default, has now been
4526 removed.
4527 This check was intended to detect binaries in
4528 <filename>/bin</filename> that link to libraries in
4529 <filename>/usr/lib</filename> and have the case where
4530 the user has <filename>/usr</filename> on a separate
4531 filesystem to <filename>/</filename>.</para>
4532
4533 <para>The removed QA check was buggy.
4534 Additionally, <filename>/usr</filename> residing on a
4535 separate partition from <filename>/</filename> is now
4536 a rare configuration.
4537 Consequently,
4538 <filename>unsafe-references-in-binaries</filename> was
4539 removed.
4540 </para></listitem>
4541 <listitem><para>
4542 <emphasis><filename>file-rdeps</filename>:</emphasis>
4543 The <filename>file-rdeps</filename> QA check is now an
4544 error by default instead of a warning.
4545 Because it is an error instead of a warning, you need to
4546 address missing runtime dependencies.</para>
4547
4548 <para>For additional information, see the
4549 <link linkend='ref-classes-insane'><filename>insane</filename></link>
4550 class and the
4551 "<link linkend='qa-errors-and-warnings'>Errors and Warnings</link>"
4552 section.
4553 </para></listitem>
4554 </itemizedlist>
4555 </para>
4556 </section>
4557
4558 <section id='migration-2.3-miscellaneous-changes'>
4559 <title>Miscellaneous Changes</title>
4560
4561 <para>
4562 The following miscellaneous changes have occurred:
4563 <itemizedlist>
4564 <listitem><para>
4565 In this release, a number of recipes have been changed to
4566 ignore the <filename>largefile</filename>
4567 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
4568 item, enabling large file support unconditionally.
4569 This feature has always been enabled by default.
4570 Disabling the feature has not been widely tested.
4571 <note>
4572 Future releases of the Yocto Project will remove
4573 entirely the ability to disable the
4574 <filename>largefile</filename> feature,
4575 which would make it unconditionally enabled everywhere.
4576 </note>
4577 </para></listitem>
4578 <listitem><para>
4579 If the
4580 <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link>
4581 value contains the value of the
4582 <link linkend='var-DATE'><filename>DATE</filename></link>
4583 variable, which is the default between Poky releases,
4584 the <filename>DATE</filename> value is explicitly excluded
4585 from <filename>/etc/issue</filename> and
4586 <filename>/etc/issue.net</filename>, which is displayed at
4587 the login prompt, in order to avoid conflicts with
4588 Multilib enabled.
4589 Regardless, the <filename>DATE</filename> value is
4590 inaccurate if the <filename>base-files</filename>
4591 recipe is restored from shared state (sstate) rather
4592 than rebuilt.</para>
4593
4594 <para>If you need the build date recorded in
4595 <filename>/etc/issue*</filename> or anywhere else in your
4596 image, a better method is to define a post-processing
4597 function to do it and have the function called from
4598 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
4599 Doing so ensures the value is always up-to-date with the
4600 created image.
4601 </para></listitem>
4602 <listitem><para>
4603 Dropbear's <filename>init</filename> script now disables
4604 DSA host keys by default.
4605 This change is in line with the systemd service
4606 file, which supports RSA keys only, and with recent
4607 versions of OpenSSH, which deprecates DSA host keys.
4608 </para></listitem>
4609 <listitem><para>
4610 The
4611 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
4612 class now correctly uses tabs as separators between all
4613 columns in <filename>installed-package-sizes.txt</filename>
4614 in order to aid import into other tools.
4615 </para></listitem>
4616 <listitem><para>
4617 The <filename>USE_LDCONFIG</filename> variable has been
4618 replaced with the "ldconfig"
Brad Bishop316dfdd2018-06-25 12:45:53 -04004619 <filename>DISTRO_FEATURES</filename> feature.
Brad Bishop6e60e8b2018-02-01 10:27:11 -05004620 Distributions that previously set:
4621 <literallayout class='monospaced'>
4622 USE_LDCONFIG = "0"
4623 </literallayout>
4624 should now instead use the following:
4625 <literallayout class='monospaced'>
4626 DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig"
4627 </literallayout>
4628 </para></listitem>
4629 <listitem><para>
4630 The default value of
4631 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
4632 now includes all versions of AGPL licenses in addition
4633 to GPL and LGPL.
4634 <note>
4635 The default list is not intended to be guaranteed
4636 as a complete safe list.
4637 You should seek legal advice based on what you are
4638 distributing if you are unsure.
4639 </note>
4640 </para></listitem>
4641 <listitem><para>
4642 Kernel module packages are now suffixed with the kernel
4643 version in order to allow module packages from multiple
4644 kernel versions to co-exist on a target system.
4645 If you wish to return to the previous naming scheme
4646 that does not include the version suffix, use the
4647 following:
4648 <literallayout class='monospaced'>
4649 KERNEL_MODULE_PACKAGE_SUFFIX to ""
4650 </literallayout>
4651 </para></listitem>
4652 <listitem><para>
4653 Removal of <filename>libtool</filename>
4654 <filename>*.la</filename> files is now enabled by default.
4655 The <filename>*.la</filename> files are not actually
4656 needed on Linux and relocating them is an unnecessary
4657 burden.</para>
4658
4659 <para>If you need to preserve these
4660 <filename>.la</filename> files (e.g. in a custom
4661 distribution), you must change
4662 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
4663 such that "remove-libtool" is not included in the value.
4664 </para></listitem>
4665 <listitem><para>
4666 Extensible SDKs built for GCC 5+ now refuse to install on a
4667 distribution where the host GCC version is 4.8 or 4.9.
4668 This change resulted from the fact that the installation
4669 is known to fail due to the way the
4670 <filename>uninative</filename> shared state (sstate)
4671 package is built.
4672 See the
4673 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
4674 class for additional information.
4675 </para></listitem>
4676 <listitem><para>
4677 All native and nativesdk recipes now use a separate
Brad Bishop316dfdd2018-06-25 12:45:53 -04004678 <filename>DISTRO_FEATURES</filename> value instead of
4679 sharing the value used by recipes for the target, in order
4680 to avoid unnecessary rebuilds.</para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05004681
4682 <para>The <filename>DISTRO_FEATURES</filename> for
4683 <filename>native</filename> recipes is
4684 <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link>
4685 added to an intersection of
4686 <filename>DISTRO_FEATURES</filename> and
4687 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>.
4688 </para>
4689
4690 <para>For nativesdk recipes, the
4691 corresponding variables are
4692 <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link>
4693 and
4694 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>.
4695 </para></listitem>
4696 <listitem><para>
4697 The <filename>FILESDIR</filename>
4698 variable, which was previously deprecated and rarely used,
4699 has now been removed.
4700 You should change any recipes that set
4701 <filename>FILESDIR</filename> to set
4702 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4703 instead.
4704 </para></listitem>
4705 <listitem><para>
4706 The <filename>MULTIMACH_HOST_SYS</filename>
4707 variable has been removed as it is no longer needed
4708 with recipe-specific sysroots.
4709 </para></listitem>
4710 </itemizedlist>
4711 </para>
4712 </section>
4713</section>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004714
4715<section id='moving-to-the-yocto-project-2.4-release'>
4716 <title>Moving to the Yocto Project 2.4 Release</title>
4717
4718 <para>
4719 This section provides migration information for moving to the
4720 Yocto Project 2.4 Release from the prior release.
4721 </para>
4722
4723 <section id='migration-2.4-memory-resident-mode'>
4724 <title>Memory Resident Mode</title>
4725
4726 <para>
4727 A persistent mode is now available in BitBake's default operation,
4728 replacing its previous "memory resident mode" (i.e.
4729 <filename>oe-init-build-env-memres</filename>).
4730 Now you only need to set
Brad Bishop316dfdd2018-06-25 12:45:53 -04004731 <link linkend='var-BB_SERVER_TIMEOUT'><filename>BB_SERVER_TIMEOUT</filename></link>
4732 to a timeout (in seconds) and BitBake's server stays resident for
4733 that amount of time between invocations.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004734 The <filename>oe-init-build-env-memres</filename> script has been
4735 removed since a separate environment setup script is no longer
4736 needed.
4737 </para>
4738 </section>
4739
4740 <section id='migration-2.4-packaging-changes'>
4741 <title>Packaging Changes</title>
4742
4743 <para>
4744 This section provides information about packaging changes that have
4745 ocurred:
4746 <itemizedlist>
4747 <listitem><para>
4748 <emphasis><filename>python3</filename> Changes:</emphasis>
4749 <itemizedlist>
4750 <listitem><para>
4751 The main "python3" package now brings in all of the
4752 standard Python 3 distribution rather than a subset.
4753 This behavior matches what is expected based on
4754 traditional Linux distributions.
4755 If you wish to install a subset of Python 3, specify
4756 <filename>python-core</filename> plus one or more of
4757 the individual packages that are still produced.
4758 </para></listitem>
4759 <listitem><para>
4760 <emphasis><filename>python3</filename>:</emphasis>
4761 The <filename>bz2.py</filename>,
4762 <filename>lzma.py</filename>, and
4763 <filename>_compression.py</filename> scripts have
4764 been moved from the
4765 <filename>python3-misc</filename> package to
4766 the <filename>python3-compression</filename> package.
4767 </para></listitem>
4768 </itemizedlist>
4769 </para></listitem>
4770 <listitem><para>
4771 <emphasis><filename>binutils</filename>:</emphasis>
4772 The <filename>libbfd</filename> library is now packaged in
4773 a separate "libbfd" package.
4774 This packaging saves space when certain tools
4775 (e.g. <filename>perf</filename>) are installed.
4776 In such cases, the tools only need
4777 <filename>libbfd</filename> rather than all the packages in
4778 <filename>binutils</filename>.
4779 </para></listitem>
4780 <listitem><para>
4781 <emphasis><filename>util-linux</filename> Changes:</emphasis>
4782 <itemizedlist>
4783 <listitem><para>
4784 The <filename>su</filename> program is now packaged
4785 in a separate "util-linux-su" package, which is only
4786 built when "pam" is listed in the
4787 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
4788 variable.
4789 <filename>util-linux</filename> should not be
4790 installed unless it is needed because
4791 <filename>su</filename> is normally provided through
4792 the shadow file format.
4793 The main <filename>util-linux</filename> package has
4794 runtime dependencies (i.e.
4795 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
4796 on the <filename>util-linux-su</filename> package
4797 when "pam" is in
Brad Bishop316dfdd2018-06-25 12:45:53 -04004798 <filename>DISTRO_FEATURES</filename>.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004799 </para></listitem>
4800 <listitem><para>
4801 The <filename>switch_root</filename> program is now
4802 packaged in a separate "util-linux-switch-root"
4803 package for small initramfs images that do not need
4804 the whole <filename>util-linux</filename> package or
4805 the busybox binary, which are both much larger than
4806 <filename>switch_root</filename>.
4807 The main <filename>util-linux</filename> package has
4808 a recommended runtime dependency (i.e.
4809 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
4810 on the <filename>util-linux-switch-root</filename> package.
4811 </para></listitem>
4812 <listitem><para>
4813 The <filename>ionice</filename> program is now
4814 packaged in a separate "util-linux-ionice" package.
4815 The main <filename>util-linux</filename> package has
4816 a recommended runtime dependency (i.e.
Brad Bishop316dfdd2018-06-25 12:45:53 -04004817 <filename>RRECOMMENDS</filename>)
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004818 on the <filename>util-linux-ionice</filename> package.
4819 </para></listitem>
4820 </itemizedlist>
4821 </para></listitem>
4822 <listitem><para>
4823 <emphasis><filename>initscripts</filename>:</emphasis>
4824 The <filename>sushell</filename> program is now packaged in
4825 a separate "initscripts-sushell" package.
4826 This packaging change allows systems to pull
4827 <filename>sushell</filename> in when
4828 <filename>selinux</filename> is enabled.
4829 The change also eliminates needing to pull in the entire
4830 <filename>initscripts</filename> package.
4831 The main <filename>initscripts</filename> package has a
Brad Bishop316dfdd2018-06-25 12:45:53 -04004832 runtime dependency (i.e. <filename>RDEPENDS</filename>)
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004833 on the <filename>sushell</filename> package when
Brad Bishop316dfdd2018-06-25 12:45:53 -04004834 "selinux" is in <filename>DISTRO_FEATURES</filename>.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004835 </para></listitem>
4836 <listitem><para>
4837 <emphasis><filename>glib-2.0</filename>:</emphasis>
4838 The <filename>glib-2.0</filename> package now has a
4839 recommended runtime dependency (i.e.
Brad Bishop316dfdd2018-06-25 12:45:53 -04004840 <filename>RRECOMMENDS</filename>) on the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004841 <filename>shared-mime-info</filename> package, since large
4842 portions of GIO are not useful without the MIME database.
4843 You can remove the dependency by using the
4844 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
4845 variable if <filename>shared-mime-info</filename> is too
4846 large and is not required.
4847 </para></listitem>
4848 <listitem><para>
4849 <emphasis>Go Standard Runtime:</emphasis>
4850 The Go standard runtime has been split out from the main
4851 <filename>go</filename> recipe into a separate
4852 <filename>go-runtime</filename> recipe.
4853 </para></listitem>
4854 </itemizedlist>
4855 </para>
4856 </section>
4857
4858 <section id='migration-2.4-removed-recipes'>
4859 <title>Removed Recipes</title>
4860
4861 <para>
4862 The following recipes have been removed:
4863 <itemizedlist>
4864 <listitem><para>
4865 <emphasis><filename>acpitests</filename>:</emphasis>
4866 This recipe is not maintained.
4867 </para></listitem>
4868 <listitem><para>
4869 <emphasis><filename>autogen-native</filename>:</emphasis>
4870 No longer required by Grub, oe-core, or meta-oe.
4871 </para></listitem>
4872 <listitem><para>
4873 <emphasis><filename>bdwgc</filename>:</emphasis>
4874 Nothing in OpenEmbedded-Core requires this recipe.
4875 It has moved to meta-oe.
4876 </para></listitem>
4877 <listitem><para>
4878 <emphasis><filename>byacc</filename>:</emphasis>
4879 This recipe was only needed by rpm 5.x and has moved to
4880 meta-oe.
4881 </para></listitem>
4882 <listitem><para>
4883 <emphasis><filename>gcc (5.4)</filename>:</emphasis>
4884 The 5.4 series dropped the recipe in favor of 6.3 / 7.2.
4885 </para></listitem>
4886 <listitem><para>
4887 <emphasis><filename>gnome-common</filename>:</emphasis>
4888 Deprecated upstream and no longer needed.
4889 </para></listitem>
4890 <listitem><para>
4891 <emphasis><filename>go-bootstrap-native</filename>:</emphasis>
4892 Go 1.9 does its own bootstrapping so this recipe has been
4893 removed.
4894 </para></listitem>
4895 <listitem><para>
4896 <emphasis><filename>guile</filename>:</emphasis>
4897 This recipe was only needed by
4898 <filename>autogen-native</filename> and
4899 <filename>remake</filename>.
4900 The recipe is no longer needed by either of these programs.
4901 </para></listitem>
4902 <listitem><para>
4903 <emphasis><filename>libclass-isa-perl</filename>:</emphasis>
4904 This recipe was previously needed for LSB 4, no longer
4905 needed.
4906 </para></listitem>
4907 <listitem><para>
4908 <emphasis><filename>libdumpvalue-perl</filename>:</emphasis>
4909 This recipe was previously needed for LSB 4, no longer
4910 needed.
4911 </para></listitem>
4912 <listitem><para>
4913 <emphasis><filename>libenv-perl</filename>:</emphasis>
4914 This recipe was previously needed for LSB 4, no longer
4915 needed.
4916 </para></listitem>
4917 <listitem><para>
4918 <emphasis><filename>libfile-checktree-perl</filename>:</emphasis>
4919 This recipe was previously needed for LSB 4, no longer
4920 needed.
4921 </para></listitem>
4922 <listitem><para>
4923 <emphasis><filename>libi18n-collate-perl</filename>:</emphasis>
4924 This recipe was previously needed for LSB 4, no longer
4925 needed.
4926 </para></listitem>
4927 <listitem><para>
4928 <emphasis><filename>libiconv</filename>:</emphasis>
4929 This recipe was only needed for <filename>uclibc</filename>,
4930 which was removed in the previous release.
4931 <filename>glibc</filename> and <filename>musl</filename>
4932 have their own implementations.
4933 <filename>meta-mingw</filename> still needs
4934 <filename>libiconv</filename>, so it has
4935 been moved to <filename>meta-mingw</filename>.
4936 </para></listitem>
4937 <listitem><para>
4938 <emphasis><filename>libpng12</filename>:</emphasis>
4939 This recipe was previously needed for LSB. The current
4940 <filename>libpng</filename> is 1.6.x.
4941 </para></listitem>
4942 <listitem><para>
4943 <emphasis><filename>libpod-plainer-perl</filename>:</emphasis>
4944 This recipe was previously needed for LSB 4, no longer
4945 needed.
4946 </para></listitem>
4947 <listitem><para>
4948 <emphasis><filename>linux-yocto (4.1)</filename>:</emphasis>
4949 This recipe was removed in favor of 4.4, 4.9, 4.10 and 4.12.
4950 </para></listitem>
4951 <listitem><para>
4952 <emphasis><filename>mailx</filename>:</emphasis>
4953 This recipe was previously only needed for LSB
4954 compatibility, and upstream is defunct.
4955 </para></listitem>
4956 <listitem><para>
4957 <emphasis><filename>mesa (git version only)</filename>:</emphasis>
4958 The git version recipe was stale with respect to the release
4959 version.
4960 </para></listitem>
4961 <listitem><para>
4962 <emphasis><filename>ofono (git version only)</filename>:</emphasis>
4963 The git version recipe was stale with respect to the release
4964 version.
4965 </para></listitem>
4966 <listitem><para>
4967 <emphasis><filename>portmap</filename>:</emphasis>
4968 This recipe is obsolete and is superseded by
4969 <filename>rpcbind</filename>.
4970 </para></listitem>
4971 <listitem><para>
4972 <emphasis><filename>python3-pygpgme</filename>:</emphasis>
4973 This recipe is old and unmaintained. It was previously
4974 required by <filename>dnf</filename>, which has switched
4975 to official <filename>gpgme</filename> Python bindings.
4976 </para></listitem>
4977 <listitem><para>
4978 <emphasis><filename>python-async</filename>:</emphasis>
4979 This recipe has been removed in favor of the Python 3
4980 version.
4981 </para></listitem>
4982 <listitem><para>
4983 <emphasis><filename>python-gitdb</filename>:</emphasis>
4984 This recipe has been removed in favor of the Python 3
4985 version.
4986 </para></listitem>
4987 <listitem><para>
4988 <emphasis><filename>python-git</filename>:</emphasis>
4989 This recipe was removed in favor of the Python 3
4990 version.
4991 </para></listitem>
4992 <listitem><para>
4993 <emphasis><filename>python-mako</filename>:</emphasis>
4994 This recipe was removed in favor of the Python 3
4995 version.
4996 </para></listitem>
4997 <listitem><para>
4998 <emphasis><filename>python-pexpect</filename>:</emphasis>
4999 This recipe was removed in favor of the Python 3 version.
5000 </para></listitem>
5001 <listitem><para>
5002 <emphasis><filename>python-ptyprocess</filename>:</emphasis>
5003 This recipe was removed in favor of Python the 3 version.
5004 </para></listitem>
5005 <listitem><para>
5006 <emphasis><filename>python-pycurl</filename>:</emphasis>
5007 Nothing is using this recipe in OpenEmbedded-Core
5008 (i.e. <filename>meta-oe</filename>).
5009 </para></listitem>
5010 <listitem><para>
5011 <emphasis><filename>python-six</filename>:</emphasis>
5012 This recipe was removed in favor of the Python 3 version.
5013 </para></listitem>
5014 <listitem><para>
5015 <emphasis><filename>python-smmap</filename>:</emphasis>
5016 This recipe was removed in favor of the Python 3 version.
5017 </para></listitem>
5018 <listitem><para>
5019 <emphasis><filename>remake</filename>:</emphasis>
5020 Using <filename>remake</filename> as the provider of
5021 <filename>virtual/make</filename> is broken.
5022 Consequently, this recipe is not needed in OpenEmbedded-Core.
5023 </para></listitem>
5024 </itemizedlist>
5025 </para>
5026 </section>
5027
5028 <section id='migration-2.4-kernel-device-tree-move'>
5029 <title>Kernel Device Tree Move</title>
5030
5031 <para>
5032 Kernel Device Tree support is now easier to enable in a kernel
5033 recipe.
5034 The Device Tree code has moved to a
Brad Bishop316dfdd2018-06-25 12:45:53 -04005035 <link linkend='ref-classes-kernel-devicetree'><filename>kernel-devicetree</filename></link>
5036 class.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005037 Functionality is automatically enabled for any recipe that inherits
5038 the
5039 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
5040 class and sets the
5041 <link linkend='var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></link>
5042 variable.
5043 The previous mechanism for doing this,
5044 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>,
5045 is still available to avoid breakage, but triggers a
5046 deprecation warning.
5047 Future releases of the Yocto Project will remove
5048 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>.
5049 It is advisable to remove any <filename>require</filename>
5050 statements that request
5051 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>
5052 from any custom kernel recipes you might have.
5053 This will avoid breakage in post 2.4 releases.
5054 </para>
5055 </section>
5056
5057 <section id='migration-2.4-package-qa-changes'>
5058 <title>Package QA Changes</title>
5059
5060 <para>
5061 The following package QA changes took place:
5062 <itemizedlist>
5063 <listitem><para>
5064 The "unsafe-references-in-scripts" QA check has been
5065 removed.
5066 </para></listitem>
5067 <listitem><para>
5068 If you refer to <filename>${COREBASE}/LICENSE</filename>
5069 within
5070 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
5071 you receive a warning because this file is a description of
5072 the license for OE-Core.
5073 Use <filename>${COMMON_LICENSE_DIR}/MIT</filename>
5074 if your recipe is MIT-licensed and you cannot use the
5075 preferred method of referring to a file within the source
5076 tree.
5077 </para></listitem>
5078 </itemizedlist>
5079 </para>
5080 </section>
5081
5082 <section id='migration-2.4-readme-changes'>
5083 <title><filename>README</filename> File Changes</title>
5084
5085 <para>
5086 The following are changes to <filename>README</filename> files:
5087 <itemizedlist>
5088 <listitem><para>
5089 The main Poky <filename>README</filename> file has been
5090 moved to the <filename>meta-poky</filename> layer and
5091 has been renamed <filename>README.poky</filename>.
5092 A symlink has been created so that references to the old
5093 location work.
5094 </para></listitem>
5095 <listitem><para>
5096 The <filename>README.hardware</filename> file has been moved
5097 to <filename>meta-yocto-bsp</filename>.
5098 A symlink has been created so that references to the old
5099 location work.
5100 </para></listitem>
5101 <listitem><para>
5102 A <filename>README.qemu</filename> file has been created
5103 with coverage of the <filename>qemu*</filename> machines.
5104 </para></listitem>
5105 </itemizedlist>
5106 </para>
5107 </section>
5108
5109 <section id='migration-2.4-miscellaneous-changes'>
5110 <title>Miscellaneous Changes</title>
5111
5112 <para>
5113 The following are additional changes:
5114 <itemizedlist>
5115 <listitem><para>
5116 The <filename>ROOTFS_PKGMANAGE_BOOTSTRAP</filename>
5117 variable and any references to it have been removed.
5118 You should remove this variable from any custom recipes.
5119 </para></listitem>
5120 <listitem><para>
5121 The <filename>meta-yocto</filename> directory has been
5122 removed.
5123 <note>
5124 In the Yocto Project 2.1 release
5125 <filename>meta-yocto</filename> was renamed to
5126 <filename>meta-poky</filename> and the
5127 <filename>meta-yocto</filename> subdirectory remained
5128 to avoid breaking existing configurations.
5129 </note>
5130 </para></listitem>
5131 <listitem><para>
5132 The <filename>maintainers.inc</filename> file, which tracks
5133 maintainers by listing a primary person responsible for each
5134 recipe in OE-Core, has been moved from
5135 <filename>meta-poky</filename> to OE-Core (i.e. from
5136 <filename>meta-poky/conf/distro/include</filename> to
5137 <filename>meta/conf/distro/include</filename>).
5138 </para></listitem>
5139 <listitem><para>
5140 The
5141 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
5142 class now makes a single commit per build rather than one
5143 commit per subdirectory in the repository.
5144 This behavior assumes the commits are enabled with
5145 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
5146 = "1", which is typical.
5147 Previously, the <filename>buildhistory</filename> class made
5148 one commit per subdirectory in the repository in order to
5149 make it easier to see the changes for a particular
5150 subdirectory.
5151 To view a particular change, specify that subdirectory as
5152 the last parameter on the <filename>git show</filename>
5153 or <filename>git diff</filename> commands.
5154 </para></listitem>
5155 <listitem><para>
5156 The <filename>x86-base.inc</filename> file, which is
5157 included by all x86-based machine configurations, now sets
5158 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
5159 using <filename>?=</filename> to "live" rather than
5160 appending with <filename>+=</filename>.
5161 This change makes the default easier to override.
5162 </para></listitem>
5163 <listitem><para>
5164 BitBake fires multiple "BuildStarted" events when
5165 multiconfig is enabled (one per configuration).
5166 For more information, see the
5167 "<ulink url='&YOCTO_DOCS_BB_URL;#events'>Events</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04005168 section in the BitBake User Manual.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005169 </para></listitem>
5170 <listitem><para>
5171 By default, the <filename>security_flags.inc</filename> file
Brad Bishop316dfdd2018-06-25 12:45:53 -04005172 sets a
5173 <link linkend='var-GCCPIE'><filename>GCCPIE</filename></link>
5174 variable with an option to enable Position Independent
5175 Executables (PIE) within <filename>gcc</filename>.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005176 Enabling PIE in the GNU C Compiler (GCC), makes Return
5177 Oriented Programming (ROP) attacks much more difficult to
5178 execute.
5179 </para></listitem>
5180 <listitem><para>
5181 OE-Core now provides a
5182 <filename>bitbake-layers</filename> plugin that implements
5183 a "create-layer" subcommand.
5184 The implementation of this subcommand has resulted in the
5185 <filename>yocto-layer</filename> script being deprecated and
5186 will likely be removed in the next Yocto Project release.
5187 </para></listitem>
5188 <listitem><para>
5189 The <filename>vmdk</filename>, <filename>vdi</filename>,
5190 and <filename>qcow2</filename> image file types are now
5191 used in conjunction with the "wic" image type through
5192 <filename>CONVERSION_CMD</filename>.
5193 Consequently, the equivalent image types are now
5194 <filename>wic.vmdk</filename>, <filename>wic.vdi</filename>,
5195 and <filename>wic.qcow2</filename>, respectively.
5196 </para></listitem>
5197 <listitem><para>
5198 <filename>do_image_&lt;type&gt;[depends]</filename> has
5199 replaced <filename>IMAGE_DEPENDS_&lt;type&gt;</filename>.
5200 If you have your own classes that implement custom image
5201 types, then you need to update them.
5202 </para></listitem>
5203 <listitem><para>
5204 OpenSSL 1.1 has been introduced.
5205 However, the default is still 1.0.x through the
5206 <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
5207 variable.
5208 This preference is set is due to the remaining compatibility
5209 issues with other software.
5210 The
5211 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
5212 variable in the openssl 1.0 recipe now includes "openssl10"
5213 as a marker that can be used in
5214 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
5215 within recipes that build software that still depend on
5216 OpenSSL 1.0.
5217 </para></listitem>
5218 <listitem><para>
5219 To ensure consistent behavior, BitBake's "-r" and "-R"
5220 options (i.e. prefile and postfile), which are used to
5221 read or post-read additional configuration files from the
5222 command line, now only affect the current BitBake command.
5223 Before these BitBake changes, these options would "stick"
5224 for future executions.
5225 </para></listitem>
5226 </itemizedlist>
5227 </para>
5228 </section>
5229</section>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005230
5231<section id='moving-to-the-yocto-project-2.5-release'>
5232 <title>Moving to the Yocto Project 2.5 Release</title>
5233
5234 <para>
5235 This section provides migration information for moving to the
5236 Yocto Project 2.5 Release from the prior release.
5237 </para>
5238
5239 <section id='migration-2.5-packaging-changes'>
5240 <title>Packaging Changes</title>
5241
5242 <para>
5243 This section provides information about packaging changes that have
5244 occurred:
5245 <itemizedlist>
5246 <listitem><para>
5247 <emphasis><filename>bind-libs</filename>:</emphasis>
5248 The libraries packaged by the bind recipe are in a
5249 separate <filename>bind-libs</filename> package.
5250 </para></listitem>
5251 <listitem><para>
5252 <emphasis><filename>libfm-gtk</filename>:</emphasis>
5253 The <filename>libfm</filename> GTK+ bindings are split into
5254 a separate <filename>libfm-gtk</filename> package.
5255 </para></listitem>
5256 <listitem><para>
5257 <emphasis><filename>flex-libfl</filename>:</emphasis>
5258 The flex recipe splits out libfl into a separate
5259 <filename>flex-libfl</filename> package to avoid too many
5260 dependencies being pulled in where only the library is
5261 needed.
5262 </para></listitem>
5263 <listitem><para>
5264 <emphasis><filename>grub-efi</filename>:</emphasis>
5265 The <filename>grub-efi</filename> configuration is split
5266 into a separate <filename>grub-bootconf</filename>
5267 recipe.
5268 However, the dependency relationship from
5269 <filename>grub-efi</filename> is through a
5270 virtual/grub-bootconf provider making it possible to have
5271 your own recipe provide the dependency.
5272 Alternatively, you can use a BitBake append file to bring
5273 the configuration back into the
5274 <filename>grub-efi</filename> recipe.
5275 </para></listitem>
5276 <listitem><para>
5277 <emphasis>armv7a Legacy Package Feed Support:</emphasis>
5278 Legacy support is removed for transitioning from
5279 <filename>armv7a</filename> to
5280 <filename>armv7a-vfp-neon</filename> in package feeds,
5281 which was previously enabled by setting
5282 <filename>PKGARCHCOMPAT_ARMV7A</filename>.
5283 This transition occurred in 2011 and active package feeds
5284 should by now be updated to the new naming.
5285 </para></listitem>
5286 </itemizedlist>
5287 </para>
5288 </section>
5289
5290 <section id='migration-2.5-removed-recipes'>
5291 <title>Removed Recipes</title>
5292
5293 <para>
5294 The following recipes have been removed:
5295 <itemizedlist>
5296 <listitem><para>
5297 <emphasis><filename>gcc</filename>:</emphasis>
5298 The version 6.4 recipes are replaced by 7.x.
5299 </para></listitem>
5300 <listitem><para>
5301 <emphasis><filename>gst-player</filename>:</emphasis>
5302 Renamed to <filename>gst-examples</filename> as per
5303 upstream.
5304 </para></listitem>
5305 <listitem><para>
5306 <emphasis><filename>hostap-utils</filename>:</emphasis>
5307 This software package is obsolete.
5308 </para></listitem>
5309 <listitem><para>
5310 <emphasis><filename>latencytop</filename>:</emphasis>
5311 This recipe is no longer maintained upstream.
5312 The last release was in 2009.
5313 </para></listitem>
5314 <listitem><para>
5315 <emphasis><filename>libpfm4</filename>:</emphasis>
5316 The only file that requires this recipe is
5317 <filename>oprofile</filename>, which has been removed.
5318 </para></listitem>
5319 <listitem><para>
5320 <emphasis><filename>linux-yocto</filename>:</emphasis>
5321 The version 4.4, 4.9, and 4.10 recipes have been removed.
5322 Versions 4.12, 4.14, and 4.15 remain.
5323 </para></listitem>
5324 <listitem><para>
5325 <emphasis><filename>man</filename>:</emphasis>
5326 This recipe has been replaced by modern
5327 <filename>man-db</filename>
5328 </para></listitem>
5329 <listitem><para>
5330 <emphasis><filename>mkelfimage</filename>:</emphasis>
5331 This tool has been removed in the upstream coreboot project,
5332 and is no longer needed with the removal of the ELF image
5333 type.
5334 </para></listitem>
5335 <listitem><para>
5336 <emphasis><filename>nativesdk-postinst-intercept</filename>:</emphasis>
5337 This recipe is not maintained.
5338 </para></listitem>
5339 <listitem><para>
5340 <emphasis><filename>neon</filename>:</emphasis>
5341 This software package is no longer maintained upstream and
5342 is no longer needed by anything in OpenEmbedded-Core.
5343 </para></listitem>
5344 <listitem><para>
5345 <emphasis><filename>oprofile</filename>:</emphasis>
5346 The functionality of this recipe is replaced by
5347 <filename>perf</filename> and keeping compatibility on
5348 an ongoing basis with <filename>musl</filename> is
5349 difficult.
5350 </para></listitem>
5351 <listitem><para>
5352 <emphasis><filename>pax</filename>:</emphasis>
5353 This software package is obsolete.
5354 </para></listitem>
5355 <listitem><para>
5356 <emphasis><filename>stat</filename>:</emphasis>
5357 This software package is not maintained upstream.
5358 <filename>coreutils</filename> provides a modern stat binary.
5359 </para></listitem>
5360 <listitem><para>
5361 <emphasis><filename>zisofs-tools-native</filename>:</emphasis>
5362 This recipe is no longer needed because the compressed
5363 ISO image feature has been removed.
5364 </para></listitem>
5365 </itemizedlist>
5366 </para>
5367 </section>
5368
5369 <section id='migration-2.5-scripts-and-tools-changes'>
5370 <title>Scripts and Tools Changes</title>
5371
5372 <para>
5373 The following are changes to scripts and tools:
5374 <itemizedlist>
5375 <listitem><para>
5376 <emphasis><filename>yocto-bsp</filename>,
5377 <filename>yocto-kernel</filename>, and
5378 <filename>yocto-layer</filename></emphasis>:
5379 The <filename>yocto-bsp</filename>,
5380 <filename>yocto-kernel</filename>, and
5381 <filename>yocto-layer</filename> scripts previously shipped
5382 with poky but not in OpenEmbedded-Core have been removed.
5383 These scripts are not maintained and are outdated.
5384 In many cases, they are also limited in scope.
5385 The <filename>bitbake-layers create-layer</filename> command
5386 is a direct replacement for <filename>yocto-layer</filename>.
5387 See the documentation to create a BSP or kernel recipe in
5388 the
5389 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-kernel-recipe-example'>BSP Kernel Recipe Example</ulink>"
5390 section.
5391 </para></listitem>
5392 <listitem><para>
5393 <emphasis><filename>devtool finish</filename>:</emphasis>
5394 <filename>devtool finish</filename> now exits with an error
5395 if there are uncommitted changes or a rebase/am in progress
5396 in the recipe's source repository.
5397 If this error occurs, there might be uncommitted changes
5398 that will not be included in updates to the patches applied
5399 by the recipe.
5400 A -f/--force option is provided for situations that the
5401 uncommitted changes are inconsequential and you want to
5402 proceed regardless.
5403 </para></listitem>
5404 <listitem><para>
5405 <emphasis><filename>scripts/oe-setup-rpmrepo</filename> script:</emphasis>
5406 The functionality of
5407 <filename>scripts/oe-setup-rpmrepo</filename> is replaced by
5408 <filename>bitbake package-index</filename>.
5409 </para></listitem>
5410 <listitem><para>
5411 <emphasis><filename>scripts/test-dependencies.sh</filename> script:</emphasis>
5412 The script is largely made obsolete by the
5413 recipe-specific sysroots functionality introduced in the
5414 previous release.
5415 </para></listitem>
5416 </itemizedlist>
5417 </para>
5418 </section>
5419
5420 <section id='migration-2.5-bitbake-changes'>
5421 <title>BitBake Changes</title>
5422
5423 <para>
5424 The following are BitBake changes:
5425 <itemizedlist>
5426 <listitem><para>
5427 The <filename>--runall</filename> option has changed.
5428 There are two different behaviors people might want:
5429 <itemizedlist>
5430 <listitem><para>
5431 <emphasis>Behavior A:</emphasis>
5432 For a given target (or set of targets) look through
5433 the task graph and run task X only if it is present
5434 and will be built.
5435 </para></listitem>
5436 <listitem><para>
5437 <emphasis>Behavior B:</emphasis>
5438 For a given target (or set of targets) look through
5439 the task graph and run task X if any recipe in the
5440 taskgraph has such a target, even if it is not in
5441 the original task graph.
5442 </para></listitem>
5443 </itemizedlist>
5444 The <filename>--runall</filename> option now performs
5445 "Behavior B".
5446 Previously <filename>--runall</filename> behaved like
5447 "Behavior A".
5448 A <filename>--runonly</filename> option has been added to
5449 retain the ability to perform "Behavior A".
5450 </para></listitem>
5451 <listitem><para>
5452 Several explicit "run this task for all recipes in the
5453 dependency tree" tasks have been removed (e.g.
5454 <filename>fetchall</filename>,
5455 <filename>checkuriall</filename>, and the
5456 <filename>*all</filename> tasks provided by the
5457 <filename>distrodata</filename> and
5458 <filename>archiver</filename> classes).
5459 There is a BitBake option to complete this for any arbitrary
5460 task. For example:
5461 <literallayout class='monospaced'>
5462 bitbake &lt;target&gt; -c fetchall
5463 </literallayout>
5464 should now be replaced with:
5465 <literallayout class='monospaced'>
5466 bitbake &lt;target&gt; --runall=fetch
5467 </literallayout>
5468 </para></listitem>
5469 </itemizedlist>
5470 </para>
5471 </section>
5472
5473 <section id='migration-2.5-python-and-python3-changes'>
5474 <title>Python and Python 3 Changes</title>
5475
5476 <para>
5477 The following are auto-packaging changes to Python and Python 3:
5478 </para>
5479 <para>
5480 The script-managed <filename>python-*-manifest.inc</filename> files
5481 that were previously used to generate Python and Python 3
5482 packages have been replaced with a JSON-based file that is
5483 easier to read and maintain.
5484 A new task is available for maintainers of the Python recipes to
5485 update the JSON file when upgrading to new Python versions.
5486 You can now edit the file directly instead of having to edit a
5487 script and run it to update the file.
5488 </para>
5489 <para>
5490 One particular change to note is that the Python recipes no longer
5491 have build-time provides for their packages.
5492 This assumes <filename>python-foo</filename> is one of the packages
5493 provided by the Python recipe.
5494 You can no longer run <filename>bitbake python-foo</filename> or
5495 have a <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> on
5496 <filename>python-foo</filename>, but doing either of the following
5497 causes the package to work as expected:
5498 <literallayout class='monospaced'>
5499 IMAGE_INSTALL_append = " python-foo"
5500 </literallayout>
5501 or
5502 <literallayout class='monospaced'>
5503 RDEPENDS_${PN} = "python-foo"
5504 </literallayout>
5505 The earlier build-time provides behavior was a quirk of the way the
5506 Python manifest file was created.
5507 For more information on this change please see
5508 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce'>this commit</ulink>.
5509 </para>
5510 </section>
5511
5512 <section id='migration-2.5-miscellaneous-changes'>
5513 <title>Miscellaneous Changes</title>
5514
5515 <para>
5516 The following are additional changes:
5517 <itemizedlist>
5518 <listitem><para>
5519 The <filename>kernel</filename> class supports building
5520 packages for multiple kernels.
5521 If your kernel recipe or <filename>.bbappend</filename> file
5522 mentions packaging at all, you should replace references to
5523 the kernel in package names with
5524 <filename>${KERNEL_PACKAGE_NAME}</filename>.
5525 For example, if you disable automatic installation of the
5526 kernel image using
5527 <filename>RDEPENDS_kernel-base = ""</filename> you can avoid
5528 warnings using
5529 <filename>RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""</filename>
5530 instead.
5531 </para></listitem>
5532 <listitem><para>
5533 The <filename>buildhistory</filename> class commits changes
5534 to the repository by default so you no longer need to set
5535 <filename>BUILDHISTORY_COMMIT = "1"</filename>.
5536 If you want to disable commits you need to set
5537 <filename>BUILDHISTORY_COMMIT = "0"</filename> in your
5538 configuration.
5539 </para></listitem>
5540 <listitem><para>
5541 The <filename>beaglebone</filename> reference machine has
5542 been renamed to <filename>beaglebone-yocto</filename>.
5543 The <filename>beaglebone-yocto</filename> BSP is a reference
5544 implementation using only mainline components available in
5545 OpenEmbedded-Core and <filename>meta-yocto-bsp</filename>,
5546 whereas Texas Instruments maintains a full-featured BSP in
5547 the <filename>meta-ti</filename> layer.
5548 This rename avoids the previous name clash that existed
5549 between the two BSPs.
5550 </para></listitem>
5551 <listitem><para>
5552 The <filename>update-alternatives</filename> class no longer
5553 works with SysV <filename>init</filename> scripts because
5554 this usage has been problematic.
5555 Also, the <filename>sysklogd</filename> recipe no longer
5556 uses <filename>update-alternatives</filename> because it is
5557 incompatible with other implementations.
5558 </para></listitem>
5559 <listitem><para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08005560 By default, the
5561 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
5562 class uses <filename>ninja</filename> instead of
Brad Bishop316dfdd2018-06-25 12:45:53 -04005563 <filename>make</filename> for building.
5564 This improves build performance.
5565 If a recipe is broken with <filename>ninja</filename>, then
5566 the recipe can set
5567 <filename>OECMAKE_GENERATOR = "Unix Makefiles"</filename>
5568 to change back to <filename>make</filename>.
5569 </para></listitem>
5570 <listitem><para>
5571 The previously deprecated <filename>base_*</filename>
5572 functions have been removed in favor of their replacements
5573 in <filename>meta/lib/oe</filename> and
5574 <filename>bitbake/lib/bb</filename>.
5575 These are typically used from recipes and classes.
5576 Any references to the old functions must be updated.
5577 The following table shows the removed functions and their
5578 replacements:
5579
5580 <literallayout class='monospaced'>
5581 <emphasis>Removed</emphasis> <emphasis>Replacement</emphasis>
5582 ============================ ============================
5583 base_path_join() oe.path.join()
5584 base_path_relative() oe.path.relative()
5585 base_path_out() oe.path.format_display()
5586 base_read_file() oe.utils.read_file()
5587 base_ifelse() oe.utils.ifelse()
5588 base_conditional() oe.utils.conditional()
5589 base_less_or_equal() oe.utils.less_or_equal()
5590 base_version_less_or_equal() oe.utils.version_less_or_equal()
5591 base_contains() bb.utils.contains()
5592 base_both_contain() oe.utils.both_contain()
5593 base_prune_suffix() oe.utils.prune_suffix()
5594 oe_filter() oe.utils.str_filter()
5595 oe_filter_out() oe.utils.str_filter_out() (or use the _remove operator).
5596 </literallayout>
5597 </para></listitem>
5598 <listitem><para>
5599 Using <filename>exit 1</filename> to explicitly defer a
5600 postinstall script until first boot is now deprecated since
5601 it is not an obvious mechanism and can mask actual errors.
5602 If you want to explicitly defer a postinstall to first boot
5603 on the target rather than at <filename>rootfs</filename>
5604 creation time, use
5605 <filename>pkg_postinst_ontarget()</filename>
5606 or call
5607 <filename>postinst-intercepts defer_to_first_boot</filename>
5608 from <filename>pkg_postinst()</filename>.
5609 Any failure of a <filename>pkg_postinst()</filename>
5610 script (including <filename>exit 1</filename>)
5611 will trigger a warning during
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08005612 <filename>do_rootfs</filename>.</para>
5613
5614 <para>For more information, see the
5615 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
5616 section in the Yocto Project Development Tasks Manual.
Brad Bishop316dfdd2018-06-25 12:45:53 -04005617 </para></listitem>
5618 <listitem><para>
5619 The <filename>elf</filename> image type has been removed.
5620 This image type was removed because the
5621 <filename>mkelfimage</filename> tool
5622 that was required to create it is no longer provided by
5623 coreboot upstream and required updating every time
5624 <filename>binutils</filename> updated.
5625 </para></listitem>
5626 <listitem><para>
5627 Support for .iso image compression (previously enabled
5628 through <filename>COMPRESSISO = "1"</filename>) has been
5629 removed.
5630 The userspace tools (<filename>zisofs-tools</filename>) are
5631 unmaintained and <filename>squashfs</filename> provides
5632 better performance and compression.
5633 In order to build a live image with squashfs+lz4 compression
5634 enabled you should now set
5635 <filename>LIVE_ROOTFS_TYPE = "squashfs-lz4"</filename>
5636 and ensure that <filename>live</filename>
5637 is in <filename>IMAGE_FSTYPES</filename>.
5638 </para></listitem>
5639 <listitem><para>
5640 Recipes with an unconditional dependency on
5641 <filename>libpam</filename> are only buildable with
5642 <filename>pam</filename> in
5643 <filename>DISTRO_FEATURES</filename>.
5644 If the dependency is truly optional then it is recommended
5645 that the dependency be conditional upon
5646 <filename>pam</filename> being in
5647 <filename>DISTRO_FEATURES</filename>.
5648 </para></listitem>
5649 <listitem><para>
5650 For EFI-based machines, the bootloader
5651 (<filename>grub-efi</filename> by default) is installed into
5652 the image at /boot.
5653 Wic can be used to split the bootloader into separate boot
5654 and rootfs partitions if necessary.
5655 </para></listitem>
5656 <listitem><para>
5657 Patches whose context does not match exactly (i.e. where
5658 patch reports "fuzz" when applying) will generate a
5659 warning.
5660 For an example of this see
5661 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57'>this commit</ulink>.
5662 </para></listitem>
5663 <listitem><para>
5664 Layers are expected to set
5665 <filename>LAYERSERIES_COMPAT_layername</filename>
5666 to match the version(s) of OpenEmbedded-Core they are
5667 compatible with.
5668 This is specified as codenames using spaces to separate
5669 multiple values (e.g. "rocko sumo").
5670 If a layer does not set
5671 <filename>LAYERSERIES_COMPAT_layername</filename>, a warning
5672 will is shown.
5673 If a layer sets a value that does not include the current
5674 version ("sumo" for the 2.5 release), then an error will be
5675 produced.
5676 </para></listitem>
5677 <listitem><para>
5678 The <filename>TZ</filename> environment variable is set to
5679 "UTC" within the build environment in order to fix
5680 reproducibility problems in some recipes.
5681 </para></listitem>
5682 </itemizedlist>
5683 </para>
5684 </section>
5685</section>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08005686
5687<section id='moving-to-the-yocto-project-2.6-release'>
5688 <title>Moving to the Yocto Project 2.6 Release</title>
5689
5690 <para>
5691 This section provides migration information for moving to the
5692 Yocto Project 2.6 Release from the prior release.
5693 </para>
5694
5695 <section id='migration-2.6-gcc-changes'>
5696 <title>GCC 8.2 is Now Used by Default</title>
5697
5698 <para>
5699 The GNU Compiler Collection version 8.2 is now used by default
5700 for compilation.
5701 For more information on what has changed in the GCC 8.x release,
5702 see
5703 <ulink url='https://gcc.gnu.org/gcc-8/changes.html'></ulink>.
5704 </para>
5705
5706 <para>
5707 If you still need to compile with version 7.x, GCC 7.3 is
5708 also provided.
5709 You can select this version by setting the
5710 and can be selected by setting the
5711 <link linkend='var-GCCVERSION'><filename>GCCVERSION</filename></link>
5712 variable to "7.%" in your configuration.
5713 </para>
5714 </section>
5715
5716 <section id='migration-2.6-removed-recipes'>
5717 <title>Removed Recipes</title>
5718
5719 <para>
5720 The following recipes have been removed:
5721 <literallayout class='monospaced'>
5722 <emphasis><filename>beecrypt</filename>:</emphasis> No longer needed since moving to RPM 4.
5723 <emphasis><filename>bigreqsproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5724 <emphasis><filename>calibrateproto</filename>:</emphasis> Removed in favor of <filename>xinput</filename>.
5725 <emphasis><filename>compositeproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5726 <emphasis><filename>damageproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5727 <emphasis><filename>dmxproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5728 <emphasis><filename>dri2proto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5729 <emphasis><filename>dri3proto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5730 <emphasis><filename>eee-acpi-scripts</filename>:</emphasis> Became obsolete.
5731 <emphasis><filename>fixesproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5732 <emphasis><filename>fontsproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5733 <emphasis><filename>fstests</filename>:</emphasis> Became obsolete.
5734 <emphasis><filename>gccmakedep</filename>:</emphasis> No longer used.
5735 <emphasis><filename>glproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5736 <emphasis><filename>gnome-desktop3</filename>:</emphasis> No longer needed. This recipe has moved to <filename>meta-oe</filename>.
5737 <emphasis><filename>icon-naming-utils</filename>:</emphasis> No longer used since the Sato theme was removed in 2016.
5738 <emphasis><filename>inputproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5739 <emphasis><filename>kbproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5740 <emphasis><filename>libusb-compat</filename>:</emphasis> Became obsolete.
5741 <emphasis><filename>libuser</filename>:</emphasis> Became obsolete.
5742 <emphasis><filename>libnfsidmap</filename>:</emphasis> No longer an external requirement since <filename>nfs-utils</filename> 2.2.1. <filename>libnfsidmap</filename> is now integrated.
5743 <emphasis><filename>libxcalibrate</filename>:</emphasis> No longer needed with <filename>xinput</filename>
5744 <emphasis><filename>mktemp</filename>:</emphasis> Became obsolete. The <filename>mktemp</filename> command is provided by both <filename>busybox</filename> and <filename>coreutils</filename>.
5745 <emphasis><filename>ossp-uuid</filename>:</emphasis> Is not being maintained and has mostly been replaced by <filename>uuid.h</filename> in <filename>util-linux</filename>.
5746 <emphasis><filename>pax-utils</filename>:</emphasis> No longer needed. Previous QA tests that did use this recipe are now done at build time.
5747 <emphasis><filename>pcmciautils</filename>:</emphasis> Became obsolete.
5748 <emphasis><filename>pixz</filename>:</emphasis> No longer needed. <filename>xz</filename> now supports multi-threaded compression.
5749 <emphasis><filename>presentproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5750 <emphasis><filename>randrproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5751 <emphasis><filename>recordproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5752 <emphasis><filename>renderproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5753 <emphasis><filename>resourceproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5754 <emphasis><filename>scrnsaverproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5755 <emphasis><filename>trace-cmd</filename>:</emphasis> Became obsolete. <filename>perf</filename> replaced this recipe's functionally.
5756 <emphasis><filename>videoproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5757 <emphasis><filename>wireless-tools</filename>:</emphasis> Became obsolete. Superseded by <filename>iw</filename>.
5758 <emphasis><filename>xcmiscproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5759 <emphasis><filename>xextproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5760 <emphasis><filename>xf86dgaproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5761 <emphasis><filename>xf86driproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5762 <emphasis><filename>xf86miscproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5763 <emphasis><filename>xf86-video-omapfb</filename>:</emphasis> Became obsolete. Use kernel modesetting driver instead.
5764 <emphasis><filename>xf86-video-omap</filename>:</emphasis> Became obsolete. Use kernel modesetting driver instead.
5765 <emphasis><filename>xf86vidmodeproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5766 <emphasis><filename>xineramaproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5767 <emphasis><filename>xproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5768 <emphasis><filename>yasm</filename>:</emphasis> No longer needed since previous usages are now satisfied by <filename>nasm</filename>.
5769 </literallayout>
5770 </para>
5771 </section>
5772
5773 <section id='migration-2.6-packaging-changes'>
5774 <title>Packaging Changes</title>
5775
5776 <para>
5777 The following packaging changes have been made:
5778 <itemizedlist>
5779 <listitem><para>
5780 <emphasis><filename>cmake</filename>:</emphasis>
5781 <filename>cmake.m4</filename> and
5782 <filename>toolchain</filename> files have been moved to the
5783 main package.
5784 </para></listitem>
5785 <listitem><para>
5786 <emphasis><filename>iptables</filename>:</emphasis>
5787 The <filename>iptables</filename> modules have been split
5788 into separate packages.
5789 </para></listitem>
5790 <listitem><para>
5791 <emphasis><filename>alsa-lib</filename>:</emphasis>
5792 <filename>libasound</filename> is now in the main
5793 <filename>alsa-lib</filename> package instead of
5794 <filename>libasound</filename>.
5795 </para></listitem>
5796 <listitem><para>
5797 <emphasis><filename>glibc</filename>:</emphasis>
5798 <filename>libnss-db</filename> is now in its own package
5799 along with a <filename>/var/db/makedbs.sh</filename>
5800 script to update databases.
5801 </para></listitem>
5802 <listitem><para>
5803 <emphasis><filename>python</filename> and <filename>python3</filename>:</emphasis>
5804 The main package has been removed from the recipe.
5805 You must install specific packages or
5806 <filename>python-modules</filename> /
5807 <filename>python3-modules</filename> for everything.
5808 </para></listitem>
5809 <listitem><para>
5810 <emphasis><filename>systemtap</filename>:</emphasis>
5811 Moved <filename>systemtap-exporter</filename> into its own
5812 package.
5813 </para></listitem>
5814 </itemizedlist>
5815 </para>
5816 </section>
5817
5818 <section id='migration-2.6-xorg-protocol-dependencies'>
5819 <title>XOrg Protocol dependencies</title>
5820
5821 <para>
5822 The "*proto" upstream repositories have been combined into one
5823 "xorgproto" repository.
5824 Thus, the corresponding recipes have also been combined into a
5825 single <filename>xorgproto</filename> recipe.
5826 Any recipes that depend upon the older <filename>*proto</filename>
5827 recipes need to be changed to depend on the newer
5828 <filename>xorgproto</filename> recipe instead.
5829 </para>
5830
5831 <para>
5832 For names of recipes removed because of this repository change,
5833 see the
5834 <link linkend="migration-2.6-removed-recipes">Removed Recipes</link>
5835 section.
5836 </para>
5837 </section>
5838
5839 <section id='migration-2.6-distutils-distutils3-fetching-dependencies'>
5840 <title><filename>distutils</filename> and <filename>distutils3</filename> Now Prevent Fetching Dependencies During the <filename>do_configure</filename> Task</title>
5841
5842 <para>
5843 Previously, it was possible for Python recipes that inherited
5844 the
5845 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>
5846 and
5847 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>
5848 classes to fetch code during the
5849 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
5850 task to satisfy dependencies mentioned in
5851 <filename>setup.py</filename> if those dependencies were not
5852 provided in the sysroot (i.e. recipes providing the dependencies
5853 were missing from
5854 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>).
5855 <note>
5856 This change affects classes beyond just the two mentioned
5857 (i.e. <filename>distutils</filename> and
5858 <filename>distutils3</filename>).
5859 Any recipe that inherits <filename>distutils*</filename>
5860 classes are affected.
5861 For example, the <filename>setuptools</filename> and
5862 <filename>setuptools3</filename> recipes are affected since
5863 they inherit the <filename>distutils*</filename> classes.
5864 </note>
5865 </para>
5866
5867 <para>
5868 Fetching these types of dependencies that are not provided in the
5869 sysroot negatively affects the ability to reproduce builds.
5870 This type of fetching is now explicitly disabled.
5871 Consequently, any missing dependencies in Python recipes that
5872 use these classes now result in an error during the
5873 <filename>do_configure</filename> task.
5874 </para>
5875 </section>
5876
5877 <section id='migration-2.6-linux-yocto-configuration-audit-issues-now-correctly-reported'>
5878 <title><filename>linux-yocto</filename> Configuration Audit Issues Now Correctly Reported</title>
5879
5880 <para>
5881 Due to a bug, the kernel configuration audit functionality was
5882 not writing out any resulting warnings during the build.
5883 This issue is now corrected.
5884 You might notice these warnings now if you have a custom kernel
5885 configuration with a <filename>linux-yocto</filename> style
5886 kernel recipe.
5887 </para>
5888 </section>
5889
5890 <section id='migration-2.6-image-kernel-artifact-naming-changes'>
5891 <title>Image/Kernel Artifact Naming Changes</title>
5892
5893 <para>
5894 The following changes have been made:
5895 <itemizedlist>
5896 <listitem><para>
5897 Name variables (e.g.
5898 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>)
5899 use a new <filename>IMAGE_VERSION_SUFFIX</filename>
5900 variable instead of
5901 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>.
5902 Using <filename>IMAGE_VERSION_SUFFIX</filename> allows
5903 easier and more direct changes.</para>
5904
5905 <para>The <filename>IMAGE_VERSION_SUFFIX</filename>
5906 variable is set in the
5907 <filename>bitbake.conf</filename> configuration file as
5908 follows:
5909 <literallayout class='monospaced'>
5910 IMAGE_VERSION_SUFFIX = "-${DATETIME}"
5911 </literallayout>
5912 </para></listitem>
5913 <listitem><para>
5914 Several variables have changed names for consistency:
5915 <literallayout class='monospaced'>
5916 Old Variable Name New Variable Name
5917 ========================================================
5918 KERNEL_IMAGE_BASE_NAME <link linkend='var-KERNEL_IMAGE_NAME'>KERNEL_IMAGE_NAME</link>
5919 KERNEL_IMAGE_SYMLINK_NAME <link linkend='var-KERNEL_IMAGE_LINK_NAME'>KERNEL_IMAGE_LINK_NAME</link>
5920 MODULE_TARBALL_BASE_NAME <link linkend='var-MODULE_TARBALL_NAME'>MODULE_TARBALL_NAME</link>
5921 MODULE_TARBALL_SYMLINK_NAME <link linkend='var-MODULE_TARBALL_LINK_NAME'>MODULE_TARBALL_LINK_NAME</link>
5922 INITRAMFS_BASE_NAME <link linkend='var-INITRAMFS_NAME'>INITRAMFS_NAME</link>
5923 </literallayout>
5924 </para></listitem>
5925 <listitem><para>
5926 The <filename>MODULE_IMAGE_BASE_NAME</filename> variable
5927 has been removed.
5928 The module tarball name is now controlled directly with the
5929 <link linkend='var-MODULE_TARBALL_NAME'><filename>MODULE_TARBALL_NAME</filename></link>
5930 variable.
5931 </para></listitem>
5932 <listitem><para>
5933 The
5934 <link linkend='var-KERNEL_DTB_NAME'><filename>KERNEL_DTB_NAME</filename></link>
5935 and
5936 <link linkend='var-KERNEL_DTB_LINK_NAME'><filename>KERNEL_DTB_LINK_NAME</filename></link>
5937 variables have been introduced to control kernel Device
5938 Tree Binary (DTB) artifact names instead of mangling
5939 <filename>KERNEL_IMAGE_*</filename> variables.
5940 </para></listitem>
5941 <listitem><para>
5942 The
5943 <link linkend='var-KERNEL_FIT_NAME'><filename>KERNEL_FIT_NAME</filename></link>
5944 and
5945 <link linkend='var-KERNEL_FIT_LINK_NAME'><filename>KERNEL_FIT_LINK_NAME</filename></link>
5946 variables have been introduced to specify the name of
5947 flattened image tree (FIT) kernel images similar to other
5948 deployed artifacts.
5949 </para></listitem>
5950 <listitem><para>
5951 The
5952 <link linkend='var-MODULE_TARBALL_NAME'><filename>MODULE_TARBALL_NAME</filename></link>
5953 and
5954 <link linkend='var-MODULE_TARBALL_LINK_NAME'><filename>MODULE_TARBALL_LINK_NAME</filename></link>
5955 variable values no longer include the "module-" prefix or
5956 ".tgz" suffix.
5957 These parts are now hardcoded so that the values are
5958 consistent with other artifact naming variables.
5959 </para></listitem>
5960 <listitem><para>
5961 Added the
5962 <link linkend='var-INITRAMFS_LINK_NAME'><filename>INITRAMFS_LINK_NAME</filename></link>
5963 variable so that the symlink can be controlled similarly
5964 to other artifact types.
5965 </para></listitem>
5966 <listitem><para>
5967 <link linkend='var-INITRAMFS_NAME'><filename>INITRAMFS_NAME</filename></link>
5968 now uses
5969 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
5970 instead of
5971 "${PV}-${PR}-${MACHINE}-${DATETIME}", which
5972 makes it consistent with other variables.
5973 </para></listitem>
5974 </itemizedlist>
5975 </para>
5976 </section>
5977
5978 <section id='migration-2.6-serial-console-deprecated'>
5979 <title><filename>SERIAL_CONSOLE</filename> Deprecated</title>
5980
5981 <para>
5982 The
5983 <link linkend='var-SERIAL_CONSOLE'><filename>SERIAL_CONSOLE</filename></link>
5984 variable has been functionally replaced by the
5985 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
5986 variable for some time.
5987 With the Yocto Project 2.6 release,
5988 <filename>SERIAL_CONSOLE</filename> has been officially deprecated.
5989 </para>
5990
5991 <para>
5992 <filename>SERIAL_CONSOLE</filename> will continue to work as
5993 before for the 2.6 release.
5994 However, for the sake of future compatibility, it is recommended
5995 that you replace all instances of
5996 <filename>SERIAL_CONSOLE</filename> with
5997 <filename>SERIAL_CONSOLES</filename>.
5998 <note>
5999 The only difference in usage is that
6000 <filename>SERIAL_CONSOLES</filename> expects entries to be
6001 separated using semicolons as compared to
6002 <filename>SERIAL_CONSOLE</filename>, which expects spaces.
6003 </note>
6004 </para>
6005 </section>
6006
6007 <section id='migration-2.6-poky-sets-unknown-configure-option-to-qa-error'>
6008 <title>Configure Script Reports Unknown Options as Errors</title>
6009
6010 <para>
6011 If the configure script reports an unknown option, this now
6012 triggers a QA error instead of a warning.
6013 Any recipes that previously got away with specifying such unknown
6014 options now need to be fixed.
6015 </para>
6016 </section>
6017
6018 <section id='migration-2.6-override-changes'>
6019 <title>Override Changes</title>
6020
6021 <para>
6022 The following changes have occurred:
6023 <itemizedlist>
6024 <listitem><para>
6025 <emphasis>The <filename>virtclass-native</filename> and
6026 <filename>virtclass-nativesdk</filename> Overrides Have
6027 Been Removed:</emphasis>
6028 The <filename>virtclass-native</filename> and
6029 <filename>virtclass-nativesdk</filename> overrides have
6030 been deprecated since 2012 in favor of
6031 <filename>class-native</filename> and
6032 <filename>class-nativesdk</filename>, respectively.
6033 Both <filename>virtclass-native</filename> and
6034 <filename>virtclass-nativesdk</filename> are now dropped.
6035 <note>
6036 The <filename>virtclass-multilib-</filename> overrides
6037 for multilib are still valid.
6038 </note>
6039 </para></listitem>
6040 <listitem><para>
6041 <emphasis>The <filename>forcevariable</filename>
6042 Override Now Has a Higher Priority Than
6043 <filename>libc</filename> Overrides:</emphasis>
6044 The <filename>forcevariable</filename> override is
6045 documented to be the highest priority override.
6046 However, due to a long-standing quirk of how
6047 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
6048 is set, the <filename>libc</filename> overrides (e.g.
6049 <filename>libc-glibc</filename>,
6050 <filename>libc-musl</filename>, and so forth) erroneously
6051 had a higher priority.
6052 This issue is now corrected.</para>
6053
6054 <para>It is likely this change will not cause any
6055 problems.
6056 However, it is possible with some unusual configurations
6057 that you might see a change in behavior if you were
6058 relying on the previous behavior.
6059 Be sure to check how you use
6060 <filename>forcevariable</filename> and
6061 <filename>libc-*</filename> overrides in your custom
6062 layers and configuration files to ensure they make sense.
6063 </para></listitem>
6064 <listitem><para>
6065 <emphasis>The <filename>build-${BUILD_OS}</filename>
6066 Override Has Been Removed:</emphasis>
6067 The <filename>build-${BUILD_OS}</filename>, which is
6068 typically <filename>build-linux</filename>, override has
6069 been removed because building on a host operating system
6070 other than a recent version of Linux is neither supported
6071 nor recommended.
6072 Dropping the override avoids giving the impression that
6073 other host operating systems might be supported.
6074 </para></listitem>
6075 <listitem><para>
6076 The "_remove" operator now preserves whitespace.
6077 Consequently, when specifying list items to remove, be
6078 aware that leading and trailing whitespace resulting from
6079 the removal is retained.</para>
6080
6081 <para>See the
6082 "<ulink url='&YOCTO_DOCS_BB_URL;#removing-override-style-syntax'>Removal (Override Style Syntax)</ulink>"
6083 section in the BitBake User Manual for a detailed example.
6084 </para></listitem>
6085 </itemizedlist>
6086 </para>
6087 </section>
6088
6089 <section id='migration-2.6-systemd-configuration-now-split-out-to-system-conf'>
6090 <title><filename>systemd</filename> Configuration is Now Split Into <filename>systemd-conf</filename></title>
6091
6092 <para>
6093 The configuration for the <filename>systemd</filename> recipe
6094 has been moved into a <filename>system-conf</filename> recipe.
6095 Moving this configuration to a separate recipe avoids the
6096 <filename>systemd</filename> recipe from becoming machine-specific
6097 for cases where machine-specific configurations need to be applied
6098 (e.g. for <filename>qemu*</filename> machines).
6099 </para>
6100
6101 <para>
6102 Currently, the new recipe packages the following files:
6103 <literallayout class='monospaced'>
6104 ${sysconfdir}/machine-id
6105 ${sysconfdir}/systemd/coredump.conf
6106 ${sysconfdir}/systemd/journald.conf
6107 ${sysconfdir}/systemd/logind.conf
6108 ${sysconfdir}/systemd/system.conf
6109 ${sysconfdir}/systemd/user.conf
6110 </literallayout>
6111 If you previously used bbappend files to append the
6112 <filename>systemd</filename> recipe to change any of the
6113 listed files, you must do so for the
6114 <filename>systemd-conf</filename> recipe instead.
6115 </para>
6116 </section>
6117
6118 <section id='migration-2.6-automatic-testing-changes'>
6119 <title>Automatic Testing Changes</title>
6120
6121 <para>
6122 This section provides information about automatic testing
6123 changes:
6124 <itemizedlist>
6125 <listitem><para>
6126 <emphasis><filename>TEST_IMAGE</filename> Variable Removed:</emphasis>
6127 Prior to this release, you set the
6128 <filename>TEST_IMAGE</filename> variable to "1" to
6129 enable automatic testing for successfully built images.
6130 The <filename>TEST_IMAGE</filename> variable no longer
6131 exists and has been replaced by the
6132 <link linkend='var-TESTIMAGE_AUTO'><filename>TESTIMAGE_AUTO</filename></link>
6133 variable.
6134 </para></listitem>
6135 <listitem><para>
6136 <emphasis>Inheriting the <filename>testimage</filename> and
6137 <filename>testsdk</filename> Classes:</emphasis>
6138 Best practices now dictate that you use the
6139 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
6140 variable rather than the
6141 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
6142 variable when you inherit the
6143 <link linkend='ref-classes-testimage*'><filename>testimage</filename></link>
6144 and
6145 <link linkend='ref-classes-testsdk'><filename>testsdk</filename></link>
6146 classes used for automatic testing.
6147 </para></listitem>
6148 </itemizedlist>
6149 </para>
6150 </section>
6151
6152 <section id='migration-2.6-openssl-changes'>
6153 <title>OpenSSL Changes</title>
6154
6155 <para>
6156 <ulink url='https://www.openssl.org/'>OpenSSL</ulink> has been
6157 upgraded from 1.0 to 1.1.
6158 By default, this upgrade could cause problems for recipes that
6159 have both versions in their dependency chains.
6160 The problem is that both versions cannot be installed together
6161 at build time.
6162 <note>
6163 It is possible to have both versions of the library at runtime.
6164 </note>
6165 </para>
6166 </section>
6167
6168 <section id='migration-2.6-bitbake-changes'>
6169 <title>BitBake Changes</title>
6170
6171 <para>
6172 The server logfile <filename>bitbake-cookerdaemon.log</filename> is
6173 now always placed in the
6174 <link linkend='build-directory'>Build Directory</link>
6175 instead of the current directory.
6176 </para>
6177 </section>
6178
6179 <section id='migration-2.6-security-changes'>
6180 <title>Security Changes</title>
6181
6182 <para>
6183 The Poky distribution now uses security compiler flags by
6184 default.
6185 Inclusion of these flags could cause new failures due to stricter
6186 checking for various potential security issues in code.
6187 </para>
6188 </section>
6189
6190 <section id='migration-2.6-post-installation-changes'>
6191 <title>Post Installation Changes</title>
6192
6193 <para>
6194 You must explicitly mark post installs to defer to the target.
6195 If you want to explicitly defer a postinstall to first boot on
6196 the target rather than at rootfs creation time, use
6197 <filename>pkg_postinst_ontarget()</filename> or call
6198 <filename>postinst-intercepts defer_to_first_boot</filename> from
6199 <filename>pkg_postinst()</filename>.
6200 Any failure of a <filename>pkg_postinst()</filename> script
6201 (including exit 1) triggers an error during the
6202 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> task.
6203 </para>
6204
6205 <para>
6206 For more information on post-installation behavior, see the
6207 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
6208 section in the Yocto Project Development Tasks Manual.
6209 </para>
6210 </section>
6211
6212 <section id='migration-2.6-python-3-profile-guided-optimizations'>
6213 <title>Python 3 Profile-Guided Optimization</title>
6214
6215 <para>
6216 The <filename>python3</filename> recipe now enables profile-guided
6217 optimization.
6218 Using this optimization requires a little extra build time in
6219 exchange for improved performance on the target at runtime.
6220 Additionally, the optimization is only enabled if the current
6221 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
6222 has support for user-mode emulation in QEMU (i.e. "qemu-usermode"
6223 is in
6224 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>,
6225 which it is by default).
6226 </para>
6227
6228 <para>
6229 If you wish to disable Python profile-guided optimization
6230 regardless of the value of
6231 <filename>MACHINE_FEATURES</filename>, then ensure that
6232 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
6233 for the <filename>python3</filename> recipe does not contain "pgo".
6234 You could accomplish the latter using the following at the
6235 configuration level:
6236 <literallayout class='monospaced'>
6237 PACKAGECONFIG_remove_pn-python3 = "pgo"
6238 </literallayout>
6239 Alternatively, you can set
6240 <filename>PACKAGECONFIG</filename> using an append file for the
6241 <filename>python3</filename> recipe.
6242 </para>
6243 </section>
6244
6245 <section id='migration-2.6-miscellaneous-changes'>
6246 <title>Miscellaneous Changes</title>
6247
6248 <para>
6249 The following miscellaneous changes occurred:
6250 <itemizedlist>
6251 <listitem><para>
6252 Default to using the Thumb-2 instruction set for armv7a
6253 and above.
6254 If you have any custom recipes that build software that
6255 needs to be built with the ARM instruction set, change the
6256 recipe to set the instruction set as follows:
6257 <literallayout class='monospaced'>
6258 ARM_INSTRUCTION_SET = "arm"
6259 </literallayout>
6260 </para></listitem>
6261 <listitem><para>
6262 <filename>run-postinsts</filename> no longer uses
6263 <filename>/etc/*-postinsts</filename> for
6264 <filename>dpkg/opkg</filename> in favor of built-in
6265 postinst support.
6266 RPM behavior remains unchanged.
6267 </para></listitem>
6268 <listitem><para>
6269 The <filename>NOISO</filename> and
6270 <filename>NOHDD</filename> variables are no longer used.
6271 You now control building <filename>*.iso</filename> and
6272 <filename>*.hddimg</filename> image types directly
6273 by using the
6274 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6275 variable.
6276 </para></listitem>
6277 <listitem><para>
6278 The <filename>scripts/contrib/mkefidisk.sh</filename>
6279 has been removed in favor of Wic.
6280 </para></listitem>
6281 <listitem><para>
6282 <filename>kernel-modules</filename> has been removed from
6283 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
6284 for <filename>qemumips</filename> and
6285 <filename>qemumips64</filename> machines.
6286 Removal also impacts the <filename>x86-base.inc</filename>
6287 file.
6288 <note>
6289 <filename>genericx86</filename> and
6290 <filename>genericx86-64</filename> retain
6291 <filename>kernel-modules</filename> as part of the
6292 <filename>RRECOMMENDS</filename> variable setting.
6293 </note>
6294 </para></listitem>
6295 <listitem><para>
6296 The <filename>LGPLv2_WHITELIST_GPL-3.0</filename>
6297 variable has been removed.
6298 If you are setting this variable in your configuration,
6299 set or append it to the
6300 <filename>WHITELIST_GPL-3.0</filename> variable instead.
6301 </para></listitem>
6302 <listitem><para>
6303 <filename>${ASNEEDED}</filename> is now included in
6304 the
6305 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
6306 variable directly.
6307 The remaining definitions from
6308 <filename>meta/conf/distro/include/as-needed.inc</filename>
6309 have been moved to corresponding recipes.
6310 </para></listitem>
6311 <listitem><para>
6312 Support for DSA host keys has been dropped from the
6313 OpenSSH recipes.
6314 If you are still using DSA keys, you must switch over to a
6315 more secure algorithm as recommended by OpenSSH upstream.
6316 </para></listitem>
6317 <listitem><para>
6318 The <filename>dhcp</filename> recipe now uses the
6319 <filename>dhcpd6.conf</filename> configuration file in
6320 <filename>dhcpd6.service</filename> for IPv6 DHCP rather
6321 than re-using <filename>dhcpd.conf</filename>, which is
6322 now reserved for IPv4.
6323 </para></listitem>
6324 </itemizedlist>
6325 </para>
6326 </section>
6327</section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006328</chapter>
6329<!--
6330vim: expandtab tw=80 ts=4
6331-->