summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/ref-manual/migration.xml527
1 files changed, 525 insertions, 2 deletions
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index f7b22d7cb6..b0e8eae1e0 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -3057,8 +3057,7 @@
3057 and the 3057 and the
3058 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>. 3058 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>.
3059 For information on these SDKs and how to build and use them, see the 3059 For information on these SDKs and how to build and use them, see the
3060 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> 3060 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
3061 manual.
3062 <note> 3061 <note>
3063 The Yocto Project Eclipse IDE Plug-in is still supported and 3062 The Yocto Project Eclipse IDE Plug-in is still supported and
3064 is not affected by this change. 3063 is not affected by this change.
@@ -4722,6 +4721,530 @@ id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>.
4722 </para> 4721 </para>
4723 </section> 4722 </section>
4724</section> 4723</section>
4724
4725<section id='moving-to-the-yocto-project-2.4-release'>
4726 <title>Moving to the Yocto Project 2.4 Release</title>
4727
4728 <para>
4729 This section provides migration information for moving to the
4730 Yocto Project 2.4 Release from the prior release.
4731 </para>
4732
4733 <section id='migration-2.4-memory-resident-mode'>
4734 <title>Memory Resident Mode</title>
4735
4736 <para>
4737 A persistent mode is now available in BitBake's default operation,
4738 replacing its previous "memory resident mode" (i.e.
4739 <filename>oe-init-build-env-memres</filename>).
4740 Now you only need to set
4741 <filename>BB_SERVER_TIMEOUT</filename> to a timeout
4742 (in seconds) and BitBake's server stays resident for that
4743 amount of time between invocations.
4744 The <filename>oe-init-build-env-memres</filename> script has been
4745 removed which means a separate environment setup script is no longer
4746 needed.
4747 </para>
4748 </section>
4749
4750 <section id='migration-2.4-packaging-changes'>
4751 <title>Packaging Changes</title>
4752
4753 <para>
4754 This section provides information about packaging changes that have
4755 ocurred:
4756 <itemizedlist>
4757 <listitem><para>
4758 <emphasis><filename>python3</filename> Changes:</emphasis>
4759 <itemizedlist>
4760 <listitem><para>
4761 The main "python3" package now brings in all of the
4762 standard Python 3 distributions rather than a subset.
4763 This behavior matches what is expected based on
4764 traditional Linux distributions.
4765 If you wish to install a subset of Python 3, specify
4766 <filename>python-core</filename> plus one or more of
4767 the individual packages that are still produced.
4768 </para></listitem>
4769 <listitem><para>
4770 <emphasis><filename>python3</filename>:</emphasis>
4771 The <filename>bz2.py</filename>,
4772 <filename>lzma.py</filename>, and
4773 <filename>_compression.py</filename> scripts have
4774 been moved from the
4775 <filename>python3-misc</filename> package to
4776 the <filename>python3-compression</filename> package.
4777 </para></listitem>
4778 </itemizedlist>
4779 </para></listitem>
4780 <listitem><para>
4781 <emphasis><filename>binutils</filename>:</emphasis>
4782 The <filename>libbfd</filename> package is now packaged in
4783 a separate "libbfd" package.
4784 This packaging saves space when certain tools
4785 (e.g. <filename>perf</filename>) are installed.
4786 In such cases, the tools only need
4787 <filename>libbfd</filename> rather than all the packages in
4788 <filename>binutils</filename>.
4789 </para></listitem>
4790 <listitem><para>
4791 <emphasis><filename>util-linux</filename> Changes:</emphasis>
4792 <itemizedlist>
4793 <listitem><para>
4794 The <filename>su</filename> package is now packaged
4795 in a separate "util-linux-su" package, which is only
4796 built when "pam" is listed in the
4797 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
4798 variable.
4799 <filename>util-linux</filename> should not be
4800 installed unless it is needed because
4801 <filename>su</filename> is normally provided through
4802 the shadow file format.
4803 The main <filename>util-linux</filename> package has
4804 runtime dependencies (i.e.
4805 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
4806 on the <filename>util-linux</filename> package when
4807 "pam" is in
4808 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
4809 </para></listitem>
4810 <listitem><para>
4811 The <filename>switch_root</filename> package is now
4812 packaged in a separate "util-linux-switch-root"
4813 package for small initramfs images that do not need
4814 the whole <filename>util-linux</filename> package or
4815 the busybox binary, which are both much larger than
4816 <filename>switch_root</filename>.
4817 The main <filename>util-linux</filename> package has
4818 a recommended runtime dependency (i.e.
4819 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
4820 on the <filename>switch_root</filename> package.
4821 </para></listitem>
4822 <listitem><para>
4823 The <filename>ionice</filename> package is now
4824 packaged in a separate "util-linux-ionice" package.
4825 The main <filename>util-linux</filename> package has
4826 a recommended runtime dependency (i.e.
4827 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
4828 on the <filename>ionice</filename> package.
4829 </para></listitem>
4830 </itemizedlist>
4831 </para></listitem>
4832 <listitem><para>
4833 <emphasis><filename>initscripts</filename>:</emphasis>
4834 The <filename>sushell</filename> package is now packaged in
4835 a separate "initscripts-sushell" package.
4836 This packaging change allows systems to pull
4837 <filename>sushell</filename> in when
4838 <filename>selinux</filename> is enabled.
4839 The change also eliminates needing to pull in the entire
4840 <filename>initscripts</filename> package.
4841 The main <filename>initscripts</filename> package has a
4842 runtime dependency (i.e.
4843 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
4844 on the <filename>sushell</filename> package when
4845 "selinux" is in
4846 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
4847 </para></listitem>
4848 <listitem><para>
4849 <emphasis><filename>glib-2.0</filename>:</emphasis>
4850 The <filename>glib-2.0</filename> package now has a
4851 recommended runtime dependency (i.e.
4852 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
4853 on the
4854 <filename>shared-mime-info</filename> package, since large
4855 portions of GIO are not useful without the MIME database.
4856 You can remove the dependency by using the
4857 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
4858 variable if <filename>shared-mime-info</filename> is too
4859 large and is not required.
4860 </para></listitem>
4861 <listitem><para>
4862 <emphasis><filename>Go Standard Runtime</filename>:</emphasis>
4863 The Go standard runtime has been split out from the main
4864 <filename>go</filename> recipe into a separate
4865 <filename>go-runtime</filename> recipe.
4866 </para></listitem>
4867 </itemizedlist>
4868 </para>
4869 </section>
4870
4871 <section id='migration-2.4-removed-recipes'>
4872 <title>Removed Recipes</title>
4873
4874 <para>
4875 The following recipes have been removed:
4876 <itemizedlist>
4877 <listitem><para>
4878 <emphasis><filename>acpitests</filename>:</emphasis>
4879 This recipe is not maintained.
4880 </para></listitem>
4881 <listitem><para>
4882 <emphasis><filename>autogen-native</filename>:</emphasis>
4883 No longer required by Grub, <filename>oe-core</filename>, or
4884 <filename>meta-oe</filename>.
4885 </para></listitem>
4886 <listitem><para>
4887 <emphasis><filename>bdwgc</filename>:</emphasis>
4888 Nothing in OpenEmbedded-Core requires this recipe.
4889 It has moved to <filename>meta-oe</filename>
4890 </para></listitem>
4891 <listitem><para>
4892 <emphasis><filename>byacc</filename>:</emphasis>
4893 This recipe was only needed by rpm 5.x and has moved to
4894 <filename>meta-oe</filename>.
4895 </para></listitem>
4896 <listitem><para>
4897 <emphasis><filename>gcc (5.4)</filename>:</emphasis>
4898 The 5.4 series dropped the recipe in favor of 6.3 / 7.2.
4899 </para></listitem>
4900 <listitem><para>
4901 <emphasis><filename>gnome-common</filename>:</emphasis>
4902 Deprecated upstream and no longer needed.
4903 </para></listitem>
4904 <listitem><para>
4905 <emphasis><filename>go-bootstrap-native</filename>:</emphasis>
4906 Go 1.9 does its own bootstrapping so this recipe has been
4907 removed.
4908 </para></listitem>
4909 <listitem><para>
4910 <emphasis><filename>guile</filename>:</emphasis>
4911 This recipe was only needed by
4912 <filename>autogen-native</filename> and
4913 <filename>remake</filename>.
4914 It is no longer needed by either of these programs.
4915 </para></listitem>
4916 <listitem><para>
4917 <emphasis><filename>libclass-isa-perl</filename>:</emphasis>
4918 This recipe was previously needed for LSB 4, which no longer
4919 requires the recipe.
4920 </para></listitem>
4921 <listitem><para>
4922 <emphasis><filename>libdumpvalue-perl</filename>:</emphasis>
4923 This recipe was previously needed for LSB 4, which no longer
4924 requires the recipe.
4925 </para></listitem>
4926 <listitem><para>
4927 <emphasis><filename>libenv-perl</filename>:</emphasis>
4928 This recipe was previously needed for LSB 4, which no longer
4929 requires the recipe.
4930 </para></listitem>
4931 <listitem><para>
4932 <emphasis><filename>libfile-checktree-perl</filename>:</emphasis>
4933 This recipe was previously needed for LSB 4, which no longer
4934 requires the recipe.
4935 </para></listitem>
4936 <listitem><para>
4937 <emphasis><filename>libi18n-collate-perl</filename>:</emphasis>
4938 This recipe was previously needed for LSB 4, which no longer
4939 requires the recipe.
4940 </para></listitem>
4941 <listitem><para>
4942 <emphasis><filename>libiconv</filename>:</emphasis>
4943 This recipe was only needed for <filename>uclibc</filename>,
4944 which was removed in the previous release.
4945 <filename>glibc</filename> and <filename>musl</filename>
4946 have their own implementations.
4947 <filename>meta-mingw</filename> still needs
4948 <filename>libiconv</filename>, so it has
4949 been moved to <filename>meta-mingw</filename>.
4950 </para></listitem>
4951 <listitem><para>
4952 <emphasis><filename>libpng12</filename>:</emphasis>
4953 This recipe was previously needed for LSB. The current
4954 <filename>libpng</filename> is 1.6.x.
4955 </para></listitem>
4956 <listitem><para>
4957 <emphasis><filename>libpod-plainer-perl</filename>:</emphasis>
4958 This recipe was previously needed for LSB 4, which no longer
4959 requires the recipe.
4960 </para></listitem>
4961 <listitem><para>
4962 <emphasis><filename>linux-yocto (4.1)</filename>:</emphasis>
4963 This recipe was removed in favor of 4.4, 4.9, 4.10 and 4.12.
4964 </para></listitem>
4965 <listitem><para>
4966 <emphasis><filename>mailx</filename>:</emphasis>
4967 This recipe was previously only needed for LSB
4968 compatibility, and upstream is defunct.
4969 </para></listitem>
4970 <listitem><para>
4971 <emphasis><filename>mesa (git version only)</filename>:</emphasis>
4972 This recipe is stale with respect to the release version.
4973 </para></listitem>
4974 <listitem><para>
4975 <emphasis><filename>ofono (git version only)</filename>:</emphasis>
4976 This recipe is stale with respect to the release version.
4977 </para></listitem>
4978 <listitem><para>
4979 <emphasis><filename>portmap</filename>:</emphasis>
4980 This recipe is obsolete and is superseded by
4981 <filename>rpcbind</filename>.
4982 </para></listitem>
4983 <listitem><para>
4984 <emphasis><filename>python3-pygpgme</filename>:</emphasis>
4985 This recipe is old and unmaintained. It was previously
4986 required by <filename>dnf</filename>, which has switched
4987 to official <filename>gpgme</filename> Python bindings.
4988 </para></listitem>
4989 <listitem><para>
4990 <emphasis><filename>python-async</filename>:</emphasis>
4991 This recipe has been removed in favor of the Python 3
4992 version.
4993 </para></listitem>
4994 <listitem><para>
4995 <emphasis><filename>python-gitdb</filename>:</emphasis>
4996 This recipe has been removed in favor of the Python 3
4997 version.
4998 </para></listitem>
4999 <listitem><para>
5000 <emphasis><filename>python-git</filename>:</emphasis>
5001 This recipe was removed in favor of the Python 3
5002 version.
5003 </para></listitem>
5004 <listitem><para>
5005 <emphasis><filename>python-mako</filename>:</emphasis>
5006 This recipe was removed in favor of the Python 3
5007 version.
5008 </para></listitem>
5009 <listitem><para>
5010 <emphasis><filename>python-pexpect</filename>:</emphasis>
5011 This recipe was removed in favor of the Python 3 version.
5012 </para></listitem>
5013 <listitem><para>
5014 <emphasis><filename>python-ptyprocess</filename>:</emphasis>
5015 This recipe was removed in favor of Python the 3 version.
5016 </para></listitem>
5017 <listitem><para>
5018 <emphasis><filename>python-pycurl</filename>:</emphasis>
5019 Nothing is using this recipe in OpenEmbedded-Core
5020 (i.e. <filename>meta-oe</filename>).
5021 </para></listitem>
5022 <listitem><para>
5023 <emphasis><filename>python-six</filename>:</emphasis>
5024 This recipe was removed in favor of the Python 3 version.
5025 </para></listitem>
5026 <listitem><para>
5027 <emphasis><filename>python-smmap</filename>:</emphasis>
5028 This recipe was removed in favor of the Python 3 version.
5029 </para></listitem>
5030 <listitem><para>
5031 <emphasis><filename>remake</filename>:</emphasis>
5032 Using <filename>remake</filename> as the provider of
5033 <filename>virtual/make</filename> is broken.
5034 Consequently, this recipe is not needed in OpenEmbedded-Core.
5035 </para></listitem>
5036 </itemizedlist>
5037 </para>
5038 </section>
5039
5040 <section id='migration-2.4-kernel-device-tree-move'>
5041 <title>Kernel Device Tree Move</title>
5042
5043 <para>
5044 Kernel Device Tree support is easy to enable in a kernel
5045 recipe.
5046 The Device Tree code has moved to a
5047 <filename>kernel-devicetree</filename> class.
5048 Functionality is automatically enabled for any recipe that inherits
5049 the
5050 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
5051 class and sets the
5052 <link linkend='var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></link>
5053 variable.
5054 The previous mechanism for doing this,
5055 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>,
5056 is still available to avoid breakage, but triggers a
5057 deprecation warning.
5058 Future releases of the Yocto Project will remove
5059 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>.
5060 It is advisable to remove any <filename>require</filename>
5061 statements that request
5062 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>
5063 from any custom kernel recipes you might have.
5064 This will avoid breakage in post 2.4 releases.
5065 </para>
5066 </section>
5067
5068 <section id='migration-2.4-package-qa-changes'>
5069 <title>Package QA Changes</title>
5070
5071 <para>
5072 The following package QA changes took place:
5073 <itemizedlist>
5074 <listitem><para>
5075 The "unsafe-references-in-scripts" QA check has been
5076 removed.
5077 Previously, this check ensured
5078 that the backslash character (i.e.
5079 <filename>/</filename>) and <filename>/usr</filename>
5080 could be on different filesystems and that
5081 <filename>/usr</filename> is no longer actively supported.
5082 </para></listitem>
5083 <listitem><para>
5084 If you refer to <filename>${COREBASE}/LICENSE</filename>
5085 within
5086 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
5087 you receive a warning because this file is a description of
5088 the license for OE-Core.
5089 Use <filename>${COMMON_LICENSE_DIR}/MIT</filename>
5090 if your recipe is MIT-licensed and you cannot use the
5091 preferred method of referring to a file within the source
5092 tree.
5093 </para></listitem>
5094 </itemizedlist>
5095 </para>
5096 </section>
5097
5098 <section id='migration-2.4-readme-changes'>
5099 <title><filename>README</filename> File Changes</title>
5100
5101 <para>
5102 The following are changes to <filename>README</filename> files:
5103 <itemizedlist>
5104 <listitem><para>
5105 The main Poky <filename>README</filename> file has been
5106 moved to the <filename>meta-poky</filename> layer and
5107 has been renamed <filename>README.poky</filename>.
5108 A symlink has been created so that references to the old
5109 location work.
5110 </para></listitem>
5111 <listitem><para>
5112 The <filename>README.hardware</filename> file has been moved
5113 to <filename>meta-yocto-bsp</filename>.
5114 A symlink has been created so that references to the old
5115 location work.
5116 </para></listitem>
5117 <listitem><para>
5118 A <filename>README.qemu</filename> file has been created
5119 with coverage of the <filename>qemu*</filename> machines.
5120 </para></listitem>
5121 </itemizedlist>
5122 </para>
5123 </section>
5124
5125 <section id='migration-2.4-miscellaneous-changes'>
5126 <title>Miscellaneous Changes</title>
5127
5128 <para>
5129 The following are additional changes:
5130 <itemizedlist>
5131 <listitem><para>
5132 The <filename>ROOTFS_PKGMANAGE_BOOTSTRAP</filename>
5133 variable and any references to it have been removed.
5134 You should remove this variable from any custom recipes.
5135 </para></listitem>
5136 <listitem><para>
5137 The <filename>meta-yocto</filename> directory has been
5138 removed.
5139 <note>
5140 In the Yocto Project 2.1 release
5141 <filename>meta-yocto</filename> was renamed to
5142 <filename>meta-poky</filename> and the
5143 <filename>meta-yocto</filename> subdirectory remained
5144 to avoid breaking existing configurations.
5145 </note>
5146 </para></listitem>
5147 <listitem><para>
5148 The <filename>maintainers.inc</filename> file, which tracks
5149 maintainers by listing a primary person responsible for each
5150 recipe in OE-Core, has been moved from
5151 <filename>meta-poky</filename> to OE-Core (i.e. from
5152 <filename>meta-poky/conf/distro/include</filename> to
5153 <filename>meta/conf/distro/include</filename>).
5154 </para></listitem>
5155 <listitem><para>
5156 The
5157 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
5158 class now makes a single commit per build rather than one
5159 commit per subdirectory in the repository.
5160 This behavior assumes the commits are enabled with
5161 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
5162 = "1", which is typical.
5163 Previously, the <filename>buildhistory</filename> class made
5164 one commit per subdirectory in the repository in order to
5165 make it easier to see the changes for a particular
5166 subdirectory.
5167 Now Git can filter these changes itself when viewed.
5168 To view a particular change, specify that subdirectory as
5169 the last parameter on the <filename>git show</filename>
5170 or <filename>git diff</filename> commands.
5171 </para></listitem>
5172 <listitem><para>
5173 The <filename>x86-base.inc</filename> file, which is
5174 included by all x86-based machine configurations, now sets
5175 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
5176 using <filename>?=</filename> to "live" rather than
5177 appending with <filename>+=</filename>.
5178 This change makes the default easier to override.
5179 </para></listitem>
5180 <listitem><para>
5181 BitBake fires multiple "BuildStarted" events when
5182 <filename>multiconfig</filename> is enabled.
5183 This is limited to one per configuration.
5184 For more information, see the
5185 "<ulink url='&YOCTO_DOCS_BB_URL;#events'>Events</ulink>"
5186 in the BitBake User Manual.
5187 </para></listitem>
5188 <listitem><para>
5189 By default, the <filename>security_flags.inc</filename> file
5190 sets a <filename>GCCPIE</filename> variable with an option
5191 to enable Position Independent Executables (PIE) within
5192 <filename>gcc</filename>.
5193 Enabling PIE in the GNU C Compiler (GCC), makes Return
5194 Oriented Programming (ROP) attacks much more difficult to
5195 execute.
5196 </para></listitem>
5197 <listitem><para>
5198 OE-Core now provides a
5199 <filename>bitbake-layers</filename> plugin that implements
5200 a "create-layer" subcommand.
5201 The implementation of this subcommand has resulted in the
5202 <filename>yocto-layer</filename> script being deprecated and
5203 will likely be removed in the next Yocto Project release.
5204 </para></listitem>
5205 <listitem><para>
5206 The <filename>vmdk</filename>, <filename>vdi</filename>,
5207 and <filename>qcow2</filename> image file types are now
5208 used in conjunction with the "wic" image type through
5209 <filename>CONVERSION_CMD</filename>.
5210 Consequently, the equivalent image types are now
5211 <filename>wic.vmdk</filename>, <filename>wic.vdi</filename>,
5212 and <filename>wic.qcow2</filename>, respectively.
5213 </para></listitem>
5214 <listitem><para>
5215 <filename>do_image_&lt;type&gt;[depends]</filename> has
5216 replaced <filename>IMAGE_DEPENDS_&lt;type&gt;</filename>.
5217 If you have your own classes that implement custom image
5218 types, then you need to update them.
5219 </para></listitem>
5220 <listitem><para>
5221 OpenSSL 1.1 has been introduced.
5222 However, the default is still 1.0.x through the
5223 <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
5224 variable.
5225 This change is due to the remaining compatibility issues
5226 with other software.
5227 The
5228 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
5229 variable includes "openssl10" as a marker for recipes that
5230 still depend on OpenSSL 1.0.
5231 </para></listitem>
5232 <listitem><para>
5233 To ensure consistent behavior, BitBake's "-r" and "-R"
5234 options (i.e. prefile and postfile), which are used to
5235 <filename>read</filename> or <filename>post-read</filename>
5236 additional configuration files from the command line, now
5237 only affect the current BitBake command.
5238 Before this change these options would "stick" for
5239 future executions.
5240 <note>
5241 BitBake server changes necessitated this change.
5242 </note>
5243 </para></listitem>
5244 </itemizedlist>
5245 </para>
5246 </section>
5247</section>
4725</chapter> 5248</chapter>
4726<!-- 5249<!--
4727vim: expandtab tw=80 ts=4 5250vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-14 12:59:08 +0000