summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/migration-2.5.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/migration-2.5.rst')
-rw-r--r--documentation/ref-manual/migration-2.5.rst310
1 files changed, 310 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration-2.5.rst b/documentation/ref-manual/migration-2.5.rst
new file mode 100644
index 0000000000..a2adc17757
--- /dev/null
+++ b/documentation/ref-manual/migration-2.5.rst
@@ -0,0 +1,310 @@
1Moving to the Yocto Project 2.5 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.5 Release from the prior release.
6
7.. _migration-2.5-packaging-changes:
8
9Packaging Changes
10-----------------
11
12This section provides information about packaging changes that have
13occurred:
14
15- ``bind-libs``: The libraries packaged by the bind recipe are in a
16 separate ``bind-libs`` package.
17
18- ``libfm-gtk``: The ``libfm`` GTK+ bindings are split into a
19 separate ``libfm-gtk`` package.
20
21- ``flex-libfl``: The flex recipe splits out libfl into a separate
22 ``flex-libfl`` package to avoid too many dependencies being pulled in
23 where only the library is needed.
24
25- ``grub-efi``: The ``grub-efi`` configuration is split into a
26 separate ``grub-bootconf`` recipe. However, the dependency
27 relationship from ``grub-efi`` is through a virtual/grub-bootconf
28 provider making it possible to have your own recipe provide the
29 dependency. Alternatively, you can use a BitBake append file to bring
30 the configuration back into the ``grub-efi`` recipe.
31
32- *armv7a Legacy Package Feed Support:* Legacy support is removed for
33 transitioning from ``armv7a`` to ``armv7a-vfp-neon`` in package
34 feeds, which was previously enabled by setting
35 ``PKGARCHCOMPAT_ARMV7A``. This transition occurred in 2011 and active
36 package feeds should by now be updated to the new naming.
37
38.. _migration-2.5-removed-recipes:
39
40Removed Recipes
41---------------
42
43The following recipes have been removed:
44
45- ``gcc``: The version 6.4 recipes are replaced by 7.x.
46
47- ``gst-player``: Renamed to ``gst-examples`` as per upstream.
48
49- ``hostap-utils``: This software package is obsolete.
50
51- ``latencytop``: This recipe is no longer maintained upstream. The
52 last release was in 2009.
53
54- ``libpfm4``: The only file that requires this recipe is
55 ``oprofile``, which has been removed.
56
57- ``linux-yocto``: The version 4.4, 4.9, and 4.10 recipes have been
58 removed. Versions 4.12, 4.14, and 4.15 remain.
59
60- ``man``: This recipe has been replaced by modern ``man-db``
61
62- ``mkelfimage``: This tool has been removed in the upstream coreboot
63 project, and is no longer needed with the removal of the ELF image
64 type.
65
66- ``nativesdk-postinst-intercept``: This recipe is not maintained.
67
68- ``neon``: This software package is no longer maintained upstream
69 and is no longer needed by anything in OpenEmbedded-Core.
70
71- ``oprofile``: The functionality of this recipe is replaced by
72 ``perf`` and keeping compatibility on an ongoing basis with ``musl``
73 is difficult.
74
75- ``pax``: This software package is obsolete.
76
77- ``stat``: This software package is not maintained upstream.
78 ``coreutils`` provides a modern stat binary.
79
80- ``zisofs-tools-native``: This recipe is no longer needed because
81 the compressed ISO image feature has been removed.
82
83.. _migration-2.5-scripts-and-tools-changes:
84
85Scripts and Tools Changes
86-------------------------
87
88The following are changes to scripts and tools:
89
90- ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer``: The
91 ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer`` scripts
92 previously shipped with poky but not in OpenEmbedded-Core have been
93 removed. These scripts are not maintained and are outdated. In many
94 cases, they are also limited in scope. The
95 ``bitbake-layers create-layer`` command is a direct replacement for
96 ``yocto-layer``. See the documentation to create a BSP or kernel
97 recipe in the ":ref:`bsp-guide/bsp:bsp kernel recipe example`" section.
98
99- ``devtool finish``: ``devtool finish`` now exits with an error if
100 there are uncommitted changes or a rebase/am in progress in the
101 recipe's source repository. If this error occurs, there might be
102 uncommitted changes that will not be included in updates to the
103 patches applied by the recipe. A -f/--force option is provided for
104 situations that the uncommitted changes are inconsequential and you
105 want to proceed regardless.
106
107- ``scripts/oe-setup-rpmrepo`` script: The functionality of
108 ``scripts/oe-setup-rpmrepo`` is replaced by
109 ``bitbake package-index``.
110
111- ``scripts/test-dependencies.sh`` script: The script is largely made
112 obsolete by the recipe-specific sysroots functionality introduced in
113 the previous release.
114
115.. _migration-2.5-bitbake-changes:
116
117BitBake Changes
118---------------
119
120The following are BitBake changes:
121
122- The ``--runall`` option has changed. There are two different
123 behaviors people might want:
124
125 - *Behavior A:* For a given target (or set of targets) look through
126 the task graph and run task X only if it is present and will be
127 built.
128
129 - *Behavior B:* For a given target (or set of targets) look through
130 the task graph and run task X if any recipe in the taskgraph has
131 such a target, even if it is not in the original task graph.
132
133 The ``--runall`` option now performs "Behavior B". Previously
134 ``--runall`` behaved like "Behavior A". A ``--runonly`` option has
135 been added to retain the ability to perform "Behavior A".
136
137- Several explicit "run this task for all recipes in the dependency
138 tree" tasks have been removed (e.g. ``fetchall``, ``checkuriall``,
139 and the ``*all`` tasks provided by the ``distrodata`` and
140 ``archiver`` classes). There is a BitBake option to complete this for
141 any arbitrary task. For example:
142 ::
143
144 bitbake <target> -c fetchall
145
146 should now be replaced with:
147 ::
148
149 bitbake <target> --runall=fetch
150
151.. _migration-2.5-python-and-python3-changes:
152
153Python and Python 3 Changes
154---------------------------
155
156The following are auto-packaging changes to Python and Python 3:
157
158The script-managed ``python-*-manifest.inc`` files that were previously
159used to generate Python and Python 3 packages have been replaced with a
160JSON-based file that is easier to read and maintain. A new task is
161available for maintainers of the Python recipes to update the JSON file
162when upgrading to new Python versions. You can now edit the file
163directly instead of having to edit a script and run it to update the
164file.
165
166One particular change to note is that the Python recipes no longer have
167build-time provides for their packages. This assumes ``python-foo`` is
168one of the packages provided by the Python recipe. You can no longer run
169``bitbake python-foo`` or have a
170:term:`DEPENDS` on ``python-foo``,
171but doing either of the following causes the package to work as
172expected: ::
173
174 IMAGE_INSTALL_append = " python-foo"
175
176or ::
177
178 RDEPENDS_${PN} = "python-foo"
179
180The earlier build-time provides behavior was a quirk of the
181way the Python manifest file was created. For more information on this
182change please see `this
183commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`__.
184
185.. _migration-2.5-miscellaneous-changes:
186
187Miscellaneous Changes
188---------------------
189
190The following are additional changes:
191
192- The ``kernel`` class supports building packages for multiple kernels.
193 If your kernel recipe or ``.bbappend`` file mentions packaging at
194 all, you should replace references to the kernel in package names
195 with ``${KERNEL_PACKAGE_NAME}``. For example, if you disable
196 automatic installation of the kernel image using
197 ``RDEPENDS_kernel-base = ""`` you can avoid warnings using
198 ``RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""`` instead.
199
200- The ``buildhistory`` class commits changes to the repository by
201 default so you no longer need to set ``BUILDHISTORY_COMMIT = "1"``.
202 If you want to disable commits you need to set
203 ``BUILDHISTORY_COMMIT = "0"`` in your configuration.
204
205- The ``beaglebone`` reference machine has been renamed to
206 ``beaglebone-yocto``. The ``beaglebone-yocto`` BSP is a reference
207 implementation using only mainline components available in
208 OpenEmbedded-Core and ``meta-yocto-bsp``, whereas Texas Instruments
209 maintains a full-featured BSP in the ``meta-ti`` layer. This rename
210 avoids the previous name clash that existed between the two BSPs.
211
212- The ``update-alternatives`` class no longer works with SysV ``init``
213 scripts because this usage has been problematic. Also, the
214 ``sysklogd`` recipe no longer uses ``update-alternatives`` because it
215 is incompatible with other implementations.
216
217- By default, the :ref:`cmake <ref-classes-cmake>` class uses
218 ``ninja`` instead of ``make`` for building. This improves build
219 performance. If a recipe is broken with ``ninja``, then the recipe
220 can set ``OECMAKE_GENERATOR = "Unix Makefiles"`` to change back to
221 ``make``.
222
223- The previously deprecated ``base_*`` functions have been removed in
224 favor of their replacements in ``meta/lib/oe`` and
225 ``bitbake/lib/bb``. These are typically used from recipes and
226 classes. Any references to the old functions must be updated. The
227 following table shows the removed functions and their replacements:
228
229 +------------------------------+----------------------------------------------------------+
230 | *Removed* | *Replacement* |
231 +==============================+==========================================================+
232 | base_path_join() | oe.path.join() |
233 +------------------------------+----------------------------------------------------------+
234 | base_path_relative() | oe.path.relative() |
235 +------------------------------+----------------------------------------------------------+
236 | base_path_out() | oe.path.format_display() |
237 +------------------------------+----------------------------------------------------------+
238 | base_read_file() | oe.utils.read_file() |
239 +------------------------------+----------------------------------------------------------+
240 | base_ifelse() | oe.utils.ifelse() |
241 +------------------------------+----------------------------------------------------------+
242 | base_conditional() | oe.utils.conditional() |
243 +------------------------------+----------------------------------------------------------+
244 | base_less_or_equal() | oe.utils.less_or_equal() |
245 +------------------------------+----------------------------------------------------------+
246 | base_version_less_or_equal() | oe.utils.version_less_or_equal() |
247 +------------------------------+----------------------------------------------------------+
248 | base_contains() | bb.utils.contains() |
249 +------------------------------+----------------------------------------------------------+
250 | base_both_contain() | oe.utils.both_contain() |
251 +------------------------------+----------------------------------------------------------+
252 | base_prune_suffix() | oe.utils.prune_suffix() |
253 +------------------------------+----------------------------------------------------------+
254 | oe_filter() | oe.utils.str_filter() |
255 +------------------------------+----------------------------------------------------------+
256 | oe_filter_out() | oe.utils.str_filter_out() (or use the \_remove operator) |
257 +------------------------------+----------------------------------------------------------+
258
259- Using ``exit 1`` to explicitly defer a postinstall script until first
260 boot is now deprecated since it is not an obvious mechanism and can
261 mask actual errors. If you want to explicitly defer a postinstall to
262 first boot on the target rather than at ``rootfs`` creation time, use
263 ``pkg_postinst_ontarget()`` or call
264 ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``.
265 Any failure of a ``pkg_postinst()`` script (including ``exit 1``)
266 will trigger a warning during ``do_rootfs``.
267
268 For more information, see the
269 ":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`"
270 section in the Yocto Project Development Tasks Manual.
271
272- The ``elf`` image type has been removed. This image type was removed
273 because the ``mkelfimage`` tool that was required to create it is no
274 longer provided by coreboot upstream and required updating every time
275 ``binutils`` updated.
276
277- Support for .iso image compression (previously enabled through
278 ``COMPRESSISO = "1"``) has been removed. The userspace tools
279 (``zisofs-tools``) are unmaintained and ``squashfs`` provides better
280 performance and compression. In order to build a live image with
281 squashfs+lz4 compression enabled you should now set
282 ``LIVE_ROOTFS_TYPE = "squashfs-lz4"`` and ensure that ``live`` is in
283 ``IMAGE_FSTYPES``.
284
285- Recipes with an unconditional dependency on ``libpam`` are only
286 buildable with ``pam`` in ``DISTRO_FEATURES``. If the dependency is
287 truly optional then it is recommended that the dependency be
288 conditional upon ``pam`` being in ``DISTRO_FEATURES``.
289
290- For EFI-based machines, the bootloader (``grub-efi`` by default) is
291 installed into the image at /boot. Wic can be used to split the
292 bootloader into separate boot and rootfs partitions if necessary.
293
294- Patches whose context does not match exactly (i.e. where patch
295 reports "fuzz" when applying) will generate a warning. For an example
296 of this see `this
297 commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57>`__.
298
299- Layers are expected to set ``LAYERSERIES_COMPAT_layername`` to match
300 the version(s) of OpenEmbedded-Core they are compatible with. This is
301 specified as codenames using spaces to separate multiple values (e.g.
302 "rocko sumo"). If a layer does not set
303 ``LAYERSERIES_COMPAT_layername``, a warning will is shown. If a layer
304 sets a value that does not include the current version ("sumo" for
305 the 2.5 release), then an error will be produced.
306
307- The ``TZ`` environment variable is set to "UTC" within the build
308 environment in order to fix reproducibility problems in some recipes.
309
310