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-1.5.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-1.5.rst')
-rw-r--r-- | documentation/ref-manual/migration-1.5.rst | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration-1.5.rst b/documentation/ref-manual/migration-1.5.rst new file mode 100644 index 0000000000..fa6ff92f10 --- /dev/null +++ b/documentation/ref-manual/migration-1.5.rst | |||
@@ -0,0 +1,355 @@ | |||
1 | Moving to the Yocto Project 1.5 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.5 Release 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 "`Required Git, tar, | ||
29 | Python and gcc Versions <#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 | ||
45 | genericx86-64 | ||
46 | BSP has been added for 64-bit Atom systems. | ||
47 | |||
48 | .. _migration-1.5-bitbake: | ||
49 | |||
50 | BitBake | ||
51 | ------- | ||
52 | |||
53 | The following changes have been made that relate to BitBake: | ||
54 | |||
55 | - BitBake now supports a ``_remove`` operator. The addition of this | ||
56 | operator means you will have to rename any items in recipe space | ||
57 | (functions, variables) whose names currently contain ``_remove_`` or | ||
58 | end with ``_remove`` to avoid unexpected behavior. | ||
59 | |||
60 | - BitBake's global method pool has been removed. This method is not | ||
61 | particularly useful and led to clashes between recipes containing | ||
62 | functions that had the same name. | ||
63 | |||
64 | - The "none" server backend has been removed. The "process" server | ||
65 | backend has been serving well as the default for a long time now. | ||
66 | |||
67 | - The ``bitbake-runtask`` script has been removed. | ||
68 | |||
69 | - ``${``\ :term:`P`\ ``}`` and | ||
70 | ``${``\ :term:`PF`\ ``}`` are no longer added to | ||
71 | :term:`PROVIDES` by default in ``bitbake.conf``. | ||
72 | These version-specific ``PROVIDES`` items were seldom used. | ||
73 | Attempting to use them could result in two versions being built | ||
74 | simultaneously rather than just one version due to the way BitBake | ||
75 | resolves dependencies. | ||
76 | |||
77 | .. _migration-1.5-qa-warnings: | ||
78 | |||
79 | QA Warnings | ||
80 | ----------- | ||
81 | |||
82 | The following changes have been made to the package QA checks: | ||
83 | |||
84 | - If you have customized :term:`ERROR_QA` or | ||
85 | :term:`WARN_QA` values in your configuration, check | ||
86 | that they contain all of the issues that you wish to be reported. | ||
87 | Previous Yocto Project versions contained a bug that meant that any | ||
88 | item not mentioned in ``ERROR_QA`` or ``WARN_QA`` would be treated as | ||
89 | a warning. Consequently, several important items were not already in | ||
90 | the default value of ``WARN_QA``. All of the possible QA checks are | ||
91 | now documented in the ":ref:`insane.bbclass <ref-classes-insane>`" | ||
92 | section. | ||
93 | |||
94 | - An additional QA check has been added to check if | ||
95 | ``/usr/share/info/dir`` is being installed. Your recipe should delete | ||
96 | this file within :ref:`ref-tasks-install` if "make | ||
97 | install" is installing it. | ||
98 | |||
99 | - If you are using the buildhistory class, the check for the package | ||
100 | version going backwards is now controlled using a standard QA check. | ||
101 | Thus, if you have customized your ``ERROR_QA`` or ``WARN_QA`` values | ||
102 | and still wish to have this check performed, you should add | ||
103 | "version-going-backwards" to your value for one or the other | ||
104 | variables depending on how you wish it to be handled. See the | ||
105 | documented QA checks in the | ||
106 | ":ref:`insane.bbclass <ref-classes-insane>`" section. | ||
107 | |||
108 | .. _migration-1.5-directory-layout-changes: | ||
109 | |||
110 | Directory Layout Changes | ||
111 | ------------------------ | ||
112 | |||
113 | The following directory changes exist: | ||
114 | |||
115 | - Output SDK installer files are now named to include the image name | ||
116 | and tuning architecture through the :term:`SDK_NAME` | ||
117 | variable. | ||
118 | |||
119 | - Images and related files are now installed into a directory that is | ||
120 | specific to the machine, instead of a parent directory containing | ||
121 | output files for multiple machines. The | ||
122 | :term:`DEPLOY_DIR_IMAGE` variable continues | ||
123 | to point to the directory containing images for the current | ||
124 | :term:`MACHINE` and should be used anywhere there is a | ||
125 | need to refer to this directory. The ``runqemu`` script now uses this | ||
126 | variable to find images and kernel binaries and will use BitBake to | ||
127 | determine the directory. Alternatively, you can set the | ||
128 | ``DEPLOY_DIR_IMAGE`` variable in the external environment. | ||
129 | |||
130 | - When buildhistory is enabled, its output is now written under the | ||
131 | :term:`Build Directory` rather than | ||
132 | :term:`TMPDIR`. Doing so makes it easier to delete | ||
133 | ``TMPDIR`` and preserve the build history. Additionally, data for | ||
134 | produced SDKs is now split by :term:`IMAGE_NAME`. | ||
135 | |||
136 | - The ``pkgdata`` directory produced as part of the packaging process | ||
137 | has been collapsed into a single machine-specific directory. This | ||
138 | directory is located under ``sysroots`` and uses a machine-specific | ||
139 | name (i.e. ``tmp/sysroots/machine/pkgdata``). | ||
140 | |||
141 | .. _migration-1.5-shortened-git-srcrev-values: | ||
142 | |||
143 | Shortened Git ``SRCREV`` Values | ||
144 | ------------------------------- | ||
145 | |||
146 | BitBake will now shorten revisions from Git repositories from the normal | ||
147 | 40 characters down to 10 characters within :term:`SRCPV` | ||
148 | for improved usability in path and file names. This change should be | ||
149 | safe within contexts where these revisions are used because the chances | ||
150 | of spatially close collisions is very low. Distant collisions are not a | ||
151 | major issue in the way the values are used. | ||
152 | |||
153 | .. _migration-1.5-image-features: | ||
154 | |||
155 | ``IMAGE_FEATURES`` | ||
156 | ------------------ | ||
157 | |||
158 | The following changes have been made that relate to | ||
159 | :term:`IMAGE_FEATURES`: | ||
160 | |||
161 | - The value of ``IMAGE_FEATURES`` is now validated to ensure invalid | ||
162 | feature items are not added. Some users mistakenly add package names | ||
163 | to this variable instead of using | ||
164 | :term:`IMAGE_INSTALL` in order to have the | ||
165 | package added to the image, which does not work. This change is | ||
166 | intended to catch those kinds of situations. Valid ``IMAGE_FEATURES`` | ||
167 | are drawn from ``PACKAGE_GROUP`` definitions, | ||
168 | :term:`COMPLEMENTARY_GLOB` and a new | ||
169 | "validitems" varflag on ``IMAGE_FEATURES``. The "validitems" varflag | ||
170 | change allows additional features to be added if they are not | ||
171 | provided using the previous two mechanisms. | ||
172 | |||
173 | - The previously deprecated "apps-console-core" ``IMAGE_FEATURES`` item | ||
174 | is no longer supported. Add "splash" to ``IMAGE_FEATURES`` if you | ||
175 | wish to have the splash screen enabled, since this is all that | ||
176 | apps-console-core was doing. | ||
177 | |||
178 | .. _migration-1.5-run: | ||
179 | |||
180 | ``/run`` | ||
181 | -------- | ||
182 | |||
183 | The ``/run`` directory from the Filesystem Hierarchy Standard 3.0 has | ||
184 | been introduced. You can find some of the implications for this change | ||
185 | `here <http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873>`__. | ||
186 | The change also means that recipes that install files to ``/var/run`` | ||
187 | must be changed. You can find a guide on how to make these changes | ||
188 | `here <https://www.mail-archive.com/openembedded-devel@lists.openembedded.org/msg31649.html>`__. | ||
189 | |||
190 | .. _migration-1.5-removal-of-package-manager-database-within-image-recipes: | ||
191 | |||
192 | Removal of Package Manager Database Within Image Recipes | ||
193 | -------------------------------------------------------- | ||
194 | |||
195 | The image ``core-image-minimal`` no longer adds | ||
196 | ``remove_packaging_data_files`` to | ||
197 | :term:`ROOTFS_POSTPROCESS_COMMAND`. | ||
198 | This addition is now handled automatically when "package-management" is | ||
199 | not in :term:`IMAGE_FEATURES`. If you have custom | ||
200 | image recipes that make this addition, you should remove the lines, as | ||
201 | they are not needed and might interfere with correct operation of | ||
202 | postinstall scripts. | ||
203 | |||
204 | .. _migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time: | ||
205 | |||
206 | Images Now Rebuild Only on Changes Instead of Every Time | ||
207 | -------------------------------------------------------- | ||
208 | |||
209 | The :ref:`ref-tasks-rootfs` and other related image | ||
210 | construction tasks are no longer marked as "nostamp". Consequently, they | ||
211 | will only be re-executed when their inputs have changed. Previous | ||
212 | versions of the OpenEmbedded build system always rebuilt the image when | ||
213 | requested rather when necessary. | ||
214 | |||
215 | .. _migration-1.5-task-recipes: | ||
216 | |||
217 | Task Recipes | ||
218 | ------------ | ||
219 | |||
220 | The previously deprecated ``task.bbclass`` has now been dropped. For | ||
221 | recipes that previously inherited from this class, you should rename | ||
222 | them from ``task-*`` to ``packagegroup-*`` and inherit packagegroup | ||
223 | instead. | ||
224 | |||
225 | For more information, see the | ||
226 | ":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section. | ||
227 | |||
228 | .. _migration-1.5-busybox: | ||
229 | |||
230 | BusyBox | ||
231 | ------- | ||
232 | |||
233 | By default, we now split BusyBox into two binaries: one that is suid | ||
234 | root for those components that need it, and another for the rest of the | ||
235 | components. Splitting BusyBox allows for optimization that eliminates | ||
236 | the ``tinylogin`` recipe as recommended by upstream. You can disable | ||
237 | this split by setting | ||
238 | :term:`BUSYBOX_SPLIT_SUID` to "0". | ||
239 | |||
240 | .. _migration-1.5-automated-image-testing: | ||
241 | |||
242 | Automated Image Testing | ||
243 | ----------------------- | ||
244 | |||
245 | A new automated image testing framework has been added through the | ||
246 | :ref:`testimage.bbclass <ref-classes-testimage*>` class. This | ||
247 | framework replaces the older ``imagetest-qemu`` framework. | ||
248 | |||
249 | You can learn more about performing automated image tests in the | ||
250 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
251 | section in the Yocto Project Development Tasks Manual. | ||
252 | |||
253 | .. _migration-1.5-build-history: | ||
254 | |||
255 | Build History | ||
256 | ------------- | ||
257 | |||
258 | Following are changes to Build History: | ||
259 | |||
260 | - Installed package sizes: ``installed-package-sizes.txt`` for an image | ||
261 | now records the size of the files installed by each package instead | ||
262 | of the size of each compressed package archive file. | ||
263 | |||
264 | - The dependency graphs (``depends*.dot``) now use the actual package | ||
265 | names instead of replacing dashes, dots and plus signs with | ||
266 | underscores. | ||
267 | |||
268 | - The ``buildhistory-diff`` and ``buildhistory-collect-srcrevs`` | ||
269 | utilities have improved command-line handling. Use the ``--help`` | ||
270 | option for each utility for more information on the new syntax. | ||
271 | |||
272 | For more information on Build History, see the | ||
273 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" | ||
274 | section in the Yocto Project Development Tasks Manual. | ||
275 | |||
276 | .. _migration-1.5-udev: | ||
277 | |||
278 | ``udev`` | ||
279 | -------- | ||
280 | |||
281 | Following are changes to ``udev``: | ||
282 | |||
283 | - ``udev`` no longer brings in ``udev-extraconf`` automatically through | ||
284 | :term:`RRECOMMENDS`, since this was originally | ||
285 | intended to be optional. If you need the extra rules, then add | ||
286 | ``udev-extraconf`` to your image. | ||
287 | |||
288 | - ``udev`` no longer brings in ``pciutils-ids`` or ``usbutils-ids`` | ||
289 | through ``RRECOMMENDS``. These are not needed by ``udev`` itself and | ||
290 | removing them saves around 350KB. | ||
291 | |||
292 | .. _migration-1.5-removed-renamed-recipes: | ||
293 | |||
294 | Removed and Renamed Recipes | ||
295 | --------------------------- | ||
296 | |||
297 | - The ``linux-yocto`` 3.2 kernel has been removed. | ||
298 | |||
299 | - ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``. | ||
300 | |||
301 | - ``tinylogin`` has been removed. It has been replaced by a suid | ||
302 | portion of Busybox. See the "`BusyBox <#migration-1.5-busybox>`__" | ||
303 | section for more information. | ||
304 | |||
305 | - ``external-python-tarball`` has been renamed to | ||
306 | ``buildtools-tarball``. | ||
307 | |||
308 | - ``web-webkit`` has been removed. It has been functionally replaced by | ||
309 | ``midori``. | ||
310 | |||
311 | - ``imake`` has been removed. It is no longer needed by any other | ||
312 | recipe. | ||
313 | |||
314 | - ``transfig-native`` has been removed. It is no longer needed by any | ||
315 | other recipe. | ||
316 | |||
317 | - ``anjuta-remote-run`` has been removed. Anjuta IDE integration has | ||
318 | not been officially supported for several releases. | ||
319 | |||
320 | .. _migration-1.5-other-changes: | ||
321 | |||
322 | Other Changes | ||
323 | ------------- | ||
324 | |||
325 | Following is a list of short entries describing other changes: | ||
326 | |||
327 | - ``run-postinsts``: Make this generic. | ||
328 | |||
329 | - ``base-files``: Remove the unnecessary ``media/``\ xxx directories. | ||
330 | |||
331 | - ``alsa-state``: Provide an empty ``asound.conf`` by default. | ||
332 | |||
333 | - ``classes/image``: Ensure | ||
334 | :term:`BAD_RECOMMENDATIONS` supports | ||
335 | pre-renamed package names. | ||
336 | |||
337 | - ``classes/rootfs_rpm``: Implement ``BAD_RECOMMENDATIONS`` for RPM. | ||
338 | |||
339 | - ``systemd``: Remove ``systemd_unitdir`` if ``systemd`` is not in | ||
340 | :term:`DISTRO_FEATURES`. | ||
341 | |||
342 | - ``systemd``: Remove ``init.d`` dir if ``systemd`` unit file is | ||
343 | present and ``sysvinit`` is not a distro feature. | ||
344 | |||
345 | - ``libpam``: Deny all services for the ``OTHER`` entries. | ||
346 | |||
347 | - ``image.bbclass``: Move ``runtime_mapping_rename`` to avoid conflict | ||
348 | with ``multilib``. See | ||
349 | `YOCTO #4993 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993>`_ | ||
350 | in Bugzilla for more information. | ||
351 | |||
352 | - ``linux-dtb``: Use kernel build system to generate the ``dtb`` files. | ||
353 | |||
354 | - ``kern-tools``: Switch from guilt to new ``kgit-s2q`` tool. | ||
355 | |||