summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/ref-manual/migration-1.3.rst195
-rw-r--r--documentation/ref-manual/migration-1.4.rst237
-rw-r--r--documentation/ref-manual/migration-1.5.rst355
-rw-r--r--documentation/ref-manual/migration-1.6.rst417
-rw-r--r--documentation/ref-manual/migration-1.7.rst225
-rw-r--r--documentation/ref-manual/migration-1.8.rst183
-rw-r--r--documentation/ref-manual/migration-2.0.rst281
-rw-r--r--documentation/ref-manual/migration-2.1.rst434
-rw-r--r--documentation/ref-manual/migration-2.2.rst451
-rw-r--r--documentation/ref-manual/migration-2.3.rst530
-rw-r--r--documentation/ref-manual/migration-2.4.rst327
-rw-r--r--documentation/ref-manual/migration-2.5.rst310
-rw-r--r--documentation/ref-manual/migration-2.6.rst476
-rw-r--r--documentation/ref-manual/migration-2.7.rst180
-rw-r--r--documentation/ref-manual/migration-3.0.rst321
-rw-r--r--documentation/ref-manual/migration-3.1.rst276
-rw-r--r--documentation/ref-manual/migration-general.rst54
-rw-r--r--documentation/ref-manual/migration.rst5253
18 files changed, 5271 insertions, 5234 deletions
diff --git a/documentation/ref-manual/migration-1.3.rst b/documentation/ref-manual/migration-1.3.rst
new file mode 100644
index 0000000000..ebbc238873
--- /dev/null
+++ b/documentation/ref-manual/migration-1.3.rst
@@ -0,0 +1,195 @@
1.. SPDX-License-Identifier: CC-BY-2.0-UK
2
3Moving to the Yocto Project 1.3 Release
4=======================================
5
6This section provides migration information for moving to the Yocto
7Project 1.3 Release from the prior release.
8
9.. _1.3-local-configuration:
10
11Local Configuration
12-------------------
13
14Differences include changes for
15:term:`SSTATE_MIRRORS` and ``bblayers.conf``.
16
17.. _migration-1.3-sstate-mirrors:
18
19SSTATE_MIRRORS
20~~~~~~~~~~~~~~
21
22The shared state cache (sstate-cache), as pointed to by
23:term:`SSTATE_DIR`, by default now has two-character
24subdirectories to prevent issues arising from too many files in the same
25directory. Also, native sstate-cache packages, which are built to run on
26the host system, will go into a subdirectory named using the distro ID
27string. If you copy the newly structured sstate-cache to a mirror
28location (either local or remote) and then point to it in
29:term:`SSTATE_MIRRORS`, you need to append "PATH"
30to the end of the mirror URL so that the path used by BitBake before the
31mirror substitution is appended to the path used to access the mirror.
32Here is an example: ::
33
34 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
35
36.. _migration-1.3-bblayers-conf:
37
38bblayers.conf
39~~~~~~~~~~~~~
40
41The ``meta-yocto`` layer consists of two parts that correspond to the
42Poky reference distribution and the reference hardware Board Support
43Packages (BSPs), respectively: ``meta-yocto`` and ``meta-yocto-bsp``.
44When running BitBake for the first time after upgrading, your
45``conf/bblayers.conf`` file will be updated to handle this change and
46you will be asked to re-run or restart for the changes to take effect.
47
48.. _1.3-recipes:
49
50Recipes
51-------
52
53Differences include changes for the following:
54
55.. _migration-1.3-python-function-whitespace:
56
57Python Function Whitespace
58~~~~~~~~~~~~~~~~~~~~~~~~~~
59
60All Python functions must now use four spaces for indentation.
61Previously, an inconsistent mix of spaces and tabs existed, which made
62extending these functions using ``_append`` or ``_prepend`` complicated
63given that Python treats whitespace as syntactically significant. If you
64are defining or extending any Python functions (e.g.
65``populate_packages``, ``do_unpack``, ``do_patch`` and so forth) in
66custom recipes or classes, you need to ensure you are using consistent
67four-space indentation.
68
69.. _migration-1.3-proto=-in-src-uri:
70
71proto= in SRC_URI
72~~~~~~~~~~~~~~~~~
73
74Any use of ``proto=`` in :term:`SRC_URI` needs to be
75changed to ``protocol=``. In particular, this applies to the following
76URIs:
77
78- ``svn://``
79
80- ``bzr://``
81
82- ``hg://``
83
84- ``osc://``
85
86Other URIs were already using ``protocol=``. This change improves
87consistency.
88
89.. _migration-1.3-nativesdk:
90
91nativesdk
92~~~~~~~~~
93
94The suffix ``nativesdk`` is now implemented as a prefix, which
95simplifies a lot of the packaging code for ``nativesdk`` recipes. All
96custom ``nativesdk`` recipes, which are relocatable packages that are
97native to :term:`SDK_ARCH`, and any references need to
98be updated to use ``nativesdk-*`` instead of ``*-nativesdk``.
99
100.. _migration-1.3-task-recipes:
101
102Task Recipes
103~~~~~~~~~~~~
104
105"Task" recipes are now known as "Package groups" and have been renamed
106from ``task-*.bb`` to ``packagegroup-*.bb``. Existing references to the
107previous ``task-*`` names should work in most cases as there is an
108automatic upgrade path for most packages. However, you should update
109references in your own recipes and configurations as they could be
110removed in future releases. You should also rename any custom ``task-*``
111recipes to ``packagegroup-*``, and change them to inherit
112``packagegroup`` instead of ``task``, as well as taking the opportunity
113to remove anything now handled by ``packagegroup.bbclass``, such as
114providing ``-dev`` and ``-dbg`` packages, setting
115:term:`LIC_FILES_CHKSUM`, and so forth. See the
116":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section for
117further details.
118
119.. _migration-1.3-image-features:
120
121IMAGE_FEATURES
122~~~~~~~~~~~~~~
123
124Image recipes that previously included "apps-console-core" in
125:term:`IMAGE_FEATURES` should now include "splash"
126instead to enable the boot-up splash screen. Retaining
127"apps-console-core" will still include the splash screen but generates a
128warning. The "apps-x11-core" and "apps-x11-games" ``IMAGE_FEATURES``
129features have been removed.
130
131.. _migration-1.3-removed-recipes:
132
133Removed Recipes
134~~~~~~~~~~~~~~~
135
136The following recipes have been removed. For most of them, it is
137unlikely that you would have any references to them in your own
138:term:`Metadata`. However, you should check your metadata
139against this list to be sure:
140
141- ``libx11-trim``: Replaced by ``libx11``, which has a negligible
142 size difference with modern Xorg.
143
144- ``xserver-xorg-lite``: Use ``xserver-xorg``, which has a negligible
145 size difference when DRI and GLX modules are not installed.
146
147- ``xserver-kdrive``: Effectively unmaintained for many years.
148
149- ``mesa-xlib``: No longer serves any purpose.
150
151- ``galago``: Replaced by telepathy.
152
153- ``gail``: Functionality was integrated into GTK+ 2.13.
154
155- ``eggdbus``: No longer needed.
156
157- ``gcc-*-intermediate``: The build has been restructured to avoid
158 the need for this step.
159
160- ``libgsmd``: Unmaintained for many years. Functionality now
161 provided by ``ofono`` instead.
162
163- *contacts, dates, tasks, eds-tools*: Largely unmaintained PIM
164 application suite. It has been moved to ``meta-gnome`` in
165 ``meta-openembedded``.
166
167In addition to the previously listed changes, the ``meta-demoapps``
168directory has also been removed because the recipes in it were not being
169maintained and many had become obsolete or broken. Additionally, these
170recipes were not parsed in the default configuration. Many of these
171recipes are already provided in an updated and maintained form within
172the OpenEmbedded community layers such as ``meta-oe`` and
173``meta-gnome``. For the remainder, you can now find them in the
174``meta-extras`` repository, which is in the
175:yocto_git:`Source Repositories <>` at
176http://git.yoctoproject.org/cgit/cgit.cgi/meta-extras/.
177
178.. _1.3-linux-kernel-naming:
179
180Linux Kernel Naming
181-------------------
182
183The naming scheme for kernel output binaries has been changed to now
184include :term:`PE` as part of the filename:
185::
186
187 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
188
189Because the ``PE`` variable is not set by default, these binary files
190could result with names that include two dash characters. Here is an
191example: ::
192
193 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
194
195
diff --git a/documentation/ref-manual/migration-1.4.rst b/documentation/ref-manual/migration-1.4.rst
new file mode 100644
index 0000000000..a658bdff68
--- /dev/null
+++ b/documentation/ref-manual/migration-1.4.rst
@@ -0,0 +1,237 @@
1Moving to the Yocto Project 1.4 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 1.4 Release from the prior release.
6
7.. _migration-1.4-bitbake:
8
9BitBake
10-------
11
12Differences include the following:
13
14- *Comment Continuation:* If a comment ends with a line continuation
15 (\) character, then the next line must also be a comment. Any
16 instance where this is not the case, now triggers a warning. You must
17 either remove the continuation character, or be sure the next line is
18 a comment.
19
20- *Package Name Overrides:* The runtime package specific variables
21 :term:`RDEPENDS`,
22 :term:`RRECOMMENDS`,
23 :term:`RSUGGESTS`,
24 :term:`RPROVIDES`,
25 :term:`RCONFLICTS`,
26 :term:`RREPLACES`, :term:`FILES`,
27 :term:`ALLOW_EMPTY`, and the pre, post, install,
28 and uninstall script functions ``pkg_preinst``, ``pkg_postinst``,
29 ``pkg_prerm``, and ``pkg_postrm`` should always have a package name
30 override. For example, use ``RDEPENDS_${PN}`` for the main package
31 instead of ``RDEPENDS``. BitBake uses more strict checks when it
32 parses recipes.
33
34.. _migration-1.4-build-behavior:
35
36Build Behavior
37--------------
38
39Differences include the following:
40
41- *Shared State Code:* The shared state code has been optimized to
42 avoid running unnecessary tasks. For example, the following no longer
43 populates the target sysroot since that is not necessary:
44 ::
45
46 $ bitbake -c rootfs some-image
47
48 Instead, the system just needs to extract the
49 output package contents, re-create the packages, and construct the
50 root filesystem. This change is unlikely to cause any problems unless
51 you have missing declared dependencies.
52
53- *Scanning Directory Names:* When scanning for files in
54 :term:`SRC_URI`, the build system now uses
55 :term:`FILESOVERRIDES` instead of
56 :term:`OVERRIDES` for the directory names. In
57 general, the values previously in ``OVERRIDES`` are now in
58 ``FILESOVERRIDES`` as well. However, if you relied upon an additional
59 value you previously added to ``OVERRIDES``, you might now need to
60 add it to ``FILESOVERRIDES`` unless you are already adding it through
61 the :term:`MACHINEOVERRIDES` or
62 :term:`DISTROOVERRIDES` variables, as
63 appropriate. For more related changes, see the
64 "`Variables <#migration-1.4-variables>`__" section.
65
66.. _migration-1.4-proxies-and-fetching-source:
67
68Proxies and Fetching Source
69---------------------------
70
71A new ``oe-git-proxy`` script has been added to replace previous methods
72of handling proxies and fetching source from Git. See the
73``meta-yocto/conf/site.conf.sample`` file for information on how to use
74this script.
75
76.. _migration-1.4-custom-interfaces-file-netbase-change:
77
78Custom Interfaces File (netbase change)
79---------------------------------------
80
81If you have created your own custom ``etc/network/interfaces`` file by
82creating an append file for the ``netbase`` recipe, you now need to
83create an append file for the ``init-ifupdown`` recipe instead, which
84you can find in the :term:`Source Directory` at
85``meta/recipes-core/init-ifupdown``. For information on how to use
86append files, see the
87":ref:`dev-manual/dev-manual-common-tasks:using .bbappend files in your layer`"
88section in the Yocto Project Development Tasks Manual.
89
90.. _migration-1.4-remote-debugging:
91
92Remote Debugging
93----------------
94
95Support for remote debugging with the Eclipse IDE is now separated into
96an image feature (``eclipse-debug``) that corresponds to the
97``packagegroup-core-eclipse-debug`` package group. Previously, the
98debugging feature was included through the ``tools-debug`` image
99feature, which corresponds to the ``packagegroup-core-tools-debug``
100package group.
101
102.. _migration-1.4-variables:
103
104Variables
105---------
106
107The following variables have changed:
108
109- ``SANITY_TESTED_DISTROS``: This variable now uses a distribution
110 ID, which is composed of the host distributor ID followed by the
111 release. Previously,
112 :term:`SANITY_TESTED_DISTROS` was
113 composed of the description field. For example, "Ubuntu 12.10"
114 becomes "Ubuntu-12.10". You do not need to worry about this change if
115 you are not specifically setting this variable, or if you are
116 specifically setting it to "".
117
118- ``SRC_URI``: The ``${``\ :term:`PN`\ ``}``,
119 ``${``\ :term:`PF`\ ``}``,
120 ``${``\ :term:`P`\ ``}``, and ``FILE_DIRNAME`` directories
121 have been dropped from the default value of the
122 :term:`FILESPATH` variable, which is used as the
123 search path for finding files referred to in
124 :term:`SRC_URI`. If you have a recipe that relied upon
125 these directories, which would be unusual, then you will need to add
126 the appropriate paths within the recipe or, alternatively, rearrange
127 the files. The most common locations are still covered by ``${BP}``,
128 ``${BPN}``, and "files", which all remain in the default value of
129 :term:`FILESPATH`.
130
131.. _migration-target-package-management-with-rpm:
132
133Target Package Management with RPM
134----------------------------------
135
136If runtime package management is enabled and the RPM backend is
137selected, Smart is now installed for package download, dependency
138resolution, and upgrades instead of Zypper. For more information on how
139to use Smart, run the following command on the target:
140::
141
142 smart --help
143
144.. _migration-1.4-recipes-moved:
145
146Recipes Moved
147-------------
148
149The following recipes were moved from their previous locations because
150they are no longer used by anything in the OpenEmbedded-Core:
151
152- ``clutter-box2d``: Now resides in the ``meta-oe`` layer.
153
154- ``evolution-data-server``: Now resides in the ``meta-gnome`` layer.
155
156- ``gthumb``: Now resides in the ``meta-gnome`` layer.
157
158- ``gtkhtml2``: Now resides in the ``meta-oe`` layer.
159
160- ``gupnp``: Now resides in the ``meta-multimedia`` layer.
161
162- ``gypsy``: Now resides in the ``meta-oe`` layer.
163
164- ``libcanberra``: Now resides in the ``meta-gnome`` layer.
165
166- ``libgdata``: Now resides in the ``meta-gnome`` layer.
167
168- ``libmusicbrainz``: Now resides in the ``meta-multimedia`` layer.
169
170- ``metacity``: Now resides in the ``meta-gnome`` layer.
171
172- ``polkit``: Now resides in the ``meta-oe`` layer.
173
174- ``zeroconf``: Now resides in the ``meta-networking`` layer.
175
176.. _migration-1.4-removals-and-renames:
177
178Removals and Renames
179--------------------
180
181The following list shows what has been removed or renamed:
182
183- ``evieext``: Removed because it has been removed from ``xserver``
184 since 2008.
185
186- *Gtk+ DirectFB:* Removed support because upstream Gtk+ no longer
187 supports it as of version 2.18.
188
189- ``libxfontcache / xfontcacheproto``: Removed because they were
190 removed from the Xorg server in 2008.
191
192- ``libxp / libxprintapputil / libxprintutil / printproto``: Removed
193 because the XPrint server was removed from Xorg in 2008.
194
195- ``libxtrap / xtrapproto``: Removed because their functionality was
196 broken upstream.
197
198- *linux-yocto 3.0 kernel:* Removed with linux-yocto 3.8 kernel being
199 added. The linux-yocto 3.2 and linux-yocto 3.4 kernels remain as part
200 of the release.
201
202- ``lsbsetup``: Removed with functionality now provided by
203 ``lsbtest``.
204
205- ``matchbox-stroke``: Removed because it was never more than a
206 proof-of-concept.
207
208- ``matchbox-wm-2 / matchbox-theme-sato-2``: Removed because they are
209 not maintained. However, ``matchbox-wm`` and ``matchbox-theme-sato``
210 are still provided.
211
212- ``mesa-dri``: Renamed to ``mesa``.
213
214- ``mesa-xlib``: Removed because it was no longer useful.
215
216- ``mutter``: Removed because nothing ever uses it and the recipe is
217 very old.
218
219- ``orinoco-conf``: Removed because it has become obsolete.
220
221- ``update-modules``: Removed because it is no longer used. The
222 kernel module ``postinstall`` and ``postrm`` scripts can now do the
223 same task without the use of this script.
224
225- ``web``: Removed because it is not maintained. Superseded by
226 ``web-webkit``.
227
228- ``xf86bigfontproto``: Removed because upstream it has been disabled
229 by default since 2007. Nothing uses ``xf86bigfontproto``.
230
231- ``xf86rushproto``: Removed because its dependency in ``xserver``
232 was spurious and it was removed in 2005.
233
234- ``zypper / libzypp / sat-solver``: Removed and been functionally
235 replaced with Smart (``python-smartpm``) when RPM packaging is used
236 and package management is enabled on the target.
237
diff --git a/documentation/ref-manual/migration-1.5.rst b/documentation/ref-manual/migration-1.5.rst
new file mode 100644
index 0000000000..ce55199df3
--- /dev/null
+++ b/documentation/ref-manual/migration-1.5.rst
@@ -0,0 +1,355 @@
1Moving to the Yocto Project 1.5 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 1.5 Release from the prior release.
6
7.. _migration-1.5-host-dependency-changes:
8
9Host Dependency Changes
10-----------------------
11
12The OpenEmbedded build system now has some additional requirements on
13the host system:
14
15- Python 2.7.3+
16
17- Tar 1.24+
18
19- Git 1.7.8+
20
21- Patched version of Make if you are using 3.82. Most distributions
22 that provide Make 3.82 use the patched version.
23
24If the Linux distribution you are using on your build host does not
25provide packages for these, you can install and use the Buildtools
26tarball, which provides an SDK-like environment containing them.
27
28For more information on this requirement, see the "`Required Git, tar,
29Python and gcc Versions <#required-git-tar-python-and-gcc-versions>`__"
30section.
31
32.. _migration-1.5-atom-pc-bsp:
33
34``atom-pc`` Board Support Package (BSP)
35---------------------------------------
36
37The ``atom-pc`` hardware reference BSP has been replaced by a
38``genericx86`` BSP. This BSP is not necessarily guaranteed to work on
39all x86 hardware, but it will run on a wider range of systems than the
40``atom-pc`` did.
41
42.. note::
43
44 Additionally, a
45 genericx86-64
46 BSP has been added for 64-bit Atom systems.
47
48.. _migration-1.5-bitbake:
49
50BitBake
51-------
52
53The following changes have been made that relate to BitBake:
54
55- BitBake now supports a ``_remove`` operator. The addition of this
56 operator means you will have to rename any items in recipe space
57 (functions, variables) whose names currently contain ``_remove_`` or
58 end with ``_remove`` to avoid unexpected behavior.
59
60- BitBake's global method pool has been removed. This method is not
61 particularly useful and led to clashes between recipes containing
62 functions that had the same name.
63
64- The "none" server backend has been removed. The "process" server
65 backend has been serving well as the default for a long time now.
66
67- The ``bitbake-runtask`` script has been removed.
68
69- ``${``\ :term:`P`\ ``}`` and
70 ``${``\ :term:`PF`\ ``}`` are no longer added to
71 :term:`PROVIDES` by default in ``bitbake.conf``.
72 These version-specific ``PROVIDES`` items were seldom used.
73 Attempting to use them could result in two versions being built
74 simultaneously rather than just one version due to the way BitBake
75 resolves dependencies.
76
77.. _migration-1.5-qa-warnings:
78
79QA Warnings
80-----------
81
82The following changes have been made to the package QA checks:
83
84- If you have customized :term:`ERROR_QA` or
85 :term:`WARN_QA` values in your configuration, check
86 that they contain all of the issues that you wish to be reported.
87 Previous Yocto Project versions contained a bug that meant that any
88 item not mentioned in ``ERROR_QA`` or ``WARN_QA`` would be treated as
89 a warning. Consequently, several important items were not already in
90 the default value of ``WARN_QA``. All of the possible QA checks are
91 now documented in the ":ref:`insane.bbclass <ref-classes-insane>`"
92 section.
93
94- An additional QA check has been added to check if
95 ``/usr/share/info/dir`` is being installed. Your recipe should delete
96 this file within :ref:`ref-tasks-install` if "make
97 install" is installing it.
98
99- If you are using the buildhistory class, the check for the package
100 version going backwards is now controlled using a standard QA check.
101 Thus, if you have customized your ``ERROR_QA`` or ``WARN_QA`` values
102 and still wish to have this check performed, you should add
103 "version-going-backwards" to your value for one or the other
104 variables depending on how you wish it to be handled. See the
105 documented QA checks in the
106 ":ref:`insane.bbclass <ref-classes-insane>`" section.
107
108.. _migration-1.5-directory-layout-changes:
109
110Directory Layout Changes
111------------------------
112
113The following directory changes exist:
114
115- Output SDK installer files are now named to include the image name
116 and tuning architecture through the :term:`SDK_NAME`
117 variable.
118
119- Images and related files are now installed into a directory that is
120 specific to the machine, instead of a parent directory containing
121 output files for multiple machines. The
122 :term:`DEPLOY_DIR_IMAGE` variable continues
123 to point to the directory containing images for the current
124 :term:`MACHINE` and should be used anywhere there is a
125 need to refer to this directory. The ``runqemu`` script now uses this
126 variable to find images and kernel binaries and will use BitBake to
127 determine the directory. Alternatively, you can set the
128 ``DEPLOY_DIR_IMAGE`` variable in the external environment.
129
130- When buildhistory is enabled, its output is now written under the
131 :term:`Build Directory` rather than
132 :term:`TMPDIR`. Doing so makes it easier to delete
133 ``TMPDIR`` and preserve the build history. Additionally, data for
134 produced SDKs is now split by :term:`IMAGE_NAME`.
135
136- The ``pkgdata`` directory produced as part of the packaging process
137 has been collapsed into a single machine-specific directory. This
138 directory is located under ``sysroots`` and uses a machine-specific
139 name (i.e. ``tmp/sysroots/machine/pkgdata``).
140
141.. _migration-1.5-shortened-git-srcrev-values:
142
143Shortened Git ``SRCREV`` Values
144-------------------------------
145
146BitBake will now shorten revisions from Git repositories from the normal
14740 characters down to 10 characters within :term:`SRCPV`
148for improved usability in path and file names. This change should be
149safe within contexts where these revisions are used because the chances
150of spatially close collisions is very low. Distant collisions are not a
151major issue in the way the values are used.
152
153.. _migration-1.5-image-features:
154
155``IMAGE_FEATURES``
156------------------
157
158The following changes have been made that relate to
159:term:`IMAGE_FEATURES`:
160
161- The value of ``IMAGE_FEATURES`` is now validated to ensure invalid
162 feature items are not added. Some users mistakenly add package names
163 to this variable instead of using
164 :term:`IMAGE_INSTALL` in order to have the
165 package added to the image, which does not work. This change is
166 intended to catch those kinds of situations. Valid ``IMAGE_FEATURES``
167 are drawn from ``PACKAGE_GROUP`` definitions,
168 :term:`COMPLEMENTARY_GLOB` and a new
169 "validitems" varflag on ``IMAGE_FEATURES``. The "validitems" varflag
170 change allows additional features to be added if they are not
171 provided using the previous two mechanisms.
172
173- The previously deprecated "apps-console-core" ``IMAGE_FEATURES`` item
174 is no longer supported. Add "splash" to ``IMAGE_FEATURES`` if you
175 wish to have the splash screen enabled, since this is all that
176 apps-console-core was doing.
177
178.. _migration-1.5-run:
179
180``/run``
181--------
182
183The ``/run`` directory from the Filesystem Hierarchy Standard 3.0 has
184been introduced. You can find some of the implications for this change
185`here <http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873>`__.
186The change also means that recipes that install files to ``/var/run``
187must be changed. You can find a guide on how to make these changes
188`here <http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530>`__.
189
190.. _migration-1.5-removal-of-package-manager-database-within-image-recipes:
191
192Removal of Package Manager Database Within Image Recipes
193--------------------------------------------------------
194
195The image ``core-image-minimal`` no longer adds
196``remove_packaging_data_files`` to
197:term:`ROOTFS_POSTPROCESS_COMMAND`.
198This addition is now handled automatically when "package-management" is
199not in :term:`IMAGE_FEATURES`. If you have custom
200image recipes that make this addition, you should remove the lines, as
201they are not needed and might interfere with correct operation of
202postinstall scripts.
203
204.. _migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time:
205
206Images Now Rebuild Only on Changes Instead of Every Time
207--------------------------------------------------------
208
209The :ref:`ref-tasks-rootfs` and other related image
210construction tasks are no longer marked as "nostamp". Consequently, they
211will only be re-executed when their inputs have changed. Previous
212versions of the OpenEmbedded build system always rebuilt the image when
213requested rather when necessary.
214
215.. _migration-1.5-task-recipes:
216
217Task Recipes
218------------
219
220The previously deprecated ``task.bbclass`` has now been dropped. For
221recipes that previously inherited from this class, you should rename
222them from ``task-*`` to ``packagegroup-*`` and inherit packagegroup
223instead.
224
225For more information, see the
226":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section.
227
228.. _migration-1.5-busybox:
229
230BusyBox
231-------
232
233By default, we now split BusyBox into two binaries: one that is suid
234root for those components that need it, and another for the rest of the
235components. Splitting BusyBox allows for optimization that eliminates
236the ``tinylogin`` recipe as recommended by upstream. You can disable
237this split by setting
238:term:`BUSYBOX_SPLIT_SUID` to "0".
239
240.. _migration-1.5-automated-image-testing:
241
242Automated Image Testing
243-----------------------
244
245A new automated image testing framework has been added through the
246:ref:`testimage.bbclass <ref-classes-testimage*>` class. This
247framework replaces the older ``imagetest-qemu`` framework.
248
249You can learn more about performing automated image tests in the
250":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
251section in the Yocto Project Development Tasks Manual.
252
253.. _migration-1.5-build-history:
254
255Build History
256-------------
257
258Following are changes to Build History:
259
260- Installed package sizes: ``installed-package-sizes.txt`` for an image
261 now records the size of the files installed by each package instead
262 of the size of each compressed package archive file.
263
264- The dependency graphs (``depends*.dot``) now use the actual package
265 names instead of replacing dashes, dots and plus signs with
266 underscores.
267
268- The ``buildhistory-diff`` and ``buildhistory-collect-srcrevs``
269 utilities have improved command-line handling. Use the ``--help``
270 option for each utility for more information on the new syntax.
271
272For more information on Build History, see the
273":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
274section in the Yocto Project Development Tasks Manual.
275
276.. _migration-1.5-udev:
277
278``udev``
279--------
280
281Following are changes to ``udev``:
282
283- ``udev`` no longer brings in ``udev-extraconf`` automatically through
284 :term:`RRECOMMENDS`, since this was originally
285 intended to be optional. If you need the extra rules, then add
286 ``udev-extraconf`` to your image.
287
288- ``udev`` no longer brings in ``pciutils-ids`` or ``usbutils-ids``
289 through ``RRECOMMENDS``. These are not needed by ``udev`` itself and
290 removing them saves around 350KB.
291
292.. _migration-1.5-removed-renamed-recipes:
293
294Removed and Renamed Recipes
295---------------------------
296
297- The ``linux-yocto`` 3.2 kernel has been removed.
298
299- ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``.
300
301- ``tinylogin`` has been removed. It has been replaced by a suid
302 portion of Busybox. See the "`BusyBox <#migration-1.5-busybox>`__"
303 section for more information.
304
305- ``external-python-tarball`` has been renamed to
306 ``buildtools-tarball``.
307
308- ``web-webkit`` has been removed. It has been functionally replaced by
309 ``midori``.
310
311- ``imake`` has been removed. It is no longer needed by any other
312 recipe.
313
314- ``transfig-native`` has been removed. It is no longer needed by any
315 other recipe.
316
317- ``anjuta-remote-run`` has been removed. Anjuta IDE integration has
318 not been officially supported for several releases.
319
320.. _migration-1.5-other-changes:
321
322Other Changes
323-------------
324
325Following is a list of short entries describing other changes:
326
327- ``run-postinsts``: Make this generic.
328
329- ``base-files``: Remove the unnecessary ``media/``\ xxx directories.
330
331- ``alsa-state``: Provide an empty ``asound.conf`` by default.
332
333- ``classes/image``: Ensure
334 :term:`BAD_RECOMMENDATIONS` supports
335 pre-renamed package names.
336
337- ``classes/rootfs_rpm``: Implement ``BAD_RECOMMENDATIONS`` for RPM.
338
339- ``systemd``: Remove ``systemd_unitdir`` if ``systemd`` is not in
340 :term:`DISTRO_FEATURES`.
341
342- ``systemd``: Remove ``init.d`` dir if ``systemd`` unit file is
343 present and ``sysvinit`` is not a distro feature.
344
345- ``libpam``: Deny all services for the ``OTHER`` entries.
346
347- ``image.bbclass``: Move ``runtime_mapping_rename`` to avoid conflict
348 with ``multilib``. See
349 `YOCTO #4993 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993>`_
350 in Bugzilla for more information.
351
352- ``linux-dtb``: Use kernel build system to generate the ``dtb`` files.
353
354- ``kern-tools``: Switch from guilt to new ``kgit-s2q`` tool.
355
diff --git a/documentation/ref-manual/migration-1.6.rst b/documentation/ref-manual/migration-1.6.rst
new file mode 100644
index 0000000000..b55be46e55
--- /dev/null
+++ b/documentation/ref-manual/migration-1.6.rst
@@ -0,0 +1,417 @@
1Moving 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
15":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
16section 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
56the branch using the following form: SRC_URI =
57"git://server.name/repository;branch=branchname" If you do not specify a
58branch, BitBake looks in the default "master" branch.
59
60Alternatively, if you need to bypass this check (e.g. if you are
61fetching a revision corresponding to a tag that is not on any branch),
62you can add ";nobranch=1" to the end of the URL within ``SRC_URI``.
63
64.. _migration-1.6-bitbake-deps:
65
66Python Definition substitutions
67~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68
69BitBake had some previously deprecated Python definitions within its
70``bb`` module removed. You should use their sub-module counterparts
71instead:
72
73- ``bb.MalformedUrl``: Use ``bb.fetch.MalformedUrl``.
74
75- ``bb.encodeurl``: Use ``bb.fetch.encodeurl``.
76
77- ``bb.decodeurl``: Use ``bb.fetch.decodeurl``
78
79- ``bb.mkdirhier``: Use ``bb.utils.mkdirhier``.
80
81- ``bb.movefile``: Use ``bb.utils.movefile``.
82
83- ``bb.copyfile``: Use ``bb.utils.copyfile``.
84
85- ``bb.which``: Use ``bb.utils.which``.
86
87- ``bb.vercmp_string``: Use ``bb.utils.vercmp_string``.
88
89- ``bb.vercmp``: Use ``bb.utils.vercmp``.
90
91.. _migration-1.6-bitbake-fetcher:
92
93SVK Fetcher
94~~~~~~~~~~~
95
96The SVK fetcher has been removed from BitBake.
97
98.. _migration-1.6-bitbake-console-output:
99
100Console Output Error Redirection
101~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102
103The BitBake console UI will now output errors to ``stderr`` instead of
104``stdout``. Consequently, if you are piping or redirecting the output of
105``bitbake`` to somewhere else, and you wish to retain the errors, you
106will need to add ``2>&1`` (or something similar) to the end of your
107``bitbake`` command line.
108
109.. _migration-1.6-task-taskname-overrides:
110
111``task-``\ taskname Overrides
112~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113
114``task-``\ taskname overrides have been adjusted so that tasks whose
115names contain underscores have the underscores replaced by hyphens for
116the override so that they now function properly. For example, the task
117override for :ref:`ref-tasks-populate_sdk` is
118``task-populate-sdk``.
119
120.. _migration-1.6-variable-changes:
121
122Changes to Variables
123--------------------
124
125The following variables have changed. For information on the
126OpenEmbedded build system variables, see the "`Variables
127Glossary <#ref-variables-glos>`__" Chapter.
128
129.. _migration-1.6-variable-changes-TMPDIR:
130
131``TMPDIR``
132~~~~~~~~~~
133
134:term:`TMPDIR` can no longer be on an NFS mount. NFS does
135not offer full POSIX locking and inode consistency and can cause
136unexpected issues if used to store ``TMPDIR``.
137
138The check for this occurs on startup. If ``TMPDIR`` is detected on an
139NFS mount, an error occurs.
140
141.. _migration-1.6-variable-changes-PRINC:
142
143``PRINC``
144~~~~~~~~~
145
146The ``PRINC`` variable has been deprecated and triggers a warning if
147detected during a build. For :term:`PR` increments on changes,
148use the PR service instead. You can find out more about this service in
149the ":ref:`dev-manual/dev-manual-common-tasks:working with a pr service`"
150section in the Yocto Project Development Tasks Manual.
151
152.. _migration-1.6-variable-changes-IMAGE_TYPES:
153
154``IMAGE_TYPES``
155~~~~~~~~~~~~~~~
156
157The "sum.jffs2" option for :term:`IMAGE_TYPES` has
158been replaced by the "jffs2.sum" option, which fits the processing
159order.
160
161.. _migration-1.6-variable-changes-COPY_LIC_MANIFEST:
162
163``COPY_LIC_MANIFEST``
164~~~~~~~~~~~~~~~~~~~~~
165
166The :term:`COPY_LIC_MANIFEST` variable must now
167be set to "1" rather than any value in order to enable it.
168
169.. _migration-1.6-variable-changes-COPY_LIC_DIRS:
170
171``COPY_LIC_DIRS``
172~~~~~~~~~~~~~~~~~
173
174The :term:`COPY_LIC_DIRS` variable must now be set
175to "1" rather than any value in order to enable it.
176
177.. _migration-1.6-variable-changes-PACKAGE_GROUP:
178
179``PACKAGE_GROUP``
180~~~~~~~~~~~~~~~~~
181
182The ``PACKAGE_GROUP`` variable has been renamed to
183:term:`FEATURE_PACKAGES` to more accurately
184reflect its purpose. You can still use ``PACKAGE_GROUP`` but the
185OpenEmbedded build system produces a warning message when it encounters
186the variable.
187
188.. _migration-1.6-variable-changes-variable-entry-behavior:
189
190Preprocess and Post Process Command Variable Behavior
191~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
192
193The following variables now expect a semicolon separated list of
194functions to call and not arbitrary shell commands:
195
196 - :term:`ROOTFS_PREPROCESS_COMMAND`
197 - :term:`ROOTFS_POSTPROCESS_COMMAND`
198 - :term:`SDK_POSTPROCESS_COMMAND`
199 - :term:`POPULATE_SDK_POST_TARGET_COMMAND`
200 - :term:`POPULATE_SDK_POST_HOST_COMMAND`
201 - :term:`IMAGE_POSTPROCESS_COMMAND`
202 - :term:`IMAGE_PREPROCESS_COMMAND`
203 - :term:`ROOTFS_POSTUNINSTALL_COMMAND`
204 - :term:`ROOTFS_POSTINSTALL_COMMAND`
205
206For
207migration purposes, you can simply wrap shell commands in a shell
208function and then call the function. Here is an example: ::
209
210 my_postprocess_function() {
211 echo "hello" > ${IMAGE_ROOTFS}/hello.txt
212 }
213 ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "
214
215.. _migration-1.6-package-test-ptest:
216
217Package Test (ptest)
218--------------------
219
220Package Tests (ptest) are built but not installed by default. For
221information on using Package Tests, see the
222":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`"
223section in the Yocto Project Development Tasks Manual. For information on the
224``ptest`` class, see the ":ref:`ptest.bbclass <ref-classes-ptest>`"
225section.
226
227.. _migration-1.6-build-changes:
228
229Build Changes
230-------------
231
232Separate build and source directories have been enabled by default for
233selected recipes where it is known to work (a whitelist) and for all
234recipes that inherit the :ref:`cmake <ref-classes-cmake>` class. In
235future releases the :ref:`autotools <ref-classes-autotools>` class
236will enable a separate build directory by default as well. Recipes
237building Autotools-based software that fails to build with a separate
238build directory should be changed to inherit from the
239:ref:`autotools-brokensep <ref-classes-autotools>` class instead of
240the ``autotools`` or ``autotools_stage``\ classes.
241
242.. _migration-1.6-building-qemu-native:
243
244``qemu-native``
245---------------
246
247``qemu-native`` now builds without SDL-based graphical output support by
248default. The following additional lines are needed in your
249``local.conf`` to enable it:
250::
251
252 PACKAGECONFIG_pn-qemu-native = "sdl"
253 ASSUME_PROVIDED += "libsdl-native"
254
255.. note::
256
257 The default
258 local.conf
259 contains these statements. Consequently, if you are building a
260 headless system and using a default
261 local.conf
262 file, you will need comment these two lines out.
263
264.. _migration-1.6-core-image-basic:
265
266``core-image-basic``
267--------------------
268
269``core-image-basic`` has been renamed to ``core-image-full-cmdline``.
270
271In addition to ``core-image-basic`` being renamed,
272``packagegroup-core-basic`` has been renamed to
273``packagegroup-core-full-cmdline`` to match.
274
275.. _migration-1.6-licensing:
276
277Licensing
278---------
279
280The top-level ``LICENSE`` file has been changed to better describe the
281license of the various components of :term:`OpenEmbedded-Core (OE-Core)`. However,
282the licensing itself remains unchanged.
283
284Normally, this change would not cause any side-effects. However, some
285recipes point to this file within
286:term:`LIC_FILES_CHKSUM` (as
287``${COREBASE}/LICENSE``) and thus the accompanying checksum must be
288changed from 3f40d7994397109285ec7b81fdeb3b58 to
2894d92cd373abda3937c2bc47fbc49d690. A better alternative is to have
290``LIC_FILES_CHKSUM`` point to a file describing the license that is
291distributed with the source that the recipe is building, if possible,
292rather than pointing to ``${COREBASE}/LICENSE``.
293
294.. _migration-1.6-cflags-options:
295
296``CFLAGS`` Options
297------------------
298
299The "-fpermissive" option has been removed from the default
300:term:`CFLAGS` value. You need to take action on
301individual recipes that fail when building with this option. You need to
302either patch the recipes to fix the issues reported by the compiler, or
303you need to add "-fpermissive" to ``CFLAGS`` in the recipes.
304
305.. _migration-1.6-custom-images:
306
307Custom Image Output Types
308-------------------------
309
310Custom image output types, as selected using
311:term:`IMAGE_FSTYPES`, must declare their
312dependencies on other image types (if any) using a new
313:term:`IMAGE_TYPEDEP` variable.
314
315.. _migration-1.6-do-package-write-task:
316
317Tasks
318-----
319
320The ``do_package_write`` task has been removed. The task is no longer
321needed.
322
323.. _migration-1.6-update-alternatives-provider:
324
325``update-alternative`` Provider
326-------------------------------
327
328The default ``update-alternatives`` provider has been changed from
329``opkg`` to ``opkg-utils``. This change resolves some troublesome
330circular dependencies. The runtime package has also been renamed from
331``update-alternatives-cworth`` to ``update-alternatives-opkg``.
332
333.. _migration-1.6-virtclass-overrides:
334
335``virtclass`` Overrides
336-----------------------
337
338The ``virtclass`` overrides are now deprecated. Use the equivalent class
339overrides instead (e.g. ``virtclass-native`` becomes ``class-native``.)
340
341.. _migration-1.6-removed-renamed-recipes:
342
343Removed and Renamed Recipes
344---------------------------
345
346The following recipes have been removed:
347
348- ``packagegroup-toolset-native`` - This recipe is largely unused.
349
350- ``linux-yocto-3.8`` - Support for the Linux yocto 3.8 kernel has been
351 dropped. Support for the 3.10 and 3.14 kernels have been added with
352 the ``linux-yocto-3.10`` and ``linux-yocto-3.14`` recipes.
353
354- ``ocf-linux`` - This recipe has been functionally replaced using
355 ``cryptodev-linux``.
356
357- ``genext2fs`` - ``genext2fs`` is no longer used by the build system
358 and is unmaintained upstream.
359
360- ``js`` - This provided an ancient version of Mozilla's javascript
361 engine that is no longer needed.
362
363- ``zaurusd`` - The recipe has been moved to the ``meta-handheld``
364 layer.
365
366- ``eglibc 2.17`` - Replaced by the ``eglibc 2.19`` recipe.
367
368- ``gcc 4.7.2`` - Replaced by the now stable ``gcc 4.8.2``.
369
370- ``external-sourcery-toolchain`` - this recipe is now maintained in
371 the ``meta-sourcery`` layer.
372
373- ``linux-libc-headers-yocto 3.4+git`` - Now using version 3.10 of the
374 ``linux-libc-headers`` by default.
375
376- ``meta-toolchain-gmae`` - This recipe is obsolete.
377
378- ``packagegroup-core-sdk-gmae`` - This recipe is obsolete.
379
380- ``packagegroup-core-standalone-gmae-sdk-target`` - This recipe is
381 obsolete.
382
383.. _migration-1.6-removed-classes:
384
385Removed Classes
386---------------
387
388The following classes have become obsolete and have been removed:
389
390- ``module_strip``
391
392- ``pkg_metainfo``
393
394- ``pkg_distribute``
395
396- ``image-empty``
397
398.. _migration-1.6-reference-bsps:
399
400Reference Board Support Packages (BSPs)
401---------------------------------------
402
403The following reference BSPs changes occurred:
404
405- The BeagleBoard (``beagleboard``) ARM reference hardware has been
406 replaced by the BeagleBone (``beaglebone``) hardware.
407
408- The RouterStation Pro (``routerstationpro``) MIPS reference hardware
409 has been replaced by the EdgeRouter Lite (``edgerouter``) hardware.
410
411The previous reference BSPs for the ``beagleboard`` and
412``routerstationpro`` machines are still available in a new
413``meta-yocto-bsp-old`` layer in the
414:yocto_git:`Source Repositories <>` at
415http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/.
416
417
diff --git a/documentation/ref-manual/migration-1.7.rst b/documentation/ref-manual/migration-1.7.rst
new file mode 100644
index 0000000000..82fd37d3a9
--- /dev/null
+++ b/documentation/ref-manual/migration-1.7.rst
@@ -0,0 +1,225 @@
1Moving to the Yocto Project 1.7 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 1.7 Release from the prior release.
6
7.. _migration-1.7-changes-to-setting-qemu-packageconfig-options:
8
9Changes to Setting QEMU ``PACKAGECONFIG`` Options in ``local.conf``
10-------------------------------------------------------------------
11
12The QEMU recipe now uses a number of
13:term:`PACKAGECONFIG` options to enable various
14optional features. The method used to set defaults for these options
15means that existing ``local.conf`` files will need to be be modified to
16append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu``
17instead of setting it. In other words, to enable graphical output for
18QEMU, you should now have these lines in ``local.conf``:
19::
20
21 PACKAGECONFIG_append_pn-qemu-native = " sdl"
22 PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
23
24.. _migration-1.7-minimum-git-version:
25
26Minimum Git version
27-------------------
28
29The minimum :ref:`overview-manual/overview-manual-development-environment:git`
30version required on the
31build host is now 1.7.8 because the ``--list`` option is now required by
32BitBake's Git fetcher. As always, if your host distribution does not
33provide a version of Git that meets this requirement, you can use the
34``buildtools-tarball`` that does. See the "`Required Git, tar, Python
35and gcc Versions <#required-git-tar-python-and-gcc-versions>`__" section
36for more information.
37
38.. _migration-1.7-autotools-class-changes:
39
40Autotools Class Changes
41-----------------------
42
43The following :ref:`autotools <ref-classes-autotools>` class changes
44occurred:
45
46- *A separate build directory is now used by default:* The
47 ``autotools`` class has been changed to use a directory for building
48 (:term:`B`), which is separate from the source directory
49 (:term:`S`). This is commonly referred to as ``B != S``, or
50 an out-of-tree build.
51
52 If the software being built is already capable of building in a
53 directory separate from the source, you do not need to do anything.
54 However, if the software is not capable of being built in this
55 manner, you will need to either patch the software so that it can
56 build separately, or you will need to change the recipe to inherit
57 the :ref:`autotools-brokensep <ref-classes-autotools>` class
58 instead of the ``autotools`` or ``autotools_stage`` classes.
59
60- The ``--foreign`` option is no longer passed to ``automake`` when
61 running ``autoconf``: This option tells ``automake`` that a
62 particular software package does not follow the GNU standards and
63 therefore should not be expected to distribute certain files such as
64 ``ChangeLog``, ``AUTHORS``, and so forth. Because the majority of
65 upstream software packages already tell ``automake`` to enable
66 foreign mode themselves, the option is mostly superfluous. However,
67 some recipes will need patches for this change. You can easily make
68 the change by patching ``configure.ac`` so that it passes "foreign"
69 to ``AM_INIT_AUTOMAKE()``. See `this
70 commit <http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2>`__
71 for an example showing how to make the patch.
72
73.. _migration-1.7-binary-configuration-scripts-disabled:
74
75Binary Configuration Scripts Disabled
76-------------------------------------
77
78Some of the core recipes that package binary configuration scripts now
79disable the scripts due to the scripts previously requiring error-prone
80path substitution. Software that links against these libraries using
81these scripts should use the much more robust ``pkg-config`` instead.
82The list of recipes changed in this version (and their configuration
83scripts) is as follows:
84::
85
86 directfb (directfb-config)
87 freetype (freetype-config)
88 gpgme (gpgme-config)
89 libassuan (libassuan-config)
90 libcroco (croco-6.0-config)
91 libgcrypt (libgcrypt-config)
92 libgpg-error (gpg-error-config)
93 libksba (ksba-config)
94 libpcap (pcap-config)
95 libpcre (pcre-config)
96 libpng (libpng-config, libpng16-config)
97 libsdl (sdl-config)
98 libusb-compat (libusb-config)
99 libxml2 (xml2-config)
100 libxslt (xslt-config)
101 ncurses (ncurses-config)
102 neon (neon-config)
103 npth (npth-config)
104 pth (pth-config)
105 taglib (taglib-config)
106
107Additionally, support for ``pkg-config`` has been added to some recipes in the
108previous list in the rare cases where the upstream software package does
109not already provide it.
110
111.. _migration-1.7-glibc-replaces-eglibc:
112
113``eglibc 2.19`` Replaced with ``glibc 2.20``
114--------------------------------------------
115
116Because ``eglibc`` and ``glibc`` were already fairly close, this
117replacement should not require any significant changes to other software
118that links to ``eglibc``. However, there were a number of minor changes
119in ``glibc 2.20`` upstream that could require patching some software
120(e.g. the removal of the ``_BSD_SOURCE`` feature test macro).
121
122``glibc 2.20`` requires version 2.6.32 or greater of the Linux kernel.
123Thus, older kernels will no longer be usable in conjunction with it.
124
125For full details on the changes in ``glibc 2.20``, see the upstream
126release notes
127`here <https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html>`__.
128
129.. _migration-1.7-kernel-module-autoloading:
130
131Kernel Module Autoloading
132-------------------------
133
134The :term:`module_autoload_* <module_autoload>` variable is now
135deprecated and a new
136:term:`KERNEL_MODULE_AUTOLOAD` variable
137should be used instead. Also, :term:`module_conf_* <module_conf>`
138must now be used in conjunction with a new
139:term:`KERNEL_MODULE_PROBECONF` variable.
140The new variables no longer require you to specify the module name as
141part of the variable name. This change not only simplifies usage but
142also allows the values of these variables to be appropriately
143incorporated into task signatures and thus trigger the appropriate tasks
144to re-execute when changed. You should replace any references to
145``module_autoload_*`` with ``KERNEL_MODULE_AUTOLOAD``, and add any
146modules for which ``module_conf_*`` is specified to
147``KERNEL_MODULE_PROBECONF``.
148
149.. _migration-1.7-qa-check-changes:
150
151QA Check Changes
152----------------
153
154The following changes have occurred to the QA check process:
155
156- Additional QA checks ``file-rdeps`` and ``build-deps`` have been
157 added in order to verify that file dependencies are satisfied (e.g.
158 package contains a script requiring ``/bin/bash``) and build-time
159 dependencies are declared, respectively. For more information, please
160 see the "`QA Error and Warning Messages <#ref-qa-checks>`__" chapter.
161
162- Package QA checks are now performed during a new
163 :ref:`ref-tasks-package_qa` task rather than being
164 part of the :ref:`ref-tasks-package` task. This allows
165 more parallel execution. This change is unlikely to be an issue
166 except for highly customized recipes that disable packaging tasks
167 themselves by marking them as ``noexec``. For those packages, you
168 will need to disable the ``do_package_qa`` task as well.
169
170- Files being overwritten during the
171 :ref:`ref-tasks-populate_sysroot` task now
172 trigger an error instead of a warning. Recipes should not be
173 overwriting files written to the sysroot by other recipes. If you
174 have these types of recipes, you need to alter them so that they do
175 not overwrite these files.
176
177 You might now receive this error after changes in configuration or
178 metadata resulting in orphaned files being left in the sysroot. If
179 you do receive this error, the way to resolve the issue is to delete
180 your :term:`TMPDIR` or to move it out of the way and
181 then re-start the build. Anything that has been fully built up to
182 that point and does not need rebuilding will be restored from the
183 shared state cache and the rest of the build will be able to proceed
184 as normal.
185
186.. _migration-1.7-removed-recipes:
187
188Removed Recipes
189---------------
190
191The following recipes have been removed:
192
193- ``x-load``: This recipe has been superseded by U-boot SPL for all
194 Cortex-based TI SoCs. For legacy boards, the ``meta-ti`` layer, which
195 contains a maintained recipe, should be used instead.
196
197- ``ubootchart``: This recipe is obsolete. A ``bootchart2`` recipe has
198 been added to functionally replace it.
199
200- ``linux-yocto 3.4``: Support for the linux-yocto 3.4 kernel has been
201 dropped. Support for the 3.10 and 3.14 kernels remains, while support
202 for version 3.17 has been added.
203
204- ``eglibc`` has been removed in favor of ``glibc``. See the
205 "```eglibc 2.19`` Replaced with
206 ``glibc 2.20`` <#migration-1.7-glibc-replaces-eglibc>`__" section for
207 more information.
208
209.. _migration-1.7-miscellaneous-changes:
210
211Miscellaneous Changes
212---------------------
213
214The following miscellaneous change occurred:
215
216- The build history feature now writes ``build-id.txt`` instead of
217 ``build-id``. Additionally, ``build-id.txt`` now contains the full
218 build header as printed by BitBake upon starting the build. You
219 should manually remove old "build-id" files from your existing build
220 history repositories to avoid confusion. For information on the build
221 history feature, see the
222 ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
223 section in the Yocto Project Development Tasks Manual.
224
225
diff --git a/documentation/ref-manual/migration-1.8.rst b/documentation/ref-manual/migration-1.8.rst
new file mode 100644
index 0000000000..d601e6b63b
--- /dev/null
+++ b/documentation/ref-manual/migration-1.8.rst
@@ -0,0 +1,183 @@
1Moving to the Yocto Project 1.8 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 1.8 Release from the prior release.
6
7.. _migration-1.8-removed-recipes:
8
9Removed Recipes
10---------------
11
12The following recipes have been removed:
13
14- ``owl-video``: Functionality replaced by ``gst-player``.
15
16- ``gaku``: Functionality replaced by ``gst-player``.
17
18- ``gnome-desktop``: This recipe is now available in ``meta-gnome`` and
19 is no longer needed.
20
21- ``gsettings-desktop-schemas``: This recipe is now available in
22 ``meta-gnome`` and is no longer needed.
23
24- ``python-argparse``: The ``argparse`` module is already provided in
25 the default Python distribution in a package named
26 ``python-argparse``. Consequently, the separate ``python-argparse``
27 recipe is no longer needed.
28
29- ``telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control``:
30 All these recipes have moved to ``meta-oe`` and are consequently no
31 longer needed by any recipes in OpenEmbedded-Core.
32
33- ``linux-yocto_3.10`` and ``linux-yocto_3.17``: Support for the
34 linux-yocto 3.10 and 3.17 kernels has been dropped. Support for the
35 3.14 kernel remains, while support for 3.19 kernel has been added.
36
37- ``poky-feed-config-opkg``: This recipe has become obsolete and is no
38 longer needed. Use ``distro-feed-config`` from ``meta-oe`` instead.
39
40- ``libav 0.8.x``: ``libav 9.x`` is now used.
41
42- ``sed-native``: No longer needed. A working version of ``sed`` is
43 expected to be provided by the host distribution.
44
45.. _migration-1.8-bluez:
46
47BlueZ 4.x / 5.x Selection
48-------------------------
49
50Proper built-in support for selecting BlueZ 5.x in preference to the
51default of 4.x now exists. To use BlueZ 5.x, simply add "bluez5" to your
52:term:`DISTRO_FEATURES` value. If you had
53previously added append files (``*.bbappend``) to make this selection,
54you can now remove them.
55
56Additionally, a ``bluetooth`` class has been added to make selection of
57the appropriate bluetooth support within a recipe a little easier. If
58you wish to make use of this class in a recipe, add something such as
59the following: ::
60
61 inherit bluetooth
62 PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}"
63 PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4"
64 PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5"
65
66.. _migration-1.8-kernel-build-changes:
67
68Kernel Build Changes
69--------------------
70
71The kernel build process was changed to place the source in a common
72shared work area and to place build artifacts separately in the source
73code tree. In theory, migration paths have been provided for most common
74usages in kernel recipes but this might not work in all cases. In
75particular, users need to ensure that ``${S}`` (source files) and
76``${B}`` (build artifacts) are used correctly in functions such as
77:ref:`ref-tasks-configure` and
78:ref:`ref-tasks-install`. For kernel recipes that do not
79inherit from ``kernel-yocto`` or include ``linux-yocto.inc``, you might
80wish to refer to the ``linux.inc`` file in the ``meta-oe`` layer for the
81kinds of changes you need to make. For reference, here is the
82`commit <http://cgit.openembedded.org/meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee>`__
83where the ``linux.inc`` file in ``meta-oe`` was updated.
84
85Recipes that rely on the kernel source code and do not inherit the
86module classes might need to add explicit dependencies on the
87``do_shared_workdir`` kernel task, for example: ::
88
89 do_configure[depends] += "virtual/kernel:do_shared_workdir"
90
91.. _migration-1.8-ssl:
92
93SSL 3.0 is Now Disabled in OpenSSL
94----------------------------------
95
96SSL 3.0 is now disabled when building OpenSSL. Disabling SSL 3.0 avoids
97any lingering instances of the POODLE vulnerability. If you feel you
98must re-enable SSL 3.0, then you can add an append file (``*.bbappend``)
99for the ``openssl`` recipe to remove "-no-ssl3" from
100:term:`EXTRA_OECONF`.
101
102.. _migration-1.8-default-sysroot-poisoning:
103
104Default Sysroot Poisoning
105-------------------------
106
107``gcc's`` default sysroot and include directories are now "poisoned". In
108other words, the sysroot and include directories are being redirected to
109a non-existent location in order to catch when host directories are
110being used due to the correct options not being passed. This poisoning
111applies both to the cross-compiler used within the build and to the
112cross-compiler produced in the SDK.
113
114If this change causes something in the build to fail, it almost
115certainly means the various compiler flags and commands are not being
116passed correctly to the underlying piece of software. In such cases, you
117need to take corrective steps.
118
119.. _migration-1.8-rebuild-improvements:
120
121Rebuild Improvements
122--------------------
123
124Changes have been made to the :ref:`base <ref-classes-base>`,
125:ref:`autotools <ref-classes-autotools>`, and
126:ref:`cmake <ref-classes-cmake>` classes to clean out generated files
127when the :ref:`ref-tasks-configure` task needs to be
128re-executed.
129
130One of the improvements is to attempt to run "make clean" during the
131``do_configure`` task if a ``Makefile`` exists. Some software packages
132do not provide a working clean target within their make files. If you
133have such recipes, you need to set
134:term:`CLEANBROKEN` to "1" within the recipe, for example: ::
135
136 CLEANBROKEN = "1"
137
138.. _migration-1.8-qa-check-and-validation-changes:
139
140QA Check and Validation Changes
141-------------------------------
142
143The following QA Check and Validation Changes have occurred:
144
145- Usage of ``PRINC`` previously triggered a warning. It now triggers an
146 error. You should remove any remaining usage of ``PRINC`` in any
147 recipe or append file.
148
149- An additional QA check has been added to detect usage of ``${D}`` in
150 :term:`FILES` values where :term:`D` values
151 should not be used at all. The same check ensures that ``$D`` is used
152 in ``pkg_preinst/pkg_postinst/pkg_prerm/pkg_postrm`` functions
153 instead of ``${D}``.
154
155- :term:`S` now needs to be set to a valid value within a
156 recipe. If ``S`` is not set in the recipe, the directory is not
157 automatically created. If ``S`` does not point to a directory that
158 exists at the time the :ref:`ref-tasks-unpack` task
159 finishes, a warning will be shown.
160
161- :term:`LICENSE` is now validated for correct
162 formatting of multiple licenses. If the format is invalid (e.g.
163 multiple licenses are specified with no operators to specify how the
164 multiple licenses interact), then a warning will be shown.
165
166.. _migration-1.8-miscellaneous-changes:
167
168Miscellaneous Changes
169---------------------
170
171The following miscellaneous changes have occurred:
172
173- The ``send-error-report`` script now expects a "-s" option to be
174 specified before the server address. This assumes a server address is
175 being specified.
176
177- The ``oe-pkgdata-util`` script now expects a "-p" option to be
178 specified before the ``pkgdata`` directory, which is now optional. If
179 the ``pkgdata`` directory is not specified, the script will run
180 BitBake to query :term:`PKGDATA_DIR` from the
181 build environment.
182
183
diff --git a/documentation/ref-manual/migration-2.0.rst b/documentation/ref-manual/migration-2.0.rst
new file mode 100644
index 0000000000..570486ba00
--- /dev/null
+++ b/documentation/ref-manual/migration-2.0.rst
@@ -0,0 +1,281 @@
1Moving to the Yocto Project 2.0 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.0 Release from the prior release.
6
7.. _migration-2.0-gcc-5:
8
9GCC 5
10-----
11
12The default compiler is now GCC 5.2. This change has required fixes for
13compilation errors in a number of other recipes.
14
15One important example is a fix for when the Linux kernel freezes at boot
16time on ARM when built with GCC 5. If you are using your own kernel
17recipe or source tree and building for ARM, you will likely need to
18apply this
19`patch <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit?id=a077224fd35b2f7fbc93f14cf67074fc792fbac2>`__.
20The standard ``linux-yocto`` kernel source tree already has a workaround
21for the same issue.
22
23For further details, see https://gcc.gnu.org/gcc-5/changes.html
24and the porting guide at
25https://gcc.gnu.org/gcc-5/porting_to.html.
26
27Alternatively, you can switch back to GCC 4.9 or 4.8 by setting
28``GCCVERSION`` in your configuration, as follows:
29::
30
31 GCCVERSION = "4.9%"
32
33.. _migration-2.0-Gstreamer-0.10-removed:
34
35Gstreamer 0.10 Removed
36----------------------
37
38Gstreamer 0.10 has been removed in favor of Gstreamer 1.x. As part of
39the change, recipes for Gstreamer 0.10 and related software are now
40located in ``meta-multimedia``. This change results in Qt4 having Phonon
41and Gstreamer support in QtWebkit disabled by default.
42
43.. _migration-2.0-removed-recipes:
44
45Removed Recipes
46---------------
47
48The following recipes have been moved or removed:
49
50- ``bluez4``: The recipe is obsolete and has been moved due to
51 ``bluez5`` becoming fully integrated. The ``bluez4`` recipe now
52 resides in ``meta-oe``.
53
54- ``gamin``: The recipe is obsolete and has been removed.
55
56- ``gnome-icon-theme``: The recipe's functionally has been replaced by
57 ``adwaita-icon-theme``.
58
59- Gstreamer 0.10 Recipes: Recipes for Gstreamer 0.10 have been removed
60 in favor of the recipes for Gstreamer 1.x.
61
62- ``insserv``: The recipe is obsolete and has been removed.
63
64- ``libunique``: The recipe is no longer used and has been moved to
65 ``meta-oe``.
66
67- ``midori``: The recipe's functionally has been replaced by
68 ``epiphany``.
69
70- ``python-gst``: The recipe is obsolete and has been removed since it
71 only contains bindings for Gstreamer 0.10.
72
73- ``qt-mobility``: The recipe is obsolete and has been removed since it
74 requires ``Gstreamer 0.10``, which has been replaced.
75
76- ``subversion``: All 1.6.x versions of this recipe have been removed.
77
78- ``webkit-gtk``: The older 1.8.3 version of this recipe has been
79 removed in favor of ``webkitgtk``.
80
81.. _migration-2.0-bitbake-datastore-improvements:
82
83BitBake datastore improvements
84------------------------------
85
86The method by which BitBake's datastore handles overrides has changed.
87Overrides are now applied dynamically and ``bb.data.update_data()`` is
88now a no-op. Thus, ``bb.data.update_data()`` is no longer required in
89order to apply the correct overrides. In practice, this change is
90unlikely to require any changes to Metadata. However, these minor
91changes in behavior exist:
92
93- All potential overrides are now visible in the variable history as
94 seen when you run the following:
95 ::
96
97 $ bitbake -e
98
99- ``d.delVar('``\ VARNAME\ ``')`` and
100 ``d.setVar('``\ VARNAME\ ``', None)`` result in the variable and all
101 of its overrides being cleared out. Before the change, only the
102 non-overridden values were cleared.
103
104.. _migration-2.0-shell-message-function-changes:
105
106Shell Message Function Changes
107------------------------------
108
109The shell versions of the BitBake message functions (i.e. ``bbdebug``,
110``bbnote``, ``bbwarn``, ``bbplain``, ``bberror``, and ``bbfatal``) are
111now connected through to their BitBake equivalents ``bb.debug()``,
112``bb.note()``, ``bb.warn()``, ``bb.plain()``, ``bb.error()``, and
113``bb.fatal()``, respectively. Thus, those message functions that you
114would expect to be printed by the BitBake UI are now actually printed.
115In practice, this change means two things:
116
117- If you now see messages on the console that you did not previously
118 see as a result of this change, you might need to clean up the calls
119 to ``bbwarn``, ``bberror``, and so forth. Or, you might want to
120 simply remove the calls.
121
122- The ``bbfatal`` message function now suppresses the full error log in
123 the UI, which means any calls to ``bbfatal`` where you still wish to
124 see the full error log should be replaced by ``die`` or
125 ``bbfatal_log``.
126
127.. _migration-2.0-extra-development-debug-package-cleanup:
128
129Extra Development/Debug Package Cleanup
130---------------------------------------
131
132The following recipes have had extra ``dev/dbg`` packages removed:
133
134- ``acl``
135
136- ``apmd``
137
138- ``aspell``
139
140- ``attr``
141
142- ``augeas``
143
144- ``bzip2``
145
146- ``cogl``
147
148- ``curl``
149
150- ``elfutils``
151
152- ``gcc-target``
153
154- ``libgcc``
155
156- ``libtool``
157
158- ``libxmu``
159
160- ``opkg``
161
162- ``pciutils``
163
164- ``rpm``
165
166- ``sysfsutils``
167
168- ``tiff``
169
170- ``xz``
171
172All of the above recipes now conform to the standard packaging scheme
173where a single ``-dev``, ``-dbg``, and ``-staticdev`` package exists per
174recipe.
175
176.. _migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core:
177
178Recipe Maintenance Tracking Data Moved to OE-Core
179-------------------------------------------------
180
181Maintenance tracking data for recipes that was previously part of
182``meta-yocto`` has been moved to :term:`OpenEmbedded-Core (OE-Core)`. The change
183includes ``package_regex.inc`` and ``distro_alias.inc``, which are
184typically enabled when using the ``distrodata`` class. Additionally, the
185contents of ``upstream_tracking.inc`` has now been split out to the
186relevant recipes.
187
188.. _migration-2.0-automatic-stale-sysroot-file-cleanup:
189
190Automatic Stale Sysroot File Cleanup
191------------------------------------
192
193Stale files from recipes that no longer exist in the current
194configuration are now automatically removed from sysroot as well as
195removed from any other place managed by shared state. This automatic
196cleanup means that the build system now properly handles situations such
197as renaming the build system side of recipes, removal of layers from
198``bblayers.conf``, and :term:`DISTRO_FEATURES`
199changes.
200
201Additionally, work directories for old versions of recipes are now
202pruned. If you wish to disable pruning old work directories, you can set
203the following variable in your configuration:
204::
205
206 SSTATE_PRUNE_OBSOLETEWORKDIR = "0"
207
208.. _migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source:
209
210``linux-yocto`` Kernel Metadata Repository Now Split from Source
211----------------------------------------------------------------
212
213The ``linux-yocto`` tree has up to now been a combined set of kernel
214changes and configuration (meta) data carried in a single tree. While
215this format is effective at keeping kernel configuration and source
216modifications synchronized, it is not always obvious to developers how
217to manipulate the Metadata as compared to the source.
218
219Metadata processing has now been removed from the
220:ref:`kernel-yocto <ref-classes-kernel-yocto>` class and the external
221Metadata repository ``yocto-kernel-cache``, which has always been used
222to seed the ``linux-yocto`` "meta" branch. This separate ``linux-yocto``
223cache repository is now the primary location for this data. Due to this
224change, ``linux-yocto`` is no longer able to process combined trees.
225Thus, if you need to have your own combined kernel repository, you must
226do the split there as well and update your recipes accordingly. See the
227``meta/recipes-kernel/linux/linux-yocto_4.1.bb`` recipe for an example.
228
229.. _migration-2.0-additional-qa-checks:
230
231Additional QA checks
232--------------------
233
234The following QA checks have been added:
235
236- Added a "host-user-contaminated" check for ownership issues for
237 packaged files outside of ``/home``. The check looks for files that
238 are incorrectly owned by the user that ran BitBake instead of owned
239 by a valid user in the target system.
240
241- Added an "invalid-chars" check for invalid (non-UTF8) characters in
242 recipe metadata variable values (i.e.
243 :term:`DESCRIPTION`,
244 :term:`SUMMARY`, :term:`LICENSE`, and
245 :term:`SECTION`). Some package managers do not support
246 these characters.
247
248- Added an "invalid-packageconfig" check for any options specified in
249 :term:`PACKAGECONFIG` that do not match any
250 ``PACKAGECONFIG`` option defined for the recipe.
251
252.. _migration-2.0-miscellaneous:
253
254Miscellaneous Changes
255---------------------
256
257These additional changes exist:
258
259- ``gtk-update-icon-cache`` has been renamed to ``gtk-icon-utils``.
260
261- The ``tools-profile`` :term:`IMAGE_FEATURES`
262 item as well as its corresponding packagegroup and
263 ``packagegroup-core-tools-profile`` no longer bring in ``oprofile``.
264 Bringing in ``oprofile`` was originally added to aid compilation on
265 resource-constrained targets. However, this aid has not been widely
266 used and is not likely to be used going forward due to the more
267 powerful target platforms and the existence of better
268 cross-compilation tools.
269
270- The :term:`IMAGE_FSTYPES` variable's default
271 value now specifies ``ext4`` instead of ``ext3``.
272
273- All support for the ``PRINC`` variable has been removed.
274
275- The ``packagegroup-core-full-cmdline`` packagegroup no longer brings
276 in ``lighttpd`` due to the fact that bringing in ``lighttpd`` is not
277 really in line with the packagegroup's purpose, which is to add full
278 versions of command-line tools that by default are provided by
279 ``busybox``.
280
281
diff --git a/documentation/ref-manual/migration-2.1.rst b/documentation/ref-manual/migration-2.1.rst
new file mode 100644
index 0000000000..a1fd3ea81d
--- /dev/null
+++ b/documentation/ref-manual/migration-2.1.rst
@@ -0,0 +1,434 @@
1Moving to the Yocto Project 2.1 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.1 Release from the prior release.
6
7.. _migration-2.1-variable-expansion-in-python-functions:
8
9Variable Expansion in Python Functions
10--------------------------------------
11
12Variable expressions, such as ``${``\ VARNAME\ ``}`` no longer expand
13automatically within Python functions. Suppressing expansion was done to
14allow Python functions to construct shell scripts or other code for
15situations in which you do not want such expressions expanded. For any
16existing code that relies on these expansions, you need to change the
17expansions to expand the value of individual variables through
18``d.getVar()``. To alternatively expand more complex expressions, use
19``d.expand()``.
20
21.. _migration-2.1-overrides-must-now-be-lower-case:
22
23Overrides Must Now be Lower-Case
24--------------------------------
25
26The convention for overrides has always been for them to be lower-case
27characters. This practice is now a requirement as BitBake's datastore
28now assumes lower-case characters in order to give a slight performance
29boost during parsing. In practical terms, this requirement means that
30anything that ends up in :term:`OVERRIDES` must now
31appear in lower-case characters (e.g. values for ``MACHINE``,
32``TARGET_ARCH``, ``DISTRO``, and also recipe names if
33``_pn-``\ recipename overrides are to be effective).
34
35.. _migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory:
36
37Expand Parameter to ``getVar()`` and ``getVarFlag()`` is Now Mandatory
38----------------------------------------------------------------------
39
40The expand parameter to ``getVar()`` and ``getVarFlag()`` previously
41defaulted to False if not specified. Now, however, no default exists so
42one must be specified. You must change any ``getVar()`` calls that do
43not specify the final expand parameter to calls that do specify the
44parameter. You can run the following ``sed`` command at the base of a
45layer to make this change:
46::
47
48 sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
49 sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
50
51.. note::
52
53 The reason for this change is that it prepares the way for changing
54 the default to True in a future Yocto Project release. This future
55 change is a much more sensible default than False. However, the
56 change needs to be made gradually as a sudden change of the default
57 would potentially cause side-effects that would be difficult to
58 detect.
59
60.. _migration-2.1-makefile-environment-changes:
61
62Makefile Environment Changes
63----------------------------
64
65:term:`EXTRA_OEMAKE` now defaults to "" instead of
66"-e MAKEFLAGS=". Setting ``EXTRA_OEMAKE`` to "-e MAKEFLAGS=" by default
67was a historical accident that has required many classes (e.g.
68``autotools``, ``module``) and recipes to override this default in order
69to work with sensible build systems. When upgrading to the release, you
70must edit any recipe that relies upon this old default by either setting
71``EXTRA_OEMAKE`` back to "-e MAKEFLAGS=" or by explicitly setting any
72required variable value overrides using ``EXTRA_OEMAKE``, which is
73typically only needed when a Makefile sets a default value for a
74variable that is inappropriate for cross-compilation using the "="
75operator rather than the "?=" operator.
76
77.. _migration-2.1-libexecdir-reverted-to-prefix-libexec:
78
79``libexecdir`` Reverted to ``${prefix}/libexec``
80------------------------------------------------
81
82The use of ``${libdir}/${BPN}`` as ``libexecdir`` is different as
83compared to all other mainstream distributions, which either uses
84``${prefix}/libexec`` or ``${libdir}``. The use is also contrary to the
85GNU Coding Standards (i.e.
86https://www.gnu.org/prep/standards/html_node/Directory-Variables.html)
87that suggest ``${prefix}/libexec`` and also notes that any
88package-specific nesting should be done by the package itself. Finally,
89having ``libexecdir`` change between recipes makes it very difficult for
90different recipes to invoke binaries that have been installed into
91``libexecdir``. The Filesystem Hierarchy Standard (i.e.
92http://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html) now
93recognizes the use of ``${prefix}/libexec/``, giving distributions the
94choice between ``${prefix}/lib`` or ``${prefix}/libexec`` without
95breaking FHS.
96
97.. _migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files:
98
99``ac_cv_sizeof_off_t`` is No Longer Cached in Site Files
100--------------------------------------------------------
101
102For recipes inheriting the :ref:`autotools <ref-classes-autotools>`
103class, ``ac_cv_sizeof_off_t`` is no longer cached in the site files for
104``autoconf``. The reason for this change is because the
105``ac_cv_sizeof_off_t`` value is not necessarily static per architecture
106as was previously assumed. Rather, the value changes based on whether
107large file support is enabled. For most software that uses ``autoconf``,
108this change should not be a problem. However, if you have a recipe that
109bypasses the standard :ref:`ref-tasks-configure` task
110from the ``autotools`` class and the software the recipe is building
111uses a very old version of ``autoconf``, the recipe might be incapable
112of determining the correct size of ``off_t`` during ``do_configure``.
113
114The best course of action is to patch the software as necessary to allow
115the default implementation from the ``autotools`` class to work such
116that ``autoreconf`` succeeds and produces a working configure script,
117and to remove the overridden ``do_configure`` task such that the default
118implementation does get used.
119
120.. _migration-2.1-image-generation-split-out-from-filesystem-generation:
121
122Image Generation is Now Split Out from Filesystem Generation
123------------------------------------------------------------
124
125Previously, for image recipes the :ref:`ref-tasks-rootfs`
126task assembled the filesystem and then from that filesystem generated
127images. With this Yocto Project release, image generation is split into
128separate ```do_image_*`` <#ref-tasks-image>`__ tasks for clarity both in
129operation and in the code.
130
131For most cases, this change does not present any problems. However, if
132you have made customizations that directly modify the ``do_rootfs`` task
133or that mention ``do_rootfs``, you might need to update those changes.
134In particular, if you had added any tasks after ``do_rootfs``, you
135should make edits so that those tasks are after the
136```do_image_complete`` <#ref-tasks-image-complete>`__ task rather than
137after ``do_rootfs`` so that the your added tasks run at the correct
138time.
139
140A minor part of this restructuring is that the post-processing
141definitions and functions have been moved from the
142:ref:`image <ref-classes-image>` class to the
143:ref:`rootfs-postcommands <ref-classes-rootfs*>` class. Functionally,
144however, they remain unchanged.
145
146.. _migration-2.1-removed-recipes:
147
148Removed Recipes
149---------------
150
151The following recipes have been removed in the 2.1 release:
152
153- ``gcc`` version 4.8: Versions 4.9 and 5.3 remain.
154
155- ``qt4``: All support for Qt 4.x has been moved out to a separate
156 ``meta-qt4`` layer because Qt 4 is no longer supported upstream.
157
158- ``x11vnc``: Moved to the ``meta-oe`` layer.
159
160- ``linux-yocto-3.14``: No longer supported.
161
162- ``linux-yocto-3.19``: No longer supported.
163
164- ``libjpeg``: Replaced by the ``libjpeg-turbo`` recipe.
165
166- ``pth``: Became obsolete.
167
168- ``liboil``: Recipe is no longer needed and has been moved to the
169 ``meta-multimedia`` layer.
170
171- ``gtk-theme-torturer``: Recipe is no longer needed and has been moved
172 to the ``meta-gnome`` layer.
173
174- ``gnome-mime-data``: Recipe is no longer needed and has been moved to
175 the ``meta-gnome`` layer.
176
177- ``udev``: Replaced by the ``eudev`` recipe for compatibility when
178 using ``sysvinit`` with newer kernels.
179
180- ``python-pygtk``: Recipe became obsolete.
181
182- ``adt-installer``: Recipe became obsolete. See the "`ADT
183 Removed <#migration-2.1-adt-removed>`__" section for more
184 information.
185
186.. _migration-2.1-class-changes:
187
188Class Changes
189-------------
190
191The following classes have changed:
192
193- ``autotools_stage``: Removed because the
194 :ref:`autotools <ref-classes-autotools>` class now provides its
195 functionality. Recipes that inherited from ``autotools_stage`` should
196 now inherit from ``autotools`` instead.
197
198- ``boot-directdisk``: Merged into the ``image-vm`` class. The
199 ``boot-directdisk`` class was rarely directly used. Consequently,
200 this change should not cause any issues.
201
202- ``bootimg``: Merged into the
203 :ref:`image-live <ref-classes-image-live>` class. The ``bootimg``
204 class was rarely directly used. Consequently, this change should not
205 cause any issues.
206
207- ``packageinfo``: Removed due to its limited use by the Hob UI, which
208 has itself been removed.
209
210.. _migration-2.1-build-system-ui-changes:
211
212Build System User Interface Changes
213-----------------------------------
214
215The following changes have been made to the build system user interface:
216
217- *Hob GTK+-based UI*: Removed because it is unmaintained and based on
218 the outdated GTK+ 2 library. The Toaster web-based UI is much more
219 capable and is actively maintained. See the
220 ":ref:`toaster-manual/toaster-manual-setup-and-use:using the toaster web interface`"
221 section in the Toaster User Manual for more information on this
222 interface.
223
224- *"puccho" BitBake UI*: Removed because is unmaintained and no longer
225 useful.
226
227.. _migration-2.1-adt-removed:
228
229ADT Removed
230-----------
231
232The Application Development Toolkit (ADT) has been removed because its
233functionality almost completely overlapped with the :ref:`standard
234SDK <sdk-manual/sdk-using:using the standard sdk>` and the
235:ref:`extensible SDK <sdk-manual/sdk-extensible:using the extensible sdk>`. For
236information on these SDKs and how to build and use them, see the
237:doc:`../sdk-manual/sdk-manual` manual.
238
239.. note::
240
241 The Yocto Project Eclipse IDE Plug-in is still supported and is not
242 affected by this change.
243
244.. _migration-2.1-poky-reference-distribution-changes:
245
246Poky Reference Distribution Changes
247-----------------------------------
248
249The following changes have been made for the Poky distribution:
250
251- The ``meta-yocto`` layer has been renamed to ``meta-poky`` to better
252 match its purpose, which is to provide the Poky reference
253 distribution. The ``meta-yocto-bsp`` layer retains its original name
254 since it provides reference machines for the Yocto Project and it is
255 otherwise unrelated to Poky. References to ``meta-yocto`` in your
256 ``conf/bblayers.conf`` should automatically be updated, so you should
257 not need to change anything unless you are relying on this naming
258 elsewhere.
259
260- The :ref:`uninative <ref-classes-uninative>` class is now enabled
261 by default in Poky. This class attempts to isolate the build system
262 from the host distribution's C library and makes re-use of native
263 shared state artifacts across different host distributions practical.
264 With this class enabled, a tarball containing a pre-built C library
265 is downloaded at the start of the build.
266
267 The ``uninative`` class is enabled through the
268 ``meta/conf/distro/include/yocto-uninative.inc`` file, which for
269 those not using the Poky distribution, can include to easily enable
270 the same functionality.
271
272 Alternatively, if you wish to build your own ``uninative`` tarball,
273 you can do so by building the ``uninative-tarball`` recipe, making it
274 available to your build machines (e.g. over HTTP/HTTPS) and setting a
275 similar configuration as the one set by ``yocto-uninative.inc``.
276
277- Static library generation, for most cases, is now disabled by default
278 in the Poky distribution. Disabling this generation saves some build
279 time as well as the size used for build output artifacts.
280
281 Disabling this library generation is accomplished through a
282 ``meta/conf/distro/include/no-static-libs.inc``, which for those not
283 using the Poky distribution can easily include to enable the same
284 functionality.
285
286 Any recipe that needs to opt-out of having the "--disable-static"
287 option specified on the configure command line either because it is
288 not a supported option for the configure script or because static
289 libraries are needed should set the following variable:
290 DISABLE_STATIC = ""
291
292- The separate ``poky-tiny`` distribution now uses the musl C library
293 instead of a heavily pared down ``glibc``. Using musl results in a
294 smaller distribution and facilitates much greater maintainability
295 because musl is designed to have a small footprint.
296
297 If you have used ``poky-tiny`` and have customized the ``glibc``
298 configuration you will need to redo those customizations with musl
299 when upgrading to the new release.
300
301.. _migration-2.1-packaging-changes:
302
303Packaging Changes
304-----------------
305
306The following changes have been made to packaging:
307
308- The ``runuser`` and ``mountpoint`` binaries, which were previously in
309 the main ``util-linux`` package, have been split out into the
310 ``util-linux-runuser`` and ``util-linux-mountpoint`` packages,
311 respectively.
312
313- The ``python-elementtree`` package has been merged into the
314 ``python-xml`` package.
315
316.. _migration-2.1-tuning-file-changes:
317
318Tuning File Changes
319-------------------
320
321The following changes have been made to the tuning files:
322
323- The "no-thumb-interwork" tuning feature has been dropped from the ARM
324 tune include files. Because interworking is required for ARM EABI,
325 attempting to disable it through a tuning feature no longer makes
326 sense.
327
328 .. note::
329
330 Support for ARM OABI was deprecated in gcc 4.7.
331
332- The ``tune-cortexm*.inc`` and ``tune-cortexr4.inc`` files have been
333 removed because they are poorly tested. Until the OpenEmbedded build
334 system officially gains support for CPUs without an MMU, these tuning
335 files would probably be better maintained in a separate layer if
336 needed.
337
338.. _migration-2.1-supporting-gobject-introspection:
339
340Supporting GObject Introspection
341--------------------------------
342
343This release supports generation of GLib Introspective Repository (GIR)
344files through GObject introspection, which is the standard mechanism for
345accessing GObject-based software from runtime environments. You can
346enable, disable, and test the generation of this data. See the
347":ref:`dev-manual/dev-manual-common-tasks:enabling gobject introspection support`"
348section in the Yocto Project Development Tasks Manual for more
349information.
350
351.. _migration-2.1-miscellaneous-changes:
352
353Miscellaneous Changes
354---------------------
355
356These additional changes exist:
357
358- The minimum Git version has been increased to 1.8.3.1. If your host
359 distribution does not provide a sufficiently recent version, you can
360 install the buildtools, which will provide it. See the "`Required
361 Git, tar, Python and gcc
362 Versions <#required-git-tar-python-and-gcc-versions>`__" section for
363 more information on the buildtools tarball.
364
365- The buggy and incomplete support for the RPM version 4 package
366 manager has been removed. The well-tested and maintained support for
367 RPM version 5 remains.
368
369- Previously, the following list of packages were removed if
370 package-management was not in
371 :term:`IMAGE_FEATURES`, regardless of any
372 dependencies:
373 ::
374
375 update-rc.d
376 base-passwd
377 shadow
378 update-alternatives
379
380 run-postinsts With the Yocto Project 2.1 release, these packages are
381 only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since
382 they might still be needed for a read-write image even in the absence
383 of a package manager (e.g. if users need to be added, modified, or
384 removed at runtime).
385
386- The
387 :ref:`devtool modify <sdk-manual/sdk-extensible:use \`\`devtool modify\`\` to modify the source of an existing component>`
388 command now defaults to extracting the source since that is most
389 commonly expected. The "-x" or "--extract" options are now no-ops. If
390 you wish to provide your own existing source tree, you will now need
391 to specify either the "-n" or "--no-extract" options when running
392 ``devtool modify``.
393
394- If the formfactor for a machine is either not supplied or does not
395 specify whether a keyboard is attached, then the default is to assume
396 a keyboard is attached rather than assume no keyboard. This change
397 primarily affects the Sato UI.
398
399- The ``.debug`` directory packaging is now automatic. If your recipe
400 builds software that installs binaries into directories other than
401 the standard ones, you no longer need to take care of setting
402 ``FILES_${PN}-dbg`` to pick up the resulting ``.debug`` directories
403 as these directories are automatically found and added.
404
405- Inaccurate disk and CPU percentage data has been dropped from
406 ``buildstats`` output. This data has been replaced with
407 ``getrusage()`` data and corrected IO statistics. You will probably
408 need to update any custom code that reads the ``buildstats`` data.
409
410- The ``meta/conf/distro/include/package_regex.inc`` is now deprecated.
411 The contents of this file have been moved to individual recipes.
412
413 .. note::
414
415 Because this file will likely be removed in a future Yocto Project
416 release, it is suggested that you remove any references to the
417 file that might be in your configuration.
418
419- The ``v86d/uvesafb`` has been removed from the ``genericx86`` and
420 ``genericx86-64`` reference machines, which are provided by the
421 ``meta-yocto-bsp`` layer. Most modern x86 boards do not rely on this
422 file and it only adds kernel error messages during startup. If you do
423 still need to support ``uvesafb``, you can simply add ``v86d`` to
424 your image.
425
426- Build sysroot paths are now removed from debug symbol files. Removing
427 these paths means that remote GDB using an unstripped build system
428 sysroot will no longer work (although this was never documented to
429 work). The supported method to accomplish something similar is to set
430 ``IMAGE_GEN_DEBUGFS`` to "1", which will generate a companion debug
431 image containing unstripped binaries and associated debug sources
432 alongside the image.
433
434
diff --git a/documentation/ref-manual/migration-2.2.rst b/documentation/ref-manual/migration-2.2.rst
new file mode 100644
index 0000000000..59d0eeeb9d
--- /dev/null
+++ b/documentation/ref-manual/migration-2.2.rst
@@ -0,0 +1,451 @@
1Moving to the Yocto Project 2.2 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.2 Release from the prior release.
6
7.. _migration-2.2-minimum-kernel-version:
8
9Minimum Kernel Version
10----------------------
11
12The minimum kernel version for the target system and for SDK is now
133.2.0, due to the upgrade to ``glibc 2.24``. Specifically, for
14AArch64-based targets the version is 3.14. For Nios II-based targets,
15the minimum kernel version is 3.19.
16
17.. note::
18
19 For x86 and x86_64, you can reset
20 OLDEST_KERNEL
21 to anything down to 2.6.32 if desired.
22
23.. _migration-2.2-staging-directories-in-sysroot-simplified:
24
25Staging Directories in Sysroot Has Been Simplified
26--------------------------------------------------
27
28The way directories are staged in sysroot has been simplified and
29introduces the new :term:`SYSROOT_DIRS`,
30:term:`SYSROOT_DIRS_NATIVE`, and
31:term:`SYSROOT_DIRS_BLACKLIST`. See the
32`v2 patch series on the OE-Core Mailing
33List <http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html>`__
34for additional information.
35
36.. _migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled:
37
38Removal of Old Images and Other Files in ``tmp/deploy`` Now Enabled
39-------------------------------------------------------------------
40
41Removal of old images and other files in ``tmp/deploy/`` is now enabled
42by default due to a new staging method used for those files. As a result
43of this change, the ``RM_OLD_IMAGE`` variable is now redundant.
44
45.. _migration-2.2-python-changes:
46
47Python Changes
48--------------
49
50The following changes for Python occurred:
51
52.. _migration-2.2-bitbake-now-requires-python-3.4:
53
54BitBake Now Requires Python 3.4+
55~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
56
57BitBake requires Python 3.4 or greater.
58
59.. _migration-2.2-utf-8-locale-required-on-build-host:
60
61UTF-8 Locale Required on Build Host
62~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63
64A UTF-8 locale is required on the build host due to Python 3. Since
65C.UTF-8 is not a standard, the default is en_US.UTF-8.
66
67.. _migration-2.2-metadata-now-must-use-python-3-syntax:
68
69Metadata Must Now Use Python 3 Syntax
70~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71
72The metadata is now required to use Python 3 syntax. For help preparing
73metadata, see any of the many Python 3 porting guides available.
74Alternatively, you can reference the conversion commits for Bitbake and
75you can use :term:`OpenEmbedded-Core (OE-Core)` as a guide for changes. Following are
76particular areas of interest:
77
78 - subprocess command-line pipes needing locale decoding
79
80 - the syntax for octal values changed
81
82 - the ``iter*()`` functions changed name \* iterators now return views, not lists
83
84 - changed names for Python modules
85
86.. _migration-2.2-target-python-recipes-switched-to-python-3:
87
88Target Python Recipes Switched to Python 3
89~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
90
91Most target Python recipes have now been switched to Python 3.
92Unfortunately, systems using RPM as a package manager and providing
93online package-manager support through SMART still require Python 2.
94
95.. note::
96
97 Python 2 and recipes that use it can still be built for the target as
98 with previous versions.
99
100.. _migration-2.2-buildtools-tarball-includes-python-3:
101
102``buildtools-tarball`` Includes Python 3
103~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104
105``buildtools-tarball`` now includes Python 3.
106
107.. _migration-2.2-uclibc-replaced-by-musl:
108
109uClibc Replaced by musl
110-----------------------
111
112uClibc has been removed in favor of musl. Musl has matured, is better
113maintained, and is compatible with a wider range of applications as
114compared to uClibc.
115
116.. _migration-2.2-B-no-longer-default-working-directory-for-tasks:
117
118``${B}`` No Longer Default Working Directory for Tasks
119------------------------------------------------------
120
121``${``\ :term:`B`\ ``}`` is no longer the default working
122directory for tasks. Consequently, any custom tasks you define now need
123to either have the
124``[``\ :ref:`dirs <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` flag
125set, or the task needs to change into the appropriate working directory
126manually (e.g using ``cd`` for a shell task).
127
128.. note::
129
130 The preferred method is to use the
131 [dirs]
132 flag.
133
134.. _migration-2.2-runqemu-ported-to-python:
135
136``runqemu`` Ported to Python
137----------------------------
138
139``runqemu`` has been ported to Python and has changed behavior in some
140cases. Previous usage patterns continue to be supported.
141
142The new ``runqemu`` is a Python script. Machine knowledge is no longer
143hardcoded into ``runqemu``. You can choose to use the ``qemuboot``
144configuration file to define the BSP's own arguments and to make it
145bootable with ``runqemu``. If you use a configuration file, use the
146following form:
147::
148
149 image-name-machine.qemuboot.conf
150
151The configuration file
152enables fine-grained tuning of options passed to QEMU without the
153``runqemu`` script hard-coding any knowledge about different machines.
154Using a configuration file is particularly convenient when trying to use
155QEMU with machines other than the ``qemu*`` machines in
156:term:`OpenEmbedded-Core (OE-Core)`. The ``qemuboot.conf`` file is generated by the
157``qemuboot`` class when the root filesystem is being build (i.e. build
158rootfs). QEMU boot arguments can be set in BSP's configuration file and
159the ``qemuboot`` class will save them to ``qemuboot.conf``.
160
161If you want to use ``runqemu`` without a configuration file, use the
162following command form:
163::
164
165 $ runqemu machine rootfs kernel [options]
166
167Supported machines are as follows:
168
169 - qemuarm
170 - qemuarm64
171 - qemux86
172 - qemux86-64
173 - qemuppc
174 - qemumips
175 - qemumips64
176 - qemumipsel
177 - qemumips64el
178
179Consider the
180following example, which uses the ``qemux86-64`` machine, provides a
181root filesystem, provides an image, and uses the ``nographic`` option: ::
182
183 $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
184
185Following is a list of variables that can be set in configuration files
186such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``:
187
188.. note::
189
190 "QB" means "QEMU Boot".
191
192::
193
194 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
195 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
196 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
197 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
198 QB_MEM: Memory (e.g. "-m 512")
199 QB_MACHINE: QEMU machine (e.g. "-machine virt")
200 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
201 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
202 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
203 option (e.g. "console=ttyS0 console=tty")
204 QB_DTB: QEMU dtb name
205 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
206 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
207 when QB_AUDIO_DRV is set.
208 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
209 QB_TAP_OPT: Network option for 'tap' mode (e.g.
210 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
211 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
212 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
213 QB_ROOTFS_OPT: Used as rootfs (e.g.
214 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
215 runqemu will replace "@ROOTFS@" with the one which is used, such as
216 core-image-minimal-qemuarm64.ext4.
217 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
218 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
219 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
220 runqemu will replace "@PORT@" with the port number which is used.
221
222To use ``runqemu``, set :term:`IMAGE_CLASSES` as
223follows and run ``runqemu``:
224
225.. note::
226
227 For command-line syntax, use
228 runqemu help
229 .
230
231::
232
233 IMAGE_CLASSES += "qemuboot"
234
235.. _migration-2.2-default-linker-hash-style-changed:
236
237Default Linker Hash Style Changed
238---------------------------------
239
240The default linker hash style for ``gcc-cross`` is now "sysv" in order
241to catch recipes that are building software without using the
242OpenEmbedded :term:`LDFLAGS`. This change could result in
243seeing some "No GNU_HASH in the elf binary" QA issues when building such
244recipes. You need to fix these recipes so that they use the expected
245``LDFLAGS``. Depending on how the software is built, the build system
246used by the software (e.g. a Makefile) might need to be patched.
247However, sometimes making this fix is as simple as adding the following
248to the recipe:
249::
250
251 TARGET_CC_ARCH += "${LDFLAGS}"
252
253.. _migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype:
254
255``KERNEL_IMAGE_BASE_NAME`` no Longer Uses ``KERNEL_IMAGETYPE``
256--------------------------------------------------------------
257
258The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the
259:term:`KERNEL_IMAGETYPE` variable to create the
260image's base name. Because the OpenEmbedded build system can now build
261multiple kernel image types, this part of the kernel image base name as
262been removed leaving only the following:
263::
264
265 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
266
267If you have recipes or
268classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to
269update the references to ensure they continue to work.
270
271.. _migration-2.2-bitbake-changes:
272
273BitBake Changes
274---------------
275
276The following changes took place for BitBake:
277
278- The "goggle" UI and standalone image-writer tool have been removed as
279 they both require GTK+ 2.0 and were not being maintained.
280
281- The Perforce fetcher now supports :term:`SRCREV` for
282 specifying the source revision to use, be it
283 ``${``\ :term:`AUTOREV`\ ``}``, changelist number,
284 p4date, or label, in preference to separate
285 :term:`SRC_URI` parameters to specify these. This
286 change is more in-line with how the other fetchers work for source
287 control systems. Recipes that fetch from Perforce will need to be
288 updated to use ``SRCREV`` in place of specifying the source revision
289 within ``SRC_URI``.
290
291- Some of BitBake's internal code structures for accessing the recipe
292 cache needed to be changed to support the new multi-configuration
293 functionality. These changes will affect external tools that use
294 BitBake's tinfoil module. For information on these changes, see the
295 changes made to the scripts supplied with OpenEmbedded-Core:
296 `1 <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>`__
297 and
298 `2 <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`__.
299
300- The task management code has been rewritten to avoid using ID
301 indirection in order to improve performance. This change is unlikely
302 to cause any problems for most users. However, the setscene
303 verification function as pointed to by
304 ``BB_SETSCENE_VERIFY_FUNCTION`` needed to change signature.
305 Consequently, a new variable named ``BB_SETSCENE_VERIFY_FUNCTION2``
306 has been added allowing multiple versions of BitBake to work with
307 suitably written metadata, which includes OpenEmbedded-Core and Poky.
308 Anyone with custom BitBake task scheduler code might also need to
309 update the code to handle the new structure.
310
311.. _migration-2.2-swabber-has-been-removed:
312
313Swabber has Been Removed
314------------------------
315
316Swabber, a tool that was intended to detect host contamination in the
317build process, has been removed, as it has been unmaintained and unused
318for some time and was never particularly effective. The OpenEmbedded
319build system has since incorporated a number of mechanisms including
320enhanced QA checks that mean that there is less of a need for such a
321tool.
322
323.. _migration-2.2-removed-recipes:
324
325Removed Recipes
326---------------
327
328The following recipes have been removed:
329
330- ``augeas``: No longer needed and has been moved to ``meta-oe``.
331
332- ``directfb``: Unmaintained and has been moved to ``meta-oe``.
333
334- ``gcc``: Removed 4.9 version. Versions 5.4 and 6.2 are still present.
335
336- ``gnome-doc-utils``: No longer needed.
337
338- ``gtk-doc-stub``: Replaced by ``gtk-doc``.
339
340- ``gtk-engines``: No longer needed and has been moved to
341 ``meta-gnome``.
342
343- ``gtk-sato-engine``: Became obsolete.
344
345- ``libglade``: No longer needed and has been moved to ``meta-oe``.
346
347- ``libmad``: Unmaintained and functionally replaced by ``libmpg123``.
348 ``libmad`` has been moved to ``meta-oe``.
349
350- ``libowl``: Became obsolete.
351
352- ``libxsettings-client``: No longer needed.
353
354- ``oh-puzzles``: Functionally replaced by ``puzzles``.
355
356- ``oprofileui``: Became obsolete. OProfile has been largely supplanted
357 by perf.
358
359- ``packagegroup-core-directfb.bb``: Removed.
360
361- ``core-image-directfb.bb``: Removed.
362
363- ``pointercal``: No longer needed and has been moved to ``meta-oe``.
364
365- ``python-imaging``: No longer needed and moved to ``meta-python``
366
367- ``python-pyrex``: No longer needed and moved to ``meta-python``.
368
369- ``sato-icon-theme``: Became obsolete.
370
371- ``swabber-native``: Swabber has been removed. See the `entry on
372 Swabber <#migration-2.2-swabber-has-been-removed>`__.
373
374- ``tslib``: No longer needed and has been moved to ``meta-oe``.
375
376- ``uclibc``: Removed in favor of musl.
377
378- ``xtscal``: No longer needed and moved to ``meta-oe``
379
380.. _migration-2.2-removed-classes:
381
382Removed Classes
383---------------
384
385The following classes have been removed:
386
387- ``distutils-native-base``: No longer needed.
388
389- ``distutils3-native-base``: No longer needed.
390
391- ``sdl``: Only set :term:`DEPENDS` and
392 :term:`SECTION`, which are better set within the
393 recipe instead.
394
395- ``sip``: Mostly unused.
396
397- ``swabber``: See the `entry on
398 Swabber <#migration-2.2-swabber-has-been-removed>`__.
399
400.. _migration-2.2-minor-packaging-changes:
401
402Minor Packaging Changes
403-----------------------
404
405The following minor packaging changes have occurred:
406
407- ``grub``: Split ``grub-editenv`` into its own package.
408
409- ``systemd``: Split container and vm related units into a new package,
410 systemd-container.
411
412- ``util-linux``: Moved ``prlimit`` to a separate
413 ``util-linux-prlimit`` package.
414
415.. _migration-2.2-miscellaneous-changes:
416
417Miscellaneous Changes
418---------------------
419
420The following miscellaneous changes have occurred:
421
422- ``package_regex.inc``: Removed because the definitions
423 ``package_regex.inc`` previously contained have been moved to their
424 respective recipes.
425
426- Both ``devtool add`` and ``recipetool create`` now use a fixed
427 :term:`SRCREV` by default when fetching from a Git
428 repository. You can override this in either case to use
429 ``${``\ :term:`AUTOREV`\ ``}`` instead by using the
430 ``-a`` or ``DASHDASHautorev`` command-line option
431
432- ``distcc``: GTK+ UI is now disabled by default.
433
434- ``packagegroup-core-tools-testapps``: Removed Piglit.
435
436- ``image.bbclass``: Renamed COMPRESS(ION) to CONVERSION. This change
437 means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and
438 ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``,
439 ``CONVERSION_DEPENDS`` and ``CONVERSION_CMD``. The ``COMPRESS*``
440 variable names will still work in the 2.2 release but metadata that
441 does not need to be backwards-compatible should be changed to use the
442 new names as the ``COMPRESS*`` ones will be removed in a future
443 release.
444
445- ``gtk-doc``: A full version of ``gtk-doc`` is now made available.
446 However, some old software might not be capable of using the current
447 version of ``gtk-doc`` to build documentation. You need to change
448 recipes that build such software so that they explicitly disable
449 building documentation with ``gtk-doc``.
450
451
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
diff --git a/documentation/ref-manual/migration-2.4.rst b/documentation/ref-manual/migration-2.4.rst
new file mode 100644
index 0000000000..260b3204b6
--- /dev/null
+++ b/documentation/ref-manual/migration-2.4.rst
@@ -0,0 +1,327 @@
1Moving to the Yocto Project 2.4 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.4 Release from the prior release.
6
7.. _migration-2.4-memory-resident-mode:
8
9Memory Resident Mode
10--------------------
11
12A persistent mode is now available in BitBake's default operation,
13replacing its previous "memory resident mode" (i.e.
14``oe-init-build-env-memres``). Now you only need to set
15:term:`BB_SERVER_TIMEOUT` to a timeout (in
16seconds) and BitBake's server stays resident for that amount of time
17between invocations. The ``oe-init-build-env-memres`` script has been
18removed since a separate environment setup script is no longer needed.
19
20.. _migration-2.4-packaging-changes:
21
22Packaging Changes
23-----------------
24
25This section provides information about packaging changes that have
26occurred:
27
28- ``python3`` Changes:
29
30 - The main "python3" package now brings in all of the standard
31 Python 3 distribution rather than a subset. This behavior matches
32 what is expected based on traditional Linux distributions. If you
33 wish to install a subset of Python 3, specify ``python-core`` plus
34 one or more of the individual packages that are still produced.
35
36 - ``python3``: The ``bz2.py``, ``lzma.py``, and
37 ``_compression.py`` scripts have been moved from the
38 ``python3-misc`` package to the ``python3-compression`` package.
39
40- ``binutils``: The ``libbfd`` library is now packaged in a separate
41 "libbfd" package. This packaging saves space when certain tools (e.g.
42 ``perf``) are installed. In such cases, the tools only need
43 ``libbfd`` rather than all the packages in ``binutils``.
44
45- ``util-linux`` Changes:
46
47 - The ``su`` program is now packaged in a separate "util-linux-su"
48 package, which is only built when "pam" is listed in the
49 :term:`DISTRO_FEATURES` variable.
50 ``util-linux`` should not be installed unless it is needed because
51 ``su`` is normally provided through the shadow file format. The
52 main ``util-linux`` package has runtime dependencies (i.e.
53 :term:`RDEPENDS`) on the ``util-linux-su`` package
54 when "pam" is in ``DISTRO_FEATURES``.
55
56 - The ``switch_root`` program is now packaged in a separate
57 "util-linux-switch-root" package for small initramfs images that
58 do not need the whole ``util-linux`` package or the busybox
59 binary, which are both much larger than ``switch_root``. The main
60 ``util-linux`` package has a recommended runtime dependency (i.e.
61 :term:`RRECOMMENDS`) on the
62 ``util-linux-switch-root`` package.
63
64 - The ``ionice`` program is now packaged in a separate
65 "util-linux-ionice" package. The main ``util-linux`` package has a
66 recommended runtime dependency (i.e. ``RRECOMMENDS``) on the
67 ``util-linux-ionice`` package.
68
69- ``initscripts``: The ``sushell`` program is now packaged in a
70 separate "initscripts-sushell" package. This packaging change allows
71 systems to pull ``sushell`` in when ``selinux`` is enabled. The
72 change also eliminates needing to pull in the entire ``initscripts``
73 package. The main ``initscripts`` package has a runtime dependency
74 (i.e. ``RDEPENDS``) on the ``sushell`` package when "selinux" is in
75 ``DISTRO_FEATURES``.
76
77- ``glib-2.0``: The ``glib-2.0`` package now has a recommended
78 runtime dependency (i.e. ``RRECOMMENDS``) on the ``shared-mime-info``
79 package, since large portions of GIO are not useful without the MIME
80 database. You can remove the dependency by using the
81 :term:`BAD_RECOMMENDATIONS` variable if
82 ``shared-mime-info`` is too large and is not required.
83
84- *Go Standard Runtime:* The Go standard runtime has been split out
85 from the main ``go`` recipe into a separate ``go-runtime`` recipe.
86
87.. _migration-2.4-removed-recipes:
88
89Removed Recipes
90---------------
91
92The following recipes have been removed:
93
94- ``acpitests``: This recipe is not maintained.
95
96- ``autogen-native``: No longer required by Grub, oe-core, or
97 meta-oe.
98
99- ``bdwgc``: Nothing in OpenEmbedded-Core requires this recipe. It
100 has moved to meta-oe.
101
102- ``byacc``: This recipe was only needed by rpm 5.x and has moved to
103 meta-oe.
104
105- ``gcc (5.4)``: The 5.4 series dropped the recipe in favor of 6.3 /
106 7.2.
107
108- ``gnome-common``: Deprecated upstream and no longer needed.
109
110- ``go-bootstrap-native``: Go 1.9 does its own bootstrapping so this
111 recipe has been removed.
112
113- ``guile``: This recipe was only needed by ``autogen-native`` and
114 ``remake``. The recipe is no longer needed by either of these
115 programs.
116
117- ``libclass-isa-perl``: This recipe was previously needed for LSB 4,
118 no longer needed.
119
120- ``libdumpvalue-perl``: This recipe was previously needed for LSB 4,
121 no longer needed.
122
123- ``libenv-perl``: This recipe was previously needed for LSB 4, no
124 longer needed.
125
126- ``libfile-checktree-perl``: This recipe was previously needed for
127 LSB 4, no longer needed.
128
129- ``libi18n-collate-perl``: This recipe was previously needed for LSB
130 4, no longer needed.
131
132- ``libiconv``: This recipe was only needed for ``uclibc``, which was
133 removed in the previous release. ``glibc`` and ``musl`` have their
134 own implementations. ``meta-mingw`` still needs ``libiconv``, so it
135 has been moved to ``meta-mingw``.
136
137- ``libpng12``: This recipe was previously needed for LSB. The
138 current ``libpng`` is 1.6.x.
139
140- ``libpod-plainer-perl``: This recipe was previously needed for LSB
141 4, no longer needed.
142
143- ``linux-yocto (4.1)``: This recipe was removed in favor of 4.4,
144 4.9, 4.10 and 4.12.
145
146- ``mailx``: This recipe was previously only needed for LSB
147 compatibility, and upstream is defunct.
148
149- ``mesa (git version only)``: The git version recipe was stale with
150 respect to the release version.
151
152- ``ofono (git version only)``: The git version recipe was stale with
153 respect to the release version.
154
155- ``portmap``: This recipe is obsolete and is superseded by
156 ``rpcbind``.
157
158- ``python3-pygpgme``: This recipe is old and unmaintained. It was
159 previously required by ``dnf``, which has switched to official
160 ``gpgme`` Python bindings.
161
162- ``python-async``: This recipe has been removed in favor of the
163 Python 3 version.
164
165- ``python-gitdb``: This recipe has been removed in favor of the
166 Python 3 version.
167
168- ``python-git``: This recipe was removed in favor of the Python 3
169 version.
170
171- ``python-mako``: This recipe was removed in favor of the Python 3
172 version.
173
174- ``python-pexpect``: This recipe was removed in favor of the Python
175 3 version.
176
177- ``python-ptyprocess``: This recipe was removed in favor of Python
178 the 3 version.
179
180- ``python-pycurl``: Nothing is using this recipe in
181 OpenEmbedded-Core (i.e. ``meta-oe``).
182
183- ``python-six``: This recipe was removed in favor of the Python 3
184 version.
185
186- ``python-smmap``: This recipe was removed in favor of the Python 3
187 version.
188
189- ``remake``: Using ``remake`` as the provider of ``virtual/make`` is
190 broken. Consequently, this recipe is not needed in OpenEmbedded-Core.
191
192.. _migration-2.4-kernel-device-tree-move:
193
194Kernel Device Tree Move
195-----------------------
196
197Kernel Device Tree support is now easier to enable in a kernel recipe.
198The Device Tree code has moved to a
199:ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class.
200Functionality is automatically enabled for any recipe that inherits the
201:ref:`kernel <ref-classes-kernel>` class and sets the
202:term:`KERNEL_DEVICETREE` variable. The
203previous mechanism for doing this,
204``meta/recipes-kernel/linux/linux-dtb.inc``, is still available to avoid
205breakage, but triggers a deprecation warning. Future releases of the
206Yocto Project will remove ``meta/recipes-kernel/linux/linux-dtb.inc``.
207It is advisable to remove any ``require`` statements that request
208``meta/recipes-kernel/linux/linux-dtb.inc`` from any custom kernel
209recipes you might have. This will avoid breakage in post 2.4 releases.
210
211.. _migration-2.4-package-qa-changes:
212
213Package QA Changes
214------------------
215
216The following package QA changes took place:
217
218- The "unsafe-references-in-scripts" QA check has been removed.
219
220- If you refer to ``${COREBASE}/LICENSE`` within
221 :term:`LIC_FILES_CHKSUM` you receive a
222 warning because this file is a description of the license for
223 OE-Core. Use ``${COMMON_LICENSE_DIR}/MIT`` if your recipe is
224 MIT-licensed and you cannot use the preferred method of referring to
225 a file within the source tree.
226
227.. _migration-2.4-readme-changes:
228
229``README`` File Changes
230-----------------------
231
232The following are changes to ``README`` files:
233
234- The main Poky ``README`` file has been moved to the ``meta-poky``
235 layer and has been renamed ``README.poky``. A symlink has been
236 created so that references to the old location work.
237
238- The ``README.hardware`` file has been moved to ``meta-yocto-bsp``. A
239 symlink has been created so that references to the old location work.
240
241- A ``README.qemu`` file has been created with coverage of the
242 ``qemu*`` machines.
243
244.. _migration-2.4-miscellaneous-changes:
245
246Miscellaneous Changes
247---------------------
248
249The following are additional changes:
250
251- The ``ROOTFS_PKGMANAGE_BOOTSTRAP`` variable and any references to it
252 have been removed. You should remove this variable from any custom
253 recipes.
254
255- The ``meta-yocto`` directory has been removed.
256
257 .. note::
258
259 In the Yocto Project 2.1 release
260 meta-yocto
261 was renamed to
262 meta-poky
263 and the
264 meta-yocto
265 subdirectory remained to avoid breaking existing configurations.
266
267- The ``maintainers.inc`` file, which tracks maintainers by listing a
268 primary person responsible for each recipe in OE-Core, has been moved
269 from ``meta-poky`` to OE-Core (i.e. from
270 ``meta-poky/conf/distro/include`` to ``meta/conf/distro/include``).
271
272- The :ref:`buildhistory <ref-classes-buildhistory>` class now makes
273 a single commit per build rather than one commit per subdirectory in
274 the repository. This behavior assumes the commits are enabled with
275 :term:`BUILDHISTORY_COMMIT` = "1", which
276 is typical. Previously, the ``buildhistory`` class made one commit
277 per subdirectory in the repository in order to make it easier to see
278 the changes for a particular subdirectory. To view a particular
279 change, specify that subdirectory as the last parameter on the
280 ``git show`` or ``git diff`` commands.
281
282- The ``x86-base.inc`` file, which is included by all x86-based machine
283 configurations, now sets :term:`IMAGE_FSTYPES`
284 using ``?=`` to "live" rather than appending with ``+=``. This change
285 makes the default easier to override.
286
287- BitBake fires multiple "BuildStarted" events when multiconfig is
288 enabled (one per configuration). For more information, see the
289 ":ref:`Events <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:events>`" section in the BitBake User
290 Manual.
291
292- By default, the ``security_flags.inc`` file sets a
293 :term:`GCCPIE` variable with an option to enable
294 Position Independent Executables (PIE) within ``gcc``. Enabling PIE
295 in the GNU C Compiler (GCC), makes Return Oriented Programming (ROP)
296 attacks much more difficult to execute.
297
298- OE-Core now provides a ``bitbake-layers`` plugin that implements a
299 "create-layer" subcommand. The implementation of this subcommand has
300 resulted in the ``yocto-layer`` script being deprecated and will
301 likely be removed in the next Yocto Project release.
302
303- The ``vmdk``, ``vdi``, and ``qcow2`` image file types are now used in
304 conjunction with the "wic" image type through ``CONVERSION_CMD``.
305 Consequently, the equivalent image types are now ``wic.vmdk``,
306 ``wic.vdi``, and ``wic.qcow2``, respectively.
307
308- ``do_image_<type>[depends]`` has replaced ``IMAGE_DEPENDS_<type>``.
309 If you have your own classes that implement custom image types, then
310 you need to update them.
311
312- OpenSSL 1.1 has been introduced. However, the default is still 1.0.x
313 through the :term:`PREFERRED_VERSION`
314 variable. This preference is set is due to the remaining
315 compatibility issues with other software. The
316 :term:`PROVIDES` variable in the openssl 1.0 recipe
317 now includes "openssl10" as a marker that can be used in
318 :term:`DEPENDS` within recipes that build software
319 that still depend on OpenSSL 1.0.
320
321- To ensure consistent behavior, BitBake's "-r" and "-R" options (i.e.
322 prefile and postfile), which are used to read or post-read additional
323 configuration files from the command line, now only affect the
324 current BitBake command. Before these BitBake changes, these options
325 would "stick" for future executions.
326
327
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
diff --git a/documentation/ref-manual/migration-2.6.rst b/documentation/ref-manual/migration-2.6.rst
new file mode 100644
index 0000000000..f16aaaa975
--- /dev/null
+++ b/documentation/ref-manual/migration-2.6.rst
@@ -0,0 +1,476 @@
1Moving to the Yocto Project 2.6 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.6 Release from the prior release.
6
7.. _migration-2.6-gcc-changes:
8
9GCC 8.2 is Now Used by Default
10------------------------------
11
12The GNU Compiler Collection version 8.2 is now used by default for
13compilation. For more information on what has changed in the GCC 8.x
14release, see https://gcc.gnu.org/gcc-8/changes.html.
15
16If you still need to compile with version 7.x, GCC 7.3 is also provided.
17You can select this version by setting the and can be selected by
18setting the :term:`GCCVERSION` variable to "7.%" in
19your configuration.
20
21.. _migration-2.6-removed-recipes:
22
23Removed Recipes
24---------------
25
26The following recipes have been removed:
27
28- *beecrypt*: No longer needed since moving to RPM 4.
29- *bigreqsproto*: Replaced by ``xorgproto``.
30- *calibrateproto*: Removed in favor of ``xinput``.
31- *compositeproto*: Replaced by ``xorgproto``.
32- *damageproto*: Replaced by ``xorgproto``.
33- *dmxproto*: Replaced by ``xorgproto``.
34- *dri2proto*: Replaced by ``xorgproto``.
35- *dri3proto*: Replaced by ``xorgproto``.
36- *eee-acpi-scripts*: Became obsolete.
37- *fixesproto*: Replaced by ``xorgproto``.
38- *fontsproto*: Replaced by ``xorgproto``.
39- *fstests*: Became obsolete.
40- *gccmakedep*: No longer used.
41- *glproto*: Replaced by ``xorgproto``.
42- *gnome-desktop3*: No longer needed. This recipe has moved to ``meta-oe``.
43- *icon-naming-utils*: No longer used since the Sato theme was removed in 2016.
44- *inputproto*: Replaced by ``xorgproto``.
45- *kbproto*: Replaced by ``xorgproto``.
46- *libusb-compat*: Became obsolete.
47- *libuser*: Became obsolete.
48- *libnfsidmap*: No longer an external requirement since ``nfs-utils`` 2.2.1. ``libnfsidmap`` is now integrated.
49- *libxcalibrate*: No longer needed with ``xinput``
50- *mktemp*: Became obsolete. The ``mktemp`` command is provided by both ``busybox`` and ``coreutils``.
51- *ossp-uuid*: Is not being maintained and has mostly been replaced by ``uuid.h`` in ``util-linux``.
52- *pax-utils*: No longer needed. Previous QA tests that did use this recipe are now done at build time.
53- *pcmciautils*: Became obsolete.
54- *pixz*: No longer needed. ``xz`` now supports multi-threaded compression.
55- *presentproto*: Replaced by ``xorgproto``.
56- *randrproto*: Replaced by ``xorgproto``.
57- *recordproto*: Replaced by ``xorgproto``.
58- *renderproto*: Replaced by ``xorgproto``.
59- *resourceproto*: Replaced by ``xorgproto``.
60- *scrnsaverproto*: Replaced by ``xorgproto``.
61- *trace-cmd*: Became obsolete. ``perf`` replaced this recipe's functionally.
62- *videoproto*: Replaced by ``xorgproto``.
63- *wireless-tools*: Became obsolete. Superseded by ``iw``.
64- *xcmiscproto*: Replaced by ``xorgproto``.
65- *xextproto*: Replaced by ``xorgproto``.
66- *xf86dgaproto*: Replaced by ``xorgproto``.
67- *xf86driproto*: Replaced by ``xorgproto``.
68- *xf86miscproto*: Replaced by ``xorgproto``.
69- *xf86-video-omapfb*: Became obsolete. Use kernel modesetting driver instead.
70- *xf86-video-omap*: Became obsolete. Use kernel modesetting driver instead.
71- *xf86vidmodeproto*: Replaced by ``xorgproto``.
72- *xineramaproto*: Replaced by ``xorgproto``.
73- *xproto*: Replaced by ``xorgproto``.
74- *yasm*: No longer needed since previous usages are now satisfied by ``nasm``.
75
76.. _migration-2.6-packaging-changes:
77
78Packaging Changes
79-----------------
80
81The following packaging changes have been made:
82
83- *cmake*: ``cmake.m4`` and ``toolchain`` files have been moved to
84 the main package.
85
86- *iptables*: The ``iptables`` modules have been split into
87 separate packages.
88
89- *alsa-lib*: ``libasound`` is now in the main ``alsa-lib`` package
90 instead of ``libasound``.
91
92- *glibc*: ``libnss-db`` is now in its own package along with a
93 ``/var/db/makedbs.sh`` script to update databases.
94
95- *python and python3*: The main package has been removed from
96 the recipe. You must install specific packages or ``python-modules``
97 / ``python3-modules`` for everything.
98
99- *systemtap*: Moved ``systemtap-exporter`` into its own package.
100
101.. _migration-2.6-xorg-protocol-dependencies:
102
103XOrg Protocol dependencies
104--------------------------
105
106The ``*proto`` upstream repositories have been combined into one
107"xorgproto" repository. Thus, the corresponding recipes have also been
108combined into a single ``xorgproto`` recipe. Any recipes that depend
109upon the older ``*proto`` recipes need to be changed to depend on the
110newer ``xorgproto`` recipe instead.
111
112For names of recipes removed because of this repository change, see the
113`Removed Recipes <#migration-2.6-removed-recipes>`__ section.
114
115.. _migration-2.6-distutils-distutils3-fetching-dependencies:
116
117``distutils`` and ``distutils3`` Now Prevent Fetching Dependencies During the ``do_configure`` Task
118---------------------------------------------------------------------------------------------------
119
120Previously, it was possible for Python recipes that inherited the
121:ref:`distutils <ref-classes-distutils>` and
122:ref:`distutils3 <ref-classes-distutils3>` classes to fetch code
123during the :ref:`ref-tasks-configure` task to satisfy
124dependencies mentioned in ``setup.py`` if those dependencies were not
125provided in the sysroot (i.e. recipes providing the dependencies were
126missing from :term:`DEPENDS`).
127
128.. note::
129
130 This change affects classes beyond just the two mentioned (i.e.
131 distutils
132 and
133 distutils3
134 ). Any recipe that inherits
135 distutils\*
136 classes are affected. For example, the
137 setuptools
138 and
139 setuptools3
140 recipes are affected since they inherit the
141 distutils\*
142 classes.
143
144Fetching these types of dependencies that are not provided in the
145sysroot negatively affects the ability to reproduce builds. This type of
146fetching is now explicitly disabled. Consequently, any missing
147dependencies in Python recipes that use these classes now result in an
148error during the ``do_configure`` task.
149
150.. _migration-2.6-linux-yocto-configuration-audit-issues-now-correctly-reported:
151
152``linux-yocto`` Configuration Audit Issues Now Correctly Reported
153-----------------------------------------------------------------
154
155Due to a bug, the kernel configuration audit functionality was not
156writing out any resulting warnings during the build. This issue is now
157corrected. You might notice these warnings now if you have a custom
158kernel configuration with a ``linux-yocto`` style kernel recipe.
159
160.. _migration-2.6-image-kernel-artifact-naming-changes:
161
162Image/Kernel Artifact Naming Changes
163------------------------------------
164
165The following changes have been made:
166
167- Name variables (e.g. :term:`IMAGE_NAME`) use a new
168 ``IMAGE_VERSION_SUFFIX`` variable instead of
169 :term:`DATETIME`. Using ``IMAGE_VERSION_SUFFIX``
170 allows easier and more direct changes.
171
172 The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf``
173 configuration file as follows:
174 ::
175
176 IMAGE_VERSION_SUFFIX = "-${DATETIME}"
177
178- Several variables have changed names for consistency:
179 ::
180
181 Old Variable Name New Variable Name
182 ========================================================
183 KERNEL_IMAGE_BASE_NAME :term:`KERNEL_IMAGE_NAME`
184 KERNEL_IMAGE_SYMLINK_NAME :term:`KERNEL_IMAGE_LINK_NAME`
185 MODULE_TARBALL_BASE_NAME :term:`MODULE_TARBALL_NAME`
186 MODULE_TARBALL_SYMLINK_NAME :term:`MODULE_TARBALL_LINK_NAME`
187 INITRAMFS_BASE_NAME :term:`INITRAMFS_NAME`
188
189- The ``MODULE_IMAGE_BASE_NAME`` variable has been removed. The module
190 tarball name is now controlled directly with the
191 :term:`MODULE_TARBALL_NAME` variable.
192
193- The :term:`KERNEL_DTB_NAME` and
194 :term:`KERNEL_DTB_LINK_NAME` variables
195 have been introduced to control kernel Device Tree Binary (DTB)
196 artifact names instead of mangling ``KERNEL_IMAGE_*`` variables.
197
198- The :term:`KERNEL_FIT_NAME` and
199 :term:`KERNEL_FIT_LINK_NAME` variables
200 have been introduced to specify the name of flattened image tree
201 (FIT) kernel images similar to other deployed artifacts.
202
203- The :term:`MODULE_TARBALL_NAME` and
204 :term:`MODULE_TARBALL_LINK_NAME`
205 variable values no longer include the "module-" prefix or ".tgz"
206 suffix. These parts are now hardcoded so that the values are
207 consistent with other artifact naming variables.
208
209- Added the :term:`INITRAMFS_LINK_NAME`
210 variable so that the symlink can be controlled similarly to other
211 artifact types.
212
213- :term:`INITRAMFS_NAME` now uses
214 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" instead
215 of "${PV}-${PR}-${MACHINE}-${DATETIME}", which makes it consistent
216 with other variables.
217
218.. _migration-2.6-serial-console-deprecated:
219
220``SERIAL_CONSOLE`` Deprecated
221-----------------------------
222
223The :term:`SERIAL_CONSOLE` variable has been
224functionally replaced by the
225:term:`SERIAL_CONSOLES` variable for some time.
226With the Yocto Project 2.6 release, ``SERIAL_CONSOLE`` has been
227officially deprecated.
228
229``SERIAL_CONSOLE`` will continue to work as before for the 2.6 release.
230However, for the sake of future compatibility, it is recommended that
231you replace all instances of ``SERIAL_CONSOLE`` with
232``SERIAL_CONSOLES``.
233
234.. note::
235
236 The only difference in usage is that
237 SERIAL_CONSOLES
238 expects entries to be separated using semicolons as compared to
239 SERIAL_CONSOLE
240 , which expects spaces.
241
242.. _migration-2.6-poky-sets-unknown-configure-option-to-qa-error:
243
244Configure Script Reports Unknown Options as Errors
245--------------------------------------------------
246
247If the configure script reports an unknown option, this now triggers a
248QA error instead of a warning. Any recipes that previously got away with
249specifying such unknown options now need to be fixed.
250
251.. _migration-2.6-override-changes:
252
253Override Changes
254----------------
255
256The following changes have occurred:
257
258- The ``virtclass-native`` and ``virtclass-nativesdk`` Overrides Have
259 Been Removed: The ``virtclass-native`` and ``virtclass-nativesdk``
260 overrides have been deprecated since 2012 in favor of
261 ``class-native`` and ``class-nativesdk``, respectively. Both
262 ``virtclass-native`` and ``virtclass-nativesdk`` are now dropped.
263
264 .. note::
265
266 The
267 virtclass-multilib-
268 overrides for multilib are still valid.
269
270- The ``forcevariable`` Override Now Has a Higher Priority Than
271 ``libc`` Overrides: The ``forcevariable`` override is documented to
272 be the highest priority override. However, due to a long-standing
273 quirk of how :term:`OVERRIDES` is set, the ``libc``
274 overrides (e.g. ``libc-glibc``, ``libc-musl``, and so forth)
275 erroneously had a higher priority. This issue is now corrected.
276
277 It is likely this change will not cause any problems. However, it is
278 possible with some unusual configurations that you might see a change
279 in behavior if you were relying on the previous behavior. Be sure to
280 check how you use ``forcevariable`` and ``libc-*`` overrides in your
281 custom layers and configuration files to ensure they make sense.
282
283- The ``build-${BUILD_OS}`` Override Has Been Removed: The
284 ``build-${BUILD_OS}``, which is typically ``build-linux``, override
285 has been removed because building on a host operating system other
286 than a recent version of Linux is neither supported nor recommended.
287 Dropping the override avoids giving the impression that other host
288 operating systems might be supported.
289
290- The "_remove" operator now preserves whitespace. Consequently, when
291 specifying list items to remove, be aware that leading and trailing
292 whitespace resulting from the removal is retained.
293
294 See the ":ref:`bitbake:removing-override-style-syntax`"
295 section in the BitBake User Manual for a detailed example.
296
297.. _migration-2.6-systemd-configuration-now-split-out-to-system-conf:
298
299``systemd`` Configuration is Now Split Into ``systemd-conf``
300------------------------------------------------------------
301
302The configuration for the ``systemd`` recipe has been moved into a
303``system-conf`` recipe. Moving this configuration to a separate recipe
304avoids the ``systemd`` recipe from becoming machine-specific for cases
305where machine-specific configurations need to be applied (e.g. for
306``qemu*`` machines).
307
308Currently, the new recipe packages the following files:
309::
310
311 ${sysconfdir}/machine-id
312 ${sysconfdir}/systemd/coredump.conf
313 ${sysconfdir}/systemd/journald.conf
314 ${sysconfdir}/systemd/logind.conf
315 ${sysconfdir}/systemd/system.conf
316 ${sysconfdir}/systemd/user.conf
317
318If you previously used bbappend files to append the ``systemd`` recipe to
319change any of the listed files, you must do so for the ``systemd-conf``
320recipe instead.
321
322.. _migration-2.6-automatic-testing-changes:
323
324Automatic Testing Changes
325-------------------------
326
327This section provides information about automatic testing changes:
328
329- ``TEST_IMAGE`` Variable Removed: Prior to this release, you set the
330 ``TEST_IMAGE`` variable to "1" to enable automatic testing for
331 successfully built images. The ``TEST_IMAGE`` variable no longer
332 exists and has been replaced by the
333 :term:`TESTIMAGE_AUTO` variable.
334
335- Inheriting the ``testimage`` and ``testsdk`` Classes: Best
336 practices now dictate that you use the
337 :term:`IMAGE_CLASSES` variable rather than the
338 :term:`INHERIT` variable when you inherit the
339 :ref:`testimage <ref-classes-testimage*>` and
340 :ref:`testsdk <ref-classes-testsdk>` classes used for automatic
341 testing.
342
343.. _migration-2.6-openssl-changes:
344
345OpenSSL Changes
346---------------
347
348`OpenSSL <https://www.openssl.org/>`__ has been upgraded from 1.0 to
3491.1. By default, this upgrade could cause problems for recipes that have
350both versions in their dependency chains. The problem is that both
351versions cannot be installed together at build time.
352
353.. note::
354
355 It is possible to have both versions of the library at runtime.
356
357.. _migration-2.6-bitbake-changes:
358
359BitBake Changes
360---------------
361
362The server logfile ``bitbake-cookerdaemon.log`` is now always placed in
363the :term:`Build Directory` instead of the current
364directory.
365
366.. _migration-2.6-security-changes:
367
368Security Changes
369----------------
370
371The Poky distribution now uses security compiler flags by default.
372Inclusion of these flags could cause new failures due to stricter
373checking for various potential security issues in code.
374
375.. _migration-2.6-post-installation-changes:
376
377Post Installation Changes
378-------------------------
379
380You must explicitly mark post installs to defer to the target. If you
381want to explicitly defer a postinstall to first boot on the target
382rather than at rootfs creation time, use ``pkg_postinst_ontarget()`` or
383call ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``.
384Any failure of a ``pkg_postinst()`` script (including exit 1) triggers
385an error during the :ref:`ref-tasks-rootfs` task.
386
387For more information on post-installation behavior, see the
388":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`"
389section in the Yocto Project Development Tasks Manual.
390
391.. _migration-2.6-python-3-profile-guided-optimizations:
392
393Python 3 Profile-Guided Optimization
394------------------------------------
395
396The ``python3`` recipe now enables profile-guided optimization. Using
397this optimization requires a little extra build time in exchange for
398improved performance on the target at runtime. Additionally, the
399optimization is only enabled if the current
400:term:`MACHINE` has support for user-mode emulation in
401QEMU (i.e. "qemu-usermode" is in
402:term:`MACHINE_FEATURES`, which it is by
403default).
404
405If you wish to disable Python profile-guided optimization regardless of
406the value of ``MACHINE_FEATURES``, then ensure that
407:term:`PACKAGECONFIG` for the ``python3`` recipe
408does not contain "pgo". You could accomplish the latter using the
409following at the configuration level:
410::
411
412 PACKAGECONFIG_remove_pn-python3 = "pgo"
413
414Alternatively, you can set ``PACKAGECONFIG`` using an append file
415for the ``python3`` recipe.
416
417.. _migration-2.6-miscellaneous-changes:
418
419Miscellaneous Changes
420---------------------
421
422The following miscellaneous changes occurred:
423
424- Default to using the Thumb-2 instruction set for armv7a and above. If
425 you have any custom recipes that build software that needs to be
426 built with the ARM instruction set, change the recipe to set the
427 instruction set as follows:
428 ::
429
430 ARM_INSTRUCTION_SET = "arm"
431
432- ``run-postinsts`` no longer uses ``/etc/*-postinsts`` for
433 ``dpkg/opkg`` in favor of built-in postinst support. RPM behavior
434 remains unchanged.
435
436- The ``NOISO`` and ``NOHDD`` variables are no longer used. You now
437 control building ``*.iso`` and ``*.hddimg`` image types directly by
438 using the :term:`IMAGE_FSTYPES` variable.
439
440- The ``scripts/contrib/mkefidisk.sh`` has been removed in favor of
441 Wic.
442
443- ``kernel-modules`` has been removed from
444 :term:`RRECOMMENDS` for ``qemumips`` and
445 ``qemumips64`` machines. Removal also impacts the ``x86-base.inc``
446 file.
447
448 .. note::
449
450 genericx86
451 and
452 genericx86-64
453 retain
454 kernel-modules
455 as part of the
456 RRECOMMENDS
457 variable setting.
458
459- The ``LGPLv2_WHITELIST_GPL-3.0`` variable has been removed. If you
460 are setting this variable in your configuration, set or append it to
461 the ``WHITELIST_GPL-3.0`` variable instead.
462
463- ``${ASNEEDED}`` is now included in the
464 :term:`TARGET_LDFLAGS` variable directly. The
465 remaining definitions from ``meta/conf/distro/include/as-needed.inc``
466 have been moved to corresponding recipes.
467
468- Support for DSA host keys has been dropped from the OpenSSH recipes.
469 If you are still using DSA keys, you must switch over to a more
470 secure algorithm as recommended by OpenSSH upstream.
471
472- The ``dhcp`` recipe now uses the ``dhcpd6.conf`` configuration file
473 in ``dhcpd6.service`` for IPv6 DHCP rather than re-using
474 ``dhcpd.conf``, which is now reserved for IPv4.
475
476
diff --git a/documentation/ref-manual/migration-2.7.rst b/documentation/ref-manual/migration-2.7.rst
new file mode 100644
index 0000000000..7e628fc3ec
--- /dev/null
+++ b/documentation/ref-manual/migration-2.7.rst
@@ -0,0 +1,180 @@
1Moving to the Yocto Project 2.7 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.7 Release from the prior release.
6
7.. _migration-2.7-bitbake-changes:
8
9BitBake Changes
10---------------
11
12The following changes have been made to BitBake:
13
14- BitBake now checks anonymous Python functions and pure Python
15 functions (e.g. ``def funcname:``) in the metadata for tab
16 indentation. If found, BitBake produces a warning.
17
18- Bitbake now checks
19 :term:`BBFILE_COLLECTIONS` for duplicate
20 entries and triggers an error if any are found.
21
22.. _migration-2.7-eclipse-support-dropped:
23
24Eclipse Support Removed
25-----------------------
26
27Support for the Eclipse IDE has been removed. Support continues for
28those releases prior to 2.7 that did include support. The 2.7 release
29does not include the Eclipse Yocto plugin.
30
31.. _migration-2.7-qemu-native-splits-system-and-user-mode-parts:
32
33``qemu-native`` Splits the System and User-Mode Parts
34-----------------------------------------------------
35
36The system and user-mode parts of ``qemu-native`` are now split.
37``qemu-native`` provides the user-mode components and
38``qemu-system-native`` provides the system components. If you have
39recipes that depend on QEMU's system emulation functionality at build
40time, they should now depend upon ``qemu-system-native`` instead of
41``qemu-native``.
42
43.. _migration-2.7-upstream-tracking.inc-removed:
44
45The ``upstream-tracking.inc`` File Has Been Removed
46---------------------------------------------------
47
48The previously deprecated ``upstream-tracking.inc`` file is now removed.
49Any ``UPSTREAM_TRACKING*`` variables are now set in the corresponding
50recipes instead.
51
52Remove any references you have to the ``upstream-tracking.inc`` file in
53your configuration.
54
55.. _migration-2.7-distro-features-libc-removed:
56
57The ``DISTRO_FEATURES_LIBC`` Variable Has Been Removed
58------------------------------------------------------
59
60The ``DISTRO_FEATURES_LIBC`` variable is no longer used. The ability to
61configure glibc using kconfig has been removed for quite some time
62making the ``libc-*`` features set no longer effective.
63
64Remove any references you have to ``DISTRO_FEATURES_LIBC`` in your own
65layers.
66
67.. _migration-2.7-license-values:
68
69License Value Corrections
70-------------------------
71
72The following corrections have been made to the
73:term:`LICENSE` values set by recipes:
74
75- *socat*: Corrected ``LICENSE`` to be "GPLv2" rather than "GPLv2+".
76- *libgfortran*: Set license to "GPL-3.0-with-GCC-exception".
77- *elfutils*: Removed "Elfutils-Exception" and set to "GPLv2" for shared libraries
78
79.. _migration-2.7-packaging-changes:
80
81Packaging Changes
82-----------------
83
84This section provides information about packaging changes.
85
86- ``bind``: The ``nsupdate`` binary has been moved to the
87 ``bind-utils`` package.
88
89- Debug split: The default debug split has been changed to create
90 separate source packages (i.e. package_name\ ``-dbg`` and
91 package_name\ ``-src``). If you are currently using ``dbg-pkgs`` in
92 :term:`IMAGE_FEATURES` to bring in debug
93 symbols and you still need the sources, you must now also add
94 ``src-pkgs`` to ``IMAGE_FEATURES``. Source packages remain in the
95 target portion of the SDK by default, unless you have set your own
96 value for :term:`SDKIMAGE_FEATURES` that
97 does not include ``src-pkgs``.
98
99- Mount all using ``util-linux``: ``/etc/default/mountall`` has moved
100 into the -mount sub-package.
101
102- Splitting binaries using ``util-linux``: ``util-linux`` now splits
103 each binary into its own package for fine-grained control. The main
104 ``util-linux`` package pulls in the individual binary packages using
105 the :term:`RRECOMMENDS` and
106 :term:`RDEPENDS` variables. As a result, existing
107 images should not see any changes assuming
108 :term:`NO_RECOMMENDATIONS` is not set.
109
110- ``netbase/base-files``: ``/etc/hosts`` has moved from ``netbase`` to
111 ``base-files``.
112
113- ``tzdata``: The main package has been converted to an empty meta
114 package that pulls in all ``tzdata`` packages by default.
115
116- ``lrzsz``: This package has been removed from
117 ``packagegroup-self-hosted`` and
118 ``packagegroup-core-tools-testapps``. The X/Y/ZModem support is less
119 likely to be needed on modern systems. If you are relying on these
120 packagegroups to include the ``lrzsz`` package in your image, you now
121 need to explicitly add the package.
122
123.. _migration-2.7-removed-recipes:
124
125Removed Recipes
126---------------
127
128The following recipes have been removed:
129
130- *gcc*: Drop version 7.3 recipes. Version 8.3 now remains.
131- *linux-yocto*: Drop versions 4.14 and 4.18 recipes. Versions 4.19 and 5.0 remain.
132- *go*: Drop version 1.9 recipes. Versions 1.11 and 1.12 remain.
133- *xvideo-tests*: Became obsolete.
134- *libart-lgpl*: Became obsolete.
135- *gtk-icon-utils-native*: These tools are now provided by gtk+3-native
136- *gcc-cross-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
137- *gcc-crosssdk-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
138- *glibc-initial*: Removed because the benefits of having it for site_config are currently outweighed by the cost of building the recipe.
139
140.. _migration-2.7-removed-classes:
141
142Removed Classes
143---------------
144
145The following classes have been removed:
146
147- *distutils-tools*: This class was never used.
148- *bugzilla.bbclass*: Became obsolete.
149- *distrodata*: This functionally has been replaced by a more modern tinfoil-based implementation.
150
151.. _migration-2.7-miscellaneous-changes:
152
153Miscellaneous Changes
154---------------------
155
156The following miscellaneous changes occurred:
157
158- The ``distro`` subdirectory of the Poky repository has been removed
159 from the top-level ``scripts`` directory.
160
161- Perl now builds for the target using
162 `perl-cross <http://arsv.github.io/perl-cross/>`_ for better
163 maintainability and improved build performance. This change should
164 not present any problems unless you have heavily customized your Perl
165 recipe.
166
167- ``arm-tunes``: Removed the "-march" option if mcpu is already added.
168
169- ``update-alternatives``: Convert file renames to
170 :term:`PACKAGE_PREPROCESS_FUNCS`
171
172- ``base/pixbufcache``: Obsolete ``sstatecompletions`` code has been
173 removed.
174
175- :ref:`native <ref-classes-native>` class:
176 :term:`RDEPENDS` handling has been enabled.
177
178- ``inetutils``: This recipe has rsh disabled.
179
180
diff --git a/documentation/ref-manual/migration-3.0.rst b/documentation/ref-manual/migration-3.0.rst
new file mode 100644
index 0000000000..e1305dfccf
--- /dev/null
+++ b/documentation/ref-manual/migration-3.0.rst
@@ -0,0 +1,321 @@
1Moving to the Yocto Project 3.0 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 3.0 Release from the prior release.
6
7.. _migration-3.0-init-system-selection:
8
9Init System Selection
10---------------------
11
12Changing the init system manager previously required setting a number of
13different variables. You can now change the manager by setting the
14``INIT_MANAGER`` variable and the corresponding include files (i.e.
15``conf/distro/include/init-manager-*.conf``). Include files are provided
16for four values: "none", "sysvinit", "systemd", and "mdev-busybox". The
17default value, "none", for ``INIT_MANAGER`` should allow your current
18settings to continue working. However, it is advisable to explicitly set
19``INIT_MANAGER``.
20
21.. _migration-3.0-lsb-support-removed:
22
23LSB Support Removed
24-------------------
25
26Linux Standard Base (LSB) as a standard is not current, and is not well
27suited for embedded applications. Support can be continued in a separate
28layer if needed. However, presently LSB support has been removed from
29the core.
30
31As a result of this change, the ``poky-lsb`` derivative distribution
32configuration that was also used for testing alternative configurations
33has been replaced with a ``poky-altcfg`` distribution that has LSB parts
34removed.
35
36.. _migration-3.0-removed-recipes:
37
38Removed Recipes
39---------------
40
41The following recipes have been removed.
42
43- ``core-image-lsb-dev``: Part of removed LSB support.
44
45- ``core-image-lsb``: Part of removed LSB support.
46
47- ``core-image-lsb-sdk``: Part of removed LSB support.
48
49- ``cve-check-tool``: Functionally replaced by the ``cve-update-db``
50 recipe and ``cve-check`` class.
51
52- ``eglinfo``: No longer maintained. ``eglinfo`` from ``mesa-demos`` is
53 an adequate and maintained alternative.
54
55- ``gcc-8.3``: Version 8.3 removed. Replaced by 9.2.
56
57- ``gnome-themes-standard``: Only needed by gtk+ 2.x, which has been
58 removed.
59
60- ``gtk+``: GTK+ 2 is obsolete and has been replaced by gtk+3.
61
62- ``irda-utils``: Has become obsolete. IrDA support has been removed
63 from the Linux kernel in version 4.17 and later.
64
65- ``libnewt-python``: ``libnewt`` Python support merged into main
66 ``libnewt`` recipe.
67
68- ``libsdl``: Replaced by newer ``libsdl2``.
69
70- ``libx11-diet``: Became obsolete.
71
72- ``libxx86dga``: Removed obsolete client library.
73
74- ``libxx86misc``: Removed. Library is redundant.
75
76- ``linux-yocto``: Version 5.0 removed, which is now redundant (5.2 /
77 4.19 present).
78
79- ``lsbinitscripts``: Part of removed LSB support.
80
81- ``lsb``: Part of removed LSB support.
82
83- ``lsbtest``: Part of removed LSB support.
84
85- ``openssl10``: Replaced by newer ``openssl`` version 1.1.
86
87- ``packagegroup-core-lsb``: Part of removed LSB support.
88
89- ``python-nose``: Removed the Python 2.x version of the recipe.
90
91- ``python-numpy``: Removed the Python 2.x version of the recipe.
92
93- ``python-scons``: Removed the Python 2.x version of the recipe.
94
95- ``source-highlight``: No longer needed.
96
97- ``stress``: Replaced by ``stress-ng``.
98
99- ``vulkan``: Split into ``vulkan-loader``, ``vulkan-headers``, and
100 ``vulkan-tools``.
101
102- ``weston-conf``: Functionality moved to ``weston-init``.
103
104.. _migration-3.0-packaging-changes:
105
106Packaging Changes
107-----------------
108
109The following packaging changes have occurred.
110
111- The `Epiphany <https://en.wikipedia.org/wiki/GNOME_Web>`__ browser
112 has been dropped from ``packagegroup-self-hosted`` as it has not been
113 needed inside ``build-appliance-image`` for quite some time and was
114 causing resource problems.
115
116- ``libcap-ng`` Python support has been moved to a separate
117 ``libcap-ng-python`` recipe to streamline the build process when the
118 Python bindings are not needed.
119
120- ``libdrm`` now packages the file ``amdgpu.ids`` into a separate
121 ``libdrm-amdgpu`` package.
122
123- ``python3``: The ``runpy`` module is now in the ``python3-core``
124 package as it is required to support the common "python3 -m" command
125 usage.
126
127- ``distcc`` now provides separate ``distcc-client`` and
128 ``distcc-server`` packages as typically one or the other are needed,
129 rather than both.
130
131- ``python*-setuptools`` recipes now separately package the
132 ``pkg_resources`` module in a ``python-pkg-resources`` /
133 ``python3-pkg-resources`` package as the module is useful independent
134 of the rest of the setuptools package. The main ``python-setuptools``
135 / ``python3-setuptools`` package depends on this new package so you
136 should only need to update dependencies unless you want to take
137 advantage of the increased granularity.
138
139.. _migration-3.0-cve-checking:
140
141CVE Checking
142------------
143
144``cve-check-tool`` has been functionally replaced by a new
145``cve-update-db`` recipe and functionality built into the ``cve-check``
146class. The result uses NVD JSON data feeds rather than the deprecated
147XML feeds that ``cve-check-tool`` was using, supports CVSSv3 scoring,
148and makes other improvements.
149
150Additionally, the ``CVE_CHECK_CVE_WHITELIST`` variable has been replaced
151by ``CVE_CHECK_WHITELIST``.
152
153.. _migration-3.0-bitbake-changes:
154
155Bitbake Changes
156---------------
157
158The following BitBake changes have occurred.
159
160- ``addtask`` statements now properly validate dependent tasks.
161 Previously, an invalid task was silently ignored. With this change,
162 the invalid task generates a warning.
163
164- Other invalid ``addtask`` and ``deltask`` usages now trigger these
165 warnings: "multiple target tasks arguments with addtask / deltask",
166 and "multiple before/after clauses".
167
168- The "multiconfig" prefix is now shortened to "mc". "multiconfig" will
169 continue to work, however it may be removed in a future release.
170
171- The ``bitbake -g`` command no longer generates a
172 ``recipe-depends.dot`` file as the contents (i.e. a reprocessed
173 version of ``task-depends.dot``) were confusing.
174
175- The ``bb.build.FuncFailed`` exception, previously raised by
176 ``bb.build.exec_func()`` when certain other exceptions have occurred,
177 has been removed. The real underlying exceptions will be raised
178 instead. If you have calls to ``bb.build.exec_func()`` in custom
179 classes or ``tinfoil-using`` scripts, any references to
180 ``bb.build.FuncFailed`` should be cleaned up.
181
182- Additionally, the ``bb.build.exec_func()`` no longer accepts the
183 "pythonexception" parameter. The function now always raises
184 exceptions. Remove this argument in any calls to
185 ``bb.build.exec_func()`` in custom classes or scripts.
186
187- The
188 :term:`bitbake:BB_SETSCENE_VERIFY_FUNCTION2`
189 is no longer used. In the unlikely event that you have any references
190 to it, they should be removed.
191
192- The ``RunQueueExecuteScenequeue`` and ``RunQueueExecuteTasks`` events
193 have been removed since setscene tasks are now executed as part of
194 the normal runqueue. Any event handling code in custom classes or
195 scripts that handles these two events need to be updated.
196
197- The arguments passed to functions used with
198 :term:`bitbake:BB_HASHCHECK_FUNCTION`
199 have changed. If you are using your own custom hash check function,
200 see
201 http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725
202 for details.
203
204- Task specifications in ``BB_TASKDEPDATA`` and class implementations
205 used in signature generator classes now use "<fn>:<task>" everywhere
206 rather than the "." delimiter that was being used in some places.
207 This change makes it consistent with all areas in the code. Custom
208 signature generator classes and code that reads ``BB_TASKDEPDATA``
209 need to be updated to use ':' as a separator rather than '.'.
210
211.. _migration-3.0-sanity-checks:
212
213Sanity Checks
214-------------
215
216The following sanity check changes occurred.
217
218- :term:`SRC_URI` is now checked for usage of two
219 problematic items:
220
221 - "${PN}" prefix/suffix use - Warnings always appear if ${PN} is
222 used. You must fix the issue regardless of whether multiconfig or
223 anything else that would cause prefixing/suffixing to happen.
224
225 - Github archive tarballs - these are not guaranteed to be stable.
226 Consequently, it is likely that the tarballs will be refreshed and
227 thus the SRC_URI checksums will fail to apply. It is recommended
228 that you fetch either an official release tarball or a specific
229 revision from the actual Git repository instead.
230
231 Either one of these items now trigger a warning by default. If you
232 wish to disable this check, remove ``src-uri-bad`` from
233 :term:`WARN_QA`.
234
235- The ``file-rdeps`` runtime dependency check no longer expands
236 :term:`RDEPENDS` recursively as there is no mechanism
237 to ensure they can be fully computed, and thus races sometimes result
238 in errors either showing up or not. Thus, you might now see errors
239 for missing runtime dependencies that were previously satisfied
240 recursively. Here is an example: package A contains a shell script
241 starting with ``#!/bin/bash`` but has no dependency on bash. However,
242 package A depends on package B, which does depend on bash. You need
243 to add the missing dependency or dependencies to resolve the warning.
244
245- Setting ``DEPENDS_${PN}`` anywhere (i.e. typically in a recipe) now
246 triggers an error. The error is triggered because
247 :term:`DEPENDS` is not a package-specific variable
248 unlike RDEPENDS. You should set ``DEPENDS`` instead.
249
250- systemd currently does not work well with the musl C library because
251 only upstream officially supports linking the library with glibc.
252 Thus, a warning is shown when building systemd in conjunction with
253 musl.
254
255.. _migration-3.0-miscellaneous-changes:
256
257Miscellaneous Changes
258---------------------
259
260The following miscellaneous changes have occurred.
261
262- The ``gnome`` class has been removed because it now does very little.
263 You should update recipes that previously inherited this class to do
264 the following: inherit gnomebase gtk-icon-cache gconf mime
265
266- The ``meta/recipes-kernel/linux/linux-dtb.inc`` file has been
267 removed. This file was previously deprecated in favor of setting
268 :term:`KERNEL_DEVICETREE` in any kernel
269 recipe and only produced a warning. Remove any ``include`` or
270 ``require`` statements pointing to this file.
271
272- :term:`TARGET_CFLAGS`,
273 :term:`TARGET_CPPFLAGS`,
274 :term:`TARGET_CXXFLAGS`, and
275 :term:`TARGET_LDFLAGS` are no longer exported
276 to the external environment. This change did not require any changes
277 to core recipes, which is a good indicator that no changes will be
278 required. However, if for some reason the software being built by one
279 of your recipes is expecting these variables to be set, then building
280 the recipe will fail. In such cases, you must either export the
281 variable or variables in the recipe or change the scripts so that
282 exporting is not necessary.
283
284- You must change the host distro identifier used in
285 :term:`NATIVELSBSTRING` to use all lowercase
286 characters even if it does not contain a version number. This change
287 is necessary only if you are not using ``uninative`` and
288 :term:`SANITY_TESTED_DISTROS`.
289
290- In the ``base-files`` recipe, writing the hostname into
291 ``/etc/hosts`` and ``/etc/hostname`` is now done within the main
292 :ref:`ref-tasks-install` function rather than in the
293 ``do_install_basefilesissue`` function. The reason for the change is
294 because ``do_install_basefilesissue`` is more easily overridden
295 without having to duplicate the hostname functionality. If you have
296 done the latter (e.g. in a ``base-files`` bbappend), then you should
297 remove it from your customized ``do_install_basefilesissue``
298 function.
299
300- The ``wic --expand`` command now uses commas to separate "key:value"
301 pairs rather than hyphens.
302
303 .. note::
304
305 The wic command-line help is not updated.
306
307 You must update any scripts or commands where you use
308 ``wic --expand`` with multiple "key:value" pairs.
309
310- UEFI image variable settings have been moved from various places to a
311 central ``conf/image-uefi.conf``. This change should not influence
312 any existing configuration as the ``meta/conf/image-uefi.conf`` in
313 the core metadata sets defaults that can be overridden in the same
314 manner as before.
315
316- ``conf/distro/include/world-broken.inc`` has been removed. For cases
317 where certain recipes need to be disabled when using the musl C
318 library, these recipes now have ``COMPATIBLE_HOST_libc-musl`` set
319 with a comment that explains why.
320
321
diff --git a/documentation/ref-manual/migration-3.1.rst b/documentation/ref-manual/migration-3.1.rst
new file mode 100644
index 0000000000..92c8c77613
--- /dev/null
+++ b/documentation/ref-manual/migration-3.1.rst
@@ -0,0 +1,276 @@
1Moving to the Yocto Project 3.1 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 3.1 Release from the prior release.
6
7.. _migration-3.1-minimum-system-requirements:
8
9Minimum system requirements
10---------------------------
11
12The following versions / requirements of build host components have been
13updated:
14
15- gcc 5.0
16
17- python 3.5
18
19- tar 1.28
20
21- ``rpcgen`` is now required on the host (part of the ``libc-dev-bin``
22 package on Ubuntu, Debian and related distributions, and the
23 ``glibc`` package on RPM-based distributions).
24
25Additionally, the ``makeinfo`` and ``pod2man`` tools are *no longer*
26required on the host.
27
28.. _migration-3.1-mpc8315e-rdb-removed:
29
30mpc8315e-rdb machine removed
31----------------------------
32
33The MPC8315E-RDB machine is old/obsolete and unobtainable, thus given
34the maintenance burden the ``mpc8315e-rdb`` machine configuration that
35supported it has been removed in this release. The removal does leave a
36gap in official PowerPC reference hardware support; this may change in
37future if a suitable machine with accompanying support resources is
38found.
39
40.. _migration-3.1-python-2-removed:
41
42Python 2 removed
43----------------
44
45Due to the expiration of upstream support in January 2020, support for
46Python 2 has now been removed; it is recommended that you use Python 3
47instead. If absolutely needed there is a meta-python2 community layer
48containing Python 2, related classes and various Python 2-based modules,
49however it should not be considered as supported.
50
51.. _migration-3.1-reproducible-builds:
52
53Reproducible builds now enabled by default
54------------------------------------------
55
56In order to avoid unnecessary differences in output files (aiding binary
57reproducibility), the Poky distribution configuration
58(``DISTRO = "poky"``) now inherits the ``reproducible_build`` class by
59default.
60
61.. _migration-3.1-ptest-feature-impact:
62
63Impact of ptest feature is now more significant
64-----------------------------------------------
65
66The Poky distribution configuration (``DISTRO = "poky"``) enables ptests
67by default to enable runtime testing of various components. In this
68release, a dependency needed to be added that has resulted in a
69significant increase in the number of components that will be built just
70when building a simple image such as core-image-minimal. If you do not
71need runtime tests enabled for core components, then it is recommended
72that you remove "ptest" from
73:term:`DISTRO_FEATURES` to save a significant
74amount of build time e.g. by adding the following in your configuration:
75::
76
77 DISTRO_FEATURES_remove = "ptest"
78
79.. _migration-3.1-removed-recipes:
80
81Removed recipes
82---------------
83
84The following recipes have been removed:
85
86- ``chkconfig``: obsolete
87
88- ``console-tools``: obsolete
89
90- ``enchant``: replaced by ``enchant2``
91
92- ``foomatic-filters``: obsolete
93
94- ``libidn``: no longer needed, moved to meta-oe
95
96- ``libmodulemd``: replaced by ``libmodulemd-v1``
97
98- ``linux-yocto``: drop 4.19, 5.2 version recipes (5.4 now provided)
99
100- ``nspr``: no longer needed, moved to meta-oe
101
102- ``nss``: no longer needed, moved to meta-oe
103
104- ``python``: Python 2 removed (Python 3 preferred)
105
106- ``python-setuptools``: Python 2 version removed (python3-setuptools
107 preferred)
108
109- ``sysprof``: no longer needed, moved to meta-oe
110
111- ``texi2html``: obsolete
112
113- ``u-boot-fw-utils``: functionally replaced by ``libubootenv``
114
115.. _migration-3.1-features-check:
116
117features_check class replaces distro_features_check
118---------------------------------------------------
119
120The ``distro_features_check`` class has had its functionality expanded,
121now supporting ``ANY_OF_MACHINE_FEATURES``,
122``REQUIRED_MACHINE_FEATURES``, ``CONFLICT_MACHINE_FEATURES``,
123``ANY_OF_COMBINED_FEATURES``, ``REQUIRED_COMBINED_FEATURES``,
124``CONFLICT_COMBINED_FEATURES``. As a result the class has now been
125renamed to ``features_check``; the ``distro_features_check`` class still
126exists but generates a warning and redirects to the new class. In
127preparation for a future removal of the old class it is recommended that
128you update recipes currently inheriting ``distro_features_check`` to
129inherit ``features_check`` instead.
130
131.. _migration-3.1-removed-classes:
132
133Removed classes
134---------------
135
136The following classes have been removed:
137
138- ``distutils-base``: moved to meta-python2
139
140- ``distutils``: moved to meta-python2
141
142- ``libc-common``: merged into the glibc recipe as nothing else used
143 it.
144
145- ``python-dir``: moved to meta-python2
146
147- ``pythonnative``: moved to meta-python2
148
149- ``setuptools``: moved to meta-python2
150
151- ``tinderclient``: dropped as it was obsolete.
152
153.. _migration-3.1-src-uri-checksums:
154
155SRC_URI checksum behaviour
156--------------------------
157
158Previously, recipes by tradition included both SHA256 and MD5 checksums
159for remotely fetched files in :term:`SRC_URI`, even
160though only one is actually mandated. However, the MD5 checksum does not
161add much given its inherent weakness; thus when a checksum fails only
162the SHA256 sum will now be printed. The md5sum will still be verified if
163it is specified.
164
165.. _migration-3.1-npm:
166
167npm fetcher changes
168-------------------
169
170The npm fetcher has been completely reworked in this release. The npm
171fetcher now only fetches the package source itself and no longer the
172dependencies; there is now also an npmsw fetcher which explicitly
173fetches the shrinkwrap file and the dependencies. This removes the
174slightly awkward ``NPM_LOCKDOWN`` and ``NPM_SHRINKWRAP`` variables which
175pointed to local files; the lockdown file is no longer needed at all.
176Additionally, the package name in ``npm://`` entries in
177:term:`SRC_URI` is now specified using a ``package``
178parameter instead of the earlier ``name`` which overlapped with the
179generic ``name`` parameter. All recipes using the npm fetcher will need
180to be changed as a result.
181
182An example of the new scheme: ::
183
184 SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \\
185 npmsw://${THISDIR}/npm-shrinkwrap.json"
186
187Another example where the sources are fetched from git rather than an npm repository: ::
188
189 SRC_URI = "git://github.com/foo/bar.git;protocol=https \
190 npmsw://${THISDIR}/npm-shrinkwrap.json"
191
192devtool and recipetool have also been updated to match with the npm
193fetcher changes. Other than producing working and more complete recipes
194for npm sources, there is also a minor change to the command line for
195devtool: the ``--fetch-dev`` option has been renamed to ``--npm-dev`` as
196it is npm-specific.
197
198.. _migration-3.1-packaging-changes:
199
200Packaging changes
201-----------------
202
203- ``intltool`` has been removed from ``packagegroup-core-sdk`` as it is
204 rarely needed to build modern software - gettext can do most of the
205 things it used to be needed for. ``intltool`` has also been removed
206 from ``packagegroup-core-self-hosted`` as it is not needed to for
207 standard builds.
208
209- git: ``git-am``, ``git-difftool``, ``git-submodule``, and
210 ``git-request-pull`` are no longer perl-based, so are now installed
211 with the main ``git`` package instead of within ``git-perltools``.
212
213- The ``ldconfig`` binary built as part of glibc has now been moved to
214 its own ``ldconfig`` package (note no ``glibc-`` prefix). This
215 package is in the :term:`RRECOMMENDS` of the main
216 ``glibc`` package if ``ldconfig`` is present in
217 :term:`DISTRO_FEATURES`.
218
219- ``libevent`` now splits each shared library into its own package (as
220 Debian does). Since these are shared libraries and will be pulled in
221 through the normal shared library dependency handling, there should
222 be no impact to existing configurations other than less unnecessary
223 libraries being installed in some cases.
224
225- linux-firmware now has a new package for ``bcm4366c`` and includes
226 available NVRAM config files into the ``bcm43340``, ``bcm43362``,
227 ``bcm43430`` and ``bcm4356-pcie`` packages.
228
229- ``harfbuzz`` now splits the new ``libharfbuzz-subset.so`` library
230 into its own package to reduce the main package size in cases where
231 ``libharfbuzz-subset.so`` is not needed.
232
233.. _migration-3.1-package-qa-warnings:
234
235Additional warnings
236-------------------
237
238Warnings will now be shown at ``do_package_qa`` time in the following
239circumstances:
240
241- A recipe installs ``.desktop`` files containing ``MimeType`` keys but
242 does not inherit the new ``mime-xdg`` class
243
244- A recipe installs ``.xml`` files into ``${datadir}/mime/packages``
245 but does not inherit the ``mime`` class
246
247.. _migration-3.1-x86-live-wic:
248
249``wic`` image type now used instead of ``live`` by default for x86
250------------------------------------------------------------------
251
252``conf/machine/include/x86-base.inc`` (inherited by most x86 machine
253configurations) now specifies ``wic`` instead of ``live`` by default in
254:term:`IMAGE_FSTYPES`. The ``live`` image type will
255likely be removed in a future release so it is recommended that you use
256``wic`` instead.
257
258.. _migration-3.1-misc:
259
260Miscellaneous changes
261---------------------
262
263- The undocumented ``SRC_DISTRIBUTE_LICENSES`` variable has now been
264 removed in favour of a new ``AVAILABLE_LICENSES`` variable which is
265 dynamically set based upon license files found in
266 ``${COMMON_LICENSE_DIR}`` and ``${LICENSE_PATH}``.
267
268- The tune definition for big-endian microblaze machines is now
269 ``microblaze`` instead of ``microblazeeb``.
270
271- ``newlib`` no longer has built-in syscalls. ``libgloss`` should then
272 provide the syscalls, ``crt0.o`` and other functions that are no
273 longer part of ``newlib`` itself. If you are using
274 ``TCLIBC = "newlib"`` this now means that you must link applications
275 with both ``newlib`` and ``libgloss``, whereas before ``newlib``
276 would run in many configurations by itself.
diff --git a/documentation/ref-manual/migration-general.rst b/documentation/ref-manual/migration-general.rst
new file mode 100644
index 0000000000..182482ec43
--- /dev/null
+++ b/documentation/ref-manual/migration-general.rst
@@ -0,0 +1,54 @@
1General Migration Considerations
2================================
3
4Some considerations are not tied to a specific Yocto Project release.
5This section presents information you should consider when migrating to
6any new Yocto Project release.
7
8- *Dealing with Customized Recipes*:
9
10 Issues could arise if you take
11 older recipes that contain customizations and simply copy them
12 forward expecting them to work after you migrate to new Yocto Project
13 metadata. For example, suppose you have a recipe in your layer that
14 is a customized version of a core recipe copied from the earlier
15 release, rather than through the use of an append file. When you
16 migrate to a newer version of Yocto Project, the metadata (e.g.
17 perhaps an include file used by the recipe) could have changed in a
18 way that would break the build. Say, for example, a function is
19 removed from an include file and the customized recipe tries to call
20 that function.
21
22 You could "forward-port" all your customizations in your recipe so
23 that everything works for the new release. However, this is not the
24 optimal solution as you would have to repeat this process with each
25 new release if changes occur that give rise to problems.
26
27 The better solution (where practical) is to use append files
28 (``*.bbappend``) to capture any customizations you want to make to a
29 recipe. Doing so, isolates your changes from the main recipe making
30 them much more manageable. However, sometimes it is not practical to
31 use an append file. A good example of this is when introducing a
32 newer or older version of a recipe in another layer.
33
34- *Updating Append Files*:
35
36 Since append files generally only contain
37 your customizations, they often do not need to be adjusted for new
38 releases. However, if the ``.bbappend`` file is specific to a
39 particular version of the recipe (i.e. its name does not use the %
40 wildcard) and the version of the recipe to which it is appending has
41 changed, then you will at a minimum need to rename the append file to
42 match the name of the recipe file. A mismatch between an append file
43 and its corresponding recipe file (``.bb``) will trigger an error
44 during parsing.
45
46 Depending on the type of customization the append file applies, other
47 incompatibilities might occur when you upgrade. For example, if your
48 append file applies a patch and the recipe to which it is appending
49 is updated to a newer version, the patch might no longer apply. If
50 this is the case and assuming the patch is still needed, you must
51 modify the patch file so that it does apply.
52
53
54
diff --git a/documentation/ref-manual/migration.rst b/documentation/ref-manual/migration.rst
index d0d8f47932..6c6119daec 100644
--- a/documentation/ref-manual/migration.rst
+++ b/documentation/ref-manual/migration.rst
@@ -8,5238 +8,23 @@ This chapter provides information you can use to migrate work to a newer
8Yocto Project release. You can find the same information in the release 8Yocto Project release. You can find the same information in the release
9notes for a given release. 9notes for a given release.
10 10
11General Migration Considerations 11.. toctree::
12================================ 12
13 migration-general
14 migration-1.3
15 migration-1.4
16 migration-1.5
17 migration-1.6
18 migration-1.7
19 migration-1.8
20 migration-2.0
21 migration-2.1
22 migration-2.2
23 migration-2.3
24 migration-2.4
25 migration-2.5
26 migration-2.6
27 migration-2.7
28 migration-3.0
29 migration-3.1
13 30
14Some considerations are not tied to a specific Yocto Project release.
15This section presents information you should consider when migrating to
16any new Yocto Project release.
17
18- *Dealing with Customized Recipes*:
19
20 Issues could arise if you take
21 older recipes that contain customizations and simply copy them
22 forward expecting them to work after you migrate to new Yocto Project
23 metadata. For example, suppose you have a recipe in your layer that
24 is a customized version of a core recipe copied from the earlier
25 release, rather than through the use of an append file. When you
26 migrate to a newer version of Yocto Project, the metadata (e.g.
27 perhaps an include file used by the recipe) could have changed in a
28 way that would break the build. Say, for example, a function is
29 removed from an include file and the customized recipe tries to call
30 that function.
31
32 You could "forward-port" all your customizations in your recipe so
33 that everything works for the new release. However, this is not the
34 optimal solution as you would have to repeat this process with each
35 new release if changes occur that give rise to problems.
36
37 The better solution (where practical) is to use append files
38 (``*.bbappend``) to capture any customizations you want to make to a
39 recipe. Doing so, isolates your changes from the main recipe making
40 them much more manageable. However, sometimes it is not practical to
41 use an append file. A good example of this is when introducing a
42 newer or older version of a recipe in another layer.
43
44- *Updating Append Files*:
45
46 Since append files generally only contain
47 your customizations, they often do not need to be adjusted for new
48 releases. However, if the ``.bbappend`` file is specific to a
49 particular version of the recipe (i.e. its name does not use the %
50 wildcard) and the version of the recipe to which it is appending has
51 changed, then you will at a minimum need to rename the append file to
52 match the name of the recipe file. A mismatch between an append file
53 and its corresponding recipe file (``.bb``) will trigger an error
54 during parsing.
55
56 Depending on the type of customization the append file applies, other
57 incompatibilities might occur when you upgrade. For example, if your
58 append file applies a patch and the recipe to which it is appending
59 is updated to a newer version, the patch might no longer apply. If
60 this is the case and assuming the patch is still needed, you must
61 modify the patch file so that it does apply.
62
63Moving to the Yocto Project 1.3 Release
64=======================================
65
66This section provides migration information for moving to the Yocto
67Project 1.3 Release from the prior release.
68
69.. _1.3-local-configuration:
70
71Local Configuration
72-------------------
73
74Differences include changes for
75:term:`SSTATE_MIRRORS` and ``bblayers.conf``.
76
77.. _migration-1.3-sstate-mirrors:
78
79SSTATE_MIRRORS
80~~~~~~~~~~~~~~
81
82The shared state cache (sstate-cache), as pointed to by
83:term:`SSTATE_DIR`, by default now has two-character
84subdirectories to prevent issues arising from too many files in the same
85directory. Also, native sstate-cache packages, which are built to run on
86the host system, will go into a subdirectory named using the distro ID
87string. If you copy the newly structured sstate-cache to a mirror
88location (either local or remote) and then point to it in
89:term:`SSTATE_MIRRORS`, you need to append "PATH"
90to the end of the mirror URL so that the path used by BitBake before the
91mirror substitution is appended to the path used to access the mirror.
92Here is an example: ::
93
94 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
95
96.. _migration-1.3-bblayers-conf:
97
98bblayers.conf
99~~~~~~~~~~~~~
100
101The ``meta-yocto`` layer consists of two parts that correspond to the
102Poky reference distribution and the reference hardware Board Support
103Packages (BSPs), respectively: ``meta-yocto`` and ``meta-yocto-bsp``.
104When running BitBake for the first time after upgrading, your
105``conf/bblayers.conf`` file will be updated to handle this change and
106you will be asked to re-run or restart for the changes to take effect.
107
108.. _1.3-recipes:
109
110Recipes
111-------
112
113Differences include changes for the following:
114
115.. _migration-1.3-python-function-whitespace:
116
117Python Function Whitespace
118~~~~~~~~~~~~~~~~~~~~~~~~~~
119
120All Python functions must now use four spaces for indentation.
121Previously, an inconsistent mix of spaces and tabs existed, which made
122extending these functions using ``_append`` or ``_prepend`` complicated
123given that Python treats whitespace as syntactically significant. If you
124are defining or extending any Python functions (e.g.
125``populate_packages``, ``do_unpack``, ``do_patch`` and so forth) in
126custom recipes or classes, you need to ensure you are using consistent
127four-space indentation.
128
129.. _migration-1.3-proto=-in-src-uri:
130
131proto= in SRC_URI
132~~~~~~~~~~~~~~~~~
133
134Any use of ``proto=`` in :term:`SRC_URI` needs to be
135changed to ``protocol=``. In particular, this applies to the following
136URIs:
137
138- ``svn://``
139
140- ``bzr://``
141
142- ``hg://``
143
144- ``osc://``
145
146Other URIs were already using ``protocol=``. This change improves
147consistency.
148
149.. _migration-1.3-nativesdk:
150
151nativesdk
152~~~~~~~~~
153
154The suffix ``nativesdk`` is now implemented as a prefix, which
155simplifies a lot of the packaging code for ``nativesdk`` recipes. All
156custom ``nativesdk`` recipes, which are relocatable packages that are
157native to :term:`SDK_ARCH`, and any references need to
158be updated to use ``nativesdk-*`` instead of ``*-nativesdk``.
159
160.. _migration-1.3-task-recipes:
161
162Task Recipes
163~~~~~~~~~~~~
164
165"Task" recipes are now known as "Package groups" and have been renamed
166from ``task-*.bb`` to ``packagegroup-*.bb``. Existing references to the
167previous ``task-*`` names should work in most cases as there is an
168automatic upgrade path for most packages. However, you should update
169references in your own recipes and configurations as they could be
170removed in future releases. You should also rename any custom ``task-*``
171recipes to ``packagegroup-*``, and change them to inherit
172``packagegroup`` instead of ``task``, as well as taking the opportunity
173to remove anything now handled by ``packagegroup.bbclass``, such as
174providing ``-dev`` and ``-dbg`` packages, setting
175:term:`LIC_FILES_CHKSUM`, and so forth. See the
176":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section for
177further details.
178
179.. _migration-1.3-image-features:
180
181IMAGE_FEATURES
182~~~~~~~~~~~~~~
183
184Image recipes that previously included "apps-console-core" in
185:term:`IMAGE_FEATURES` should now include "splash"
186instead to enable the boot-up splash screen. Retaining
187"apps-console-core" will still include the splash screen but generates a
188warning. The "apps-x11-core" and "apps-x11-games" ``IMAGE_FEATURES``
189features have been removed.
190
191.. _migration-1.3-removed-recipes:
192
193Removed Recipes
194~~~~~~~~~~~~~~~
195
196The following recipes have been removed. For most of them, it is
197unlikely that you would have any references to them in your own
198:term:`Metadata`. However, you should check your metadata
199against this list to be sure:
200
201- ``libx11-trim``: Replaced by ``libx11``, which has a negligible
202 size difference with modern Xorg.
203
204- ``xserver-xorg-lite``: Use ``xserver-xorg``, which has a negligible
205 size difference when DRI and GLX modules are not installed.
206
207- ``xserver-kdrive``: Effectively unmaintained for many years.
208
209- ``mesa-xlib``: No longer serves any purpose.
210
211- ``galago``: Replaced by telepathy.
212
213- ``gail``: Functionality was integrated into GTK+ 2.13.
214
215- ``eggdbus``: No longer needed.
216
217- ``gcc-*-intermediate``: The build has been restructured to avoid
218 the need for this step.
219
220- ``libgsmd``: Unmaintained for many years. Functionality now
221 provided by ``ofono`` instead.
222
223- *contacts, dates, tasks, eds-tools*: Largely unmaintained PIM
224 application suite. It has been moved to ``meta-gnome`` in
225 ``meta-openembedded``.
226
227In addition to the previously listed changes, the ``meta-demoapps``
228directory has also been removed because the recipes in it were not being
229maintained and many had become obsolete or broken. Additionally, these
230recipes were not parsed in the default configuration. Many of these
231recipes are already provided in an updated and maintained form within
232the OpenEmbedded community layers such as ``meta-oe`` and
233``meta-gnome``. For the remainder, you can now find them in the
234``meta-extras`` repository, which is in the
235:yocto_git:`Source Repositories <>` at
236http://git.yoctoproject.org/cgit/cgit.cgi/meta-extras/.
237
238.. _1.3-linux-kernel-naming:
239
240Linux Kernel Naming
241-------------------
242
243The naming scheme for kernel output binaries has been changed to now
244include :term:`PE` as part of the filename:
245::
246
247 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
248
249Because the ``PE`` variable is not set by default, these binary files
250could result with names that include two dash characters. Here is an
251example: ::
252
253 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
254
255Moving to the Yocto Project 1.4 Release
256=======================================
257
258This section provides migration information for moving to the Yocto
259Project 1.4 Release from the prior release.
260
261.. _migration-1.4-bitbake:
262
263BitBake
264-------
265
266Differences include the following:
267
268- *Comment Continuation:* If a comment ends with a line continuation
269 (\) character, then the next line must also be a comment. Any
270 instance where this is not the case, now triggers a warning. You must
271 either remove the continuation character, or be sure the next line is
272 a comment.
273
274- *Package Name Overrides:* The runtime package specific variables
275 :term:`RDEPENDS`,
276 :term:`RRECOMMENDS`,
277 :term:`RSUGGESTS`,
278 :term:`RPROVIDES`,
279 :term:`RCONFLICTS`,
280 :term:`RREPLACES`, :term:`FILES`,
281 :term:`ALLOW_EMPTY`, and the pre, post, install,
282 and uninstall script functions ``pkg_preinst``, ``pkg_postinst``,
283 ``pkg_prerm``, and ``pkg_postrm`` should always have a package name
284 override. For example, use ``RDEPENDS_${PN}`` for the main package
285 instead of ``RDEPENDS``. BitBake uses more strict checks when it
286 parses recipes.
287
288.. _migration-1.4-build-behavior:
289
290Build Behavior
291--------------
292
293Differences include the following:
294
295- *Shared State Code:* The shared state code has been optimized to
296 avoid running unnecessary tasks. For example, the following no longer
297 populates the target sysroot since that is not necessary:
298 ::
299
300 $ bitbake -c rootfs some-image
301
302 Instead, the system just needs to extract the
303 output package contents, re-create the packages, and construct the
304 root filesystem. This change is unlikely to cause any problems unless
305 you have missing declared dependencies.
306
307- *Scanning Directory Names:* When scanning for files in
308 :term:`SRC_URI`, the build system now uses
309 :term:`FILESOVERRIDES` instead of
310 :term:`OVERRIDES` for the directory names. In
311 general, the values previously in ``OVERRIDES`` are now in
312 ``FILESOVERRIDES`` as well. However, if you relied upon an additional
313 value you previously added to ``OVERRIDES``, you might now need to
314 add it to ``FILESOVERRIDES`` unless you are already adding it through
315 the :term:`MACHINEOVERRIDES` or
316 :term:`DISTROOVERRIDES` variables, as
317 appropriate. For more related changes, see the
318 "`Variables <#migration-1.4-variables>`__" section.
319
320.. _migration-1.4-proxies-and-fetching-source:
321
322Proxies and Fetching Source
323---------------------------
324
325A new ``oe-git-proxy`` script has been added to replace previous methods
326of handling proxies and fetching source from Git. See the
327``meta-yocto/conf/site.conf.sample`` file for information on how to use
328this script.
329
330.. _migration-1.4-custom-interfaces-file-netbase-change:
331
332Custom Interfaces File (netbase change)
333---------------------------------------
334
335If you have created your own custom ``etc/network/interfaces`` file by
336creating an append file for the ``netbase`` recipe, you now need to
337create an append file for the ``init-ifupdown`` recipe instead, which
338you can find in the :term:`Source Directory` at
339``meta/recipes-core/init-ifupdown``. For information on how to use
340append files, see the
341":ref:`dev-manual/dev-manual-common-tasks:using .bbappend files in your layer`"
342section in the Yocto Project Development Tasks Manual.
343
344.. _migration-1.4-remote-debugging:
345
346Remote Debugging
347----------------
348
349Support for remote debugging with the Eclipse IDE is now separated into
350an image feature (``eclipse-debug``) that corresponds to the
351``packagegroup-core-eclipse-debug`` package group. Previously, the
352debugging feature was included through the ``tools-debug`` image
353feature, which corresponds to the ``packagegroup-core-tools-debug``
354package group.
355
356.. _migration-1.4-variables:
357
358Variables
359---------
360
361The following variables have changed:
362
363- ``SANITY_TESTED_DISTROS``: This variable now uses a distribution
364 ID, which is composed of the host distributor ID followed by the
365 release. Previously,
366 :term:`SANITY_TESTED_DISTROS` was
367 composed of the description field. For example, "Ubuntu 12.10"
368 becomes "Ubuntu-12.10". You do not need to worry about this change if
369 you are not specifically setting this variable, or if you are
370 specifically setting it to "".
371
372- ``SRC_URI``: The ``${``\ :term:`PN`\ ``}``,
373 ``${``\ :term:`PF`\ ``}``,
374 ``${``\ :term:`P`\ ``}``, and ``FILE_DIRNAME`` directories
375 have been dropped from the default value of the
376 :term:`FILESPATH` variable, which is used as the
377 search path for finding files referred to in
378 :term:`SRC_URI`. If you have a recipe that relied upon
379 these directories, which would be unusual, then you will need to add
380 the appropriate paths within the recipe or, alternatively, rearrange
381 the files. The most common locations are still covered by ``${BP}``,
382 ``${BPN}``, and "files", which all remain in the default value of
383 :term:`FILESPATH`.
384
385.. _migration-target-package-management-with-rpm:
386
387Target Package Management with RPM
388----------------------------------
389
390If runtime package management is enabled and the RPM backend is
391selected, Smart is now installed for package download, dependency
392resolution, and upgrades instead of Zypper. For more information on how
393to use Smart, run the following command on the target:
394::
395
396 smart --help
397
398.. _migration-1.4-recipes-moved:
399
400Recipes Moved
401-------------
402
403The following recipes were moved from their previous locations because
404they are no longer used by anything in the OpenEmbedded-Core:
405
406- ``clutter-box2d``: Now resides in the ``meta-oe`` layer.
407
408- ``evolution-data-server``: Now resides in the ``meta-gnome`` layer.
409
410- ``gthumb``: Now resides in the ``meta-gnome`` layer.
411
412- ``gtkhtml2``: Now resides in the ``meta-oe`` layer.
413
414- ``gupnp``: Now resides in the ``meta-multimedia`` layer.
415
416- ``gypsy``: Now resides in the ``meta-oe`` layer.
417
418- ``libcanberra``: Now resides in the ``meta-gnome`` layer.
419
420- ``libgdata``: Now resides in the ``meta-gnome`` layer.
421
422- ``libmusicbrainz``: Now resides in the ``meta-multimedia`` layer.
423
424- ``metacity``: Now resides in the ``meta-gnome`` layer.
425
426- ``polkit``: Now resides in the ``meta-oe`` layer.
427
428- ``zeroconf``: Now resides in the ``meta-networking`` layer.
429
430.. _migration-1.4-removals-and-renames:
431
432Removals and Renames
433--------------------
434
435The following list shows what has been removed or renamed:
436
437- ``evieext``: Removed because it has been removed from ``xserver``
438 since 2008.
439
440- *Gtk+ DirectFB:* Removed support because upstream Gtk+ no longer
441 supports it as of version 2.18.
442
443- ``libxfontcache / xfontcacheproto``: Removed because they were
444 removed from the Xorg server in 2008.
445
446- ``libxp / libxprintapputil / libxprintutil / printproto``: Removed
447 because the XPrint server was removed from Xorg in 2008.
448
449- ``libxtrap / xtrapproto``: Removed because their functionality was
450 broken upstream.
451
452- *linux-yocto 3.0 kernel:* Removed with linux-yocto 3.8 kernel being
453 added. The linux-yocto 3.2 and linux-yocto 3.4 kernels remain as part
454 of the release.
455
456- ``lsbsetup``: Removed with functionality now provided by
457 ``lsbtest``.
458
459- ``matchbox-stroke``: Removed because it was never more than a
460 proof-of-concept.
461
462- ``matchbox-wm-2 / matchbox-theme-sato-2``: Removed because they are
463 not maintained. However, ``matchbox-wm`` and ``matchbox-theme-sato``
464 are still provided.
465
466- ``mesa-dri``: Renamed to ``mesa``.
467
468- ``mesa-xlib``: Removed because it was no longer useful.
469
470- ``mutter``: Removed because nothing ever uses it and the recipe is
471 very old.
472
473- ``orinoco-conf``: Removed because it has become obsolete.
474
475- ``update-modules``: Removed because it is no longer used. The
476 kernel module ``postinstall`` and ``postrm`` scripts can now do the
477 same task without the use of this script.
478
479- ``web``: Removed because it is not maintained. Superseded by
480 ``web-webkit``.
481
482- ``xf86bigfontproto``: Removed because upstream it has been disabled
483 by default since 2007. Nothing uses ``xf86bigfontproto``.
484
485- ``xf86rushproto``: Removed because its dependency in ``xserver``
486 was spurious and it was removed in 2005.
487
488- ``zypper / libzypp / sat-solver``: Removed and been functionally
489 replaced with Smart (``python-smartpm``) when RPM packaging is used
490 and package management is enabled on the target.
491
492Moving to the Yocto Project 1.5 Release
493=======================================
494
495This section provides migration information for moving to the Yocto
496Project 1.5 Release from the prior release.
497
498.. _migration-1.5-host-dependency-changes:
499
500Host Dependency Changes
501-----------------------
502
503The OpenEmbedded build system now has some additional requirements on
504the host system:
505
506- Python 2.7.3+
507
508- Tar 1.24+
509
510- Git 1.7.8+
511
512- Patched version of Make if you are using 3.82. Most distributions
513 that provide Make 3.82 use the patched version.
514
515If the Linux distribution you are using on your build host does not
516provide packages for these, you can install and use the Buildtools
517tarball, which provides an SDK-like environment containing them.
518
519For more information on this requirement, see the "`Required Git, tar,
520Python and gcc Versions <#required-git-tar-python-and-gcc-versions>`__"
521section.
522
523.. _migration-1.5-atom-pc-bsp:
524
525``atom-pc`` Board Support Package (BSP)
526---------------------------------------
527
528The ``atom-pc`` hardware reference BSP has been replaced by a
529``genericx86`` BSP. This BSP is not necessarily guaranteed to work on
530all x86 hardware, but it will run on a wider range of systems than the
531``atom-pc`` did.
532
533.. note::
534
535 Additionally, a
536 genericx86-64
537 BSP has been added for 64-bit Atom systems.
538
539.. _migration-1.5-bitbake:
540
541BitBake
542-------
543
544The following changes have been made that relate to BitBake:
545
546- BitBake now supports a ``_remove`` operator. The addition of this
547 operator means you will have to rename any items in recipe space
548 (functions, variables) whose names currently contain ``_remove_`` or
549 end with ``_remove`` to avoid unexpected behavior.
550
551- BitBake's global method pool has been removed. This method is not
552 particularly useful and led to clashes between recipes containing
553 functions that had the same name.
554
555- The "none" server backend has been removed. The "process" server
556 backend has been serving well as the default for a long time now.
557
558- The ``bitbake-runtask`` script has been removed.
559
560- ``${``\ :term:`P`\ ``}`` and
561 ``${``\ :term:`PF`\ ``}`` are no longer added to
562 :term:`PROVIDES` by default in ``bitbake.conf``.
563 These version-specific ``PROVIDES`` items were seldom used.
564 Attempting to use them could result in two versions being built
565 simultaneously rather than just one version due to the way BitBake
566 resolves dependencies.
567
568.. _migration-1.5-qa-warnings:
569
570QA Warnings
571-----------
572
573The following changes have been made to the package QA checks:
574
575- If you have customized :term:`ERROR_QA` or
576 :term:`WARN_QA` values in your configuration, check
577 that they contain all of the issues that you wish to be reported.
578 Previous Yocto Project versions contained a bug that meant that any
579 item not mentioned in ``ERROR_QA`` or ``WARN_QA`` would be treated as
580 a warning. Consequently, several important items were not already in
581 the default value of ``WARN_QA``. All of the possible QA checks are
582 now documented in the ":ref:`insane.bbclass <ref-classes-insane>`"
583 section.
584
585- An additional QA check has been added to check if
586 ``/usr/share/info/dir`` is being installed. Your recipe should delete
587 this file within :ref:`ref-tasks-install` if "make
588 install" is installing it.
589
590- If you are using the buildhistory class, the check for the package
591 version going backwards is now controlled using a standard QA check.
592 Thus, if you have customized your ``ERROR_QA`` or ``WARN_QA`` values
593 and still wish to have this check performed, you should add
594 "version-going-backwards" to your value for one or the other
595 variables depending on how you wish it to be handled. See the
596 documented QA checks in the
597 ":ref:`insane.bbclass <ref-classes-insane>`" section.
598
599.. _migration-1.5-directory-layout-changes:
600
601Directory Layout Changes
602------------------------
603
604The following directory changes exist:
605
606- Output SDK installer files are now named to include the image name
607 and tuning architecture through the :term:`SDK_NAME`
608 variable.
609
610- Images and related files are now installed into a directory that is
611 specific to the machine, instead of a parent directory containing
612 output files for multiple machines. The
613 :term:`DEPLOY_DIR_IMAGE` variable continues
614 to point to the directory containing images for the current
615 :term:`MACHINE` and should be used anywhere there is a
616 need to refer to this directory. The ``runqemu`` script now uses this
617 variable to find images and kernel binaries and will use BitBake to
618 determine the directory. Alternatively, you can set the
619 ``DEPLOY_DIR_IMAGE`` variable in the external environment.
620
621- When buildhistory is enabled, its output is now written under the
622 :term:`Build Directory` rather than
623 :term:`TMPDIR`. Doing so makes it easier to delete
624 ``TMPDIR`` and preserve the build history. Additionally, data for
625 produced SDKs is now split by :term:`IMAGE_NAME`.
626
627- The ``pkgdata`` directory produced as part of the packaging process
628 has been collapsed into a single machine-specific directory. This
629 directory is located under ``sysroots`` and uses a machine-specific
630 name (i.e. ``tmp/sysroots/machine/pkgdata``).
631
632.. _migration-1.5-shortened-git-srcrev-values:
633
634Shortened Git ``SRCREV`` Values
635-------------------------------
636
637BitBake will now shorten revisions from Git repositories from the normal
63840 characters down to 10 characters within :term:`SRCPV`
639for improved usability in path and file names. This change should be
640safe within contexts where these revisions are used because the chances
641of spatially close collisions is very low. Distant collisions are not a
642major issue in the way the values are used.
643
644.. _migration-1.5-image-features:
645
646``IMAGE_FEATURES``
647------------------
648
649The following changes have been made that relate to
650:term:`IMAGE_FEATURES`:
651
652- The value of ``IMAGE_FEATURES`` is now validated to ensure invalid
653 feature items are not added. Some users mistakenly add package names
654 to this variable instead of using
655 :term:`IMAGE_INSTALL` in order to have the
656 package added to the image, which does not work. This change is
657 intended to catch those kinds of situations. Valid ``IMAGE_FEATURES``
658 are drawn from ``PACKAGE_GROUP`` definitions,
659 :term:`COMPLEMENTARY_GLOB` and a new
660 "validitems" varflag on ``IMAGE_FEATURES``. The "validitems" varflag
661 change allows additional features to be added if they are not
662 provided using the previous two mechanisms.
663
664- The previously deprecated "apps-console-core" ``IMAGE_FEATURES`` item
665 is no longer supported. Add "splash" to ``IMAGE_FEATURES`` if you
666 wish to have the splash screen enabled, since this is all that
667 apps-console-core was doing.
668
669.. _migration-1.5-run:
670
671``/run``
672--------
673
674The ``/run`` directory from the Filesystem Hierarchy Standard 3.0 has
675been introduced. You can find some of the implications for this change
676`here <http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873>`__.
677The change also means that recipes that install files to ``/var/run``
678must be changed. You can find a guide on how to make these changes
679`here <http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530>`__.
680
681.. _migration-1.5-removal-of-package-manager-database-within-image-recipes:
682
683Removal of Package Manager Database Within Image Recipes
684--------------------------------------------------------
685
686The image ``core-image-minimal`` no longer adds
687``remove_packaging_data_files`` to
688:term:`ROOTFS_POSTPROCESS_COMMAND`.
689This addition is now handled automatically when "package-management" is
690not in :term:`IMAGE_FEATURES`. If you have custom
691image recipes that make this addition, you should remove the lines, as
692they are not needed and might interfere with correct operation of
693postinstall scripts.
694
695.. _migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time:
696
697Images Now Rebuild Only on Changes Instead of Every Time
698--------------------------------------------------------
699
700The :ref:`ref-tasks-rootfs` and other related image
701construction tasks are no longer marked as "nostamp". Consequently, they
702will only be re-executed when their inputs have changed. Previous
703versions of the OpenEmbedded build system always rebuilt the image when
704requested rather when necessary.
705
706.. _migration-1.5-task-recipes:
707
708Task Recipes
709------------
710
711The previously deprecated ``task.bbclass`` has now been dropped. For
712recipes that previously inherited from this class, you should rename
713them from ``task-*`` to ``packagegroup-*`` and inherit packagegroup
714instead.
715
716For more information, see the
717":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section.
718
719.. _migration-1.5-busybox:
720
721BusyBox
722-------
723
724By default, we now split BusyBox into two binaries: one that is suid
725root for those components that need it, and another for the rest of the
726components. Splitting BusyBox allows for optimization that eliminates
727the ``tinylogin`` recipe as recommended by upstream. You can disable
728this split by setting
729:term:`BUSYBOX_SPLIT_SUID` to "0".
730
731.. _migration-1.5-automated-image-testing:
732
733Automated Image Testing
734-----------------------
735
736A new automated image testing framework has been added through the
737:ref:`testimage.bbclass <ref-classes-testimage*>` class. This
738framework replaces the older ``imagetest-qemu`` framework.
739
740You can learn more about performing automated image tests in the
741":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
742section in the Yocto Project Development Tasks Manual.
743
744.. _migration-1.5-build-history:
745
746Build History
747-------------
748
749Following are changes to Build History:
750
751- Installed package sizes: ``installed-package-sizes.txt`` for an image
752 now records the size of the files installed by each package instead
753 of the size of each compressed package archive file.
754
755- The dependency graphs (``depends*.dot``) now use the actual package
756 names instead of replacing dashes, dots and plus signs with
757 underscores.
758
759- The ``buildhistory-diff`` and ``buildhistory-collect-srcrevs``
760 utilities have improved command-line handling. Use the ``--help``
761 option for each utility for more information on the new syntax.
762
763For more information on Build History, see the
764":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
765section in the Yocto Project Development Tasks Manual.
766
767.. _migration-1.5-udev:
768
769``udev``
770--------
771
772Following are changes to ``udev``:
773
774- ``udev`` no longer brings in ``udev-extraconf`` automatically through
775 :term:`RRECOMMENDS`, since this was originally
776 intended to be optional. If you need the extra rules, then add
777 ``udev-extraconf`` to your image.
778
779- ``udev`` no longer brings in ``pciutils-ids`` or ``usbutils-ids``
780 through ``RRECOMMENDS``. These are not needed by ``udev`` itself and
781 removing them saves around 350KB.
782
783.. _migration-1.5-removed-renamed-recipes:
784
785Removed and Renamed Recipes
786---------------------------
787
788- The ``linux-yocto`` 3.2 kernel has been removed.
789
790- ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``.
791
792- ``tinylogin`` has been removed. It has been replaced by a suid
793 portion of Busybox. See the "`BusyBox <#migration-1.5-busybox>`__"
794 section for more information.
795
796- ``external-python-tarball`` has been renamed to
797 ``buildtools-tarball``.
798
799- ``web-webkit`` has been removed. It has been functionally replaced by
800 ``midori``.
801
802- ``imake`` has been removed. It is no longer needed by any other
803 recipe.
804
805- ``transfig-native`` has been removed. It is no longer needed by any
806 other recipe.
807
808- ``anjuta-remote-run`` has been removed. Anjuta IDE integration has
809 not been officially supported for several releases.
810
811.. _migration-1.5-other-changes:
812
813Other Changes
814-------------
815
816Following is a list of short entries describing other changes:
817
818- ``run-postinsts``: Make this generic.
819
820- ``base-files``: Remove the unnecessary ``media/``\ xxx directories.
821
822- ``alsa-state``: Provide an empty ``asound.conf`` by default.
823
824- ``classes/image``: Ensure
825 :term:`BAD_RECOMMENDATIONS` supports
826 pre-renamed package names.
827
828- ``classes/rootfs_rpm``: Implement ``BAD_RECOMMENDATIONS`` for RPM.
829
830- ``systemd``: Remove ``systemd_unitdir`` if ``systemd`` is not in
831 :term:`DISTRO_FEATURES`.
832
833- ``systemd``: Remove ``init.d`` dir if ``systemd`` unit file is
834 present and ``sysvinit`` is not a distro feature.
835
836- ``libpam``: Deny all services for the ``OTHER`` entries.
837
838- ``image.bbclass``: Move ``runtime_mapping_rename`` to avoid conflict
839 with ``multilib``. See
840 `YOCTO #4993 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993>`_
841 in Bugzilla for more information.
842
843- ``linux-dtb``: Use kernel build system to generate the ``dtb`` files.
844
845- ``kern-tools``: Switch from guilt to new ``kgit-s2q`` tool.
846
847Moving to the Yocto Project 1.6 Release
848=======================================
849
850This section provides migration information for moving to the Yocto
851Project 1.6 Release from the prior release.
852
853.. _migration-1.6-archiver-class:
854
855``archiver`` Class
856------------------
857
858The :ref:`archiver <ref-classes-archiver>` class has been rewritten
859and its configuration has been simplified. For more details on the
860source archiver, see the
861":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
862section in the Yocto Project Development Tasks Manual.
863
864.. _migration-1.6-packaging-changes:
865
866Packaging Changes
867-----------------
868
869The following packaging changes have been made:
870
871- The ``binutils`` recipe no longer produces a ``binutils-symlinks``
872 package. ``update-alternatives`` is now used to handle the preferred
873 ``binutils`` variant on the target instead.
874
875- The tc (traffic control) utilities have been split out of the main
876 ``iproute2`` package and put into the ``iproute2-tc`` package.
877
878- The ``gtk-engines`` schemas have been moved to a dedicated
879 ``gtk-engines-schemas`` package.
880
881- The ``armv7a`` with thumb package architecture suffix has changed.
882 The suffix for these packages with the thumb optimization enabled is
883 "t2" as it should be. Use of this suffix was not the case in the 1.5
884 release. Architecture names will change within package feeds as a
885 result.
886
887.. _migration-1.6-bitbake:
888
889BitBake
890-------
891
892The following changes have been made to :term:`BitBake`.
893
894.. _migration-1.6-matching-branch-requirement-for-git-fetching:
895
896Matching Branch Requirement for Git Fetching
897~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
898
899When fetching source from a Git repository using
900:term:`SRC_URI`, BitBake will now validate the
901:term:`SRCREV` value against the branch. You can specify
902the branch using the following form: SRC_URI =
903"git://server.name/repository;branch=branchname" If you do not specify a
904branch, BitBake looks in the default "master" branch.
905
906Alternatively, if you need to bypass this check (e.g. if you are
907fetching a revision corresponding to a tag that is not on any branch),
908you can add ";nobranch=1" to the end of the URL within ``SRC_URI``.
909
910.. _migration-1.6-bitbake-deps:
911
912Python Definition substitutions
913~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
914
915BitBake had some previously deprecated Python definitions within its
916``bb`` module removed. You should use their sub-module counterparts
917instead:
918
919- ``bb.MalformedUrl``: Use ``bb.fetch.MalformedUrl``.
920
921- ``bb.encodeurl``: Use ``bb.fetch.encodeurl``.
922
923- ``bb.decodeurl``: Use ``bb.fetch.decodeurl``
924
925- ``bb.mkdirhier``: Use ``bb.utils.mkdirhier``.
926
927- ``bb.movefile``: Use ``bb.utils.movefile``.
928
929- ``bb.copyfile``: Use ``bb.utils.copyfile``.
930
931- ``bb.which``: Use ``bb.utils.which``.
932
933- ``bb.vercmp_string``: Use ``bb.utils.vercmp_string``.
934
935- ``bb.vercmp``: Use ``bb.utils.vercmp``.
936
937.. _migration-1.6-bitbake-fetcher:
938
939SVK Fetcher
940~~~~~~~~~~~
941
942The SVK fetcher has been removed from BitBake.
943
944.. _migration-1.6-bitbake-console-output:
945
946Console Output Error Redirection
947~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
948
949The BitBake console UI will now output errors to ``stderr`` instead of
950``stdout``. Consequently, if you are piping or redirecting the output of
951``bitbake`` to somewhere else, and you wish to retain the errors, you
952will need to add ``2>&1`` (or something similar) to the end of your
953``bitbake`` command line.
954
955.. _migration-1.6-task-taskname-overrides:
956
957``task-``\ taskname Overrides
958~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
959
960``task-``\ taskname overrides have been adjusted so that tasks whose
961names contain underscores have the underscores replaced by hyphens for
962the override so that they now function properly. For example, the task
963override for :ref:`ref-tasks-populate_sdk` is
964``task-populate-sdk``.
965
966.. _migration-1.6-variable-changes:
967
968Changes to Variables
969--------------------
970
971The following variables have changed. For information on the
972OpenEmbedded build system variables, see the "`Variables
973Glossary <#ref-variables-glos>`__" Chapter.
974
975.. _migration-1.6-variable-changes-TMPDIR:
976
977``TMPDIR``
978~~~~~~~~~~
979
980:term:`TMPDIR` can no longer be on an NFS mount. NFS does
981not offer full POSIX locking and inode consistency and can cause
982unexpected issues if used to store ``TMPDIR``.
983
984The check for this occurs on startup. If ``TMPDIR`` is detected on an
985NFS mount, an error occurs.
986
987.. _migration-1.6-variable-changes-PRINC:
988
989``PRINC``
990~~~~~~~~~
991
992The ``PRINC`` variable has been deprecated and triggers a warning if
993detected during a build. For :term:`PR` increments on changes,
994use the PR service instead. You can find out more about this service in
995the ":ref:`dev-manual/dev-manual-common-tasks:working with a pr service`"
996section in the Yocto Project Development Tasks Manual.
997
998.. _migration-1.6-variable-changes-IMAGE_TYPES:
999
1000``IMAGE_TYPES``
1001~~~~~~~~~~~~~~~
1002
1003The "sum.jffs2" option for :term:`IMAGE_TYPES` has
1004been replaced by the "jffs2.sum" option, which fits the processing
1005order.
1006
1007.. _migration-1.6-variable-changes-COPY_LIC_MANIFEST:
1008
1009``COPY_LIC_MANIFEST``
1010~~~~~~~~~~~~~~~~~~~~~
1011
1012The :term:`COPY_LIC_MANIFEST` variable must now
1013be set to "1" rather than any value in order to enable it.
1014
1015.. _migration-1.6-variable-changes-COPY_LIC_DIRS:
1016
1017``COPY_LIC_DIRS``
1018~~~~~~~~~~~~~~~~~
1019
1020The :term:`COPY_LIC_DIRS` variable must now be set
1021to "1" rather than any value in order to enable it.
1022
1023.. _migration-1.6-variable-changes-PACKAGE_GROUP:
1024
1025``PACKAGE_GROUP``
1026~~~~~~~~~~~~~~~~~
1027
1028The ``PACKAGE_GROUP`` variable has been renamed to
1029:term:`FEATURE_PACKAGES` to more accurately
1030reflect its purpose. You can still use ``PACKAGE_GROUP`` but the
1031OpenEmbedded build system produces a warning message when it encounters
1032the variable.
1033
1034.. _migration-1.6-variable-changes-variable-entry-behavior:
1035
1036Preprocess and Post Process Command Variable Behavior
1037~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1038
1039The following variables now expect a semicolon separated list of
1040functions to call and not arbitrary shell commands:
1041
1042 - :term:`ROOTFS_PREPROCESS_COMMAND`
1043 - :term:`ROOTFS_POSTPROCESS_COMMAND`
1044 - :term:`SDK_POSTPROCESS_COMMAND`
1045 - :term:`POPULATE_SDK_POST_TARGET_COMMAND`
1046 - :term:`POPULATE_SDK_POST_HOST_COMMAND`
1047 - :term:`IMAGE_POSTPROCESS_COMMAND`
1048 - :term:`IMAGE_PREPROCESS_COMMAND`
1049 - :term:`ROOTFS_POSTUNINSTALL_COMMAND`
1050 - :term:`ROOTFS_POSTINSTALL_COMMAND`
1051
1052For
1053migration purposes, you can simply wrap shell commands in a shell
1054function and then call the function. Here is an example: ::
1055
1056 my_postprocess_function() {
1057 echo "hello" > ${IMAGE_ROOTFS}/hello.txt
1058 }
1059 ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "
1060
1061.. _migration-1.6-package-test-ptest:
1062
1063Package Test (ptest)
1064--------------------
1065
1066Package Tests (ptest) are built but not installed by default. For
1067information on using Package Tests, see the
1068":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`"
1069section in the Yocto Project Development Tasks Manual. For information on the
1070``ptest`` class, see the ":ref:`ptest.bbclass <ref-classes-ptest>`"
1071section.
1072
1073.. _migration-1.6-build-changes:
1074
1075Build Changes
1076-------------
1077
1078Separate build and source directories have been enabled by default for
1079selected recipes where it is known to work (a whitelist) and for all
1080recipes that inherit the :ref:`cmake <ref-classes-cmake>` class. In
1081future releases the :ref:`autotools <ref-classes-autotools>` class
1082will enable a separate build directory by default as well. Recipes
1083building Autotools-based software that fails to build with a separate
1084build directory should be changed to inherit from the
1085:ref:`autotools-brokensep <ref-classes-autotools>` class instead of
1086the ``autotools`` or ``autotools_stage``\ classes.
1087
1088.. _migration-1.6-building-qemu-native:
1089
1090``qemu-native``
1091---------------
1092
1093``qemu-native`` now builds without SDL-based graphical output support by
1094default. The following additional lines are needed in your
1095``local.conf`` to enable it:
1096::
1097
1098 PACKAGECONFIG_pn-qemu-native = "sdl"
1099 ASSUME_PROVIDED += "libsdl-native"
1100
1101.. note::
1102
1103 The default
1104 local.conf
1105 contains these statements. Consequently, if you are building a
1106 headless system and using a default
1107 local.conf
1108 file, you will need comment these two lines out.
1109
1110.. _migration-1.6-core-image-basic:
1111
1112``core-image-basic``
1113--------------------
1114
1115``core-image-basic`` has been renamed to ``core-image-full-cmdline``.
1116
1117In addition to ``core-image-basic`` being renamed,
1118``packagegroup-core-basic`` has been renamed to
1119``packagegroup-core-full-cmdline`` to match.
1120
1121.. _migration-1.6-licensing:
1122
1123Licensing
1124---------
1125
1126The top-level ``LICENSE`` file has been changed to better describe the
1127license of the various components of :term:`OpenEmbedded-Core (OE-Core)`. However,
1128the licensing itself remains unchanged.
1129
1130Normally, this change would not cause any side-effects. However, some
1131recipes point to this file within
1132:term:`LIC_FILES_CHKSUM` (as
1133``${COREBASE}/LICENSE``) and thus the accompanying checksum must be
1134changed from 3f40d7994397109285ec7b81fdeb3b58 to
11354d92cd373abda3937c2bc47fbc49d690. A better alternative is to have
1136``LIC_FILES_CHKSUM`` point to a file describing the license that is
1137distributed with the source that the recipe is building, if possible,
1138rather than pointing to ``${COREBASE}/LICENSE``.
1139
1140.. _migration-1.6-cflags-options:
1141
1142``CFLAGS`` Options
1143------------------
1144
1145The "-fpermissive" option has been removed from the default
1146:term:`CFLAGS` value. You need to take action on
1147individual recipes that fail when building with this option. You need to
1148either patch the recipes to fix the issues reported by the compiler, or
1149you need to add "-fpermissive" to ``CFLAGS`` in the recipes.
1150
1151.. _migration-1.6-custom-images:
1152
1153Custom Image Output Types
1154-------------------------
1155
1156Custom image output types, as selected using
1157:term:`IMAGE_FSTYPES`, must declare their
1158dependencies on other image types (if any) using a new
1159:term:`IMAGE_TYPEDEP` variable.
1160
1161.. _migration-1.6-do-package-write-task:
1162
1163Tasks
1164-----
1165
1166The ``do_package_write`` task has been removed. The task is no longer
1167needed.
1168
1169.. _migration-1.6-update-alternatives-provider:
1170
1171``update-alternative`` Provider
1172-------------------------------
1173
1174The default ``update-alternatives`` provider has been changed from
1175``opkg`` to ``opkg-utils``. This change resolves some troublesome
1176circular dependencies. The runtime package has also been renamed from
1177``update-alternatives-cworth`` to ``update-alternatives-opkg``.
1178
1179.. _migration-1.6-virtclass-overrides:
1180
1181``virtclass`` Overrides
1182-----------------------
1183
1184The ``virtclass`` overrides are now deprecated. Use the equivalent class
1185overrides instead (e.g. ``virtclass-native`` becomes ``class-native``.)
1186
1187.. _migration-1.6-removed-renamed-recipes:
1188
1189Removed and Renamed Recipes
1190---------------------------
1191
1192The following recipes have been removed:
1193
1194- ``packagegroup-toolset-native`` - This recipe is largely unused.
1195
1196- ``linux-yocto-3.8`` - Support for the Linux yocto 3.8 kernel has been
1197 dropped. Support for the 3.10 and 3.14 kernels have been added with
1198 the ``linux-yocto-3.10`` and ``linux-yocto-3.14`` recipes.
1199
1200- ``ocf-linux`` - This recipe has been functionally replaced using
1201 ``cryptodev-linux``.
1202
1203- ``genext2fs`` - ``genext2fs`` is no longer used by the build system
1204 and is unmaintained upstream.
1205
1206- ``js`` - This provided an ancient version of Mozilla's javascript
1207 engine that is no longer needed.
1208
1209- ``zaurusd`` - The recipe has been moved to the ``meta-handheld``
1210 layer.
1211
1212- ``eglibc 2.17`` - Replaced by the ``eglibc 2.19`` recipe.
1213
1214- ``gcc 4.7.2`` - Replaced by the now stable ``gcc 4.8.2``.
1215
1216- ``external-sourcery-toolchain`` - this recipe is now maintained in
1217 the ``meta-sourcery`` layer.
1218
1219- ``linux-libc-headers-yocto 3.4+git`` - Now using version 3.10 of the
1220 ``linux-libc-headers`` by default.
1221
1222- ``meta-toolchain-gmae`` - This recipe is obsolete.
1223
1224- ``packagegroup-core-sdk-gmae`` - This recipe is obsolete.
1225
1226- ``packagegroup-core-standalone-gmae-sdk-target`` - This recipe is
1227 obsolete.
1228
1229.. _migration-1.6-removed-classes:
1230
1231Removed Classes
1232---------------
1233
1234The following classes have become obsolete and have been removed:
1235
1236- ``module_strip``
1237
1238- ``pkg_metainfo``
1239
1240- ``pkg_distribute``
1241
1242- ``image-empty``
1243
1244.. _migration-1.6-reference-bsps:
1245
1246Reference Board Support Packages (BSPs)
1247---------------------------------------
1248
1249The following reference BSPs changes occurred:
1250
1251- The BeagleBoard (``beagleboard``) ARM reference hardware has been
1252 replaced by the BeagleBone (``beaglebone``) hardware.
1253
1254- The RouterStation Pro (``routerstationpro``) MIPS reference hardware
1255 has been replaced by the EdgeRouter Lite (``edgerouter``) hardware.
1256
1257The previous reference BSPs for the ``beagleboard`` and
1258``routerstationpro`` machines are still available in a new
1259``meta-yocto-bsp-old`` layer in the
1260:yocto_git:`Source Repositories <>` at
1261http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/.
1262
1263Moving to the Yocto Project 1.7 Release
1264=======================================
1265
1266This section provides migration information for moving to the Yocto
1267Project 1.7 Release from the prior release.
1268
1269.. _migration-1.7-changes-to-setting-qemu-packageconfig-options:
1270
1271Changes to Setting QEMU ``PACKAGECONFIG`` Options in ``local.conf``
1272-------------------------------------------------------------------
1273
1274The QEMU recipe now uses a number of
1275:term:`PACKAGECONFIG` options to enable various
1276optional features. The method used to set defaults for these options
1277means that existing ``local.conf`` files will need to be be modified to
1278append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu``
1279instead of setting it. In other words, to enable graphical output for
1280QEMU, you should now have these lines in ``local.conf``:
1281::
1282
1283 PACKAGECONFIG_append_pn-qemu-native = " sdl"
1284 PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
1285
1286.. _migration-1.7-minimum-git-version:
1287
1288Minimum Git version
1289-------------------
1290
1291The minimum :ref:`overview-manual/overview-manual-development-environment:git`
1292version required on the
1293build host is now 1.7.8 because the ``--list`` option is now required by
1294BitBake's Git fetcher. As always, if your host distribution does not
1295provide a version of Git that meets this requirement, you can use the
1296``buildtools-tarball`` that does. See the "`Required Git, tar, Python
1297and gcc Versions <#required-git-tar-python-and-gcc-versions>`__" section
1298for more information.
1299
1300.. _migration-1.7-autotools-class-changes:
1301
1302Autotools Class Changes
1303-----------------------
1304
1305The following :ref:`autotools <ref-classes-autotools>` class changes
1306occurred:
1307
1308- *A separate build directory is now used by default:* The
1309 ``autotools`` class has been changed to use a directory for building
1310 (:term:`B`), which is separate from the source directory
1311 (:term:`S`). This is commonly referred to as ``B != S``, or
1312 an out-of-tree build.
1313
1314 If the software being built is already capable of building in a
1315 directory separate from the source, you do not need to do anything.
1316 However, if the software is not capable of being built in this
1317 manner, you will need to either patch the software so that it can
1318 build separately, or you will need to change the recipe to inherit
1319 the :ref:`autotools-brokensep <ref-classes-autotools>` class
1320 instead of the ``autotools`` or ``autotools_stage`` classes.
1321
1322- The ``--foreign`` option is no longer passed to ``automake`` when
1323 running ``autoconf``: This option tells ``automake`` that a
1324 particular software package does not follow the GNU standards and
1325 therefore should not be expected to distribute certain files such as
1326 ``ChangeLog``, ``AUTHORS``, and so forth. Because the majority of
1327 upstream software packages already tell ``automake`` to enable
1328 foreign mode themselves, the option is mostly superfluous. However,
1329 some recipes will need patches for this change. You can easily make
1330 the change by patching ``configure.ac`` so that it passes "foreign"
1331 to ``AM_INIT_AUTOMAKE()``. See `this
1332 commit <http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2>`__
1333 for an example showing how to make the patch.
1334
1335.. _migration-1.7-binary-configuration-scripts-disabled:
1336
1337Binary Configuration Scripts Disabled
1338-------------------------------------
1339
1340Some of the core recipes that package binary configuration scripts now
1341disable the scripts due to the scripts previously requiring error-prone
1342path substitution. Software that links against these libraries using
1343these scripts should use the much more robust ``pkg-config`` instead.
1344The list of recipes changed in this version (and their configuration
1345scripts) is as follows:
1346::
1347
1348 directfb (directfb-config)
1349 freetype (freetype-config)
1350 gpgme (gpgme-config)
1351 libassuan (libassuan-config)
1352 libcroco (croco-6.0-config)
1353 libgcrypt (libgcrypt-config)
1354 libgpg-error (gpg-error-config)
1355 libksba (ksba-config)
1356 libpcap (pcap-config)
1357 libpcre (pcre-config)
1358 libpng (libpng-config, libpng16-config)
1359 libsdl (sdl-config)
1360 libusb-compat (libusb-config)
1361 libxml2 (xml2-config)
1362 libxslt (xslt-config)
1363 ncurses (ncurses-config)
1364 neon (neon-config)
1365 npth (npth-config)
1366 pth (pth-config)
1367 taglib (taglib-config)
1368
1369Additionally, support for ``pkg-config`` has been added to some recipes in the
1370previous list in the rare cases where the upstream software package does
1371not already provide it.
1372
1373.. _migration-1.7-glibc-replaces-eglibc:
1374
1375``eglibc 2.19`` Replaced with ``glibc 2.20``
1376--------------------------------------------
1377
1378Because ``eglibc`` and ``glibc`` were already fairly close, this
1379replacement should not require any significant changes to other software
1380that links to ``eglibc``. However, there were a number of minor changes
1381in ``glibc 2.20`` upstream that could require patching some software
1382(e.g. the removal of the ``_BSD_SOURCE`` feature test macro).
1383
1384``glibc 2.20`` requires version 2.6.32 or greater of the Linux kernel.
1385Thus, older kernels will no longer be usable in conjunction with it.
1386
1387For full details on the changes in ``glibc 2.20``, see the upstream
1388release notes
1389`here <https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html>`__.
1390
1391.. _migration-1.7-kernel-module-autoloading:
1392
1393Kernel Module Autoloading
1394-------------------------
1395
1396The :term:`module_autoload_* <module_autoload>` variable is now
1397deprecated and a new
1398:term:`KERNEL_MODULE_AUTOLOAD` variable
1399should be used instead. Also, :term:`module_conf_* <module_conf>`
1400must now be used in conjunction with a new
1401:term:`KERNEL_MODULE_PROBECONF` variable.
1402The new variables no longer require you to specify the module name as
1403part of the variable name. This change not only simplifies usage but
1404also allows the values of these variables to be appropriately
1405incorporated into task signatures and thus trigger the appropriate tasks
1406to re-execute when changed. You should replace any references to
1407``module_autoload_*`` with ``KERNEL_MODULE_AUTOLOAD``, and add any
1408modules for which ``module_conf_*`` is specified to
1409``KERNEL_MODULE_PROBECONF``.
1410
1411.. _migration-1.7-qa-check-changes:
1412
1413QA Check Changes
1414----------------
1415
1416The following changes have occurred to the QA check process:
1417
1418- Additional QA checks ``file-rdeps`` and ``build-deps`` have been
1419 added in order to verify that file dependencies are satisfied (e.g.
1420 package contains a script requiring ``/bin/bash``) and build-time
1421 dependencies are declared, respectively. For more information, please
1422 see the "`QA Error and Warning Messages <#ref-qa-checks>`__" chapter.
1423
1424- Package QA checks are now performed during a new
1425 :ref:`ref-tasks-package_qa` task rather than being
1426 part of the :ref:`ref-tasks-package` task. This allows
1427 more parallel execution. This change is unlikely to be an issue
1428 except for highly customized recipes that disable packaging tasks
1429 themselves by marking them as ``noexec``. For those packages, you
1430 will need to disable the ``do_package_qa`` task as well.
1431
1432- Files being overwritten during the
1433 :ref:`ref-tasks-populate_sysroot` task now
1434 trigger an error instead of a warning. Recipes should not be
1435 overwriting files written to the sysroot by other recipes. If you
1436 have these types of recipes, you need to alter them so that they do
1437 not overwrite these files.
1438
1439 You might now receive this error after changes in configuration or
1440 metadata resulting in orphaned files being left in the sysroot. If
1441 you do receive this error, the way to resolve the issue is to delete
1442 your :term:`TMPDIR` or to move it out of the way and
1443 then re-start the build. Anything that has been fully built up to
1444 that point and does not need rebuilding will be restored from the
1445 shared state cache and the rest of the build will be able to proceed
1446 as normal.
1447
1448.. _migration-1.7-removed-recipes:
1449
1450Removed Recipes
1451---------------
1452
1453The following recipes have been removed:
1454
1455- ``x-load``: This recipe has been superseded by U-boot SPL for all
1456 Cortex-based TI SoCs. For legacy boards, the ``meta-ti`` layer, which
1457 contains a maintained recipe, should be used instead.
1458
1459- ``ubootchart``: This recipe is obsolete. A ``bootchart2`` recipe has
1460 been added to functionally replace it.
1461
1462- ``linux-yocto 3.4``: Support for the linux-yocto 3.4 kernel has been
1463 dropped. Support for the 3.10 and 3.14 kernels remains, while support
1464 for version 3.17 has been added.
1465
1466- ``eglibc`` has been removed in favor of ``glibc``. See the
1467 "```eglibc 2.19`` Replaced with
1468 ``glibc 2.20`` <#migration-1.7-glibc-replaces-eglibc>`__" section for
1469 more information.
1470
1471.. _migration-1.7-miscellaneous-changes:
1472
1473Miscellaneous Changes
1474---------------------
1475
1476The following miscellaneous change occurred:
1477
1478- The build history feature now writes ``build-id.txt`` instead of
1479 ``build-id``. Additionally, ``build-id.txt`` now contains the full
1480 build header as printed by BitBake upon starting the build. You
1481 should manually remove old "build-id" files from your existing build
1482 history repositories to avoid confusion. For information on the build
1483 history feature, see the
1484 ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
1485 section in the Yocto Project Development Tasks Manual.
1486
1487Moving to the Yocto Project 1.8 Release
1488=======================================
1489
1490This section provides migration information for moving to the Yocto
1491Project 1.8 Release from the prior release.
1492
1493.. _migration-1.8-removed-recipes:
1494
1495Removed Recipes
1496---------------
1497
1498The following recipes have been removed:
1499
1500- ``owl-video``: Functionality replaced by ``gst-player``.
1501
1502- ``gaku``: Functionality replaced by ``gst-player``.
1503
1504- ``gnome-desktop``: This recipe is now available in ``meta-gnome`` and
1505 is no longer needed.
1506
1507- ``gsettings-desktop-schemas``: This recipe is now available in
1508 ``meta-gnome`` and is no longer needed.
1509
1510- ``python-argparse``: The ``argparse`` module is already provided in
1511 the default Python distribution in a package named
1512 ``python-argparse``. Consequently, the separate ``python-argparse``
1513 recipe is no longer needed.
1514
1515- ``telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control``:
1516 All these recipes have moved to ``meta-oe`` and are consequently no
1517 longer needed by any recipes in OpenEmbedded-Core.
1518
1519- ``linux-yocto_3.10`` and ``linux-yocto_3.17``: Support for the
1520 linux-yocto 3.10 and 3.17 kernels has been dropped. Support for the
1521 3.14 kernel remains, while support for 3.19 kernel has been added.
1522
1523- ``poky-feed-config-opkg``: This recipe has become obsolete and is no
1524 longer needed. Use ``distro-feed-config`` from ``meta-oe`` instead.
1525
1526- ``libav 0.8.x``: ``libav 9.x`` is now used.
1527
1528- ``sed-native``: No longer needed. A working version of ``sed`` is
1529 expected to be provided by the host distribution.
1530
1531.. _migration-1.8-bluez:
1532
1533BlueZ 4.x / 5.x Selection
1534-------------------------
1535
1536Proper built-in support for selecting BlueZ 5.x in preference to the
1537default of 4.x now exists. To use BlueZ 5.x, simply add "bluez5" to your
1538:term:`DISTRO_FEATURES` value. If you had
1539previously added append files (``*.bbappend``) to make this selection,
1540you can now remove them.
1541
1542Additionally, a ``bluetooth`` class has been added to make selection of
1543the appropriate bluetooth support within a recipe a little easier. If
1544you wish to make use of this class in a recipe, add something such as
1545the following: ::
1546
1547 inherit bluetooth
1548 PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}"
1549 PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4"
1550 PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5"
1551
1552.. _migration-1.8-kernel-build-changes:
1553
1554Kernel Build Changes
1555--------------------
1556
1557The kernel build process was changed to place the source in a common
1558shared work area and to place build artifacts separately in the source
1559code tree. In theory, migration paths have been provided for most common
1560usages in kernel recipes but this might not work in all cases. In
1561particular, users need to ensure that ``${S}`` (source files) and
1562``${B}`` (build artifacts) are used correctly in functions such as
1563:ref:`ref-tasks-configure` and
1564:ref:`ref-tasks-install`. For kernel recipes that do not
1565inherit from ``kernel-yocto`` or include ``linux-yocto.inc``, you might
1566wish to refer to the ``linux.inc`` file in the ``meta-oe`` layer for the
1567kinds of changes you need to make. For reference, here is the
1568`commit <http://cgit.openembedded.org/meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee>`__
1569where the ``linux.inc`` file in ``meta-oe`` was updated.
1570
1571Recipes that rely on the kernel source code and do not inherit the
1572module classes might need to add explicit dependencies on the
1573``do_shared_workdir`` kernel task, for example: ::
1574
1575 do_configure[depends] += "virtual/kernel:do_shared_workdir"
1576
1577.. _migration-1.8-ssl:
1578
1579SSL 3.0 is Now Disabled in OpenSSL
1580----------------------------------
1581
1582SSL 3.0 is now disabled when building OpenSSL. Disabling SSL 3.0 avoids
1583any lingering instances of the POODLE vulnerability. If you feel you
1584must re-enable SSL 3.0, then you can add an append file (``*.bbappend``)
1585for the ``openssl`` recipe to remove "-no-ssl3" from
1586:term:`EXTRA_OECONF`.
1587
1588.. _migration-1.8-default-sysroot-poisoning:
1589
1590Default Sysroot Poisoning
1591-------------------------
1592
1593``gcc's`` default sysroot and include directories are now "poisoned". In
1594other words, the sysroot and include directories are being redirected to
1595a non-existent location in order to catch when host directories are
1596being used due to the correct options not being passed. This poisoning
1597applies both to the cross-compiler used within the build and to the
1598cross-compiler produced in the SDK.
1599
1600If this change causes something in the build to fail, it almost
1601certainly means the various compiler flags and commands are not being
1602passed correctly to the underlying piece of software. In such cases, you
1603need to take corrective steps.
1604
1605.. _migration-1.8-rebuild-improvements:
1606
1607Rebuild Improvements
1608--------------------
1609
1610Changes have been made to the :ref:`base <ref-classes-base>`,
1611:ref:`autotools <ref-classes-autotools>`, and
1612:ref:`cmake <ref-classes-cmake>` classes to clean out generated files
1613when the :ref:`ref-tasks-configure` task needs to be
1614re-executed.
1615
1616One of the improvements is to attempt to run "make clean" during the
1617``do_configure`` task if a ``Makefile`` exists. Some software packages
1618do not provide a working clean target within their make files. If you
1619have such recipes, you need to set
1620:term:`CLEANBROKEN` to "1" within the recipe, for example: ::
1621
1622 CLEANBROKEN = "1"
1623
1624.. _migration-1.8-qa-check-and-validation-changes:
1625
1626QA Check and Validation Changes
1627-------------------------------
1628
1629The following QA Check and Validation Changes have occurred:
1630
1631- Usage of ``PRINC`` previously triggered a warning. It now triggers an
1632 error. You should remove any remaining usage of ``PRINC`` in any
1633 recipe or append file.
1634
1635- An additional QA check has been added to detect usage of ``${D}`` in
1636 :term:`FILES` values where :term:`D` values
1637 should not be used at all. The same check ensures that ``$D`` is used
1638 in ``pkg_preinst/pkg_postinst/pkg_prerm/pkg_postrm`` functions
1639 instead of ``${D}``.
1640
1641- :term:`S` now needs to be set to a valid value within a
1642 recipe. If ``S`` is not set in the recipe, the directory is not
1643 automatically created. If ``S`` does not point to a directory that
1644 exists at the time the :ref:`ref-tasks-unpack` task
1645 finishes, a warning will be shown.
1646
1647- :term:`LICENSE` is now validated for correct
1648 formatting of multiple licenses. If the format is invalid (e.g.
1649 multiple licenses are specified with no operators to specify how the
1650 multiple licenses interact), then a warning will be shown.
1651
1652.. _migration-1.8-miscellaneous-changes:
1653
1654Miscellaneous Changes
1655---------------------
1656
1657The following miscellaneous changes have occurred:
1658
1659- The ``send-error-report`` script now expects a "-s" option to be
1660 specified before the server address. This assumes a server address is
1661 being specified.
1662
1663- The ``oe-pkgdata-util`` script now expects a "-p" option to be
1664 specified before the ``pkgdata`` directory, which is now optional. If
1665 the ``pkgdata`` directory is not specified, the script will run
1666 BitBake to query :term:`PKGDATA_DIR` from the
1667 build environment.
1668
1669Moving to the Yocto Project 2.0 Release
1670=======================================
1671
1672This section provides migration information for moving to the Yocto
1673Project 2.0 Release from the prior release.
1674
1675.. _migration-2.0-gcc-5:
1676
1677GCC 5
1678-----
1679
1680The default compiler is now GCC 5.2. This change has required fixes for
1681compilation errors in a number of other recipes.
1682
1683One important example is a fix for when the Linux kernel freezes at boot
1684time on ARM when built with GCC 5. If you are using your own kernel
1685recipe or source tree and building for ARM, you will likely need to
1686apply this
1687`patch <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit?id=a077224fd35b2f7fbc93f14cf67074fc792fbac2>`__.
1688The standard ``linux-yocto`` kernel source tree already has a workaround
1689for the same issue.
1690
1691For further details, see https://gcc.gnu.org/gcc-5/changes.html
1692and the porting guide at
1693https://gcc.gnu.org/gcc-5/porting_to.html.
1694
1695Alternatively, you can switch back to GCC 4.9 or 4.8 by setting
1696``GCCVERSION`` in your configuration, as follows:
1697::
1698
1699 GCCVERSION = "4.9%"
1700
1701.. _migration-2.0-Gstreamer-0.10-removed:
1702
1703Gstreamer 0.10 Removed
1704----------------------
1705
1706Gstreamer 0.10 has been removed in favor of Gstreamer 1.x. As part of
1707the change, recipes for Gstreamer 0.10 and related software are now
1708located in ``meta-multimedia``. This change results in Qt4 having Phonon
1709and Gstreamer support in QtWebkit disabled by default.
1710
1711.. _migration-2.0-removed-recipes:
1712
1713Removed Recipes
1714---------------
1715
1716The following recipes have been moved or removed:
1717
1718- ``bluez4``: The recipe is obsolete and has been moved due to
1719 ``bluez5`` becoming fully integrated. The ``bluez4`` recipe now
1720 resides in ``meta-oe``.
1721
1722- ``gamin``: The recipe is obsolete and has been removed.
1723
1724- ``gnome-icon-theme``: The recipe's functionally has been replaced by
1725 ``adwaita-icon-theme``.
1726
1727- Gstreamer 0.10 Recipes: Recipes for Gstreamer 0.10 have been removed
1728 in favor of the recipes for Gstreamer 1.x.
1729
1730- ``insserv``: The recipe is obsolete and has been removed.
1731
1732- ``libunique``: The recipe is no longer used and has been moved to
1733 ``meta-oe``.
1734
1735- ``midori``: The recipe's functionally has been replaced by
1736 ``epiphany``.
1737
1738- ``python-gst``: The recipe is obsolete and has been removed since it
1739 only contains bindings for Gstreamer 0.10.
1740
1741- ``qt-mobility``: The recipe is obsolete and has been removed since it
1742 requires ``Gstreamer 0.10``, which has been replaced.
1743
1744- ``subversion``: All 1.6.x versions of this recipe have been removed.
1745
1746- ``webkit-gtk``: The older 1.8.3 version of this recipe has been
1747 removed in favor of ``webkitgtk``.
1748
1749.. _migration-2.0-bitbake-datastore-improvements:
1750
1751BitBake datastore improvements
1752------------------------------
1753
1754The method by which BitBake's datastore handles overrides has changed.
1755Overrides are now applied dynamically and ``bb.data.update_data()`` is
1756now a no-op. Thus, ``bb.data.update_data()`` is no longer required in
1757order to apply the correct overrides. In practice, this change is
1758unlikely to require any changes to Metadata. However, these minor
1759changes in behavior exist:
1760
1761- All potential overrides are now visible in the variable history as
1762 seen when you run the following:
1763 ::
1764
1765 $ bitbake -e
1766
1767- ``d.delVar('``\ VARNAME\ ``')`` and
1768 ``d.setVar('``\ VARNAME\ ``', None)`` result in the variable and all
1769 of its overrides being cleared out. Before the change, only the
1770 non-overridden values were cleared.
1771
1772.. _migration-2.0-shell-message-function-changes:
1773
1774Shell Message Function Changes
1775------------------------------
1776
1777The shell versions of the BitBake message functions (i.e. ``bbdebug``,
1778``bbnote``, ``bbwarn``, ``bbplain``, ``bberror``, and ``bbfatal``) are
1779now connected through to their BitBake equivalents ``bb.debug()``,
1780``bb.note()``, ``bb.warn()``, ``bb.plain()``, ``bb.error()``, and
1781``bb.fatal()``, respectively. Thus, those message functions that you
1782would expect to be printed by the BitBake UI are now actually printed.
1783In practice, this change means two things:
1784
1785- If you now see messages on the console that you did not previously
1786 see as a result of this change, you might need to clean up the calls
1787 to ``bbwarn``, ``bberror``, and so forth. Or, you might want to
1788 simply remove the calls.
1789
1790- The ``bbfatal`` message function now suppresses the full error log in
1791 the UI, which means any calls to ``bbfatal`` where you still wish to
1792 see the full error log should be replaced by ``die`` or
1793 ``bbfatal_log``.
1794
1795.. _migration-2.0-extra-development-debug-package-cleanup:
1796
1797Extra Development/Debug Package Cleanup
1798---------------------------------------
1799
1800The following recipes have had extra ``dev/dbg`` packages removed:
1801
1802- ``acl``
1803
1804- ``apmd``
1805
1806- ``aspell``
1807
1808- ``attr``
1809
1810- ``augeas``
1811
1812- ``bzip2``
1813
1814- ``cogl``
1815
1816- ``curl``
1817
1818- ``elfutils``
1819
1820- ``gcc-target``
1821
1822- ``libgcc``
1823
1824- ``libtool``
1825
1826- ``libxmu``
1827
1828- ``opkg``
1829
1830- ``pciutils``
1831
1832- ``rpm``
1833
1834- ``sysfsutils``
1835
1836- ``tiff``
1837
1838- ``xz``
1839
1840All of the above recipes now conform to the standard packaging scheme
1841where a single ``-dev``, ``-dbg``, and ``-staticdev`` package exists per
1842recipe.
1843
1844.. _migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core:
1845
1846Recipe Maintenance Tracking Data Moved to OE-Core
1847-------------------------------------------------
1848
1849Maintenance tracking data for recipes that was previously part of
1850``meta-yocto`` has been moved to :term:`OpenEmbedded-Core (OE-Core)`. The change
1851includes ``package_regex.inc`` and ``distro_alias.inc``, which are
1852typically enabled when using the ``distrodata`` class. Additionally, the
1853contents of ``upstream_tracking.inc`` has now been split out to the
1854relevant recipes.
1855
1856.. _migration-2.0-automatic-stale-sysroot-file-cleanup:
1857
1858Automatic Stale Sysroot File Cleanup
1859------------------------------------
1860
1861Stale files from recipes that no longer exist in the current
1862configuration are now automatically removed from sysroot as well as
1863removed from any other place managed by shared state. This automatic
1864cleanup means that the build system now properly handles situations such
1865as renaming the build system side of recipes, removal of layers from
1866``bblayers.conf``, and :term:`DISTRO_FEATURES`
1867changes.
1868
1869Additionally, work directories for old versions of recipes are now
1870pruned. If you wish to disable pruning old work directories, you can set
1871the following variable in your configuration:
1872::
1873
1874 SSTATE_PRUNE_OBSOLETEWORKDIR = "0"
1875
1876.. _migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source:
1877
1878``linux-yocto`` Kernel Metadata Repository Now Split from Source
1879----------------------------------------------------------------
1880
1881The ``linux-yocto`` tree has up to now been a combined set of kernel
1882changes and configuration (meta) data carried in a single tree. While
1883this format is effective at keeping kernel configuration and source
1884modifications synchronized, it is not always obvious to developers how
1885to manipulate the Metadata as compared to the source.
1886
1887Metadata processing has now been removed from the
1888:ref:`kernel-yocto <ref-classes-kernel-yocto>` class and the external
1889Metadata repository ``yocto-kernel-cache``, which has always been used
1890to seed the ``linux-yocto`` "meta" branch. This separate ``linux-yocto``
1891cache repository is now the primary location for this data. Due to this
1892change, ``linux-yocto`` is no longer able to process combined trees.
1893Thus, if you need to have your own combined kernel repository, you must
1894do the split there as well and update your recipes accordingly. See the
1895``meta/recipes-kernel/linux/linux-yocto_4.1.bb`` recipe for an example.
1896
1897.. _migration-2.0-additional-qa-checks:
1898
1899Additional QA checks
1900--------------------
1901
1902The following QA checks have been added:
1903
1904- Added a "host-user-contaminated" check for ownership issues for
1905 packaged files outside of ``/home``. The check looks for files that
1906 are incorrectly owned by the user that ran BitBake instead of owned
1907 by a valid user in the target system.
1908
1909- Added an "invalid-chars" check for invalid (non-UTF8) characters in
1910 recipe metadata variable values (i.e.
1911 :term:`DESCRIPTION`,
1912 :term:`SUMMARY`, :term:`LICENSE`, and
1913 :term:`SECTION`). Some package managers do not support
1914 these characters.
1915
1916- Added an "invalid-packageconfig" check for any options specified in
1917 :term:`PACKAGECONFIG` that do not match any
1918 ``PACKAGECONFIG`` option defined for the recipe.
1919
1920.. _migration-2.0-miscellaneous:
1921
1922Miscellaneous Changes
1923---------------------
1924
1925These additional changes exist:
1926
1927- ``gtk-update-icon-cache`` has been renamed to ``gtk-icon-utils``.
1928
1929- The ``tools-profile`` :term:`IMAGE_FEATURES`
1930 item as well as its corresponding packagegroup and
1931 ``packagegroup-core-tools-profile`` no longer bring in ``oprofile``.
1932 Bringing in ``oprofile`` was originally added to aid compilation on
1933 resource-constrained targets. However, this aid has not been widely
1934 used and is not likely to be used going forward due to the more
1935 powerful target platforms and the existence of better
1936 cross-compilation tools.
1937
1938- The :term:`IMAGE_FSTYPES` variable's default
1939 value now specifies ``ext4`` instead of ``ext3``.
1940
1941- All support for the ``PRINC`` variable has been removed.
1942
1943- The ``packagegroup-core-full-cmdline`` packagegroup no longer brings
1944 in ``lighttpd`` due to the fact that bringing in ``lighttpd`` is not
1945 really in line with the packagegroup's purpose, which is to add full
1946 versions of command-line tools that by default are provided by
1947 ``busybox``.
1948
1949Moving to the Yocto Project 2.1 Release
1950=======================================
1951
1952This section provides migration information for moving to the Yocto
1953Project 2.1 Release from the prior release.
1954
1955.. _migration-2.1-variable-expansion-in-python-functions:
1956
1957Variable Expansion in Python Functions
1958--------------------------------------
1959
1960Variable expressions, such as ``${``\ VARNAME\ ``}`` no longer expand
1961automatically within Python functions. Suppressing expansion was done to
1962allow Python functions to construct shell scripts or other code for
1963situations in which you do not want such expressions expanded. For any
1964existing code that relies on these expansions, you need to change the
1965expansions to expand the value of individual variables through
1966``d.getVar()``. To alternatively expand more complex expressions, use
1967``d.expand()``.
1968
1969.. _migration-2.1-overrides-must-now-be-lower-case:
1970
1971Overrides Must Now be Lower-Case
1972--------------------------------
1973
1974The convention for overrides has always been for them to be lower-case
1975characters. This practice is now a requirement as BitBake's datastore
1976now assumes lower-case characters in order to give a slight performance
1977boost during parsing. In practical terms, this requirement means that
1978anything that ends up in :term:`OVERRIDES` must now
1979appear in lower-case characters (e.g. values for ``MACHINE``,
1980``TARGET_ARCH``, ``DISTRO``, and also recipe names if
1981``_pn-``\ recipename overrides are to be effective).
1982
1983.. _migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory:
1984
1985Expand Parameter to ``getVar()`` and ``getVarFlag()`` is Now Mandatory
1986----------------------------------------------------------------------
1987
1988The expand parameter to ``getVar()`` and ``getVarFlag()`` previously
1989defaulted to False if not specified. Now, however, no default exists so
1990one must be specified. You must change any ``getVar()`` calls that do
1991not specify the final expand parameter to calls that do specify the
1992parameter. You can run the following ``sed`` command at the base of a
1993layer to make this change:
1994::
1995
1996 sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
1997 sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
1998
1999.. note::
2000
2001 The reason for this change is that it prepares the way for changing
2002 the default to True in a future Yocto Project release. This future
2003 change is a much more sensible default than False. However, the
2004 change needs to be made gradually as a sudden change of the default
2005 would potentially cause side-effects that would be difficult to
2006 detect.
2007
2008.. _migration-2.1-makefile-environment-changes:
2009
2010Makefile Environment Changes
2011----------------------------
2012
2013:term:`EXTRA_OEMAKE` now defaults to "" instead of
2014"-e MAKEFLAGS=". Setting ``EXTRA_OEMAKE`` to "-e MAKEFLAGS=" by default
2015was a historical accident that has required many classes (e.g.
2016``autotools``, ``module``) and recipes to override this default in order
2017to work with sensible build systems. When upgrading to the release, you
2018must edit any recipe that relies upon this old default by either setting
2019``EXTRA_OEMAKE`` back to "-e MAKEFLAGS=" or by explicitly setting any
2020required variable value overrides using ``EXTRA_OEMAKE``, which is
2021typically only needed when a Makefile sets a default value for a
2022variable that is inappropriate for cross-compilation using the "="
2023operator rather than the "?=" operator.
2024
2025.. _migration-2.1-libexecdir-reverted-to-prefix-libexec:
2026
2027``libexecdir`` Reverted to ``${prefix}/libexec``
2028------------------------------------------------
2029
2030The use of ``${libdir}/${BPN}`` as ``libexecdir`` is different as
2031compared to all other mainstream distributions, which either uses
2032``${prefix}/libexec`` or ``${libdir}``. The use is also contrary to the
2033GNU Coding Standards (i.e.
2034https://www.gnu.org/prep/standards/html_node/Directory-Variables.html)
2035that suggest ``${prefix}/libexec`` and also notes that any
2036package-specific nesting should be done by the package itself. Finally,
2037having ``libexecdir`` change between recipes makes it very difficult for
2038different recipes to invoke binaries that have been installed into
2039``libexecdir``. The Filesystem Hierarchy Standard (i.e.
2040http://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html) now
2041recognizes the use of ``${prefix}/libexec/``, giving distributions the
2042choice between ``${prefix}/lib`` or ``${prefix}/libexec`` without
2043breaking FHS.
2044
2045.. _migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files:
2046
2047``ac_cv_sizeof_off_t`` is No Longer Cached in Site Files
2048--------------------------------------------------------
2049
2050For recipes inheriting the :ref:`autotools <ref-classes-autotools>`
2051class, ``ac_cv_sizeof_off_t`` is no longer cached in the site files for
2052``autoconf``. The reason for this change is because the
2053``ac_cv_sizeof_off_t`` value is not necessarily static per architecture
2054as was previously assumed. Rather, the value changes based on whether
2055large file support is enabled. For most software that uses ``autoconf``,
2056this change should not be a problem. However, if you have a recipe that
2057bypasses the standard :ref:`ref-tasks-configure` task
2058from the ``autotools`` class and the software the recipe is building
2059uses a very old version of ``autoconf``, the recipe might be incapable
2060of determining the correct size of ``off_t`` during ``do_configure``.
2061
2062The best course of action is to patch the software as necessary to allow
2063the default implementation from the ``autotools`` class to work such
2064that ``autoreconf`` succeeds and produces a working configure script,
2065and to remove the overridden ``do_configure`` task such that the default
2066implementation does get used.
2067
2068.. _migration-2.1-image-generation-split-out-from-filesystem-generation:
2069
2070Image Generation is Now Split Out from Filesystem Generation
2071------------------------------------------------------------
2072
2073Previously, for image recipes the :ref:`ref-tasks-rootfs`
2074task assembled the filesystem and then from that filesystem generated
2075images. With this Yocto Project release, image generation is split into
2076separate ```do_image_*`` <#ref-tasks-image>`__ tasks for clarity both in
2077operation and in the code.
2078
2079For most cases, this change does not present any problems. However, if
2080you have made customizations that directly modify the ``do_rootfs`` task
2081or that mention ``do_rootfs``, you might need to update those changes.
2082In particular, if you had added any tasks after ``do_rootfs``, you
2083should make edits so that those tasks are after the
2084```do_image_complete`` <#ref-tasks-image-complete>`__ task rather than
2085after ``do_rootfs`` so that the your added tasks run at the correct
2086time.
2087
2088A minor part of this restructuring is that the post-processing
2089definitions and functions have been moved from the
2090:ref:`image <ref-classes-image>` class to the
2091:ref:`rootfs-postcommands <ref-classes-rootfs*>` class. Functionally,
2092however, they remain unchanged.
2093
2094.. _migration-2.1-removed-recipes:
2095
2096Removed Recipes
2097---------------
2098
2099The following recipes have been removed in the 2.1 release:
2100
2101- ``gcc`` version 4.8: Versions 4.9 and 5.3 remain.
2102
2103- ``qt4``: All support for Qt 4.x has been moved out to a separate
2104 ``meta-qt4`` layer because Qt 4 is no longer supported upstream.
2105
2106- ``x11vnc``: Moved to the ``meta-oe`` layer.
2107
2108- ``linux-yocto-3.14``: No longer supported.
2109
2110- ``linux-yocto-3.19``: No longer supported.
2111
2112- ``libjpeg``: Replaced by the ``libjpeg-turbo`` recipe.
2113
2114- ``pth``: Became obsolete.
2115
2116- ``liboil``: Recipe is no longer needed and has been moved to the
2117 ``meta-multimedia`` layer.
2118
2119- ``gtk-theme-torturer``: Recipe is no longer needed and has been moved
2120 to the ``meta-gnome`` layer.
2121
2122- ``gnome-mime-data``: Recipe is no longer needed and has been moved to
2123 the ``meta-gnome`` layer.
2124
2125- ``udev``: Replaced by the ``eudev`` recipe for compatibility when
2126 using ``sysvinit`` with newer kernels.
2127
2128- ``python-pygtk``: Recipe became obsolete.
2129
2130- ``adt-installer``: Recipe became obsolete. See the "`ADT
2131 Removed <#migration-2.1-adt-removed>`__" section for more
2132 information.
2133
2134.. _migration-2.1-class-changes:
2135
2136Class Changes
2137-------------
2138
2139The following classes have changed:
2140
2141- ``autotools_stage``: Removed because the
2142 :ref:`autotools <ref-classes-autotools>` class now provides its
2143 functionality. Recipes that inherited from ``autotools_stage`` should
2144 now inherit from ``autotools`` instead.
2145
2146- ``boot-directdisk``: Merged into the ``image-vm`` class. The
2147 ``boot-directdisk`` class was rarely directly used. Consequently,
2148 this change should not cause any issues.
2149
2150- ``bootimg``: Merged into the
2151 :ref:`image-live <ref-classes-image-live>` class. The ``bootimg``
2152 class was rarely directly used. Consequently, this change should not
2153 cause any issues.
2154
2155- ``packageinfo``: Removed due to its limited use by the Hob UI, which
2156 has itself been removed.
2157
2158.. _migration-2.1-build-system-ui-changes:
2159
2160Build System User Interface Changes
2161-----------------------------------
2162
2163The following changes have been made to the build system user interface:
2164
2165- *Hob GTK+-based UI*: Removed because it is unmaintained and based on
2166 the outdated GTK+ 2 library. The Toaster web-based UI is much more
2167 capable and is actively maintained. See the
2168 ":ref:`toaster-manual/toaster-manual-setup-and-use:using the toaster web interface`"
2169 section in the Toaster User Manual for more information on this
2170 interface.
2171
2172- *"puccho" BitBake UI*: Removed because is unmaintained and no longer
2173 useful.
2174
2175.. _migration-2.1-adt-removed:
2176
2177ADT Removed
2178-----------
2179
2180The Application Development Toolkit (ADT) has been removed because its
2181functionality almost completely overlapped with the :ref:`standard
2182SDK <sdk-manual/sdk-using:using the standard sdk>` and the
2183:ref:`extensible SDK <sdk-manual/sdk-extensible:using the extensible sdk>`. For
2184information on these SDKs and how to build and use them, see the
2185:doc:`../sdk-manual/sdk-manual` manual.
2186
2187.. note::
2188
2189 The Yocto Project Eclipse IDE Plug-in is still supported and is not
2190 affected by this change.
2191
2192.. _migration-2.1-poky-reference-distribution-changes:
2193
2194Poky Reference Distribution Changes
2195-----------------------------------
2196
2197The following changes have been made for the Poky distribution:
2198
2199- The ``meta-yocto`` layer has been renamed to ``meta-poky`` to better
2200 match its purpose, which is to provide the Poky reference
2201 distribution. The ``meta-yocto-bsp`` layer retains its original name
2202 since it provides reference machines for the Yocto Project and it is
2203 otherwise unrelated to Poky. References to ``meta-yocto`` in your
2204 ``conf/bblayers.conf`` should automatically be updated, so you should
2205 not need to change anything unless you are relying on this naming
2206 elsewhere.
2207
2208- The :ref:`uninative <ref-classes-uninative>` class is now enabled
2209 by default in Poky. This class attempts to isolate the build system
2210 from the host distribution's C library and makes re-use of native
2211 shared state artifacts across different host distributions practical.
2212 With this class enabled, a tarball containing a pre-built C library
2213 is downloaded at the start of the build.
2214
2215 The ``uninative`` class is enabled through the
2216 ``meta/conf/distro/include/yocto-uninative.inc`` file, which for
2217 those not using the Poky distribution, can include to easily enable
2218 the same functionality.
2219
2220 Alternatively, if you wish to build your own ``uninative`` tarball,
2221 you can do so by building the ``uninative-tarball`` recipe, making it
2222 available to your build machines (e.g. over HTTP/HTTPS) and setting a
2223 similar configuration as the one set by ``yocto-uninative.inc``.
2224
2225- Static library generation, for most cases, is now disabled by default
2226 in the Poky distribution. Disabling this generation saves some build
2227 time as well as the size used for build output artifacts.
2228
2229 Disabling this library generation is accomplished through a
2230 ``meta/conf/distro/include/no-static-libs.inc``, which for those not
2231 using the Poky distribution can easily include to enable the same
2232 functionality.
2233
2234 Any recipe that needs to opt-out of having the "--disable-static"
2235 option specified on the configure command line either because it is
2236 not a supported option for the configure script or because static
2237 libraries are needed should set the following variable:
2238 DISABLE_STATIC = ""
2239
2240- The separate ``poky-tiny`` distribution now uses the musl C library
2241 instead of a heavily pared down ``glibc``. Using musl results in a
2242 smaller distribution and facilitates much greater maintainability
2243 because musl is designed to have a small footprint.
2244
2245 If you have used ``poky-tiny`` and have customized the ``glibc``
2246 configuration you will need to redo those customizations with musl
2247 when upgrading to the new release.
2248
2249.. _migration-2.1-packaging-changes:
2250
2251Packaging Changes
2252-----------------
2253
2254The following changes have been made to packaging:
2255
2256- The ``runuser`` and ``mountpoint`` binaries, which were previously in
2257 the main ``util-linux`` package, have been split out into the
2258 ``util-linux-runuser`` and ``util-linux-mountpoint`` packages,
2259 respectively.
2260
2261- The ``python-elementtree`` package has been merged into the
2262 ``python-xml`` package.
2263
2264.. _migration-2.1-tuning-file-changes:
2265
2266Tuning File Changes
2267-------------------
2268
2269The following changes have been made to the tuning files:
2270
2271- The "no-thumb-interwork" tuning feature has been dropped from the ARM
2272 tune include files. Because interworking is required for ARM EABI,
2273 attempting to disable it through a tuning feature no longer makes
2274 sense.
2275
2276 .. note::
2277
2278 Support for ARM OABI was deprecated in gcc 4.7.
2279
2280- The ``tune-cortexm*.inc`` and ``tune-cortexr4.inc`` files have been
2281 removed because they are poorly tested. Until the OpenEmbedded build
2282 system officially gains support for CPUs without an MMU, these tuning
2283 files would probably be better maintained in a separate layer if
2284 needed.
2285
2286.. _migration-2.1-supporting-gobject-introspection:
2287
2288Supporting GObject Introspection
2289--------------------------------
2290
2291This release supports generation of GLib Introspective Repository (GIR)
2292files through GObject introspection, which is the standard mechanism for
2293accessing GObject-based software from runtime environments. You can
2294enable, disable, and test the generation of this data. See the
2295":ref:`dev-manual/dev-manual-common-tasks:enabling gobject introspection support`"
2296section in the Yocto Project Development Tasks Manual for more
2297information.
2298
2299.. _migration-2.1-miscellaneous-changes:
2300
2301Miscellaneous Changes
2302---------------------
2303
2304These additional changes exist:
2305
2306- The minimum Git version has been increased to 1.8.3.1. If your host
2307 distribution does not provide a sufficiently recent version, you can
2308 install the buildtools, which will provide it. See the "`Required
2309 Git, tar, Python and gcc
2310 Versions <#required-git-tar-python-and-gcc-versions>`__" section for
2311 more information on the buildtools tarball.
2312
2313- The buggy and incomplete support for the RPM version 4 package
2314 manager has been removed. The well-tested and maintained support for
2315 RPM version 5 remains.
2316
2317- Previously, the following list of packages were removed if
2318 package-management was not in
2319 :term:`IMAGE_FEATURES`, regardless of any
2320 dependencies:
2321 ::
2322
2323 update-rc.d
2324 base-passwd
2325 shadow
2326 update-alternatives
2327
2328 run-postinsts With the Yocto Project 2.1 release, these packages are
2329 only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since
2330 they might still be needed for a read-write image even in the absence
2331 of a package manager (e.g. if users need to be added, modified, or
2332 removed at runtime).
2333
2334- The
2335 :ref:`devtool modify <sdk-manual/sdk-extensible:use \`\`devtool modify\`\` to modify the source of an existing component>`
2336 command now defaults to extracting the source since that is most
2337 commonly expected. The "-x" or "--extract" options are now no-ops. If
2338 you wish to provide your own existing source tree, you will now need
2339 to specify either the "-n" or "--no-extract" options when running
2340 ``devtool modify``.
2341
2342- If the formfactor for a machine is either not supplied or does not
2343 specify whether a keyboard is attached, then the default is to assume
2344 a keyboard is attached rather than assume no keyboard. This change
2345 primarily affects the Sato UI.
2346
2347- The ``.debug`` directory packaging is now automatic. If your recipe
2348 builds software that installs binaries into directories other than
2349 the standard ones, you no longer need to take care of setting
2350 ``FILES_${PN}-dbg`` to pick up the resulting ``.debug`` directories
2351 as these directories are automatically found and added.
2352
2353- Inaccurate disk and CPU percentage data has been dropped from
2354 ``buildstats`` output. This data has been replaced with
2355 ``getrusage()`` data and corrected IO statistics. You will probably
2356 need to update any custom code that reads the ``buildstats`` data.
2357
2358- The ``meta/conf/distro/include/package_regex.inc`` is now deprecated.
2359 The contents of this file have been moved to individual recipes.
2360
2361 .. note::
2362
2363 Because this file will likely be removed in a future Yocto Project
2364 release, it is suggested that you remove any references to the
2365 file that might be in your configuration.
2366
2367- The ``v86d/uvesafb`` has been removed from the ``genericx86`` and
2368 ``genericx86-64`` reference machines, which are provided by the
2369 ``meta-yocto-bsp`` layer. Most modern x86 boards do not rely on this
2370 file and it only adds kernel error messages during startup. If you do
2371 still need to support ``uvesafb``, you can simply add ``v86d`` to
2372 your image.
2373
2374- Build sysroot paths are now removed from debug symbol files. Removing
2375 these paths means that remote GDB using an unstripped build system
2376 sysroot will no longer work (although this was never documented to
2377 work). The supported method to accomplish something similar is to set
2378 ``IMAGE_GEN_DEBUGFS`` to "1", which will generate a companion debug
2379 image containing unstripped binaries and associated debug sources
2380 alongside the image.
2381
2382Moving to the Yocto Project 2.2 Release
2383=======================================
2384
2385This section provides migration information for moving to the Yocto
2386Project 2.2 Release from the prior release.
2387
2388.. _migration-2.2-minimum-kernel-version:
2389
2390Minimum Kernel Version
2391----------------------
2392
2393The minimum kernel version for the target system and for SDK is now
23943.2.0, due to the upgrade to ``glibc 2.24``. Specifically, for
2395AArch64-based targets the version is 3.14. For Nios II-based targets,
2396the minimum kernel version is 3.19.
2397
2398.. note::
2399
2400 For x86 and x86_64, you can reset
2401 OLDEST_KERNEL
2402 to anything down to 2.6.32 if desired.
2403
2404.. _migration-2.2-staging-directories-in-sysroot-simplified:
2405
2406Staging Directories in Sysroot Has Been Simplified
2407--------------------------------------------------
2408
2409The way directories are staged in sysroot has been simplified and
2410introduces the new :term:`SYSROOT_DIRS`,
2411:term:`SYSROOT_DIRS_NATIVE`, and
2412:term:`SYSROOT_DIRS_BLACKLIST`. See the
2413`v2 patch series on the OE-Core Mailing
2414List <http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html>`__
2415for additional information.
2416
2417.. _migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled:
2418
2419Removal of Old Images and Other Files in ``tmp/deploy`` Now Enabled
2420-------------------------------------------------------------------
2421
2422Removal of old images and other files in ``tmp/deploy/`` is now enabled
2423by default due to a new staging method used for those files. As a result
2424of this change, the ``RM_OLD_IMAGE`` variable is now redundant.
2425
2426.. _migration-2.2-python-changes:
2427
2428Python Changes
2429--------------
2430
2431The following changes for Python occurred:
2432
2433.. _migration-2.2-bitbake-now-requires-python-3.4:
2434
2435BitBake Now Requires Python 3.4+
2436~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2437
2438BitBake requires Python 3.4 or greater.
2439
2440.. _migration-2.2-utf-8-locale-required-on-build-host:
2441
2442UTF-8 Locale Required on Build Host
2443~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2444
2445A UTF-8 locale is required on the build host due to Python 3. Since
2446C.UTF-8 is not a standard, the default is en_US.UTF-8.
2447
2448.. _migration-2.2-metadata-now-must-use-python-3-syntax:
2449
2450Metadata Must Now Use Python 3 Syntax
2451~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2452
2453The metadata is now required to use Python 3 syntax. For help preparing
2454metadata, see any of the many Python 3 porting guides available.
2455Alternatively, you can reference the conversion commits for Bitbake and
2456you can use :term:`OpenEmbedded-Core (OE-Core)` as a guide for changes. Following are
2457particular areas of interest:
2458
2459 - subprocess command-line pipes needing locale decoding
2460
2461 - the syntax for octal values changed
2462
2463 - the ``iter*()`` functions changed name \* iterators now return views, not lists
2464
2465 - changed names for Python modules
2466
2467.. _migration-2.2-target-python-recipes-switched-to-python-3:
2468
2469Target Python Recipes Switched to Python 3
2470~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2471
2472Most target Python recipes have now been switched to Python 3.
2473Unfortunately, systems using RPM as a package manager and providing
2474online package-manager support through SMART still require Python 2.
2475
2476.. note::
2477
2478 Python 2 and recipes that use it can still be built for the target as
2479 with previous versions.
2480
2481.. _migration-2.2-buildtools-tarball-includes-python-3:
2482
2483``buildtools-tarball`` Includes Python 3
2484~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2485
2486``buildtools-tarball`` now includes Python 3.
2487
2488.. _migration-2.2-uclibc-replaced-by-musl:
2489
2490uClibc Replaced by musl
2491-----------------------
2492
2493uClibc has been removed in favor of musl. Musl has matured, is better
2494maintained, and is compatible with a wider range of applications as
2495compared to uClibc.
2496
2497.. _migration-2.2-B-no-longer-default-working-directory-for-tasks:
2498
2499``${B}`` No Longer Default Working Directory for Tasks
2500------------------------------------------------------
2501
2502``${``\ :term:`B`\ ``}`` is no longer the default working
2503directory for tasks. Consequently, any custom tasks you define now need
2504to either have the
2505``[``\ :ref:`dirs <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` flag
2506set, or the task needs to change into the appropriate working directory
2507manually (e.g using ``cd`` for a shell task).
2508
2509.. note::
2510
2511 The preferred method is to use the
2512 [dirs]
2513 flag.
2514
2515.. _migration-2.2-runqemu-ported-to-python:
2516
2517``runqemu`` Ported to Python
2518----------------------------
2519
2520``runqemu`` has been ported to Python and has changed behavior in some
2521cases. Previous usage patterns continue to be supported.
2522
2523The new ``runqemu`` is a Python script. Machine knowledge is no longer
2524hardcoded into ``runqemu``. You can choose to use the ``qemuboot``
2525configuration file to define the BSP's own arguments and to make it
2526bootable with ``runqemu``. If you use a configuration file, use the
2527following form:
2528::
2529
2530 image-name-machine.qemuboot.conf
2531
2532The configuration file
2533enables fine-grained tuning of options passed to QEMU without the
2534``runqemu`` script hard-coding any knowledge about different machines.
2535Using a configuration file is particularly convenient when trying to use
2536QEMU with machines other than the ``qemu*`` machines in
2537:term:`OpenEmbedded-Core (OE-Core)`. The ``qemuboot.conf`` file is generated by the
2538``qemuboot`` class when the root filesystem is being build (i.e. build
2539rootfs). QEMU boot arguments can be set in BSP's configuration file and
2540the ``qemuboot`` class will save them to ``qemuboot.conf``.
2541
2542If you want to use ``runqemu`` without a configuration file, use the
2543following command form:
2544::
2545
2546 $ runqemu machine rootfs kernel [options]
2547
2548Supported machines are as follows:
2549
2550 - qemuarm
2551 - qemuarm64
2552 - qemux86
2553 - qemux86-64
2554 - qemuppc
2555 - qemumips
2556 - qemumips64
2557 - qemumipsel
2558 - qemumips64el
2559
2560Consider the
2561following example, which uses the ``qemux86-64`` machine, provides a
2562root filesystem, provides an image, and uses the ``nographic`` option: ::
2563
2564 $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
2565
2566Following is a list of variables that can be set in configuration files
2567such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``:
2568
2569.. note::
2570
2571 "QB" means "QEMU Boot".
2572
2573::
2574
2575 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
2576 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
2577 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
2578 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
2579 QB_MEM: Memory (e.g. "-m 512")
2580 QB_MACHINE: QEMU machine (e.g. "-machine virt")
2581 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
2582 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
2583 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
2584 option (e.g. "console=ttyS0 console=tty")
2585 QB_DTB: QEMU dtb name
2586 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
2587 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
2588 when QB_AUDIO_DRV is set.
2589 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
2590 QB_TAP_OPT: Network option for 'tap' mode (e.g.
2591 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
2592 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
2593 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
2594 QB_ROOTFS_OPT: Used as rootfs (e.g.
2595 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
2596 runqemu will replace "@ROOTFS@" with the one which is used, such as
2597 core-image-minimal-qemuarm64.ext4.
2598 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
2599 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
2600 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
2601 runqemu will replace "@PORT@" with the port number which is used.
2602
2603To use ``runqemu``, set :term:`IMAGE_CLASSES` as
2604follows and run ``runqemu``:
2605
2606.. note::
2607
2608 For command-line syntax, use
2609 runqemu help
2610 .
2611
2612::
2613
2614 IMAGE_CLASSES += "qemuboot"
2615
2616.. _migration-2.2-default-linker-hash-style-changed:
2617
2618Default Linker Hash Style Changed
2619---------------------------------
2620
2621The default linker hash style for ``gcc-cross`` is now "sysv" in order
2622to catch recipes that are building software without using the
2623OpenEmbedded :term:`LDFLAGS`. This change could result in
2624seeing some "No GNU_HASH in the elf binary" QA issues when building such
2625recipes. You need to fix these recipes so that they use the expected
2626``LDFLAGS``. Depending on how the software is built, the build system
2627used by the software (e.g. a Makefile) might need to be patched.
2628However, sometimes making this fix is as simple as adding the following
2629to the recipe:
2630::
2631
2632 TARGET_CC_ARCH += "${LDFLAGS}"
2633
2634.. _migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype:
2635
2636``KERNEL_IMAGE_BASE_NAME`` no Longer Uses ``KERNEL_IMAGETYPE``
2637--------------------------------------------------------------
2638
2639The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the
2640:term:`KERNEL_IMAGETYPE` variable to create the
2641image's base name. Because the OpenEmbedded build system can now build
2642multiple kernel image types, this part of the kernel image base name as
2643been removed leaving only the following:
2644::
2645
2646 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
2647
2648If you have recipes or
2649classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to
2650update the references to ensure they continue to work.
2651
2652.. _migration-2.2-bitbake-changes:
2653
2654BitBake Changes
2655---------------
2656
2657The following changes took place for BitBake:
2658
2659- The "goggle" UI and standalone image-writer tool have been removed as
2660 they both require GTK+ 2.0 and were not being maintained.
2661
2662- The Perforce fetcher now supports :term:`SRCREV` for
2663 specifying the source revision to use, be it
2664 ``${``\ :term:`AUTOREV`\ ``}``, changelist number,
2665 p4date, or label, in preference to separate
2666 :term:`SRC_URI` parameters to specify these. This
2667 change is more in-line with how the other fetchers work for source
2668 control systems. Recipes that fetch from Perforce will need to be
2669 updated to use ``SRCREV`` in place of specifying the source revision
2670 within ``SRC_URI``.
2671
2672- Some of BitBake's internal code structures for accessing the recipe
2673 cache needed to be changed to support the new multi-configuration
2674 functionality. These changes will affect external tools that use
2675 BitBake's tinfoil module. For information on these changes, see the
2676 changes made to the scripts supplied with OpenEmbedded-Core:
2677 `1 <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>`__
2678 and
2679 `2 <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`__.
2680
2681- The task management code has been rewritten to avoid using ID
2682 indirection in order to improve performance. This change is unlikely
2683 to cause any problems for most users. However, the setscene
2684 verification function as pointed to by
2685 ``BB_SETSCENE_VERIFY_FUNCTION`` needed to change signature.
2686 Consequently, a new variable named ``BB_SETSCENE_VERIFY_FUNCTION2``
2687 has been added allowing multiple versions of BitBake to work with
2688 suitably written metadata, which includes OpenEmbedded-Core and Poky.
2689 Anyone with custom BitBake task scheduler code might also need to
2690 update the code to handle the new structure.
2691
2692.. _migration-2.2-swabber-has-been-removed:
2693
2694Swabber has Been Removed
2695------------------------
2696
2697Swabber, a tool that was intended to detect host contamination in the
2698build process, has been removed, as it has been unmaintained and unused
2699for some time and was never particularly effective. The OpenEmbedded
2700build system has since incorporated a number of mechanisms including
2701enhanced QA checks that mean that there is less of a need for such a
2702tool.
2703
2704.. _migration-2.2-removed-recipes:
2705
2706Removed Recipes
2707---------------
2708
2709The following recipes have been removed:
2710
2711- ``augeas``: No longer needed and has been moved to ``meta-oe``.
2712
2713- ``directfb``: Unmaintained and has been moved to ``meta-oe``.
2714
2715- ``gcc``: Removed 4.9 version. Versions 5.4 and 6.2 are still present.
2716
2717- ``gnome-doc-utils``: No longer needed.
2718
2719- ``gtk-doc-stub``: Replaced by ``gtk-doc``.
2720
2721- ``gtk-engines``: No longer needed and has been moved to
2722 ``meta-gnome``.
2723
2724- ``gtk-sato-engine``: Became obsolete.
2725
2726- ``libglade``: No longer needed and has been moved to ``meta-oe``.
2727
2728- ``libmad``: Unmaintained and functionally replaced by ``libmpg123``.
2729 ``libmad`` has been moved to ``meta-oe``.
2730
2731- ``libowl``: Became obsolete.
2732
2733- ``libxsettings-client``: No longer needed.
2734
2735- ``oh-puzzles``: Functionally replaced by ``puzzles``.
2736
2737- ``oprofileui``: Became obsolete. OProfile has been largely supplanted
2738 by perf.
2739
2740- ``packagegroup-core-directfb.bb``: Removed.
2741
2742- ``core-image-directfb.bb``: Removed.
2743
2744- ``pointercal``: No longer needed and has been moved to ``meta-oe``.
2745
2746- ``python-imaging``: No longer needed and moved to ``meta-python``
2747
2748- ``python-pyrex``: No longer needed and moved to ``meta-python``.
2749
2750- ``sato-icon-theme``: Became obsolete.
2751
2752- ``swabber-native``: Swabber has been removed. See the `entry on
2753 Swabber <#migration-2.2-swabber-has-been-removed>`__.
2754
2755- ``tslib``: No longer needed and has been moved to ``meta-oe``.
2756
2757- ``uclibc``: Removed in favor of musl.
2758
2759- ``xtscal``: No longer needed and moved to ``meta-oe``
2760
2761.. _migration-2.2-removed-classes:
2762
2763Removed Classes
2764---------------
2765
2766The following classes have been removed:
2767
2768- ``distutils-native-base``: No longer needed.
2769
2770- ``distutils3-native-base``: No longer needed.
2771
2772- ``sdl``: Only set :term:`DEPENDS` and
2773 :term:`SECTION`, which are better set within the
2774 recipe instead.
2775
2776- ``sip``: Mostly unused.
2777
2778- ``swabber``: See the `entry on
2779 Swabber <#migration-2.2-swabber-has-been-removed>`__.
2780
2781.. _migration-2.2-minor-packaging-changes:
2782
2783Minor Packaging Changes
2784-----------------------
2785
2786The following minor packaging changes have occurred:
2787
2788- ``grub``: Split ``grub-editenv`` into its own package.
2789
2790- ``systemd``: Split container and vm related units into a new package,
2791 systemd-container.
2792
2793- ``util-linux``: Moved ``prlimit`` to a separate
2794 ``util-linux-prlimit`` package.
2795
2796.. _migration-2.2-miscellaneous-changes:
2797
2798Miscellaneous Changes
2799---------------------
2800
2801The following miscellaneous changes have occurred:
2802
2803- ``package_regex.inc``: Removed because the definitions
2804 ``package_regex.inc`` previously contained have been moved to their
2805 respective recipes.
2806
2807- Both ``devtool add`` and ``recipetool create`` now use a fixed
2808 :term:`SRCREV` by default when fetching from a Git
2809 repository. You can override this in either case to use
2810 ``${``\ :term:`AUTOREV`\ ``}`` instead by using the
2811 ``-a`` or ``DASHDASHautorev`` command-line option
2812
2813- ``distcc``: GTK+ UI is now disabled by default.
2814
2815- ``packagegroup-core-tools-testapps``: Removed Piglit.
2816
2817- ``image.bbclass``: Renamed COMPRESS(ION) to CONVERSION. This change
2818 means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and
2819 ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``,
2820 ``CONVERSION_DEPENDS`` and ``CONVERSION_CMD``. The ``COMPRESS*``
2821 variable names will still work in the 2.2 release but metadata that
2822 does not need to be backwards-compatible should be changed to use the
2823 new names as the ``COMPRESS*`` ones will be removed in a future
2824 release.
2825
2826- ``gtk-doc``: A full version of ``gtk-doc`` is now made available.
2827 However, some old software might not be capable of using the current
2828 version of ``gtk-doc`` to build documentation. You need to change
2829 recipes that build such software so that they explicitly disable
2830 building documentation with ``gtk-doc``.
2831
2832Moving to the Yocto Project 2.3 Release
2833=======================================
2834
2835This section provides migration information for moving to the Yocto
2836Project 2.3 Release from the prior release.
2837
2838.. _migration-2.3-recipe-specific-sysroots:
2839
2840Recipe-specific Sysroots
2841------------------------
2842
2843The OpenEmbedded build system now uses one sysroot per recipe to resolve
2844long-standing issues with configuration script auto-detection of
2845undeclared dependencies. Consequently, you might find that some of your
2846previously written custom recipes are missing declared dependencies,
2847particularly those dependencies that are incidentally built earlier in a
2848typical build process and thus are already likely to be present in the
2849shared sysroot in previous releases.
2850
2851Consider the following:
2852
2853- *Declare Build-Time Dependencies:* Because of this new feature, you
2854 must explicitly declare all build-time dependencies for your recipe.
2855 If you do not declare these dependencies, they are not populated into
2856 the sysroot for the recipe.
2857
2858- *Specify Pre-Installation and Post-Installation Native Tool
2859 Dependencies:* You must specifically specify any special native tool
2860 dependencies of ``pkg_preinst`` and ``pkg_postinst`` scripts by using
2861 the :term:`PACKAGE_WRITE_DEPS` variable.
2862 Specifying these dependencies ensures that these tools are available
2863 if these scripts need to be run on the build host during the
2864 :ref:`ref-tasks-rootfs` task.
2865
2866 As an example, see the ``dbus`` recipe. You will see that this recipe
2867 has a ``pkg_postinst`` that calls ``systemctl`` if "systemd" is in
2868 :term:`DISTRO_FEATURES`. In the example,
2869 ``systemd-systemctl-native`` is added to ``PACKAGE_WRITE_DEPS``,
2870 which is also conditional on "systemd" being in ``DISTRO_FEATURES``.
2871
2872- Examine Recipes that Use ``SSTATEPOSTINSTFUNCS``: You need to
2873 examine any recipe that uses ``SSTATEPOSTINSTFUNCS`` and determine
2874 steps to take.
2875
2876 Functions added to ``SSTATEPOSTINSTFUNCS`` are still called as they
2877 were in previous Yocto Project releases. However, since a separate
2878 sysroot is now being populated for every recipe and if existing
2879 functions being called through ``SSTATEPOSTINSTFUNCS`` are doing
2880 relocation, then you will need to change these to use a
2881 post-installation script that is installed by a function added to
2882 :term:`SYSROOT_PREPROCESS_FUNCS`.
2883
2884 For an example, see the ``pixbufcache`` class in ``meta/classes/`` in
2885 the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`.
2886
2887 .. note::
2888
2889 The
2890 SSTATEPOSTINSTFUNCS
2891 variable itself is now deprecated in favor of the
2892 do_populate_sysroot[postfuncs]
2893 task. Consequently, if you do still have any function or functions
2894 that need to be called after the sysroot component is created for
2895 a recipe, then you would be well advised to take steps to use a
2896 post installation script as described previously. Taking these
2897 steps prepares your code for when
2898 SSTATEPOSTINSTFUNCS
2899 is removed in a future Yocto Project release.
2900
2901- *Specify the Sysroot when Using Certain External Scripts:* Because
2902 the shared sysroot is now gone, the scripts
2903 ``oe-find-native-sysroot`` and ``oe-run-native`` have been changed
2904 such that you need to specify which recipe's
2905 :term:`STAGING_DIR_NATIVE` is used.
2906
2907.. note::
2908
2909 You can find more information on how recipe-specific sysroots work in
2910 the "
2911 staging.bbclass
2912 " section.
2913
2914.. _migration-2.3-path-variable:
2915
2916``PATH`` Variable
2917-----------------
2918
2919Within the environment used to run build tasks, the environment variable
2920``PATH`` is now sanitized such that the normal native binary paths
2921(``/bin``, ``/sbin``, ``/usr/bin`` and so forth) are removed and a
2922directory containing symbolic links linking only to the binaries from
2923the host mentioned in the :term:`HOSTTOOLS` and
2924:term:`HOSTTOOLS_NONFATAL` variables is added
2925to ``PATH``.
2926
2927Consequently, any native binaries provided by the host that you need to
2928call needs to be in one of these two variables at the configuration
2929level.
2930
2931Alternatively, you can add a native recipe (i.e. ``-native``) that
2932provides the binary to the recipe's :term:`DEPENDS`
2933value.
2934
2935.. note::
2936
2937 PATH
2938 is not sanitized in the same way within
2939 devshell
2940 . If it were, you would have difficulty running host tools for
2941 development and debugging within the shell.
2942
2943.. _migration-2.3-scripts:
2944
2945Changes to Scripts
2946------------------
2947
2948The following changes to scripts took place:
2949
2950- ``oe-find-native-sysroot``: The usage for the
2951 ``oe-find-native-sysroot`` script has changed to the following:
2952 ::
2953
2954 $ . oe-find-native-sysroot recipe
2955
2956 You must now supply a recipe for recipe
2957 as part of the command. Prior to the Yocto Project &DISTRO; release, it
2958 was not necessary to provide the script with the command.
2959
2960- ``oe-run-native``: The usage for the ``oe-run-native`` script has
2961 changed to the following:
2962 ::
2963
2964 $ oe-run-native native_recipe tool
2965
2966 You must
2967 supply the name of the native recipe and the tool you want to run as
2968 part of the command. Prior to the Yocto Project DISTRO release, it
2969 was not necessary to provide the native recipe with the command.
2970
2971- ``cleanup-workdir``: The ``cleanup-workdir`` script has been
2972 removed because the script was found to be deleting files it should
2973 not have, which lead to broken build trees. Rather than trying to
2974 delete portions of :term:`TMPDIR` and getting it wrong,
2975 it is recommended that you delete ``TMPDIR`` and have it restored
2976 from shared state (sstate) on subsequent builds.
2977
2978- ``wipe-sysroot``: The ``wipe-sysroot`` script has been removed as
2979 it is no longer needed with recipe-specific sysroots.
2980
2981.. _migration-2.3-functions:
2982
2983Changes to Functions
2984--------------------
2985
2986The previously deprecated ``bb.data.getVar()``, ``bb.data.setVar()``,
2987and related functions have been removed in favor of ``d.getVar()``,
2988``d.setVar()``, and so forth.
2989
2990You need to fix any references to these old functions.
2991
2992.. _migration-2.3-bitbake-changes:
2993
2994BitBake Changes
2995---------------
2996
2997The following changes took place for BitBake:
2998
2999- *BitBake's Graphical Dependency Explorer UI Replaced:* BitBake's
3000 graphical dependency explorer UI ``depexp`` was replaced by
3001 ``taskexp`` ("Task Explorer"), which provides a graphical way of
3002 exploring the ``task-depends.dot`` file. The data presented by Task
3003 Explorer is much more accurate than the data that was presented by
3004 ``depexp``. Being able to visualize the data is an often requested
3005 feature as standard ``*.dot`` file viewers cannot usual cope with the
3006 size of the ``task-depends.dot`` file.
3007
3008- *BitBake "-g" Output Changes:* The ``package-depends.dot`` and
3009 ``pn-depends.dot`` files as previously generated using the
3010 ``bitbake -g`` command have been removed. A ``recipe-depends.dot``
3011 file is now generated as a collapsed version of ``task-depends.dot``
3012 instead.
3013
3014 The reason for this change is because ``package-depends.dot`` and
3015 ``pn-depends.dot`` largely date back to a time before task-based
3016 execution and do not take into account task-level dependencies
3017 between recipes, which could be misleading.
3018
3019- *Mirror Variable Splitting Changes:* Mirror variables including
3020 :term:`MIRRORS`, :term:`PREMIRRORS`,
3021 and :term:`SSTATE_MIRRORS` can now separate
3022 values entirely with spaces. Consequently, you no longer need "\\n".
3023 BitBake looks for pairs of values, which simplifies usage. There
3024 should be no change required to existing mirror variable values
3025 themselves.
3026
3027- *The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an
3028 "rsh" Parameter:* The SVN fetcher now takes an "ssh" parameter
3029 instead of an "rsh" parameter. This new optional parameter is used
3030 when the "protocol" parameter is set to "svn+ssh". You can only use
3031 the new parameter to specify the ``ssh`` program used by SVN. The SVN
3032 fetcher passes the new parameter through the ``SVN_SSH`` environment
3033 variable during the :ref:`ref-tasks-fetch` task.
3034
3035 See the ":ref:`bitbake:svn-fetcher`"
3036 section in the BitBake
3037 User Manual for additional information.
3038
3039- ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2``
3040 Removed: Because the mechanism they were part of is no longer
3041 necessary with recipe-specific sysroots, the
3042 ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2``
3043 variables have been removed.
3044
3045.. _migration-2.3-absolute-symlinks:
3046
3047Absolute Symbolic Links
3048-----------------------
3049
3050Absolute symbolic links (symlinks) within staged files are no longer
3051permitted and now trigger an error. Any explicit creation of symlinks
3052can use the ``lnr`` script, which is a replacement for ``ln -r``.
3053
3054If the build scripts in the software that the recipe is building are
3055creating a number of absolute symlinks that need to be corrected, you
3056can inherit ``relative_symlinks`` within the recipe to turn those
3057absolute symlinks into relative symlinks.
3058
3059.. _migration-2.3-gplv2-and-gplv3-moves:
3060
3061GPLv2 Versions of GPLv3 Recipes Moved
3062-------------------------------------
3063
3064Older GPLv2 versions of GPLv3 recipes have moved to a separate
3065``meta-gplv2`` layer.
3066
3067If you use :term:`INCOMPATIBLE_LICENSE` to
3068exclude GPLv3 or set :term:`PREFERRED_VERSION`
3069to substitute a GPLv2 version of a GPLv3 recipe, then you must add the
3070``meta-gplv2`` layer to your configuration.
3071
3072.. note::
3073
3074 You can find
3075 meta-gplv2
3076 layer in the OpenEmbedded layer index at
3077 .
3078
3079These relocated GPLv2 recipes do not receive the same level of
3080maintenance as other core recipes. The recipes do not get security fixes
3081and upstream no longer maintains them. In fact, the upstream community
3082is actively hostile towards people that use the old versions of the
3083recipes. Moving these recipes into a separate layer both makes the
3084different needs of the recipes clearer and clearly identifies the number
3085of these recipes.
3086
3087.. note::
3088
3089 The long-term solution might be to move to BSD-licensed replacements
3090 of the GPLv3 components for those that need to exclude GPLv3-licensed
3091 components from the target system. This solution will be investigated
3092 for future Yocto Project releases.
3093
3094.. _migration-2.3-package-management-changes:
3095
3096Package Management Changes
3097--------------------------
3098
3099The following package management changes took place:
3100
3101- Smart package manager is replaced by DNF package manager. Smart has
3102 become unmaintained upstream, is not ported to Python 3.x.
3103 Consequently, Smart needed to be replaced. DNF is the only feasible
3104 candidate.
3105
3106 The change in functionality is that the on-target runtime package
3107 management from remote package feeds is now done with a different
3108 tool that has a different set of command-line options. If you have
3109 scripts that call the tool directly, or use its API, they need to be
3110 fixed.
3111
3112 For more information, see the `DNF
3113 Documentation <http://dnf.readthedocs.io/en/latest/>`__.
3114
3115- Rpm 5.x is replaced with Rpm 4.x. This is done for two major reasons:
3116
3117 - DNF is API-incompatible with Rpm 5.x and porting it and
3118 maintaining the port is non-trivial.
3119
3120 - Rpm 5.x itself has limited maintenance upstream, and the Yocto
3121 Project is one of the very few remaining users.
3122
3123- Berkeley DB 6.x is removed and Berkeley DB 5.x becomes the default:
3124
3125 - Version 6.x of Berkeley DB has largely been rejected by the open
3126 source community due to its AGPLv3 license. As a result, most
3127 mainstream open source projects that require DB are still
3128 developed and tested with DB 5.x.
3129
3130 - In OE-core, the only thing that was requiring DB 6.x was Rpm 5.x.
3131 Thus, no reason exists to continue carrying DB 6.x in OE-core.
3132
3133- ``createrepo`` is replaced with ``createrepo_c``.
3134
3135 ``createrepo_c`` is the current incarnation of the tool that
3136 generates remote repository metadata. It is written in C as compared
3137 to ``createrepo``, which is written in Python. ``createrepo_c`` is
3138 faster and is maintained.
3139
3140- Architecture-independent RPM packages are "noarch" instead of "all".
3141
3142 This change was made because too many places in DNF/RPM4 stack
3143 already make that assumption. Only the filenames and the architecture
3144 tag has changed. Nothing else has changed in OE-core system,
3145 particularly in the :ref:`allarch.bbclass <ref-classes-allarch>`
3146 class.
3147
3148- Signing of remote package feeds using ``PACKAGE_FEED_SIGN`` is not
3149 currently supported. This issue will be fully addressed in a future
3150 Yocto Project release. See `defect
3151 11209 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209>`__
3152 for more information on a solution to package feed signing with RPM
3153 in the Yocto Project 2.3 release.
3154
3155- OPKG now uses the libsolv backend for resolving package dependencies
3156 by default. This is vastly superior to OPKG's internal ad-hoc solver
3157 that was previously used. This change does have a small impact on
3158 disk (around 500 KB) and memory footprint.
3159
3160 .. note::
3161
3162 For further details on this change, see the
3163 commit message
3164 .
3165
3166.. _migration-2.3-removed-recipes:
3167
3168Removed Recipes
3169---------------
3170
3171The following recipes have been removed:
3172
3173- ``linux-yocto 4.8``: Version 4.8 has been removed. Versions 4.1
3174 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 are now present.
3175
3176- ``python-smartpm``: Functionally replaced by ``dnf``.
3177
3178- ``createrepo``: Replaced by the ``createrepo-c`` recipe.
3179
3180- ``rpmresolve``: No longer needed with the move to RPM 4 as RPM
3181 itself is used instead.
3182
3183- ``gstreamer``: Removed the GStreamer Git version recipes as they
3184 have been stale. ``1.10.``\ x recipes are still present.
3185
3186- ``alsa-conf-base``: Merged into ``alsa-conf`` since ``libasound``
3187 depended on both. Essentially, no way existed to install only one of
3188 these.
3189
3190- ``tremor``: Moved to ``meta-multimedia``. Fixed-integer Vorbis
3191 decoding is not needed by current hardware. Thus, GStreamer's ivorbis
3192 plugin has been disabled by default eliminating the need for the
3193 ``tremor`` recipe in :term:`OpenEmbedded-Core (OE-Core)`.
3194
3195- ``gummiboot``: Replaced by ``systemd-boot``.
3196
3197.. _migration-2.3-wic-changes:
3198
3199Wic Changes
3200-----------
3201
3202The following changes have been made to Wic:
3203
3204.. note::
3205
3206 For more information on Wic, see the "
3207 Creating Partitioned Images Using Wic
3208 " section in the Yocto Project Development Tasks Manual.
3209
3210- *Default Output Directory Changed:* Wic's default output directory is
3211 now the current directory by default instead of the unusual
3212 ``/var/tmp/wic``.
3213
3214 The "-o" and "--outdir" options remain unchanged and are used to
3215 specify your preferred output directory if you do not want to use the
3216 default directory.
3217
3218- *fsimage Plug-in Removed:* The Wic fsimage plugin has been removed as
3219 it duplicates functionality of the rawcopy plugin.
3220
3221.. _migration-2.3-qa-changes:
3222
3223QA Changes
3224----------
3225
3226The following QA checks have changed:
3227
3228- ``unsafe-references-in-binaries``: The
3229 ``unsafe-references-in-binaries`` QA check, which was disabled by
3230 default, has now been removed. This check was intended to detect
3231 binaries in ``/bin`` that link to libraries in ``/usr/lib`` and have
3232 the case where the user has ``/usr`` on a separate filesystem to
3233 ``/``.
3234
3235 The removed QA check was buggy. Additionally, ``/usr`` residing on a
3236 separate partition from ``/`` is now a rare configuration.
3237 Consequently, ``unsafe-references-in-binaries`` was removed.
3238
3239- ``file-rdeps``: The ``file-rdeps`` QA check is now an error by
3240 default instead of a warning. Because it is an error instead of a
3241 warning, you need to address missing runtime dependencies.
3242
3243 For additional information, see the
3244 :ref:`insane <ref-classes-insane>` class and the "`Errors and
3245 Warnings <#qa-errors-and-warnings>`__" section.
3246
3247.. _migration-2.3-miscellaneous-changes:
3248
3249Miscellaneous Changes
3250---------------------
3251
3252The following miscellaneous changes have occurred:
3253
3254- In this release, a number of recipes have been changed to ignore the
3255 ``largefile`` :term:`DISTRO_FEATURES` item,
3256 enabling large file support unconditionally. This feature has always
3257 been enabled by default. Disabling the feature has not been widely
3258 tested.
3259
3260 .. note::
3261
3262 Future releases of the Yocto Project will remove entirely the
3263 ability to disable the
3264 largefile
3265 feature, which would make it unconditionally enabled everywhere.
3266
3267- If the :term:`DISTRO_VERSION` value contains
3268 the value of the :term:`DATE` variable, which is the
3269 default between Poky releases, the ``DATE`` value is explicitly
3270 excluded from ``/etc/issue`` and ``/etc/issue.net``, which is
3271 displayed at the login prompt, in order to avoid conflicts with
3272 Multilib enabled. Regardless, the ``DATE`` value is inaccurate if the
3273 ``base-files`` recipe is restored from shared state (sstate) rather
3274 than rebuilt.
3275
3276 If you need the build date recorded in ``/etc/issue*`` or anywhere
3277 else in your image, a better method is to define a post-processing
3278 function to do it and have the function called from
3279 :term:`ROOTFS_POSTPROCESS_COMMAND`.
3280 Doing so ensures the value is always up-to-date with the created
3281 image.
3282
3283- Dropbear's ``init`` script now disables DSA host keys by default.
3284 This change is in line with the systemd service file, which supports
3285 RSA keys only, and with recent versions of OpenSSH, which deprecates
3286 DSA host keys.
3287
3288- The :ref:`buildhistory <ref-classes-buildhistory>` class now
3289 correctly uses tabs as separators between all columns in
3290 ``installed-package-sizes.txt`` in order to aid import into other
3291 tools.
3292
3293- The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig"
3294 ``DISTRO_FEATURES`` feature. Distributions that previously set:
3295 ::
3296
3297 USE_LDCONFIG = "0"
3298
3299 should now instead use the following:
3300
3301 ::
3302
3303 DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig"
3304
3305- The default value of
3306 :term:`COPYLEFT_LICENSE_INCLUDE` now
3307 includes all versions of AGPL licenses in addition to GPL and LGPL.
3308
3309 .. note::
3310
3311 The default list is not intended to be guaranteed as a complete
3312 safe list. You should seek legal advice based on what you are
3313 distributing if you are unsure.
3314
3315- Kernel module packages are now suffixed with the kernel version in
3316 order to allow module packages from multiple kernel versions to
3317 co-exist on a target system. If you wish to return to the previous
3318 naming scheme that does not include the version suffix, use the
3319 following:
3320 ::
3321
3322 KERNEL_MODULE_PACKAGE_SUFFIX to ""
3323
3324- Removal of ``libtool`` ``*.la`` files is now enabled by default. The
3325 ``*.la`` files are not actually needed on Linux and relocating them
3326 is an unnecessary burden.
3327
3328 If you need to preserve these ``.la`` files (e.g. in a custom
3329 distribution), you must change
3330 :term:`INHERIT_DISTRO` such that
3331 "remove-libtool" is not included in the value.
3332
3333- Extensible SDKs built for GCC 5+ now refuse to install on a
3334 distribution where the host GCC version is 4.8 or 4.9. This change
3335 resulted from the fact that the installation is known to fail due to
3336 the way the ``uninative`` shared state (sstate) package is built. See
3337 the :ref:`uninative <ref-classes-uninative>` class for additional
3338 information.
3339
3340- All native and nativesdk recipes now use a separate
3341 ``DISTRO_FEATURES`` value instead of sharing the value used by
3342 recipes for the target, in order to avoid unnecessary rebuilds.
3343
3344 The ``DISTRO_FEATURES`` for ``native`` recipes is
3345 :term:`DISTRO_FEATURES_NATIVE` added to
3346 an intersection of ``DISTRO_FEATURES`` and
3347 :term:`DISTRO_FEATURES_FILTER_NATIVE`.
3348
3349 For nativesdk recipes, the corresponding variables are
3350 :term:`DISTRO_FEATURES_NATIVESDK`
3351 and
3352 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`.
3353
3354- The ``FILESDIR`` variable, which was previously deprecated and rarely
3355 used, has now been removed. You should change any recipes that set
3356 ``FILESDIR`` to set :term:`FILESPATH` instead.
3357
3358- The ``MULTIMACH_HOST_SYS`` variable has been removed as it is no
3359 longer needed with recipe-specific sysroots.
3360
3361Moving to the Yocto Project 2.4 Release
3362=======================================
3363
3364This section provides migration information for moving to the Yocto
3365Project 2.4 Release from the prior release.
3366
3367.. _migration-2.4-memory-resident-mode:
3368
3369Memory Resident Mode
3370--------------------
3371
3372A persistent mode is now available in BitBake's default operation,
3373replacing its previous "memory resident mode" (i.e.
3374``oe-init-build-env-memres``). Now you only need to set
3375:term:`BB_SERVER_TIMEOUT` to a timeout (in
3376seconds) and BitBake's server stays resident for that amount of time
3377between invocations. The ``oe-init-build-env-memres`` script has been
3378removed since a separate environment setup script is no longer needed.
3379
3380.. _migration-2.4-packaging-changes:
3381
3382Packaging Changes
3383-----------------
3384
3385This section provides information about packaging changes that have
3386occurred:
3387
3388- ``python3`` Changes:
3389
3390 - The main "python3" package now brings in all of the standard
3391 Python 3 distribution rather than a subset. This behavior matches
3392 what is expected based on traditional Linux distributions. If you
3393 wish to install a subset of Python 3, specify ``python-core`` plus
3394 one or more of the individual packages that are still produced.
3395
3396 - ``python3``: The ``bz2.py``, ``lzma.py``, and
3397 ``_compression.py`` scripts have been moved from the
3398 ``python3-misc`` package to the ``python3-compression`` package.
3399
3400- ``binutils``: The ``libbfd`` library is now packaged in a separate
3401 "libbfd" package. This packaging saves space when certain tools (e.g.
3402 ``perf``) are installed. In such cases, the tools only need
3403 ``libbfd`` rather than all the packages in ``binutils``.
3404
3405- ``util-linux`` Changes:
3406
3407 - The ``su`` program is now packaged in a separate "util-linux-su"
3408 package, which is only built when "pam" is listed in the
3409 :term:`DISTRO_FEATURES` variable.
3410 ``util-linux`` should not be installed unless it is needed because
3411 ``su`` is normally provided through the shadow file format. The
3412 main ``util-linux`` package has runtime dependencies (i.e.
3413 :term:`RDEPENDS`) on the ``util-linux-su`` package
3414 when "pam" is in ``DISTRO_FEATURES``.
3415
3416 - The ``switch_root`` program is now packaged in a separate
3417 "util-linux-switch-root" package for small initramfs images that
3418 do not need the whole ``util-linux`` package or the busybox
3419 binary, which are both much larger than ``switch_root``. The main
3420 ``util-linux`` package has a recommended runtime dependency (i.e.
3421 :term:`RRECOMMENDS`) on the
3422 ``util-linux-switch-root`` package.
3423
3424 - The ``ionice`` program is now packaged in a separate
3425 "util-linux-ionice" package. The main ``util-linux`` package has a
3426 recommended runtime dependency (i.e. ``RRECOMMENDS``) on the
3427 ``util-linux-ionice`` package.
3428
3429- ``initscripts``: The ``sushell`` program is now packaged in a
3430 separate "initscripts-sushell" package. This packaging change allows
3431 systems to pull ``sushell`` in when ``selinux`` is enabled. The
3432 change also eliminates needing to pull in the entire ``initscripts``
3433 package. The main ``initscripts`` package has a runtime dependency
3434 (i.e. ``RDEPENDS``) on the ``sushell`` package when "selinux" is in
3435 ``DISTRO_FEATURES``.
3436
3437- ``glib-2.0``: The ``glib-2.0`` package now has a recommended
3438 runtime dependency (i.e. ``RRECOMMENDS``) on the ``shared-mime-info``
3439 package, since large portions of GIO are not useful without the MIME
3440 database. You can remove the dependency by using the
3441 :term:`BAD_RECOMMENDATIONS` variable if
3442 ``shared-mime-info`` is too large and is not required.
3443
3444- *Go Standard Runtime:* The Go standard runtime has been split out
3445 from the main ``go`` recipe into a separate ``go-runtime`` recipe.
3446
3447.. _migration-2.4-removed-recipes:
3448
3449Removed Recipes
3450---------------
3451
3452The following recipes have been removed:
3453
3454- ``acpitests``: This recipe is not maintained.
3455
3456- ``autogen-native``: No longer required by Grub, oe-core, or
3457 meta-oe.
3458
3459- ``bdwgc``: Nothing in OpenEmbedded-Core requires this recipe. It
3460 has moved to meta-oe.
3461
3462- ``byacc``: This recipe was only needed by rpm 5.x and has moved to
3463 meta-oe.
3464
3465- ``gcc (5.4)``: The 5.4 series dropped the recipe in favor of 6.3 /
3466 7.2.
3467
3468- ``gnome-common``: Deprecated upstream and no longer needed.
3469
3470- ``go-bootstrap-native``: Go 1.9 does its own bootstrapping so this
3471 recipe has been removed.
3472
3473- ``guile``: This recipe was only needed by ``autogen-native`` and
3474 ``remake``. The recipe is no longer needed by either of these
3475 programs.
3476
3477- ``libclass-isa-perl``: This recipe was previously needed for LSB 4,
3478 no longer needed.
3479
3480- ``libdumpvalue-perl``: This recipe was previously needed for LSB 4,
3481 no longer needed.
3482
3483- ``libenv-perl``: This recipe was previously needed for LSB 4, no
3484 longer needed.
3485
3486- ``libfile-checktree-perl``: This recipe was previously needed for
3487 LSB 4, no longer needed.
3488
3489- ``libi18n-collate-perl``: This recipe was previously needed for LSB
3490 4, no longer needed.
3491
3492- ``libiconv``: This recipe was only needed for ``uclibc``, which was
3493 removed in the previous release. ``glibc`` and ``musl`` have their
3494 own implementations. ``meta-mingw`` still needs ``libiconv``, so it
3495 has been moved to ``meta-mingw``.
3496
3497- ``libpng12``: This recipe was previously needed for LSB. The
3498 current ``libpng`` is 1.6.x.
3499
3500- ``libpod-plainer-perl``: This recipe was previously needed for LSB
3501 4, no longer needed.
3502
3503- ``linux-yocto (4.1)``: This recipe was removed in favor of 4.4,
3504 4.9, 4.10 and 4.12.
3505
3506- ``mailx``: This recipe was previously only needed for LSB
3507 compatibility, and upstream is defunct.
3508
3509- ``mesa (git version only)``: The git version recipe was stale with
3510 respect to the release version.
3511
3512- ``ofono (git version only)``: The git version recipe was stale with
3513 respect to the release version.
3514
3515- ``portmap``: This recipe is obsolete and is superseded by
3516 ``rpcbind``.
3517
3518- ``python3-pygpgme``: This recipe is old and unmaintained. It was
3519 previously required by ``dnf``, which has switched to official
3520 ``gpgme`` Python bindings.
3521
3522- ``python-async``: This recipe has been removed in favor of the
3523 Python 3 version.
3524
3525- ``python-gitdb``: This recipe has been removed in favor of the
3526 Python 3 version.
3527
3528- ``python-git``: This recipe was removed in favor of the Python 3
3529 version.
3530
3531- ``python-mako``: This recipe was removed in favor of the Python 3
3532 version.
3533
3534- ``python-pexpect``: This recipe was removed in favor of the Python
3535 3 version.
3536
3537- ``python-ptyprocess``: This recipe was removed in favor of Python
3538 the 3 version.
3539
3540- ``python-pycurl``: Nothing is using this recipe in
3541 OpenEmbedded-Core (i.e. ``meta-oe``).
3542
3543- ``python-six``: This recipe was removed in favor of the Python 3
3544 version.
3545
3546- ``python-smmap``: This recipe was removed in favor of the Python 3
3547 version.
3548
3549- ``remake``: Using ``remake`` as the provider of ``virtual/make`` is
3550 broken. Consequently, this recipe is not needed in OpenEmbedded-Core.
3551
3552.. _migration-2.4-kernel-device-tree-move:
3553
3554Kernel Device Tree Move
3555-----------------------
3556
3557Kernel Device Tree support is now easier to enable in a kernel recipe.
3558The Device Tree code has moved to a
3559:ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class.
3560Functionality is automatically enabled for any recipe that inherits the
3561:ref:`kernel <ref-classes-kernel>` class and sets the
3562:term:`KERNEL_DEVICETREE` variable. The
3563previous mechanism for doing this,
3564``meta/recipes-kernel/linux/linux-dtb.inc``, is still available to avoid
3565breakage, but triggers a deprecation warning. Future releases of the
3566Yocto Project will remove ``meta/recipes-kernel/linux/linux-dtb.inc``.
3567It is advisable to remove any ``require`` statements that request
3568``meta/recipes-kernel/linux/linux-dtb.inc`` from any custom kernel
3569recipes you might have. This will avoid breakage in post 2.4 releases.
3570
3571.. _migration-2.4-package-qa-changes:
3572
3573Package QA Changes
3574------------------
3575
3576The following package QA changes took place:
3577
3578- The "unsafe-references-in-scripts" QA check has been removed.
3579
3580- If you refer to ``${COREBASE}/LICENSE`` within
3581 :term:`LIC_FILES_CHKSUM` you receive a
3582 warning because this file is a description of the license for
3583 OE-Core. Use ``${COMMON_LICENSE_DIR}/MIT`` if your recipe is
3584 MIT-licensed and you cannot use the preferred method of referring to
3585 a file within the source tree.
3586
3587.. _migration-2.4-readme-changes:
3588
3589``README`` File Changes
3590-----------------------
3591
3592The following are changes to ``README`` files:
3593
3594- The main Poky ``README`` file has been moved to the ``meta-poky``
3595 layer and has been renamed ``README.poky``. A symlink has been
3596 created so that references to the old location work.
3597
3598- The ``README.hardware`` file has been moved to ``meta-yocto-bsp``. A
3599 symlink has been created so that references to the old location work.
3600
3601- A ``README.qemu`` file has been created with coverage of the
3602 ``qemu*`` machines.
3603
3604.. _migration-2.4-miscellaneous-changes:
3605
3606Miscellaneous Changes
3607---------------------
3608
3609The following are additional changes:
3610
3611- The ``ROOTFS_PKGMANAGE_BOOTSTRAP`` variable and any references to it
3612 have been removed. You should remove this variable from any custom
3613 recipes.
3614
3615- The ``meta-yocto`` directory has been removed.
3616
3617 .. note::
3618
3619 In the Yocto Project 2.1 release
3620 meta-yocto
3621 was renamed to
3622 meta-poky
3623 and the
3624 meta-yocto
3625 subdirectory remained to avoid breaking existing configurations.
3626
3627- The ``maintainers.inc`` file, which tracks maintainers by listing a
3628 primary person responsible for each recipe in OE-Core, has been moved
3629 from ``meta-poky`` to OE-Core (i.e. from
3630 ``meta-poky/conf/distro/include`` to ``meta/conf/distro/include``).
3631
3632- The :ref:`buildhistory <ref-classes-buildhistory>` class now makes
3633 a single commit per build rather than one commit per subdirectory in
3634 the repository. This behavior assumes the commits are enabled with
3635 :term:`BUILDHISTORY_COMMIT` = "1", which
3636 is typical. Previously, the ``buildhistory`` class made one commit
3637 per subdirectory in the repository in order to make it easier to see
3638 the changes for a particular subdirectory. To view a particular
3639 change, specify that subdirectory as the last parameter on the
3640 ``git show`` or ``git diff`` commands.
3641
3642- The ``x86-base.inc`` file, which is included by all x86-based machine
3643 configurations, now sets :term:`IMAGE_FSTYPES`
3644 using ``?=`` to "live" rather than appending with ``+=``. This change
3645 makes the default easier to override.
3646
3647- BitBake fires multiple "BuildStarted" events when multiconfig is
3648 enabled (one per configuration). For more information, see the
3649 ":ref:`Events <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:events>`" section in the BitBake User
3650 Manual.
3651
3652- By default, the ``security_flags.inc`` file sets a
3653 :term:`GCCPIE` variable with an option to enable
3654 Position Independent Executables (PIE) within ``gcc``. Enabling PIE
3655 in the GNU C Compiler (GCC), makes Return Oriented Programming (ROP)
3656 attacks much more difficult to execute.
3657
3658- OE-Core now provides a ``bitbake-layers`` plugin that implements a
3659 "create-layer" subcommand. The implementation of this subcommand has
3660 resulted in the ``yocto-layer`` script being deprecated and will
3661 likely be removed in the next Yocto Project release.
3662
3663- The ``vmdk``, ``vdi``, and ``qcow2`` image file types are now used in
3664 conjunction with the "wic" image type through ``CONVERSION_CMD``.
3665 Consequently, the equivalent image types are now ``wic.vmdk``,
3666 ``wic.vdi``, and ``wic.qcow2``, respectively.
3667
3668- ``do_image_<type>[depends]`` has replaced ``IMAGE_DEPENDS_<type>``.
3669 If you have your own classes that implement custom image types, then
3670 you need to update them.
3671
3672- OpenSSL 1.1 has been introduced. However, the default is still 1.0.x
3673 through the :term:`PREFERRED_VERSION`
3674 variable. This preference is set is due to the remaining
3675 compatibility issues with other software. The
3676 :term:`PROVIDES` variable in the openssl 1.0 recipe
3677 now includes "openssl10" as a marker that can be used in
3678 :term:`DEPENDS` within recipes that build software
3679 that still depend on OpenSSL 1.0.
3680
3681- To ensure consistent behavior, BitBake's "-r" and "-R" options (i.e.
3682 prefile and postfile), which are used to read or post-read additional
3683 configuration files from the command line, now only affect the
3684 current BitBake command. Before these BitBake changes, these options
3685 would "stick" for future executions.
3686
3687Moving to the Yocto Project 2.5 Release
3688=======================================
3689
3690This section provides migration information for moving to the Yocto
3691Project 2.5 Release from the prior release.
3692
3693.. _migration-2.5-packaging-changes:
3694
3695Packaging Changes
3696-----------------
3697
3698This section provides information about packaging changes that have
3699occurred:
3700
3701- ``bind-libs``: The libraries packaged by the bind recipe are in a
3702 separate ``bind-libs`` package.
3703
3704- ``libfm-gtk``: The ``libfm`` GTK+ bindings are split into a
3705 separate ``libfm-gtk`` package.
3706
3707- ``flex-libfl``: The flex recipe splits out libfl into a separate
3708 ``flex-libfl`` package to avoid too many dependencies being pulled in
3709 where only the library is needed.
3710
3711- ``grub-efi``: The ``grub-efi`` configuration is split into a
3712 separate ``grub-bootconf`` recipe. However, the dependency
3713 relationship from ``grub-efi`` is through a virtual/grub-bootconf
3714 provider making it possible to have your own recipe provide the
3715 dependency. Alternatively, you can use a BitBake append file to bring
3716 the configuration back into the ``grub-efi`` recipe.
3717
3718- *armv7a Legacy Package Feed Support:* Legacy support is removed for
3719 transitioning from ``armv7a`` to ``armv7a-vfp-neon`` in package
3720 feeds, which was previously enabled by setting
3721 ``PKGARCHCOMPAT_ARMV7A``. This transition occurred in 2011 and active
3722 package feeds should by now be updated to the new naming.
3723
3724.. _migration-2.5-removed-recipes:
3725
3726Removed Recipes
3727---------------
3728
3729The following recipes have been removed:
3730
3731- ``gcc``: The version 6.4 recipes are replaced by 7.x.
3732
3733- ``gst-player``: Renamed to ``gst-examples`` as per upstream.
3734
3735- ``hostap-utils``: This software package is obsolete.
3736
3737- ``latencytop``: This recipe is no longer maintained upstream. The
3738 last release was in 2009.
3739
3740- ``libpfm4``: The only file that requires this recipe is
3741 ``oprofile``, which has been removed.
3742
3743- ``linux-yocto``: The version 4.4, 4.9, and 4.10 recipes have been
3744 removed. Versions 4.12, 4.14, and 4.15 remain.
3745
3746- ``man``: This recipe has been replaced by modern ``man-db``
3747
3748- ``mkelfimage``: This tool has been removed in the upstream coreboot
3749 project, and is no longer needed with the removal of the ELF image
3750 type.
3751
3752- ``nativesdk-postinst-intercept``: This recipe is not maintained.
3753
3754- ``neon``: This software package is no longer maintained upstream
3755 and is no longer needed by anything in OpenEmbedded-Core.
3756
3757- ``oprofile``: The functionality of this recipe is replaced by
3758 ``perf`` and keeping compatibility on an ongoing basis with ``musl``
3759 is difficult.
3760
3761- ``pax``: This software package is obsolete.
3762
3763- ``stat``: This software package is not maintained upstream.
3764 ``coreutils`` provides a modern stat binary.
3765
3766- ``zisofs-tools-native``: This recipe is no longer needed because
3767 the compressed ISO image feature has been removed.
3768
3769.. _migration-2.5-scripts-and-tools-changes:
3770
3771Scripts and Tools Changes
3772-------------------------
3773
3774The following are changes to scripts and tools:
3775
3776- ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer``: The
3777 ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer`` scripts
3778 previously shipped with poky but not in OpenEmbedded-Core have been
3779 removed. These scripts are not maintained and are outdated. In many
3780 cases, they are also limited in scope. The
3781 ``bitbake-layers create-layer`` command is a direct replacement for
3782 ``yocto-layer``. See the documentation to create a BSP or kernel
3783 recipe in the ":ref:`bsp-guide/bsp:bsp kernel recipe example`" section.
3784
3785- ``devtool finish``: ``devtool finish`` now exits with an error if
3786 there are uncommitted changes or a rebase/am in progress in the
3787 recipe's source repository. If this error occurs, there might be
3788 uncommitted changes that will not be included in updates to the
3789 patches applied by the recipe. A -f/--force option is provided for
3790 situations that the uncommitted changes are inconsequential and you
3791 want to proceed regardless.
3792
3793- ``scripts/oe-setup-rpmrepo`` script: The functionality of
3794 ``scripts/oe-setup-rpmrepo`` is replaced by
3795 ``bitbake package-index``.
3796
3797- ``scripts/test-dependencies.sh`` script: The script is largely made
3798 obsolete by the recipe-specific sysroots functionality introduced in
3799 the previous release.
3800
3801.. _migration-2.5-bitbake-changes:
3802
3803BitBake Changes
3804---------------
3805
3806The following are BitBake changes:
3807
3808- The ``--runall`` option has changed. There are two different
3809 behaviors people might want:
3810
3811 - *Behavior A:* For a given target (or set of targets) look through
3812 the task graph and run task X only if it is present and will be
3813 built.
3814
3815 - *Behavior B:* For a given target (or set of targets) look through
3816 the task graph and run task X if any recipe in the taskgraph has
3817 such a target, even if it is not in the original task graph.
3818
3819 The ``--runall`` option now performs "Behavior B". Previously
3820 ``--runall`` behaved like "Behavior A". A ``--runonly`` option has
3821 been added to retain the ability to perform "Behavior A".
3822
3823- Several explicit "run this task for all recipes in the dependency
3824 tree" tasks have been removed (e.g. ``fetchall``, ``checkuriall``,
3825 and the ``*all`` tasks provided by the ``distrodata`` and
3826 ``archiver`` classes). There is a BitBake option to complete this for
3827 any arbitrary task. For example:
3828 ::
3829
3830 bitbake <target> -c fetchall
3831
3832 should now be replaced with:
3833 ::
3834
3835 bitbake <target> --runall=fetch
3836
3837.. _migration-2.5-python-and-python3-changes:
3838
3839Python and Python 3 Changes
3840---------------------------
3841
3842The following are auto-packaging changes to Python and Python 3:
3843
3844The script-managed ``python-*-manifest.inc`` files that were previously
3845used to generate Python and Python 3 packages have been replaced with a
3846JSON-based file that is easier to read and maintain. A new task is
3847available for maintainers of the Python recipes to update the JSON file
3848when upgrading to new Python versions. You can now edit the file
3849directly instead of having to edit a script and run it to update the
3850file.
3851
3852One particular change to note is that the Python recipes no longer have
3853build-time provides for their packages. This assumes ``python-foo`` is
3854one of the packages provided by the Python recipe. You can no longer run
3855``bitbake python-foo`` or have a
3856:term:`DEPENDS` on ``python-foo``,
3857but doing either of the following causes the package to work as
3858expected: ::
3859
3860 IMAGE_INSTALL_append = " python-foo"
3861
3862or ::
3863
3864 RDEPENDS_${PN} = "python-foo"
3865
3866The earlier build-time provides behavior was a quirk of the
3867way the Python manifest file was created. For more information on this
3868change please see `this
3869commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`__.
3870
3871.. _migration-2.5-miscellaneous-changes:
3872
3873Miscellaneous Changes
3874---------------------
3875
3876The following are additional changes:
3877
3878- The ``kernel`` class supports building packages for multiple kernels.
3879 If your kernel recipe or ``.bbappend`` file mentions packaging at
3880 all, you should replace references to the kernel in package names
3881 with ``${KERNEL_PACKAGE_NAME}``. For example, if you disable
3882 automatic installation of the kernel image using
3883 ``RDEPENDS_kernel-base = ""`` you can avoid warnings using
3884 ``RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""`` instead.
3885
3886- The ``buildhistory`` class commits changes to the repository by
3887 default so you no longer need to set ``BUILDHISTORY_COMMIT = "1"``.
3888 If you want to disable commits you need to set
3889 ``BUILDHISTORY_COMMIT = "0"`` in your configuration.
3890
3891- The ``beaglebone`` reference machine has been renamed to
3892 ``beaglebone-yocto``. The ``beaglebone-yocto`` BSP is a reference
3893 implementation using only mainline components available in
3894 OpenEmbedded-Core and ``meta-yocto-bsp``, whereas Texas Instruments
3895 maintains a full-featured BSP in the ``meta-ti`` layer. This rename
3896 avoids the previous name clash that existed between the two BSPs.
3897
3898- The ``update-alternatives`` class no longer works with SysV ``init``
3899 scripts because this usage has been problematic. Also, the
3900 ``sysklogd`` recipe no longer uses ``update-alternatives`` because it
3901 is incompatible with other implementations.
3902
3903- By default, the :ref:`cmake <ref-classes-cmake>` class uses
3904 ``ninja`` instead of ``make`` for building. This improves build
3905 performance. If a recipe is broken with ``ninja``, then the recipe
3906 can set ``OECMAKE_GENERATOR = "Unix Makefiles"`` to change back to
3907 ``make``.
3908
3909- The previously deprecated ``base_*`` functions have been removed in
3910 favor of their replacements in ``meta/lib/oe`` and
3911 ``bitbake/lib/bb``. These are typically used from recipes and
3912 classes. Any references to the old functions must be updated. The
3913 following table shows the removed functions and their replacements:
3914
3915 +------------------------------+----------------------------------------------------------+
3916 | *Removed* | *Replacement* |
3917 +==============================+==========================================================+
3918 | base_path_join() | oe.path.join() |
3919 +------------------------------+----------------------------------------------------------+
3920 | base_path_relative() | oe.path.relative() |
3921 +------------------------------+----------------------------------------------------------+
3922 | base_path_out() | oe.path.format_display() |
3923 +------------------------------+----------------------------------------------------------+
3924 | base_read_file() | oe.utils.read_file() |
3925 +------------------------------+----------------------------------------------------------+
3926 | base_ifelse() | oe.utils.ifelse() |
3927 +------------------------------+----------------------------------------------------------+
3928 | base_conditional() | oe.utils.conditional() |
3929 +------------------------------+----------------------------------------------------------+
3930 | base_less_or_equal() | oe.utils.less_or_equal() |
3931 +------------------------------+----------------------------------------------------------+
3932 | base_version_less_or_equal() | oe.utils.version_less_or_equal() |
3933 +------------------------------+----------------------------------------------------------+
3934 | base_contains() | bb.utils.contains() |
3935 +------------------------------+----------------------------------------------------------+
3936 | base_both_contain() | oe.utils.both_contain() |
3937 +------------------------------+----------------------------------------------------------+
3938 | base_prune_suffix() | oe.utils.prune_suffix() |
3939 +------------------------------+----------------------------------------------------------+
3940 | oe_filter() | oe.utils.str_filter() |
3941 +------------------------------+----------------------------------------------------------+
3942 | oe_filter_out() | oe.utils.str_filter_out() (or use the \_remove operator) |
3943 +------------------------------+----------------------------------------------------------+
3944
3945- Using ``exit 1`` to explicitly defer a postinstall script until first
3946 boot is now deprecated since it is not an obvious mechanism and can
3947 mask actual errors. If you want to explicitly defer a postinstall to
3948 first boot on the target rather than at ``rootfs`` creation time, use
3949 ``pkg_postinst_ontarget()`` or call
3950 ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``.
3951 Any failure of a ``pkg_postinst()`` script (including ``exit 1``)
3952 will trigger a warning during ``do_rootfs``.
3953
3954 For more information, see the
3955 ":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`"
3956 section in the Yocto Project Development Tasks Manual.
3957
3958- The ``elf`` image type has been removed. This image type was removed
3959 because the ``mkelfimage`` tool that was required to create it is no
3960 longer provided by coreboot upstream and required updating every time
3961 ``binutils`` updated.
3962
3963- Support for .iso image compression (previously enabled through
3964 ``COMPRESSISO = "1"``) has been removed. The userspace tools
3965 (``zisofs-tools``) are unmaintained and ``squashfs`` provides better
3966 performance and compression. In order to build a live image with
3967 squashfs+lz4 compression enabled you should now set
3968 ``LIVE_ROOTFS_TYPE = "squashfs-lz4"`` and ensure that ``live`` is in
3969 ``IMAGE_FSTYPES``.
3970
3971- Recipes with an unconditional dependency on ``libpam`` are only
3972 buildable with ``pam`` in ``DISTRO_FEATURES``. If the dependency is
3973 truly optional then it is recommended that the dependency be
3974 conditional upon ``pam`` being in ``DISTRO_FEATURES``.
3975
3976- For EFI-based machines, the bootloader (``grub-efi`` by default) is
3977 installed into the image at /boot. Wic can be used to split the
3978 bootloader into separate boot and rootfs partitions if necessary.
3979
3980- Patches whose context does not match exactly (i.e. where patch
3981 reports "fuzz" when applying) will generate a warning. For an example
3982 of this see `this
3983 commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57>`__.
3984
3985- Layers are expected to set ``LAYERSERIES_COMPAT_layername`` to match
3986 the version(s) of OpenEmbedded-Core they are compatible with. This is
3987 specified as codenames using spaces to separate multiple values (e.g.
3988 "rocko sumo"). If a layer does not set
3989 ``LAYERSERIES_COMPAT_layername``, a warning will is shown. If a layer
3990 sets a value that does not include the current version ("sumo" for
3991 the 2.5 release), then an error will be produced.
3992
3993- The ``TZ`` environment variable is set to "UTC" within the build
3994 environment in order to fix reproducibility problems in some recipes.
3995
3996Moving to the Yocto Project 2.6 Release
3997=======================================
3998
3999This section provides migration information for moving to the Yocto
4000Project 2.6 Release from the prior release.
4001
4002.. _migration-2.6-gcc-changes:
4003
4004GCC 8.2 is Now Used by Default
4005------------------------------
4006
4007The GNU Compiler Collection version 8.2 is now used by default for
4008compilation. For more information on what has changed in the GCC 8.x
4009release, see https://gcc.gnu.org/gcc-8/changes.html.
4010
4011If you still need to compile with version 7.x, GCC 7.3 is also provided.
4012You can select this version by setting the and can be selected by
4013setting the :term:`GCCVERSION` variable to "7.%" in
4014your configuration.
4015
4016.. _migration-2.6-removed-recipes:
4017
4018Removed Recipes
4019---------------
4020
4021The following recipes have been removed:
4022
4023- *beecrypt*: No longer needed since moving to RPM 4.
4024- *bigreqsproto*: Replaced by ``xorgproto``.
4025- *calibrateproto*: Removed in favor of ``xinput``.
4026- *compositeproto*: Replaced by ``xorgproto``.
4027- *damageproto*: Replaced by ``xorgproto``.
4028- *dmxproto*: Replaced by ``xorgproto``.
4029- *dri2proto*: Replaced by ``xorgproto``.
4030- *dri3proto*: Replaced by ``xorgproto``.
4031- *eee-acpi-scripts*: Became obsolete.
4032- *fixesproto*: Replaced by ``xorgproto``.
4033- *fontsproto*: Replaced by ``xorgproto``.
4034- *fstests*: Became obsolete.
4035- *gccmakedep*: No longer used.
4036- *glproto*: Replaced by ``xorgproto``.
4037- *gnome-desktop3*: No longer needed. This recipe has moved to ``meta-oe``.
4038- *icon-naming-utils*: No longer used since the Sato theme was removed in 2016.
4039- *inputproto*: Replaced by ``xorgproto``.
4040- *kbproto*: Replaced by ``xorgproto``.
4041- *libusb-compat*: Became obsolete.
4042- *libuser*: Became obsolete.
4043- *libnfsidmap*: No longer an external requirement since ``nfs-utils`` 2.2.1. ``libnfsidmap`` is now integrated.
4044- *libxcalibrate*: No longer needed with ``xinput``
4045- *mktemp*: Became obsolete. The ``mktemp`` command is provided by both ``busybox`` and ``coreutils``.
4046- *ossp-uuid*: Is not being maintained and has mostly been replaced by ``uuid.h`` in ``util-linux``.
4047- *pax-utils*: No longer needed. Previous QA tests that did use this recipe are now done at build time.
4048- *pcmciautils*: Became obsolete.
4049- *pixz*: No longer needed. ``xz`` now supports multi-threaded compression.
4050- *presentproto*: Replaced by ``xorgproto``.
4051- *randrproto*: Replaced by ``xorgproto``.
4052- *recordproto*: Replaced by ``xorgproto``.
4053- *renderproto*: Replaced by ``xorgproto``.
4054- *resourceproto*: Replaced by ``xorgproto``.
4055- *scrnsaverproto*: Replaced by ``xorgproto``.
4056- *trace-cmd*: Became obsolete. ``perf`` replaced this recipe's functionally.
4057- *videoproto*: Replaced by ``xorgproto``.
4058- *wireless-tools*: Became obsolete. Superseded by ``iw``.
4059- *xcmiscproto*: Replaced by ``xorgproto``.
4060- *xextproto*: Replaced by ``xorgproto``.
4061- *xf86dgaproto*: Replaced by ``xorgproto``.
4062- *xf86driproto*: Replaced by ``xorgproto``.
4063- *xf86miscproto*: Replaced by ``xorgproto``.
4064- *xf86-video-omapfb*: Became obsolete. Use kernel modesetting driver instead.
4065- *xf86-video-omap*: Became obsolete. Use kernel modesetting driver instead.
4066- *xf86vidmodeproto*: Replaced by ``xorgproto``.
4067- *xineramaproto*: Replaced by ``xorgproto``.
4068- *xproto*: Replaced by ``xorgproto``.
4069- *yasm*: No longer needed since previous usages are now satisfied by ``nasm``.
4070
4071.. _migration-2.6-packaging-changes:
4072
4073Packaging Changes
4074-----------------
4075
4076The following packaging changes have been made:
4077
4078- *cmake*: ``cmake.m4`` and ``toolchain`` files have been moved to
4079 the main package.
4080
4081- *iptables*: The ``iptables`` modules have been split into
4082 separate packages.
4083
4084- *alsa-lib*: ``libasound`` is now in the main ``alsa-lib`` package
4085 instead of ``libasound``.
4086
4087- *glibc*: ``libnss-db`` is now in its own package along with a
4088 ``/var/db/makedbs.sh`` script to update databases.
4089
4090- *python and python3*: The main package has been removed from
4091 the recipe. You must install specific packages or ``python-modules``
4092 / ``python3-modules`` for everything.
4093
4094- *systemtap*: Moved ``systemtap-exporter`` into its own package.
4095
4096.. _migration-2.6-xorg-protocol-dependencies:
4097
4098XOrg Protocol dependencies
4099--------------------------
4100
4101The ``*proto`` upstream repositories have been combined into one
4102"xorgproto" repository. Thus, the corresponding recipes have also been
4103combined into a single ``xorgproto`` recipe. Any recipes that depend
4104upon the older ``*proto`` recipes need to be changed to depend on the
4105newer ``xorgproto`` recipe instead.
4106
4107For names of recipes removed because of this repository change, see the
4108`Removed Recipes <#migration-2.6-removed-recipes>`__ section.
4109
4110.. _migration-2.6-distutils-distutils3-fetching-dependencies:
4111
4112``distutils`` and ``distutils3`` Now Prevent Fetching Dependencies During the ``do_configure`` Task
4113---------------------------------------------------------------------------------------------------
4114
4115Previously, it was possible for Python recipes that inherited the
4116:ref:`distutils <ref-classes-distutils>` and
4117:ref:`distutils3 <ref-classes-distutils3>` classes to fetch code
4118during the :ref:`ref-tasks-configure` task to satisfy
4119dependencies mentioned in ``setup.py`` if those dependencies were not
4120provided in the sysroot (i.e. recipes providing the dependencies were
4121missing from :term:`DEPENDS`).
4122
4123.. note::
4124
4125 This change affects classes beyond just the two mentioned (i.e.
4126 distutils
4127 and
4128 distutils3
4129 ). Any recipe that inherits
4130 distutils\*
4131 classes are affected. For example, the
4132 setuptools
4133 and
4134 setuptools3
4135 recipes are affected since they inherit the
4136 distutils\*
4137 classes.
4138
4139Fetching these types of dependencies that are not provided in the
4140sysroot negatively affects the ability to reproduce builds. This type of
4141fetching is now explicitly disabled. Consequently, any missing
4142dependencies in Python recipes that use these classes now result in an
4143error during the ``do_configure`` task.
4144
4145.. _migration-2.6-linux-yocto-configuration-audit-issues-now-correctly-reported:
4146
4147``linux-yocto`` Configuration Audit Issues Now Correctly Reported
4148-----------------------------------------------------------------
4149
4150Due to a bug, the kernel configuration audit functionality was not
4151writing out any resulting warnings during the build. This issue is now
4152corrected. You might notice these warnings now if you have a custom
4153kernel configuration with a ``linux-yocto`` style kernel recipe.
4154
4155.. _migration-2.6-image-kernel-artifact-naming-changes:
4156
4157Image/Kernel Artifact Naming Changes
4158------------------------------------
4159
4160The following changes have been made:
4161
4162- Name variables (e.g. :term:`IMAGE_NAME`) use a new
4163 ``IMAGE_VERSION_SUFFIX`` variable instead of
4164 :term:`DATETIME`. Using ``IMAGE_VERSION_SUFFIX``
4165 allows easier and more direct changes.
4166
4167 The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf``
4168 configuration file as follows:
4169 ::
4170
4171 IMAGE_VERSION_SUFFIX = "-${DATETIME}"
4172
4173- Several variables have changed names for consistency:
4174 ::
4175
4176 Old Variable Name New Variable Name
4177 ========================================================
4178 KERNEL_IMAGE_BASE_NAME :term:`KERNEL_IMAGE_NAME`
4179 KERNEL_IMAGE_SYMLINK_NAME :term:`KERNEL_IMAGE_LINK_NAME`
4180 MODULE_TARBALL_BASE_NAME :term:`MODULE_TARBALL_NAME`
4181 MODULE_TARBALL_SYMLINK_NAME :term:`MODULE_TARBALL_LINK_NAME`
4182 INITRAMFS_BASE_NAME :term:`INITRAMFS_NAME`
4183
4184- The ``MODULE_IMAGE_BASE_NAME`` variable has been removed. The module
4185 tarball name is now controlled directly with the
4186 :term:`MODULE_TARBALL_NAME` variable.
4187
4188- The :term:`KERNEL_DTB_NAME` and
4189 :term:`KERNEL_DTB_LINK_NAME` variables
4190 have been introduced to control kernel Device Tree Binary (DTB)
4191 artifact names instead of mangling ``KERNEL_IMAGE_*`` variables.
4192
4193- The :term:`KERNEL_FIT_NAME` and
4194 :term:`KERNEL_FIT_LINK_NAME` variables
4195 have been introduced to specify the name of flattened image tree
4196 (FIT) kernel images similar to other deployed artifacts.
4197
4198- The :term:`MODULE_TARBALL_NAME` and
4199 :term:`MODULE_TARBALL_LINK_NAME`
4200 variable values no longer include the "module-" prefix or ".tgz"
4201 suffix. These parts are now hardcoded so that the values are
4202 consistent with other artifact naming variables.
4203
4204- Added the :term:`INITRAMFS_LINK_NAME`
4205 variable so that the symlink can be controlled similarly to other
4206 artifact types.
4207
4208- :term:`INITRAMFS_NAME` now uses
4209 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" instead
4210 of "${PV}-${PR}-${MACHINE}-${DATETIME}", which makes it consistent
4211 with other variables.
4212
4213.. _migration-2.6-serial-console-deprecated:
4214
4215``SERIAL_CONSOLE`` Deprecated
4216-----------------------------
4217
4218The :term:`SERIAL_CONSOLE` variable has been
4219functionally replaced by the
4220:term:`SERIAL_CONSOLES` variable for some time.
4221With the Yocto Project 2.6 release, ``SERIAL_CONSOLE`` has been
4222officially deprecated.
4223
4224``SERIAL_CONSOLE`` will continue to work as before for the 2.6 release.
4225However, for the sake of future compatibility, it is recommended that
4226you replace all instances of ``SERIAL_CONSOLE`` with
4227``SERIAL_CONSOLES``.
4228
4229.. note::
4230
4231 The only difference in usage is that
4232 SERIAL_CONSOLES
4233 expects entries to be separated using semicolons as compared to
4234 SERIAL_CONSOLE
4235 , which expects spaces.
4236
4237.. _migration-2.6-poky-sets-unknown-configure-option-to-qa-error:
4238
4239Configure Script Reports Unknown Options as Errors
4240--------------------------------------------------
4241
4242If the configure script reports an unknown option, this now triggers a
4243QA error instead of a warning. Any recipes that previously got away with
4244specifying such unknown options now need to be fixed.
4245
4246.. _migration-2.6-override-changes:
4247
4248Override Changes
4249----------------
4250
4251The following changes have occurred:
4252
4253- The ``virtclass-native`` and ``virtclass-nativesdk`` Overrides Have
4254 Been Removed: The ``virtclass-native`` and ``virtclass-nativesdk``
4255 overrides have been deprecated since 2012 in favor of
4256 ``class-native`` and ``class-nativesdk``, respectively. Both
4257 ``virtclass-native`` and ``virtclass-nativesdk`` are now dropped.
4258
4259 .. note::
4260
4261 The
4262 virtclass-multilib-
4263 overrides for multilib are still valid.
4264
4265- The ``forcevariable`` Override Now Has a Higher Priority Than
4266 ``libc`` Overrides: The ``forcevariable`` override is documented to
4267 be the highest priority override. However, due to a long-standing
4268 quirk of how :term:`OVERRIDES` is set, the ``libc``
4269 overrides (e.g. ``libc-glibc``, ``libc-musl``, and so forth)
4270 erroneously had a higher priority. This issue is now corrected.
4271
4272 It is likely this change will not cause any problems. However, it is
4273 possible with some unusual configurations that you might see a change
4274 in behavior if you were relying on the previous behavior. Be sure to
4275 check how you use ``forcevariable`` and ``libc-*`` overrides in your
4276 custom layers and configuration files to ensure they make sense.
4277
4278- The ``build-${BUILD_OS}`` Override Has Been Removed: The
4279 ``build-${BUILD_OS}``, which is typically ``build-linux``, override
4280 has been removed because building on a host operating system other
4281 than a recent version of Linux is neither supported nor recommended.
4282 Dropping the override avoids giving the impression that other host
4283 operating systems might be supported.
4284
4285- The "_remove" operator now preserves whitespace. Consequently, when
4286 specifying list items to remove, be aware that leading and trailing
4287 whitespace resulting from the removal is retained.
4288
4289 See the ":ref:`bitbake:removing-override-style-syntax`"
4290 section in the BitBake User Manual for a detailed example.
4291
4292.. _migration-2.6-systemd-configuration-now-split-out-to-system-conf:
4293
4294``systemd`` Configuration is Now Split Into ``systemd-conf``
4295------------------------------------------------------------
4296
4297The configuration for the ``systemd`` recipe has been moved into a
4298``system-conf`` recipe. Moving this configuration to a separate recipe
4299avoids the ``systemd`` recipe from becoming machine-specific for cases
4300where machine-specific configurations need to be applied (e.g. for
4301``qemu*`` machines).
4302
4303Currently, the new recipe packages the following files:
4304::
4305
4306 ${sysconfdir}/machine-id
4307 ${sysconfdir}/systemd/coredump.conf
4308 ${sysconfdir}/systemd/journald.conf
4309 ${sysconfdir}/systemd/logind.conf
4310 ${sysconfdir}/systemd/system.conf
4311 ${sysconfdir}/systemd/user.conf
4312
4313If you previously used bbappend files to append the ``systemd`` recipe to
4314change any of the listed files, you must do so for the ``systemd-conf``
4315recipe instead.
4316
4317.. _migration-2.6-automatic-testing-changes:
4318
4319Automatic Testing Changes
4320-------------------------
4321
4322This section provides information about automatic testing changes:
4323
4324- ``TEST_IMAGE`` Variable Removed: Prior to this release, you set the
4325 ``TEST_IMAGE`` variable to "1" to enable automatic testing for
4326 successfully built images. The ``TEST_IMAGE`` variable no longer
4327 exists and has been replaced by the
4328 :term:`TESTIMAGE_AUTO` variable.
4329
4330- Inheriting the ``testimage`` and ``testsdk`` Classes: Best
4331 practices now dictate that you use the
4332 :term:`IMAGE_CLASSES` variable rather than the
4333 :term:`INHERIT` variable when you inherit the
4334 :ref:`testimage <ref-classes-testimage*>` and
4335 :ref:`testsdk <ref-classes-testsdk>` classes used for automatic
4336 testing.
4337
4338.. _migration-2.6-openssl-changes:
4339
4340OpenSSL Changes
4341---------------
4342
4343`OpenSSL <https://www.openssl.org/>`__ has been upgraded from 1.0 to
43441.1. By default, this upgrade could cause problems for recipes that have
4345both versions in their dependency chains. The problem is that both
4346versions cannot be installed together at build time.
4347
4348.. note::
4349
4350 It is possible to have both versions of the library at runtime.
4351
4352.. _migration-2.6-bitbake-changes:
4353
4354BitBake Changes
4355---------------
4356
4357The server logfile ``bitbake-cookerdaemon.log`` is now always placed in
4358the :term:`Build Directory` instead of the current
4359directory.
4360
4361.. _migration-2.6-security-changes:
4362
4363Security Changes
4364----------------
4365
4366The Poky distribution now uses security compiler flags by default.
4367Inclusion of these flags could cause new failures due to stricter
4368checking for various potential security issues in code.
4369
4370.. _migration-2.6-post-installation-changes:
4371
4372Post Installation Changes
4373-------------------------
4374
4375You must explicitly mark post installs to defer to the target. If you
4376want to explicitly defer a postinstall to first boot on the target
4377rather than at rootfs creation time, use ``pkg_postinst_ontarget()`` or
4378call ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``.
4379Any failure of a ``pkg_postinst()`` script (including exit 1) triggers
4380an error during the :ref:`ref-tasks-rootfs` task.
4381
4382For more information on post-installation behavior, see the
4383":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`"
4384section in the Yocto Project Development Tasks Manual.
4385
4386.. _migration-2.6-python-3-profile-guided-optimizations:
4387
4388Python 3 Profile-Guided Optimization
4389------------------------------------
4390
4391The ``python3`` recipe now enables profile-guided optimization. Using
4392this optimization requires a little extra build time in exchange for
4393improved performance on the target at runtime. Additionally, the
4394optimization is only enabled if the current
4395:term:`MACHINE` has support for user-mode emulation in
4396QEMU (i.e. "qemu-usermode" is in
4397:term:`MACHINE_FEATURES`, which it is by
4398default).
4399
4400If you wish to disable Python profile-guided optimization regardless of
4401the value of ``MACHINE_FEATURES``, then ensure that
4402:term:`PACKAGECONFIG` for the ``python3`` recipe
4403does not contain "pgo". You could accomplish the latter using the
4404following at the configuration level:
4405::
4406
4407 PACKAGECONFIG_remove_pn-python3 = "pgo"
4408
4409Alternatively, you can set ``PACKAGECONFIG`` using an append file
4410for the ``python3`` recipe.
4411
4412.. _migration-2.6-miscellaneous-changes:
4413
4414Miscellaneous Changes
4415---------------------
4416
4417The following miscellaneous changes occurred:
4418
4419- Default to using the Thumb-2 instruction set for armv7a and above. If
4420 you have any custom recipes that build software that needs to be
4421 built with the ARM instruction set, change the recipe to set the
4422 instruction set as follows:
4423 ::
4424
4425 ARM_INSTRUCTION_SET = "arm"
4426
4427- ``run-postinsts`` no longer uses ``/etc/*-postinsts`` for
4428 ``dpkg/opkg`` in favor of built-in postinst support. RPM behavior
4429 remains unchanged.
4430
4431- The ``NOISO`` and ``NOHDD`` variables are no longer used. You now
4432 control building ``*.iso`` and ``*.hddimg`` image types directly by
4433 using the :term:`IMAGE_FSTYPES` variable.
4434
4435- The ``scripts/contrib/mkefidisk.sh`` has been removed in favor of
4436 Wic.
4437
4438- ``kernel-modules`` has been removed from
4439 :term:`RRECOMMENDS` for ``qemumips`` and
4440 ``qemumips64`` machines. Removal also impacts the ``x86-base.inc``
4441 file.
4442
4443 .. note::
4444
4445 genericx86
4446 and
4447 genericx86-64
4448 retain
4449 kernel-modules
4450 as part of the
4451 RRECOMMENDS
4452 variable setting.
4453
4454- The ``LGPLv2_WHITELIST_GPL-3.0`` variable has been removed. If you
4455 are setting this variable in your configuration, set or append it to
4456 the ``WHITELIST_GPL-3.0`` variable instead.
4457
4458- ``${ASNEEDED}`` is now included in the
4459 :term:`TARGET_LDFLAGS` variable directly. The
4460 remaining definitions from ``meta/conf/distro/include/as-needed.inc``
4461 have been moved to corresponding recipes.
4462
4463- Support for DSA host keys has been dropped from the OpenSSH recipes.
4464 If you are still using DSA keys, you must switch over to a more
4465 secure algorithm as recommended by OpenSSH upstream.
4466
4467- The ``dhcp`` recipe now uses the ``dhcpd6.conf`` configuration file
4468 in ``dhcpd6.service`` for IPv6 DHCP rather than re-using
4469 ``dhcpd.conf``, which is now reserved for IPv4.
4470
4471Moving to the Yocto Project 2.7 Release
4472=======================================
4473
4474This section provides migration information for moving to the Yocto
4475Project 2.7 Release from the prior release.
4476
4477.. _migration-2.7-bitbake-changes:
4478
4479BitBake Changes
4480---------------
4481
4482The following changes have been made to BitBake:
4483
4484- BitBake now checks anonymous Python functions and pure Python
4485 functions (e.g. ``def funcname:``) in the metadata for tab
4486 indentation. If found, BitBake produces a warning.
4487
4488- Bitbake now checks
4489 :term:`BBFILE_COLLECTIONS` for duplicate
4490 entries and triggers an error if any are found.
4491
4492.. _migration-2.7-eclipse-support-dropped:
4493
4494Eclipse Support Removed
4495-----------------------
4496
4497Support for the Eclipse IDE has been removed. Support continues for
4498those releases prior to 2.7 that did include support. The 2.7 release
4499does not include the Eclipse Yocto plugin.
4500
4501.. _migration-2.7-qemu-native-splits-system-and-user-mode-parts:
4502
4503``qemu-native`` Splits the System and User-Mode Parts
4504-----------------------------------------------------
4505
4506The system and user-mode parts of ``qemu-native`` are now split.
4507``qemu-native`` provides the user-mode components and
4508``qemu-system-native`` provides the system components. If you have
4509recipes that depend on QEMU's system emulation functionality at build
4510time, they should now depend upon ``qemu-system-native`` instead of
4511``qemu-native``.
4512
4513.. _migration-2.7-upstream-tracking.inc-removed:
4514
4515The ``upstream-tracking.inc`` File Has Been Removed
4516---------------------------------------------------
4517
4518The previously deprecated ``upstream-tracking.inc`` file is now removed.
4519Any ``UPSTREAM_TRACKING*`` variables are now set in the corresponding
4520recipes instead.
4521
4522Remove any references you have to the ``upstream-tracking.inc`` file in
4523your configuration.
4524
4525.. _migration-2.7-distro-features-libc-removed:
4526
4527The ``DISTRO_FEATURES_LIBC`` Variable Has Been Removed
4528------------------------------------------------------
4529
4530The ``DISTRO_FEATURES_LIBC`` variable is no longer used. The ability to
4531configure glibc using kconfig has been removed for quite some time
4532making the ``libc-*`` features set no longer effective.
4533
4534Remove any references you have to ``DISTRO_FEATURES_LIBC`` in your own
4535layers.
4536
4537.. _migration-2.7-license-values:
4538
4539License Value Corrections
4540-------------------------
4541
4542The following corrections have been made to the
4543:term:`LICENSE` values set by recipes:
4544
4545- *socat*: Corrected ``LICENSE`` to be "GPLv2" rather than "GPLv2+".
4546- *libgfortran*: Set license to "GPL-3.0-with-GCC-exception".
4547- *elfutils*: Removed "Elfutils-Exception" and set to "GPLv2" for shared libraries
4548
4549.. _migration-2.7-packaging-changes:
4550
4551Packaging Changes
4552-----------------
4553
4554This section provides information about packaging changes.
4555
4556- ``bind``: The ``nsupdate`` binary has been moved to the
4557 ``bind-utils`` package.
4558
4559- Debug split: The default debug split has been changed to create
4560 separate source packages (i.e. package_name\ ``-dbg`` and
4561 package_name\ ``-src``). If you are currently using ``dbg-pkgs`` in
4562 :term:`IMAGE_FEATURES` to bring in debug
4563 symbols and you still need the sources, you must now also add
4564 ``src-pkgs`` to ``IMAGE_FEATURES``. Source packages remain in the
4565 target portion of the SDK by default, unless you have set your own
4566 value for :term:`SDKIMAGE_FEATURES` that
4567 does not include ``src-pkgs``.
4568
4569- Mount all using ``util-linux``: ``/etc/default/mountall`` has moved
4570 into the -mount sub-package.
4571
4572- Splitting binaries using ``util-linux``: ``util-linux`` now splits
4573 each binary into its own package for fine-grained control. The main
4574 ``util-linux`` package pulls in the individual binary packages using
4575 the :term:`RRECOMMENDS` and
4576 :term:`RDEPENDS` variables. As a result, existing
4577 images should not see any changes assuming
4578 :term:`NO_RECOMMENDATIONS` is not set.
4579
4580- ``netbase/base-files``: ``/etc/hosts`` has moved from ``netbase`` to
4581 ``base-files``.
4582
4583- ``tzdata``: The main package has been converted to an empty meta
4584 package that pulls in all ``tzdata`` packages by default.
4585
4586- ``lrzsz``: This package has been removed from
4587 ``packagegroup-self-hosted`` and
4588 ``packagegroup-core-tools-testapps``. The X/Y/ZModem support is less
4589 likely to be needed on modern systems. If you are relying on these
4590 packagegroups to include the ``lrzsz`` package in your image, you now
4591 need to explicitly add the package.
4592
4593.. _migration-2.7-removed-recipes:
4594
4595Removed Recipes
4596---------------
4597
4598The following recipes have been removed:
4599
4600- *gcc*: Drop version 7.3 recipes. Version 8.3 now remains.
4601- *linux-yocto*: Drop versions 4.14 and 4.18 recipes. Versions 4.19 and 5.0 remain.
4602- *go*: Drop version 1.9 recipes. Versions 1.11 and 1.12 remain.
4603- *xvideo-tests*: Became obsolete.
4604- *libart-lgpl*: Became obsolete.
4605- *gtk-icon-utils-native*: These tools are now provided by gtk+3-native
4606- *gcc-cross-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
4607- *gcc-crosssdk-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
4608- *glibc-initial*: Removed because the benefits of having it for site_config are currently outweighed by the cost of building the recipe.
4609
4610.. _migration-2.7-removed-classes:
4611
4612Removed Classes
4613---------------
4614
4615The following classes have been removed:
4616
4617- *distutils-tools*: This class was never used.
4618- *bugzilla.bbclass*: Became obsolete.
4619- *distrodata*: This functionally has been replaced by a more modern tinfoil-based implementation.
4620
4621.. _migration-2.7-miscellaneous-changes:
4622
4623Miscellaneous Changes
4624---------------------
4625
4626The following miscellaneous changes occurred:
4627
4628- The ``distro`` subdirectory of the Poky repository has been removed
4629 from the top-level ``scripts`` directory.
4630
4631- Perl now builds for the target using
4632 `perl-cross <http://arsv.github.io/perl-cross/>`_ for better
4633 maintainability and improved build performance. This change should
4634 not present any problems unless you have heavily customized your Perl
4635 recipe.
4636
4637- ``arm-tunes``: Removed the "-march" option if mcpu is already added.
4638
4639- ``update-alternatives``: Convert file renames to
4640 :term:`PACKAGE_PREPROCESS_FUNCS`
4641
4642- ``base/pixbufcache``: Obsolete ``sstatecompletions`` code has been
4643 removed.
4644
4645- :ref:`native <ref-classes-native>` class:
4646 :term:`RDEPENDS` handling has been enabled.
4647
4648- ``inetutils``: This recipe has rsh disabled.
4649
4650Moving to the Yocto Project 3.0 Release
4651=======================================
4652
4653This section provides migration information for moving to the Yocto
4654Project 3.0 Release from the prior release.
4655
4656.. _migration-3.0-init-system-selection:
4657
4658Init System Selection
4659---------------------
4660
4661Changing the init system manager previously required setting a number of
4662different variables. You can now change the manager by setting the
4663``INIT_MANAGER`` variable and the corresponding include files (i.e.
4664``conf/distro/include/init-manager-*.conf``). Include files are provided
4665for four values: "none", "sysvinit", "systemd", and "mdev-busybox". The
4666default value, "none", for ``INIT_MANAGER`` should allow your current
4667settings to continue working. However, it is advisable to explicitly set
4668``INIT_MANAGER``.
4669
4670.. _migration-3.0-lsb-support-removed:
4671
4672LSB Support Removed
4673-------------------
4674
4675Linux Standard Base (LSB) as a standard is not current, and is not well
4676suited for embedded applications. Support can be continued in a separate
4677layer if needed. However, presently LSB support has been removed from
4678the core.
4679
4680As a result of this change, the ``poky-lsb`` derivative distribution
4681configuration that was also used for testing alternative configurations
4682has been replaced with a ``poky-altcfg`` distribution that has LSB parts
4683removed.
4684
4685.. _migration-3.0-removed-recipes:
4686
4687Removed Recipes
4688---------------
4689
4690The following recipes have been removed.
4691
4692- ``core-image-lsb-dev``: Part of removed LSB support.
4693
4694- ``core-image-lsb``: Part of removed LSB support.
4695
4696- ``core-image-lsb-sdk``: Part of removed LSB support.
4697
4698- ``cve-check-tool``: Functionally replaced by the ``cve-update-db``
4699 recipe and ``cve-check`` class.
4700
4701- ``eglinfo``: No longer maintained. ``eglinfo`` from ``mesa-demos`` is
4702 an adequate and maintained alternative.
4703
4704- ``gcc-8.3``: Version 8.3 removed. Replaced by 9.2.
4705
4706- ``gnome-themes-standard``: Only needed by gtk+ 2.x, which has been
4707 removed.
4708
4709- ``gtk+``: GTK+ 2 is obsolete and has been replaced by gtk+3.
4710
4711- ``irda-utils``: Has become obsolete. IrDA support has been removed
4712 from the Linux kernel in version 4.17 and later.
4713
4714- ``libnewt-python``: ``libnewt`` Python support merged into main
4715 ``libnewt`` recipe.
4716
4717- ``libsdl``: Replaced by newer ``libsdl2``.
4718
4719- ``libx11-diet``: Became obsolete.
4720
4721- ``libxx86dga``: Removed obsolete client library.
4722
4723- ``libxx86misc``: Removed. Library is redundant.
4724
4725- ``linux-yocto``: Version 5.0 removed, which is now redundant (5.2 /
4726 4.19 present).
4727
4728- ``lsbinitscripts``: Part of removed LSB support.
4729
4730- ``lsb``: Part of removed LSB support.
4731
4732- ``lsbtest``: Part of removed LSB support.
4733
4734- ``openssl10``: Replaced by newer ``openssl`` version 1.1.
4735
4736- ``packagegroup-core-lsb``: Part of removed LSB support.
4737
4738- ``python-nose``: Removed the Python 2.x version of the recipe.
4739
4740- ``python-numpy``: Removed the Python 2.x version of the recipe.
4741
4742- ``python-scons``: Removed the Python 2.x version of the recipe.
4743
4744- ``source-highlight``: No longer needed.
4745
4746- ``stress``: Replaced by ``stress-ng``.
4747
4748- ``vulkan``: Split into ``vulkan-loader``, ``vulkan-headers``, and
4749 ``vulkan-tools``.
4750
4751- ``weston-conf``: Functionality moved to ``weston-init``.
4752
4753.. _migration-3.0-packaging-changes:
4754
4755Packaging Changes
4756-----------------
4757
4758The following packaging changes have occurred.
4759
4760- The `Epiphany <https://en.wikipedia.org/wiki/GNOME_Web>`__ browser
4761 has been dropped from ``packagegroup-self-hosted`` as it has not been
4762 needed inside ``build-appliance-image`` for quite some time and was
4763 causing resource problems.
4764
4765- ``libcap-ng`` Python support has been moved to a separate
4766 ``libcap-ng-python`` recipe to streamline the build process when the
4767 Python bindings are not needed.
4768
4769- ``libdrm`` now packages the file ``amdgpu.ids`` into a separate
4770 ``libdrm-amdgpu`` package.
4771
4772- ``python3``: The ``runpy`` module is now in the ``python3-core``
4773 package as it is required to support the common "python3 -m" command
4774 usage.
4775
4776- ``distcc`` now provides separate ``distcc-client`` and
4777 ``distcc-server`` packages as typically one or the other are needed,
4778 rather than both.
4779
4780- ``python*-setuptools`` recipes now separately package the
4781 ``pkg_resources`` module in a ``python-pkg-resources`` /
4782 ``python3-pkg-resources`` package as the module is useful independent
4783 of the rest of the setuptools package. The main ``python-setuptools``
4784 / ``python3-setuptools`` package depends on this new package so you
4785 should only need to update dependencies unless you want to take
4786 advantage of the increased granularity.
4787
4788.. _migration-3.0-cve-checking:
4789
4790CVE Checking
4791------------
4792
4793``cve-check-tool`` has been functionally replaced by a new
4794``cve-update-db`` recipe and functionality built into the ``cve-check``
4795class. The result uses NVD JSON data feeds rather than the deprecated
4796XML feeds that ``cve-check-tool`` was using, supports CVSSv3 scoring,
4797and makes other improvements.
4798
4799Additionally, the ``CVE_CHECK_CVE_WHITELIST`` variable has been replaced
4800by ``CVE_CHECK_WHITELIST``.
4801
4802.. _migration-3.0-bitbake-changes:
4803
4804Bitbake Changes
4805---------------
4806
4807The following BitBake changes have occurred.
4808
4809- ``addtask`` statements now properly validate dependent tasks.
4810 Previously, an invalid task was silently ignored. With this change,
4811 the invalid task generates a warning.
4812
4813- Other invalid ``addtask`` and ``deltask`` usages now trigger these
4814 warnings: "multiple target tasks arguments with addtask / deltask",
4815 and "multiple before/after clauses".
4816
4817- The "multiconfig" prefix is now shortened to "mc". "multiconfig" will
4818 continue to work, however it may be removed in a future release.
4819
4820- The ``bitbake -g`` command no longer generates a
4821 ``recipe-depends.dot`` file as the contents (i.e. a reprocessed
4822 version of ``task-depends.dot``) were confusing.
4823
4824- The ``bb.build.FuncFailed`` exception, previously raised by
4825 ``bb.build.exec_func()`` when certain other exceptions have occurred,
4826 has been removed. The real underlying exceptions will be raised
4827 instead. If you have calls to ``bb.build.exec_func()`` in custom
4828 classes or ``tinfoil-using`` scripts, any references to
4829 ``bb.build.FuncFailed`` should be cleaned up.
4830
4831- Additionally, the ``bb.build.exec_func()`` no longer accepts the
4832 "pythonexception" parameter. The function now always raises
4833 exceptions. Remove this argument in any calls to
4834 ``bb.build.exec_func()`` in custom classes or scripts.
4835
4836- The
4837 :term:`bitbake:BB_SETSCENE_VERIFY_FUNCTION2`
4838 is no longer used. In the unlikely event that you have any references
4839 to it, they should be removed.
4840
4841- The ``RunQueueExecuteScenequeue`` and ``RunQueueExecuteTasks`` events
4842 have been removed since setscene tasks are now executed as part of
4843 the normal runqueue. Any event handling code in custom classes or
4844 scripts that handles these two events need to be updated.
4845
4846- The arguments passed to functions used with
4847 :term:`bitbake:BB_HASHCHECK_FUNCTION`
4848 have changed. If you are using your own custom hash check function,
4849 see
4850 http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725
4851 for details.
4852
4853- Task specifications in ``BB_TASKDEPDATA`` and class implementations
4854 used in signature generator classes now use "<fn>:<task>" everywhere
4855 rather than the "." delimiter that was being used in some places.
4856 This change makes it consistent with all areas in the code. Custom
4857 signature generator classes and code that reads ``BB_TASKDEPDATA``
4858 need to be updated to use ':' as a separator rather than '.'.
4859
4860.. _migration-3.0-sanity-checks:
4861
4862Sanity Checks
4863-------------
4864
4865The following sanity check changes occurred.
4866
4867- :term:`SRC_URI` is now checked for usage of two
4868 problematic items:
4869
4870 - "${PN}" prefix/suffix use - Warnings always appear if ${PN} is
4871 used. You must fix the issue regardless of whether multiconfig or
4872 anything else that would cause prefixing/suffixing to happen.
4873
4874 - Github archive tarballs - these are not guaranteed to be stable.
4875 Consequently, it is likely that the tarballs will be refreshed and
4876 thus the SRC_URI checksums will fail to apply. It is recommended
4877 that you fetch either an official release tarball or a specific
4878 revision from the actual Git repository instead.
4879
4880 Either one of these items now trigger a warning by default. If you
4881 wish to disable this check, remove ``src-uri-bad`` from
4882 :term:`WARN_QA`.
4883
4884- The ``file-rdeps`` runtime dependency check no longer expands
4885 :term:`RDEPENDS` recursively as there is no mechanism
4886 to ensure they can be fully computed, and thus races sometimes result
4887 in errors either showing up or not. Thus, you might now see errors
4888 for missing runtime dependencies that were previously satisfied
4889 recursively. Here is an example: package A contains a shell script
4890 starting with ``#!/bin/bash`` but has no dependency on bash. However,
4891 package A depends on package B, which does depend on bash. You need
4892 to add the missing dependency or dependencies to resolve the warning.
4893
4894- Setting ``DEPENDS_${PN}`` anywhere (i.e. typically in a recipe) now
4895 triggers an error. The error is triggered because
4896 :term:`DEPENDS` is not a package-specific variable
4897 unlike RDEPENDS. You should set ``DEPENDS`` instead.
4898
4899- systemd currently does not work well with the musl C library because
4900 only upstream officially supports linking the library with glibc.
4901 Thus, a warning is shown when building systemd in conjunction with
4902 musl.
4903
4904.. _migration-3.0-miscellaneous-changes:
4905
4906Miscellaneous Changes
4907---------------------
4908
4909The following miscellaneous changes have occurred.
4910
4911- The ``gnome`` class has been removed because it now does very little.
4912 You should update recipes that previously inherited this class to do
4913 the following: inherit gnomebase gtk-icon-cache gconf mime
4914
4915- The ``meta/recipes-kernel/linux/linux-dtb.inc`` file has been
4916 removed. This file was previously deprecated in favor of setting
4917 :term:`KERNEL_DEVICETREE` in any kernel
4918 recipe and only produced a warning. Remove any ``include`` or
4919 ``require`` statements pointing to this file.
4920
4921- :term:`TARGET_CFLAGS`,
4922 :term:`TARGET_CPPFLAGS`,
4923 :term:`TARGET_CXXFLAGS`, and
4924 :term:`TARGET_LDFLAGS` are no longer exported
4925 to the external environment. This change did not require any changes
4926 to core recipes, which is a good indicator that no changes will be
4927 required. However, if for some reason the software being built by one
4928 of your recipes is expecting these variables to be set, then building
4929 the recipe will fail. In such cases, you must either export the
4930 variable or variables in the recipe or change the scripts so that
4931 exporting is not necessary.
4932
4933- You must change the host distro identifier used in
4934 :term:`NATIVELSBSTRING` to use all lowercase
4935 characters even if it does not contain a version number. This change
4936 is necessary only if you are not using ``uninative`` and
4937 :term:`SANITY_TESTED_DISTROS`.
4938
4939- In the ``base-files`` recipe, writing the hostname into
4940 ``/etc/hosts`` and ``/etc/hostname`` is now done within the main
4941 :ref:`ref-tasks-install` function rather than in the
4942 ``do_install_basefilesissue`` function. The reason for the change is
4943 because ``do_install_basefilesissue`` is more easily overridden
4944 without having to duplicate the hostname functionality. If you have
4945 done the latter (e.g. in a ``base-files`` bbappend), then you should
4946 remove it from your customized ``do_install_basefilesissue``
4947 function.
4948
4949- The ``wic --expand`` command now uses commas to separate "key:value"
4950 pairs rather than hyphens.
4951
4952 .. note::
4953
4954 The wic command-line help is not updated.
4955
4956 You must update any scripts or commands where you use
4957 ``wic --expand`` with multiple "key:value" pairs.
4958
4959- UEFI image variable settings have been moved from various places to a
4960 central ``conf/image-uefi.conf``. This change should not influence
4961 any existing configuration as the ``meta/conf/image-uefi.conf`` in
4962 the core metadata sets defaults that can be overridden in the same
4963 manner as before.
4964
4965- ``conf/distro/include/world-broken.inc`` has been removed. For cases
4966 where certain recipes need to be disabled when using the musl C
4967 library, these recipes now have ``COMPATIBLE_HOST_libc-musl`` set
4968 with a comment that explains why.
4969
4970Moving to the Yocto Project 3.1 Release
4971=======================================
4972
4973This section provides migration information for moving to the Yocto
4974Project 3.1 Release from the prior release.
4975
4976.. _migration-3.1-minimum-system-requirements:
4977
4978Minimum system requirements
4979---------------------------
4980
4981The following versions / requirements of build host components have been
4982updated:
4983
4984- gcc 5.0
4985
4986- python 3.5
4987
4988- tar 1.28
4989
4990- ``rpcgen`` is now required on the host (part of the ``libc-dev-bin``
4991 package on Ubuntu, Debian and related distributions, and the
4992 ``glibc`` package on RPM-based distributions).
4993
4994Additionally, the ``makeinfo`` and ``pod2man`` tools are *no longer*
4995required on the host.
4996
4997.. _migration-3.1-mpc8315e-rdb-removed:
4998
4999mpc8315e-rdb machine removed
5000----------------------------
5001
5002The MPC8315E-RDB machine is old/obsolete and unobtainable, thus given
5003the maintenance burden the ``mpc8315e-rdb`` machine configuration that
5004supported it has been removed in this release. The removal does leave a
5005gap in official PowerPC reference hardware support; this may change in
5006future if a suitable machine with accompanying support resources is
5007found.
5008
5009.. _migration-3.1-python-2-removed:
5010
5011Python 2 removed
5012----------------
5013
5014Due to the expiration of upstream support in January 2020, support for
5015Python 2 has now been removed; it is recommended that you use Python 3
5016instead. If absolutely needed there is a meta-python2 community layer
5017containing Python 2, related classes and various Python 2-based modules,
5018however it should not be considered as supported.
5019
5020.. _migration-3.1-reproducible-builds:
5021
5022Reproducible builds now enabled by default
5023------------------------------------------
5024
5025In order to avoid unnecessary differences in output files (aiding binary
5026reproducibility), the Poky distribution configuration
5027(``DISTRO = "poky"``) now inherits the ``reproducible_build`` class by
5028default.
5029
5030.. _migration-3.1-ptest-feature-impact:
5031
5032Impact of ptest feature is now more significant
5033-----------------------------------------------
5034
5035The Poky distribution configuration (``DISTRO = "poky"``) enables ptests
5036by default to enable runtime testing of various components. In this
5037release, a dependency needed to be added that has resulted in a
5038significant increase in the number of components that will be built just
5039when building a simple image such as core-image-minimal. If you do not
5040need runtime tests enabled for core components, then it is recommended
5041that you remove "ptest" from
5042:term:`DISTRO_FEATURES` to save a significant
5043amount of build time e.g. by adding the following in your configuration:
5044::
5045
5046 DISTRO_FEATURES_remove = "ptest"
5047
5048.. _migration-3.1-removed-recipes:
5049
5050Removed recipes
5051---------------
5052
5053The following recipes have been removed:
5054
5055- ``chkconfig``: obsolete
5056
5057- ``console-tools``: obsolete
5058
5059- ``enchant``: replaced by ``enchant2``
5060
5061- ``foomatic-filters``: obsolete
5062
5063- ``libidn``: no longer needed, moved to meta-oe
5064
5065- ``libmodulemd``: replaced by ``libmodulemd-v1``
5066
5067- ``linux-yocto``: drop 4.19, 5.2 version recipes (5.4 now provided)
5068
5069- ``nspr``: no longer needed, moved to meta-oe
5070
5071- ``nss``: no longer needed, moved to meta-oe
5072
5073- ``python``: Python 2 removed (Python 3 preferred)
5074
5075- ``python-setuptools``: Python 2 version removed (python3-setuptools
5076 preferred)
5077
5078- ``sysprof``: no longer needed, moved to meta-oe
5079
5080- ``texi2html``: obsolete
5081
5082- ``u-boot-fw-utils``: functionally replaced by ``libubootenv``
5083
5084.. _migration-3.1-features-check:
5085
5086features_check class replaces distro_features_check
5087---------------------------------------------------
5088
5089The ``distro_features_check`` class has had its functionality expanded,
5090now supporting ``ANY_OF_MACHINE_FEATURES``,
5091``REQUIRED_MACHINE_FEATURES``, ``CONFLICT_MACHINE_FEATURES``,
5092``ANY_OF_COMBINED_FEATURES``, ``REQUIRED_COMBINED_FEATURES``,
5093``CONFLICT_COMBINED_FEATURES``. As a result the class has now been
5094renamed to ``features_check``; the ``distro_features_check`` class still
5095exists but generates a warning and redirects to the new class. In
5096preparation for a future removal of the old class it is recommended that
5097you update recipes currently inheriting ``distro_features_check`` to
5098inherit ``features_check`` instead.
5099
5100.. _migration-3.1-removed-classes:
5101
5102Removed classes
5103---------------
5104
5105The following classes have been removed:
5106
5107- ``distutils-base``: moved to meta-python2
5108
5109- ``distutils``: moved to meta-python2
5110
5111- ``libc-common``: merged into the glibc recipe as nothing else used
5112 it.
5113
5114- ``python-dir``: moved to meta-python2
5115
5116- ``pythonnative``: moved to meta-python2
5117
5118- ``setuptools``: moved to meta-python2
5119
5120- ``tinderclient``: dropped as it was obsolete.
5121
5122.. _migration-3.1-src-uri-checksums:
5123
5124SRC_URI checksum behaviour
5125--------------------------
5126
5127Previously, recipes by tradition included both SHA256 and MD5 checksums
5128for remotely fetched files in :term:`SRC_URI`, even
5129though only one is actually mandated. However, the MD5 checksum does not
5130add much given its inherent weakness; thus when a checksum fails only
5131the SHA256 sum will now be printed. The md5sum will still be verified if
5132it is specified.
5133
5134.. _migration-3.1-npm:
5135
5136npm fetcher changes
5137-------------------
5138
5139The npm fetcher has been completely reworked in this release. The npm
5140fetcher now only fetches the package source itself and no longer the
5141dependencies; there is now also an npmsw fetcher which explicitly
5142fetches the shrinkwrap file and the dependencies. This removes the
5143slightly awkward ``NPM_LOCKDOWN`` and ``NPM_SHRINKWRAP`` variables which
5144pointed to local files; the lockdown file is no longer needed at all.
5145Additionally, the package name in ``npm://`` entries in
5146:term:`SRC_URI` is now specified using a ``package``
5147parameter instead of the earlier ``name`` which overlapped with the
5148generic ``name`` parameter. All recipes using the npm fetcher will need
5149to be changed as a result.
5150
5151An example of the new scheme: ::
5152
5153 SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \
5154 npmsw://${THISDIR}/npm-shrinkwrap.json"
5155
5156Another example where the sources are fetched from git rather than an npm repository: ::
5157
5158 SRC_URI = "git://github.com/foo/bar.git;protocol=https \
5159 npmsw://${THISDIR}/npm-shrinkwrap.json"
5160
5161devtool and recipetool have also been updated to match with the npm
5162fetcher changes. Other than producing working and more complete recipes
5163for npm sources, there is also a minor change to the command line for
5164devtool: the ``--fetch-dev`` option has been renamed to ``--npm-dev`` as
5165it is npm-specific.
5166
5167.. _migration-3.1-packaging-changes:
5168
5169Packaging changes
5170-----------------
5171
5172- ``intltool`` has been removed from ``packagegroup-core-sdk`` as it is
5173 rarely needed to build modern software - gettext can do most of the
5174 things it used to be needed for. ``intltool`` has also been removed
5175 from ``packagegroup-core-self-hosted`` as it is not needed to for
5176 standard builds.
5177
5178- git: ``git-am``, ``git-difftool``, ``git-submodule``, and
5179 ``git-request-pull`` are no longer perl-based, so are now installed
5180 with the main ``git`` package instead of within ``git-perltools``.
5181
5182- The ``ldconfig`` binary built as part of glibc has now been moved to
5183 its own ``ldconfig`` package (note no ``glibc-`` prefix). This
5184 package is in the :term:`RRECOMMENDS` of the main
5185 ``glibc`` package if ``ldconfig`` is present in
5186 :term:`DISTRO_FEATURES`.
5187
5188- ``libevent`` now splits each shared library into its own package (as
5189 Debian does). Since these are shared libraries and will be pulled in
5190 through the normal shared library dependency handling, there should
5191 be no impact to existing configurations other than less unnecessary
5192 libraries being installed in some cases.
5193
5194- linux-firmware now has a new package for ``bcm4366c`` and includes
5195 available NVRAM config files into the ``bcm43340``, ``bcm43362``,
5196 ``bcm43430`` and ``bcm4356-pcie`` packages.
5197
5198- ``harfbuzz`` now splits the new ``libharfbuzz-subset.so`` library
5199 into its own package to reduce the main package size in cases where
5200 ``libharfbuzz-subset.so`` is not needed.
5201
5202.. _migration-3.1-package-qa-warnings:
5203
5204Additional warnings
5205-------------------
5206
5207Warnings will now be shown at ``do_package_qa`` time in the following
5208circumstances:
5209
5210- A recipe installs ``.desktop`` files containing ``MimeType`` keys but
5211 does not inherit the new ``mime-xdg`` class
5212
5213- A recipe installs ``.xml`` files into ``${datadir}/mime/packages``
5214 but does not inherit the ``mime`` class
5215
5216.. _migration-3.1-x86-live-wic:
5217
5218``wic`` image type now used instead of ``live`` by default for x86
5219------------------------------------------------------------------
5220
5221``conf/machine/include/x86-base.inc`` (inherited by most x86 machine
5222configurations) now specifies ``wic`` instead of ``live`` by default in
5223:term:`IMAGE_FSTYPES`. The ``live`` image type will
5224likely be removed in a future release so it is recommended that you use
5225``wic`` instead.
5226
5227.. _migration-3.1-misc:
5228
5229Miscellaneous changes
5230---------------------
5231
5232- The undocumented ``SRC_DISTRIBUTE_LICENSES`` variable has now been
5233 removed in favour of a new ``AVAILABLE_LICENSES`` variable which is
5234 dynamically set based upon license files found in
5235 ``${COMMON_LICENSE_DIR}`` and ``${LICENSE_PATH}``.
5236
5237- The tune definition for big-endian microblaze machines is now
5238 ``microblaze`` instead of ``microblazeeb``.
5239
5240- ``newlib`` no longer has built-in syscalls. ``libgloss`` should then
5241 provide the syscalls, ``crt0.o`` and other functions that are no
5242 longer part of ``newlib`` itself. If you are using
5243 ``TCLIBC = "newlib"`` this now means that you must link applications
5244 with both ``newlib`` and ``libgloss``, whereas before ``newlib``
5245 would run in many configurations by itself.