diff options
author | Nicolas Dechesne <nicolas.dechesne@linaro.org> | 2020-11-20 20:17:33 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2021-01-04 10:55:00 +0000 |
commit | fa0cb4d34b1073f215fa3c680f2316208739d53d (patch) | |
tree | ba89c1f4289fd6456af4409a6a19caf6548dfb9c /documentation/ref-manual/migration-2.4.rst | |
parent | a038e58f3cd82c56102444bdc5ac76c9f1550a0d (diff) | |
download | poky-fa0cb4d34b1073f215fa3c680f2316208739d53d.tar.gz |
sphinx: import docs
The Yocto Project docs was migrated from Docbook to Sphinx in YP
3.2. This 3.1 is an LTS release, and since 3.1 docs are 'close to'
the docs in 3.2, we agreed to backport sphinx docs onto 3.1.
This first patch brings all changes done in 3.2 until:
7f64574f7 README: include detailed information about sphinx
There are other changes after this commit, but they will be
selectively backported in individual patches.
This patch was generated with the following command:
git cherry-pick -n \
$(git log --reverse --oneline \
ac352ad7f95db7eeacb53c2778caa31800bd7c26..7f64574f7 \
| cut -f1 -d' ')
The following commits were applies in the dunfell docs, but not in
master, so they were first reverted (and squashed into this change). A
commit will reintroduce the content from these patches in the Sphinx
files in a followup patch.
069c27574 Documenation: Prepared for the 3.1.1 release
bd140f0f9 Documentation: Add 3.1.1 version updates missing from previous commit
17cc71a8f Documenation: Prepared for the 3.1.2 release
1a69e2c02 Documenation: Prepared for the 3.1.3 release
8910ac1c7 Documenation: Prepared for the 3.1.4 release
(From yocto-docs rev: c25fe058b88b893b0d146f3ed27320b47cdec236)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/migration-2.4.rst')
-rw-r--r-- | documentation/ref-manual/migration-2.4.rst | 327 |
1 files changed, 327 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration-2.4.rst b/documentation/ref-manual/migration-2.4.rst new file mode 100644 index 0000000000..260b3204b6 --- /dev/null +++ b/documentation/ref-manual/migration-2.4.rst | |||
@@ -0,0 +1,327 @@ | |||
1 | Moving to the Yocto Project 2.4 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.4 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.4-memory-resident-mode: | ||
8 | |||
9 | Memory Resident Mode | ||
10 | -------------------- | ||
11 | |||
12 | A persistent mode is now available in BitBake's default operation, | ||
13 | replacing 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 | ||
16 | seconds) and BitBake's server stays resident for that amount of time | ||
17 | between invocations. The ``oe-init-build-env-memres`` script has been | ||
18 | removed since a separate environment setup script is no longer needed. | ||
19 | |||
20 | .. _migration-2.4-packaging-changes: | ||
21 | |||
22 | Packaging Changes | ||
23 | ----------------- | ||
24 | |||
25 | This section provides information about packaging changes that have | ||
26 | occurred: | ||
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 | |||
89 | Removed Recipes | ||
90 | --------------- | ||
91 | |||
92 | The 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 | |||
194 | Kernel Device Tree Move | ||
195 | ----------------------- | ||
196 | |||
197 | Kernel Device Tree support is now easier to enable in a kernel recipe. | ||
198 | The Device Tree code has moved to a | ||
199 | :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class. | ||
200 | Functionality 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 | ||
203 | previous mechanism for doing this, | ||
204 | ``meta/recipes-kernel/linux/linux-dtb.inc``, is still available to avoid | ||
205 | breakage, but triggers a deprecation warning. Future releases of the | ||
206 | Yocto Project will remove ``meta/recipes-kernel/linux/linux-dtb.inc``. | ||
207 | It is advisable to remove any ``require`` statements that request | ||
208 | ``meta/recipes-kernel/linux/linux-dtb.inc`` from any custom kernel | ||
209 | recipes you might have. This will avoid breakage in post 2.4 releases. | ||
210 | |||
211 | .. _migration-2.4-package-qa-changes: | ||
212 | |||
213 | Package QA Changes | ||
214 | ------------------ | ||
215 | |||
216 | The 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 | |||
232 | The 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 | |||
246 | Miscellaneous Changes | ||
247 | --------------------- | ||
248 | |||
249 | The 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 | |||