summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorMichael Opdenacker <michael.opdenacker@bootlin.com>2021-06-10 11:26:21 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2021-06-14 22:45:33 +0100
commit5f978a6ccacf9f7f9475207c5a2a1af1dc4c3d00 (patch)
treefa7ba7ced9e17426b72e07c50288163a5d8ba901 /documentation/ref-manual
parentdae1e986a0608d899f67f1ae62389d350824235f (diff)
downloadpoky-5f978a6ccacf9f7f9475207c5a2a1af1dc4c3d00.tar.gz
ref-manual: move migration guides to separate document
This makes the reference manual much lighter by moving the migration guides to a separate document. The migration guides are also reordered from last to first, and they appear directly in the left bar, making them easier to find in the documentation. (From yocto-docs rev: 5121b86ee97eb62a0c69c9ad1fc0e3fabbe3e934) Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/index.rst1
-rw-r--r--documentation/ref-manual/migration-1.3.rst194
-rw-r--r--documentation/ref-manual/migration-1.4.rst235
-rw-r--r--documentation/ref-manual/migration-1.5.rst353
-rw-r--r--documentation/ref-manual/migration-1.6.rst414
-rw-r--r--documentation/ref-manual/migration-1.7.rst221
-rw-r--r--documentation/ref-manual/migration-1.8.rst183
-rw-r--r--documentation/ref-manual/migration-2.0.rst278
-rw-r--r--documentation/ref-manual/migration-2.1.rst432
-rw-r--r--documentation/ref-manual/migration-2.2.rst446
-rw-r--r--documentation/ref-manual/migration-2.3.rst517
-rw-r--r--documentation/ref-manual/migration-2.4.rst327
-rw-r--r--documentation/ref-manual/migration-2.5.rst308
-rw-r--r--documentation/ref-manual/migration-2.6.rst452
-rw-r--r--documentation/ref-manual/migration-2.7.rst180
-rw-r--r--documentation/ref-manual/migration-3.0.rst319
-rw-r--r--documentation/ref-manual/migration-3.1.rst275
-rw-r--r--documentation/ref-manual/migration-3.2.rst313
-rw-r--r--documentation/ref-manual/migration-3.3.rst168
-rw-r--r--documentation/ref-manual/migration-general.rst54
-rw-r--r--documentation/ref-manual/migration.rst32
-rw-r--r--documentation/ref-manual/release-process.rst6
22 files changed, 4 insertions, 5704 deletions
diff --git a/documentation/ref-manual/index.rst b/documentation/ref-manual/index.rst
index deb0383cfc..5cf10c5c2f 100644
--- a/documentation/ref-manual/index.rst
+++ b/documentation/ref-manual/index.rst
@@ -13,7 +13,6 @@ Yocto Project Reference Manual
13 system-requirements 13 system-requirements
14 terms 14 terms
15 release-process 15 release-process
16 migration
17 structure 16 structure
18 classes 17 classes
19 tasks 18 tasks
diff --git a/documentation/ref-manual/migration-1.3.rst b/documentation/ref-manual/migration-1.3.rst
deleted file mode 100644
index b90767ff90..0000000000
--- a/documentation/ref-manual/migration-1.3.rst
+++ /dev/null
@@ -1,194 +0,0 @@
1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Moving to the Yocto Project 1.3 Release (danny)
4===============================================
5
6This section provides migration information for moving to the Yocto
7Project 1.3 Release (codename "danny") 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
176:yocto_git:`/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 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
187
188Because the ``PE`` variable is not set by default, these binary files
189could result with names that include two dash characters. Here is an
190example::
191
192 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
193
194
diff --git a/documentation/ref-manual/migration-1.4.rst b/documentation/ref-manual/migration-1.4.rst
deleted file mode 100644
index deb848749c..0000000000
--- a/documentation/ref-manual/migration-1.4.rst
+++ /dev/null
@@ -1,235 +0,0 @@
1Moving to the Yocto Project 1.4 Release (dylan)
2===============================================
3
4This section provides migration information for moving to the Yocto
5Project 1.4 Release (codename "dylan") 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 $ bitbake -c rootfs some-image
46
47 Instead, the system just needs to extract the
48 output package contents, re-create the packages, and construct the
49 root filesystem. This change is unlikely to cause any problems unless
50 you have missing declared dependencies.
51
52- *Scanning Directory Names:* When scanning for files in
53 :term:`SRC_URI`, the build system now uses
54 :term:`FILESOVERRIDES` instead of
55 :term:`OVERRIDES` for the directory names. In
56 general, the values previously in ``OVERRIDES`` are now in
57 ``FILESOVERRIDES`` as well. However, if you relied upon an additional
58 value you previously added to ``OVERRIDES``, you might now need to
59 add it to ``FILESOVERRIDES`` unless you are already adding it through
60 the :term:`MACHINEOVERRIDES` or
61 :term:`DISTROOVERRIDES` variables, as
62 appropriate. For more related changes, see the
63 ":ref:`ref-manual/migration-1.4:variables`" section.
64
65.. _migration-1.4-proxies-and-fetching-source:
66
67Proxies and Fetching Source
68---------------------------
69
70A new ``oe-git-proxy`` script has been added to replace previous methods
71of handling proxies and fetching source from Git. See the
72``meta-yocto/conf/site.conf.sample`` file for information on how to use
73this script.
74
75.. _migration-1.4-custom-interfaces-file-netbase-change:
76
77Custom Interfaces File (netbase change)
78---------------------------------------
79
80If you have created your own custom ``etc/network/interfaces`` file by
81creating an append file for the ``netbase`` recipe, you now need to
82create an append file for the ``init-ifupdown`` recipe instead, which
83you can find in the :term:`Source Directory` at
84``meta/recipes-core/init-ifupdown``. For information on how to use
85append files, see the
86":ref:`dev-manual/common-tasks:using .bbappend files in your layer`"
87section in the Yocto Project Development Tasks Manual.
88
89.. _migration-1.4-remote-debugging:
90
91Remote Debugging
92----------------
93
94Support for remote debugging with the Eclipse IDE is now separated into
95an image feature (``eclipse-debug``) that corresponds to the
96``packagegroup-core-eclipse-debug`` package group. Previously, the
97debugging feature was included through the ``tools-debug`` image
98feature, which corresponds to the ``packagegroup-core-tools-debug``
99package group.
100
101.. _migration-1.4-variables:
102
103Variables
104---------
105
106The following variables have changed:
107
108- ``SANITY_TESTED_DISTROS``: This variable now uses a distribution
109 ID, which is composed of the host distributor ID followed by the
110 release. Previously,
111 :term:`SANITY_TESTED_DISTROS` was
112 composed of the description field. For example, "Ubuntu 12.10"
113 becomes "Ubuntu-12.10". You do not need to worry about this change if
114 you are not specifically setting this variable, or if you are
115 specifically setting it to "".
116
117- ``SRC_URI``: The ``${``\ :term:`PN`\ ``}``,
118 ``${``\ :term:`PF`\ ``}``,
119 ``${``\ :term:`P`\ ``}``, and ``FILE_DIRNAME`` directories
120 have been dropped from the default value of the
121 :term:`FILESPATH` variable, which is used as the
122 search path for finding files referred to in
123 :term:`SRC_URI`. If you have a recipe that relied upon
124 these directories, which would be unusual, then you will need to add
125 the appropriate paths within the recipe or, alternatively, rearrange
126 the files. The most common locations are still covered by ``${``\ :term:`BP`\ ``}``,
127 ``${``\ :term:`BPN`\ ``}``, and "files", which all remain in the default value of
128 :term:`FILESPATH`.
129
130.. _migration-target-package-management-with-rpm:
131
132Target Package Management with RPM
133----------------------------------
134
135If runtime package management is enabled and the RPM backend is
136selected, Smart is now installed for package download, dependency
137resolution, and upgrades instead of Zypper. For more information on how
138to use Smart, run the following command on the target::
139
140 smart --help
141
142.. _migration-1.4-recipes-moved:
143
144Recipes Moved
145-------------
146
147The following recipes were moved from their previous locations because
148they are no longer used by anything in the OpenEmbedded-Core:
149
150- ``clutter-box2d``: Now resides in the ``meta-oe`` layer.
151
152- ``evolution-data-server``: Now resides in the ``meta-gnome`` layer.
153
154- ``gthumb``: Now resides in the ``meta-gnome`` layer.
155
156- ``gtkhtml2``: Now resides in the ``meta-oe`` layer.
157
158- ``gupnp``: Now resides in the ``meta-multimedia`` layer.
159
160- ``gypsy``: Now resides in the ``meta-oe`` layer.
161
162- ``libcanberra``: Now resides in the ``meta-gnome`` layer.
163
164- ``libgdata``: Now resides in the ``meta-gnome`` layer.
165
166- ``libmusicbrainz``: Now resides in the ``meta-multimedia`` layer.
167
168- ``metacity``: Now resides in the ``meta-gnome`` layer.
169
170- ``polkit``: Now resides in the ``meta-oe`` layer.
171
172- ``zeroconf``: Now resides in the ``meta-networking`` layer.
173
174.. _migration-1.4-removals-and-renames:
175
176Removals and Renames
177--------------------
178
179The following list shows what has been removed or renamed:
180
181- ``evieext``: Removed because it has been removed from ``xserver``
182 since 2008.
183
184- *Gtk+ DirectFB:* Removed support because upstream Gtk+ no longer
185 supports it as of version 2.18.
186
187- ``libxfontcache / xfontcacheproto``: Removed because they were
188 removed from the Xorg server in 2008.
189
190- ``libxp / libxprintapputil / libxprintutil / printproto``: Removed
191 because the XPrint server was removed from Xorg in 2008.
192
193- ``libxtrap / xtrapproto``: Removed because their functionality was
194 broken upstream.
195
196- *linux-yocto 3.0 kernel:* Removed with linux-yocto 3.8 kernel being
197 added. The linux-yocto 3.2 and linux-yocto 3.4 kernels remain as part
198 of the release.
199
200- ``lsbsetup``: Removed with functionality now provided by
201 ``lsbtest``.
202
203- ``matchbox-stroke``: Removed because it was never more than a
204 proof-of-concept.
205
206- ``matchbox-wm-2 / matchbox-theme-sato-2``: Removed because they are
207 not maintained. However, ``matchbox-wm`` and ``matchbox-theme-sato``
208 are still provided.
209
210- ``mesa-dri``: Renamed to ``mesa``.
211
212- ``mesa-xlib``: Removed because it was no longer useful.
213
214- ``mutter``: Removed because nothing ever uses it and the recipe is
215 very old.
216
217- ``orinoco-conf``: Removed because it has become obsolete.
218
219- ``update-modules``: Removed because it is no longer used. The
220 kernel module ``postinstall`` and ``postrm`` scripts can now do the
221 same task without the use of this script.
222
223- ``web``: Removed because it is not maintained. Superseded by
224 ``web-webkit``.
225
226- ``xf86bigfontproto``: Removed because upstream it has been disabled
227 by default since 2007. Nothing uses ``xf86bigfontproto``.
228
229- ``xf86rushproto``: Removed because its dependency in ``xserver``
230 was spurious and it was removed in 2005.
231
232- ``zypper / libzypp / sat-solver``: Removed and been functionally
233 replaced with Smart (``python-smartpm``) when RPM packaging is used
234 and package management is enabled on the target.
235
diff --git a/documentation/ref-manual/migration-1.5.rst b/documentation/ref-manual/migration-1.5.rst
deleted file mode 100644
index c772e51b54..0000000000
--- a/documentation/ref-manual/migration-1.5.rst
+++ /dev/null
@@ -1,353 +0,0 @@
1Moving to the Yocto Project 1.5 Release (dora)
2==============================================
3
4This section provides migration information for moving to the Yocto
5Project 1.5 Release (codename "dora") 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
29":ref:`ref-manual/system-requirements: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 ``genericx86-64`` BSP has been added for 64-bit Atom
45 systems.
46
47.. _migration-1.5-bitbake:
48
49BitBake
50-------
51
52The following changes have been made that relate to BitBake:
53
54- BitBake now supports a ``_remove`` operator. The addition of this
55 operator means you will have to rename any items in recipe space
56 (functions, variables) whose names currently contain ``_remove_`` or
57 end with ``_remove`` to avoid unexpected behavior.
58
59- BitBake's global method pool has been removed. This method is not
60 particularly useful and led to clashes between recipes containing
61 functions that had the same name.
62
63- The "none" server backend has been removed. The "process" server
64 backend has been serving well as the default for a long time now.
65
66- The ``bitbake-runtask`` script has been removed.
67
68- ``${``\ :term:`P`\ ``}`` and
69 ``${``\ :term:`PF`\ ``}`` are no longer added to
70 :term:`PROVIDES` by default in ``bitbake.conf``.
71 These version-specific ``PROVIDES`` items were seldom used.
72 Attempting to use them could result in two versions being built
73 simultaneously rather than just one version due to the way BitBake
74 resolves dependencies.
75
76.. _migration-1.5-qa-warnings:
77
78QA Warnings
79-----------
80
81The following changes have been made to the package QA checks:
82
83- If you have customized :term:`ERROR_QA` or
84 :term:`WARN_QA` values in your configuration, check
85 that they contain all of the issues that you wish to be reported.
86 Previous Yocto Project versions contained a bug that meant that any
87 item not mentioned in ``ERROR_QA`` or ``WARN_QA`` would be treated as
88 a warning. Consequently, several important items were not already in
89 the default value of ``WARN_QA``. All of the possible QA checks are
90 now documented in the ":ref:`insane.bbclass <ref-classes-insane>`"
91 section.
92
93- An additional QA check has been added to check if
94 ``/usr/share/info/dir`` is being installed. Your recipe should delete
95 this file within :ref:`ref-tasks-install` if "make
96 install" is installing it.
97
98- If you are using the ``buildhistory`` class, the check for the package
99 version going backwards is now controlled using a standard QA check.
100 Thus, if you have customized your ``ERROR_QA`` or ``WARN_QA`` values
101 and still wish to have this check performed, you should add
102 "version-going-backwards" to your value for one or the other
103 variables depending on how you wish it to be handled. See the
104 documented QA checks in the
105 ":ref:`insane.bbclass <ref-classes-insane>`" section.
106
107.. _migration-1.5-directory-layout-changes:
108
109Directory Layout Changes
110------------------------
111
112The following directory changes exist:
113
114- Output SDK installer files are now named to include the image name
115 and tuning architecture through the :term:`SDK_NAME`
116 variable.
117
118- Images and related files are now installed into a directory that is
119 specific to the machine, instead of a parent directory containing
120 output files for multiple machines. The
121 :term:`DEPLOY_DIR_IMAGE` variable continues
122 to point to the directory containing images for the current
123 :term:`MACHINE` and should be used anywhere there is a
124 need to refer to this directory. The ``runqemu`` script now uses this
125 variable to find images and kernel binaries and will use BitBake to
126 determine the directory. Alternatively, you can set the
127 ``DEPLOY_DIR_IMAGE`` variable in the external environment.
128
129- When buildhistory is enabled, its output is now written under the
130 :term:`Build Directory` rather than
131 :term:`TMPDIR`. Doing so makes it easier to delete
132 ``TMPDIR`` and preserve the build history. Additionally, data for
133 produced SDKs is now split by :term:`IMAGE_NAME`.
134
135- The ``pkgdata`` directory produced as part of the packaging process
136 has been collapsed into a single machine-specific directory. This
137 directory is located under ``sysroots`` and uses a machine-specific
138 name (i.e. ``tmp/sysroots/machine/pkgdata``).
139
140.. _migration-1.5-shortened-git-srcrev-values:
141
142Shortened Git ``SRCREV`` Values
143-------------------------------
144
145BitBake will now shorten revisions from Git repositories from the normal
14640 characters down to 10 characters within :term:`SRCPV`
147for improved usability in path and file names. This change should be
148safe within contexts where these revisions are used because the chances
149of spatially close collisions is very low. Distant collisions are not a
150major issue in the way the values are used.
151
152.. _migration-1.5-image-features:
153
154``IMAGE_FEATURES``
155------------------
156
157The following changes have been made that relate to
158:term:`IMAGE_FEATURES`:
159
160- The value of ``IMAGE_FEATURES`` is now validated to ensure invalid
161 feature items are not added. Some users mistakenly add package names
162 to this variable instead of using
163 :term:`IMAGE_INSTALL` in order to have the
164 package added to the image, which does not work. This change is
165 intended to catch those kinds of situations. Valid ``IMAGE_FEATURES``
166 are drawn from ``PACKAGE_GROUP`` definitions,
167 :term:`COMPLEMENTARY_GLOB` and a new
168 "validitems" varflag on ``IMAGE_FEATURES``. The "validitems" varflag
169 change allows additional features to be added if they are not
170 provided using the previous two mechanisms.
171
172- The previously deprecated "apps-console-core" ``IMAGE_FEATURES`` item
173 is no longer supported. Add "splash" to ``IMAGE_FEATURES`` if you
174 wish to have the splash screen enabled, since this is all that
175 apps-console-core was doing.
176
177.. _migration-1.5-run:
178
179``/run``
180--------
181
182The ``/run`` directory from the Filesystem Hierarchy Standard 3.0 has
183been introduced. You can find some of the implications for this change
184:oe_git:`here </openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873>`.
185The change also means that recipes that install files to ``/var/run``
186must be changed. You can find a guide on how to make these changes
187`here <https://www.mail-archive.com/openembedded-devel@lists.openembedded.org/msg31649.html>`__.
188
189.. _migration-1.5-removal-of-package-manager-database-within-image-recipes:
190
191Removal of Package Manager Database Within Image Recipes
192--------------------------------------------------------
193
194The image ``core-image-minimal`` no longer adds
195``remove_packaging_data_files`` to
196:term:`ROOTFS_POSTPROCESS_COMMAND`.
197This addition is now handled automatically when "package-management" is
198not in :term:`IMAGE_FEATURES`. If you have custom
199image recipes that make this addition, you should remove the lines, as
200they are not needed and might interfere with correct operation of
201postinstall scripts.
202
203.. _migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time:
204
205Images Now Rebuild Only on Changes Instead of Every Time
206--------------------------------------------------------
207
208The :ref:`ref-tasks-rootfs` and other related image
209construction tasks are no longer marked as "nostamp". Consequently, they
210will only be re-executed when their inputs have changed. Previous
211versions of the OpenEmbedded build system always rebuilt the image when
212requested rather when necessary.
213
214.. _migration-1.5-task-recipes:
215
216Task Recipes
217------------
218
219The previously deprecated ``task.bbclass`` has now been dropped. For
220recipes that previously inherited from this class, you should rename
221them from ``task-*`` to ``packagegroup-*`` and inherit packagegroup
222instead.
223
224For more information, see the
225":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section.
226
227.. _migration-1.5-busybox:
228
229BusyBox
230-------
231
232By default, we now split BusyBox into two binaries: one that is suid
233root for those components that need it, and another for the rest of the
234components. Splitting BusyBox allows for optimization that eliminates
235the ``tinylogin`` recipe as recommended by upstream. You can disable
236this split by setting
237:term:`BUSYBOX_SPLIT_SUID` to "0".
238
239.. _migration-1.5-automated-image-testing:
240
241Automated Image Testing
242-----------------------
243
244A new automated image testing framework has been added through the
245:ref:`testimage.bbclass <ref-classes-testimage*>` class. This
246framework replaces the older ``imagetest-qemu`` framework.
247
248You can learn more about performing automated image tests in the
249":ref:`dev-manual/common-tasks:performing automated runtime testing`"
250section in the Yocto Project Development Tasks Manual.
251
252.. _migration-1.5-build-history:
253
254Build History
255-------------
256
257Following are changes to Build History:
258
259- Installed package sizes: ``installed-package-sizes.txt`` for an image
260 now records the size of the files installed by each package instead
261 of the size of each compressed package archive file.
262
263- The dependency graphs (``depends*.dot``) now use the actual package
264 names instead of replacing dashes, dots and plus signs with
265 underscores.
266
267- The ``buildhistory-diff`` and ``buildhistory-collect-srcrevs``
268 utilities have improved command-line handling. Use the ``--help``
269 option for each utility for more information on the new syntax.
270
271For more information on Build History, see the
272":ref:`dev-manual/common-tasks:maintaining build output quality`"
273section in the Yocto Project Development Tasks Manual.
274
275.. _migration-1.5-udev:
276
277``udev``
278--------
279
280Following are changes to ``udev``:
281
282- ``udev`` no longer brings in ``udev-extraconf`` automatically through
283 :term:`RRECOMMENDS`, since this was originally
284 intended to be optional. If you need the extra rules, then add
285 ``udev-extraconf`` to your image.
286
287- ``udev`` no longer brings in ``pciutils-ids`` or ``usbutils-ids``
288 through ``RRECOMMENDS``. These are not needed by ``udev`` itself and
289 removing them saves around 350KB.
290
291.. _migration-1.5-removed-renamed-recipes:
292
293Removed and Renamed Recipes
294---------------------------
295
296- The ``linux-yocto`` 3.2 kernel has been removed.
297
298- ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``.
299
300- ``tinylogin`` has been removed. It has been replaced by a suid
301 portion of Busybox. See the ":ref:`migration-1.5-busybox`"
302 section for more information.
303
304- ``external-python-tarball`` has been renamed to
305 ``buildtools-tarball``.
306
307- ``web-webkit`` has been removed. It has been functionally replaced by
308 ``midori``.
309
310- ``imake`` has been removed. It is no longer needed by any other
311 recipe.
312
313- ``transfig-native`` has been removed. It is no longer needed by any
314 other recipe.
315
316- ``anjuta-remote-run`` has been removed. Anjuta IDE integration has
317 not been officially supported for several releases.
318
319.. _migration-1.5-other-changes:
320
321Other Changes
322-------------
323
324Following is a list of short entries describing other changes:
325
326- ``run-postinsts``: Make this generic.
327
328- ``base-files``: Remove the unnecessary ``media/``\ xxx directories.
329
330- ``alsa-state``: Provide an empty ``asound.conf`` by default.
331
332- ``classes/image``: Ensure
333 :term:`BAD_RECOMMENDATIONS` supports
334 pre-renamed package names.
335
336- ``classes/rootfs_rpm``: Implement ``BAD_RECOMMENDATIONS`` for RPM.
337
338- ``systemd``: Remove ``systemd_unitdir`` if ``systemd`` is not in
339 :term:`DISTRO_FEATURES`.
340
341- ``systemd``: Remove ``init.d`` dir if ``systemd`` unit file is
342 present and ``sysvinit`` is not a distro feature.
343
344- ``libpam``: Deny all services for the ``OTHER`` entries.
345
346- ``image.bbclass``: Move ``runtime_mapping_rename`` to avoid conflict
347 with ``multilib``. See :yocto_bugs:`YOCTO #4993 </show_bug.cgi?id=4993>`
348 in Bugzilla for more information.
349
350- ``linux-dtb``: Use kernel build system to generate the ``dtb`` files.
351
352- ``kern-tools``: Switch from guilt to new ``kgit-s2q`` tool.
353
diff --git a/documentation/ref-manual/migration-1.6.rst b/documentation/ref-manual/migration-1.6.rst
deleted file mode 100644
index 5a18d63103..0000000000
--- a/documentation/ref-manual/migration-1.6.rst
+++ /dev/null
@@ -1,414 +0,0 @@
1Moving to the Yocto Project 1.6 Release (daisy)
2===============================================
3
4This section provides migration information for moving to the Yocto
5Project 1.6 Release (codename "daisy") 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/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::
57
58 SRC_URI = "git://server.name/repository;branch=branchname"
59
60If you do not specify a branch, BitBake looks in the default "master" branch.
61
62Alternatively, if you need to bypass this check (e.g. if you are
63fetching a revision corresponding to a tag that is not on any branch),
64you can add ";nobranch=1" to the end of the URL within ``SRC_URI``.
65
66.. _migration-1.6-bitbake-deps:
67
68Python Definition substitutions
69~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70
71BitBake had some previously deprecated Python definitions within its
72``bb`` module removed. You should use their sub-module counterparts
73instead:
74
75- ``bb.MalformedUrl``: Use ``bb.fetch.MalformedUrl``.
76
77- ``bb.encodeurl``: Use ``bb.fetch.encodeurl``.
78
79- ``bb.decodeurl``: Use ``bb.fetch.decodeurl``
80
81- ``bb.mkdirhier``: Use ``bb.utils.mkdirhier``.
82
83- ``bb.movefile``: Use ``bb.utils.movefile``.
84
85- ``bb.copyfile``: Use ``bb.utils.copyfile``.
86
87- ``bb.which``: Use ``bb.utils.which``.
88
89- ``bb.vercmp_string``: Use ``bb.utils.vercmp_string``.
90
91- ``bb.vercmp``: Use ``bb.utils.vercmp``.
92
93.. _migration-1.6-bitbake-fetcher:
94
95SVK Fetcher
96~~~~~~~~~~~
97
98The SVK fetcher has been removed from BitBake.
99
100.. _migration-1.6-bitbake-console-output:
101
102Console Output Error Redirection
103~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104
105The BitBake console UI will now output errors to ``stderr`` instead of
106``stdout``. Consequently, if you are piping or redirecting the output of
107``bitbake`` to somewhere else, and you wish to retain the errors, you
108will need to add ``2>&1`` (or something similar) to the end of your
109``bitbake`` command line.
110
111.. _migration-1.6-task-taskname-overrides:
112
113``task-``\ taskname Overrides
114~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115
116``task-``\ taskname overrides have been adjusted so that tasks whose
117names contain underscores have the underscores replaced by hyphens for
118the override so that they now function properly. For example, the task
119override for :ref:`ref-tasks-populate_sdk` is
120``task-populate-sdk``.
121
122.. _migration-1.6-variable-changes:
123
124Changes to Variables
125--------------------
126
127The following variables have changed. For information on the
128OpenEmbedded build system variables, see the ":doc:`/ref-manual/variables`" Chapter.
129
130.. _migration-1.6-variable-changes-TMPDIR:
131
132``TMPDIR``
133~~~~~~~~~~
134
135:term:`TMPDIR` can no longer be on an NFS mount. NFS does
136not offer full POSIX locking and inode consistency and can cause
137unexpected issues if used to store ``TMPDIR``.
138
139The check for this occurs on startup. If ``TMPDIR`` is detected on an
140NFS mount, an error occurs.
141
142.. _migration-1.6-variable-changes-PRINC:
143
144``PRINC``
145~~~~~~~~~
146
147The ``PRINC`` variable has been deprecated and triggers a warning if
148detected during a build. For :term:`PR` increments on changes,
149use the PR service instead. You can find out more about this service in
150the ":ref:`dev-manual/common-tasks:working with a pr service`"
151section in the Yocto Project Development Tasks Manual.
152
153.. _migration-1.6-variable-changes-IMAGE_TYPES:
154
155``IMAGE_TYPES``
156~~~~~~~~~~~~~~~
157
158The "sum.jffs2" option for :term:`IMAGE_TYPES` has
159been replaced by the "jffs2.sum" option, which fits the processing
160order.
161
162.. _migration-1.6-variable-changes-COPY_LIC_MANIFEST:
163
164``COPY_LIC_MANIFEST``
165~~~~~~~~~~~~~~~~~~~~~
166
167The :term:`COPY_LIC_MANIFEST` variable must now
168be set to "1" rather than any value in order to enable it.
169
170.. _migration-1.6-variable-changes-COPY_LIC_DIRS:
171
172``COPY_LIC_DIRS``
173~~~~~~~~~~~~~~~~~
174
175The :term:`COPY_LIC_DIRS` variable must now be set
176to "1" rather than any value in order to enable it.
177
178.. _migration-1.6-variable-changes-PACKAGE_GROUP:
179
180``PACKAGE_GROUP``
181~~~~~~~~~~~~~~~~~
182
183The ``PACKAGE_GROUP`` variable has been renamed to
184:term:`FEATURE_PACKAGES` to more accurately
185reflect its purpose. You can still use ``PACKAGE_GROUP`` but the
186OpenEmbedded build system produces a warning message when it encounters
187the variable.
188
189.. _migration-1.6-variable-changes-variable-entry-behavior:
190
191Preprocess and Post Process Command Variable Behavior
192~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
193
194The following variables now expect a semicolon separated list of
195functions to call and not arbitrary shell commands:
196
197 - :term:`ROOTFS_PREPROCESS_COMMAND`
198 - :term:`ROOTFS_POSTPROCESS_COMMAND`
199 - :term:`SDK_POSTPROCESS_COMMAND`
200 - :term:`POPULATE_SDK_POST_TARGET_COMMAND`
201 - :term:`POPULATE_SDK_POST_HOST_COMMAND`
202 - :term:`IMAGE_POSTPROCESS_COMMAND`
203 - :term:`IMAGE_PREPROCESS_COMMAND`
204 - :term:`ROOTFS_POSTUNINSTALL_COMMAND`
205 - :term:`ROOTFS_POSTINSTALL_COMMAND`
206
207For
208migration purposes, you can simply wrap shell commands in a shell
209function and then call the function. Here is an example::
210
211 my_postprocess_function() {
212 echo "hello" > ${IMAGE_ROOTFS}/hello.txt
213 }
214 ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "
215
216.. _migration-1.6-package-test-ptest:
217
218Package Test (ptest)
219--------------------
220
221Package Tests (ptest) are built but not installed by default. For
222information on using Package Tests, see the
223":ref:`dev-manual/common-tasks:testing packages with ptest`"
224section in the Yocto Project Development Tasks Manual. For information on the
225``ptest`` class, see the ":ref:`ptest.bbclass <ref-classes-ptest>`"
226section.
227
228.. _migration-1.6-build-changes:
229
230Build Changes
231-------------
232
233Separate build and source directories have been enabled by default for
234selected recipes where it is known to work (a whitelist) and for all
235recipes that inherit the :ref:`cmake <ref-classes-cmake>` class. In
236future releases the :ref:`autotools <ref-classes-autotools>` class
237will enable a separate build directory by default as well. Recipes
238building Autotools-based software that fails to build with a separate
239build directory should be changed to inherit from the
240:ref:`autotools-brokensep <ref-classes-autotools>` class instead of
241the ``autotools`` or ``autotools_stage``\ classes.
242
243.. _migration-1.6-building-qemu-native:
244
245``qemu-native``
246---------------
247
248``qemu-native`` now builds without SDL-based graphical output support by
249default. The following additional lines are needed in your
250``local.conf`` to enable it::
251
252 PACKAGECONFIG_pn-qemu-native = "sdl"
253 ASSUME_PROVIDED += "libsdl-native"
254
255.. note::
256
257 The default ``local.conf`` contains these statements. Consequently, if you
258 are building a headless system and using a default ``local.conf``
259 file, you will need comment these two lines out.
260
261.. _migration-1.6-core-image-basic:
262
263``core-image-basic``
264--------------------
265
266``core-image-basic`` has been renamed to ``core-image-full-cmdline``.
267
268In addition to ``core-image-basic`` being renamed,
269``packagegroup-core-basic`` has been renamed to
270``packagegroup-core-full-cmdline`` to match.
271
272.. _migration-1.6-licensing:
273
274Licensing
275---------
276
277The top-level ``LICENSE`` file has been changed to better describe the
278license of the various components of :term:`OpenEmbedded-Core (OE-Core)`. However,
279the licensing itself remains unchanged.
280
281Normally, this change would not cause any side-effects. However, some
282recipes point to this file within
283:term:`LIC_FILES_CHKSUM` (as
284``${COREBASE}/LICENSE``) and thus the accompanying checksum must be
285changed from 3f40d7994397109285ec7b81fdeb3b58 to
2864d92cd373abda3937c2bc47fbc49d690. A better alternative is to have
287``LIC_FILES_CHKSUM`` point to a file describing the license that is
288distributed with the source that the recipe is building, if possible,
289rather than pointing to ``${COREBASE}/LICENSE``.
290
291.. _migration-1.6-cflags-options:
292
293``CFLAGS`` Options
294------------------
295
296The "-fpermissive" option has been removed from the default
297:term:`CFLAGS` value. You need to take action on
298individual recipes that fail when building with this option. You need to
299either patch the recipes to fix the issues reported by the compiler, or
300you need to add "-fpermissive" to ``CFLAGS`` in the recipes.
301
302.. _migration-1.6-custom-images:
303
304Custom Image Output Types
305-------------------------
306
307Custom image output types, as selected using
308:term:`IMAGE_FSTYPES`, must declare their
309dependencies on other image types (if any) using a new
310:term:`IMAGE_TYPEDEP` variable.
311
312.. _migration-1.6-do-package-write-task:
313
314Tasks
315-----
316
317The ``do_package_write`` task has been removed. The task is no longer
318needed.
319
320.. _migration-1.6-update-alternatives-provider:
321
322``update-alternative`` Provider
323-------------------------------
324
325The default ``update-alternatives`` provider has been changed from
326``opkg`` to ``opkg-utils``. This change resolves some troublesome
327circular dependencies. The runtime package has also been renamed from
328``update-alternatives-cworth`` to ``update-alternatives-opkg``.
329
330.. _migration-1.6-virtclass-overrides:
331
332``virtclass`` Overrides
333-----------------------
334
335The ``virtclass`` overrides are now deprecated. Use the equivalent class
336overrides instead (e.g. ``virtclass-native`` becomes ``class-native``.)
337
338.. _migration-1.6-removed-renamed-recipes:
339
340Removed and Renamed Recipes
341---------------------------
342
343The following recipes have been removed:
344
345- ``packagegroup-toolset-native`` - This recipe is largely unused.
346
347- ``linux-yocto-3.8`` - Support for the Linux yocto 3.8 kernel has been
348 dropped. Support for the 3.10 and 3.14 kernels have been added with
349 the ``linux-yocto-3.10`` and ``linux-yocto-3.14`` recipes.
350
351- ``ocf-linux`` - This recipe has been functionally replaced using
352 ``cryptodev-linux``.
353
354- ``genext2fs`` - ``genext2fs`` is no longer used by the build system
355 and is unmaintained upstream.
356
357- ``js`` - This provided an ancient version of Mozilla's javascript
358 engine that is no longer needed.
359
360- ``zaurusd`` - The recipe has been moved to the ``meta-handheld``
361 layer.
362
363- ``eglibc 2.17`` - Replaced by the ``eglibc 2.19`` recipe.
364
365- ``gcc 4.7.2`` - Replaced by the now stable ``gcc 4.8.2``.
366
367- ``external-sourcery-toolchain`` - this recipe is now maintained in
368 the ``meta-sourcery`` layer.
369
370- ``linux-libc-headers-yocto 3.4+git`` - Now using version 3.10 of the
371 ``linux-libc-headers`` by default.
372
373- ``meta-toolchain-gmae`` - This recipe is obsolete.
374
375- ``packagegroup-core-sdk-gmae`` - This recipe is obsolete.
376
377- ``packagegroup-core-standalone-gmae-sdk-target`` - This recipe is
378 obsolete.
379
380.. _migration-1.6-removed-classes:
381
382Removed Classes
383---------------
384
385The following classes have become obsolete and have been removed:
386
387- ``module_strip``
388
389- ``pkg_metainfo``
390
391- ``pkg_distribute``
392
393- ``image-empty``
394
395.. _migration-1.6-reference-bsps:
396
397Reference Board Support Packages (BSPs)
398---------------------------------------
399
400The following reference BSPs changes occurred:
401
402- The BeagleBoard (``beagleboard``) ARM reference hardware has been
403 replaced by the BeagleBone (``beaglebone``) hardware.
404
405- The RouterStation Pro (``routerstationpro``) MIPS reference hardware
406 has been replaced by the EdgeRouter Lite (``edgerouter``) hardware.
407
408The previous reference BSPs for the ``beagleboard`` and
409``routerstationpro`` machines are still available in a new
410``meta-yocto-bsp-old`` layer in the
411:yocto_git:`Source Repositories <>` at
412:yocto_git:`/meta-yocto-bsp-old/`.
413
414
diff --git a/documentation/ref-manual/migration-1.7.rst b/documentation/ref-manual/migration-1.7.rst
deleted file mode 100644
index 46bf126583..0000000000
--- a/documentation/ref-manual/migration-1.7.rst
+++ /dev/null
@@ -1,221 +0,0 @@
1Moving to the Yocto Project 1.7 Release (dizzy)
2===============================================
3
4This section provides migration information for moving to the Yocto
5Project 1.7 Release (codename "dizzy") 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 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 PACKAGECONFIG_append_pn-qemu-native = " sdl"
21 PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
22
23.. _migration-1.7-minimum-git-version:
24
25Minimum Git version
26-------------------
27
28The minimum :ref:`overview-manual/development-environment:git`
29version required on the
30build host is now 1.7.8 because the ``--list`` option is now required by
31BitBake's Git fetcher. As always, if your host distribution does not
32provide a version of Git that meets this requirement, you can use the
33``buildtools-tarball`` that does. See the
34":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`"
35section for more information.
36
37.. _migration-1.7-autotools-class-changes:
38
39Autotools Class Changes
40-----------------------
41
42The following :ref:`autotools <ref-classes-autotools>` class changes
43occurred:
44
45- *A separate build directory is now used by default:* The
46 ``autotools`` class has been changed to use a directory for building
47 (:term:`B`), which is separate from the source directory
48 (:term:`S`). This is commonly referred to as ``B != S``, or
49 an out-of-tree build.
50
51 If the software being built is already capable of building in a
52 directory separate from the source, you do not need to do anything.
53 However, if the software is not capable of being built in this
54 manner, you will need to either patch the software so that it can
55 build separately, or you will need to change the recipe to inherit
56 the :ref:`autotools-brokensep <ref-classes-autotools>` class
57 instead of the ``autotools`` or ``autotools_stage`` classes.
58
59- The ``--foreign`` option is no longer passed to ``automake`` when
60 running ``autoconf``: This option tells ``automake`` that a
61 particular software package does not follow the GNU standards and
62 therefore should not be expected to distribute certain files such as
63 ``ChangeLog``, ``AUTHORS``, and so forth. Because the majority of
64 upstream software packages already tell ``automake`` to enable
65 foreign mode themselves, the option is mostly superfluous. However,
66 some recipes will need patches for this change. You can easily make
67 the change by patching ``configure.ac`` so that it passes "foreign"
68 to ``AM_INIT_AUTOMAKE()``. See :oe_git:`this
69 commit </openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2>`
70 for an example showing how to make the patch.
71
72.. _migration-1.7-binary-configuration-scripts-disabled:
73
74Binary Configuration Scripts Disabled
75-------------------------------------
76
77Some of the core recipes that package binary configuration scripts now
78disable the scripts due to the scripts previously requiring error-prone
79path substitution. Software that links against these libraries using
80these scripts should use the much more robust ``pkg-config`` instead.
81The list of recipes changed in this version (and their configuration
82scripts) is as follows::
83
84 directfb (directfb-config)
85 freetype (freetype-config)
86 gpgme (gpgme-config)
87 libassuan (libassuan-config)
88 libcroco (croco-6.0-config)
89 libgcrypt (libgcrypt-config)
90 libgpg-error (gpg-error-config)
91 libksba (ksba-config)
92 libpcap (pcap-config)
93 libpcre (pcre-config)
94 libpng (libpng-config, libpng16-config)
95 libsdl (sdl-config)
96 libusb-compat (libusb-config)
97 libxml2 (xml2-config)
98 libxslt (xslt-config)
99 ncurses (ncurses-config)
100 neon (neon-config)
101 npth (npth-config)
102 pth (pth-config)
103 taglib (taglib-config)
104
105Additionally, support for ``pkg-config`` has been added to some recipes in the
106previous list in the rare cases where the upstream software package does
107not already provide it.
108
109.. _migration-1.7-glibc-replaces-eglibc:
110
111``eglibc 2.19`` Replaced with ``glibc 2.20``
112--------------------------------------------
113
114Because ``eglibc`` and ``glibc`` were already fairly close, this
115replacement should not require any significant changes to other software
116that links to ``eglibc``. However, there were a number of minor changes
117in ``glibc 2.20`` upstream that could require patching some software
118(e.g. the removal of the ``_BSD_SOURCE`` feature test macro).
119
120``glibc 2.20`` requires version 2.6.32 or greater of the Linux kernel.
121Thus, older kernels will no longer be usable in conjunction with it.
122
123For full details on the changes in ``glibc 2.20``, see the upstream
124release notes
125`here <https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html>`__.
126
127.. _migration-1.7-kernel-module-autoloading:
128
129Kernel Module Autoloading
130-------------------------
131
132The :term:`module_autoload_* <module_autoload>` variable is now
133deprecated and a new
134:term:`KERNEL_MODULE_AUTOLOAD` variable
135should be used instead. Also, :term:`module_conf_* <module_conf>`
136must now be used in conjunction with a new
137:term:`KERNEL_MODULE_PROBECONF` variable.
138The new variables no longer require you to specify the module name as
139part of the variable name. This change not only simplifies usage but
140also allows the values of these variables to be appropriately
141incorporated into task signatures and thus trigger the appropriate tasks
142to re-execute when changed. You should replace any references to
143``module_autoload_*`` with ``KERNEL_MODULE_AUTOLOAD``, and add any
144modules for which ``module_conf_*`` is specified to
145``KERNEL_MODULE_PROBECONF``.
146
147.. _migration-1.7-qa-check-changes:
148
149QA Check Changes
150----------------
151
152The following changes have occurred to the QA check process:
153
154- Additional QA checks ``file-rdeps`` and ``build-deps`` have been
155 added in order to verify that file dependencies are satisfied (e.g.
156 package contains a script requiring ``/bin/bash``) and build-time
157 dependencies are declared, respectively. For more information, please
158 see the ":doc:`/ref-manual/qa-checks`" chapter.
159
160- Package QA checks are now performed during a new
161 :ref:`ref-tasks-package_qa` task rather than being
162 part of the :ref:`ref-tasks-package` task. This allows
163 more parallel execution. This change is unlikely to be an issue
164 except for highly customized recipes that disable packaging tasks
165 themselves by marking them as ``noexec``. For those packages, you
166 will need to disable the ``do_package_qa`` task as well.
167
168- Files being overwritten during the
169 :ref:`ref-tasks-populate_sysroot` task now
170 trigger an error instead of a warning. Recipes should not be
171 overwriting files written to the sysroot by other recipes. If you
172 have these types of recipes, you need to alter them so that they do
173 not overwrite these files.
174
175 You might now receive this error after changes in configuration or
176 metadata resulting in orphaned files being left in the sysroot. If
177 you do receive this error, the way to resolve the issue is to delete
178 your :term:`TMPDIR` or to move it out of the way and
179 then re-start the build. Anything that has been fully built up to
180 that point and does not need rebuilding will be restored from the
181 shared state cache and the rest of the build will be able to proceed
182 as normal.
183
184.. _migration-1.7-removed-recipes:
185
186Removed Recipes
187---------------
188
189The following recipes have been removed:
190
191- ``x-load``: This recipe has been superseded by U-Boot SPL for all
192 Cortex-based TI SoCs. For legacy boards, the ``meta-ti`` layer, which
193 contains a maintained recipe, should be used instead.
194
195- ``ubootchart``: This recipe is obsolete. A ``bootchart2`` recipe has
196 been added to functionally replace it.
197
198- ``linux-yocto 3.4``: Support for the linux-yocto 3.4 kernel has been
199 dropped. Support for the 3.10 and 3.14 kernels remains, while support
200 for version 3.17 has been added.
201
202- ``eglibc`` has been removed in favor of ``glibc``. See the
203 ":ref:`migration-1.7-glibc-replaces-eglibc`" section for more information.
204
205.. _migration-1.7-miscellaneous-changes:
206
207Miscellaneous Changes
208---------------------
209
210The following miscellaneous change occurred:
211
212- The build history feature now writes ``build-id.txt`` instead of
213 ``build-id``. Additionally, ``build-id.txt`` now contains the full
214 build header as printed by BitBake upon starting the build. You
215 should manually remove old "build-id" files from your existing build
216 history repositories to avoid confusion. For information on the build
217 history feature, see the
218 ":ref:`dev-manual/common-tasks:maintaining build output quality`"
219 section in the Yocto Project Development Tasks Manual.
220
221
diff --git a/documentation/ref-manual/migration-1.8.rst b/documentation/ref-manual/migration-1.8.rst
deleted file mode 100644
index 68d5dcf859..0000000000
--- a/documentation/ref-manual/migration-1.8.rst
+++ /dev/null
@@ -1,183 +0,0 @@
1Moving to the Yocto Project 1.8 Release (fido)
2==============================================
3
4This section provides migration information for moving to the Yocto
5Project 1.8 Release (codename "fido") 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:oe_git:`commit </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
deleted file mode 100644
index 8319b0ee36..0000000000
--- a/documentation/ref-manual/migration-2.0.rst
+++ /dev/null
@@ -1,278 +0,0 @@
1Moving to the Yocto Project 2.0 Release (jethro)
2================================================
3
4This section provides migration information for moving to the Yocto
5Project 2.0 Release (codename "jethro") 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 GCCVERSION = "4.9%"
31
32.. _migration-2.0-Gstreamer-0.10-removed:
33
34Gstreamer 0.10 Removed
35----------------------
36
37Gstreamer 0.10 has been removed in favor of Gstreamer 1.x. As part of
38the change, recipes for Gstreamer 0.10 and related software are now
39located in ``meta-multimedia``. This change results in Qt4 having Phonon
40and Gstreamer support in QtWebkit disabled by default.
41
42.. _migration-2.0-removed-recipes:
43
44Removed Recipes
45---------------
46
47The following recipes have been moved or removed:
48
49- ``bluez4``: The recipe is obsolete and has been moved due to
50 ``bluez5`` becoming fully integrated. The ``bluez4`` recipe now
51 resides in ``meta-oe``.
52
53- ``gamin``: The recipe is obsolete and has been removed.
54
55- ``gnome-icon-theme``: The recipe's functionally has been replaced by
56 ``adwaita-icon-theme``.
57
58- Gstreamer 0.10 Recipes: Recipes for Gstreamer 0.10 have been removed
59 in favor of the recipes for Gstreamer 1.x.
60
61- ``insserv``: The recipe is obsolete and has been removed.
62
63- ``libunique``: The recipe is no longer used and has been moved to
64 ``meta-oe``.
65
66- ``midori``: The recipe's functionally has been replaced by
67 ``epiphany``.
68
69- ``python-gst``: The recipe is obsolete and has been removed since it
70 only contains bindings for Gstreamer 0.10.
71
72- ``qt-mobility``: The recipe is obsolete and has been removed since it
73 requires ``Gstreamer 0.10``, which has been replaced.
74
75- ``subversion``: All 1.6.x versions of this recipe have been removed.
76
77- ``webkit-gtk``: The older 1.8.3 version of this recipe has been
78 removed in favor of ``webkitgtk``.
79
80.. _migration-2.0-bitbake-datastore-improvements:
81
82BitBake datastore improvements
83------------------------------
84
85The method by which BitBake's datastore handles overrides has changed.
86Overrides are now applied dynamically and ``bb.data.update_data()`` is
87now a no-op. Thus, ``bb.data.update_data()`` is no longer required in
88order to apply the correct overrides. In practice, this change is
89unlikely to require any changes to Metadata. However, these minor
90changes in behavior exist:
91
92- All potential overrides are now visible in the variable history as
93 seen when you run the following::
94
95 $ bitbake -e
96
97- ``d.delVar('VARNAME')`` and
98 ``d.setVar('VARNAME', None)`` result in the variable and all
99 of its overrides being cleared out. Before the change, only the
100 non-overridden values were cleared.
101
102.. _migration-2.0-shell-message-function-changes:
103
104Shell Message Function Changes
105------------------------------
106
107The shell versions of the BitBake message functions (i.e. ``bbdebug``,
108``bbnote``, ``bbwarn``, ``bbplain``, ``bberror``, and ``bbfatal``) are
109now connected through to their BitBake equivalents ``bb.debug()``,
110``bb.note()``, ``bb.warn()``, ``bb.plain()``, ``bb.error()``, and
111``bb.fatal()``, respectively. Thus, those message functions that you
112would expect to be printed by the BitBake UI are now actually printed.
113In practice, this change means two things:
114
115- If you now see messages on the console that you did not previously
116 see as a result of this change, you might need to clean up the calls
117 to ``bbwarn``, ``bberror``, and so forth. Or, you might want to
118 simply remove the calls.
119
120- The ``bbfatal`` message function now suppresses the full error log in
121 the UI, which means any calls to ``bbfatal`` where you still wish to
122 see the full error log should be replaced by ``die`` or
123 ``bbfatal_log``.
124
125.. _migration-2.0-extra-development-debug-package-cleanup:
126
127Extra Development/Debug Package Cleanup
128---------------------------------------
129
130The following recipes have had extra ``dev/dbg`` packages removed:
131
132- ``acl``
133
134- ``apmd``
135
136- ``aspell``
137
138- ``attr``
139
140- ``augeas``
141
142- ``bzip2``
143
144- ``cogl``
145
146- ``curl``
147
148- ``elfutils``
149
150- ``gcc-target``
151
152- ``libgcc``
153
154- ``libtool``
155
156- ``libxmu``
157
158- ``opkg``
159
160- ``pciutils``
161
162- ``rpm``
163
164- ``sysfsutils``
165
166- ``tiff``
167
168- ``xz``
169
170All of the above recipes now conform to the standard packaging scheme
171where a single ``-dev``, ``-dbg``, and ``-staticdev`` package exists per
172recipe.
173
174.. _migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core:
175
176Recipe Maintenance Tracking Data Moved to OE-Core
177-------------------------------------------------
178
179Maintenance tracking data for recipes that was previously part of
180``meta-yocto`` has been moved to :term:`OpenEmbedded-Core (OE-Core)`. The change
181includes ``package_regex.inc`` and ``distro_alias.inc``, which are
182typically enabled when using the ``distrodata`` class. Additionally, the
183contents of ``upstream_tracking.inc`` has now been split out to the
184relevant recipes.
185
186.. _migration-2.0-automatic-stale-sysroot-file-cleanup:
187
188Automatic Stale Sysroot File Cleanup
189------------------------------------
190
191Stale files from recipes that no longer exist in the current
192configuration are now automatically removed from sysroot as well as
193removed from any other place managed by shared state. This automatic
194cleanup means that the build system now properly handles situations such
195as renaming the build system side of recipes, removal of layers from
196``bblayers.conf``, and :term:`DISTRO_FEATURES`
197changes.
198
199Additionally, work directories for old versions of recipes are now
200pruned. If you wish to disable pruning old work directories, you can set
201the following variable in your configuration::
202
203 SSTATE_PRUNE_OBSOLETEWORKDIR = "0"
204
205.. _migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source:
206
207``linux-yocto`` Kernel Metadata Repository Now Split from Source
208----------------------------------------------------------------
209
210The ``linux-yocto`` tree has up to now been a combined set of kernel
211changes and configuration (meta) data carried in a single tree. While
212this format is effective at keeping kernel configuration and source
213modifications synchronized, it is not always obvious to developers how
214to manipulate the Metadata as compared to the source.
215
216Metadata processing has now been removed from the
217:ref:`kernel-yocto <ref-classes-kernel-yocto>` class and the external
218Metadata repository ``yocto-kernel-cache``, which has always been used
219to seed the ``linux-yocto`` "meta" branch. This separate ``linux-yocto``
220cache repository is now the primary location for this data. Due to this
221change, ``linux-yocto`` is no longer able to process combined trees.
222Thus, if you need to have your own combined kernel repository, you must
223do the split there as well and update your recipes accordingly. See the
224``meta/recipes-kernel/linux/linux-yocto_4.1.bb`` recipe for an example.
225
226.. _migration-2.0-additional-qa-checks:
227
228Additional QA checks
229--------------------
230
231The following QA checks have been added:
232
233- Added a "host-user-contaminated" check for ownership issues for
234 packaged files outside of ``/home``. The check looks for files that
235 are incorrectly owned by the user that ran BitBake instead of owned
236 by a valid user in the target system.
237
238- Added an "invalid-chars" check for invalid (non-UTF8) characters in
239 recipe metadata variable values (i.e.
240 :term:`DESCRIPTION`,
241 :term:`SUMMARY`, :term:`LICENSE`, and
242 :term:`SECTION`). Some package managers do not support
243 these characters.
244
245- Added an "invalid-packageconfig" check for any options specified in
246 :term:`PACKAGECONFIG` that do not match any
247 ``PACKAGECONFIG`` option defined for the recipe.
248
249.. _migration-2.0-miscellaneous:
250
251Miscellaneous Changes
252---------------------
253
254These additional changes exist:
255
256- ``gtk-update-icon-cache`` has been renamed to ``gtk-icon-utils``.
257
258- The ``tools-profile`` :term:`IMAGE_FEATURES`
259 item as well as its corresponding packagegroup and
260 ``packagegroup-core-tools-profile`` no longer bring in ``oprofile``.
261 Bringing in ``oprofile`` was originally added to aid compilation on
262 resource-constrained targets. However, this aid has not been widely
263 used and is not likely to be used going forward due to the more
264 powerful target platforms and the existence of better
265 cross-compilation tools.
266
267- The :term:`IMAGE_FSTYPES` variable's default
268 value now specifies ``ext4`` instead of ``ext3``.
269
270- All support for the ``PRINC`` variable has been removed.
271
272- The ``packagegroup-core-full-cmdline`` packagegroup no longer brings
273 in ``lighttpd`` due to the fact that bringing in ``lighttpd`` is not
274 really in line with the packagegroup's purpose, which is to add full
275 versions of command-line tools that by default are provided by
276 ``busybox``.
277
278
diff --git a/documentation/ref-manual/migration-2.1.rst b/documentation/ref-manual/migration-2.1.rst
deleted file mode 100644
index 32d193f0ff..0000000000
--- a/documentation/ref-manual/migration-2.1.rst
+++ /dev/null
@@ -1,432 +0,0 @@
1Moving to the Yocto Project 2.1 Release (krogoth)
2=================================================
3
4This section provides migration information for moving to the Yocto
5Project 2.1 Release (codename "krogoth") 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 sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
48 sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
49
50.. note::
51
52 The reason for this change is that it prepares the way for changing
53 the default to True in a future Yocto Project release. This future
54 change is a much more sensible default than False. However, the
55 change needs to be made gradually as a sudden change of the default
56 would potentially cause side-effects that would be difficult to
57 detect.
58
59.. _migration-2.1-makefile-environment-changes:
60
61Makefile Environment Changes
62----------------------------
63
64:term:`EXTRA_OEMAKE` now defaults to "" instead of
65"-e MAKEFLAGS=". Setting ``EXTRA_OEMAKE`` to "-e MAKEFLAGS=" by default
66was a historical accident that has required many classes (e.g.
67``autotools``, ``module``) and recipes to override this default in order
68to work with sensible build systems. When upgrading to the release, you
69must edit any recipe that relies upon this old default by either setting
70``EXTRA_OEMAKE`` back to "-e MAKEFLAGS=" or by explicitly setting any
71required variable value overrides using ``EXTRA_OEMAKE``, which is
72typically only needed when a Makefile sets a default value for a
73variable that is inappropriate for cross-compilation using the "="
74operator rather than the "?=" operator.
75
76.. _migration-2.1-libexecdir-reverted-to-prefix-libexec:
77
78``libexecdir`` Reverted to ``${prefix}/libexec``
79------------------------------------------------
80
81The use of ``${libdir}/${BPN}`` as ``libexecdir`` is different as
82compared to all other mainstream distributions, which either uses
83``${prefix}/libexec`` or ``${libdir}``. The use is also contrary to the
84GNU Coding Standards (i.e.
85https://www.gnu.org/prep/standards/html_node/Directory-Variables.html)
86that suggest ``${prefix}/libexec`` and also notes that any
87package-specific nesting should be done by the package itself. Finally,
88having ``libexecdir`` change between recipes makes it very difficult for
89different recipes to invoke binaries that have been installed into
90``libexecdir``. The Filesystem Hierarchy Standard (i.e.
91https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html) now
92recognizes the use of ``${prefix}/libexec/``, giving distributions the
93choice between ``${prefix}/lib`` or ``${prefix}/libexec`` without
94breaking FHS.
95
96.. _migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files:
97
98``ac_cv_sizeof_off_t`` is No Longer Cached in Site Files
99--------------------------------------------------------
100
101For recipes inheriting the :ref:`autotools <ref-classes-autotools>`
102class, ``ac_cv_sizeof_off_t`` is no longer cached in the site files for
103``autoconf``. The reason for this change is because the
104``ac_cv_sizeof_off_t`` value is not necessarily static per architecture
105as was previously assumed. Rather, the value changes based on whether
106large file support is enabled. For most software that uses ``autoconf``,
107this change should not be a problem. However, if you have a recipe that
108bypasses the standard :ref:`ref-tasks-configure` task
109from the ``autotools`` class and the software the recipe is building
110uses a very old version of ``autoconf``, the recipe might be incapable
111of determining the correct size of ``off_t`` during ``do_configure``.
112
113The best course of action is to patch the software as necessary to allow
114the default implementation from the ``autotools`` class to work such
115that ``autoreconf`` succeeds and produces a working configure script,
116and to remove the overridden ``do_configure`` task such that the default
117implementation does get used.
118
119.. _migration-2.1-image-generation-split-out-from-filesystem-generation:
120
121Image Generation is Now Split Out from Filesystem Generation
122------------------------------------------------------------
123
124Previously, for image recipes the :ref:`ref-tasks-rootfs`
125task assembled the filesystem and then from that filesystem generated
126images. With this Yocto Project release, image generation is split into
127separate :ref:`ref-tasks-image` tasks for clarity both in
128operation and in the code.
129
130For most cases, this change does not present any problems. However, if
131you have made customizations that directly modify the ``do_rootfs`` task
132or that mention ``do_rootfs``, you might need to update those changes.
133In particular, if you had added any tasks after ``do_rootfs``, you
134should make edits so that those tasks are after the
135:ref:`ref-tasks-image-complete` task rather than
136after ``do_rootfs`` so that your added tasks run at the correct
137time.
138
139A minor part of this restructuring is that the post-processing
140definitions and functions have been moved from the
141:ref:`image <ref-classes-image>` class to the
142:ref:`rootfs-postcommands <ref-classes-rootfs*>` class. Functionally,
143however, they remain unchanged.
144
145.. _migration-2.1-removed-recipes:
146
147Removed Recipes
148---------------
149
150The following recipes have been removed in the 2.1 release:
151
152- ``gcc`` version 4.8: Versions 4.9 and 5.3 remain.
153
154- ``qt4``: All support for Qt 4.x has been moved out to a separate
155 ``meta-qt4`` layer because Qt 4 is no longer supported upstream.
156
157- ``x11vnc``: Moved to the ``meta-oe`` layer.
158
159- ``linux-yocto-3.14``: No longer supported.
160
161- ``linux-yocto-3.19``: No longer supported.
162
163- ``libjpeg``: Replaced by the ``libjpeg-turbo`` recipe.
164
165- ``pth``: Became obsolete.
166
167- ``liboil``: Recipe is no longer needed and has been moved to the
168 ``meta-multimedia`` layer.
169
170- ``gtk-theme-torturer``: Recipe is no longer needed and has been moved
171 to the ``meta-gnome`` layer.
172
173- ``gnome-mime-data``: Recipe is no longer needed and has been moved to
174 the ``meta-gnome`` layer.
175
176- ``udev``: Replaced by the ``eudev`` recipe for compatibility when
177 using ``sysvinit`` with newer kernels.
178
179- ``python-pygtk``: Recipe became obsolete.
180
181- ``adt-installer``: Recipe became obsolete. See the
182 ":ref:`ref-manual/migration-2.1:adt removed`" section for more information.
183
184.. _migration-2.1-class-changes:
185
186Class Changes
187-------------
188
189The following classes have changed:
190
191- ``autotools_stage``: Removed because the
192 :ref:`autotools <ref-classes-autotools>` class now provides its
193 functionality. Recipes that inherited from ``autotools_stage`` should
194 now inherit from ``autotools`` instead.
195
196- ``boot-directdisk``: Merged into the ``image-vm`` class. The
197 ``boot-directdisk`` class was rarely directly used. Consequently,
198 this change should not cause any issues.
199
200- ``bootimg``: Merged into the
201 :ref:`image-live <ref-classes-image-live>` class. The ``bootimg``
202 class was rarely directly used. Consequently, this change should not
203 cause any issues.
204
205- ``packageinfo``: Removed due to its limited use by the Hob UI, which
206 has itself been removed.
207
208.. _migration-2.1-build-system-ui-changes:
209
210Build System User Interface Changes
211-----------------------------------
212
213The following changes have been made to the build system user interface:
214
215- *Hob GTK+-based UI*: Removed because it is unmaintained and based on
216 the outdated GTK+ 2 library. The Toaster web-based UI is much more
217 capable and is actively maintained. See the
218 ":ref:`toaster-manual/setup-and-use:using the toaster web interface`"
219 section in the Toaster User Manual for more information on this
220 interface.
221
222- *"puccho" BitBake UI*: Removed because is unmaintained and no longer
223 useful.
224
225.. _migration-2.1-adt-removed:
226
227ADT Removed
228-----------
229
230The Application Development Toolkit (ADT) has been removed because its
231functionality almost completely overlapped with the :ref:`standard
232SDK <sdk-manual/using:using the standard sdk>` and the
233:ref:`extensible SDK <sdk-manual/extensible:using the extensible sdk>`. For
234information on these SDKs and how to build and use them, see the
235:doc:`/sdk-manual/index` manual.
236
237.. note::
238
239 The Yocto Project Eclipse IDE Plug-in is still supported and is not
240 affected by this change.
241
242.. _migration-2.1-poky-reference-distribution-changes:
243
244Poky Reference Distribution Changes
245-----------------------------------
246
247The following changes have been made for the Poky distribution:
248
249- The ``meta-yocto`` layer has been renamed to ``meta-poky`` to better
250 match its purpose, which is to provide the Poky reference
251 distribution. The ``meta-yocto-bsp`` layer retains its original name
252 since it provides reference machines for the Yocto Project and it is
253 otherwise unrelated to Poky. References to ``meta-yocto`` in your
254 ``conf/bblayers.conf`` should automatically be updated, so you should
255 not need to change anything unless you are relying on this naming
256 elsewhere.
257
258- The :ref:`uninative <ref-classes-uninative>` class is now enabled
259 by default in Poky. This class attempts to isolate the build system
260 from the host distribution's C library and makes re-use of native
261 shared state artifacts across different host distributions practical.
262 With this class enabled, a tarball containing a pre-built C library
263 is downloaded at the start of the build.
264
265 The ``uninative`` class is enabled through the
266 ``meta/conf/distro/include/yocto-uninative.inc`` file, which for
267 those not using the Poky distribution, can include to easily enable
268 the same functionality.
269
270 Alternatively, if you wish to build your own ``uninative`` tarball,
271 you can do so by building the ``uninative-tarball`` recipe, making it
272 available to your build machines (e.g. over HTTP/HTTPS) and setting a
273 similar configuration as the one set by ``yocto-uninative.inc``.
274
275- Static library generation, for most cases, is now disabled by default
276 in the Poky distribution. Disabling this generation saves some build
277 time as well as the size used for build output artifacts.
278
279 Disabling this library generation is accomplished through a
280 ``meta/conf/distro/include/no-static-libs.inc``, which for those not
281 using the Poky distribution can easily include to enable the same
282 functionality.
283
284 Any recipe that needs to opt-out of having the "--disable-static"
285 option specified on the configure command line either because it is
286 not a supported option for the configure script or because static
287 libraries are needed should set the following variable::
288
289 DISABLE_STATIC = ""
290
291- The separate ``poky-tiny`` distribution now uses the musl C library
292 instead of a heavily pared down ``glibc``. Using musl results in a
293 smaller distribution and facilitates much greater maintainability
294 because musl is designed to have a small footprint.
295
296 If you have used ``poky-tiny`` and have customized the ``glibc``
297 configuration you will need to redo those customizations with musl
298 when upgrading to the new release.
299
300.. _migration-2.1-packaging-changes:
301
302Packaging Changes
303-----------------
304
305The following changes have been made to packaging:
306
307- The ``runuser`` and ``mountpoint`` binaries, which were previously in
308 the main ``util-linux`` package, have been split out into the
309 ``util-linux-runuser`` and ``util-linux-mountpoint`` packages,
310 respectively.
311
312- The ``python-elementtree`` package has been merged into the
313 ``python-xml`` package.
314
315.. _migration-2.1-tuning-file-changes:
316
317Tuning File Changes
318-------------------
319
320The following changes have been made to the tuning files:
321
322- The "no-thumb-interwork" tuning feature has been dropped from the ARM
323 tune include files. Because interworking is required for ARM EABI,
324 attempting to disable it through a tuning feature no longer makes
325 sense.
326
327 .. note::
328
329 Support for ARM OABI was deprecated in gcc 4.7.
330
331- The ``tune-cortexm*.inc`` and ``tune-cortexr4.inc`` files have been
332 removed because they are poorly tested. Until the OpenEmbedded build
333 system officially gains support for CPUs without an MMU, these tuning
334 files would probably be better maintained in a separate layer if
335 needed.
336
337.. _migration-2.1-supporting-gobject-introspection:
338
339Supporting GObject Introspection
340--------------------------------
341
342This release supports generation of GLib Introspective Repository (GIR)
343files through GObject introspection, which is the standard mechanism for
344accessing GObject-based software from runtime environments. You can
345enable, disable, and test the generation of this data. See the
346":ref:`dev-manual/common-tasks:enabling gobject introspection support`"
347section in the Yocto Project Development Tasks Manual for more
348information.
349
350.. _migration-2.1-miscellaneous-changes:
351
352Miscellaneous Changes
353---------------------
354
355These additional changes exist:
356
357- The minimum Git version has been increased to 1.8.3.1. If your host
358 distribution does not provide a sufficiently recent version, you can
359 install the buildtools, which will provide it. See the
360 :ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`
361 section for more information on the buildtools tarball.
362
363- The buggy and incomplete support for the RPM version 4 package
364 manager has been removed. The well-tested and maintained support for
365 RPM version 5 remains.
366
367- Previously, the following list of packages were removed if
368 package-management was not in
369 :term:`IMAGE_FEATURES`, regardless of any
370 dependencies::
371
372 update-rc.d
373 base-passwd
374 shadow
375 update-alternatives
376 run-postinsts
377
378 With the Yocto Project 2.1 release, these packages are
379 only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since
380 they might still be needed for a read-write image even in the absence
381 of a package manager (e.g. if users need to be added, modified, or
382 removed at runtime).
383
384- The
385 :ref:`devtool modify <sdk-manual/extensible:use \`\`devtool modify\`\` to modify the source of an existing component>`
386 command now defaults to extracting the source since that is most
387 commonly expected. The "-x" or "--extract" options are now no-ops. If
388 you wish to provide your own existing source tree, you will now need
389 to specify either the "-n" or "--no-extract" options when running
390 ``devtool modify``.
391
392- If the formfactor for a machine is either not supplied or does not
393 specify whether a keyboard is attached, then the default is to assume
394 a keyboard is attached rather than assume no keyboard. This change
395 primarily affects the Sato UI.
396
397- The ``.debug`` directory packaging is now automatic. If your recipe
398 builds software that installs binaries into directories other than
399 the standard ones, you no longer need to take care of setting
400 ``FILES_${PN}-dbg`` to pick up the resulting ``.debug`` directories
401 as these directories are automatically found and added.
402
403- Inaccurate disk and CPU percentage data has been dropped from
404 ``buildstats`` output. This data has been replaced with
405 ``getrusage()`` data and corrected IO statistics. You will probably
406 need to update any custom code that reads the ``buildstats`` data.
407
408- The ``meta/conf/distro/include/package_regex.inc`` is now deprecated.
409 The contents of this file have been moved to individual recipes.
410
411 .. note::
412
413 Because this file will likely be removed in a future Yocto Project
414 release, it is suggested that you remove any references to the
415 file that might be in your configuration.
416
417- The ``v86d/uvesafb`` has been removed from the ``genericx86`` and
418 ``genericx86-64`` reference machines, which are provided by the
419 ``meta-yocto-bsp`` layer. Most modern x86 boards do not rely on this
420 file and it only adds kernel error messages during startup. If you do
421 still need to support ``uvesafb``, you can simply add ``v86d`` to
422 your image.
423
424- Build sysroot paths are now removed from debug symbol files. Removing
425 these paths means that remote GDB using an unstripped build system
426 sysroot will no longer work (although this was never documented to
427 work). The supported method to accomplish something similar is to set
428 ``IMAGE_GEN_DEBUGFS`` to "1", which will generate a companion debug
429 image containing unstripped binaries and associated debug sources
430 alongside the image.
431
432
diff --git a/documentation/ref-manual/migration-2.2.rst b/documentation/ref-manual/migration-2.2.rst
deleted file mode 100644
index a60ce8d52b..0000000000
--- a/documentation/ref-manual/migration-2.2.rst
+++ /dev/null
@@ -1,446 +0,0 @@
1Moving to the Yocto Project 2.2 Release (morty)
2===============================================
3
4This section provides migration information for moving to the Yocto
5Project 2.2 Release (codename "morty") 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 :term:`OLDEST_KERNEL`
20 to anything down to 2.6.32 if desired.
21
22.. _migration-2.2-staging-directories-in-sysroot-simplified:
23
24Staging Directories in Sysroot Has Been Simplified
25--------------------------------------------------
26
27The way directories are staged in sysroot has been simplified and
28introduces the new :term:`SYSROOT_DIRS`,
29:term:`SYSROOT_DIRS_NATIVE`, and
30:term:`SYSROOT_DIRS_BLACKLIST`. See the
31:oe_lists:`v2 patch series on the OE-Core Mailing List
32</pipermail/openembedded-core/2016-May/121365.html>`
33for additional information.
34
35.. _migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled:
36
37Removal of Old Images and Other Files in ``tmp/deploy`` Now Enabled
38-------------------------------------------------------------------
39
40Removal of old images and other files in ``tmp/deploy/`` is now enabled
41by default due to a new staging method used for those files. As a result
42of this change, the ``RM_OLD_IMAGE`` variable is now redundant.
43
44.. _migration-2.2-python-changes:
45
46Python Changes
47--------------
48
49The following changes for Python occurred:
50
51.. _migration-2.2-bitbake-now-requires-python-3.4:
52
53BitBake Now Requires Python 3.4+
54~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55
56BitBake requires Python 3.4 or greater.
57
58.. _migration-2.2-utf-8-locale-required-on-build-host:
59
60UTF-8 Locale Required on Build Host
61~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62
63A UTF-8 locale is required on the build host due to Python 3. Since
64C.UTF-8 is not a standard, the default is en_US.UTF-8.
65
66.. _migration-2.2-metadata-now-must-use-python-3-syntax:
67
68Metadata Must Now Use Python 3 Syntax
69~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70
71The metadata is now required to use Python 3 syntax. For help preparing
72metadata, see any of the many Python 3 porting guides available.
73Alternatively, you can reference the conversion commits for Bitbake and
74you can use :term:`OpenEmbedded-Core (OE-Core)` as a guide for changes. Following are
75particular areas of interest:
76
77 - subprocess command-line pipes needing locale decoding
78
79 - the syntax for octal values changed
80
81 - the ``iter*()`` functions changed name
82
83 - iterators now return views, not lists
84
85 - changed names for Python modules
86
87.. _migration-2.2-target-python-recipes-switched-to-python-3:
88
89Target Python Recipes Switched to Python 3
90~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91
92Most target Python recipes have now been switched to Python 3.
93Unfortunately, systems using RPM as a package manager and providing
94online package-manager support through SMART still require Python 2.
95
96.. note::
97
98 Python 2 and recipes that use it can still be built for the target as
99 with previous versions.
100
101.. _migration-2.2-buildtools-tarball-includes-python-3:
102
103``buildtools-tarball`` Includes Python 3
104~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105
106``buildtools-tarball`` now includes Python 3.
107
108.. _migration-2.2-uclibc-replaced-by-musl:
109
110uClibc Replaced by musl
111-----------------------
112
113uClibc has been removed in favor of musl. Musl has matured, is better
114maintained, and is compatible with a wider range of applications as
115compared to uClibc.
116
117.. _migration-2.2-B-no-longer-default-working-directory-for-tasks:
118
119``${B}`` No Longer Default Working Directory for Tasks
120------------------------------------------------------
121
122``${``\ :term:`B`\ ``}`` is no longer the default working
123directory for tasks. Consequently, any custom tasks you define now need
124to either have the
125``[``\ :ref:`dirs <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` flag
126set, or the task needs to change into the appropriate working directory
127manually (e.g using ``cd`` for a shell task).
128
129.. note::
130
131 The preferred method is to use the
132 [dirs]
133 flag.
134
135.. _migration-2.2-runqemu-ported-to-python:
136
137``runqemu`` Ported to Python
138----------------------------
139
140``runqemu`` has been ported to Python and has changed behavior in some
141cases. Previous usage patterns continue to be supported.
142
143The new ``runqemu`` is a Python script. Machine knowledge is no longer
144hardcoded into ``runqemu``. You can choose to use the ``qemuboot``
145configuration file to define the BSP's own arguments and to make it
146bootable with ``runqemu``. If you use a configuration file, use the
147following form::
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 $ runqemu machine rootfs kernel [options]
165
166Supported machines are as follows:
167
168 - qemuarm
169 - qemuarm64
170 - qemux86
171 - qemux86-64
172 - qemuppc
173 - qemumips
174 - qemumips64
175 - qemumipsel
176 - qemumips64el
177
178Consider the
179following example, which uses the ``qemux86-64`` machine, provides a
180root filesystem, provides an image, and uses the ``nographic`` option::
181
182 $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
183
184Following is a list of variables that can be set in configuration files
185such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``:
186
187.. note::
188
189 "QB" means "QEMU Boot".
190
191::
192
193 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
194 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
195 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
196 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
197 QB_MEM: Memory (e.g. "-m 512")
198 QB_MACHINE: QEMU machine (e.g. "-machine virt")
199 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
200 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
201 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
202 option (e.g. "console=ttyS0 console=tty")
203 QB_DTB: QEMU dtb name
204 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
205 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
206 when QB_AUDIO_DRV is set.
207 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
208 QB_TAP_OPT: Network option for 'tap' mode (e.g.
209 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
210 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
211 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
212 QB_ROOTFS_OPT: Used as rootfs (e.g.
213 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
214 runqemu will replace "@ROOTFS@" with the one which is used, such as
215 core-image-minimal-qemuarm64.ext4.
216 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
217 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
218 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
219 runqemu will replace "@PORT@" with the port number which is used.
220
221To use ``runqemu``, set :term:`IMAGE_CLASSES` as
222follows and run ``runqemu``:
223
224.. note::
225
226 For command-line syntax, use ``runqemu help``.
227
228::
229
230 IMAGE_CLASSES += "qemuboot"
231
232.. _migration-2.2-default-linker-hash-style-changed:
233
234Default Linker Hash Style Changed
235---------------------------------
236
237The default linker hash style for ``gcc-cross`` is now "sysv" in order
238to catch recipes that are building software without using the
239OpenEmbedded :term:`LDFLAGS`. This change could result in
240seeing some "No GNU_HASH in the elf binary" QA issues when building such
241recipes. You need to fix these recipes so that they use the expected
242``LDFLAGS``. Depending on how the software is built, the build system
243used by the software (e.g. a Makefile) might need to be patched.
244However, sometimes making this fix is as simple as adding the following
245to the recipe::
246
247 TARGET_CC_ARCH += "${LDFLAGS}"
248
249.. _migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype:
250
251``KERNEL_IMAGE_BASE_NAME`` no Longer Uses ``KERNEL_IMAGETYPE``
252--------------------------------------------------------------
253
254The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the
255:term:`KERNEL_IMAGETYPE` variable to create the
256image's base name. Because the OpenEmbedded build system can now build
257multiple kernel image types, this part of the kernel image base name as
258been removed leaving only the following::
259
260 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
261
262If you have recipes or
263classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to
264update the references to ensure they continue to work.
265
266.. _migration-2.2-bitbake-changes:
267
268BitBake Changes
269---------------
270
271The following changes took place for BitBake:
272
273- The "goggle" UI and standalone image-writer tool have been removed as
274 they both require GTK+ 2.0 and were not being maintained.
275
276- The Perforce fetcher now supports :term:`SRCREV` for
277 specifying the source revision to use, be it
278 ``${``\ :term:`AUTOREV`\ ``}``, changelist number,
279 p4date, or label, in preference to separate
280 :term:`SRC_URI` parameters to specify these. This
281 change is more in-line with how the other fetchers work for source
282 control systems. Recipes that fetch from Perforce will need to be
283 updated to use ``SRCREV`` in place of specifying the source revision
284 within ``SRC_URI``.
285
286- Some of BitBake's internal code structures for accessing the recipe
287 cache needed to be changed to support the new multi-configuration
288 functionality. These changes will affect external tools that use
289 BitBake's tinfoil module. For information on these changes, see the
290 changes made to the scripts supplied with OpenEmbedded-Core:
291 :yocto_git:`1 </poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>`
292 and
293 :yocto_git:`2 </poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`.
294
295- The task management code has been rewritten to avoid using ID
296 indirection in order to improve performance. This change is unlikely
297 to cause any problems for most users. However, the setscene
298 verification function as pointed to by
299 ``BB_SETSCENE_VERIFY_FUNCTION`` needed to change signature.
300 Consequently, a new variable named ``BB_SETSCENE_VERIFY_FUNCTION2``
301 has been added allowing multiple versions of BitBake to work with
302 suitably written metadata, which includes OpenEmbedded-Core and Poky.
303 Anyone with custom BitBake task scheduler code might also need to
304 update the code to handle the new structure.
305
306.. _migration-2.2-swabber-has-been-removed:
307
308Swabber has Been Removed
309------------------------
310
311Swabber, a tool that was intended to detect host contamination in the
312build process, has been removed, as it has been unmaintained and unused
313for some time and was never particularly effective. The OpenEmbedded
314build system has since incorporated a number of mechanisms including
315enhanced QA checks that mean that there is less of a need for such a
316tool.
317
318.. _migration-2.2-removed-recipes:
319
320Removed Recipes
321---------------
322
323The following recipes have been removed:
324
325- ``augeas``: No longer needed and has been moved to ``meta-oe``.
326
327- ``directfb``: Unmaintained and has been moved to ``meta-oe``.
328
329- ``gcc``: Removed 4.9 version. Versions 5.4 and 6.2 are still present.
330
331- ``gnome-doc-utils``: No longer needed.
332
333- ``gtk-doc-stub``: Replaced by ``gtk-doc``.
334
335- ``gtk-engines``: No longer needed and has been moved to
336 ``meta-gnome``.
337
338- ``gtk-sato-engine``: Became obsolete.
339
340- ``libglade``: No longer needed and has been moved to ``meta-oe``.
341
342- ``libmad``: Unmaintained and functionally replaced by ``libmpg123``.
343 ``libmad`` has been moved to ``meta-oe``.
344
345- ``libowl``: Became obsolete.
346
347- ``libxsettings-client``: No longer needed.
348
349- ``oh-puzzles``: Functionally replaced by ``puzzles``.
350
351- ``oprofileui``: Became obsolete. OProfile has been largely supplanted
352 by perf.
353
354- ``packagegroup-core-directfb.bb``: Removed.
355
356- ``core-image-directfb.bb``: Removed.
357
358- ``pointercal``: No longer needed and has been moved to ``meta-oe``.
359
360- ``python-imaging``: No longer needed and moved to ``meta-python``
361
362- ``python-pyrex``: No longer needed and moved to ``meta-python``.
363
364- ``sato-icon-theme``: Became obsolete.
365
366- ``swabber-native``: Swabber has been removed. See the :ref:`entry on
367 Swabber <ref-manual/migration-2.2:swabber has been removed>`.
368
369- ``tslib``: No longer needed and has been moved to ``meta-oe``.
370
371- ``uclibc``: Removed in favor of musl.
372
373- ``xtscal``: No longer needed and moved to ``meta-oe``
374
375.. _migration-2.2-removed-classes:
376
377Removed Classes
378---------------
379
380The following classes have been removed:
381
382- ``distutils-native-base``: No longer needed.
383
384- ``distutils3-native-base``: No longer needed.
385
386- ``sdl``: Only set :term:`DEPENDS` and
387 :term:`SECTION`, which are better set within the
388 recipe instead.
389
390- ``sip``: Mostly unused.
391
392- ``swabber``: See the :ref:`entry on
393 Swabber <ref-manual/migration-2.2:swabber has been removed>`.
394
395.. _migration-2.2-minor-packaging-changes:
396
397Minor Packaging Changes
398-----------------------
399
400The following minor packaging changes have occurred:
401
402- ``grub``: Split ``grub-editenv`` into its own package.
403
404- ``systemd``: Split container and vm related units into a new package,
405 systemd-container.
406
407- ``util-linux``: Moved ``prlimit`` to a separate
408 ``util-linux-prlimit`` package.
409
410.. _migration-2.2-miscellaneous-changes:
411
412Miscellaneous Changes
413---------------------
414
415The following miscellaneous changes have occurred:
416
417- ``package_regex.inc``: Removed because the definitions
418 ``package_regex.inc`` previously contained have been moved to their
419 respective recipes.
420
421- Both ``devtool add`` and ``recipetool create`` now use a fixed
422 :term:`SRCREV` by default when fetching from a Git
423 repository. You can override this in either case to use
424 ``${``\ :term:`AUTOREV`\ ``}`` instead by using the
425 ``-a`` or ``--autorev`` command-line option
426
427- ``distcc``: GTK+ UI is now disabled by default.
428
429- ``packagegroup-core-tools-testapps``: Removed Piglit.
430
431- ``image.bbclass``: Renamed COMPRESS(ION) to CONVERSION. This change
432 means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and
433 ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``,
434 ``CONVERSION_DEPENDS`` and ``CONVERSION_CMD``. The ``COMPRESS*``
435 variable names will still work in the 2.2 release but metadata that
436 does not need to be backwards-compatible should be changed to use the
437 new names as the ``COMPRESS*`` ones will be removed in a future
438 release.
439
440- ``gtk-doc``: A full version of ``gtk-doc`` is now made available.
441 However, some old software might not be capable of using the current
442 version of ``gtk-doc`` to build documentation. You need to change
443 recipes that build such software so that they explicitly disable
444 building documentation with ``gtk-doc``.
445
446
diff --git a/documentation/ref-manual/migration-2.3.rst b/documentation/ref-manual/migration-2.3.rst
deleted file mode 100644
index dfbda612ae..0000000000
--- a/documentation/ref-manual/migration-2.3.rst
+++ /dev/null
@@ -1,517 +0,0 @@
1Moving to the Yocto Project 2.3 Release (pyro)
2==============================================
3
4This section provides migration information for moving to the Yocto
5Project 2.3 Release (codename "pyro") 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/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 ":ref:`ref-classes-staging`" section.
80
81.. _migration-2.3-path-variable:
82
83``PATH`` Variable
84-----------------
85
86Within the environment used to run build tasks, the environment variable
87``PATH`` is now sanitized such that the normal native binary paths
88(``/bin``, ``/sbin``, ``/usr/bin`` and so forth) are removed and a
89directory containing symbolic links linking only to the binaries from
90the host mentioned in the :term:`HOSTTOOLS` and
91:term:`HOSTTOOLS_NONFATAL` variables is added
92to ``PATH``.
93
94Consequently, any native binaries provided by the host that you need to
95call needs to be in one of these two variables at the configuration
96level.
97
98Alternatively, you can add a native recipe (i.e. ``-native``) that
99provides the binary to the recipe's :term:`DEPENDS`
100value.
101
102.. note::
103
104 PATH
105 is not sanitized in the same way within ``devshell``.
106 If it were, you would have difficulty running host tools for
107 development and debugging within the shell.
108
109.. _migration-2.3-scripts:
110
111Changes to Scripts
112------------------
113
114The following changes to scripts took place:
115
116- ``oe-find-native-sysroot``: The usage for the
117 ``oe-find-native-sysroot`` script has changed to the following::
118
119 $ . oe-find-native-sysroot recipe
120
121 You must now supply a recipe for recipe
122 as part of the command. Prior to the Yocto Project 2.3 release, it
123 was not necessary to provide the script with the command.
124
125- ``oe-run-native``: The usage for the ``oe-run-native`` script has
126 changed to the following::
127
128 $ oe-run-native native_recipe tool
129
130 You must
131 supply the name of the native recipe and the tool you want to run as
132 part of the command. Prior to the Yocto Project 2.3 release, it
133 was not necessary to provide the native recipe with the command.
134
135- ``cleanup-workdir``: The ``cleanup-workdir`` script has been
136 removed because the script was found to be deleting files it should
137 not have, which lead to broken build trees. Rather than trying to
138 delete portions of :term:`TMPDIR` and getting it wrong,
139 it is recommended that you delete ``TMPDIR`` and have it restored
140 from shared state (sstate) on subsequent builds.
141
142- ``wipe-sysroot``: The ``wipe-sysroot`` script has been removed as
143 it is no longer needed with recipe-specific sysroots.
144
145.. _migration-2.3-functions:
146
147Changes to Functions
148--------------------
149
150The previously deprecated ``bb.data.getVar()``, ``bb.data.setVar()``,
151and related functions have been removed in favor of ``d.getVar()``,
152``d.setVar()``, and so forth.
153
154You need to fix any references to these old functions.
155
156.. _migration-2.3-bitbake-changes:
157
158BitBake Changes
159---------------
160
161The following changes took place for BitBake:
162
163- *BitBake's Graphical Dependency Explorer UI Replaced:* BitBake's
164 graphical dependency explorer UI ``depexp`` was replaced by
165 ``taskexp`` ("Task Explorer"), which provides a graphical way of
166 exploring the ``task-depends.dot`` file. The data presented by Task
167 Explorer is much more accurate than the data that was presented by
168 ``depexp``. Being able to visualize the data is an often requested
169 feature as standard ``*.dot`` file viewers cannot usual cope with the
170 size of the ``task-depends.dot`` file.
171
172- *BitBake "-g" Output Changes:* The ``package-depends.dot`` and
173 ``pn-depends.dot`` files as previously generated using the
174 ``bitbake -g`` command have been removed. A ``recipe-depends.dot``
175 file is now generated as a collapsed version of ``task-depends.dot``
176 instead.
177
178 The reason for this change is because ``package-depends.dot`` and
179 ``pn-depends.dot`` largely date back to a time before task-based
180 execution and do not take into account task-level dependencies
181 between recipes, which could be misleading.
182
183- *Mirror Variable Splitting Changes:* Mirror variables including
184 :term:`MIRRORS`, :term:`PREMIRRORS`,
185 and :term:`SSTATE_MIRRORS` can now separate
186 values entirely with spaces. Consequently, you no longer need "\\n".
187 BitBake looks for pairs of values, which simplifies usage. There
188 should be no change required to existing mirror variable values
189 themselves.
190
191- *The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an
192 "rsh" Parameter:* The SVN fetcher now takes an "ssh" parameter
193 instead of an "rsh" parameter. This new optional parameter is used
194 when the "protocol" parameter is set to "svn+ssh". You can only use
195 the new parameter to specify the ``ssh`` program used by SVN. The SVN
196 fetcher passes the new parameter through the ``SVN_SSH`` environment
197 variable during the :ref:`ref-tasks-fetch` task.
198
199 See the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:subversion (svn) fetcher (\`\`svn://\`\`)`"
200 section in the BitBake
201 User Manual for additional information.
202
203- ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2``
204 Removed: Because the mechanism they were part of is no longer
205 necessary with recipe-specific sysroots, the
206 ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2``
207 variables have been removed.
208
209.. _migration-2.3-absolute-symlinks:
210
211Absolute Symbolic Links
212-----------------------
213
214Absolute symbolic links (symlinks) within staged files are no longer
215permitted and now trigger an error. Any explicit creation of symlinks
216can use the ``lnr`` script, which is a replacement for ``ln -r``.
217
218If the build scripts in the software that the recipe is building are
219creating a number of absolute symlinks that need to be corrected, you
220can inherit ``relative_symlinks`` within the recipe to turn those
221absolute symlinks into relative symlinks.
222
223.. _migration-2.3-gplv2-and-gplv3-moves:
224
225GPLv2 Versions of GPLv3 Recipes Moved
226-------------------------------------
227
228Older GPLv2 versions of GPLv3 recipes have moved to a separate
229``meta-gplv2`` layer.
230
231If you use :term:`INCOMPATIBLE_LICENSE` to
232exclude GPLv3 or set :term:`PREFERRED_VERSION`
233to substitute a GPLv2 version of a GPLv3 recipe, then you must add the
234``meta-gplv2`` layer to your configuration.
235
236.. note::
237
238 You can ``find meta-gplv2`` layer in the OpenEmbedded layer index at
239 :oe_layer:`/meta-gplv2`.
240
241These relocated GPLv2 recipes do not receive the same level of
242maintenance as other core recipes. The recipes do not get security fixes
243and upstream no longer maintains them. In fact, the upstream community
244is actively hostile towards people that use the old versions of the
245recipes. Moving these recipes into a separate layer both makes the
246different needs of the recipes clearer and clearly identifies the number
247of these recipes.
248
249.. note::
250
251 The long-term solution might be to move to BSD-licensed replacements
252 of the GPLv3 components for those that need to exclude GPLv3-licensed
253 components from the target system. This solution will be investigated
254 for future Yocto Project releases.
255
256.. _migration-2.3-package-management-changes:
257
258Package Management Changes
259--------------------------
260
261The following package management changes took place:
262
263- Smart package manager is replaced by DNF package manager. Smart has
264 become unmaintained upstream, is not ported to Python 3.x.
265 Consequently, Smart needed to be replaced. DNF is the only feasible
266 candidate.
267
268 The change in functionality is that the on-target runtime package
269 management from remote package feeds is now done with a different
270 tool that has a different set of command-line options. If you have
271 scripts that call the tool directly, or use its API, they need to be
272 fixed.
273
274 For more information, see the `DNF
275 Documentation <https://dnf.readthedocs.io/en/latest/>`__.
276
277- Rpm 5.x is replaced with Rpm 4.x. This is done for two major reasons:
278
279 - DNF is API-incompatible with Rpm 5.x and porting it and
280 maintaining the port is non-trivial.
281
282 - Rpm 5.x itself has limited maintenance upstream, and the Yocto
283 Project is one of the very few remaining users.
284
285- Berkeley DB 6.x is removed and Berkeley DB 5.x becomes the default:
286
287 - Version 6.x of Berkeley DB has largely been rejected by the open
288 source community due to its AGPLv3 license. As a result, most
289 mainstream open source projects that require DB are still
290 developed and tested with DB 5.x.
291
292 - In OE-core, the only thing that was requiring DB 6.x was Rpm 5.x.
293 Thus, no reason exists to continue carrying DB 6.x in OE-core.
294
295- ``createrepo`` is replaced with ``createrepo_c``.
296
297 ``createrepo_c`` is the current incarnation of the tool that
298 generates remote repository metadata. It is written in C as compared
299 to ``createrepo``, which is written in Python. ``createrepo_c`` is
300 faster and is maintained.
301
302- Architecture-independent RPM packages are "noarch" instead of "all".
303
304 This change was made because too many places in DNF/RPM4 stack
305 already make that assumption. Only the filenames and the architecture
306 tag has changed. Nothing else has changed in OE-core system,
307 particularly in the :ref:`allarch.bbclass <ref-classes-allarch>`
308 class.
309
310- Signing of remote package feeds using ``PACKAGE_FEED_SIGN`` is not
311 currently supported. This issue will be fully addressed in a future
312 Yocto Project release. See :yocto_bugs:`defect 11209 </show_bug.cgi?id=11209>`
313 for more information on a solution to package feed signing with RPM
314 in the Yocto Project 2.3 release.
315
316- OPKG now uses the libsolv backend for resolving package dependencies
317 by default. This is vastly superior to OPKG's internal ad-hoc solver
318 that was previously used. This change does have a small impact on
319 disk (around 500 KB) and memory footprint.
320
321 .. note::
322
323 For further details on this change, see the
324 :yocto_git:`commit message </poky/commit/?id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81>`.
325
326.. _migration-2.3-removed-recipes:
327
328Removed Recipes
329---------------
330
331The following recipes have been removed:
332
333- ``linux-yocto 4.8``: Version 4.8 has been removed. Versions 4.1
334 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 are now present.
335
336- ``python-smartpm``: Functionally replaced by ``dnf``.
337
338- ``createrepo``: Replaced by the ``createrepo-c`` recipe.
339
340- ``rpmresolve``: No longer needed with the move to RPM 4 as RPM
341 itself is used instead.
342
343- ``gstreamer``: Removed the GStreamer Git version recipes as they
344 have been stale. ``1.10.``\ x recipes are still present.
345
346- ``alsa-conf-base``: Merged into ``alsa-conf`` since ``libasound``
347 depended on both. Essentially, no way existed to install only one of
348 these.
349
350- ``tremor``: Moved to ``meta-multimedia``. Fixed-integer Vorbis
351 decoding is not needed by current hardware. Thus, GStreamer's ivorbis
352 plugin has been disabled by default eliminating the need for the
353 ``tremor`` recipe in :term:`OpenEmbedded-Core (OE-Core)`.
354
355- ``gummiboot``: Replaced by ``systemd-boot``.
356
357.. _migration-2.3-wic-changes:
358
359Wic Changes
360-----------
361
362The following changes have been made to Wic:
363
364.. note::
365
366 For more information on Wic, see the
367 ":ref:`dev-manual/common-tasks:creating partitioned images using wic`"
368 section in the Yocto Project Development Tasks Manual.
369
370- *Default Output Directory Changed:* Wic's default output directory is
371 now the current directory by default instead of the unusual
372 ``/var/tmp/wic``.
373
374 The "-o" and "--outdir" options remain unchanged and are used to
375 specify your preferred output directory if you do not want to use the
376 default directory.
377
378- *fsimage Plug-in Removed:* The Wic fsimage plugin has been removed as
379 it duplicates functionality of the rawcopy plugin.
380
381.. _migration-2.3-qa-changes:
382
383QA Changes
384----------
385
386The following QA checks have changed:
387
388- ``unsafe-references-in-binaries``: The
389 ``unsafe-references-in-binaries`` QA check, which was disabled by
390 default, has now been removed. This check was intended to detect
391 binaries in ``/bin`` that link to libraries in ``/usr/lib`` and have
392 the case where the user has ``/usr`` on a separate filesystem to
393 ``/``.
394
395 The removed QA check was buggy. Additionally, ``/usr`` residing on a
396 separate partition from ``/`` is now a rare configuration.
397 Consequently, ``unsafe-references-in-binaries`` was removed.
398
399- ``file-rdeps``: The ``file-rdeps`` QA check is now an error by
400 default instead of a warning. Because it is an error instead of a
401 warning, you need to address missing runtime dependencies.
402
403 For additional information, see the
404 :ref:`insane <ref-classes-insane>` class and the
405 ":ref:`ref-manual/qa-checks:errors and warnings`" section.
406
407.. _migration-2.3-miscellaneous-changes:
408
409Miscellaneous Changes
410---------------------
411
412The following miscellaneous changes have occurred:
413
414- In this release, a number of recipes have been changed to ignore the
415 ``largefile`` :term:`DISTRO_FEATURES` item,
416 enabling large file support unconditionally. This feature has always
417 been enabled by default. Disabling the feature has not been widely
418 tested.
419
420 .. note::
421
422 Future releases of the Yocto Project will remove entirely the
423 ability to disable the
424 largefile
425 feature, which would make it unconditionally enabled everywhere.
426
427- If the :term:`DISTRO_VERSION` value contains
428 the value of the :term:`DATE` variable, which is the
429 default between Poky releases, the ``DATE`` value is explicitly
430 excluded from ``/etc/issue`` and ``/etc/issue.net``, which is
431 displayed at the login prompt, in order to avoid conflicts with
432 Multilib enabled. Regardless, the ``DATE`` value is inaccurate if the
433 ``base-files`` recipe is restored from shared state (sstate) rather
434 than rebuilt.
435
436 If you need the build date recorded in ``/etc/issue*`` or anywhere
437 else in your image, a better method is to define a post-processing
438 function to do it and have the function called from
439 :term:`ROOTFS_POSTPROCESS_COMMAND`.
440 Doing so ensures the value is always up-to-date with the created
441 image.
442
443- Dropbear's ``init`` script now disables DSA host keys by default.
444 This change is in line with the systemd service file, which supports
445 RSA keys only, and with recent versions of OpenSSH, which deprecates
446 DSA host keys.
447
448- The :ref:`buildhistory <ref-classes-buildhistory>` class now
449 correctly uses tabs as separators between all columns in
450 ``installed-package-sizes.txt`` in order to aid import into other
451 tools.
452
453- The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig"
454 ``DISTRO_FEATURES`` feature. Distributions that previously set::
455
456 USE_LDCONFIG = "0"
457
458 should now instead use the following::
459
460 DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig"
461
462- The default value of
463 :term:`COPYLEFT_LICENSE_INCLUDE` now
464 includes all versions of AGPL licenses in addition to GPL and LGPL.
465
466 .. note::
467
468 The default list is not intended to be guaranteed as a complete
469 safe list. You should seek legal advice based on what you are
470 distributing if you are unsure.
471
472- Kernel module packages are now suffixed with the kernel version in
473 order to allow module packages from multiple kernel versions to
474 co-exist on a target system. If you wish to return to the previous
475 naming scheme that does not include the version suffix, use the
476 following::
477
478 KERNEL_MODULE_PACKAGE_SUFFIX = ""
479
480- Removal of ``libtool`` ``*.la`` files is now enabled by default. The
481 ``*.la`` files are not actually needed on Linux and relocating them
482 is an unnecessary burden.
483
484 If you need to preserve these ``.la`` files (e.g. in a custom
485 distribution), you must change
486 :term:`INHERIT_DISTRO` such that
487 "remove-libtool" is not included in the value.
488
489- Extensible SDKs built for GCC 5+ now refuse to install on a
490 distribution where the host GCC version is 4.8 or 4.9. This change
491 resulted from the fact that the installation is known to fail due to
492 the way the ``uninative`` shared state (sstate) package is built. See
493 the :ref:`uninative <ref-classes-uninative>` class for additional
494 information.
495
496- All native and nativesdk recipes now use a separate
497 ``DISTRO_FEATURES`` value instead of sharing the value used by
498 recipes for the target, in order to avoid unnecessary rebuilds.
499
500 The ``DISTRO_FEATURES`` for ``native`` recipes is
501 :term:`DISTRO_FEATURES_NATIVE` added to
502 an intersection of ``DISTRO_FEATURES`` and
503 :term:`DISTRO_FEATURES_FILTER_NATIVE`.
504
505 For nativesdk recipes, the corresponding variables are
506 :term:`DISTRO_FEATURES_NATIVESDK`
507 and
508 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`.
509
510- The ``FILESDIR`` variable, which was previously deprecated and rarely
511 used, has now been removed. You should change any recipes that set
512 ``FILESDIR`` to set :term:`FILESPATH` instead.
513
514- The ``MULTIMACH_HOST_SYS`` variable has been removed as it is no
515 longer needed with recipe-specific sysroots.
516
517
diff --git a/documentation/ref-manual/migration-2.4.rst b/documentation/ref-manual/migration-2.4.rst
deleted file mode 100644
index 2ba17e0ed5..0000000000
--- a/documentation/ref-manual/migration-2.4.rst
+++ /dev/null
@@ -1,327 +0,0 @@
1Moving to the Yocto Project 2.4 Release (rocko)
2===============================================
3
4This section provides migration information for moving to the Yocto
5Project 2.4 Release (codename "rocko") 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
deleted file mode 100644
index 86a0da9c40..0000000000
--- a/documentation/ref-manual/migration-2.5.rst
+++ /dev/null
@@ -1,308 +0,0 @@
1Moving to the Yocto Project 2.5 Release (sumo)
2==============================================
3
4This section provides migration information for moving to the Yocto
5Project 2.5 Release (codename "sumo") 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 bitbake <target> -c fetchall
144
145 should now be replaced with::
146
147 bitbake <target> --runall=fetch
148
149.. _migration-2.5-python-and-python3-changes:
150
151Python and Python 3 Changes
152---------------------------
153
154The following are auto-packaging changes to Python and Python 3:
155
156The script-managed ``python-*-manifest.inc`` files that were previously
157used to generate Python and Python 3 packages have been replaced with a
158JSON-based file that is easier to read and maintain. A new task is
159available for maintainers of the Python recipes to update the JSON file
160when upgrading to new Python versions. You can now edit the file
161directly instead of having to edit a script and run it to update the
162file.
163
164One particular change to note is that the Python recipes no longer have
165build-time provides for their packages. This assumes ``python-foo`` is
166one of the packages provided by the Python recipe. You can no longer run
167``bitbake python-foo`` or have a
168:term:`DEPENDS` on ``python-foo``,
169but doing either of the following causes the package to work as
170expected::
171
172 IMAGE_INSTALL_append = " python-foo"
173
174or ::
175
176 RDEPENDS_${PN} = "python-foo"
177
178The earlier build-time provides behavior was a quirk of the
179way the Python manifest file was created. For more information on this
180change please see :yocto_git:`this commit
181</poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`.
182
183.. _migration-2.5-miscellaneous-changes:
184
185Miscellaneous Changes
186---------------------
187
188The following are additional changes:
189
190- The ``kernel`` class supports building packages for multiple kernels.
191 If your kernel recipe or ``.bbappend`` file mentions packaging at
192 all, you should replace references to the kernel in package names
193 with ``${KERNEL_PACKAGE_NAME}``. For example, if you disable
194 automatic installation of the kernel image using
195 ``RDEPENDS_kernel-base = ""`` you can avoid warnings using
196 ``RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""`` instead.
197
198- The ``buildhistory`` class commits changes to the repository by
199 default so you no longer need to set ``BUILDHISTORY_COMMIT = "1"``.
200 If you want to disable commits you need to set
201 ``BUILDHISTORY_COMMIT = "0"`` in your configuration.
202
203- The ``beaglebone`` reference machine has been renamed to
204 ``beaglebone-yocto``. The ``beaglebone-yocto`` BSP is a reference
205 implementation using only mainline components available in
206 OpenEmbedded-Core and ``meta-yocto-bsp``, whereas Texas Instruments
207 maintains a full-featured BSP in the ``meta-ti`` layer. This rename
208 avoids the previous name clash that existed between the two BSPs.
209
210- The ``update-alternatives`` class no longer works with SysV ``init``
211 scripts because this usage has been problematic. Also, the
212 ``sysklogd`` recipe no longer uses ``update-alternatives`` because it
213 is incompatible with other implementations.
214
215- By default, the :ref:`cmake <ref-classes-cmake>` class uses
216 ``ninja`` instead of ``make`` for building. This improves build
217 performance. If a recipe is broken with ``ninja``, then the recipe
218 can set ``OECMAKE_GENERATOR = "Unix Makefiles"`` to change back to
219 ``make``.
220
221- The previously deprecated ``base_*`` functions have been removed in
222 favor of their replacements in ``meta/lib/oe`` and
223 ``bitbake/lib/bb``. These are typically used from recipes and
224 classes. Any references to the old functions must be updated. The
225 following table shows the removed functions and their replacements:
226
227 +------------------------------+----------------------------------------------------------+
228 | *Removed* | *Replacement* |
229 +==============================+==========================================================+
230 | base_path_join() | oe.path.join() |
231 +------------------------------+----------------------------------------------------------+
232 | base_path_relative() | oe.path.relative() |
233 +------------------------------+----------------------------------------------------------+
234 | base_path_out() | oe.path.format_display() |
235 +------------------------------+----------------------------------------------------------+
236 | base_read_file() | oe.utils.read_file() |
237 +------------------------------+----------------------------------------------------------+
238 | base_ifelse() | oe.utils.ifelse() |
239 +------------------------------+----------------------------------------------------------+
240 | base_conditional() | oe.utils.conditional() |
241 +------------------------------+----------------------------------------------------------+
242 | base_less_or_equal() | oe.utils.less_or_equal() |
243 +------------------------------+----------------------------------------------------------+
244 | base_version_less_or_equal() | oe.utils.version_less_or_equal() |
245 +------------------------------+----------------------------------------------------------+
246 | base_contains() | bb.utils.contains() |
247 +------------------------------+----------------------------------------------------------+
248 | base_both_contain() | oe.utils.both_contain() |
249 +------------------------------+----------------------------------------------------------+
250 | base_prune_suffix() | oe.utils.prune_suffix() |
251 +------------------------------+----------------------------------------------------------+
252 | oe_filter() | oe.utils.str_filter() |
253 +------------------------------+----------------------------------------------------------+
254 | oe_filter_out() | oe.utils.str_filter_out() (or use the \_remove operator) |
255 +------------------------------+----------------------------------------------------------+
256
257- Using ``exit 1`` to explicitly defer a postinstall script until first
258 boot is now deprecated since it is not an obvious mechanism and can
259 mask actual errors. If you want to explicitly defer a postinstall to
260 first boot on the target rather than at ``rootfs`` creation time, use
261 ``pkg_postinst_ontarget()`` or call
262 ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``.
263 Any failure of a ``pkg_postinst()`` script (including ``exit 1``)
264 will trigger a warning during ``do_rootfs``.
265
266 For more information, see the
267 ":ref:`dev-manual/common-tasks:post-installation scripts`"
268 section in the Yocto Project Development Tasks Manual.
269
270- The ``elf`` image type has been removed. This image type was removed
271 because the ``mkelfimage`` tool that was required to create it is no
272 longer provided by coreboot upstream and required updating every time
273 ``binutils`` updated.
274
275- Support for .iso image compression (previously enabled through
276 ``COMPRESSISO = "1"``) has been removed. The userspace tools
277 (``zisofs-tools``) are unmaintained and ``squashfs`` provides better
278 performance and compression. In order to build a live image with
279 squashfs+lz4 compression enabled you should now set
280 ``LIVE_ROOTFS_TYPE = "squashfs-lz4"`` and ensure that ``live`` is in
281 ``IMAGE_FSTYPES``.
282
283- Recipes with an unconditional dependency on ``libpam`` are only
284 buildable with ``pam`` in ``DISTRO_FEATURES``. If the dependency is
285 truly optional then it is recommended that the dependency be
286 conditional upon ``pam`` being in ``DISTRO_FEATURES``.
287
288- For EFI-based machines, the bootloader (``grub-efi`` by default) is
289 installed into the image at /boot. Wic can be used to split the
290 bootloader into separate boot and rootfs partitions if necessary.
291
292- Patches whose context does not match exactly (i.e. where patch
293 reports "fuzz" when applying) will generate a warning. For an example
294 of this see :yocto_git:`this commit
295 </poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57>`.
296
297- Layers are expected to set ``LAYERSERIES_COMPAT_layername`` to match
298 the version(s) of OpenEmbedded-Core they are compatible with. This is
299 specified as codenames using spaces to separate multiple values (e.g.
300 "rocko sumo"). If a layer does not set
301 ``LAYERSERIES_COMPAT_layername``, a warning will is shown. If a layer
302 sets a value that does not include the current version ("sumo" for
303 the 2.5 release), then an error will be produced.
304
305- The ``TZ`` environment variable is set to "UTC" within the build
306 environment in order to fix reproducibility problems in some recipes.
307
308
diff --git a/documentation/ref-manual/migration-2.6.rst b/documentation/ref-manual/migration-2.6.rst
deleted file mode 100644
index d1c6c0c5f5..0000000000
--- a/documentation/ref-manual/migration-2.6.rst
+++ /dev/null
@@ -1,452 +0,0 @@
1Moving to the Yocto Project 2.6 Release (thud)
2==============================================
3
4This section provides migration information for moving to the Yocto
5Project 2.6 Release (codename "thud") 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:ref:`ref-manual/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``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`` and ``distutils3``). Any recipe that inherits ``distutils*``
132 classes are affected. For example, the ``setuptools`` and ``setuptools3``
133 recipes are affected since they inherit the ``distutils*`` classes.
134
135Fetching these types of dependencies that are not provided in the
136sysroot negatively affects the ability to reproduce builds. This type of
137fetching is now explicitly disabled. Consequently, any missing
138dependencies in Python recipes that use these classes now result in an
139error during the ``do_configure`` task.
140
141.. _migration-2.6-linux-yocto-configuration-audit-issues-now-correctly-reported:
142
143``linux-yocto`` Configuration Audit Issues Now Correctly Reported
144-----------------------------------------------------------------
145
146Due to a bug, the kernel configuration audit functionality was not
147writing out any resulting warnings during the build. This issue is now
148corrected. You might notice these warnings now if you have a custom
149kernel configuration with a ``linux-yocto`` style kernel recipe.
150
151.. _migration-2.6-image-kernel-artifact-naming-changes:
152
153Image/Kernel Artifact Naming Changes
154------------------------------------
155
156The following changes have been made:
157
158- Name variables (e.g. :term:`IMAGE_NAME`) use a new
159 ``IMAGE_VERSION_SUFFIX`` variable instead of
160 :term:`DATETIME`. Using ``IMAGE_VERSION_SUFFIX``
161 allows easier and more direct changes.
162
163 The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf``
164 configuration file as follows::
165
166 IMAGE_VERSION_SUFFIX = "-${DATETIME}"
167
168- Several variables have changed names for consistency::
169
170 Old Variable Name New Variable Name
171 ========================================================
172 KERNEL_IMAGE_BASE_NAME KERNEL_IMAGE_NAME
173 KERNEL_IMAGE_SYMLINK_NAME KERNEL_IMAGE_LINK_NAME
174 MODULE_TARBALL_BASE_NAME MODULE_TARBALL_NAME
175 MODULE_TARBALL_SYMLINK_NAME MODULE_TARBALL_LINK_NAME
176 INITRAMFS_BASE_NAME INITRAMFS_NAME
177
178- The ``MODULE_IMAGE_BASE_NAME`` variable has been removed. The module
179 tarball name is now controlled directly with the
180 :term:`MODULE_TARBALL_NAME` variable.
181
182- The :term:`KERNEL_DTB_NAME` and
183 :term:`KERNEL_DTB_LINK_NAME` variables
184 have been introduced to control kernel Device Tree Binary (DTB)
185 artifact names instead of mangling ``KERNEL_IMAGE_*`` variables.
186
187- The :term:`KERNEL_FIT_NAME` and
188 :term:`KERNEL_FIT_LINK_NAME` variables
189 have been introduced to specify the name of flattened image tree
190 (FIT) kernel images similar to other deployed artifacts.
191
192- The :term:`MODULE_TARBALL_NAME` and
193 :term:`MODULE_TARBALL_LINK_NAME`
194 variable values no longer include the "module-" prefix or ".tgz"
195 suffix. These parts are now hardcoded so that the values are
196 consistent with other artifact naming variables.
197
198- Added the :term:`INITRAMFS_LINK_NAME`
199 variable so that the symlink can be controlled similarly to other
200 artifact types.
201
202- :term:`INITRAMFS_NAME` now uses
203 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" instead
204 of "${PV}-${PR}-${MACHINE}-${DATETIME}", which makes it consistent
205 with other variables.
206
207.. _migration-2.6-serial-console-deprecated:
208
209``SERIAL_CONSOLE`` Deprecated
210-----------------------------
211
212The :term:`SERIAL_CONSOLE` variable has been
213functionally replaced by the
214:term:`SERIAL_CONSOLES` variable for some time.
215With the Yocto Project 2.6 release, ``SERIAL_CONSOLE`` has been
216officially deprecated.
217
218``SERIAL_CONSOLE`` will continue to work as before for the 2.6 release.
219However, for the sake of future compatibility, it is recommended that
220you replace all instances of ``SERIAL_CONSOLE`` with
221``SERIAL_CONSOLES``.
222
223.. note::
224
225 The only difference in usage is that ``SERIAL_CONSOLES``
226 expects entries to be separated using semicolons as compared to
227 ``SERIAL_CONSOLE``, which expects spaces.
228
229.. _migration-2.6-poky-sets-unknown-configure-option-to-qa-error:
230
231Configure Script Reports Unknown Options as Errors
232--------------------------------------------------
233
234If the configure script reports an unknown option, this now triggers a
235QA error instead of a warning. Any recipes that previously got away with
236specifying such unknown options now need to be fixed.
237
238.. _migration-2.6-override-changes:
239
240Override Changes
241----------------
242
243The following changes have occurred:
244
245- The ``virtclass-native`` and ``virtclass-nativesdk`` Overrides Have
246 Been Removed: The ``virtclass-native`` and ``virtclass-nativesdk``
247 overrides have been deprecated since 2012 in favor of
248 ``class-native`` and ``class-nativesdk``, respectively. Both
249 ``virtclass-native`` and ``virtclass-nativesdk`` are now dropped.
250
251 .. note::
252
253 The ``virtclass-multilib-`` overrides for multilib are still valid.
254
255- The ``forcevariable`` Override Now Has a Higher Priority Than
256 ``libc`` Overrides: The ``forcevariable`` override is documented to
257 be the highest priority override. However, due to a long-standing
258 quirk of how :term:`OVERRIDES` is set, the ``libc``
259 overrides (e.g. ``libc-glibc``, ``libc-musl``, and so forth)
260 erroneously had a higher priority. This issue is now corrected.
261
262 It is likely this change will not cause any problems. However, it is
263 possible with some unusual configurations that you might see a change
264 in behavior if you were relying on the previous behavior. Be sure to
265 check how you use ``forcevariable`` and ``libc-*`` overrides in your
266 custom layers and configuration files to ensure they make sense.
267
268- The ``build-${BUILD_OS}`` Override Has Been Removed: The
269 ``build-${BUILD_OS}``, which is typically ``build-linux``, override
270 has been removed because building on a host operating system other
271 than a recent version of Linux is neither supported nor recommended.
272 Dropping the override avoids giving the impression that other host
273 operating systems might be supported.
274
275- The "_remove" operator now preserves whitespace. Consequently, when
276 specifying list items to remove, be aware that leading and trailing
277 whitespace resulting from the removal is retained.
278
279 See the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:removal (override style syntax)`"
280 section in the BitBake User Manual for a detailed example.
281
282.. _migration-2.6-systemd-configuration-now-split-out-to-system-conf:
283
284``systemd`` Configuration is Now Split Into ``systemd-conf``
285------------------------------------------------------------
286
287The configuration for the ``systemd`` recipe has been moved into a
288``system-conf`` recipe. Moving this configuration to a separate recipe
289avoids the ``systemd`` recipe from becoming machine-specific for cases
290where machine-specific configurations need to be applied (e.g. for
291``qemu*`` machines).
292
293Currently, the new recipe packages the following files::
294
295 ${sysconfdir}/machine-id
296 ${sysconfdir}/systemd/coredump.conf
297 ${sysconfdir}/systemd/journald.conf
298 ${sysconfdir}/systemd/logind.conf
299 ${sysconfdir}/systemd/system.conf
300 ${sysconfdir}/systemd/user.conf
301
302If you previously used bbappend files to append the ``systemd`` recipe to
303change any of the listed files, you must do so for the ``systemd-conf``
304recipe instead.
305
306.. _migration-2.6-automatic-testing-changes:
307
308Automatic Testing Changes
309-------------------------
310
311This section provides information about automatic testing changes:
312
313- ``TEST_IMAGE`` Variable Removed: Prior to this release, you set the
314 ``TEST_IMAGE`` variable to "1" to enable automatic testing for
315 successfully built images. The ``TEST_IMAGE`` variable no longer
316 exists and has been replaced by the
317 :term:`TESTIMAGE_AUTO` variable.
318
319- Inheriting the ``testimage`` and ``testsdk`` Classes: Best
320 practices now dictate that you use the
321 :term:`IMAGE_CLASSES` variable rather than the
322 :term:`INHERIT` variable when you inherit the
323 :ref:`testimage <ref-classes-testimage*>` and
324 :ref:`testsdk <ref-classes-testsdk>` classes used for automatic
325 testing.
326
327.. _migration-2.6-openssl-changes:
328
329OpenSSL Changes
330---------------
331
332`OpenSSL <https://www.openssl.org/>`__ has been upgraded from 1.0 to
3331.1. By default, this upgrade could cause problems for recipes that have
334both versions in their dependency chains. The problem is that both
335versions cannot be installed together at build time.
336
337.. note::
338
339 It is possible to have both versions of the library at runtime.
340
341.. _migration-2.6-bitbake-changes:
342
343BitBake Changes
344---------------
345
346The server logfile ``bitbake-cookerdaemon.log`` is now always placed in
347the :term:`Build Directory` instead of the current
348directory.
349
350.. _migration-2.6-security-changes:
351
352Security Changes
353----------------
354
355The Poky distribution now uses security compiler flags by default.
356Inclusion of these flags could cause new failures due to stricter
357checking for various potential security issues in code.
358
359.. _migration-2.6-post-installation-changes:
360
361Post Installation Changes
362-------------------------
363
364You must explicitly mark post installs to defer to the target. If you
365want to explicitly defer a postinstall to first boot on the target
366rather than at rootfs creation time, use ``pkg_postinst_ontarget()`` or
367call ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``.
368Any failure of a ``pkg_postinst()`` script (including exit 1) triggers
369an error during the :ref:`ref-tasks-rootfs` task.
370
371For more information on post-installation behavior, see the
372":ref:`dev-manual/common-tasks:post-installation scripts`"
373section in the Yocto Project Development Tasks Manual.
374
375.. _migration-2.6-python-3-profile-guided-optimizations:
376
377Python 3 Profile-Guided Optimization
378------------------------------------
379
380The ``python3`` recipe now enables profile-guided optimization. Using
381this optimization requires a little extra build time in exchange for
382improved performance on the target at runtime. Additionally, the
383optimization is only enabled if the current
384:term:`MACHINE` has support for user-mode emulation in
385QEMU (i.e. "qemu-usermode" is in
386:term:`MACHINE_FEATURES`, which it is by
387default).
388
389If you wish to disable Python profile-guided optimization regardless of
390the value of ``MACHINE_FEATURES``, then ensure that
391:term:`PACKAGECONFIG` for the ``python3`` recipe
392does not contain "pgo". You could accomplish the latter using the
393following at the configuration level::
394
395 PACKAGECONFIG_remove_pn-python3 = "pgo"
396
397Alternatively, you can set ``PACKAGECONFIG`` using an append file
398for the ``python3`` recipe.
399
400.. _migration-2.6-miscellaneous-changes:
401
402Miscellaneous Changes
403---------------------
404
405The following miscellaneous changes occurred:
406
407- Default to using the Thumb-2 instruction set for armv7a and above. If
408 you have any custom recipes that build software that needs to be
409 built with the ARM instruction set, change the recipe to set the
410 instruction set as follows::
411
412 ARM_INSTRUCTION_SET = "arm"
413
414- ``run-postinsts`` no longer uses ``/etc/*-postinsts`` for
415 ``dpkg/opkg`` in favor of built-in postinst support. RPM behavior
416 remains unchanged.
417
418- The ``NOISO`` and ``NOHDD`` variables are no longer used. You now
419 control building ``*.iso`` and ``*.hddimg`` image types directly by
420 using the :term:`IMAGE_FSTYPES` variable.
421
422- The ``scripts/contrib/mkefidisk.sh`` has been removed in favor of
423 Wic.
424
425- ``kernel-modules`` has been removed from
426 :term:`RRECOMMENDS` for ``qemumips`` and
427 ``qemumips64`` machines. Removal also impacts the ``x86-base.inc``
428 file.
429
430 .. note::
431
432 ``genericx86`` and ``genericx86-64`` retain ``kernel-modules`` as part of
433 the ``RRECOMMENDS`` variable setting.
434
435- The ``LGPLv2_WHITELIST_GPL-3.0`` variable has been removed. If you
436 are setting this variable in your configuration, set or append it to
437 the ``WHITELIST_GPL-3.0`` variable instead.
438
439- ``${ASNEEDED}`` is now included in the
440 :term:`TARGET_LDFLAGS` variable directly. The
441 remaining definitions from ``meta/conf/distro/include/as-needed.inc``
442 have been moved to corresponding recipes.
443
444- Support for DSA host keys has been dropped from the OpenSSH recipes.
445 If you are still using DSA keys, you must switch over to a more
446 secure algorithm as recommended by OpenSSH upstream.
447
448- The ``dhcp`` recipe now uses the ``dhcpd6.conf`` configuration file
449 in ``dhcpd6.service`` for IPv6 DHCP rather than re-using
450 ``dhcpd.conf``, which is now reserved for IPv4.
451
452
diff --git a/documentation/ref-manual/migration-2.7.rst b/documentation/ref-manual/migration-2.7.rst
deleted file mode 100644
index 1be4d5d5b9..0000000000
--- a/documentation/ref-manual/migration-2.7.rst
+++ /dev/null
@@ -1,180 +0,0 @@
1Moving to the Yocto Project 2.7 Release (warrior)
2=================================================
3
4This section provides migration information for moving to the Yocto
5Project 2.7 Release (codename "warrior") 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 <https://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
deleted file mode 100644
index a3da850150..0000000000
--- a/documentation/ref-manual/migration-3.0.rst
+++ /dev/null
@@ -1,319 +0,0 @@
1Moving to the Yocto Project 3.0 Release (zeus)
2==============================================
3
4This section provides migration information for moving to the Yocto
5Project 3.0 Release (codename "zeus") 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 ``BB_SETSCENE_VERIFY_FUNCTION2`` variable is no longer used. In
188 the unlikely event that you have any references to it, they should be
189 removed.
190
191- The ``RunQueueExecuteScenequeue`` and ``RunQueueExecuteTasks`` events
192 have been removed since setscene tasks are now executed as part of
193 the normal runqueue. Any event handling code in custom classes or
194 scripts that handles these two events need to be updated.
195
196- The arguments passed to functions used with
197 :term:`bitbake:BB_HASHCHECK_FUNCTION`
198 have changed. If you are using your own custom hash check function,
199 see :yocto_git:`/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725`
200 for details.
201
202- Task specifications in ``BB_TASKDEPDATA`` and class implementations
203 used in signature generator classes now use "<fn>:<task>" everywhere
204 rather than the "." delimiter that was being used in some places.
205 This change makes it consistent with all areas in the code. Custom
206 signature generator classes and code that reads ``BB_TASKDEPDATA``
207 need to be updated to use ':' as a separator rather than '.'.
208
209.. _migration-3.0-sanity-checks:
210
211Sanity Checks
212-------------
213
214The following sanity check changes occurred.
215
216- :term:`SRC_URI` is now checked for usage of two
217 problematic items:
218
219 - "${PN}" prefix/suffix use - Warnings always appear if ${PN} is
220 used. You must fix the issue regardless of whether multiconfig or
221 anything else that would cause prefixing/suffixing to happen.
222
223 - Github archive tarballs - these are not guaranteed to be stable.
224 Consequently, it is likely that the tarballs will be refreshed and
225 thus the SRC_URI checksums will fail to apply. It is recommended
226 that you fetch either an official release tarball or a specific
227 revision from the actual Git repository instead.
228
229 Either one of these items now trigger a warning by default. If you
230 wish to disable this check, remove ``src-uri-bad`` from
231 :term:`WARN_QA`.
232
233- The ``file-rdeps`` runtime dependency check no longer expands
234 :term:`RDEPENDS` recursively as there is no mechanism
235 to ensure they can be fully computed, and thus races sometimes result
236 in errors either showing up or not. Thus, you might now see errors
237 for missing runtime dependencies that were previously satisfied
238 recursively. Here is an example: package A contains a shell script
239 starting with ``#!/bin/bash`` but has no dependency on bash. However,
240 package A depends on package B, which does depend on bash. You need
241 to add the missing dependency or dependencies to resolve the warning.
242
243- Setting ``DEPENDS_${PN}`` anywhere (i.e. typically in a recipe) now
244 triggers an error. The error is triggered because
245 :term:`DEPENDS` is not a package-specific variable
246 unlike RDEPENDS. You should set ``DEPENDS`` instead.
247
248- systemd currently does not work well with the musl C library because
249 only upstream officially supports linking the library with glibc.
250 Thus, a warning is shown when building systemd in conjunction with
251 musl.
252
253.. _migration-3.0-miscellaneous-changes:
254
255Miscellaneous Changes
256---------------------
257
258The following miscellaneous changes have occurred.
259
260- The ``gnome`` class has been removed because it now does very little.
261 You should update recipes that previously inherited this class to do
262 the following: inherit gnomebase gtk-icon-cache gconf mime
263
264- The ``meta/recipes-kernel/linux/linux-dtb.inc`` file has been
265 removed. This file was previously deprecated in favor of setting
266 :term:`KERNEL_DEVICETREE` in any kernel
267 recipe and only produced a warning. Remove any ``include`` or
268 ``require`` statements pointing to this file.
269
270- :term:`TARGET_CFLAGS`,
271 :term:`TARGET_CPPFLAGS`,
272 :term:`TARGET_CXXFLAGS`, and
273 :term:`TARGET_LDFLAGS` are no longer exported
274 to the external environment. This change did not require any changes
275 to core recipes, which is a good indicator that no changes will be
276 required. However, if for some reason the software being built by one
277 of your recipes is expecting these variables to be set, then building
278 the recipe will fail. In such cases, you must either export the
279 variable or variables in the recipe or change the scripts so that
280 exporting is not necessary.
281
282- You must change the host distro identifier used in
283 :term:`NATIVELSBSTRING` to use all lowercase
284 characters even if it does not contain a version number. This change
285 is necessary only if you are not using ``uninative`` and
286 :term:`SANITY_TESTED_DISTROS`.
287
288- In the ``base-files`` recipe, writing the hostname into
289 ``/etc/hosts`` and ``/etc/hostname`` is now done within the main
290 :ref:`ref-tasks-install` function rather than in the
291 ``do_install_basefilesissue`` function. The reason for the change is
292 because ``do_install_basefilesissue`` is more easily overridden
293 without having to duplicate the hostname functionality. If you have
294 done the latter (e.g. in a ``base-files`` bbappend), then you should
295 remove it from your customized ``do_install_basefilesissue``
296 function.
297
298- The ``wic --expand`` command now uses commas to separate "key:value"
299 pairs rather than hyphens.
300
301 .. note::
302
303 The wic command-line help is not updated.
304
305 You must update any scripts or commands where you use
306 ``wic --expand`` with multiple "key:value" pairs.
307
308- UEFI image variable settings have been moved from various places to a
309 central ``conf/image-uefi.conf``. This change should not influence
310 any existing configuration as the ``meta/conf/image-uefi.conf`` in
311 the core metadata sets defaults that can be overridden in the same
312 manner as before.
313
314- ``conf/distro/include/world-broken.inc`` has been removed. For cases
315 where certain recipes need to be disabled when using the musl C
316 library, these recipes now have ``COMPATIBLE_HOST_libc-musl`` set
317 with a comment that explains why.
318
319
diff --git a/documentation/ref-manual/migration-3.1.rst b/documentation/ref-manual/migration-3.1.rst
deleted file mode 100644
index 7822285a87..0000000000
--- a/documentation/ref-manual/migration-3.1.rst
+++ /dev/null
@@ -1,275 +0,0 @@
1Moving to the Yocto Project 3.1 Release (dunfell)
2=================================================
3
4This section provides migration information for moving to the Yocto
5Project 3.1 Release (codename "dunfell") 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 DISTRO_FEATURES_remove = "ptest"
77
78.. _migration-3.1-removed-recipes:
79
80Removed recipes
81---------------
82
83The following recipes have been removed:
84
85- ``chkconfig``: obsolete
86
87- ``console-tools``: obsolete
88
89- ``enchant``: replaced by ``enchant2``
90
91- ``foomatic-filters``: obsolete
92
93- ``libidn``: no longer needed, moved to meta-oe
94
95- ``libmodulemd``: replaced by ``libmodulemd-v1``
96
97- ``linux-yocto``: drop 4.19, 5.2 version recipes (5.4 now provided)
98
99- ``nspr``: no longer needed, moved to meta-oe
100
101- ``nss``: no longer needed, moved to meta-oe
102
103- ``python``: Python 2 removed (Python 3 preferred)
104
105- ``python-setuptools``: Python 2 version removed (python3-setuptools
106 preferred)
107
108- ``sysprof``: no longer needed, moved to meta-oe
109
110- ``texi2html``: obsolete
111
112- ``u-boot-fw-utils``: functionally replaced by ``libubootenv``
113
114.. _migration-3.1-features-check:
115
116features_check class replaces distro_features_check
117---------------------------------------------------
118
119The ``distro_features_check`` class has had its functionality expanded,
120now supporting ``ANY_OF_MACHINE_FEATURES``,
121``REQUIRED_MACHINE_FEATURES``, ``CONFLICT_MACHINE_FEATURES``,
122``ANY_OF_COMBINED_FEATURES``, ``REQUIRED_COMBINED_FEATURES``,
123``CONFLICT_COMBINED_FEATURES``. As a result the class has now been
124renamed to ``features_check``; the ``distro_features_check`` class still
125exists but generates a warning and redirects to the new class. In
126preparation for a future removal of the old class it is recommended that
127you update recipes currently inheriting ``distro_features_check`` to
128inherit ``features_check`` instead.
129
130.. _migration-3.1-removed-classes:
131
132Removed classes
133---------------
134
135The following classes have been removed:
136
137- ``distutils-base``: moved to meta-python2
138
139- ``distutils``: moved to meta-python2
140
141- ``libc-common``: merged into the glibc recipe as nothing else used
142 it.
143
144- ``python-dir``: moved to meta-python2
145
146- ``pythonnative``: moved to meta-python2
147
148- ``setuptools``: moved to meta-python2
149
150- ``tinderclient``: dropped as it was obsolete.
151
152.. _migration-3.1-src-uri-checksums:
153
154SRC_URI checksum behaviour
155--------------------------
156
157Previously, recipes by tradition included both SHA256 and MD5 checksums
158for remotely fetched files in :term:`SRC_URI`, even
159though only one is actually mandated. However, the MD5 checksum does not
160add much given its inherent weakness; thus when a checksum fails only
161the SHA256 sum will now be printed. The md5sum will still be verified if
162it is specified.
163
164.. _migration-3.1-npm:
165
166npm fetcher changes
167-------------------
168
169The npm fetcher has been completely reworked in this release. The npm
170fetcher now only fetches the package source itself and no longer the
171dependencies; there is now also an npmsw fetcher which explicitly
172fetches the shrinkwrap file and the dependencies. This removes the
173slightly awkward ``NPM_LOCKDOWN`` and ``NPM_SHRINKWRAP`` variables which
174pointed to local files; the lockdown file is no longer needed at all.
175Additionally, the package name in ``npm://`` entries in
176:term:`SRC_URI` is now specified using a ``package``
177parameter instead of the earlier ``name`` which overlapped with the
178generic ``name`` parameter. All recipes using the npm fetcher will need
179to be changed as a result.
180
181An example of the new scheme::
182
183 SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \
184 npmsw://${THISDIR}/npm-shrinkwrap.json"
185
186Another example where the sources are fetched from git rather than an npm repository::
187
188 SRC_URI = "git://github.com/foo/bar.git;protocol=https \
189 npmsw://${THISDIR}/npm-shrinkwrap.json"
190
191devtool and recipetool have also been updated to match with the npm
192fetcher changes. Other than producing working and more complete recipes
193for npm sources, there is also a minor change to the command line for
194devtool: the ``--fetch-dev`` option has been renamed to ``--npm-dev`` as
195it is npm-specific.
196
197.. _migration-3.1-packaging-changes:
198
199Packaging changes
200-----------------
201
202- ``intltool`` has been removed from ``packagegroup-core-sdk`` as it is
203 rarely needed to build modern software - gettext can do most of the
204 things it used to be needed for. ``intltool`` has also been removed
205 from ``packagegroup-core-self-hosted`` as it is not needed to for
206 standard builds.
207
208- git: ``git-am``, ``git-difftool``, ``git-submodule``, and
209 ``git-request-pull`` are no longer perl-based, so are now installed
210 with the main ``git`` package instead of within ``git-perltools``.
211
212- The ``ldconfig`` binary built as part of glibc has now been moved to
213 its own ``ldconfig`` package (note no ``glibc-`` prefix). This
214 package is in the :term:`RRECOMMENDS` of the main
215 ``glibc`` package if ``ldconfig`` is present in
216 :term:`DISTRO_FEATURES`.
217
218- ``libevent`` now splits each shared library into its own package (as
219 Debian does). Since these are shared libraries and will be pulled in
220 through the normal shared library dependency handling, there should
221 be no impact to existing configurations other than less unnecessary
222 libraries being installed in some cases.
223
224- linux-firmware now has a new package for ``bcm4366c`` and includes
225 available NVRAM config files into the ``bcm43340``, ``bcm43362``,
226 ``bcm43430`` and ``bcm4356-pcie`` packages.
227
228- ``harfbuzz`` now splits the new ``libharfbuzz-subset.so`` library
229 into its own package to reduce the main package size in cases where
230 ``libharfbuzz-subset.so`` is not needed.
231
232.. _migration-3.1-package-qa-warnings:
233
234Additional warnings
235-------------------
236
237Warnings will now be shown at ``do_package_qa`` time in the following
238circumstances:
239
240- A recipe installs ``.desktop`` files containing ``MimeType`` keys but
241 does not inherit the new ``mime-xdg`` class
242
243- A recipe installs ``.xml`` files into ``${datadir}/mime/packages``
244 but does not inherit the ``mime`` class
245
246.. _migration-3.1-x86-live-wic:
247
248``wic`` image type now used instead of ``live`` by default for x86
249------------------------------------------------------------------
250
251``conf/machine/include/x86-base.inc`` (inherited by most x86 machine
252configurations) now specifies ``wic`` instead of ``live`` by default in
253:term:`IMAGE_FSTYPES`. The ``live`` image type will
254likely be removed in a future release so it is recommended that you use
255``wic`` instead.
256
257.. _migration-3.1-misc:
258
259Miscellaneous changes
260---------------------
261
262- The undocumented ``SRC_DISTRIBUTE_LICENSES`` variable has now been
263 removed in favour of a new ``AVAILABLE_LICENSES`` variable which is
264 dynamically set based upon license files found in
265 ``${COMMON_LICENSE_DIR}`` and ``${LICENSE_PATH}``.
266
267- The tune definition for big-endian microblaze machines is now
268 ``microblaze`` instead of ``microblazeeb``.
269
270- ``newlib`` no longer has built-in syscalls. ``libgloss`` should then
271 provide the syscalls, ``crt0.o`` and other functions that are no
272 longer part of ``newlib`` itself. If you are using
273 ``TCLIBC = "newlib"`` this now means that you must link applications
274 with both ``newlib`` and ``libgloss``, whereas before ``newlib``
275 would run in many configurations by itself.
diff --git a/documentation/ref-manual/migration-3.2.rst b/documentation/ref-manual/migration-3.2.rst
deleted file mode 100644
index 956a56f626..0000000000
--- a/documentation/ref-manual/migration-3.2.rst
+++ /dev/null
@@ -1,313 +0,0 @@
1Moving to the Yocto Project 3.2 Release (gatesgarth)
2====================================================
3
4This section provides migration information for moving to the Yocto
5Project 3.2 Release (codename "gatesgarth") from the prior release.
6
7.. _migration-3.2-minimum-system-requirements:
8
9Minimum system requirements
10---------------------------
11
12``gcc`` version 6.0 is now required at minimum on the build host. For older
13host distributions where this is not available, you can use the
14``buildtools-extended-tarball`` (easily installable using
15``scripts/install-buildtools``).
16
17
18.. _migration-3.2-removed-recipes:
19
20Removed recipes
21---------------
22
23The following recipes have been removed:
24
25- ``bjam-native``: replaced by ``boost-build-native``
26- ``avahi-ui``: folded into the main ``avahi`` recipe - the GTK UI can be disabled using :term:`PACKAGECONFIG` for ``avahi``.
27- ``build-compare``: no longer needed with the removal of the ``packagefeed-stability`` class
28- ``dhcp``: obsolete, functionally replaced by ``dhcpcd`` and ``kea``
29- ``libmodulemd-v1``: replaced by ``libmodulemd``
30- ``packagegroup-core-device-devel``: obsolete
31
32
33.. _migration-3.2-removed-classes:
34
35Removed classes
36---------------
37
38The following classes (.bbclass files) have been removed:
39
40- ``spdx``: obsolete - the Yocto Project is a strong supporter of SPDX, but this class was old code using a dated approach and had the potential to be misleading. The ``meta-sdpxscanner`` layer is a much more modern and active approach to handling this and is recommended as a replacement.
41
42- ``packagefeed-stability``: this class had become obsolete with the advent of hash equivalence and reproducible builds.
43
44
45pseudo path filtering and mismatch behaviour
46--------------------------------------------
47
48pseudo now operates on a filtered subset of files. This is a significant change
49to the way pseudo operates within OpenEmbedded - by default, pseudo monitors and
50logs (adds to its database) any file created or modified whilst in a ``fakeroot``
51environment. However, there are large numbers of files that we simply don't care
52about the permissions of whilst in that ``fakeroot`` context, for example ${:term:`S`}, ${:term:`B`}, ${:term:`T`},
53${:term:`SSTATE_DIR`}, the central sstate control directories, and others.
54
55As of this release, new functionality in pseudo is enabled to ignore these
56directory trees (controlled using a new :term:`PSEUDO_IGNORE_PATHS` variable)
57resulting in a cleaner database with less chance of "stray" mismatches if files
58are modified outside pseudo context. It also should reduce some overhead from
59pseudo as the interprocess round trip to the server is avoided.
60
61There is a possible complication where some existing recipe may break, for
62example, a recipe was found to be writing to ``${B}/install`` for
63``make install`` in ``do_install`` and since ``${B}`` is listed as not to be tracked,
64there were errors trying to ``chown root`` for files in this location. Another
65example was the ``tcl`` recipe where the source directory ``S`` is set to a
66subdirectory of the source tree but files were written out to the directory
67structure above that subdirectory. For these types of cases in your own recipes,
68extend ``PSEUDO_IGNORE_PATHS`` to cover additional paths that pseudo should not
69be monitoring.
70
71In addition, pseudo's behaviour on mismatches has now been changed - rather
72than doing what turns out to be a rather dangerous "fixup" if it sees a file
73with a different path but the same inode as another file it has previously seen,
74pseudo will throw an ``abort()`` and direct you to a :yocto_wiki:`wiki page </Pseudo_Abort>`
75that explains how to deal with this.
76
77
78.. _migration-3.2-multilib-mlprefix:
79
80``MLPREFIX`` now required for multilib when runtime dependencies conditionally added
81------------------------------------------------------------------------------------
82
83In order to solve some previously intractable problems with runtime
84dependencies and multilib, a change was made that now requires the :term:`MLPREFIX`
85value to be explicitly prepended to package names being added as
86dependencies (e.g. in :term:`RDEPENDS` and :term:`RRECOMMENDS` values)
87where the dependency is conditionally added.
88
89If you have anonymous python or in-line python conditionally adding
90dependencies in your custom recipes, and you intend for those recipes to
91work with multilib, then you will need to ensure that ``${MLPREFIX}``
92is prefixed on the package names in the dependencies, for example
93(from the ``glibc`` recipe)::
94
95 RRECOMMENDS_${PN} = "${@bb.utils.contains('DISTRO_FEATURES', 'ldconfig', '${MLPREFIX}ldconfig', '', d)}"
96
97This also applies when conditionally adding packages to :term:`PACKAGES` where
98those packages have dependencies, for example (from the ``alsa-plugins`` recipe)::
99
100 PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}"
101 ...
102 RDEPENDS_${PN}-pulseaudio-conf += "\
103 ${MLPREFIX}libasound-module-conf-pulse \
104 ${MLPREFIX}libasound-module-ctl-pulse \
105 ${MLPREFIX}libasound-module-pcm-pulse \
106 "
107
108
109.. _migration-3.2-packagegroup-core-device-devel:
110
111packagegroup-core-device-devel no longer included in images built for qemu* machines
112------------------------------------------------------------------------------------
113
114``packagegroup-core-device-devel`` was previously added automatically to
115images built for ``qemu*`` machines, however the purpose of the group and what
116it should contain is no longer clear, and in general, adding userspace
117development items to images is best done at the image/class level; thus this
118packagegroup was removed.
119
120This packagegroup previously pulled in the following:
121
122- ``distcc-config``
123- ``nfs-export-root``
124- ``bash``
125- ``binutils-symlinks``
126
127If you still need any of these in your image built for a ``qemu*`` machine
128then you will add them explicitly to :term:`IMAGE_INSTALL` or another
129appropriate place in the dependency chain for your image (if you have not
130already done so).
131
132
133.. _migration-3.2-dhcp:
134
135DHCP server/client replaced
136---------------------------
137
138The ``dhcp`` software package has become unmaintained and thus has been
139functionally replaced by ``dhcpcd`` (client) and ``kea`` (server). You will
140need to replace references to the recipe/package names as appropriate - most
141commonly, at the package level ``dhcp-client`` should be replaced by
142``dhcpcd`` and ``dhcp-server`` should be replaced by ``kea``. If you have any
143custom configuration files for these they will need to be adapted - refer to
144the upstream documentation for ``dhcpcd`` and ``kea`` for further details.
145
146
147.. _migration-3.2-packaging-changes:
148
149Packaging changes
150-----------------
151
152- ``python3``: the ``urllib`` python package has now moved into the core package, as it is used more commonly than just netclient (e.g. email, xml, mimetypes, pydoc). In addition, the ``pathlib`` module is now also part of the core package.
153
154- ``iptables``: ``iptables-apply`` and ``ip6tables-apply`` have been split out to their own package to avoid a bash dependency in the main ``iptables`` package
155
156
157.. _migration-3.2-package-qa-checks:
158
159Package QA check changes
160------------------------
161
162Previously, the following package QA checks triggered warnings, however they can
163be indicators of genuine underlying problems and are therefore now treated as
164errors:
165
166- :ref:`already-stripped <qa-check-already-stripped>`
167- :ref:`compile-host-path <qa-check-compile-host-path>`
168- :ref:`installed-vs-shipped <qa-check-installed-vs-shipped>`
169- :ref:`ldflags <qa-check-ldflags>`
170- :ref:`pn-overrides <qa-check-pn-overrides>`
171- :ref:`rpaths <qa-check-rpaths>`
172- :ref:`staticdev <qa-check-staticdev>`
173- :ref:`unknown-configure-option <qa-check-unknown-configure-option>`
174- :ref:`useless-rpaths <qa-check-useless-rpaths>`
175
176In addition, the following new checks were added and default to triggering an error:
177
178- :ref:`shebang-size <qa-check-shebang-size>`: Check for shebang (#!) lines longer than 128 characters, which can give an error at runtime depending on the operating system.
179
180- :ref:`unhandled-features-check <qa-check-unhandled-features-check>`: Check if any of the variables supported by the :ref:`features_check <ref-classes-features_check>` class is set while not inheriting the class itself.
181
182- :ref:`missing-update-alternatives <qa-check-missing-update-alternatives>`: Check if the recipe sets the :term:`ALTERNATIVE` variable for any of its packages, and does not inherit the :ref:`update-alternatives <ref-classes-update-alternatives>` class.
183
184- A trailing slash or duplicated slashes in the value of :term:`S` or :term:`B` will now trigger a warning so that they can be removed and path comparisons can be more reliable - remove any instances of these in your recipes if the warning is displayed.
185
186
187.. _migration-3.2-src-uri-file-globbing:
188
189Globbing no longer supported in ``file://`` entries in ``SRC_URI``
190------------------------------------------------------------------
191
192Globbing (``*`` and ``?`` wildcards) in ``file://`` URLs within :term:`SRC_URI`
193did not properly support file checksums, thus changes to the source files
194would not always change the do_fetch task checksum, and consequently would
195not ensure that the changed files would be incorporated in subsequent builds.
196
197Unfortunately it is not practical to make globbing work generically here, so
198the decision was taken to remove support for globs in ``file://`` URLs.
199If you have any usage of these in your recipes, then you will now need to
200either add each of the files that you expect to match explicitly, or
201alternatively if you still need files to be pulled in dynamically, put the
202files into a subdirectory and reference that instead.
203
204
205.. _migration-3.2-deploydir-clean:
206
207deploy class now cleans ``DEPLOYDIR`` before ``do_deploy``
208----------------------------------------------------------
209
210``do_deploy`` as implemented in the :ref:`deploy <ref-classes-deploy>` class now cleans up ${:term:`DEPLOYDIR`} before running, just as ``do_install`` cleans up ${:term:`D`} before running. This reduces the risk of ``DEPLOYDIR`` being accidentally contaminated by files from previous runs, possibly even with different config, in case of incremental builds.
211
212Most recipes and classes that inherit the ``deploy`` class or interact with ``do_deploy`` are unlikely to be affected by this unless they add ``prefuncs`` to ``do_deploy`` *which also* put files into ``${DEPLOYDIR}`` - these should be refactored to use ``do_deploy_prepend`` instead.
213
214
215.. _migration-3.2-nativesdk-sdk-provides-dummy:
216
217Custom SDK / SDK-style recipes need to include ``nativesdk-sdk-provides-dummy``
218-------------------------------------------------------------------------------
219
220All ``nativesdk`` packages require ``/bin/sh`` due to their postinstall scriptlets, thus this package has to be dummy-provided within the SDK and ``nativesdk-sdk-provides-dummy`` now does this. If you have a custom SDK recipe (or your own SDK-style recipe similar to e.g. ``buildtools-tarball``), you will need to ensure ``nativesdk-sdk-provides-dummy`` or an equivalent is included in :term:`TOOLCHAIN_HOST_TASK`.
221
222
223``ld.so.conf`` now moved back to main ``glibc`` package
224-------------------------------------------------------
225
226There are cases where one doesn't want ``ldconfig`` on target (e.g. for
227read-only root filesystems, it's rather pointless), yet one still
228needs ``/etc/ld.so.conf`` to be present at image build time:
229
230When some recipe installs libraries to a non-standard location, and
231therefore installs in a file in ``/etc/ld.so.conf.d/foo.conf``, we
232need ``/etc/ld.so.conf`` containing::
233
234 include /etc/ld.so.conf.d/*.conf
235
236in order to get those other locations picked up.
237
238Thus ``/etc/ld.so.conf`` is now in the main ``glibc`` package so that
239there's always an ``ld.so.conf`` present when the build-time ``ldconfig``
240runs towards the end of image construction.
241
242The ``ld.so.conf`` and ``ld.so.conf.d/*.conf`` files do not take up
243significant space (at least not compared to the ~700kB ``ldconfig`` binary), and they
244might be needed in case ``ldconfig`` is installable, so they are left
245in place after the image is built. Technically it would be possible to
246remove them if desired, though it would not be trivial if you still
247wanted the build-time ldconfig to function (:term:`ROOTFS_POSTPROCESS_COMMAND`
248will not work as ``ldconfig`` is run after the functions referred to
249by that variable).
250
251
252.. _migration-3.2-virgl:
253
254Host DRI drivers now used for GL support within ``runqemu``
255-----------------------------------------------------------
256
257``runqemu`` now uses the mesa-native libraries everywhere virgl is used
258(i.e. when ``gl``, ``gl-es`` or ``egl-headless`` options are specified),
259but instructs them to load DRI drivers from the host. Unfortunately this
260may not work well with proprietary graphics drivers such as those from
261Nvidia; if you are using such drivers then you may need to switch to an
262alternative (such as Nouveau in the case of Nvidia hardware) or avoid
263using the GL options.
264
265
266.. _migration-3.2-initramfs-suffix:
267
268initramfs images now use a blank suffix
269---------------------------------------
270
271The reference initramfs images (``core-image-minimal-initramfs``,
272``core-image-tiny-initramfs`` and ``core-image-testmaster-initramfs``) now
273set an empty string for :term:`IMAGE_NAME_SUFFIX`, which otherwise defaults
274to ``".rootfs"``. These images aren't root filesystems and thus the rootfs
275label didn't make sense. If you are looking for the output files generated
276by these image recipes directly then you will need to adapt to the new
277naming without the ``.rootfs`` part.
278
279
280.. _migration-3.2-image-artifact-names:
281
282Image artifact name variables now centralised in image-artifact-names class
283---------------------------------------------------------------------------
284
285The defaults for the following image artifact name variables have been moved
286from bitbake.conf to a new ``image-artifact-names`` class:
287
288- :term:`IMAGE_BASENAME`
289- :term:`IMAGE_LINK_NAME`
290- :term:`IMAGE_NAME`
291- :term:`IMAGE_NAME_SUFFIX`
292- :term:`IMAGE_VERSION_SUFFIX`
293
294Image-related classes now inherit this class, and typically these variables
295are only referenced within image recipes so those will be unaffected by this
296change. However if you have references to these variables in either a recipe
297that is not an image or a class that is enabled globally, then those will
298now need to be changed to ``inherit image-artifact-names``.
299
300
301.. _migration-3.2-misc:
302
303Miscellaneous changes
304---------------------
305
306- Support for the long-deprecated ``PACKAGE_GROUP`` variable has now been removed - replace any remaining instances with :term:`FEATURE_PACKAGES`.
307- The ``FILESPATHPKG`` variable, having been previously deprecated, has now been removed. Replace any remaining references with appropriate use of :term:`FILESEXTRAPATHS`.
308- Erroneous use of ``inherit +=`` (instead of ``INHERIT +=``) in a configuration file now triggers an error instead of silently being ignored.
309- ptest support has been removed from the ``kbd`` recipe, as upstream has moved to autotest which is difficult to work with in a cross-compilation environment.
310- ``oe.utils.is_machine_specific()`` and ``oe.utils.machine_paths()`` have been removed as their utility was questionable. In the unlikely event that you have references to these in your own code, then the code will need to be reworked.
311- The ``i2ctransfer`` module is now disabled by default when building ``busybox`` in order to be consistent with disabling the other i2c tools there. If you do wish the i2ctransfer module to be built in BusyBox then add ``CONFIG_I2CTRANSFER=y`` to your custom BusyBox configuration.
312- In the ``Upstream-Status`` header convention for patches, ``Accepted`` has been replaced with ``Backport`` as these almost always mean the same thing i.e. the patch is already upstream and may need to be removed in a future recipe upgrade. If you are adding these headers to your own patches then use ``Backport`` to indicate that the patch has been sent upstream.
313- The ``tune-supersparc.inc`` tune file has been removed as it does not appear to be widely used and no longer works.
diff --git a/documentation/ref-manual/migration-3.3.rst b/documentation/ref-manual/migration-3.3.rst
deleted file mode 100644
index 4fb51a39dc..0000000000
--- a/documentation/ref-manual/migration-3.3.rst
+++ /dev/null
@@ -1,168 +0,0 @@
1Moving to the Yocto Project 3.3 Release (hardknott)
2===================================================
3
4This section provides migration information for moving to the Yocto
5Project 3.3 Release (codename "hardknott") from the prior release.
6
7
8.. _migration-3.3-minimum-system-requirements:
9
10Minimum system requirements
11---------------------------
12
13You will now need at least Python 3.6 installed on your build host. Most recent
14distributions provide this, but should you be building on a distribution that
15does not have it, you can use the ``buildtools-tarball`` (easily installable
16using ``scripts/install-buildtools``) - see
17:ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`
18for details.
19
20
21.. _migration-3.3-removed-recipes:
22
23Removed recipes
24---------------
25
26The following recipes have been removed:
27
28- ``go-dep``: obsolete with the advent of go modules
29- ``gst-validate``: replaced by ``gst-devtools``
30- ``linux-yocto``: removed 5.8 version recipes (5.4 / 5.10 still provided)
31- ``vulkan-demos``: replaced by ``vulkan-samples``
32
33
34.. _migration-3.3-common-license-only-versions:
35
36Single version common license file naming
37-----------------------------------------
38
39Some license files in ``meta/files/common-licenses`` have been renamed to match
40current SPDX naming conventions:
41
42- AGPL-3.0 -> AGPL-3.0-only
43- GPL-1.0 -> GPL-1.0-only
44- GPL-2.0 -> GPL-2.0-only
45- GPL-3.0 -> GPL-3.0-only
46- LGPL-2.0 -> LGPL-2.0-only
47- LGPL-2.1 -> LGPL-2.1-only
48- LGPL-3.0 -> LGPL-3.0-only
49
50Additionally, corresponding "-or-later" suffixed files have been added e.g.
51``GPL-2.0-or-later``.
52
53It is not required that you change :term:`LICENSE` values as there are mappings
54from the original names in place; however, in rare cases where you have a recipe
55which sets :term:`LIC_FILES_CHKSUM` to point to file(s) in
56``meta/files/common-licenses`` (which in any case is not recommended) you will
57need to update those.
58
59
60.. _migration-3.3-python3targetconfig:
61
62New ``python3targetconfig`` class
63---------------------------------
64
65A new :ref:`python3targetconfig <ref-classes-python3targetconfig>` class has been
66created for situations where you would previously have inherited the
67``python3native`` class but need access to target configuration data (such as
68correct installation directories). Recipes where this situation applies should
69be changed to inherit ``python3targetconfig`` instead of ``python3native``. This
70also adds a dependency on target ``python3``, so it should only be used where
71appropriate in order to avoid unnecessarily lengthening builds.
72
73Some example recipes where this change has been made: ``gpgme``, ``libcap-ng``,
74``python3-pycairo``.
75
76
77.. _migration-3.3-distutils-path:
78
79``setup.py`` path for python modules
80------------------------------------
81
82In a Python module, sometimes ``setup.py`` can be buried deep in the
83source tree. Previously this was handled in recipes by setting :term:`S` to
84point to the subdirectory within the source where ``setup.py`` is located.
85However with the recent :ref:`pseudo <overview-manual/concepts:fakeroot and pseudo>`
86changes, some Python modules make changes to files beneath ``${S}``, for
87example::
88
89 S = "${WORKDIR}/git/python/pythonmodule"
90
91then in ``setup.py`` it works with source code in a relative fashion, such
92as ``../../src``. This causes pseudo to abort as it isn't able to track
93the paths properly. This release introduces a new :term:`DISTUTILS_SETUP_PATH`
94variable so that recipes can specify it explicitly, for example::
95
96 S = "${WORKDIR}/git"
97 DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule"
98
99Recipes that inherit from :ref:`distutils3 <ref-classes-distutils3>` (or
100:ref:`setuptools3 <ref-classes-setuptools3>` which itself inherits
101:ref:`distutils3 <ref-classes-distutils3>`) that also set :term:`S` to
102point to a Python module within a subdirectory in the aforementioned
103manner should be changed to set :term:`DISTUTILS_SETUP_PATH` instead.
104
105
106.. _migration-3.3-bitbake:
107
108BitBake changes
109---------------
110
111- BitBake is now configured to use a default ``umask`` of ``022`` for all tasks
112 (specified via a new :term:`BB_DEFAULT_UMASK` variable). If needed, ``umask`` can
113 still be set on a per-task basis via the ``umask`` varflag on the task
114 function, but that is unlikely to be necessary in most cases.
115
116- If a version specified in :term:`PREFERRED_VERSION` is not available this
117 will now trigger a warning instead of just a note, making such issues more
118 visible.
119
120
121.. _migration-3.3-packaging:
122
123Packaging changes
124-----------------
125
126The following packaging changes have been made; in all cases the main package
127still depends upon the split out packages so you should not need to do anything
128unless you want to take advantage of the improved granularity:
129
130- ``dbus``: ``-common`` and ``-tools`` split out
131- ``iproute2``: split ``ip`` binary to its own package
132- ``net-tools``: split ``mii-tool`` into its own package
133- ``procps``: split ``ps`` and ``sysctl`` into their own packages
134- ``rpm``: split build and extra functionality into separate packages
135- ``sudo``: split ``sudo`` binary into ``sudo-sudo`` and libs into ``sudo-lib``
136- ``systemtap``: examples, python scripts and runtime material split out
137- ``util-linux``: ``libuuid`` has been split out to its own
138 ``util-linux-libuuid`` recipe (and corresponding packages) to avoid circular
139 dependencies if ``libgcrypt`` support is enabled in ``util-linux``.
140 (``util-linux`` depends upon ``util-linux-libuuid``.)
141
142
143.. _migration-3.3-misc:
144
145Miscellaneous changes
146---------------------
147
148- The default poky :term:`DISTRO_VERSION` value now uses the core metadata's
149 git hash (i.e. :term:`METADATA_REVISION`) rather than the date (i.e.
150 :term:`DATE`) to reduce one small source of non-reproducibility. You can
151 of course specify your own :term:`DISTRO_VERSION` value as desired
152 (particularly if you create your own custom distro configuration).
153- ``adwaita-icon-theme`` version 3.34.3 has been added back, and is selected
154 as the default via :term:`PREFERRED_VERSION` in
155 ``meta/conf/distro/include/default-versions.inc`` due to newer versions
156 not working well with ``librsvg`` 2.40. ``librsvg`` is not practically
157 upgradeable at the moment as it has been ported to Rust, and Rust is not
158 (yet) in OE-Core, but this will change in a future release.
159- ``ffmpeg`` is now configured to disable GPL-licensed portions by default
160 to make it harder to accidentally violate the GPL. To explicitly enable GPL
161 licensed portions, add ``gpl`` to :term:`PACKAGECONFIG` for ``ffmpeg``
162 using a bbappend (or use ``PACKAGECONFIG_append_pn-ffmpeg = " gpl"`` in
163 your configuration.)
164- ``connman`` is now set to conflict with ``systemd-networkd`` as they
165 overlap functionally and may interfere with each other at runtime.
166- Canonical SPDX license names are now used in image license manifests in
167 order to avoid aliases of the same license from showing up together (e.g.
168 ``GPLv2`` and ``GPL-2.0``)
diff --git a/documentation/ref-manual/migration-general.rst b/documentation/ref-manual/migration-general.rst
deleted file mode 100644
index 182482ec43..0000000000
--- a/documentation/ref-manual/migration-general.rst
+++ /dev/null
@@ -1,54 +0,0 @@
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
deleted file mode 100644
index a01d4ee143..0000000000
--- a/documentation/ref-manual/migration.rst
+++ /dev/null
@@ -1,32 +0,0 @@
1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3******************************************
4Migrating to a Newer Yocto Project Release
5******************************************
6
7This chapter provides information you can use to migrate work to a newer
8Yocto Project release. You can find the same information in the release
9notes for a given release.
10
11.. toctree::
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
30 migration-3.2
31 migration-3.3
32
diff --git a/documentation/ref-manual/release-process.rst b/documentation/ref-manual/release-process.rst
index 935a2e39bb..64adc1e389 100644
--- a/documentation/ref-manual/release-process.rst
+++ b/documentation/ref-manual/release-process.rst
@@ -62,8 +62,10 @@ codename are likely to be compatible and thus work together.
62 62
63Releases are given a nominal release version as well but the codename is 63Releases are given a nominal release version as well but the codename is
64used in repositories for this reason. You can find information on Yocto 64used in repositories for this reason. You can find information on Yocto
65Project releases and codenames at 65Project releases and codenames at :yocto_wiki:`/Releases`.
66:yocto_wiki:`/Releases`. 66
67Our :doc:`/migration-guides/index` detail how to migrate from one release of
68the Yocto Project to the next.
67 69
68Stable Release Process 70Stable Release Process
69====================== 71======================