diff options
Diffstat (limited to 'documentation/migration-guides/migration-2.1.rst')
-rw-r--r-- | documentation/migration-guides/migration-2.1.rst | 432 |
1 files changed, 432 insertions, 0 deletions
diff --git a/documentation/migration-guides/migration-2.1.rst b/documentation/migration-guides/migration-2.1.rst new file mode 100644 index 0000000000..d4db8218cf --- /dev/null +++ b/documentation/migration-guides/migration-2.1.rst | |||
@@ -0,0 +1,432 @@ | |||
1 | Release 2.1 (krogoth) | ||
2 | ===================== | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.1 Release (codename "krogoth") from the prior release. | ||
6 | |||
7 | .. _migration-2.1-variable-expansion-in-python-functions: | ||
8 | |||
9 | Variable Expansion in Python Functions | ||
10 | -------------------------------------- | ||
11 | |||
12 | Variable expressions, such as ``${VARNAME}`` no longer expand | ||
13 | automatically within Python functions. Suppressing expansion was done to | ||
14 | allow Python functions to construct shell scripts or other code for | ||
15 | situations in which you do not want such expressions expanded. For any | ||
16 | existing code that relies on these expansions, you need to change the | ||
17 | expansions to expand the value of individual variables through | ||
18 | ``d.getVar()``. To alternatively expand more complex expressions, use | ||
19 | ``d.expand()``. | ||
20 | |||
21 | .. _migration-2.1-overrides-must-now-be-lower-case: | ||
22 | |||
23 | Overrides Must Now be Lower-Case | ||
24 | -------------------------------- | ||
25 | |||
26 | The convention for overrides has always been for them to be lower-case | ||
27 | characters. This practice is now a requirement as BitBake's datastore | ||
28 | now assumes lower-case characters in order to give a slight performance | ||
29 | boost during parsing. In practical terms, this requirement means that | ||
30 | anything that ends up in :term:`OVERRIDES` must now | ||
31 | appear in lower-case characters (e.g. values for ``MACHINE``, | ||
32 | ``TARGET_ARCH``, ``DISTRO``, and also recipe names if | ||
33 | ``_pn-``\ recipename overrides are to be effective). | ||
34 | |||
35 | .. _migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory: | ||
36 | |||
37 | Expand Parameter to ``getVar()`` and ``getVarFlag()`` is Now Mandatory | ||
38 | ---------------------------------------------------------------------- | ||
39 | |||
40 | The expand parameter to ``getVar()`` and ``getVarFlag()`` previously | ||
41 | defaulted to False if not specified. Now, however, no default exists so | ||
42 | one must be specified. You must change any ``getVar()`` calls that do | ||
43 | not specify the final expand parameter to calls that do specify the | ||
44 | parameter. You can run the following ``sed`` command at the base of a | ||
45 | layer to make this change:: | ||
46 | |||
47 | sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *` | ||
48 | sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *` | ||
49 | |||
50 | .. note:: | ||
51 | |||
52 | The reason for this change is that it prepares the way for changing | ||
53 | the default to True in a future Yocto Project release. This future | ||
54 | change is a much more sensible default than False. However, the | ||
55 | change needs to be made gradually as a sudden change of the default | ||
56 | would potentially cause side-effects that would be difficult to | ||
57 | detect. | ||
58 | |||
59 | .. _migration-2.1-makefile-environment-changes: | ||
60 | |||
61 | Makefile Environment Changes | ||
62 | ---------------------------- | ||
63 | |||
64 | :term:`EXTRA_OEMAKE` now defaults to "" instead of | ||
65 | "-e MAKEFLAGS=". Setting ``EXTRA_OEMAKE`` to "-e MAKEFLAGS=" by default | ||
66 | was a historical accident that has required many classes (e.g. | ||
67 | ``autotools``, ``module``) and recipes to override this default in order | ||
68 | to work with sensible build systems. When upgrading to the release, you | ||
69 | must edit any recipe that relies upon this old default by either setting | ||
70 | ``EXTRA_OEMAKE`` back to "-e MAKEFLAGS=" or by explicitly setting any | ||
71 | required variable value overrides using ``EXTRA_OEMAKE``, which is | ||
72 | typically only needed when a Makefile sets a default value for a | ||
73 | variable that is inappropriate for cross-compilation using the "=" | ||
74 | operator rather than the "?=" operator. | ||
75 | |||
76 | .. _migration-2.1-libexecdir-reverted-to-prefix-libexec: | ||
77 | |||
78 | ``libexecdir`` Reverted to ``${prefix}/libexec`` | ||
79 | ------------------------------------------------ | ||
80 | |||
81 | The use of ``${libdir}/${BPN}`` as ``libexecdir`` is different as | ||
82 | compared to all other mainstream distributions, which either uses | ||
83 | ``${prefix}/libexec`` or ``${libdir}``. The use is also contrary to the | ||
84 | GNU Coding Standards (i.e. | ||
85 | https://www.gnu.org/prep/standards/html_node/Directory-Variables.html) | ||
86 | that suggest ``${prefix}/libexec`` and also notes that any | ||
87 | package-specific nesting should be done by the package itself. Finally, | ||
88 | having ``libexecdir`` change between recipes makes it very difficult for | ||
89 | different recipes to invoke binaries that have been installed into | ||
90 | ``libexecdir``. The Filesystem Hierarchy Standard (i.e. | ||
91 | https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html) now | ||
92 | recognizes the use of ``${prefix}/libexec/``, giving distributions the | ||
93 | choice between ``${prefix}/lib`` or ``${prefix}/libexec`` without | ||
94 | breaking FHS. | ||
95 | |||
96 | .. _migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files: | ||
97 | |||
98 | ``ac_cv_sizeof_off_t`` is No Longer Cached in Site Files | ||
99 | -------------------------------------------------------- | ||
100 | |||
101 | For recipes inheriting the :ref:`autotools <ref-classes-autotools>` | ||
102 | class, ``ac_cv_sizeof_off_t`` is no longer cached in the site files for | ||
103 | ``autoconf``. The reason for this change is because the | ||
104 | ``ac_cv_sizeof_off_t`` value is not necessarily static per architecture | ||
105 | as was previously assumed. Rather, the value changes based on whether | ||
106 | large file support is enabled. For most software that uses ``autoconf``, | ||
107 | this change should not be a problem. However, if you have a recipe that | ||
108 | bypasses the standard :ref:`ref-tasks-configure` task | ||
109 | from the ``autotools`` class and the software the recipe is building | ||
110 | uses a very old version of ``autoconf``, the recipe might be incapable | ||
111 | of determining the correct size of ``off_t`` during ``do_configure``. | ||
112 | |||
113 | The best course of action is to patch the software as necessary to allow | ||
114 | the default implementation from the ``autotools`` class to work such | ||
115 | that ``autoreconf`` succeeds and produces a working configure script, | ||
116 | and to remove the overridden ``do_configure`` task such that the default | ||
117 | implementation does get used. | ||
118 | |||
119 | .. _migration-2.1-image-generation-split-out-from-filesystem-generation: | ||
120 | |||
121 | Image Generation is Now Split Out from Filesystem Generation | ||
122 | ------------------------------------------------------------ | ||
123 | |||
124 | Previously, for image recipes the :ref:`ref-tasks-rootfs` | ||
125 | task assembled the filesystem and then from that filesystem generated | ||
126 | images. With this Yocto Project release, image generation is split into | ||
127 | separate :ref:`ref-tasks-image` tasks for clarity both in | ||
128 | operation and in the code. | ||
129 | |||
130 | For most cases, this change does not present any problems. However, if | ||
131 | you have made customizations that directly modify the ``do_rootfs`` task | ||
132 | or that mention ``do_rootfs``, you might need to update those changes. | ||
133 | In particular, if you had added any tasks after ``do_rootfs``, you | ||
134 | should make edits so that those tasks are after the | ||
135 | :ref:`ref-tasks-image-complete` task rather than | ||
136 | after ``do_rootfs`` so that your added tasks run at the correct | ||
137 | time. | ||
138 | |||
139 | A minor part of this restructuring is that the post-processing | ||
140 | definitions and functions have been moved from the | ||
141 | :ref:`image <ref-classes-image>` class to the | ||
142 | :ref:`rootfs-postcommands <ref-classes-rootfs*>` class. Functionally, | ||
143 | however, they remain unchanged. | ||
144 | |||
145 | .. _migration-2.1-removed-recipes: | ||
146 | |||
147 | Removed Recipes | ||
148 | --------------- | ||
149 | |||
150 | The following recipes have been removed in the 2.1 release: | ||
151 | |||
152 | - ``gcc`` version 4.8: Versions 4.9 and 5.3 remain. | ||
153 | |||
154 | - ``qt4``: All support for Qt 4.x has been moved out to a separate | ||
155 | ``meta-qt4`` layer because Qt 4 is no longer supported upstream. | ||
156 | |||
157 | - ``x11vnc``: Moved to the ``meta-oe`` layer. | ||
158 | |||
159 | - ``linux-yocto-3.14``: No longer supported. | ||
160 | |||
161 | - ``linux-yocto-3.19``: No longer supported. | ||
162 | |||
163 | - ``libjpeg``: Replaced by the ``libjpeg-turbo`` recipe. | ||
164 | |||
165 | - ``pth``: Became obsolete. | ||
166 | |||
167 | - ``liboil``: Recipe is no longer needed and has been moved to the | ||
168 | ``meta-multimedia`` layer. | ||
169 | |||
170 | - ``gtk-theme-torturer``: Recipe is no longer needed and has been moved | ||
171 | to the ``meta-gnome`` layer. | ||
172 | |||
173 | - ``gnome-mime-data``: Recipe is no longer needed and has been moved to | ||
174 | the ``meta-gnome`` layer. | ||
175 | |||
176 | - ``udev``: Replaced by the ``eudev`` recipe for compatibility when | ||
177 | using ``sysvinit`` with newer kernels. | ||
178 | |||
179 | - ``python-pygtk``: Recipe became obsolete. | ||
180 | |||
181 | - ``adt-installer``: Recipe became obsolete. See the | ||
182 | ":ref:`migration-guides/migration-2.1:adt removed`" section for more information. | ||
183 | |||
184 | .. _migration-2.1-class-changes: | ||
185 | |||
186 | Class Changes | ||
187 | ------------- | ||
188 | |||
189 | The following classes have changed: | ||
190 | |||
191 | - ``autotools_stage``: Removed because the | ||
192 | :ref:`autotools <ref-classes-autotools>` class now provides its | ||
193 | functionality. Recipes that inherited from ``autotools_stage`` should | ||
194 | now inherit from ``autotools`` instead. | ||
195 | |||
196 | - ``boot-directdisk``: Merged into the ``image-vm`` class. The | ||
197 | ``boot-directdisk`` class was rarely directly used. Consequently, | ||
198 | this change should not cause any issues. | ||
199 | |||
200 | - ``bootimg``: Merged into the | ||
201 | :ref:`image-live <ref-classes-image-live>` class. The ``bootimg`` | ||
202 | class was rarely directly used. Consequently, this change should not | ||
203 | cause any issues. | ||
204 | |||
205 | - ``packageinfo``: Removed due to its limited use by the Hob UI, which | ||
206 | has itself been removed. | ||
207 | |||
208 | .. _migration-2.1-build-system-ui-changes: | ||
209 | |||
210 | Build System User Interface Changes | ||
211 | ----------------------------------- | ||
212 | |||
213 | The following changes have been made to the build system user interface: | ||
214 | |||
215 | - *Hob GTK+-based UI*: Removed because it is unmaintained and based on | ||
216 | the outdated GTK+ 2 library. The Toaster web-based UI is much more | ||
217 | capable and is actively maintained. See the | ||
218 | ":ref:`toaster-manual/setup-and-use:using the toaster web interface`" | ||
219 | section in the Toaster User Manual for more information on this | ||
220 | interface. | ||
221 | |||
222 | - *"puccho" BitBake UI*: Removed because is unmaintained and no longer | ||
223 | useful. | ||
224 | |||
225 | .. _migration-2.1-adt-removed: | ||
226 | |||
227 | ADT Removed | ||
228 | ----------- | ||
229 | |||
230 | The Application Development Toolkit (ADT) has been removed because its | ||
231 | functionality almost completely overlapped with the :ref:`standard | ||
232 | SDK <sdk-manual/using:using the standard sdk>` and the | ||
233 | :ref:`extensible SDK <sdk-manual/extensible:using the extensible sdk>`. For | ||
234 | information on these SDKs and how to build and use them, see the | ||
235 | :doc:`/sdk-manual/index` manual. | ||
236 | |||
237 | .. note:: | ||
238 | |||
239 | The Yocto Project Eclipse IDE Plug-in is still supported and is not | ||
240 | affected by this change. | ||
241 | |||
242 | .. _migration-2.1-poky-reference-distribution-changes: | ||
243 | |||
244 | Poky Reference Distribution Changes | ||
245 | ----------------------------------- | ||
246 | |||
247 | The following changes have been made for the Poky distribution: | ||
248 | |||
249 | - The ``meta-yocto`` layer has been renamed to ``meta-poky`` to better | ||
250 | match its purpose, which is to provide the Poky reference | ||
251 | distribution. The ``meta-yocto-bsp`` layer retains its original name | ||
252 | since it provides reference machines for the Yocto Project and it is | ||
253 | otherwise unrelated to Poky. References to ``meta-yocto`` in your | ||
254 | ``conf/bblayers.conf`` should automatically be updated, so you should | ||
255 | not need to change anything unless you are relying on this naming | ||
256 | elsewhere. | ||
257 | |||
258 | - The :ref:`uninative <ref-classes-uninative>` class is now enabled | ||
259 | by default in Poky. This class attempts to isolate the build system | ||
260 | from the host distribution's C library and makes re-use of native | ||
261 | shared state artifacts across different host distributions practical. | ||
262 | With this class enabled, a tarball containing a pre-built C library | ||
263 | is downloaded at the start of the build. | ||
264 | |||
265 | The ``uninative`` class is enabled through the | ||
266 | ``meta/conf/distro/include/yocto-uninative.inc`` file, which for | ||
267 | those not using the Poky distribution, can include to easily enable | ||
268 | the same functionality. | ||
269 | |||
270 | Alternatively, if you wish to build your own ``uninative`` tarball, | ||
271 | you can do so by building the ``uninative-tarball`` recipe, making it | ||
272 | available to your build machines (e.g. over HTTP/HTTPS) and setting a | ||
273 | similar configuration as the one set by ``yocto-uninative.inc``. | ||
274 | |||
275 | - Static library generation, for most cases, is now disabled by default | ||
276 | in the Poky distribution. Disabling this generation saves some build | ||
277 | time as well as the size used for build output artifacts. | ||
278 | |||
279 | Disabling this library generation is accomplished through a | ||
280 | ``meta/conf/distro/include/no-static-libs.inc``, which for those not | ||
281 | using the Poky distribution can easily include to enable the same | ||
282 | functionality. | ||
283 | |||
284 | Any recipe that needs to opt-out of having the "--disable-static" | ||
285 | option specified on the configure command line either because it is | ||
286 | not a supported option for the configure script or because static | ||
287 | libraries are needed should set the following variable:: | ||
288 | |||
289 | DISABLE_STATIC = "" | ||
290 | |||
291 | - The separate ``poky-tiny`` distribution now uses the musl C library | ||
292 | instead of a heavily pared down ``glibc``. Using musl results in a | ||
293 | smaller distribution and facilitates much greater maintainability | ||
294 | because musl is designed to have a small footprint. | ||
295 | |||
296 | If you have used ``poky-tiny`` and have customized the ``glibc`` | ||
297 | configuration you will need to redo those customizations with musl | ||
298 | when upgrading to the new release. | ||
299 | |||
300 | .. _migration-2.1-packaging-changes: | ||
301 | |||
302 | Packaging Changes | ||
303 | ----------------- | ||
304 | |||
305 | The following changes have been made to packaging: | ||
306 | |||
307 | - The ``runuser`` and ``mountpoint`` binaries, which were previously in | ||
308 | the main ``util-linux`` package, have been split out into the | ||
309 | ``util-linux-runuser`` and ``util-linux-mountpoint`` packages, | ||
310 | respectively. | ||
311 | |||
312 | - The ``python-elementtree`` package has been merged into the | ||
313 | ``python-xml`` package. | ||
314 | |||
315 | .. _migration-2.1-tuning-file-changes: | ||
316 | |||
317 | Tuning File Changes | ||
318 | ------------------- | ||
319 | |||
320 | The following changes have been made to the tuning files: | ||
321 | |||
322 | - The "no-thumb-interwork" tuning feature has been dropped from the ARM | ||
323 | tune include files. Because interworking is required for ARM EABI, | ||
324 | attempting to disable it through a tuning feature no longer makes | ||
325 | sense. | ||
326 | |||
327 | .. note:: | ||
328 | |||
329 | Support for ARM OABI was deprecated in gcc 4.7. | ||
330 | |||
331 | - The ``tune-cortexm*.inc`` and ``tune-cortexr4.inc`` files have been | ||
332 | removed because they are poorly tested. Until the OpenEmbedded build | ||
333 | system officially gains support for CPUs without an MMU, these tuning | ||
334 | files would probably be better maintained in a separate layer if | ||
335 | needed. | ||
336 | |||
337 | .. _migration-2.1-supporting-gobject-introspection: | ||
338 | |||
339 | Supporting GObject Introspection | ||
340 | -------------------------------- | ||
341 | |||
342 | This release supports generation of GLib Introspective Repository (GIR) | ||
343 | files through GObject introspection, which is the standard mechanism for | ||
344 | accessing GObject-based software from runtime environments. You can | ||
345 | enable, disable, and test the generation of this data. See the | ||
346 | ":ref:`dev-manual/common-tasks:enabling gobject introspection support`" | ||
347 | section in the Yocto Project Development Tasks Manual for more | ||
348 | information. | ||
349 | |||
350 | .. _migration-2.1-miscellaneous-changes: | ||
351 | |||
352 | Miscellaneous Changes | ||
353 | --------------------- | ||
354 | |||
355 | These additional changes exist: | ||
356 | |||
357 | - The minimum Git version has been increased to 1.8.3.1. If your host | ||
358 | distribution does not provide a sufficiently recent version, you can | ||
359 | install the buildtools, which will provide it. See the | ||
360 | :ref:`ref-manual/system-requirements:required git, tar, python and gcc versions` | ||
361 | section for more information on the buildtools tarball. | ||
362 | |||
363 | - The buggy and incomplete support for the RPM version 4 package | ||
364 | manager has been removed. The well-tested and maintained support for | ||
365 | RPM version 5 remains. | ||
366 | |||
367 | - Previously, the following list of packages were removed if | ||
368 | package-management was not in | ||
369 | :term:`IMAGE_FEATURES`, regardless of any | ||
370 | dependencies:: | ||
371 | |||
372 | update-rc.d | ||
373 | base-passwd | ||
374 | shadow | ||
375 | update-alternatives | ||
376 | run-postinsts | ||
377 | |||
378 | With the Yocto Project 2.1 release, these packages are | ||
379 | only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since | ||
380 | they might still be needed for a read-write image even in the absence | ||
381 | of a package manager (e.g. if users need to be added, modified, or | ||
382 | removed at runtime). | ||
383 | |||
384 | - The | ||
385 | :ref:`devtool modify <sdk-manual/extensible:use \`\`devtool modify\`\` to modify the source of an existing component>` | ||
386 | command now defaults to extracting the source since that is most | ||
387 | commonly expected. The "-x" or "--extract" options are now no-ops. If | ||
388 | you wish to provide your own existing source tree, you will now need | ||
389 | to specify either the "-n" or "--no-extract" options when running | ||
390 | ``devtool modify``. | ||
391 | |||
392 | - If the formfactor for a machine is either not supplied or does not | ||
393 | specify whether a keyboard is attached, then the default is to assume | ||
394 | a keyboard is attached rather than assume no keyboard. This change | ||
395 | primarily affects the Sato UI. | ||
396 | |||
397 | - The ``.debug`` directory packaging is now automatic. If your recipe | ||
398 | builds software that installs binaries into directories other than | ||
399 | the standard ones, you no longer need to take care of setting | ||
400 | ``FILES_${PN}-dbg`` to pick up the resulting ``.debug`` directories | ||
401 | as these directories are automatically found and added. | ||
402 | |||
403 | - Inaccurate disk and CPU percentage data has been dropped from | ||
404 | ``buildstats`` output. This data has been replaced with | ||
405 | ``getrusage()`` data and corrected IO statistics. You will probably | ||
406 | need to update any custom code that reads the ``buildstats`` data. | ||
407 | |||
408 | - The ``meta/conf/distro/include/package_regex.inc`` is now deprecated. | ||
409 | The contents of this file have been moved to individual recipes. | ||
410 | |||
411 | .. note:: | ||
412 | |||
413 | Because this file will likely be removed in a future Yocto Project | ||
414 | release, it is suggested that you remove any references to the | ||
415 | file that might be in your configuration. | ||
416 | |||
417 | - The ``v86d/uvesafb`` has been removed from the ``genericx86`` and | ||
418 | ``genericx86-64`` reference machines, which are provided by the | ||
419 | ``meta-yocto-bsp`` layer. Most modern x86 boards do not rely on this | ||
420 | file and it only adds kernel error messages during startup. If you do | ||
421 | still need to support ``uvesafb``, you can simply add ``v86d`` to | ||
422 | your image. | ||
423 | |||
424 | - Build sysroot paths are now removed from debug symbol files. Removing | ||
425 | these paths means that remote GDB using an unstripped build system | ||
426 | sysroot will no longer work (although this was never documented to | ||
427 | work). The supported method to accomplish something similar is to set | ||
428 | ``IMAGE_GEN_DEBUGFS`` to "1", which will generate a companion debug | ||
429 | image containing unstripped binaries and associated debug sources | ||
430 | alongside the image. | ||
431 | |||
432 | |||