summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/poky-ref-manual/migration.xml235
-rw-r--r--documentation/poky-ref-manual/poky-ref-manual.xml2
2 files changed, 237 insertions, 0 deletions
diff --git a/documentation/poky-ref-manual/migration.xml b/documentation/poky-ref-manual/migration.xml
new file mode 100644
index 0000000000..f410fa020f
--- /dev/null
+++ b/documentation/poky-ref-manual/migration.xml
@@ -0,0 +1,235 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='migration'>
6<title>Migrating to a Newer Yocto Project Release</title>
7
8 <para>
9 This chapter provides information you can use to migrate work to a
10 newer Yocto Project release. You can find the same information in the
11 release notes for a given release.
12 </para>
13
14<section id='moving-to-the-yocto-project-1.3-release'>
15 <title>Moving to the Yocto Project 1.3 Release</title>
16
17 <para>
18 This section provides migration information for moving to the
19 Yocto Project 1.3 Release.
20 </para>
21
22 <section id='1.3-local-configuration'>
23 <title>Local Configuration</title>
24
25 <para>
26 Differences include changes for
27 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
28 and <filename>bblayers.conf</filename>.
29 </para>
30
31 <section id='migration-1.3-sstate-mirrors'>
32 <title>SSTATE_MIRRORS</title>
33
34 <para>
35 The shared state cache (sstate-cache) as pointed to by
36 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> by default
37 now has two-character subdirectories to prevent there being an issue with too
38 many files in the same directory.
39 Also, native sstate-cache packages will go into a subdirectory named using
40 the distro ID string.
41 If you copy the newly structured sstate-cache to a mirror location
42 (either local or remote) and then point to it in
43 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
44 you need to append "PATH" to the end of the mirror URL so that
45 the path used by BitBake before the mirror substitution is
46 appended to the path used to access the mirror.
47 Here is an example:
48 <literallayout class='monospaced'>
49 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
50 </literallayout>
51 </para>
52 </section>
53
54 <section id='migration-1.3-bblayers-conf'>
55 <title>bblayers.conf</title>
56
57 <para>
58 The <filename>meta-yocto</filename> layer has been split into
59 two parts: <filename>meta-yocto</filename> and
60 <filename>meta-yocto-bsp</filename>, corresponding to the
61 Poky reference distro configuration and the reference
62 hardware Board Support Packages (BSPs), respectively.
63 When running BitBake or Hob for the first time after upgrading,
64 your <filename>conf/bblayers.conf</filename> file will be
65 updated to handle this change and you will be asked to
66 re-run/restart for the changes to take effect.
67 </para>
68 </section>
69 </section>
70
71 <section id='1.3-recipes'>
72 <title>Recipes</title>
73
74 <para>
75 Differences include changes for the following:
76 <itemizedlist>
77 <listitem><para>Python function whitespace</para></listitem>
78 <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem>
79 <listitem><para><filename>nativesdk</filename></para></listitem>
80 <listitem><para>Task recipes</para></listitem>
81 <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem>
82 <listitem><para>Removed recipes</para></listitem>
83 </itemizedlist>
84 </para>
85
86 <section id='migration-1.3-python-function-whitespace'>
87 <title>Python Function Whitespace</title>
88
89 <para>
90 All Python functions must now use four spaces for indentation.
91 Previously, an inconsistent mix of spaces and tabs existed,
92 which made extending these functions using
93 <filename>_append</filename> or <filename>_prepend</filename>
94 complicated given that Python treats whitespace as
95 syntactically significant.
96 If you are defining or extending any Python functions (e.g.
97 <filename>populate_packages</filename>, <filename>do_unpack</filename>,
98 <filename>do_patch</filename> and so forth) in custom recipes
99 or classes, you need to ensure you are using consistent
100 four-space indentation.
101 </para>
102 </section>
103
104 <section id='migration-1.3-proto=-in-src-uri'>
105 <title>proto= in SRC_URI</title>
106
107 <para>
108 Any use of <filename>proto=</filename> in
109 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
110 needs to be changed to <filename>protocol=</filename>.
111 In particular, this applies to the following URIs:
112 <itemizedlist>
113 <listitem><para><filename>svn://</filename></para></listitem>
114 <listitem><para><filename>bzr://</filename></para></listitem>
115 <listitem><para><filename>hg://</filename></para></listitem>
116 <listitem><para><filename>osc://</filename></para></listitem>
117 </itemizedlist>
118 Other URIs were already using <filename>protocol=</filename>.
119 This change improves consistency.
120 </para>
121 </section>
122
123 <section id='migration-1.3-nativesdk'>
124 <title>nativesdk</title>
125
126 <para>
127 The suffix <filename>nativesdk</filename> is now implemented
128 as a prefix, which simplifies a lot of the packaging code for
129 <filename>nativesdk</filename> recipes.
130 All custom <filename>nativesdk</filename> recipes and any
131 references need to be updated to use
132 <filename>nativesdk-*</filename> instead of
133 <filename>*-nativesdk</filename>.
134 </para>
135 </section>
136
137 <section id='migration-1.3-task-recipes'>
138 <title>Task Recipes</title>
139
140 <para>
141 "Task" recipes are now known as "Package groups" and have
142 been renamed from <filename>task-*.bb</filename> to
143 <filename>packagegroup-*.bb</filename>.
144 Existing references to the previous <filename>task-*</filename>
145 names should work in most cases as there is an automatic
146 upgrade path for most packages.
147 However, you should update references in your own recipes and
148 configurations as they could be removed in future releases.
149 You should also rename any custom <filename>task-*</filename>
150 recipes to <filename>packagegroup-*</filename>, and change
151 them to inherit <filename>packagegroup</filename> instead of
152 <filename>task</filename>, as well as taking the opportunity
153 to remove anything now handled by
154 <filename>packagegroup.bbclass</filename>, such as providing
155 <filename>-dev</filename> and <filename>-dbg</filename>
156 packages, setting
157 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
158 and so forth.
159 See the
160 "<link linkend='ref-classes-packagegroup'>Package Groups - packagegroup.bbclass</link>"
161 section for further details.
162 </para>
163 </section>
164
165 <section id='migration-1.3-image-features'>
166 <title>IMAGE_FEATURES</title>
167
168 <para>
169 Image recipes that previously included "apps-console-core"
170 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
171 should now include "splash" instead to enable the boot-up
172 splash screen.
173 Retaining "apps-console-core" will still include the splash
174 screen generates a warning.
175 The "apps-x11-core" and "apps-x11-games"
176 <filename>IMAGE_FEATURES</filename> features have been removed.
177 </para>
178 </section>
179
180 <section id='migration-1.3-removed-recipes'>
181 <title>Removed Recipes</title>
182
183 <para>
184 The following recipes have been removed.
185 For most of them, it is unlikely that you would have any
186 references to them in your own metadata.
187 However, you should check your metadata against this list to be sure:
188 <itemizedlist>
189 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
190 Replaced by <filename>libx11</filename>, which has a negligible
191 size difference as compared with modern Xorg.</para></listitem>
192 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
193 Use <filename>xserver-xorg</filename>, which has a negligible
194 size difference when DRI and GLX modules are not installed.</para></listitem>
195 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
196 Effectively unmaintained for many years.</para></listitem>
197 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
198 No longer serves any purpose.</para></listitem>
199 <listitem><para><emphasis><filename>galago</filename></emphasis>:
200 Replaced by telepathy.</para></listitem>
201 <listitem><para><emphasis><filename>gail</filename></emphasis>:
202 Functionality was integrated into GTK+ 2.13.</para></listitem>
203 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
204 No longer needed.</para></listitem>
205 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
206 The build has been restructured to avoid the need for
207 this step.</para></listitem>
208 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
209 Unmaintained for many years and now provided by
210 <filename>ofono</filename> instead.</para></listitem>
211 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
212 Largely unmaintained PIM application suite.
213 It has been moved to <filename>meta-gnome</filename>
214 in <filename>meta-openembedded</filename>.</para></listitem>
215 </itemizedlist>
216 In addition to the previously listed changes, the
217 <filename>meta-demoapps</filename> directory has also been removed
218 because the recipes in it were not being maintained and many
219 had become obsolete or broken.
220 Additionally, these recipes were not parsed in the default configuration.
221 Many of these recipes are already provided in an updated and
222 maintained form within OpenEmbedded community layers such as
223 <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
224 For the remainder, you can now find them in the
225 <filename>meta-extras</filename> repository in the
226 Yocto Project source repositories at
227 <ulink url='http://git.yoctoproject.org'></ulink>.
228 </para>
229 </section>
230 </section>
231</section>
232</chapter>
233<!--
234vim: expandtab tw=80 ts=4
235-->
diff --git a/documentation/poky-ref-manual/poky-ref-manual.xml b/documentation/poky-ref-manual/poky-ref-manual.xml
index e405375bbb..f36fab4eb9 100644
--- a/documentation/poky-ref-manual/poky-ref-manual.xml
+++ b/documentation/poky-ref-manual/poky-ref-manual.xml
@@ -89,6 +89,8 @@
89 89
90 <xi:include href="technical-details.xml"/> 90 <xi:include href="technical-details.xml"/>
91 91
92 <xi:include href="migration.xml"/>
93
92 <xi:include href="ref-structure.xml"/> 94 <xi:include href="ref-structure.xml"/>
93 95
94 <xi:include href="ref-bitbake.xml"/> 96 <xi:include href="ref-bitbake.xml"/>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-22 05:54:50 +0000