summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/migration.xml
diff options
context:
space:
mode:
authorAdrian Dudau <adrian.dudau@enea.com>2013-12-12 13:46:05 +0100
committerAdrian Dudau <adrian.dudau@enea.com>2013-12-12 13:47:32 +0100
commit14b00ff23a912494edc7f146e668c40ca82b8508 (patch)
treef7f4e592ccb935bc312cfa0cfc3c0cbbe444970d /documentation/ref-manual/migration.xml
downloadyocto-docs-14b00ff23a912494edc7f146e668c40ca82b8508.tar.gz
initial commit of Enea Linux 3.1HEADmaster
Migrated from the internal git server on the dora-enea branch Signed-off-by: Adrian Dudau <adrian.dudau@enea.com>
Diffstat (limited to 'documentation/ref-manual/migration.xml')
-rw-r--r--documentation/ref-manual/migration.xml1089
1 files changed, 1089 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
new file mode 100644
index 0000000..dc24628
--- /dev/null
+++ b/documentation/ref-manual/migration.xml
@@ -0,0 +1,1089 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='migration'>
6<title>Migrating to a Newer Yocto Project Release</title>
7
8 <para>
9 This chapter provides information you can use to migrate work to a
10 newer Yocto Project release. You can find the same information in the
11 release notes for a given release.
12 </para>
13
14<section id='moving-to-the-yocto-project-1.3-release'>
15 <title>Moving to the Yocto Project 1.3 Release</title>
16
17 <para>
18 This section provides migration information for moving to the
19 Yocto Project 1.3 Release from the prior release.
20 </para>
21
22 <section id='1.3-local-configuration'>
23 <title>Local Configuration</title>
24
25 <para>
26 Differences include changes for
27 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
28 and <filename>bblayers.conf</filename>.
29 </para>
30
31 <section id='migration-1.3-sstate-mirrors'>
32 <title>SSTATE_MIRRORS</title>
33
34 <para>
35 The shared state cache (sstate-cache), as pointed to by
36 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, by default
37 now has two-character subdirectories to prevent issues arising
38 from too many files in the same directory.
39 Also, native sstate-cache packages will go into a subdirectory named using
40 the distro ID string.
41 If you copy the newly structured sstate-cache to a mirror location
42 (either local or remote) and then point to it in
43 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
44 you need to append "PATH" to the end of the mirror URL so that
45 the path used by BitBake before the mirror substitution is
46 appended to the path used to access the mirror.
47 Here is an example:
48 <literallayout class='monospaced'>
49 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
50 </literallayout>
51 </para>
52 </section>
53
54 <section id='migration-1.3-bblayers-conf'>
55 <title>bblayers.conf</title>
56
57 <para>
58 The <filename>meta-yocto</filename> layer consists of two parts
59 that correspond to the Poky reference distribution and the
60 reference hardware Board Support Packages (BSPs), respectively:
61 <filename>meta-yocto</filename> and
62 <filename>meta-yocto-bsp</filename>.
63 When running BitBake or Hob for the first time after upgrading,
64 your <filename>conf/bblayers.conf</filename> file will be
65 updated to handle this change and you will be asked to
66 re-run or restart for the changes to take effect.
67 </para>
68 </section>
69 </section>
70
71 <section id='1.3-recipes'>
72 <title>Recipes</title>
73
74 <para>
75 Differences include changes for the following:
76 <itemizedlist>
77 <listitem><para>Python function whitespace</para></listitem>
78 <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem>
79 <listitem><para><filename>nativesdk</filename></para></listitem>
80 <listitem><para>Task recipes</para></listitem>
81 <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem>
82 <listitem><para>Removed recipes</para></listitem>
83 </itemizedlist>
84 </para>
85
86 <section id='migration-1.3-python-function-whitespace'>
87 <title>Python Function Whitespace</title>
88
89 <para>
90 All Python functions must now use four spaces for indentation.
91 Previously, an inconsistent mix of spaces and tabs existed,
92 which made extending these functions using
93 <filename>_append</filename> or <filename>_prepend</filename>
94 complicated given that Python treats whitespace as
95 syntactically significant.
96 If you are defining or extending any Python functions (e.g.
97 <filename>populate_packages</filename>, <filename>do_unpack</filename>,
98 <filename>do_patch</filename> and so forth) in custom recipes
99 or classes, you need to ensure you are using consistent
100 four-space indentation.
101 </para>
102 </section>
103
104 <section id='migration-1.3-proto=-in-src-uri'>
105 <title>proto= in SRC_URI</title>
106
107 <para>
108 Any use of <filename>proto=</filename> in
109 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
110 needs to be changed to <filename>protocol=</filename>.
111 In particular, this applies to the following URIs:
112 <itemizedlist>
113 <listitem><para><filename>svn://</filename></para></listitem>
114 <listitem><para><filename>bzr://</filename></para></listitem>
115 <listitem><para><filename>hg://</filename></para></listitem>
116 <listitem><para><filename>osc://</filename></para></listitem>
117 </itemizedlist>
118 Other URIs were already using <filename>protocol=</filename>.
119 This change improves consistency.
120 </para>
121 </section>
122
123 <section id='migration-1.3-nativesdk'>
124 <title>nativesdk</title>
125
126 <para>
127 The suffix <filename>nativesdk</filename> is now implemented
128 as a prefix, which simplifies a lot of the packaging code for
129 <filename>nativesdk</filename> recipes.
130 All custom <filename>nativesdk</filename> recipes and any
131 references need to be updated to use
132 <filename>nativesdk-*</filename> instead of
133 <filename>*-nativesdk</filename>.
134 </para>
135 </section>
136
137 <section id='migration-1.3-task-recipes'>
138 <title>Task Recipes</title>
139
140 <para>
141 "Task" recipes are now known as "Package groups" and have
142 been renamed from <filename>task-*.bb</filename> to
143 <filename>packagegroup-*.bb</filename>.
144 Existing references to the previous <filename>task-*</filename>
145 names should work in most cases as there is an automatic
146 upgrade path for most packages.
147 However, you should update references in your own recipes and
148 configurations as they could be removed in future releases.
149 You should also rename any custom <filename>task-*</filename>
150 recipes to <filename>packagegroup-*</filename>, and change
151 them to inherit <filename>packagegroup</filename> instead of
152 <filename>task</filename>, as well as taking the opportunity
153 to remove anything now handled by
154 <filename>packagegroup.bbclass</filename>, such as providing
155 <filename>-dev</filename> and <filename>-dbg</filename>
156 packages, setting
157 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
158 and so forth.
159 See the
160 "<link linkend='ref-classes-packagegroup'>Package Groups - packagegroup.bbclass</link>"
161 section for further details.
162 </para>
163 </section>
164
165 <section id='migration-1.3-image-features'>
166 <title>IMAGE_FEATURES</title>
167
168 <para>
169 Image recipes that previously included "apps-console-core"
170 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
171 should now include "splash" instead to enable the boot-up
172 splash screen.
173 Retaining "apps-console-core" will still include the splash
174 screen but generates a warning.
175 The "apps-x11-core" and "apps-x11-games"
176 <filename>IMAGE_FEATURES</filename> features have been removed.
177 </para>
178 </section>
179
180 <section id='migration-1.3-removed-recipes'>
181 <title>Removed Recipes</title>
182
183 <para>
184 The following recipes have been removed.
185 For most of them, it is unlikely that you would have any
186 references to them in your own
187 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>.
188 However, you should check your metadata against this list to be sure:
189 <itemizedlist>
190 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
191 Replaced by <filename>libx11</filename>, which has a negligible
192 size difference with modern Xorg.</para></listitem>
193 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
194 Use <filename>xserver-xorg</filename>, which has a negligible
195 size difference when DRI and GLX modules are not installed.</para></listitem>
196 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
197 Effectively unmaintained for many years.</para></listitem>
198 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
199 No longer serves any purpose.</para></listitem>
200 <listitem><para><emphasis><filename>galago</filename></emphasis>:
201 Replaced by telepathy.</para></listitem>
202 <listitem><para><emphasis><filename>gail</filename></emphasis>:
203 Functionality was integrated into GTK+ 2.13.</para></listitem>
204 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
205 No longer needed.</para></listitem>
206 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
207 The build has been restructured to avoid the need for
208 this step.</para></listitem>
209 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
210 Unmaintained for many years.
211 Functionality now provided by
212 <filename>ofono</filename> instead.</para></listitem>
213 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
214 Largely unmaintained PIM application suite.
215 It has been moved to <filename>meta-gnome</filename>
216 in <filename>meta-openembedded</filename>.</para></listitem>
217 </itemizedlist>
218 In addition to the previously listed changes, the
219 <filename>meta-demoapps</filename> directory has also been removed
220 because the recipes in it were not being maintained and many
221 had become obsolete or broken.
222 Additionally, these recipes were not parsed in the default configuration.
223 Many of these recipes are already provided in an updated and
224 maintained form within the OpenEmbedded community layers such as
225 <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
226 For the remainder, you can now find them in the
227 <filename>meta-extras</filename> repository, which is in the
228 Yocto Project
229 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>.
230 </para>
231 </section>
232 </section>
233
234 <section id='1.3-linux-kernel-naming'>
235 <title>Linux Kernel Naming</title>
236
237 <para>
238 The naming scheme for kernel output binaries has been changed to
239 now include
240 <link linkend='var-PE'><filename>PE</filename></link> as part of the
241 filename:
242 <literallayout class='monospaced'>
243 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
244 </literallayout>
245 </para>
246
247 <para>
248 Because the <filename>PE</filename> variable is not set by default,
249 these binary files could result with names that include two dash
250 characters.
251 Here is an example:
252 <literallayout class='monospaced'>
253 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
254 </literallayout>
255 </para>
256 </section>
257</section>
258
259<section id='moving-to-the-yocto-project-1.4-release'>
260 <title>Moving to the Yocto Project 1.4 Release</title>
261
262 <para>
263 This section provides migration information for moving to the
264 Yocto Project 1.4 Release from the prior release.
265 </para>
266
267 <section id='migration-1.4-bitbake'>
268 <title>BitBake</title>
269
270 <para>
271 Differences include the following:
272 <itemizedlist>
273 <listitem><para><emphasis>Comment Continuation:</emphasis>
274 If a comment ends with a line continuation (\) character,
275 then the next line must also be a comment.
276 Any instance where this is not the case, now triggers
277 a warning.
278 You must either remove the continuation character, or be
279 sure the next line is a comment.
280 </para></listitem>
281 <listitem><para><emphasis>Package Name Overrides:</emphasis>
282 The runtime package specific variables
283 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
284 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
285 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
286 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
287 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
288 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
289 <link linkend='var-FILES'><filename>FILES</filename></link>,
290 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
291 and the pre, post, install, and uninstall script functions
292 <filename>pkg_preinst</filename>,
293 <filename>pkg_postinst</filename>,
294 <filename>pkg_prerm</filename>, and
295 <filename>pkg_postrm</filename> should always have a
296 package name override.
297 For example, use <filename>RDEPENDS_${PN}</filename> for
298 the main package instead of <filename>RDEPENDS</filename>.
299 BitBake uses more strict checks when it parses recipes.
300 </para></listitem>
301 </itemizedlist>
302 </para>
303 </section>
304
305 <section id='migration-1.4-build-behavior'>
306 <title>Build Behavior</title>
307
308 <para>
309 Differences include the following:
310 <itemizedlist>
311 <listitem><para><emphasis>Shared State Code:</emphasis>
312 The shared state code has been optimized to avoid running
313 unnecessary tasks.
314 For example,
315 <filename>bitbake -c rootfs some-image</filename> from
316 shared state no longer populates the target sysroot
317 since that is not necessary.
318 Instead, the system just needs to extract the output
319 package contents, re-create the packages, and construct
320 the root filesystem.
321 This change is unlikely to cause any problems unless
322 you have missing declared dependencies.
323 </para></listitem>
324 <listitem><para><emphasis>Scanning Directory Names:</emphasis>
325 When scanning for files in
326 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
327 the build system now uses
328 <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
329 instead of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
330 for the directory names.
331 In general, the values previously in
332 <filename>OVERRIDES</filename> are now in
333 <filename>FILESOVERRIDES</filename> as well.
334 However, if you relied upon an additional value
335 you previously added to <filename>OVERRIDES</filename>,
336 you might now need to add it to
337 <filename>FILESOVERRIDES</filename> unless you are already
338 adding it through the
339 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>
340 or <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
341 variables, as appropriate.
342 For more related changes, see the
343 "<link linkend='migration-1.4-variables'>Variables</link>"
344 section.
345 </para></listitem>
346 </itemizedlist>
347 </para>
348 </section>
349
350
351 <section id='migration-1.4-proxies-and-fetching-source'>
352 <title>Proxies and Fetching Source</title>
353
354 <para>
355 A new <filename>oe-git-proxy</filename> script has been added to
356 replace previous methods of handling proxies and fetching source
357 from Git.
358 See the <filename>meta-yocto/conf/site.conf.sample</filename> file
359 for information on how to use this script.
360 </para>
361 </section>
362
363 <section id='migration-1.4-custom-interfaces-file-netbase-change'>
364 <title>Custom Interfaces File (netbase change)</title>
365
366 <para>
367 If you have created your own custom
368 <filename>etc/network/interfaces</filename> file by creating
369 an append file for the <filename>netbase</filename> recipe,
370 you now need to create an append file for the
371 <filename>init-ifupdown</filename> recipe instead, which you can
372 find in the
373 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
374 at <filename>meta/recipes-core/init-ifupdown</filename>.
375 For information on how to use append files, see the
376 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
377 in the Yocto Project Development Manual.
378 </para>
379 </section>
380
381 <section id='migration-1.4-remote-debugging'>
382 <title>Remote Debugging</title>
383
384 <para>
385 Support for remote debugging with the Eclipse IDE is now
386 separated into an image feature
387 (<filename>eclipse-debug</filename>) that corresponds to the
388 <filename>packagegroup-core-eclipse-debug</filename> package group.
389 Previously, the debugging feature was included through the
390 <filename>tools-debug</filename> image feature, which corresponds
391 to the <filename>packagegroup-core-tools-debug</filename>
392 package group.
393 </para>
394 </section>
395
396 <section id='migration-1.4-variables'>
397 <title>Variables</title>
398
399 <para>
400 The following variables have changed:
401 <itemizedlist>
402 <listitem><para><emphasis><filename>SANITY_TESTED_DISTROS</filename>:</emphasis>
403 This variable now uses a distribution ID, which is composed
404 of the host distributor ID followed by the release.
405 Previously,
406 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
407 was composed of the description field.
408 For example, "Ubuntu 12.10" becomes "Ubuntu-12.10".
409 You do not need to worry about this change if you are not
410 specifically setting this variable, or if you are
411 specifically setting it to "".
412 </para></listitem>
413 <listitem><para><emphasis><filename>SRC_URI</filename>:</emphasis>
414 The <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>,
415 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>,
416 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>,
417 and <filename>FILE_DIRNAME</filename> directories have been
418 dropped from the default value of the
419 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
420 variable, which is used as the search path for finding files
421 referred to in
422 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
423 If you have a recipe that relied upon these directories,
424 which would be unusual, then you will need to add the
425 appropriate paths within the recipe or, alternatively,
426 rearrange the files.
427 The most common locations are still covered by
428 <filename>${BP}</filename>, <filename>${BPN}</filename>,
429 and "files", which all remain in the default value of
430 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
431 </para></listitem>
432 </itemizedlist>
433 </para>
434 </section>
435
436 <section id='migration-target-package-management-with-rpm'>
437 <title>Target Package Management with RPM</title>
438
439 <para>
440 If runtime package management is enabled and the RPM backend
441 is selected, Smart is now installed for package download, dependency
442 resolution, and upgrades instead of Zypper.
443 For more information on how to use Smart, run the following command
444 on the target:
445 <literallayout class='monospaced'>
446 smart --help
447 </literallayout>
448 </para>
449 </section>
450
451 <section id='migration-1.4-recipes-moved'>
452 <title>Recipes Moved</title>
453
454 <para>
455 The following recipes were moved from their previous locations
456 because they are no longer used by anything in
457 the OpenEmbedded-Core:
458 <itemizedlist>
459 <listitem><para><emphasis><filename>clutter-box2d</filename>:</emphasis>
460 Now resides in the <filename>meta-oe</filename> layer.
461 </para></listitem>
462 <listitem><para><emphasis><filename>evolution-data-server</filename>:</emphasis>
463 Now resides in the <filename>meta-gnome</filename> layer.
464 </para></listitem>
465 <listitem><para><emphasis><filename>gthumb</filename>:</emphasis>
466 Now resides in the <filename>meta-gnome</filename> layer.
467 </para></listitem>
468 <listitem><para><emphasis><filename>gtkhtml2</filename>:</emphasis>
469 Now resides in the <filename>meta-oe</filename> layer.
470 </para></listitem>
471 <listitem><para><emphasis><filename>gupnp</filename>:</emphasis>
472 Now resides in the <filename>meta-multimedia</filename> layer.
473 </para></listitem>
474 <listitem><para><emphasis><filename>gypsy</filename>:</emphasis>
475 Now resides in the <filename>meta-oe</filename> layer.
476 </para></listitem>
477 <listitem><para><emphasis><filename>libcanberra</filename>:</emphasis>
478 Now resides in the <filename>meta-gnome</filename> layer.
479 </para></listitem>
480 <listitem><para><emphasis><filename>libgdata</filename>:</emphasis>
481 Now resides in the <filename>meta-gnome</filename> layer.
482 </para></listitem>
483 <listitem><para><emphasis><filename>libmusicbrainz</filename>:</emphasis>
484 Now resides in the <filename>meta-multimedia</filename> layer.
485 </para></listitem>
486 <listitem><para><emphasis><filename>metacity</filename>:</emphasis>
487 Now resides in the <filename>meta-gnome</filename> layer.
488 </para></listitem>
489 <listitem><para><emphasis><filename>polkit</filename>:</emphasis>
490 Now resides in the <filename>meta-oe</filename> layer.
491 </para></listitem>
492 <listitem><para><emphasis><filename>zeroconf</filename>:</emphasis>
493 Now resides in the <filename>meta-networking</filename> layer.
494 </para></listitem>
495 </itemizedlist>
496 </para>
497 </section>
498
499 <section id='migration-1.4-removals-and-renames'>
500 <title>Removals and Renames</title>
501
502 <para>
503 The following list shows what has been removed or renamed:
504 <itemizedlist>
505 <listitem><para><emphasis><filename>evieext</filename>:</emphasis>
506 Removed because it has been removed from
507 <filename>xserver</filename> since 2008.
508 </para></listitem>
509 <listitem><para><emphasis>Gtk+ DirectFB:</emphasis>
510 Removed support because upstream Gtk+ no longer supports it
511 as of version 2.18.
512 </para></listitem>
513 <listitem><para><emphasis><filename>libxfontcache / xfontcacheproto</filename>:</emphasis>
514 Removed because they were removed from the Xorg server in 2008.
515 </para></listitem>
516 <listitem><para><emphasis><filename>libxp / libxprintapputil / libxprintutil / printproto</filename>:</emphasis>
517 Removed because the XPrint server was removed from
518 Xorg in 2008.
519 </para></listitem>
520 <listitem><para><emphasis><filename>libxtrap / xtrapproto</filename>:</emphasis>
521 Removed because their functionality was broken upstream.
522 </para></listitem>
523 <listitem><para><emphasis>linux-yocto 3.0 kernel:</emphasis>
524 Removed with linux-yocto 3.8 kernel being added.
525 The linux-yocto 3.2 and linux-yocto 3.4 kernels remain
526 as part of the release.
527 </para></listitem>
528 <listitem><para><emphasis><filename>lsbsetup</filename>:</emphasis>
529 Removed with functionality now provided by
530 <filename>lsbtest</filename>.
531 </para></listitem>
532 <listitem><para><emphasis><filename>matchbox-stroke</filename>:</emphasis>
533 Removed because it was never more than a proof-of-concept.
534 </para></listitem>
535 <listitem><para><emphasis><filename>matchbox-wm-2 / matchbox-theme-sato-2</filename>:</emphasis>
536 Removed because they are not maintained.
537 However, <filename>matchbox-wm</filename> and
538 <filename>matchbox-theme-sato</filename> are still
539 provided.
540 </para></listitem>
541 <listitem><para><emphasis><filename>mesa-dri</filename>:</emphasis>
542 Renamed to <filename>mesa</filename>.
543 </para></listitem>
544 <listitem><para><emphasis><filename>mesa-xlib</filename>:</emphasis>
545 Removed because it was no longer useful.
546 </para></listitem>
547 <listitem><para><emphasis><filename>mutter</filename>:</emphasis>
548 Removed because nothing ever uses it and the recipe is
549 very old.
550 </para></listitem>
551 <listitem><para><emphasis><filename>orinoco-conf</filename>:</emphasis>
552 Removed because it has become obsolete.
553 </para></listitem>
554 <listitem><para><emphasis><filename>update-modules</filename>:</emphasis>
555 Removed because it is no longer used.
556 The kernel module <filename>postinstall</filename> and
557 <filename>postrm</filename> scripts can now do the same
558 task without the use of this script.
559 </para></listitem>
560 <listitem><para><emphasis><filename>web</filename>:</emphasis>
561 Removed because it is not maintained. Superseded by
562 <filename>web-webkit</filename>.
563 </para></listitem>
564 <listitem><para><emphasis><filename>xf86bigfontproto</filename>:</emphasis>
565 Removed because upstream it has been disabled by default
566 since 2007.
567 Nothing uses <filename>xf86bigfontproto</filename>.
568 </para></listitem>
569 <listitem><para><emphasis><filename>xf86rushproto</filename>:</emphasis>
570 Removed because its dependency in
571 <filename>xserver</filename> was spurious and it was
572 removed in 2005.
573 </para></listitem>
574 <listitem><para><emphasis><filename>zypper / libzypp / sat-solver</filename>:</emphasis>
575 Removed and been functionally replaced with Smart
576 (<filename>python-smartpm</filename>) when RPM packaging
577 is used and package management is enabled on the target.
578 </para></listitem>
579 </itemizedlist>
580 </para>
581 </section>
582</section>
583
584<section id='moving-to-the-yocto-project-1.5-release'>
585 <title>Moving to the Yocto Project 1.5 Release</title>
586
587 <para>
588 This section provides migration information for moving to the
589 Yocto Project 1.5 Release from the prior release.
590 </para>
591
592 <section id='migration-1.5-host-dependency-changes'>
593 <title>Host Dependency Changes</title>
594
595 <para>
596 The OpenEmbedded build system now has some additional requirements
597 on the host system:
598 <itemizedlist>
599 <listitem><para>Python 2.7.3+</para></listitem>
600 <listitem><para>Tar 1.24+</para></listitem>
601 <listitem><para>Git 1.7.5+</para></listitem>
602 <listitem><para>Patched version of Make if you are using
603 3.82.
604 Most distributions that provide Make 3.82 use the patched
605 version.</para></listitem>
606 </itemizedlist>
607 If the Linux distribution you are using on your build host
608 does not provide packages for these, you can install and use
609 the Buildtools tarball, which provides an SDK-like environment
610 containing them.
611 </para>
612
613 <para>
614 For more information on this requirement, see the
615 "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
616 section.
617 </para>
618 </section>
619
620 <section id='migration-1.5-atom-pc-bsp'>
621 <title><filename>atom-pc</filename> Board Support Package (BSP)</title>
622
623 <para>
624 The <filename>atom-pc</filename> hardware reference BSP has been
625 replaced by a <filename>genericx86</filename> BSP.
626 This BSP is not necessarily guaranteed to work on all x86
627 hardware, but it will run on a wider range of systems than the
628 <filename>atom-pc</filename> did.
629 <note>
630 Additionally, a <filename>genericx86-64</filename> BSP has been
631 added for 64-bit systems.
632 </note>
633 </para>
634 </section>
635
636 <section id='migration-1.5-bitbake'>
637 <title>BitBake</title>
638
639 <para>
640 The following changes have been made that relate to BitBake:
641 <itemizedlist>
642 <listitem><para>
643 BitBake now supports a <filename>_remove</filename>
644 operator.
645 The addition of this operator means you will have to
646 rename any items in recipe space (functions, variables)
647 whose names currently contain
648 <filename>_remove_</filename> or end with
649 <filename>_remove</filename> to avoid unexpected behavior.
650 </para></listitem>
651 <listitem><para>
652 BitBake's global method pool has been removed.
653 This method is not particularly useful and led to clashes
654 between recipes containing functions that had the
655 same name.</para></listitem>
656 <listitem><para>
657 The "none" server backend has been removed.
658 The "process" server backend has been serving well as the
659 default for a long time now.</para></listitem>
660 <listitem><para>
661 The <filename>bitbake-runtask</filename> script has been
662 removed.</para></listitem>
663 <listitem><para>
664 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>
665 and
666 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>
667 are no longer added to
668 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
669 by default in <filename>bitbake.conf</filename>.
670 These version-specific <filename>PROVIDES</filename>
671 items were seldom used.
672 Attempting to use them could result in two versions being
673 built simultaneously rather than just one version due to
674 the way BitBake resolves dependencies.</para></listitem>
675 </itemizedlist>
676 </para>
677 </section>
678
679 <section id='migration-1.5-qa-warnings'>
680 <title>QA Warnings</title>
681
682 <para>
683 The following changes have been made to the package QA checks:
684 <itemizedlist>
685 <listitem><para>
686 If you have customized
687 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
688 or <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link>
689 values in your configuration, check that they contain all of
690 the issues that you wish to be reported.
691 Previous Yocto Project versions contained a bug that meant
692 that any item not mentioned in <filename>ERROR_QA</filename>
693 or <filename>WARN_QA</filename> would be treated as a
694 warning.
695 Consequently, several important items were not already in
696 the default value of <filename>WARN_QA</filename>.
697 All of the possible QA checks are now documented in the
698 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
699 section.</para></listitem>
700 <listitem><para>
701 An additional QA check has been added to check if
702 <filename>/usr/share/info/dir</filename> is being installed.
703 Your recipe should delete this file within
704 <filename>do_install</filename> if "make install" is
705 installing it.</para></listitem>
706 <listitem><para>
707 If you are using the buildhistory class, the check for the
708 package version going backwards is now controlled using a
709 standard QA check.
710 Thus, if you have customized your
711 <filename>ERROR_QA</filename> or
712 <filename>WARN_QA</filename> values and still wish to have
713 this check performed, you should add
714 "version-going-backwards" to your value for one or the
715 other variables depending on how you wish it to be handled.
716 See the documented QA checks in the
717 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
718 section.
719 </para></listitem>
720 </itemizedlist>
721 </para>
722 </section>
723
724 <section id='migration-1.5-directory-layout-changes'>
725 <title>Directory Layout Changes</title>
726
727 <para>
728 The following directory changes exist:
729 <itemizedlist>
730 <listitem><para>
731 Output SDK installer files are now named to include the
732 image name and tuning architecture through the
733 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
734 variable.</para></listitem>
735 <listitem><para>
736 Images and related files are now installed into a directory
737 that is specific to the machine, instead of a parent
738 directory containing output files for multiple machines.
739 The
740 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
741 variable continues to point to the directory containing
742 images for the current
743 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
744 and should be used anywhere there is a need to refer to
745 this directory.
746 The <filename>runqemu</filename> script now uses this
747 variable to find images and kernel binaries and will use
748 BitBake to determine the directory.
749 Alternatively, you can set the
750 <filename>DEPLOY_DIR_IMAGE</filename> variable in the
751 external environment.</para></listitem>
752 <listitem><para>
753 When buildhistory is enabled, its output is now written
754 under the
755 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
756 rather than
757 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>.
758 Doing so makes it easier to delete
759 <filename>TMPDIR</filename> and preserve the build history.
760 Additionally, data for produced SDKs is now split by
761 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>.
762 </para></listitem>
763 <listitem><para>
764 The <filename>pkgdata</filename> directory produced as
765 part of the packaging process has been collapsed into a
766 single machine-specific directory.
767 This directory is located under
768 <filename>sysroots</filename> and uses a machine-specific
769 name (i.e.
770 <filename>tmp/sysroots/&lt;machine&gt;/pkgdata</filename>).
771 </para></listitem>
772 </itemizedlist>
773 </para>
774 </section>
775
776 <section id='migration-1.5-shortened-git-srcrev-values'>
777 <title>Shortened Git <filename>SRCREV</filename> Values</title>
778
779 <para>
780 BitBake will now shorten revisions from Git repositories from the
781 normal 40 characters down to 10 characters within
782 <link linkend='var-SRCPV'><filename>SRCPV</filename></link>
783 for improved usability in path and file names.
784 This change should be safe within contexts where these revisions
785 are used because the chances of spatially close collisions
786 is very low.
787 Distant collisions are not a major issue in the way
788 the values are used.
789 </para>
790 </section>
791
792 <section id='migration-1.5-image-features'>
793 <title><filename>IMAGE_FEATURES</filename></title>
794
795 <para>
796 The following changes have been made that relate to
797 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
798 <itemizedlist>
799 <listitem><para>
800 The value of
801 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
802 is now validated to ensure invalid feature items are not
803 added.
804 Some users mistakenly add package names to this variable
805 instead of using
806 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
807 in order to have the package added to the image, which does
808 not work.
809 This change is intended to catch those kinds of situations.
810 Valid <filename>IMAGE_FEATURES</filename> are drawn from
811 <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
812 definitions,
813 <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link>
814 and a new "validitems" varflag on
815 <filename>IMAGE_FEATURES</filename>.
816 The "validitems" varflag change allows additional features
817 to be added if they are not provided using the previous
818 two mechanisms.
819 </para></listitem>
820 <listitem><para>
821 The previously deprecated "apps-console-core"
822 <filename>IMAGE_FEATURES</filename> item is no longer
823 supported.
824 Add "splash" to <filename>IMAGE_FEATURES</filename> if you
825 wish to have the splash screen enabled, since this is
826 all that apps-console-core was doing.</para></listitem>
827 </itemizedlist>
828 </para>
829 </section>
830
831 <section id='migration-1.5-run'>
832 <title><filename>run</filename></title>
833
834 <para>
835 The <filename>run</filename> directory from the Filesystem
836 Hierarchy Standard 3.0 has been introduced.
837 You can find some of the implications for this change
838 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873'>here</ulink>.
839 The change also means that recipes that install files to
840 <filename>/var/run</filename> must be changed.
841 You can find a guide on how to make these changes
842 <ulink url='http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530'>here</ulink>.
843 </para>
844 </section>
845
846 <section id='migration-1.5-removal-of-package-manager-database-within-image-recipes'>
847 <title>Removal of Package Manager Database Within Image Recipes</title>
848
849 <para>
850 The image <filename>core-image-minimal</filename> no longer adds
851 <filename>remove_packaging_data_files</filename> to
852 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
853 This addition is now handled automatically when "package-management"
854 is not in
855 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
856 If you have custom image recipes that make this addition,
857 you should remove the lines, as they are not needed and might
858 interfere with correct operation of postinstall scripts.
859 </para>
860 </section>
861
862 <section id='migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time'>
863 <title>Images Now Rebuild Only on Changes Instead of Every Time</title>
864
865 <para>
866 The <filename>do_rootfs</filename> and other related image
867 construction tasks are no longer marked as "nostamp".
868 Consequently, they will only be re-executed when their inputs have
869 changed.
870 Previous versions of the OpenEmbedded build system always rebuilt
871 the image when requested rather when necessary.
872 </para>
873 </section>
874
875 <section id='migration-1.5-task-recipes'>
876 <title>Task Recipes</title>
877
878 <para>
879 The previously deprecated <filename>task.bbclass</filename> has
880 now been dropped.
881 For recipes that previously inherited from this task, you should
882 rename them from <filename>task-*</filename> to
883 <filename>packagegroup-*</filename> and inherit packagegroup
884 instead.
885 </para>
886
887 <para>
888 For more information, see the
889 "<link linkend='ref-classes-packagegroup'>Package Groups - <filename>packagegroup.bbclass</filename></link>"
890 section.
891 </para>
892 </section>
893
894 <section id='migration-1.5-busybox'>
895 <title>BusyBox</title>
896
897 <para>
898 By default, we now split BusyBox into two binaries:
899 one that is suid root for those components that need it, and
900 another for the rest of the components.
901 Splitting BusyBox allows for optimization that eliminates the
902 <filename>tinylogin</filename> recipe as recommended by upstream.
903 You can disable this split by setting
904 <link linkend='var-BUSYBOX_SPLIT_SUID'><filename>BUSYBOX_SPLIT_SUID</filename></link>
905 to "0".
906 </para>
907 </section>
908
909 <section id='migration-1.5-automated-image-testing'>
910 <title>Automated Image Testing</title>
911
912 <para>
913 A new automated image testing framework has been added
914 through the
915 <link linkend='ref-classes-testimage'><filename>testimage*.bbclass</filename></link>
916 class.
917 This framework replaces the older
918 <filename>imagetest-qemu</filename> framework.
919 </para>
920
921 <para>
922 You can learn more about performing automated image tests in the
923 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
924 section.
925 </para>
926 </section>
927
928 <section id='migration-1.5-build-history'>
929 <title>Build History</title>
930
931 <para>
932 Following are changes to Build History:
933 <itemizedlist>
934 <listitem><para>
935 Installed package sizes:
936 <filename>installed-package-sizes.txt</filename> for an
937 image now records the size of the files installed by each
938 package instead of the size of each compressed package
939 archive file.</para></listitem>
940 <listitem><para>
941 The dependency graphs (<filename>depends*.dot</filename>)
942 now use the actual package names instead of replacing
943 dashes, dots and plus signs with underscores.
944 </para></listitem>
945 <listitem><para>
946 The <filename>buildhistory-diff</filename> and
947 <filename>buildhistory-collect-srcrevs</filename>
948 utilities have improved command-line handling.
949 Use the <filename>&dash;&dash;help</filename> option for
950 each utility for more information on the new syntax.
951 </para></listitem>
952 </itemizedlist>
953 For more information on Build History, see the
954 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
955 section.
956 </para>
957 </section>
958
959 <section id='migration-1.5-udev'>
960 <title><filename>udev</filename></title>
961
962 <para>
963 Following are changes to <filename>udev</filename>:
964 <itemizedlist>
965 <listitem><para>
966 <filename>udev</filename> no longer brings in
967 <filename>udev-extraconf</filename> automatically
968 through
969 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
970 since this was originally intended to be optional.
971 If you need the extra rules, then add
972 <filename>udev-extraconf</filename> to your image.
973 </para></listitem>
974 <listitem><para>
975 <filename>udev</filename> no longer brings in
976 <filename>pciutils-ids</filename> or
977 <filename>usbutils-ids</filename> through
978 <filename>RRECOMMENDS</filename>.
979 These are not needed by <filename>udev</filename> itself
980 and removing them saves around 350KB.
981 </para></listitem>
982 </itemizedlist>
983 </para>
984 </section>
985
986 <section id='removed-renamed-recipes'>
987 <title>Removed and Renamed Recipes</title>
988
989 <itemizedlist>
990 <listitem><para>
991 The <filename>linux-yocto</filename> 3.2 kernel has been
992 removed.</para></listitem>
993 <listitem><para>
994 <filename>libtool-nativesdk</filename> has been renamed to
995 <filename>nativesdk-libtool</filename>.</para></listitem>
996 <listitem><para>
997 <filename>tinylogin</filename> has been removed.
998 It has been replaced by a suid portion of Busybox.
999 See the
1000 "<link linkend='migration-1.5-busybox'>BusyBox</link>" section
1001 for more information.</para></listitem>
1002 <listitem><para>
1003 <filename>external-python-tarball</filename> has been renamed
1004 to <filename>buildtools-tarball</filename>.
1005 </para></listitem>
1006 <listitem><para>
1007 <filename>web-webkit</filename> has been removed.
1008 It has been functionally replaced by
1009 <filename>midori</filename>.</para></listitem>
1010 <listitem><para>
1011 <filename>imake</filename> has been removed.
1012 It is no longer needed by any other recipe.
1013 </para></listitem>
1014 <listitem><para>
1015 <filename>transfig-native</filename> has been removed.
1016 It is no longer needed by any other recipe.
1017 </para></listitem>
1018 <listitem><para>
1019 <filename>anjuta-remote-run</filename> has been removed.
1020 Anjuta IDE integration has not been officially supported for
1021 several releases.</para></listitem>
1022 </itemizedlist>
1023 </section>
1024
1025 <section id='migration-1.5-other-changes'>
1026 <title>Other Changes</title>
1027
1028 <para>
1029 Following is a list of short entries describing other changes:
1030 <itemizedlist>
1031 <listitem><para>
1032 <filename>run-postinsts</filename>: Make this generic.
1033 </para></listitem>
1034 <listitem><para>
1035 <filename>base-files</filename>: Remove the unnecessary
1036 <filename>media/xxx</filename> directories.
1037 </para></listitem>
1038 <listitem><para>
1039 <filename>alsa-state</filename>: Provide an empty
1040 <filename>asound.conf</filename> by default.
1041 </para></listitem>
1042 <listitem><para>
1043 <filename>classes/image</filename>: Ensure
1044 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1045 supports pre-renamed package names.</para></listitem>
1046 <listitem><para>
1047 <filename>classes/rootfs_rpm</filename>: Implement
1048 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1049 for RPM.</para></listitem>
1050 <listitem><para>
1051 <filename>systemd</filename>: Remove
1052 <filename>systemd_unitdir</filename> if
1053 <filename>systemd</filename> is not in
1054 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1055 </para></listitem>
1056 <listitem><para>
1057 <filename>systemd</filename>: Remove
1058 <filename>init.d</filename> dir if
1059 <filename>systemd</filename> unit file is present and
1060 <filename>sysvinit</filename> is not a distro feature.
1061 </para></listitem>
1062 <listitem><para>
1063 <filename>libpam</filename>: Deny all services for the
1064 <filename>OTHER</filename> entries.
1065 </para></listitem>
1066 <listitem><para>
1067 <filename>image.bbclass</filename>: Move
1068 <filename>runtime_mapping_rename</filename> to avoid
1069 conflict with <filename>multilib</filename>.
1070 See
1071 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993'><filename>YOCTO #4993</filename></ulink>
1072 in Bugzilla for more information.
1073 </para></listitem>
1074 <listitem><para>
1075 <filename>linux-dtb</filename>: Use kernel build system
1076 to generate the <filename>dtb</filename> files.
1077 </para></listitem>
1078 <listitem><para>
1079 <filename>kern-tools</filename>: Switch from guilt to
1080 new <filename>kgit-s2q</filename> tool.
1081 </para></listitem>
1082 </itemizedlist>
1083 </para>
1084 </section>
1085</section>
1086</chapter>
1087<!--
1088vim: expandtab tw=80 ts=4
1089-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-13 12:04:40 +0000