summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/ref-manual/migration.xml417
1 files changed, 417 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 09f5f33de7..2998fbe437 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -5227,6 +5227,423 @@ id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>.
5227 </para> 5227 </para>
5228 </section> 5228 </section>
5229</section> 5229</section>
5230
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 ocurred:
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 gtk</filename>package and bindings are
5254 split into 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>ARMv7-A Legacy Support:</emphasis>
5278 Legacy support is removed for transitioning from ARMv7-A
5279 to armv7a-vfp-neon in package feeds, which was previously
5280 enabled by setting
5281 <filename>PKGARCHCOMPAT_ARMV7A</filename>.
5282 This transition occurred in 2011 and active package feeds
5283 should by now be updated to the new naming.
5284 </para></listitem>
5285 </itemizedlist>
5286 </para>
5287 </section>
5288
5289 <section id='migration-2.5-removed-recipes'>
5290 <title>Removed Recipes</title>
5291
5292 <para>
5293 The following recipes have been removed:
5294 <itemizedlist>
5295 <listitem><para>
5296 <emphasis><filename>gcc</filename>:</emphasis>
5297 The version 6.4 recipes are replaced by 7.x.
5298 </para></listitem>
5299 <listitem><para>
5300 <emphasis><filename>gst-player</filename>:</emphasis>
5301 Renamed to <filename>gst-examples</filename> as per
5302 upstream.
5303 </para></listitem>
5304 <listitem><para>
5305 <emphasis><filename>hostap-utils</filename>:</emphasis>
5306 This recipe is obsolete.
5307 </para></listitem>
5308 <listitem><para>
5309 <emphasis><filename>latencytop</filename>:</emphasis>
5310 This recipe is no longer maintained upstream.
5311 The last release was in 2009.
5312 </para></listitem>
5313 <listitem><para>
5314 <emphasis><filename>libpfm4</filename>:</emphasis>
5315 The only file that requires this recipe is
5316 <filename>oprofile</filename>, which has been removed.
5317 </para></listitem>
5318 <listitem><para>
5319 <emphasis><filename>linux-yocto</filename>:</emphasis>
5320 The version 4.4, 4.9, and 4.10 recipes have been removed.
5321 Versions 4.12, 4.14, and 4.15 remain.
5322 </para></listitem>
5323 <listitem><para>
5324 <emphasis><filename>man</filename>:</emphasis>
5325 This recipe has been replaced by
5326 <filename>modern man-db</filename>
5327 </para></listitem>
5328 <listitem><para>
5329 <emphasis><filename>mkelfimage</filename>:</emphasis>
5330 This recipe has been removed in the upstream coreboot,
5331 and is no longer needed with the removal of the ELF image
5332 type.
5333 </para></listitem>
5334 <listitem><para>
5335 <emphasis><filename>nativesdk-postinst-intercept</filename>:</emphasis>
5336 This recipe is not maintained.
5337 </para></listitem>
5338 <listitem><para>
5339 <emphasis><filename>neon</filename>:</emphasis>
5340 This recipe is not maintained upstream and is not used by
5341 anything in OpenEmbedded-Core.
5342 </para></listitem>
5343 <listitem><para>
5344 <emphasis><filename>oprofile</filename>:</emphasis>
5345 The functionality of this recipe is replaced by
5346 <filename>perf</filename> since keeping ongoing
5347 compatibility on with <filename>musl</filename> is
5348 difficult.
5349 </para></listitem>
5350 <listitem><para>
5351 <emphasis><filename>pax</filename>:</emphasis>
5352 This recipe is obsolete.
5353 </para></listitem>
5354 <listitem><para>
5355 <emphasis><filename>stat</filename>:</emphasis>
5356 This recipe is not maintained upstream.
5357 <filename>coreutils</filename> provides a modern binary for
5358 the stat recipe.
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
5370
5371
5372
5373
5374
5375
5376
5377
5378
5379
5380
5381
5382
5383
5384
5385
5386
5387
5388 <section id='migration-2.5-scripts-and-tools-changes'>
5389 <title>Scripts and Tools Changes</title>
5390
5391 <para>
5392 The following are changes to scripts and tools:
5393 <itemizedlist>
5394 <listitem><para>
5395 <filename>yocto-bsp</filename>,
5396 <filename>yocto-kernel</filename>, and
5397 <filename>yocto-layer</filename>:
5398 The <filename>yocto-bsp</filename>,
5399 <filename>yocto-kernel</filename>, and
5400 <filename>yocto-layer</filename> scripts previously shipped
5401 with poky but not in OpenEmbedded-Core have been removed.
5402 These scripts are not maintained and are outdated.
5403 In many cases, they are also limited in scope.
5404 The <filename>bitbake-layers create-layer</filename> command
5405 is a direct replacement for <filename>yocto-layer</filename>.
5406 See the documentation to create a BSP or kernel recipe in
5407 the
5408 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-kernel-recipe-example'>BSP Kernel Recipe Example</ulink>"
5409 section.
5410 </para></listitem>
5411 <listitem><para>
5412 <emphasis><filename>devtool finish</filename>:</emphasis>
5413 will now exit with an error if there are uncommitted changes
5414 or a rebase/am in progress in the source repository for the
5415 recipe, as it may indicate that you have forgotten to
5416 commit some changes (and thus these would not be reflected
5417 in updates to the patches applied by the recipe).
5418 A -f/--force option is provided for situations where you
5419 know that those uncomitted changes are inconsequential and
5420 wish to proceed regardless.
5421 </para></listitem>
5422 <listitem><para>
5423 <emphasis><filename>scripts/oe-setup-rpmrepo</filename> script:</emphasis>
5424 has been removed as its functionality can be replaced by
5425 bitbake package-index.
5426 </para></listitem>
5427 <listitem><para>
5428 <emphasis><filename>scripts/test-dependencies.sh</filename> script:</emphasis>
5429 has been removed as it was largely made obsolete by the
5430 recipe-specific sysroots functionality introduced in the
5431 previous release.
5432 </para></listitem>
5433 </itemizedlist>
5434 </para>
5435 </section>
5436
5437 <section id='migration-2.5-bitbake-changes'>
5438 <title>BitBake Changes</title>
5439
5440 <para>
5441 The following are changes BitBake:
5442 <itemizedlist>
5443 <listitem><para>
5444 The --runall option has changed behaviour slightly.
5445 There are in fact two different behaviours people may want:
5446 <itemizedlist>
5447 <listitem><para>
5448 For a given target (or set of targets) look through
5449 the task graph and run task X only if its present
5450 and would have been built.
5451 </para></listitem>
5452 <listitem><para>
5453 For a given target (or set of targets) look through
5454 the task graph and run task X if any recipe in the
5455 taskgraph has such a target even if it wasn't in the
5456 original task graph.
5457 </para></listitem>
5458 </itemizedlist>
5459 The --runall option now performs (b), previously it behaved
5460 like (a). A --runonly option has been added to retain the
5461 ability to perform (a).
5462 </para></listitem>
5463 <listitem><para>
5464 Several explicit "run this task for all recipes in the
5465 dependency tree" tasks (such as fetchall, checkuriall, and
5466 the *all tasks provided by the distrodata and archiver
5467 classes) have now been removed as there is a bitbake option
5468 to do this for any arbitrary task, for example:
5469 <literallayout class='monospaced'>
5470 bitbake &lt;target&gt; -c fetchall
5471 </literallayout>
5472 should now be replaced with:
5473 <literallayout class='monospaced'>
5474 bitbake &lt;target&gt; --runall=fetch
5475 </literallayout>
5476 </para></listitem>
5477 </itemizedlist>
5478 </para>
5479 </section>
5480
5481
5482 <section id='migration-2.5-miscellaneous-changes'>
5483 <title>Miscellaneous Changes</title>
5484
5485 <para>
5486 The following are additional changes:
5487 <itemizedlist>
5488 <listitem><para>
5489 The kernel class now supports building packages for multiple
5490 kernels. If your kernel recipe/bbappend mentions packaging
5491 at all, then you are advised to replace references to kernel
5492 in package names with ${KERNEL_PACKAGE_NAME}. For example,
5493 if you disable automatic installation of the kernel image
5494 using RDEPENDS_kernel-base = "" then to avoid warnings you
5495 will now need to use
5496 RDEPENDS_${KERNEL_PACKAGE_NAME}-base = "" instead.
5497 </para></listitem>
5498 <listitem><para>
5499 The buildhistory class now commits changes to the repository
5500 by default, so setting BUILDHISTORY_COMMIT = "1" is no
5501 longer necessary. If you wish commits to be disabled, then
5502 you will now need to set BUILDHISTORY_COMMIT = "0" in your
5503 configuration.
5504 </para></listitem>
5505 <listitem><para>
5506 The beaglebone reference machine has been renamed to
5507 beaglebone-yocto. The beaglebone-yocto BSP is a reference
5508 implementation using only mainline components available in
5509 OpenEmbedded-Core and meta-yocto-bsp, whereas Texas
5510 Instruments maintain a full-featured BSP in the meta-ti
5511 layer, and the rename avoids the previous name clash that
5512 existed between the two BSPs.
5513 </para></listitem>
5514 <listitem><para>
5515 The update-alternatives class will now no longer work with
5516 SysV init scripts as such usage has been proven to be
5517 problematic.
5518 Related to this, the sysklogd recipe no longer uses
5519 update-alternatives as it is incompatible with other
5520 implementations.
5521 </para></listitem>
5522 <listitem><para>
5523 The cmake class now uses ninja instead of make by default
5524 for building in order to improve build performance. If a
5525 recipe is broken with ninja then the recipe can set
5526 OECMAKE_GENERATOR = "Unix Makefiles" to change back to make.
5527 </para></listitem>
5528 <listitem><para>
5529 python: Restructure python packaging and replace it with
5530 autopackaging
5531 </para></listitem>
5532 <listitem><para>
5533 python3: Restructure python3 packaging and replace it with
5534 autopackaging
5535 </para></listitem>
5536 <listitem><para>
5537 The previously deprecated base_* functions have now removed,
5538 in favour of their replacements in meta/lib/oe and
5539 bitbake/lib/bb.
5540 These are typically used from recipes and classes and any
5541 references to the old functions will now need to be updated.
5542 The full list along with each of their replacements:
5543 <itemizedlist>
5544 <listitem><para>
5545 base_path_join() -> oe.path.join()
5546 </para></listitem>
5547 base_path_relative() -> oe.path.relative()
5548 <listitem><para>
5549 base_path_out() -> oe.path.format_display()
5550 </para></listitem>
5551 <listitem><para>
5552 base_read_file() -> oe.utils.read_file()
5553 </para></listitem>
5554 <listitem><para>
5555 base_ifelse() -> oe.utils.ifelse()
5556 </para></listitem>
5557 <listitem><para>
5558 base_conditional() -> oe.utils.conditional()
5559 </para></listitem>
5560 <listitem><para>
5561 base_less_or_equal() -> oe.utils.less_or_equal()
5562 </para></listitem>
5563 <listitem><para>
5564 base_version_less_or_equal() -> oe.utils.version_less_or_equal()
5565 </para></listitem>
5566 <listitem><para>
5567 base_contains() -> bb.utils.contains()
5568 </para></listitem>
5569 <listitem><para>
5570 base_both_contain() -> oe.utils.both_contain()
5571 </para></listitem>
5572 <listitem><para>
5573 base_prune_suffix() -> oe.utils.prune_suffix()
5574 </para></listitem>
5575 <listitem><para>
5576 oe_filter() -> oe.utils.str_filter()
5577 </para></listitem>
5578 <listitem><para>
5579 oe_filter_out() -> oe.utils.str_filter_out()
5580 (or use the _remove operator)
5581 </para></listitem>
5582 </itemizedlist>
5583 </para></listitem>
5584 <listitem><para>
5585 Using exit 1 as a means of explicitly deferring a
5586 postinstall script until first boot is now deprecated, as
5587 it is not an obvious mechanism and can mask actual errors.
5588 If you want to explicitly defer a postinstall to first boot
5589 on the target rather than possibly at rootfs creation time,
5590 use pkg_postinst_ontarget() or alternatively call
5591 postinst-intercepts defer_to_first_boot from pkg_postinst().
5592 Any failure of a pkg_postinst() script (including exit 1)
5593 will now trigger a warning during do_rootfs.
5594 </para></listitem>
5595 <listitem><para>
5596 The elf image type has been removed, as the mkelfimage tool
5597 that was required to create it is no longer provided by
5598 coreboot upstream, and required updating every time binutils
5599 got updated.
5600 </para></listitem>
5601 <listitem><para>
5602 Support for .iso image compression (previously enabled via
5603 COMPRESSISO = "1") has been removed, since the userspace
5604 tools (zisofs-tools) are unmaintained and squashfs provides
5605 better performance and compression.
5606 In order to build a live image with squashfs+lz4 compression
5607 enabled you would set LIVE_ROOTFS_TYPE = "squashfs-lz4"
5608 and ensure that live is in IMAGE_FSTYPES.
5609 </para></listitem>
5610 <listitem><para>
5611 Recipes having an unconditional dependency on libpam will
5612 now only be buildable with pam in DISTRO_FEATURES.
5613 If the dependency is truly optional then it is recommended
5614 that the dependency be made conditional upon pam being in
5615 DISTRO_FEATURES.
5616 </para></listitem>
5617 <listitem><para>
5618 For EFI-based machines, the bootloader (grub-efi by default)
5619 is now installed into the image at /boot. wic can be used to
5620 split this into separate boot and rootfs partitions if
5621 desired.
5622 </para></listitem>
5623 <listitem><para>
5624 Patches whose context does not match exactly (i.e. where
5625 patch reports "fuzz" when applying) will now generate a
5626 warning.
5627 See http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57
5628 </para></listitem>
5629 <listitem><para>
5630 Layers are now expected to set LAYERSERIES_COMPAT_layername
5631 to match the version(s) of OpenEmbedded-Core they are
5632 compatible with (specified as codenames using spaces to
5633 separate multiple values, e.g. "rocko sumo").
5634 If a layer does not set this, a warning will be shown.
5635 If a layer sets a value that does not include the current
5636 version, then an error will be produced.
5637 </para></listitem>
5638 <listitem><para>
5639 The TZ environment variable is now set to "UTC" within the
5640 build environment in order to fix reproducibility problems
5641 in some recipes.
5642 </para></listitem>
5643 </itemizedlist>
5644 </para>
5645 </section>
5646</section>
5230</chapter> 5647</chapter>
5231<!-- 5648<!--
5232vim: expandtab tw=80 ts=4 5649vim: expandtab tw=80 ts=4