diff options
Diffstat (limited to 'documentation/ref-manual/migration-1.3.rst')
-rw-r--r-- | documentation/ref-manual/migration-1.3.rst | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration-1.3.rst b/documentation/ref-manual/migration-1.3.rst new file mode 100644 index 0000000000..ebbc238873 --- /dev/null +++ b/documentation/ref-manual/migration-1.3.rst | |||
@@ -0,0 +1,195 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | Moving to the Yocto Project 1.3 Release | ||
4 | ======================================= | ||
5 | |||
6 | This section provides migration information for moving to the Yocto | ||
7 | Project 1.3 Release from the prior release. | ||
8 | |||
9 | .. _1.3-local-configuration: | ||
10 | |||
11 | Local Configuration | ||
12 | ------------------- | ||
13 | |||
14 | Differences include changes for | ||
15 | :term:`SSTATE_MIRRORS` and ``bblayers.conf``. | ||
16 | |||
17 | .. _migration-1.3-sstate-mirrors: | ||
18 | |||
19 | SSTATE_MIRRORS | ||
20 | ~~~~~~~~~~~~~~ | ||
21 | |||
22 | The shared state cache (sstate-cache), as pointed to by | ||
23 | :term:`SSTATE_DIR`, by default now has two-character | ||
24 | subdirectories to prevent issues arising from too many files in the same | ||
25 | directory. Also, native sstate-cache packages, which are built to run on | ||
26 | the host system, will go into a subdirectory named using the distro ID | ||
27 | string. If you copy the newly structured sstate-cache to a mirror | ||
28 | location (either local or remote) and then point to it in | ||
29 | :term:`SSTATE_MIRRORS`, you need to append "PATH" | ||
30 | to the end of the mirror URL so that the path used by BitBake before the | ||
31 | mirror substitution is appended to the path used to access the mirror. | ||
32 | Here is an example: :: | ||
33 | |||
34 | SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" | ||
35 | |||
36 | .. _migration-1.3-bblayers-conf: | ||
37 | |||
38 | bblayers.conf | ||
39 | ~~~~~~~~~~~~~ | ||
40 | |||
41 | The ``meta-yocto`` layer consists of two parts that correspond to the | ||
42 | Poky reference distribution and the reference hardware Board Support | ||
43 | Packages (BSPs), respectively: ``meta-yocto`` and ``meta-yocto-bsp``. | ||
44 | When running BitBake for the first time after upgrading, your | ||
45 | ``conf/bblayers.conf`` file will be updated to handle this change and | ||
46 | you will be asked to re-run or restart for the changes to take effect. | ||
47 | |||
48 | .. _1.3-recipes: | ||
49 | |||
50 | Recipes | ||
51 | ------- | ||
52 | |||
53 | Differences include changes for the following: | ||
54 | |||
55 | .. _migration-1.3-python-function-whitespace: | ||
56 | |||
57 | Python Function Whitespace | ||
58 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
59 | |||
60 | All Python functions must now use four spaces for indentation. | ||
61 | Previously, an inconsistent mix of spaces and tabs existed, which made | ||
62 | extending these functions using ``_append`` or ``_prepend`` complicated | ||
63 | given that Python treats whitespace as syntactically significant. If you | ||
64 | are defining or extending any Python functions (e.g. | ||
65 | ``populate_packages``, ``do_unpack``, ``do_patch`` and so forth) in | ||
66 | custom recipes or classes, you need to ensure you are using consistent | ||
67 | four-space indentation. | ||
68 | |||
69 | .. _migration-1.3-proto=-in-src-uri: | ||
70 | |||
71 | proto= in SRC_URI | ||
72 | ~~~~~~~~~~~~~~~~~ | ||
73 | |||
74 | Any use of ``proto=`` in :term:`SRC_URI` needs to be | ||
75 | changed to ``protocol=``. In particular, this applies to the following | ||
76 | URIs: | ||
77 | |||
78 | - ``svn://`` | ||
79 | |||
80 | - ``bzr://`` | ||
81 | |||
82 | - ``hg://`` | ||
83 | |||
84 | - ``osc://`` | ||
85 | |||
86 | Other URIs were already using ``protocol=``. This change improves | ||
87 | consistency. | ||
88 | |||
89 | .. _migration-1.3-nativesdk: | ||
90 | |||
91 | nativesdk | ||
92 | ~~~~~~~~~ | ||
93 | |||
94 | The suffix ``nativesdk`` is now implemented as a prefix, which | ||
95 | simplifies a lot of the packaging code for ``nativesdk`` recipes. All | ||
96 | custom ``nativesdk`` recipes, which are relocatable packages that are | ||
97 | native to :term:`SDK_ARCH`, and any references need to | ||
98 | be updated to use ``nativesdk-*`` instead of ``*-nativesdk``. | ||
99 | |||
100 | .. _migration-1.3-task-recipes: | ||
101 | |||
102 | Task Recipes | ||
103 | ~~~~~~~~~~~~ | ||
104 | |||
105 | "Task" recipes are now known as "Package groups" and have been renamed | ||
106 | from ``task-*.bb`` to ``packagegroup-*.bb``. Existing references to the | ||
107 | previous ``task-*`` names should work in most cases as there is an | ||
108 | automatic upgrade path for most packages. However, you should update | ||
109 | references in your own recipes and configurations as they could be | ||
110 | removed in future releases. You should also rename any custom ``task-*`` | ||
111 | recipes to ``packagegroup-*``, and change them to inherit | ||
112 | ``packagegroup`` instead of ``task``, as well as taking the opportunity | ||
113 | to remove anything now handled by ``packagegroup.bbclass``, such as | ||
114 | providing ``-dev`` and ``-dbg`` packages, setting | ||
115 | :term:`LIC_FILES_CHKSUM`, and so forth. See the | ||
116 | ":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section for | ||
117 | further details. | ||
118 | |||
119 | .. _migration-1.3-image-features: | ||
120 | |||
121 | IMAGE_FEATURES | ||
122 | ~~~~~~~~~~~~~~ | ||
123 | |||
124 | Image recipes that previously included "apps-console-core" in | ||
125 | :term:`IMAGE_FEATURES` should now include "splash" | ||
126 | instead to enable the boot-up splash screen. Retaining | ||
127 | "apps-console-core" will still include the splash screen but generates a | ||
128 | warning. The "apps-x11-core" and "apps-x11-games" ``IMAGE_FEATURES`` | ||
129 | features have been removed. | ||
130 | |||
131 | .. _migration-1.3-removed-recipes: | ||
132 | |||
133 | Removed Recipes | ||
134 | ~~~~~~~~~~~~~~~ | ||
135 | |||
136 | The following recipes have been removed. For most of them, it is | ||
137 | unlikely that you would have any references to them in your own | ||
138 | :term:`Metadata`. However, you should check your metadata | ||
139 | against this list to be sure: | ||
140 | |||
141 | - ``libx11-trim``: Replaced by ``libx11``, which has a negligible | ||
142 | size difference with modern Xorg. | ||
143 | |||
144 | - ``xserver-xorg-lite``: Use ``xserver-xorg``, which has a negligible | ||
145 | size difference when DRI and GLX modules are not installed. | ||
146 | |||
147 | - ``xserver-kdrive``: Effectively unmaintained for many years. | ||
148 | |||
149 | - ``mesa-xlib``: No longer serves any purpose. | ||
150 | |||
151 | - ``galago``: Replaced by telepathy. | ||
152 | |||
153 | - ``gail``: Functionality was integrated into GTK+ 2.13. | ||
154 | |||
155 | - ``eggdbus``: No longer needed. | ||
156 | |||
157 | - ``gcc-*-intermediate``: The build has been restructured to avoid | ||
158 | the need for this step. | ||
159 | |||
160 | - ``libgsmd``: Unmaintained for many years. Functionality now | ||
161 | provided by ``ofono`` instead. | ||
162 | |||
163 | - *contacts, dates, tasks, eds-tools*: Largely unmaintained PIM | ||
164 | application suite. It has been moved to ``meta-gnome`` in | ||
165 | ``meta-openembedded``. | ||
166 | |||
167 | In addition to the previously listed changes, the ``meta-demoapps`` | ||
168 | directory has also been removed because the recipes in it were not being | ||
169 | maintained and many had become obsolete or broken. Additionally, these | ||
170 | recipes were not parsed in the default configuration. Many of these | ||
171 | recipes are already provided in an updated and maintained form within | ||
172 | the OpenEmbedded community layers such as ``meta-oe`` and | ||
173 | ``meta-gnome``. For the remainder, you can now find them in the | ||
174 | ``meta-extras`` repository, which is in the | ||
175 | :yocto_git:`Source Repositories <>` at | ||
176 | http://git.yoctoproject.org/cgit/cgit.cgi/meta-extras/. | ||
177 | |||
178 | .. _1.3-linux-kernel-naming: | ||
179 | |||
180 | Linux Kernel Naming | ||
181 | ------------------- | ||
182 | |||
183 | The naming scheme for kernel output binaries has been changed to now | ||
184 | include :term:`PE` as part of the filename: | ||
185 | :: | ||
186 | |||
187 | KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}" | ||
188 | |||
189 | Because the ``PE`` variable is not set by default, these binary files | ||
190 | could result with names that include two dash characters. Here is an | ||
191 | example: :: | ||
192 | |||
193 | bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin | ||
194 | |||
195 | |||