/[gentoo]/xml/htdocs/doc/en/gentoo-upgrading.xml
Gentoo

Diff of /xml/htdocs/doc/en/gentoo-upgrading.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.18 Revision 1.25
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-upgrading.xml,v 1.18 2005/01/25 11:48:14 neysx Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-upgrading.xml,v 1.25 2005/09/20 18:24:14 swift Exp $ -->
4 4
5<guide link="/doc/en/gentoo-upgrading.xml"> 5<guide link="/doc/en/gentoo-upgrading.xml">
6<title>Gentoo Upgrading Guide</title> 6<title>Gentoo Upgrading Guide</title>
7 7
8<author title="Author"> 8<author title="Author">
12<abstract> 12<abstract>
13This document explains how new Gentoo releases affect existing installs. 13This document explains how new Gentoo releases affect existing installs.
14</abstract> 14</abstract>
15 15
16<!-- The content of this document is licensed under the CC-BY-SA license --> 16<!-- The content of this document is licensed under the CC-BY-SA license -->
17<!-- See http://creativecommons.org/licenses/by-sa/2.0 --> 17<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
18<license/> 18<license/>
19 19
20<version>2.8</version> 20<version>2.13</version>
21<date>2005-01-22</date> 21<date>2005-08-12</date>
22 22
23<chapter> 23<chapter>
24<title>Gentoo and Upgrades</title> 24<title>Gentoo and Upgrades</title>
25<section> 25<section>
26<title>Philosophy</title> 26<title>Philosophy</title>
37<p> 37<p>
38You know (being a Gentoo user after all) that this process is extremely 38You know (being a Gentoo user after all) that this process is extremely
39frustrating for power users that want to live on the bleeding edge. Even power 39frustrating for power users that want to live on the bleeding edge. Even power
40users from other distributions probably share the same feelings, given the 40users from other distributions probably share the same feelings, given the
41popularity and spread of tools like apt or apt-rpm which make it 41popularity and spread of tools like apt or apt-rpm which make it
42possible to have quick and frequent updates. However, no distibution is more 42possible to have quick and frequent updates. However, no distribution is more
43suited than Gentoo to satisfy these kind of demanding users. From the beginning, 43suited than Gentoo to satisfy these kind of demanding users. From the
44Gentoo was designed around the concept of fast, incremental updates. 44beginning, Gentoo was designed around the concept of fast, incremental
45updates.
45</p> 46</p>
46 47
47<p> 48<p>
48Ideally, you install once and never bother with releases: just follow the 49Ideally, you install once and never bother with releases: just follow the
49instructions in <uri 50instructions in <uri
66There are various reasons: 67There are various reasons:
67</p> 68</p>
68 69
69<ul> 70<ul>
70 <li> 71 <li>
71 A new release means new LiveCDs with bugfixes and more features. 72 A new release means new Installation CDs with bugfixes and more features.
72 </li> 73 </li>
73 <li> 74 <li>
74 A new release provides an updated set of GRP packages, so that users that 75 A new release provides an updated set of GRP packages, so that users that
75 choose "the fast way" to install (stage3 + precompiled packages) end up 76 choose "the fast way" to install (stage3 + precompiled packages) end up
76 with a system that is not outdated. 77 with a system that is not outdated.
95</p> 96</p>
96 97
97<p> 98<p>
98The profile in use is determined by the symbolic link 99The profile in use is determined by the symbolic link
99<path>/etc/make.profile</path>, which points to a subdirectory of 100<path>/etc/make.profile</path>, which points to a subdirectory of
100<path>/usr/portage/profiles</path> which holds the profile files. For instance, 101<path>/usr/portage/profiles</path> which holds the profile files. For
101the x86 2004.2 profile can be found at <path>/usr/portage/profiles/default-x86-2004.2</path> 102instance, the default x86 2005.1 profile can be found
102(old-style location) or at <path>/usr/portage/profiles/default-linux/x86/2004.2</path> (new-style 103at <path>/usr/portage/profiles/default-linux/x86/2005.1</path>.
103location - only for use with Portage 2.0.51 and later). With respect to new-style profile directories, note that the files in 104The files in the parent directories are part of the profile as well (and
104parent directories are part of the profile (and are therefore shared 105are therefore shared by different subprofiles). This is why we call these
105by different subprofiles). 106<e>cascaded profiles</e>.
106</p> 107</p>
107 108
108<p> 109<p>
109Profiles obsoleted by new ones are kept in <path>/usr/portage/profiles</path> 110Profiles obsoleted by new ones are kept in <path>/usr/portage/profiles</path>
110along with the current ones, but they are marked as deprecated. When that happens a 111along with the current ones, but they are marked as deprecated. When that
111file named <path>deprecated</path> is put in the profile directory. The content 112happens a file named <path>deprecated</path> is put in the profile directory.
112of this file is the name of the profile that should be "upgraded to"; portage uses 113The content of this file is the name of the profile that should be "upgraded
113this information to automatically warn you when you should update to a new profile. 114to"; portage uses this information to automatically warn you when you should
114</p> 115update to a new profile.
115
116<p> 116</p>
117
118<p>
117There are various reasons that a new profile may be created: the release of new 119There are various reasons that a new profile may be created: the release of
118versions of core packages (such as <c>baselayout</c>, <c>gcc</c>, or <c>glibc</c>) 120new versions of core packages (such as <c>baselayout</c>, <c>gcc</c>, or
119that are incompatible with previous versions, a change in the default USE flags or 121<c>glibc</c>) that are incompatible with previous versions, a change in
120in the virtual mappings, or maybe a change in system-wide settings (such as defining 122the default USE flags or in the virtual mappings, or maybe a change in
121udev to be the default manager for <path>/dev</path> instead of devfs). 123system-wide settings.
122</p> 124</p>
123 125
124</body> 126</body>
125</section> 127</section>
126</chapter> 128</chapter>
130<section> 132<section>
131<title>Releases without profile changes</title> 133<title>Releases without profile changes</title>
132<body> 134<body>
133 135
134<p> 136<p>
135If a new Gentoo release is announced that does not include a new profile (such 137If a new Gentoo release is announced that does not include a new profile
136as the 2004.1 release for x86), then you can safely pretend that it never 138then you can safely pretend that it never happened :).
137happened :).
138</p> 139</p>
139 140
140<p> 141<p>
141If you update your installed packages 142If you update your installed packages
142<uri link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=1">as explained in 143<uri link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=1">as explained in
149<section> 150<section>
150<title>Releases with profile changes</title> 151<title>Releases with profile changes</title>
151<body> 152<body>
152 153
153<p> 154<p>
154If a release introduces a new profile, you have the choice to migrate to the 155If a release (such as 2005.1 for x86) introduces a new profile, you have the
155new profile. 156choice to migrate to the new profile.
156</p>
157
158<p> 157</p>
158
159<p>
159Naturally, you are not forced to do so, and you can continue to use the old profile 160Naturally, you are not forced to do so, and you can continue to use the old
160and just update your packages 161profile and just update your packages
161<uri link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=1">as explained in 162<uri link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=1">as explained
162the Gentoo Handbook</uri>. 163in the Gentoo Handbook</uri>.
163</p>
164
165<p> 164</p>
165
166<p>
166However, Gentoo strongly recommends updating your profile if it becomes deprecated. 167However, Gentoo strongly recommends updating your profile if it becomes
167When this happens, it means that Gentoo developers no longer plan on supporting it. 168deprecated. When this happens, it means that Gentoo developers no longer
168Using the table below, you can quickly check to see what profiles are currently supported. 169plan on supporting it. Using the table below, you can quickly check to
170see what profiles are currently supported.
169</p> 171</p>
170 172
171<p> 173<p>
172If you decide to migrate to the new profile, then you will have to manually 174If you decide to migrate to the new profile, then you will have to manually
173perform the update. The way you update may vary significantly from release to release; it 175perform the update. The way you update may vary significantly from release
174depends on how deep the modifications introduced in the new profile are. 176to release; it depends on how deep the modifications introduced in the new
177profile are.
175</p> 178</p>
176 179
177<p> 180<p>
178In the simplest case you only have to change the <path>/etc/make.profile</path> 181In the simplest case you only have to change the <path>/etc/make.profile</path>
179symlink, in the worst case you may have to recompile your system from scratch 182symlink, in the worst case you may have to recompile your system from scratch
180while doing a neat voodoo dance. Migration is usually covered in the release 183while doing a neat voodoo dance. Migration is usually covered in the release
181notes (e.g. <uri 184notes. You can also find <uri link="#instructions">instructions</uri> at the
182link="/proj/en/releng/release/2004.3/x86-release-notes.xml">the x86 2004.3 185end of this guide.
183release notes</uri>). You can also find <uri
184link="#instructions">instructions</uri> at the end of this guide.
185</p> 186</p>
186 187
187</body> 188</body>
188</section> 189</section>
189<section> 190<section>
195</p> 196</p>
196 197
197<table> 198<table>
198<tr> 199<tr>
199 <th>Architecture</th> 200 <th>Architecture</th>
200 <th>Most recent profile</th> 201 <th>Most recent profiles</th>
201 <th>Other supported profiles</th> 202 <th>Other supported profiles</th>
202</tr> 203</tr>
203<tr> 204<tr>
204 <th>alpha</th> 205 <th>alpha</th>
205 <ti>2004.3</ti> 206 <ti>2005.0, 2005.0/2.4</ti>
206 <ti></ti> 207 <ti></ti>
207</tr> 208</tr>
208<tr> 209<tr>
209 <th>arm</th> 210 <th>arm</th>
210 <ti>2004.3</ti> 211 <ti>2004.3</ti>
211 <ti></ti> 212 <ti></ti>
212</tr> 213</tr>
213<tr> 214<tr>
214 <th>amd64</th> 215 <th>amd64</th>
216 <ti>2005.1, 2005.1/no-multilib</ti>
217 <ti>2005.0, 2005.0/no-multilib, 2004.3</ti>
218</tr>
219<tr>
220 <th>hppa</th>
221 <ti>2005.0, 2005.0/2.4</ti>
222 <ti>2004.3, 2004.2</ti>
223</tr>
224<tr>
225 <th>ia64</th>
226 <ti>2005.0</ti>
215 <ti>2004.3</ti> 227 <ti>2004.3</ti>
216 <ti>2004.2, 2004.0</ti>
217</tr>
218<tr> 228</tr>
229<tr>
219 <th>hppa</th> 230 <th>ppc</th>
220 <ti>2004.3</ti> 231 <ti>2005.1</ti>
232 <ti>2005.0, 2004.3, 2004.0</ti>
233</tr>
234<tr>
235 <th>mips</th>
236 <ti>2005.0</ti>
221 <ti>2004.2</ti> 237 <ti>2004.2</ti>
222</tr>
223<tr>
224 <th>ia64</th>
225 <ti>2004.3</ti>
226 <ti></ti>
227</tr>
228<tr>
229 <th>ppc</th>
230 <ti>2004.3</ti>
231 <ti>2004.0</ti>
232</tr>
233<tr>
234 <th>mips</th>
235 <ti>2004.2</ti>
236 <ti></ti>
237</tr> 238</tr>
238<tr> 239<tr>
239 <th>s390</th> 240 <th>s390</th>
240 <ti>2004.3</ti> 241 <ti>2004.3</ti>
241 <ti></ti> 242 <ti></ti>
242</tr> 243</tr>
243<tr> 244<tr>
244 <th>sparc</th> 245 <th>sparc</th>
245 <ti>2004.3</ti> 246 <ti>2005.1</ti>
246 <ti>2004.0</ti> 247 <ti>2005.0</ti>
247</tr> 248</tr>
248<tr> 249<tr>
249 <th>x86</th> 250 <th>x86</th>
250 <ti>2004.3</ti> 251 <ti>2005.1, 2005.1/2.4</ti>
251 <ti>2004.2, 2004.0</ti> 252 <ti>2005.0, 2005.0/2.4</ti>
252</tr> 253</tr>
253</table> 254</table>
254 255
255</body> 256</body>
256</section> 257</section>
257</chapter> 258</chapter>
258 259
259<chapter id="instructions"> 260<chapter id="instructions">
260<title>Profile updating instructions</title> 261<title>Profile updating instructions</title>
262<section>
263<title>Updating to 2005.1</title>
264<body>
265
266<p>
267To switch to the 2005.1 profile, point the <path>/etc/make.profile</path>
268symlink to the new location. Make sure your Portage is updated before you
269change your profile.
270</p>
271
272<pre caption="Changing to a 2005.1 profile">
273# <i>rm /etc/make.profile</i>
274# <i>ln -s ../usr/portage/profiles/</i>&lt;selected profile&gt;<i> /etc/make.profile</i>
275</pre>
276
277<p>
278<b>All archs</b> - There are no fundamental changes in this profile. No
279specific action needs to be performed.
280</p>
281
282<p>
283<b>ppc</b> - With the 2005.1 release, the ppc and ppc64 profiles were merged
284and a number of subprofiles for specific subarchitectures were created. Make
285sure you choose the correct subprofile for your system when migrating to a
2862005.1 profile.
287</p>
288
289</body>
290</section>
291<section>
292<title>Updating to 2005.0</title>
293<body>
294
295<p>
296With the introduction of 2005.0, several architectures have decided to define
297additional profiles. Make sure you read the description of said profiles before
298you decide to migrate to one of them. Most architectures now also default to the
2992.6 kernel tree where 2.4 was chosen previously.
300</p>
301
302<p>
303Some architectures require a bit more actions to be completed in order to
304convert from one profile to another. If that is the case, the step-by-step
305guides are linked from the table.
306</p>
307
308<table>
309<tr>
310 <th>Profile</th>
311 <th>Description</th>
312 <th>Specific Upgrade Guide</th>
313</tr>
314<tr>
315 <ti>default-linux/alpha/2005.0</ti>
316 <ti>Default Alpha 2005.0 profile for 2.6 kernels</ti>
317 <ti></ti>
318</tr>
319<tr>
320 <ti>default-linux/alpha/2005.0/2.4</ti>
321 <ti>Alpha 2005.0 profile for 2.4 kernels</ti>
322 <ti></ti>
323</tr>
324<tr>
325 <ti>default-linux/amd64/2005.0</ti>
326 <ti>Default AMD64 2005.0 profile for 2.6 kernels</ti>
327 <ti>
328 <uri
329 link="/proj/en/base/amd64/howtos/index.xml?part=1&amp;chap=1#doc_chap1">Upgrading to
330 2005.0</uri>
331 </ti>
332</tr>
333<tr>
334 <ti>default-linux/amd64/2005.0/no-multilib</ti>
335 <ti>AMD64 2005.0 profile for multilib-disabled system installations</ti>
336 <ti>
337 <uri link="/proj/en/base/amd64/howtos/index.xml?part=1&amp;chap=1#doc_chap5">Upgrading to
338 2005.0</uri>
339 </ti>
340</tr>
341<tr>
342 <ti>default-linux/arm/2005.0</ti>
343 <ti>Default ARM 2005.0 profile for 2.6 kernels</ti>
344 <ti></ti>
345</tr>
346<tr>
347 <ti>default-linux/hppa/2005.0</ti>
348 <ti>Default HPPA 2005.0 profile for 2.6 kernels</ti>
349 <ti></ti>
350</tr>
351<tr>
352 <ti>default-linux/hppa/2005.0/2.4</ti>
353 <ti>HPPA 2005.0 profile for 2.4 kernels</ti>
354 <ti></ti>
355</tr>
356<tr>
357 <ti>default-linux/mips/2005.0</ti>
358 <ti>Default MIPS 2005.0 profile</ti>
359 <ti></ti>
360</tr>
361<tr>
362 <ti>default-linux/mips/cobalt/2005.0</ti>
363 <ti>Cobalt specific MIPS 2005.0 profile</ti>
364 <ti></ti>
365</tr>
366<tr>
367 <ti>default-linux/mips/mips64/n32/2005.0</ti>
368 <ti>2005.0 profile for n32-supporting MIPS platforms</ti>
369 <ti></ti>
370</tr>
371<tr>
372 <ti>default-linux/mips/mips64/ip28/2005.0</ti>
373 <ti>Indigo2 Impact specific 64-bit 2005.0 profile</ti>
374 <ti></ti>
375</tr>
376<tr>
377 <ti>default-linux/mips/mips64/2005.0</ti>
378 <ti>64-bit MIPS 2005.0 profile</ti>
379 <ti></ti>
380</tr>
381<tr>
382 <ti>default-linux/ppc/2005.0</ti>
383 <ti>Default PPC 2005.0 profile for 2.6 kernels</ti>
384 <ti></ti>
385</tr>
386<tr>
387 <ti>default-linux/ppc64/2005.0</ti>
388 <ti>Default PPC64 2005.0 profile for 2.6 kernels</ti>
389 <ti></ti>
390</tr>
391<tr>
392 <ti>default-linux/s390/2005.0</ti>
393 <ti>Default S390 2005.0 profile</ti>
394 <ti></ti>
395</tr>
396<tr>
397 <ti>default-linux/sparc/sparc32/2005.0</ti>
398 <ti>Default Sparc 32-bit 2005.0 profile</ti>
399 <ti></ti>
400</tr>
401<!-- http://dev.gentoo.org/~dsd/kernel-2.6.htm
402 No subprofiles for sparc
403<tr>
404 <ti>default-linux/sparc/sparc32/2005.0/2.6</ti>
405 <ti>Sparc 32-bit 2005.0 profile for 2.6 kernels</ti>
406 <ti></ti>
407</tr>
408-->
409<tr>
410 <ti>default-linux/sparc/sparc64/2005.0</ti>
411 <ti>Default Sparc 64-bit 2005.0 profile</ti>
412 <ti></ti>
413</tr>
414<!-- http://dev.gentoo.org/~dsd/kernel-2.6.htm
415 No subprofiles for sparc
416<tr>
417 <ti>default-linux/sparc/sparc64/2005.0/2.6</ti>
418 <ti>Sparc 64-bit 2005.0 profile for 2.6 kernels</ti>
419 <ti></ti>
420</tr>
421-->
422<tr>
423 <ti>default-linux/x86/2005.0</ti>
424 <ti>Default x86 2005.0 profile for 2.6 kernels</ti>
425 <ti></ti>
426</tr>
427<tr>
428 <ti>default-linux/x86/2005.0/2.4</ti>
429 <ti>x86 2005.0 profile for 2.4 kernels</ti>
430 <ti></ti>
431</tr>
432</table>
433
434<p>
435To switch to the selected profile, point the <path>/etc/make.profile</path>
436symlink to the new location. Make sure your Portage is updated before you change
437your profile!
438</p>
439
440<pre caption="Changing to a 2005.0 profile">
441# <i>rm /etc/make.profile</i>
442# <i>ln -s ../usr/portage/profiles/</i>&lt;selected profile&gt;<i> /etc/make.profile</i>
443</pre>
444
445<p>
446If you are running a Linux 2.4-based system but want to migrate to a 2.6-based
447kernel, make sure you read our <uri link="/doc/en/migration-to-2.6.xml">Gentoo
448Linux 2.6 Migration Guide</uri>.
449</p>
450
451</body>
452</section>
261<section> 453<section>
262<title>Updating to 2004.3</title> 454<title>Updating to 2004.3</title>
263<body> 455<body>
264 456
265<p> 457<p>
297<path>/var/lib/portage/world</path> after the profile switch, or manually 489<path>/var/lib/portage/world</path> after the profile switch, or manually
298emerge them. 490emerge them.
299</p> 491</p>
300 492
301<p> 493<p>
302<b>ppc</b> - <c>sys-fs/udev</c> is now the default instead of <c>sys-fs/devfs</c> 494<b>ppc</b> - <c>sys-fs/udev</c> is now the default instead of
303for newly installed machines. This has no effect on already installed machines, 495<c>sys-fs/devfs</c> for newly installed machines. This has no
304though. 496effect on already installed machines, though.
497</p>
498
499</body>
500</section>
501<section>
502<title>Updating Portage to Support Cascading Profiles</title>
503<body>
504
305</p> 505<p>
506Although this section does not seem to integrate well in this upgrading guide,
507it is quite important. Any profile listed above this section requires a Portage
508version that supports cascading profiles. However, some obsoleted profiles don't
509allow the user to upgrade Portage or the user is using a profile that isn't
510available anymore - any attempt to upgrade Portage will result in a failure.
511</p>
512
513<p>
514To work around this problem, users can set a temporary symbolic link to the
515<e>obsolete</e> profile, allowing them to upgrade their Portage after which
516they can continue with the upgrade procedure set forth in this guide:
517</p>
518
519<pre caption="Updating Portage through the obsolete profile">
520# <i>rm /etc/make.profile</i>
521# <i>cd /etc</i>
522# <i>ln -sf ../usr/portage/profiles/obsolete make.profile</i>
523# <i>emerge -n '>=sys-apps/portage-2.0.51'</i>
524</pre>
306 525
307</body> 526</body>
308</section> 527</section>
309<section> 528<section>
310<title>Updating to 2004.2</title> 529<title>Updating to 2004.2</title>
311<body> 530<body>
312 531
313<p> 532<p>
314To switch to the 2004.2 profile, point the <path>/etc/make.profile</path> symlink 533To switch to the 2004.2 profile, point the <path>/etc/make.profile</path>
315to the new location: 534symlink to the new location:
316</p> 535</p>
317 536
318<warn> 537<warn>
319Don't forget to upgrade Portage <e>before</e> you change your profile!!! 538Don't forget to upgrade Portage <e>before</e> you change your profile!!!
320</warn> 539</warn>
344<section> 563<section>
345<title>Updating to 2004.0</title> 564<title>Updating to 2004.0</title>
346<body> 565<body>
347 566
348<p> 567<p>
349To switch to the 2004.0 profile, point the <path>/etc/make.profile</path> symlink 568To switch to the 2004.0 profile, point the <path>/etc/make.profile</path>
350to the new location: 569symlink to the new location:
351</p> 570</p>
352 571
353<pre caption="Updating the /etc/make.profile symlink"> 572<pre caption="Updating the /etc/make.profile symlink">
354<comment>substitute &lt;arch&gt; with your arch</comment> 573<comment>substitute &lt;arch&gt; with your arch</comment>
355# <i>rm /etc/make.profile</i> 574# <i>rm /etc/make.profile</i>

Legend:
Removed from v.1.18  
changed lines
  Added in v.1.25

  ViewVC Help
Powered by ViewVC 1.1.20