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-3.0.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-3.0.rst')
-rw-r--r-- | documentation/ref-manual/migration-3.0.rst | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration-3.0.rst b/documentation/ref-manual/migration-3.0.rst new file mode 100644 index 0000000000..e1305dfccf --- /dev/null +++ b/documentation/ref-manual/migration-3.0.rst | |||
@@ -0,0 +1,321 @@ | |||
1 | Moving to the Yocto Project 3.0 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 3.0 Release from the prior release. | ||
6 | |||
7 | .. _migration-3.0-init-system-selection: | ||
8 | |||
9 | Init System Selection | ||
10 | --------------------- | ||
11 | |||
12 | Changing the init system manager previously required setting a number of | ||
13 | different 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 | ||
16 | for four values: "none", "sysvinit", "systemd", and "mdev-busybox". The | ||
17 | default value, "none", for ``INIT_MANAGER`` should allow your current | ||
18 | settings to continue working. However, it is advisable to explicitly set | ||
19 | ``INIT_MANAGER``. | ||
20 | |||
21 | .. _migration-3.0-lsb-support-removed: | ||
22 | |||
23 | LSB Support Removed | ||
24 | ------------------- | ||
25 | |||
26 | Linux Standard Base (LSB) as a standard is not current, and is not well | ||
27 | suited for embedded applications. Support can be continued in a separate | ||
28 | layer if needed. However, presently LSB support has been removed from | ||
29 | the core. | ||
30 | |||
31 | As a result of this change, the ``poky-lsb`` derivative distribution | ||
32 | configuration that was also used for testing alternative configurations | ||
33 | has been replaced with a ``poky-altcfg`` distribution that has LSB parts | ||
34 | removed. | ||
35 | |||
36 | .. _migration-3.0-removed-recipes: | ||
37 | |||
38 | Removed Recipes | ||
39 | --------------- | ||
40 | |||
41 | The 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 | |||
106 | Packaging Changes | ||
107 | ----------------- | ||
108 | |||
109 | The 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 | |||
141 | CVE 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`` | ||
146 | class. The result uses NVD JSON data feeds rather than the deprecated | ||
147 | XML feeds that ``cve-check-tool`` was using, supports CVSSv3 scoring, | ||
148 | and makes other improvements. | ||
149 | |||
150 | Additionally, the ``CVE_CHECK_CVE_WHITELIST`` variable has been replaced | ||
151 | by ``CVE_CHECK_WHITELIST``. | ||
152 | |||
153 | .. _migration-3.0-bitbake-changes: | ||
154 | |||
155 | Bitbake Changes | ||
156 | --------------- | ||
157 | |||
158 | The following BitBake changes have occurred. | ||
159 | |||
160 | - ``addtask`` statements now properly validate dependent tasks. | ||
161 | Previously, an invalid task was silently ignored. With this change, | ||
162 | the invalid task generates a warning. | ||
163 | |||
164 | - Other invalid ``addtask`` and ``deltask`` usages now trigger these | ||
165 | warnings: "multiple target tasks arguments with addtask / deltask", | ||
166 | and "multiple before/after clauses". | ||
167 | |||
168 | - The "multiconfig" prefix is now shortened to "mc". "multiconfig" will | ||
169 | continue to work, however it may be removed in a future release. | ||
170 | |||
171 | - The ``bitbake -g`` command no longer generates a | ||
172 | ``recipe-depends.dot`` file as the contents (i.e. a reprocessed | ||
173 | version of ``task-depends.dot``) were confusing. | ||
174 | |||
175 | - The ``bb.build.FuncFailed`` exception, previously raised by | ||
176 | ``bb.build.exec_func()`` when certain other exceptions have occurred, | ||
177 | has been removed. The real underlying exceptions will be raised | ||
178 | instead. If you have calls to ``bb.build.exec_func()`` in custom | ||
179 | classes or ``tinfoil-using`` scripts, any references to | ||
180 | ``bb.build.FuncFailed`` should be cleaned up. | ||
181 | |||
182 | - Additionally, the ``bb.build.exec_func()`` no longer accepts the | ||
183 | "pythonexception" parameter. The function now always raises | ||
184 | exceptions. Remove this argument in any calls to | ||
185 | ``bb.build.exec_func()`` in custom classes or scripts. | ||
186 | |||
187 | - The | ||
188 | :term:`bitbake:BB_SETSCENE_VERIFY_FUNCTION2` | ||
189 | is no longer used. In the unlikely event that you have any references | ||
190 | to it, they should be removed. | ||
191 | |||
192 | - The ``RunQueueExecuteScenequeue`` and ``RunQueueExecuteTasks`` events | ||
193 | have been removed since setscene tasks are now executed as part of | ||
194 | the normal runqueue. Any event handling code in custom classes or | ||
195 | scripts that handles these two events need to be updated. | ||
196 | |||
197 | - The arguments passed to functions used with | ||
198 | :term:`bitbake:BB_HASHCHECK_FUNCTION` | ||
199 | have changed. If you are using your own custom hash check function, | ||
200 | see | ||
201 | http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725 | ||
202 | for details. | ||
203 | |||
204 | - Task specifications in ``BB_TASKDEPDATA`` and class implementations | ||
205 | used in signature generator classes now use "<fn>:<task>" everywhere | ||
206 | rather than the "." delimiter that was being used in some places. | ||
207 | This change makes it consistent with all areas in the code. Custom | ||
208 | signature generator classes and code that reads ``BB_TASKDEPDATA`` | ||
209 | need to be updated to use ':' as a separator rather than '.'. | ||
210 | |||
211 | .. _migration-3.0-sanity-checks: | ||
212 | |||
213 | Sanity Checks | ||
214 | ------------- | ||
215 | |||
216 | The following sanity check changes occurred. | ||
217 | |||
218 | - :term:`SRC_URI` is now checked for usage of two | ||
219 | problematic items: | ||
220 | |||
221 | - "${PN}" prefix/suffix use - Warnings always appear if ${PN} is | ||
222 | used. You must fix the issue regardless of whether multiconfig or | ||
223 | anything else that would cause prefixing/suffixing to happen. | ||
224 | |||
225 | - Github archive tarballs - these are not guaranteed to be stable. | ||
226 | Consequently, it is likely that the tarballs will be refreshed and | ||
227 | thus the SRC_URI checksums will fail to apply. It is recommended | ||
228 | that you fetch either an official release tarball or a specific | ||
229 | revision from the actual Git repository instead. | ||
230 | |||
231 | Either one of these items now trigger a warning by default. If you | ||
232 | wish to disable this check, remove ``src-uri-bad`` from | ||
233 | :term:`WARN_QA`. | ||
234 | |||
235 | - The ``file-rdeps`` runtime dependency check no longer expands | ||
236 | :term:`RDEPENDS` recursively as there is no mechanism | ||
237 | to ensure they can be fully computed, and thus races sometimes result | ||
238 | in errors either showing up or not. Thus, you might now see errors | ||
239 | for missing runtime dependencies that were previously satisfied | ||
240 | recursively. Here is an example: package A contains a shell script | ||
241 | starting with ``#!/bin/bash`` but has no dependency on bash. However, | ||
242 | package A depends on package B, which does depend on bash. You need | ||
243 | to add the missing dependency or dependencies to resolve the warning. | ||
244 | |||
245 | - Setting ``DEPENDS_${PN}`` anywhere (i.e. typically in a recipe) now | ||
246 | triggers an error. The error is triggered because | ||
247 | :term:`DEPENDS` is not a package-specific variable | ||
248 | unlike RDEPENDS. You should set ``DEPENDS`` instead. | ||
249 | |||
250 | - systemd currently does not work well with the musl C library because | ||
251 | only upstream officially supports linking the library with glibc. | ||
252 | Thus, a warning is shown when building systemd in conjunction with | ||
253 | musl. | ||
254 | |||
255 | .. _migration-3.0-miscellaneous-changes: | ||
256 | |||
257 | Miscellaneous Changes | ||
258 | --------------------- | ||
259 | |||
260 | The following miscellaneous changes have occurred. | ||
261 | |||
262 | - The ``gnome`` class has been removed because it now does very little. | ||
263 | You should update recipes that previously inherited this class to do | ||
264 | the following: inherit gnomebase gtk-icon-cache gconf mime | ||
265 | |||
266 | - The ``meta/recipes-kernel/linux/linux-dtb.inc`` file has been | ||
267 | removed. This file was previously deprecated in favor of setting | ||
268 | :term:`KERNEL_DEVICETREE` in any kernel | ||
269 | recipe and only produced a warning. Remove any ``include`` or | ||
270 | ``require`` statements pointing to this file. | ||
271 | |||
272 | - :term:`TARGET_CFLAGS`, | ||
273 | :term:`TARGET_CPPFLAGS`, | ||
274 | :term:`TARGET_CXXFLAGS`, and | ||
275 | :term:`TARGET_LDFLAGS` are no longer exported | ||
276 | to the external environment. This change did not require any changes | ||
277 | to core recipes, which is a good indicator that no changes will be | ||
278 | required. However, if for some reason the software being built by one | ||
279 | of your recipes is expecting these variables to be set, then building | ||
280 | the recipe will fail. In such cases, you must either export the | ||
281 | variable or variables in the recipe or change the scripts so that | ||
282 | exporting is not necessary. | ||
283 | |||
284 | - You must change the host distro identifier used in | ||
285 | :term:`NATIVELSBSTRING` to use all lowercase | ||
286 | characters even if it does not contain a version number. This change | ||
287 | is necessary only if you are not using ``uninative`` and | ||
288 | :term:`SANITY_TESTED_DISTROS`. | ||
289 | |||
290 | - In the ``base-files`` recipe, writing the hostname into | ||
291 | ``/etc/hosts`` and ``/etc/hostname`` is now done within the main | ||
292 | :ref:`ref-tasks-install` function rather than in the | ||
293 | ``do_install_basefilesissue`` function. The reason for the change is | ||
294 | because ``do_install_basefilesissue`` is more easily overridden | ||
295 | without having to duplicate the hostname functionality. If you have | ||
296 | done the latter (e.g. in a ``base-files`` bbappend), then you should | ||
297 | remove it from your customized ``do_install_basefilesissue`` | ||
298 | function. | ||
299 | |||
300 | - The ``wic --expand`` command now uses commas to separate "key:value" | ||
301 | pairs rather than hyphens. | ||
302 | |||
303 | .. note:: | ||
304 | |||
305 | The wic command-line help is not updated. | ||
306 | |||
307 | You must update any scripts or commands where you use | ||
308 | ``wic --expand`` with multiple "key:value" pairs. | ||
309 | |||
310 | - UEFI image variable settings have been moved from various places to a | ||
311 | central ``conf/image-uefi.conf``. This change should not influence | ||
312 | any existing configuration as the ``meta/conf/image-uefi.conf`` in | ||
313 | the core metadata sets defaults that can be overridden in the same | ||
314 | manner as before. | ||
315 | |||
316 | - ``conf/distro/include/world-broken.inc`` has been removed. For cases | ||
317 | where certain recipes need to be disabled when using the musl C | ||
318 | library, these recipes now have ``COMPATIBLE_HOST_libc-musl`` set | ||
319 | with a comment that explains why. | ||
320 | |||
321 | |||