diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2021-06-10 11:26:21 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2021-06-14 22:45:33 +0100 |
commit | 5f978a6ccacf9f7f9475207c5a2a1af1dc4c3d00 (patch) | |
tree | fa7ba7ced9e17426b72e07c50288163a5d8ba901 /documentation/ref-manual/migration-1.5.rst | |
parent | dae1e986a0608d899f67f1ae62389d350824235f (diff) | |
download | poky-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/migration-1.5.rst')
-rw-r--r-- | documentation/ref-manual/migration-1.5.rst | 353 |
1 files changed, 0 insertions, 353 deletions
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 @@ | |||
1 | Moving to the Yocto Project 1.5 Release (dora) | ||
2 | ============================================== | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.5 Release (codename "dora") from the prior release. | ||
6 | |||
7 | .. _migration-1.5-host-dependency-changes: | ||
8 | |||
9 | Host Dependency Changes | ||
10 | ----------------------- | ||
11 | |||
12 | The OpenEmbedded build system now has some additional requirements on | ||
13 | the 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 | |||
24 | If the Linux distribution you are using on your build host does not | ||
25 | provide packages for these, you can install and use the Buildtools | ||
26 | tarball, which provides an SDK-like environment containing them. | ||
27 | |||
28 | For more information on this requirement, see the | ||
29 | ":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`" | ||
30 | section. | ||
31 | |||
32 | .. _migration-1.5-atom-pc-bsp: | ||
33 | |||
34 | ``atom-pc`` Board Support Package (BSP) | ||
35 | --------------------------------------- | ||
36 | |||
37 | The ``atom-pc`` hardware reference BSP has been replaced by a | ||
38 | ``genericx86`` BSP. This BSP is not necessarily guaranteed to work on | ||
39 | all 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 | |||
49 | BitBake | ||
50 | ------- | ||
51 | |||
52 | The 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 | |||
78 | QA Warnings | ||
79 | ----------- | ||
80 | |||
81 | The 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 | |||
109 | Directory Layout Changes | ||
110 | ------------------------ | ||
111 | |||
112 | The 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 | |||
142 | Shortened Git ``SRCREV`` Values | ||
143 | ------------------------------- | ||
144 | |||
145 | BitBake will now shorten revisions from Git repositories from the normal | ||
146 | 40 characters down to 10 characters within :term:`SRCPV` | ||
147 | for improved usability in path and file names. This change should be | ||
148 | safe within contexts where these revisions are used because the chances | ||
149 | of spatially close collisions is very low. Distant collisions are not a | ||
150 | major issue in the way the values are used. | ||
151 | |||
152 | .. _migration-1.5-image-features: | ||
153 | |||
154 | ``IMAGE_FEATURES`` | ||
155 | ------------------ | ||
156 | |||
157 | The 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 | |||
182 | The ``/run`` directory from the Filesystem Hierarchy Standard 3.0 has | ||
183 | been introduced. You can find some of the implications for this change | ||
184 | :oe_git:`here </openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873>`. | ||
185 | The change also means that recipes that install files to ``/var/run`` | ||
186 | must 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 | |||
191 | Removal of Package Manager Database Within Image Recipes | ||
192 | -------------------------------------------------------- | ||
193 | |||
194 | The image ``core-image-minimal`` no longer adds | ||
195 | ``remove_packaging_data_files`` to | ||
196 | :term:`ROOTFS_POSTPROCESS_COMMAND`. | ||
197 | This addition is now handled automatically when "package-management" is | ||
198 | not in :term:`IMAGE_FEATURES`. If you have custom | ||
199 | image recipes that make this addition, you should remove the lines, as | ||
200 | they are not needed and might interfere with correct operation of | ||
201 | postinstall scripts. | ||
202 | |||
203 | .. _migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time: | ||
204 | |||
205 | Images Now Rebuild Only on Changes Instead of Every Time | ||
206 | -------------------------------------------------------- | ||
207 | |||
208 | The :ref:`ref-tasks-rootfs` and other related image | ||
209 | construction tasks are no longer marked as "nostamp". Consequently, they | ||
210 | will only be re-executed when their inputs have changed. Previous | ||
211 | versions of the OpenEmbedded build system always rebuilt the image when | ||
212 | requested rather when necessary. | ||
213 | |||
214 | .. _migration-1.5-task-recipes: | ||
215 | |||
216 | Task Recipes | ||
217 | ------------ | ||
218 | |||
219 | The previously deprecated ``task.bbclass`` has now been dropped. For | ||
220 | recipes that previously inherited from this class, you should rename | ||
221 | them from ``task-*`` to ``packagegroup-*`` and inherit packagegroup | ||
222 | instead. | ||
223 | |||
224 | For more information, see the | ||
225 | ":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section. | ||
226 | |||
227 | .. _migration-1.5-busybox: | ||
228 | |||
229 | BusyBox | ||
230 | ------- | ||
231 | |||
232 | By default, we now split BusyBox into two binaries: one that is suid | ||
233 | root for those components that need it, and another for the rest of the | ||
234 | components. Splitting BusyBox allows for optimization that eliminates | ||
235 | the ``tinylogin`` recipe as recommended by upstream. You can disable | ||
236 | this split by setting | ||
237 | :term:`BUSYBOX_SPLIT_SUID` to "0". | ||
238 | |||
239 | .. _migration-1.5-automated-image-testing: | ||
240 | |||
241 | Automated Image Testing | ||
242 | ----------------------- | ||
243 | |||
244 | A new automated image testing framework has been added through the | ||
245 | :ref:`testimage.bbclass <ref-classes-testimage*>` class. This | ||
246 | framework replaces the older ``imagetest-qemu`` framework. | ||
247 | |||
248 | You can learn more about performing automated image tests in the | ||
249 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | ||
250 | section in the Yocto Project Development Tasks Manual. | ||
251 | |||
252 | .. _migration-1.5-build-history: | ||
253 | |||
254 | Build History | ||
255 | ------------- | ||
256 | |||
257 | Following 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 | |||
271 | For more information on Build History, see the | ||
272 | ":ref:`dev-manual/common-tasks:maintaining build output quality`" | ||
273 | section in the Yocto Project Development Tasks Manual. | ||
274 | |||
275 | .. _migration-1.5-udev: | ||
276 | |||
277 | ``udev`` | ||
278 | -------- | ||
279 | |||
280 | Following 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 | |||
293 | Removed 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 | |||
321 | Other Changes | ||
322 | ------------- | ||
323 | |||
324 | Following 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 | |||