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