summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/migration.xml201
1 files changed, 201 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 03efc7be2f..9422b5a277 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -7095,6 +7095,207 @@ id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>.
7095 </section> 7095 </section>
7096</section> 7096</section>
7097 7097
7098
7099<section id='moving-to-the-yocto-project-3.1-release'>
7100 <title>Moving to the Yocto Project 3.1 Release</title>
7101
7102 <para>
7103 This section provides migration information for moving to the
7104 Yocto Project 3.1 Release from the prior release.
7105 </para>
7106
7107 <section id='migration-3.1-minimum-system-requirements'>
7108 <title>Minimum system requirements</title>
7109
7110 <para>
7111 The following versions / requirements of build host components have been updated:
7112 <itemizedlist>
7113 <listitem><para>gcc 5.0</para></listitem>
7114 <listitem><para>python 3.5</para></listitem>
7115 <listitem><para>tar 1.28</para></listitem>
7116 <listitem><para><filename>rpcgen</filename> is now required on the host (part of the <filename>libc-dev-bin</filename> package on Ubuntu, Debian and related distributions, and the <filename>glibc</filename> package on RPM-based distributions).</para></listitem>
7117 </itemizedlist>
7118
7119 Additionally, the <filename>makeinfo</filename> and <filename>pod2man</filename>
7120 tools are <emphasis>no longer</emphasis> required on the host.
7121 </para>
7122 </section>
7123
7124 <section id='migration-3.1-mpc8315e-rdb-removed'>
7125 <title>mpc8315e-rdb machine removed</title>
7126
7127 <para>
7128 The MPC8315E-RDB machine is old/obsolete and unobtainable, thus given the maintenance burden
7129 the <filename>mpc8315e-rdb</filename> machine configuration that supported it has been removed
7130 in this release. The removal does leave a gap in official PowerPC reference hardware
7131 support; this may change in future if a suitable machine with accompanying support resources
7132 is found.
7133 </para>
7134 </section>
7135
7136 <section id='migration-3.1-python-2-removed'>
7137 <title>Python 2 removed</title>
7138
7139 <para>
7140 Due to the expiration of upstream support in January 2020, support for Python 2 has now been removed; it is recommended that you use Python 3 instead. If absolutely needed there is a meta-python2 community layer containing Python 2, related classes and various Python 2-based modules, however it should not be considered as supported.
7141 </para>
7142 </section>
7143
7144 <section id='migration-3.1-reproducible-builds'>
7145 <title>Reproducible builds now enabled by default</title>
7146
7147 <para>
7148 In order to avoid unnecessary differences in output files (aiding binary reproducibility), the Poky distribution configuration (<filename><link linkend='var-DISTRO'>DISTRO</link> = "poky"</filename>) now inherits the <filename>reproducible_build</filename> class by default.
7149 </para>
7150 </section>
7151
7152 <section id='migration-3.1-ptest-feature-impact'>
7153 <title>Impact of ptest feature is now more significant</title>
7154
7155 <para>
7156 The Poky distribution configuration (<filename><link linkend='var-DISTRO'>DISTRO</link> = "poky"</filename>) enables ptests by default to enable runtime testing of various components. In this release, a dependency needed to be added that has resulted in a significant increase in the number of components that will be built just when building a simple image such as core-image-minimal. If you do not need runtime tests enabled for core components, then it is recommended that you remove "ptest" from <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> to save a significant amount of build time e.g. by adding the following in your configuration:
7157
7158 <literallayout class='monospaced'>
7159 DISTRO_FEATURES_remove = "ptest"
7160 </literallayout>
7161 </para>
7162 </section>
7163
7164 <section id='migration-3.1-removed-recipes'>
7165 <title>Removed recipes</title>
7166
7167 <para>
7168 The following recipes have been removed:
7169
7170 <itemizedlist>
7171 <listitem><para><filename>chkconfig</filename>: obsolete</para></listitem>
7172 <listitem><para><filename>console-tools</filename>: obsolete</para></listitem>
7173 <listitem><para><filename>enchant</filename>: replaced by <filename>enchant2</filename></para></listitem>
7174 <listitem><para><filename>foomatic-filters</filename>: obsolete</para></listitem>
7175 <listitem><para><filename>libidn</filename>: no longer needed, moved to meta-oe</para></listitem>
7176 <listitem><para><filename>libmodulemd</filename>: replaced by <filename>libmodulemd-v1</filename></para></listitem>
7177 <listitem><para><filename>linux-yocto</filename>: drop 4.19, 5.2 version recipes (5.4 now provided)</para></listitem>
7178 <listitem><para><filename>nspr</filename>: no longer needed, moved to meta-oe</para></listitem>
7179 <listitem><para><filename>nss</filename>: no longer needed, moved to meta-oe</para></listitem>
7180 <listitem><para><filename>python</filename>: Python 2 removed (Python 3 preferred)</para></listitem>
7181 <listitem><para><filename>python-setuptools</filename>: Python 2 version removed (python3-setuptools preferred)</para></listitem>
7182 <listitem><para><filename>sysprof</filename>: no longer needed, moved to meta-oe</para></listitem>
7183 <listitem><para><filename>texi2html</filename>: obsolete</para></listitem>
7184 <listitem><para><filename>u-boot-fw-utils</filename>: functionally replaced by <filename>libubootenv</filename></para></listitem>
7185 </itemizedlist>
7186 </para>
7187 </section>
7188
7189 <section id='migration-3.1-features-check'>
7190 <title>features_check class replaces distro_features_check</title>
7191
7192 <para>
7193 The <filename>distro_features_check</filename> class has had its functionality expanded, now supporting <filename>ANY_OF_MACHINE_FEATURES</filename>, <filename>REQUIRED_MACHINE_FEATURES</filename>, <filename>CONFLICT_MACHINE_FEATURES</filename>, <filename>ANY_OF_COMBINED_FEATURES</filename>, <filename>REQUIRED_COMBINED_FEATURES</filename>, <filename>CONFLICT_COMBINED_FEATURES</filename>. As a result the class has now been renamed to <filename>features_check</filename>; the <filename>distro_features_check</filename> class still exists but generates a warning and redirects to the new class. In preparation for a future removal of the old class it is recommended that you update recipes currently inheriting <filename>distro_features_check</filename> to inherit <filename>features_check</filename> instead.
7194 </para>
7195 </section>
7196
7197 <section id='migration-3.1-removed-classes'>
7198 <title>Removed classes</title>
7199
7200 <para>
7201 The following classes have been removed:
7202
7203 <itemizedlist>
7204 <listitem><para><filename>distutils-base</filename>: moved to meta-python2</para></listitem>
7205 <listitem><para><filename>distutils</filename>: moved to meta-python2</para></listitem>
7206 <listitem><para><filename>libc-common</filename>: merged into the glibc recipe as nothing else used it.</para></listitem>
7207 <listitem><para><filename>python-dir</filename>: moved to meta-python2</para></listitem>
7208 <listitem><para><filename>pythonnative</filename>: moved to meta-python2</para></listitem>
7209 <listitem><para><filename>setuptools</filename>: moved to meta-python2</para></listitem>
7210 <listitem><para><filename>tinderclient</filename>: dropped as it was obsolete.</para></listitem>
7211 </itemizedlist>
7212 </para>
7213 </section>
7214
7215 <section id='migration-3.1-src-uri-checksums'>
7216 <title>SRC_URI checksum behaviour</title>
7217
7218 <para>
7219 Previously, recipes by tradition included both SHA256 and MD5 checksums for remotely fetched files in <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>, even though only one is actually mandated. However, the MD5 checksum does not add much given its inherent weakness; thus when a checksum fails only the SHA256 sum will now be printed. The md5sum will still be verified if it is specified.
7220 </para>
7221 </section>
7222
7223
7224 <section id='migration-3.1-npm'>
7225 <title>npm fetcher changes</title>
7226
7227 <para>
7228 The npm fetcher has been completely reworked in this release. The npm fetcher now only fetches the package source itself and no longer the dependencies; there is now also an npmsw fetcher which explicitly fetches the shrinkwrap file and the dependencies. This removes the slightly awkward <filename>NPM_LOCKDOWN</filename> and <filename>NPM_SHRINKWRAP</filename> variables which pointed to local files; the lockdown file is no longer needed at all. Additionally, the package name in <filename>npm://</filename> entries in <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> is now specified using a <filename>package</filename> parameter instead of the earlier <filename>name</filename> which overlapped with the generic <filename>name</filename> parameter. All recipes using the npm fetcher will need to be changed as a result.
7229 </para>
7230 <para>
7231 An example of the new scheme:
7232 <literallayout class='monospaced'>
7233SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \
7234 npmsw://${THISDIR}/npm-shrinkwrap.json"
7235 </literallayout>
7236 Another example where the sources are fetched from git rather than an npm repository:
7237 <literallayout class='monospaced'>
7238SRC_URI = "git://github.com/foo/bar.git;protocol=https \
7239 npmsw://${THISDIR}/npm-shrinkwrap.json"
7240 </literallayout>
7241 </para>
7242 <para>
7243 devtool and recipetool have also been updated to match with the npm fetcher changes. Other than producing working and more complete recipes for npm sources, there is also a minor change to the command line for devtool: the <filename>--fetch-dev</filename> option has been renamed to <filename>--npm-dev</filename> as it is npm-specific.
7244 </para>
7245 </section>
7246
7247
7248 <section id='migration-3.1-packaging-changes'>
7249 <title>Packaging changes</title>
7250
7251 <para>
7252 <itemizedlist>
7253 <listitem><para><filename>intltool</filename> has been removed from <filename>packagegroup-core-sdk</filename> as it is rarely needed to build modern software - gettext can do most of the things it used to be needed for. <filename>intltool</filename> has also been removed from <filename>packagegroup-core-self-hosted</filename> as it is not needed to for standard builds.</para></listitem>
7254 <listitem><para>git: <filename>git-am</filename>, <filename>git-difftool</filename>, <filename>git-submodule</filename>, and <filename>git-request-pull</filename> are no longer perl-based, so are now installed with the main <filename>git</filename> package instead of within <filename>git-perltools</filename>.</para></listitem>
7255 <listitem><para>The <filename>ldconfig</filename> binary built as part of glibc has now been moved to its own <filename>ldconfig</filename> package (note no <filename>glibc-</filename> prefix). This package is in the <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> of the main <filename>glibc</filename> package if <filename>ldconfig</filename> is present in <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.</para></listitem>
7256 <listitem><para><filename>libevent</filename> now splits each shared library into its own package (as Debian does). Since these are shared libraries and will be pulled in through the normal shared library dependency handling, there should be no impact to existing configurations other than less unnecessary libraries being installed in some cases.</para></listitem>
7257 <listitem><para>linux-firmware now has a new package for <filename>bcm4366c</filename> and includes available NVRAM config files into the <filename>bcm43340</filename>, <filename>bcm43362</filename>, <filename>bcm43430</filename> and <filename>bcm4356-pcie</filename> packages.</para></listitem>
7258 <listitem><para><filename>harfbuzz</filename> now splits the new <filename>libharfbuzz-subset.so</filename> library into its own package to reduce the main package size in cases where <filename>libharfbuzz-subset.so</filename> is not needed.</para></listitem>
7259 </itemizedlist>
7260 </para>
7261 </section>
7262
7263 <section id='migration-3.1-package-qa-warnings'>
7264 <title>Additional warnings</title>
7265
7266 <para>
7267 Warnings will now be shown at <filename>do_package_qa</filename> time in the following circumstances:
7268
7269 <itemizedlist>
7270 <listitem><para>A recipe installs <filename>.desktop</filename> files containing <filename>MimeType</filename> keys but does not inherit the new <filename>mime-xdg</filename> class</para></listitem>
7271 <listitem><para>A recipe installs <filename>.xml</filename> files into <filename>${datadir}/mime/packages</filename> but does not inherit the <filename>mime</filename> class</para></listitem>
7272 </itemizedlist>
7273 </para>
7274 </section>
7275
7276 <section id='migration-3.1-x86-live-wic'>
7277 <title><filename>wic</filename> image type now used instead of <filename>live</filename> by default for x86</title>
7278
7279 <para>
7280 <filename>conf/machine/include/x86-base.inc</filename> (inherited by most x86 machine configurations) now specifies <filename>wic</filename> instead of <filename>live</filename> by default in <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>. The <filename>live</filename> image type will likely be removed in a future release so it is recommended that you use <filename>wic</filename> instead.
7281 </para>
7282 </section>
7283
7284 <section id='migration-3.1-misc'>
7285 <title>Miscellaneous changes</title>
7286
7287 <para>
7288 <itemizedlist>
7289 <listitem><para>The undocumented <filename>SRC_DISTRIBUTE_LICENSES</filename> variable has now been removed in favour of a new <filename>AVAILABLE_LICENSES</filename> variable which is dynamically set based upon license files found in <filename>${COMMON_LICENSE_DIR}</filename> and <filename>${LICENSE_PATH}</filename>.</para></listitem>
7290 <listitem><para>The tune definition for big-endian microblaze machines is now <filename>microblaze</filename> instead of <filename>microblazeeb</filename>.</para></listitem>
7291 <listitem><para><filename>newlib</filename> no longer has built-in syscalls. <filename>libgloss</filename> should then provide the syscalls, <filename>crt0.o</filename> and other functions that are no longer part of <filename>newlib</filename> itself. If you are using <filename>TCLIBC = "newlib"</filename> this now means that you must link applications with both <filename>newlib</filename> and <filename>libgloss</filename>, whereas before <filename>newlib</filename> would run in many configurations by itself.</para></listitem>
7292 </itemizedlist>
7293 </para>
7294 </section>
7295
7296</section>
7297
7298
7098</chapter> 7299</chapter>
7099<!-- 7300<!--
7100vim: expandtab tw=80 ts=4 7301vim: expandtab tw=80 ts=4