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/migration-guides/migration-1.6.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/migration-guides/migration-1.6.rst')
-rw-r--r-- | documentation/migration-guides/migration-1.6.rst | 414 |
1 files changed, 414 insertions, 0 deletions
diff --git a/documentation/migration-guides/migration-1.6.rst b/documentation/migration-guides/migration-1.6.rst new file mode 100644 index 0000000000..1408e12c23 --- /dev/null +++ b/documentation/migration-guides/migration-1.6.rst | |||
@@ -0,0 +1,414 @@ | |||
1 | Release 1.6 (daisy) | ||
2 | =================== | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.6 Release (codename "daisy") from the prior release. | ||
6 | |||
7 | .. _migration-1.6-archiver-class: | ||
8 | |||
9 | ``archiver`` Class | ||
10 | ------------------ | ||
11 | |||
12 | The :ref:`archiver <ref-classes-archiver>` class has been rewritten | ||
13 | and its configuration has been simplified. For more details on the | ||
14 | source archiver, see the | ||
15 | ":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" | ||
16 | section in the Yocto Project Development Tasks Manual. | ||
17 | |||
18 | .. _migration-1.6-packaging-changes: | ||
19 | |||
20 | Packaging Changes | ||
21 | ----------------- | ||
22 | |||
23 | The following packaging changes have been made: | ||
24 | |||
25 | - The ``binutils`` recipe no longer produces a ``binutils-symlinks`` | ||
26 | package. ``update-alternatives`` is now used to handle the preferred | ||
27 | ``binutils`` variant on the target instead. | ||
28 | |||
29 | - The tc (traffic control) utilities have been split out of the main | ||
30 | ``iproute2`` package and put into the ``iproute2-tc`` package. | ||
31 | |||
32 | - The ``gtk-engines`` schemas have been moved to a dedicated | ||
33 | ``gtk-engines-schemas`` package. | ||
34 | |||
35 | - The ``armv7a`` with thumb package architecture suffix has changed. | ||
36 | The suffix for these packages with the thumb optimization enabled is | ||
37 | "t2" as it should be. Use of this suffix was not the case in the 1.5 | ||
38 | release. Architecture names will change within package feeds as a | ||
39 | result. | ||
40 | |||
41 | .. _migration-1.6-bitbake: | ||
42 | |||
43 | BitBake | ||
44 | ------- | ||
45 | |||
46 | The following changes have been made to :term:`BitBake`. | ||
47 | |||
48 | .. _migration-1.6-matching-branch-requirement-for-git-fetching: | ||
49 | |||
50 | Matching Branch Requirement for Git Fetching | ||
51 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
52 | |||
53 | When fetching source from a Git repository using | ||
54 | :term:`SRC_URI`, BitBake will now validate the | ||
55 | :term:`SRCREV` value against the branch. You can specify | ||
56 | the branch using the following form:: | ||
57 | |||
58 | SRC_URI = "git://server.name/repository;branch=branchname" | ||
59 | |||
60 | If you do not specify a branch, BitBake looks in the default "master" branch. | ||
61 | |||
62 | Alternatively, if you need to bypass this check (e.g. if you are | ||
63 | fetching a revision corresponding to a tag that is not on any branch), | ||
64 | you can add ";nobranch=1" to the end of the URL within ``SRC_URI``. | ||
65 | |||
66 | .. _migration-1.6-bitbake-deps: | ||
67 | |||
68 | Python Definition substitutions | ||
69 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
70 | |||
71 | BitBake had some previously deprecated Python definitions within its | ||
72 | ``bb`` module removed. You should use their sub-module counterparts | ||
73 | instead: | ||
74 | |||
75 | - ``bb.MalformedUrl``: Use ``bb.fetch.MalformedUrl``. | ||
76 | |||
77 | - ``bb.encodeurl``: Use ``bb.fetch.encodeurl``. | ||
78 | |||
79 | - ``bb.decodeurl``: Use ``bb.fetch.decodeurl`` | ||
80 | |||
81 | - ``bb.mkdirhier``: Use ``bb.utils.mkdirhier``. | ||
82 | |||
83 | - ``bb.movefile``: Use ``bb.utils.movefile``. | ||
84 | |||
85 | - ``bb.copyfile``: Use ``bb.utils.copyfile``. | ||
86 | |||
87 | - ``bb.which``: Use ``bb.utils.which``. | ||
88 | |||
89 | - ``bb.vercmp_string``: Use ``bb.utils.vercmp_string``. | ||
90 | |||
91 | - ``bb.vercmp``: Use ``bb.utils.vercmp``. | ||
92 | |||
93 | .. _migration-1.6-bitbake-fetcher: | ||
94 | |||
95 | SVK Fetcher | ||
96 | ~~~~~~~~~~~ | ||
97 | |||
98 | The SVK fetcher has been removed from BitBake. | ||
99 | |||
100 | .. _migration-1.6-bitbake-console-output: | ||
101 | |||
102 | Console Output Error Redirection | ||
103 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
104 | |||
105 | The BitBake console UI will now output errors to ``stderr`` instead of | ||
106 | ``stdout``. Consequently, if you are piping or redirecting the output of | ||
107 | ``bitbake`` to somewhere else, and you wish to retain the errors, you | ||
108 | will need to add ``2>&1`` (or something similar) to the end of your | ||
109 | ``bitbake`` command line. | ||
110 | |||
111 | .. _migration-1.6-task-taskname-overrides: | ||
112 | |||
113 | ``task-``\ taskname Overrides | ||
114 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
115 | |||
116 | ``task-``\ taskname overrides have been adjusted so that tasks whose | ||
117 | names contain underscores have the underscores replaced by hyphens for | ||
118 | the override so that they now function properly. For example, the task | ||
119 | override for :ref:`ref-tasks-populate_sdk` is | ||
120 | ``task-populate-sdk``. | ||
121 | |||
122 | .. _migration-1.6-variable-changes: | ||
123 | |||
124 | Changes to Variables | ||
125 | -------------------- | ||
126 | |||
127 | The following variables have changed. For information on the | ||
128 | OpenEmbedded build system variables, see the ":doc:`/ref-manual/variables`" Chapter. | ||
129 | |||
130 | .. _migration-1.6-variable-changes-TMPDIR: | ||
131 | |||
132 | ``TMPDIR`` | ||
133 | ~~~~~~~~~~ | ||
134 | |||
135 | :term:`TMPDIR` can no longer be on an NFS mount. NFS does | ||
136 | not offer full POSIX locking and inode consistency and can cause | ||
137 | unexpected issues if used to store ``TMPDIR``. | ||
138 | |||
139 | The check for this occurs on startup. If ``TMPDIR`` is detected on an | ||
140 | NFS mount, an error occurs. | ||
141 | |||
142 | .. _migration-1.6-variable-changes-PRINC: | ||
143 | |||
144 | ``PRINC`` | ||
145 | ~~~~~~~~~ | ||
146 | |||
147 | The ``PRINC`` variable has been deprecated and triggers a warning if | ||
148 | detected during a build. For :term:`PR` increments on changes, | ||
149 | use the PR service instead. You can find out more about this service in | ||
150 | the ":ref:`dev-manual/common-tasks:working with a pr service`" | ||
151 | section in the Yocto Project Development Tasks Manual. | ||
152 | |||
153 | .. _migration-1.6-variable-changes-IMAGE_TYPES: | ||
154 | |||
155 | ``IMAGE_TYPES`` | ||
156 | ~~~~~~~~~~~~~~~ | ||
157 | |||
158 | The "sum.jffs2" option for :term:`IMAGE_TYPES` has | ||
159 | been replaced by the "jffs2.sum" option, which fits the processing | ||
160 | order. | ||
161 | |||
162 | .. _migration-1.6-variable-changes-COPY_LIC_MANIFEST: | ||
163 | |||
164 | ``COPY_LIC_MANIFEST`` | ||
165 | ~~~~~~~~~~~~~~~~~~~~~ | ||
166 | |||
167 | The :term:`COPY_LIC_MANIFEST` variable must now | ||
168 | be set to "1" rather than any value in order to enable it. | ||
169 | |||
170 | .. _migration-1.6-variable-changes-COPY_LIC_DIRS: | ||
171 | |||
172 | ``COPY_LIC_DIRS`` | ||
173 | ~~~~~~~~~~~~~~~~~ | ||
174 | |||
175 | The :term:`COPY_LIC_DIRS` variable must now be set | ||
176 | to "1" rather than any value in order to enable it. | ||
177 | |||
178 | .. _migration-1.6-variable-changes-PACKAGE_GROUP: | ||
179 | |||
180 | ``PACKAGE_GROUP`` | ||
181 | ~~~~~~~~~~~~~~~~~ | ||
182 | |||
183 | The ``PACKAGE_GROUP`` variable has been renamed to | ||
184 | :term:`FEATURE_PACKAGES` to more accurately | ||
185 | reflect its purpose. You can still use ``PACKAGE_GROUP`` but the | ||
186 | OpenEmbedded build system produces a warning message when it encounters | ||
187 | the variable. | ||
188 | |||
189 | .. _migration-1.6-variable-changes-variable-entry-behavior: | ||
190 | |||
191 | Preprocess and Post Process Command Variable Behavior | ||
192 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
193 | |||
194 | The following variables now expect a semicolon separated list of | ||
195 | functions to call and not arbitrary shell commands: | ||
196 | |||
197 | - :term:`ROOTFS_PREPROCESS_COMMAND` | ||
198 | - :term:`ROOTFS_POSTPROCESS_COMMAND` | ||
199 | - :term:`SDK_POSTPROCESS_COMMAND` | ||
200 | - :term:`POPULATE_SDK_POST_TARGET_COMMAND` | ||
201 | - :term:`POPULATE_SDK_POST_HOST_COMMAND` | ||
202 | - :term:`IMAGE_POSTPROCESS_COMMAND` | ||
203 | - :term:`IMAGE_PREPROCESS_COMMAND` | ||
204 | - :term:`ROOTFS_POSTUNINSTALL_COMMAND` | ||
205 | - :term:`ROOTFS_POSTINSTALL_COMMAND` | ||
206 | |||
207 | For | ||
208 | migration purposes, you can simply wrap shell commands in a shell | ||
209 | function and then call the function. Here is an example:: | ||
210 | |||
211 | my_postprocess_function() { | ||
212 | echo "hello" > ${IMAGE_ROOTFS}/hello.txt | ||
213 | } | ||
214 | ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; " | ||
215 | |||
216 | .. _migration-1.6-package-test-ptest: | ||
217 | |||
218 | Package Test (ptest) | ||
219 | -------------------- | ||
220 | |||
221 | Package Tests (ptest) are built but not installed by default. For | ||
222 | information on using Package Tests, see the | ||
223 | ":ref:`dev-manual/common-tasks:testing packages with ptest`" | ||
224 | section in the Yocto Project Development Tasks Manual. For information on the | ||
225 | ``ptest`` class, see the ":ref:`ptest.bbclass <ref-classes-ptest>`" | ||
226 | section. | ||
227 | |||
228 | .. _migration-1.6-build-changes: | ||
229 | |||
230 | Build Changes | ||
231 | ------------- | ||
232 | |||
233 | Separate build and source directories have been enabled by default for | ||
234 | selected recipes where it is known to work (a whitelist) and for all | ||
235 | recipes that inherit the :ref:`cmake <ref-classes-cmake>` class. In | ||
236 | future releases the :ref:`autotools <ref-classes-autotools>` class | ||
237 | will enable a separate build directory by default as well. Recipes | ||
238 | building Autotools-based software that fails to build with a separate | ||
239 | build directory should be changed to inherit from the | ||
240 | :ref:`autotools-brokensep <ref-classes-autotools>` class instead of | ||
241 | the ``autotools`` or ``autotools_stage``\ classes. | ||
242 | |||
243 | .. _migration-1.6-building-qemu-native: | ||
244 | |||
245 | ``qemu-native`` | ||
246 | --------------- | ||
247 | |||
248 | ``qemu-native`` now builds without SDL-based graphical output support by | ||
249 | default. The following additional lines are needed in your | ||
250 | ``local.conf`` to enable it:: | ||
251 | |||
252 | PACKAGECONFIG_pn-qemu-native = "sdl" | ||
253 | ASSUME_PROVIDED += "libsdl-native" | ||
254 | |||
255 | .. note:: | ||
256 | |||
257 | The default ``local.conf`` contains these statements. Consequently, if you | ||
258 | are building a headless system and using a default ``local.conf`` | ||
259 | file, you will need comment these two lines out. | ||
260 | |||
261 | .. _migration-1.6-core-image-basic: | ||
262 | |||
263 | ``core-image-basic`` | ||
264 | -------------------- | ||
265 | |||
266 | ``core-image-basic`` has been renamed to ``core-image-full-cmdline``. | ||
267 | |||
268 | In addition to ``core-image-basic`` being renamed, | ||
269 | ``packagegroup-core-basic`` has been renamed to | ||
270 | ``packagegroup-core-full-cmdline`` to match. | ||
271 | |||
272 | .. _migration-1.6-licensing: | ||
273 | |||
274 | Licensing | ||
275 | --------- | ||
276 | |||
277 | The top-level ``LICENSE`` file has been changed to better describe the | ||
278 | license of the various components of :term:`OpenEmbedded-Core (OE-Core)`. However, | ||
279 | the licensing itself remains unchanged. | ||
280 | |||
281 | Normally, this change would not cause any side-effects. However, some | ||
282 | recipes point to this file within | ||
283 | :term:`LIC_FILES_CHKSUM` (as | ||
284 | ``${COREBASE}/LICENSE``) and thus the accompanying checksum must be | ||
285 | changed from 3f40d7994397109285ec7b81fdeb3b58 to | ||
286 | 4d92cd373abda3937c2bc47fbc49d690. A better alternative is to have | ||
287 | ``LIC_FILES_CHKSUM`` point to a file describing the license that is | ||
288 | distributed with the source that the recipe is building, if possible, | ||
289 | rather than pointing to ``${COREBASE}/LICENSE``. | ||
290 | |||
291 | .. _migration-1.6-cflags-options: | ||
292 | |||
293 | ``CFLAGS`` Options | ||
294 | ------------------ | ||
295 | |||
296 | The "-fpermissive" option has been removed from the default | ||
297 | :term:`CFLAGS` value. You need to take action on | ||
298 | individual recipes that fail when building with this option. You need to | ||
299 | either patch the recipes to fix the issues reported by the compiler, or | ||
300 | you need to add "-fpermissive" to ``CFLAGS`` in the recipes. | ||
301 | |||
302 | .. _migration-1.6-custom-images: | ||
303 | |||
304 | Custom Image Output Types | ||
305 | ------------------------- | ||
306 | |||
307 | Custom image output types, as selected using | ||
308 | :term:`IMAGE_FSTYPES`, must declare their | ||
309 | dependencies on other image types (if any) using a new | ||
310 | :term:`IMAGE_TYPEDEP` variable. | ||
311 | |||
312 | .. _migration-1.6-do-package-write-task: | ||
313 | |||
314 | Tasks | ||
315 | ----- | ||
316 | |||
317 | The ``do_package_write`` task has been removed. The task is no longer | ||
318 | needed. | ||
319 | |||
320 | .. _migration-1.6-update-alternatives-provider: | ||
321 | |||
322 | ``update-alternative`` Provider | ||
323 | ------------------------------- | ||
324 | |||
325 | The default ``update-alternatives`` provider has been changed from | ||
326 | ``opkg`` to ``opkg-utils``. This change resolves some troublesome | ||
327 | circular dependencies. The runtime package has also been renamed from | ||
328 | ``update-alternatives-cworth`` to ``update-alternatives-opkg``. | ||
329 | |||
330 | .. _migration-1.6-virtclass-overrides: | ||
331 | |||
332 | ``virtclass`` Overrides | ||
333 | ----------------------- | ||
334 | |||
335 | The ``virtclass`` overrides are now deprecated. Use the equivalent class | ||
336 | overrides instead (e.g. ``virtclass-native`` becomes ``class-native``.) | ||
337 | |||
338 | .. _migration-1.6-removed-renamed-recipes: | ||
339 | |||
340 | Removed and Renamed Recipes | ||
341 | --------------------------- | ||
342 | |||
343 | The following recipes have been removed: | ||
344 | |||
345 | - ``packagegroup-toolset-native`` - This recipe is largely unused. | ||
346 | |||
347 | - ``linux-yocto-3.8`` - Support for the Linux yocto 3.8 kernel has been | ||
348 | dropped. Support for the 3.10 and 3.14 kernels have been added with | ||
349 | the ``linux-yocto-3.10`` and ``linux-yocto-3.14`` recipes. | ||
350 | |||
351 | - ``ocf-linux`` - This recipe has been functionally replaced using | ||
352 | ``cryptodev-linux``. | ||
353 | |||
354 | - ``genext2fs`` - ``genext2fs`` is no longer used by the build system | ||
355 | and is unmaintained upstream. | ||
356 | |||
357 | - ``js`` - This provided an ancient version of Mozilla's javascript | ||
358 | engine that is no longer needed. | ||
359 | |||
360 | - ``zaurusd`` - The recipe has been moved to the ``meta-handheld`` | ||
361 | layer. | ||
362 | |||
363 | - ``eglibc 2.17`` - Replaced by the ``eglibc 2.19`` recipe. | ||
364 | |||
365 | - ``gcc 4.7.2`` - Replaced by the now stable ``gcc 4.8.2``. | ||
366 | |||
367 | - ``external-sourcery-toolchain`` - this recipe is now maintained in | ||
368 | the ``meta-sourcery`` layer. | ||
369 | |||
370 | - ``linux-libc-headers-yocto 3.4+git`` - Now using version 3.10 of the | ||
371 | ``linux-libc-headers`` by default. | ||
372 | |||
373 | - ``meta-toolchain-gmae`` - This recipe is obsolete. | ||
374 | |||
375 | - ``packagegroup-core-sdk-gmae`` - This recipe is obsolete. | ||
376 | |||
377 | - ``packagegroup-core-standalone-gmae-sdk-target`` - This recipe is | ||
378 | obsolete. | ||
379 | |||
380 | .. _migration-1.6-removed-classes: | ||
381 | |||
382 | Removed Classes | ||
383 | --------------- | ||
384 | |||
385 | The following classes have become obsolete and have been removed: | ||
386 | |||
387 | - ``module_strip`` | ||
388 | |||
389 | - ``pkg_metainfo`` | ||
390 | |||
391 | - ``pkg_distribute`` | ||
392 | |||
393 | - ``image-empty`` | ||
394 | |||
395 | .. _migration-1.6-reference-bsps: | ||
396 | |||
397 | Reference Board Support Packages (BSPs) | ||
398 | --------------------------------------- | ||
399 | |||
400 | The following reference BSPs changes occurred: | ||
401 | |||
402 | - The BeagleBoard (``beagleboard``) ARM reference hardware has been | ||
403 | replaced by the BeagleBone (``beaglebone``) hardware. | ||
404 | |||
405 | - The RouterStation Pro (``routerstationpro``) MIPS reference hardware | ||
406 | has been replaced by the EdgeRouter Lite (``edgerouter``) hardware. | ||
407 | |||
408 | The previous reference BSPs for the ``beagleboard`` and | ||
409 | ``routerstationpro`` machines are still available in a new | ||
410 | ``meta-yocto-bsp-old`` layer in the | ||
411 | :yocto_git:`Source Repositories <>` at | ||
412 | :yocto_git:`/meta-yocto-bsp-old/`. | ||
413 | |||
414 | |||