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-2.1.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-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 | |||