blob: ed155d0df905f5263e3e4438269ebe7b31126de4 [file] [log] [blame]
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001Moving to the Yocto Project 1.6 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 1.6 Release from the prior release.
6
7.. _migration-1.6-archiver-class:
8
9``archiver`` Class
10------------------
11
12The :ref:`archiver <ref-classes-archiver>` class has been rewritten
13and its configuration has been simplified. For more details on the
14source archiver, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060015":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050016section in the Yocto Project Development Tasks Manual.
17
18.. _migration-1.6-packaging-changes:
19
20Packaging Changes
21-----------------
22
23The following packaging changes have been made:
24
25- The ``binutils`` recipe no longer produces a ``binutils-symlinks``
26 package. ``update-alternatives`` is now used to handle the preferred
27 ``binutils`` variant on the target instead.
28
29- The tc (traffic control) utilities have been split out of the main
30 ``iproute2`` package and put into the ``iproute2-tc`` package.
31
32- The ``gtk-engines`` schemas have been moved to a dedicated
33 ``gtk-engines-schemas`` package.
34
35- The ``armv7a`` with thumb package architecture suffix has changed.
36 The suffix for these packages with the thumb optimization enabled is
37 "t2" as it should be. Use of this suffix was not the case in the 1.5
38 release. Architecture names will change within package feeds as a
39 result.
40
41.. _migration-1.6-bitbake:
42
43BitBake
44-------
45
46The following changes have been made to :term:`BitBake`.
47
48.. _migration-1.6-matching-branch-requirement-for-git-fetching:
49
50Matching Branch Requirement for Git Fetching
51~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52
53When fetching source from a Git repository using
54:term:`SRC_URI`, BitBake will now validate the
55:term:`SRCREV` value against the branch. You can specify
Andrew Geissler4c19ea12020-10-27 13:52:24 -050056the branch using the following form:
57::
58
59 SRC_URI = "git://server.name/repository;branch=branchname"
60
61If you do not specify a branch, BitBake looks in the default "master" branch.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050062
63Alternatively, if you need to bypass this check (e.g. if you are
64fetching a revision corresponding to a tag that is not on any branch),
65you can add ";nobranch=1" to the end of the URL within ``SRC_URI``.
66
67.. _migration-1.6-bitbake-deps:
68
69Python Definition substitutions
70~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71
72BitBake had some previously deprecated Python definitions within its
73``bb`` module removed. You should use their sub-module counterparts
74instead:
75
76- ``bb.MalformedUrl``: Use ``bb.fetch.MalformedUrl``.
77
78- ``bb.encodeurl``: Use ``bb.fetch.encodeurl``.
79
80- ``bb.decodeurl``: Use ``bb.fetch.decodeurl``
81
82- ``bb.mkdirhier``: Use ``bb.utils.mkdirhier``.
83
84- ``bb.movefile``: Use ``bb.utils.movefile``.
85
86- ``bb.copyfile``: Use ``bb.utils.copyfile``.
87
88- ``bb.which``: Use ``bb.utils.which``.
89
90- ``bb.vercmp_string``: Use ``bb.utils.vercmp_string``.
91
92- ``bb.vercmp``: Use ``bb.utils.vercmp``.
93
94.. _migration-1.6-bitbake-fetcher:
95
96SVK Fetcher
97~~~~~~~~~~~
98
99The SVK fetcher has been removed from BitBake.
100
101.. _migration-1.6-bitbake-console-output:
102
103Console Output Error Redirection
104~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105
106The BitBake console UI will now output errors to ``stderr`` instead of
107``stdout``. Consequently, if you are piping or redirecting the output of
108``bitbake`` to somewhere else, and you wish to retain the errors, you
109will need to add ``2>&1`` (or something similar) to the end of your
110``bitbake`` command line.
111
112.. _migration-1.6-task-taskname-overrides:
113
114``task-``\ taskname Overrides
115~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
116
117``task-``\ taskname overrides have been adjusted so that tasks whose
118names contain underscores have the underscores replaced by hyphens for
119the override so that they now function properly. For example, the task
120override for :ref:`ref-tasks-populate_sdk` is
121``task-populate-sdk``.
122
123.. _migration-1.6-variable-changes:
124
125Changes to Variables
126--------------------
127
128The following variables have changed. For information on the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600129OpenEmbedded build system variables, see the ":doc:`/ref-manual/variables`" Chapter.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500130
131.. _migration-1.6-variable-changes-TMPDIR:
132
133``TMPDIR``
134~~~~~~~~~~
135
136:term:`TMPDIR` can no longer be on an NFS mount. NFS does
137not offer full POSIX locking and inode consistency and can cause
138unexpected issues if used to store ``TMPDIR``.
139
140The check for this occurs on startup. If ``TMPDIR`` is detected on an
141NFS mount, an error occurs.
142
143.. _migration-1.6-variable-changes-PRINC:
144
145``PRINC``
146~~~~~~~~~
147
148The ``PRINC`` variable has been deprecated and triggers a warning if
149detected during a build. For :term:`PR` increments on changes,
150use the PR service instead. You can find out more about this service in
Andrew Geissler09209ee2020-12-13 08:44:15 -0600151the ":ref:`dev-manual/common-tasks:working with a pr service`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500152section in the Yocto Project Development Tasks Manual.
153
154.. _migration-1.6-variable-changes-IMAGE_TYPES:
155
156``IMAGE_TYPES``
157~~~~~~~~~~~~~~~
158
159The "sum.jffs2" option for :term:`IMAGE_TYPES` has
160been replaced by the "jffs2.sum" option, which fits the processing
161order.
162
163.. _migration-1.6-variable-changes-COPY_LIC_MANIFEST:
164
165``COPY_LIC_MANIFEST``
166~~~~~~~~~~~~~~~~~~~~~
167
168The :term:`COPY_LIC_MANIFEST` variable must now
169be set to "1" rather than any value in order to enable it.
170
171.. _migration-1.6-variable-changes-COPY_LIC_DIRS:
172
173``COPY_LIC_DIRS``
174~~~~~~~~~~~~~~~~~
175
176The :term:`COPY_LIC_DIRS` variable must now be set
177to "1" rather than any value in order to enable it.
178
179.. _migration-1.6-variable-changes-PACKAGE_GROUP:
180
181``PACKAGE_GROUP``
182~~~~~~~~~~~~~~~~~
183
184The ``PACKAGE_GROUP`` variable has been renamed to
185:term:`FEATURE_PACKAGES` to more accurately
186reflect its purpose. You can still use ``PACKAGE_GROUP`` but the
187OpenEmbedded build system produces a warning message when it encounters
188the variable.
189
190.. _migration-1.6-variable-changes-variable-entry-behavior:
191
192Preprocess and Post Process Command Variable Behavior
193~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
194
195The following variables now expect a semicolon separated list of
196functions to call and not arbitrary shell commands:
197
198 - :term:`ROOTFS_PREPROCESS_COMMAND`
199 - :term:`ROOTFS_POSTPROCESS_COMMAND`
200 - :term:`SDK_POSTPROCESS_COMMAND`
201 - :term:`POPULATE_SDK_POST_TARGET_COMMAND`
202 - :term:`POPULATE_SDK_POST_HOST_COMMAND`
203 - :term:`IMAGE_POSTPROCESS_COMMAND`
204 - :term:`IMAGE_PREPROCESS_COMMAND`
205 - :term:`ROOTFS_POSTUNINSTALL_COMMAND`
206 - :term:`ROOTFS_POSTINSTALL_COMMAND`
207
208For
209migration purposes, you can simply wrap shell commands in a shell
210function and then call the function. Here is an example: ::
211
212 my_postprocess_function() {
213 echo "hello" > ${IMAGE_ROOTFS}/hello.txt
214 }
215 ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "
216
217.. _migration-1.6-package-test-ptest:
218
219Package Test (ptest)
220--------------------
221
222Package Tests (ptest) are built but not installed by default. For
223information on using Package Tests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600224":ref:`dev-manual/common-tasks:testing packages with ptest`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500225section in the Yocto Project Development Tasks Manual. For information on the
226``ptest`` class, see the ":ref:`ptest.bbclass <ref-classes-ptest>`"
227section.
228
229.. _migration-1.6-build-changes:
230
231Build Changes
232-------------
233
234Separate build and source directories have been enabled by default for
235selected recipes where it is known to work (a whitelist) and for all
236recipes that inherit the :ref:`cmake <ref-classes-cmake>` class. In
237future releases the :ref:`autotools <ref-classes-autotools>` class
238will enable a separate build directory by default as well. Recipes
239building Autotools-based software that fails to build with a separate
240build directory should be changed to inherit from the
241:ref:`autotools-brokensep <ref-classes-autotools>` class instead of
242the ``autotools`` or ``autotools_stage``\ classes.
243
244.. _migration-1.6-building-qemu-native:
245
246``qemu-native``
247---------------
248
249``qemu-native`` now builds without SDL-based graphical output support by
250default. The following additional lines are needed in your
251``local.conf`` to enable it:
252::
253
254 PACKAGECONFIG_pn-qemu-native = "sdl"
255 ASSUME_PROVIDED += "libsdl-native"
256
257.. note::
258
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500259 The default ``local.conf`` contains these statements. Consequently, if you
260 are building a headless system and using a default ``local.conf``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500261 file, you will need comment these two lines out.
262
263.. _migration-1.6-core-image-basic:
264
265``core-image-basic``
266--------------------
267
268``core-image-basic`` has been renamed to ``core-image-full-cmdline``.
269
270In addition to ``core-image-basic`` being renamed,
271``packagegroup-core-basic`` has been renamed to
272``packagegroup-core-full-cmdline`` to match.
273
274.. _migration-1.6-licensing:
275
276Licensing
277---------
278
279The top-level ``LICENSE`` file has been changed to better describe the
280license of the various components of :term:`OpenEmbedded-Core (OE-Core)`. However,
281the licensing itself remains unchanged.
282
283Normally, this change would not cause any side-effects. However, some
284recipes point to this file within
285:term:`LIC_FILES_CHKSUM` (as
286``${COREBASE}/LICENSE``) and thus the accompanying checksum must be
287changed from 3f40d7994397109285ec7b81fdeb3b58 to
2884d92cd373abda3937c2bc47fbc49d690. A better alternative is to have
289``LIC_FILES_CHKSUM`` point to a file describing the license that is
290distributed with the source that the recipe is building, if possible,
291rather than pointing to ``${COREBASE}/LICENSE``.
292
293.. _migration-1.6-cflags-options:
294
295``CFLAGS`` Options
296------------------
297
298The "-fpermissive" option has been removed from the default
299:term:`CFLAGS` value. You need to take action on
300individual recipes that fail when building with this option. You need to
301either patch the recipes to fix the issues reported by the compiler, or
302you need to add "-fpermissive" to ``CFLAGS`` in the recipes.
303
304.. _migration-1.6-custom-images:
305
306Custom Image Output Types
307-------------------------
308
309Custom image output types, as selected using
310:term:`IMAGE_FSTYPES`, must declare their
311dependencies on other image types (if any) using a new
312:term:`IMAGE_TYPEDEP` variable.
313
314.. _migration-1.6-do-package-write-task:
315
316Tasks
317-----
318
319The ``do_package_write`` task has been removed. The task is no longer
320needed.
321
322.. _migration-1.6-update-alternatives-provider:
323
324``update-alternative`` Provider
325-------------------------------
326
327The default ``update-alternatives`` provider has been changed from
328``opkg`` to ``opkg-utils``. This change resolves some troublesome
329circular dependencies. The runtime package has also been renamed from
330``update-alternatives-cworth`` to ``update-alternatives-opkg``.
331
332.. _migration-1.6-virtclass-overrides:
333
334``virtclass`` Overrides
335-----------------------
336
337The ``virtclass`` overrides are now deprecated. Use the equivalent class
338overrides instead (e.g. ``virtclass-native`` becomes ``class-native``.)
339
340.. _migration-1.6-removed-renamed-recipes:
341
342Removed and Renamed Recipes
343---------------------------
344
345The following recipes have been removed:
346
347- ``packagegroup-toolset-native`` - This recipe is largely unused.
348
349- ``linux-yocto-3.8`` - Support for the Linux yocto 3.8 kernel has been
350 dropped. Support for the 3.10 and 3.14 kernels have been added with
351 the ``linux-yocto-3.10`` and ``linux-yocto-3.14`` recipes.
352
353- ``ocf-linux`` - This recipe has been functionally replaced using
354 ``cryptodev-linux``.
355
356- ``genext2fs`` - ``genext2fs`` is no longer used by the build system
357 and is unmaintained upstream.
358
359- ``js`` - This provided an ancient version of Mozilla's javascript
360 engine that is no longer needed.
361
362- ``zaurusd`` - The recipe has been moved to the ``meta-handheld``
363 layer.
364
365- ``eglibc 2.17`` - Replaced by the ``eglibc 2.19`` recipe.
366
367- ``gcc 4.7.2`` - Replaced by the now stable ``gcc 4.8.2``.
368
369- ``external-sourcery-toolchain`` - this recipe is now maintained in
370 the ``meta-sourcery`` layer.
371
372- ``linux-libc-headers-yocto 3.4+git`` - Now using version 3.10 of the
373 ``linux-libc-headers`` by default.
374
375- ``meta-toolchain-gmae`` - This recipe is obsolete.
376
377- ``packagegroup-core-sdk-gmae`` - This recipe is obsolete.
378
379- ``packagegroup-core-standalone-gmae-sdk-target`` - This recipe is
380 obsolete.
381
382.. _migration-1.6-removed-classes:
383
384Removed Classes
385---------------
386
387The following classes have become obsolete and have been removed:
388
389- ``module_strip``
390
391- ``pkg_metainfo``
392
393- ``pkg_distribute``
394
395- ``image-empty``
396
397.. _migration-1.6-reference-bsps:
398
399Reference Board Support Packages (BSPs)
400---------------------------------------
401
402The following reference BSPs changes occurred:
403
404- The BeagleBoard (``beagleboard``) ARM reference hardware has been
405 replaced by the BeagleBone (``beaglebone``) hardware.
406
407- The RouterStation Pro (``routerstationpro``) MIPS reference hardware
408 has been replaced by the EdgeRouter Lite (``edgerouter``) hardware.
409
410The previous reference BSPs for the ``beagleboard`` and
411``routerstationpro`` machines are still available in a new
412``meta-yocto-bsp-old`` layer in the
413:yocto_git:`Source Repositories <>` at
Andrew Geissler09209ee2020-12-13 08:44:15 -0600414:yocto_git:`/meta-yocto-bsp-old/`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500415
416