summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/migration-2.3.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/migration-2.3.rst')
-rw-r--r--documentation/ref-manual/migration-2.3.rst530
1 files changed, 530 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration-2.3.rst b/documentation/ref-manual/migration-2.3.rst
new file mode 100644
index 0000000000..7f34f0cd75
--- /dev/null
+++ b/documentation/ref-manual/migration-2.3.rst
@@ -0,0 +1,530 @@
1Moving to the Yocto Project 2.3 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.3 Release from the prior release.
6
7.. _migration-2.3-recipe-specific-sysroots:
8
9Recipe-specific Sysroots
10------------------------
11
12The OpenEmbedded build system now uses one sysroot per recipe to resolve
13long-standing issues with configuration script auto-detection of
14undeclared dependencies. Consequently, you might find that some of your
15previously written custom recipes are missing declared dependencies,
16particularly those dependencies that are incidentally built earlier in a
17typical build process and thus are already likely to be present in the
18shared sysroot in previous releases.
19
20Consider the following:
21
22- *Declare Build-Time Dependencies:* Because of this new feature, you
23 must explicitly declare all build-time dependencies for your recipe.
24 If you do not declare these dependencies, they are not populated into
25 the sysroot for the recipe.
26
27- *Specify Pre-Installation and Post-Installation Native Tool
28 Dependencies:* You must specifically specify any special native tool
29 dependencies of ``pkg_preinst`` and ``pkg_postinst`` scripts by using
30 the :term:`PACKAGE_WRITE_DEPS` variable.
31 Specifying these dependencies ensures that these tools are available
32 if these scripts need to be run on the build host during the
33 :ref:`ref-tasks-rootfs` task.
34
35 As an example, see the ``dbus`` recipe. You will see that this recipe
36 has a ``pkg_postinst`` that calls ``systemctl`` if "systemd" is in
37 :term:`DISTRO_FEATURES`. In the example,
38 ``systemd-systemctl-native`` is added to ``PACKAGE_WRITE_DEPS``,
39 which is also conditional on "systemd" being in ``DISTRO_FEATURES``.
40
41- Examine Recipes that Use ``SSTATEPOSTINSTFUNCS``: You need to
42 examine any recipe that uses ``SSTATEPOSTINSTFUNCS`` and determine
43 steps to take.
44
45 Functions added to ``SSTATEPOSTINSTFUNCS`` are still called as they
46 were in previous Yocto Project releases. However, since a separate
47 sysroot is now being populated for every recipe and if existing
48 functions being called through ``SSTATEPOSTINSTFUNCS`` are doing
49 relocation, then you will need to change these to use a
50 post-installation script that is installed by a function added to
51 :term:`SYSROOT_PREPROCESS_FUNCS`.
52
53 For an example, see the ``pixbufcache`` class in ``meta/classes/`` in
54 the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`.
55
56 .. note::
57
58 The
59 SSTATEPOSTINSTFUNCS
60 variable itself is now deprecated in favor of the
61 do_populate_sysroot[postfuncs]
62 task. Consequently, if you do still have any function or functions
63 that need to be called after the sysroot component is created for
64 a recipe, then you would be well advised to take steps to use a
65 post installation script as described previously. Taking these
66 steps prepares your code for when
67 SSTATEPOSTINSTFUNCS
68 is removed in a future Yocto Project release.
69
70- *Specify the Sysroot when Using Certain External Scripts:* Because
71 the shared sysroot is now gone, the scripts
72 ``oe-find-native-sysroot`` and ``oe-run-native`` have been changed
73 such that you need to specify which recipe's
74 :term:`STAGING_DIR_NATIVE` is used.
75
76.. note::
77
78 You can find more information on how recipe-specific sysroots work in
79 the "
80 staging.bbclass
81 " section.
82
83.. _migration-2.3-path-variable:
84
85``PATH`` Variable
86-----------------
87
88Within the environment used to run build tasks, the environment variable
89``PATH`` is now sanitized such that the normal native binary paths
90(``/bin``, ``/sbin``, ``/usr/bin`` and so forth) are removed and a
91directory containing symbolic links linking only to the binaries from
92the host mentioned in the :term:`HOSTTOOLS` and
93:term:`HOSTTOOLS_NONFATAL` variables is added
94to ``PATH``.
95
96Consequently, any native binaries provided by the host that you need to
97call needs to be in one of these two variables at the configuration
98level.
99
100Alternatively, you can add a native recipe (i.e. ``-native``) that
101provides the binary to the recipe's :term:`DEPENDS`
102value.
103
104.. note::
105
106 PATH
107 is not sanitized in the same way within
108 devshell
109 . If it were, you would have difficulty running host tools for
110 development and debugging within the shell.
111
112.. _migration-2.3-scripts:
113
114Changes to Scripts
115------------------
116
117The following changes to scripts took place:
118
119- ``oe-find-native-sysroot``: The usage for the
120 ``oe-find-native-sysroot`` script has changed to the following:
121 ::
122
123 $ . oe-find-native-sysroot recipe
124
125 You must now supply a recipe for recipe
126 as part of the command. Prior to the Yocto Project &DISTRO; release, it
127 was not necessary to provide the script with the command.
128
129- ``oe-run-native``: The usage for the ``oe-run-native`` script has
130 changed to the following:
131 ::
132
133 $ oe-run-native native_recipe tool
134
135 You must
136 supply the name of the native recipe and the tool you want to run as
137 part of the command. Prior to the Yocto Project DISTRO release, it
138 was not necessary to provide the native recipe with the command.
139
140- ``cleanup-workdir``: The ``cleanup-workdir`` script has been
141 removed because the script was found to be deleting files it should
142 not have, which lead to broken build trees. Rather than trying to
143 delete portions of :term:`TMPDIR` and getting it wrong,
144 it is recommended that you delete ``TMPDIR`` and have it restored
145 from shared state (sstate) on subsequent builds.
146
147- ``wipe-sysroot``: The ``wipe-sysroot`` script has been removed as
148 it is no longer needed with recipe-specific sysroots.
149
150.. _migration-2.3-functions:
151
152Changes to Functions
153--------------------
154
155The previously deprecated ``bb.data.getVar()``, ``bb.data.setVar()``,
156and related functions have been removed in favor of ``d.getVar()``,
157``d.setVar()``, and so forth.
158
159You need to fix any references to these old functions.
160
161.. _migration-2.3-bitbake-changes:
162
163BitBake Changes
164---------------
165
166The following changes took place for BitBake:
167
168- *BitBake's Graphical Dependency Explorer UI Replaced:* BitBake's
169 graphical dependency explorer UI ``depexp`` was replaced by
170 ``taskexp`` ("Task Explorer"), which provides a graphical way of
171 exploring the ``task-depends.dot`` file. The data presented by Task
172 Explorer is much more accurate than the data that was presented by
173 ``depexp``. Being able to visualize the data is an often requested
174 feature as standard ``*.dot`` file viewers cannot usual cope with the
175 size of the ``task-depends.dot`` file.
176
177- *BitBake "-g" Output Changes:* The ``package-depends.dot`` and
178 ``pn-depends.dot`` files as previously generated using the
179 ``bitbake -g`` command have been removed. A ``recipe-depends.dot``
180 file is now generated as a collapsed version of ``task-depends.dot``
181 instead.
182
183 The reason for this change is because ``package-depends.dot`` and
184 ``pn-depends.dot`` largely date back to a time before task-based
185 execution and do not take into account task-level dependencies
186 between recipes, which could be misleading.
187
188- *Mirror Variable Splitting Changes:* Mirror variables including
189 :term:`MIRRORS`, :term:`PREMIRRORS`,
190 and :term:`SSTATE_MIRRORS` can now separate
191 values entirely with spaces. Consequently, you no longer need "\\n".
192 BitBake looks for pairs of values, which simplifies usage. There
193 should be no change required to existing mirror variable values
194 themselves.
195
196- *The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an
197 "rsh" Parameter:* The SVN fetcher now takes an "ssh" parameter
198 instead of an "rsh" parameter. This new optional parameter is used
199 when the "protocol" parameter is set to "svn+ssh". You can only use
200 the new parameter to specify the ``ssh`` program used by SVN. The SVN
201 fetcher passes the new parameter through the ``SVN_SSH`` environment
202 variable during the :ref:`ref-tasks-fetch` task.
203
204 See the ":ref:`bitbake:svn-fetcher`"
205 section in the BitBake
206 User Manual for additional information.
207
208- ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2``
209 Removed: Because the mechanism they were part of is no longer
210 necessary with recipe-specific sysroots, the
211 ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2``
212 variables have been removed.
213
214.. _migration-2.3-absolute-symlinks:
215
216Absolute Symbolic Links
217-----------------------
218
219Absolute symbolic links (symlinks) within staged files are no longer
220permitted and now trigger an error. Any explicit creation of symlinks
221can use the ``lnr`` script, which is a replacement for ``ln -r``.
222
223If the build scripts in the software that the recipe is building are
224creating a number of absolute symlinks that need to be corrected, you
225can inherit ``relative_symlinks`` within the recipe to turn those
226absolute symlinks into relative symlinks.
227
228.. _migration-2.3-gplv2-and-gplv3-moves:
229
230GPLv2 Versions of GPLv3 Recipes Moved
231-------------------------------------
232
233Older GPLv2 versions of GPLv3 recipes have moved to a separate
234``meta-gplv2`` layer.
235
236If you use :term:`INCOMPATIBLE_LICENSE` to
237exclude GPLv3 or set :term:`PREFERRED_VERSION`
238to substitute a GPLv2 version of a GPLv3 recipe, then you must add the
239``meta-gplv2`` layer to your configuration.
240
241.. note::
242
243 You can find
244 meta-gplv2
245 layer in the OpenEmbedded layer index at
246 .
247
248These relocated GPLv2 recipes do not receive the same level of
249maintenance as other core recipes. The recipes do not get security fixes
250and upstream no longer maintains them. In fact, the upstream community
251is actively hostile towards people that use the old versions of the
252recipes. Moving these recipes into a separate layer both makes the
253different needs of the recipes clearer and clearly identifies the number
254of these recipes.
255
256.. note::
257
258 The long-term solution might be to move to BSD-licensed replacements
259 of the GPLv3 components for those that need to exclude GPLv3-licensed
260 components from the target system. This solution will be investigated
261 for future Yocto Project releases.
262
263.. _migration-2.3-package-management-changes:
264
265Package Management Changes
266--------------------------
267
268The following package management changes took place:
269
270- Smart package manager is replaced by DNF package manager. Smart has
271 become unmaintained upstream, is not ported to Python 3.x.
272 Consequently, Smart needed to be replaced. DNF is the only feasible
273 candidate.
274
275 The change in functionality is that the on-target runtime package
276 management from remote package feeds is now done with a different
277 tool that has a different set of command-line options. If you have
278 scripts that call the tool directly, or use its API, they need to be
279 fixed.
280
281 For more information, see the `DNF
282 Documentation <http://dnf.readthedocs.io/en/latest/>`__.
283
284- Rpm 5.x is replaced with Rpm 4.x. This is done for two major reasons:
285
286 - DNF is API-incompatible with Rpm 5.x and porting it and
287 maintaining the port is non-trivial.
288
289 - Rpm 5.x itself has limited maintenance upstream, and the Yocto
290 Project is one of the very few remaining users.
291
292- Berkeley DB 6.x is removed and Berkeley DB 5.x becomes the default:
293
294 - Version 6.x of Berkeley DB has largely been rejected by the open
295 source community due to its AGPLv3 license. As a result, most
296 mainstream open source projects that require DB are still
297 developed and tested with DB 5.x.
298
299 - In OE-core, the only thing that was requiring DB 6.x was Rpm 5.x.
300 Thus, no reason exists to continue carrying DB 6.x in OE-core.
301
302- ``createrepo`` is replaced with ``createrepo_c``.
303
304 ``createrepo_c`` is the current incarnation of the tool that
305 generates remote repository metadata. It is written in C as compared
306 to ``createrepo``, which is written in Python. ``createrepo_c`` is
307 faster and is maintained.
308
309- Architecture-independent RPM packages are "noarch" instead of "all".
310
311 This change was made because too many places in DNF/RPM4 stack
312 already make that assumption. Only the filenames and the architecture
313 tag has changed. Nothing else has changed in OE-core system,
314 particularly in the :ref:`allarch.bbclass <ref-classes-allarch>`
315 class.
316
317- Signing of remote package feeds using ``PACKAGE_FEED_SIGN`` is not
318 currently supported. This issue will be fully addressed in a future
319 Yocto Project release. See `defect
320 11209 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209>`__
321 for more information on a solution to package feed signing with RPM
322 in the Yocto Project 2.3 release.
323
324- OPKG now uses the libsolv backend for resolving package dependencies
325 by default. This is vastly superior to OPKG's internal ad-hoc solver
326 that was previously used. This change does have a small impact on
327 disk (around 500 KB) and memory footprint.
328
329 .. note::
330
331 For further details on this change, see the
332 commit message
333 .
334
335.. _migration-2.3-removed-recipes:
336
337Removed Recipes
338---------------
339
340The following recipes have been removed:
341
342- ``linux-yocto 4.8``: Version 4.8 has been removed. Versions 4.1
343 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 are now present.
344
345- ``python-smartpm``: Functionally replaced by ``dnf``.
346
347- ``createrepo``: Replaced by the ``createrepo-c`` recipe.
348
349- ``rpmresolve``: No longer needed with the move to RPM 4 as RPM
350 itself is used instead.
351
352- ``gstreamer``: Removed the GStreamer Git version recipes as they
353 have been stale. ``1.10.``\ x recipes are still present.
354
355- ``alsa-conf-base``: Merged into ``alsa-conf`` since ``libasound``
356 depended on both. Essentially, no way existed to install only one of
357 these.
358
359- ``tremor``: Moved to ``meta-multimedia``. Fixed-integer Vorbis
360 decoding is not needed by current hardware. Thus, GStreamer's ivorbis
361 plugin has been disabled by default eliminating the need for the
362 ``tremor`` recipe in :term:`OpenEmbedded-Core (OE-Core)`.
363
364- ``gummiboot``: Replaced by ``systemd-boot``.
365
366.. _migration-2.3-wic-changes:
367
368Wic Changes
369-----------
370
371The following changes have been made to Wic:
372
373.. note::
374
375 For more information on Wic, see the "
376 Creating Partitioned Images Using Wic
377 " section in the Yocto Project Development Tasks Manual.
378
379- *Default Output Directory Changed:* Wic's default output directory is
380 now the current directory by default instead of the unusual
381 ``/var/tmp/wic``.
382
383 The "-o" and "--outdir" options remain unchanged and are used to
384 specify your preferred output directory if you do not want to use the
385 default directory.
386
387- *fsimage Plug-in Removed:* The Wic fsimage plugin has been removed as
388 it duplicates functionality of the rawcopy plugin.
389
390.. _migration-2.3-qa-changes:
391
392QA Changes
393----------
394
395The following QA checks have changed:
396
397- ``unsafe-references-in-binaries``: The
398 ``unsafe-references-in-binaries`` QA check, which was disabled by
399 default, has now been removed. This check was intended to detect
400 binaries in ``/bin`` that link to libraries in ``/usr/lib`` and have
401 the case where the user has ``/usr`` on a separate filesystem to
402 ``/``.
403
404 The removed QA check was buggy. Additionally, ``/usr`` residing on a
405 separate partition from ``/`` is now a rare configuration.
406 Consequently, ``unsafe-references-in-binaries`` was removed.
407
408- ``file-rdeps``: The ``file-rdeps`` QA check is now an error by
409 default instead of a warning. Because it is an error instead of a
410 warning, you need to address missing runtime dependencies.
411
412 For additional information, see the
413 :ref:`insane <ref-classes-insane>` class and the "`Errors and
414 Warnings <#qa-errors-and-warnings>`__" section.
415
416.. _migration-2.3-miscellaneous-changes:
417
418Miscellaneous Changes
419---------------------
420
421The following miscellaneous changes have occurred:
422
423- In this release, a number of recipes have been changed to ignore the
424 ``largefile`` :term:`DISTRO_FEATURES` item,
425 enabling large file support unconditionally. This feature has always
426 been enabled by default. Disabling the feature has not been widely
427 tested.
428
429 .. note::
430
431 Future releases of the Yocto Project will remove entirely the
432 ability to disable the
433 largefile
434 feature, which would make it unconditionally enabled everywhere.
435
436- If the :term:`DISTRO_VERSION` value contains
437 the value of the :term:`DATE` variable, which is the
438 default between Poky releases, the ``DATE`` value is explicitly
439 excluded from ``/etc/issue`` and ``/etc/issue.net``, which is
440 displayed at the login prompt, in order to avoid conflicts with
441 Multilib enabled. Regardless, the ``DATE`` value is inaccurate if the
442 ``base-files`` recipe is restored from shared state (sstate) rather
443 than rebuilt.
444
445 If you need the build date recorded in ``/etc/issue*`` or anywhere
446 else in your image, a better method is to define a post-processing
447 function to do it and have the function called from
448 :term:`ROOTFS_POSTPROCESS_COMMAND`.
449 Doing so ensures the value is always up-to-date with the created
450 image.
451
452- Dropbear's ``init`` script now disables DSA host keys by default.
453 This change is in line with the systemd service file, which supports
454 RSA keys only, and with recent versions of OpenSSH, which deprecates
455 DSA host keys.
456
457- The :ref:`buildhistory <ref-classes-buildhistory>` class now
458 correctly uses tabs as separators between all columns in
459 ``installed-package-sizes.txt`` in order to aid import into other
460 tools.
461
462- The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig"
463 ``DISTRO_FEATURES`` feature. Distributions that previously set:
464 ::
465
466 USE_LDCONFIG = "0"
467
468 should now instead use the following:
469
470 ::
471
472 DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig"
473
474- The default value of
475 :term:`COPYLEFT_LICENSE_INCLUDE` now
476 includes all versions of AGPL licenses in addition to GPL and LGPL.
477
478 .. note::
479
480 The default list is not intended to be guaranteed as a complete
481 safe list. You should seek legal advice based on what you are
482 distributing if you are unsure.
483
484- Kernel module packages are now suffixed with the kernel version in
485 order to allow module packages from multiple kernel versions to
486 co-exist on a target system. If you wish to return to the previous
487 naming scheme that does not include the version suffix, use the
488 following:
489 ::
490
491 KERNEL_MODULE_PACKAGE_SUFFIX to ""
492
493- Removal of ``libtool`` ``*.la`` files is now enabled by default. The
494 ``*.la`` files are not actually needed on Linux and relocating them
495 is an unnecessary burden.
496
497 If you need to preserve these ``.la`` files (e.g. in a custom
498 distribution), you must change
499 :term:`INHERIT_DISTRO` such that
500 "remove-libtool" is not included in the value.
501
502- Extensible SDKs built for GCC 5+ now refuse to install on a
503 distribution where the host GCC version is 4.8 or 4.9. This change
504 resulted from the fact that the installation is known to fail due to
505 the way the ``uninative`` shared state (sstate) package is built. See
506 the :ref:`uninative <ref-classes-uninative>` class for additional
507 information.
508
509- All native and nativesdk recipes now use a separate
510 ``DISTRO_FEATURES`` value instead of sharing the value used by
511 recipes for the target, in order to avoid unnecessary rebuilds.
512
513 The ``DISTRO_FEATURES`` for ``native`` recipes is
514 :term:`DISTRO_FEATURES_NATIVE` added to
515 an intersection of ``DISTRO_FEATURES`` and
516 :term:`DISTRO_FEATURES_FILTER_NATIVE`.
517
518 For nativesdk recipes, the corresponding variables are
519 :term:`DISTRO_FEATURES_NATIVESDK`
520 and
521 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`.
522
523- The ``FILESDIR`` variable, which was previously deprecated and rarely
524 used, has now been removed. You should change any recipes that set
525 ``FILESDIR`` to set :term:`FILESPATH` instead.
526
527- The ``MULTIMACH_HOST_SYS`` variable has been removed as it is no
528 longer needed with recipe-specific sysroots.
529
530