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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.28 - (hide annotations) (download) (as text)
Sun Feb 12 18:51:35 2006 UTC (8 years, 10 months ago) by rane
Branch: MAIN
Changes since 1.27: +5 -12 lines
File MIME type: application/xml
removing references to the nonexistent amd64 upgrading howtos

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 rane 1.28 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-upgrading.xml,v 1.27 2005/12/19 11:49:16 jkt Exp $ -->
4 swift 1.1
5     <guide link="/doc/en/gentoo-upgrading.xml">
6     <title>Gentoo Upgrading Guide</title>
7    
8     <author title="Author">
9 neysx 1.18 <mail link="greg_g@gentoo.org">Gregorio Guidi</mail>
10 swift 1.1 </author>
11    
12     <abstract>
13 vapier 1.7 This document explains how new Gentoo releases affect existing installs.
14 swift 1.1 </abstract>
15    
16     <!-- The content of this document is licensed under the CC-BY-SA license -->
17 neysx 1.24 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
18 swift 1.1 <license/>
19    
20 rane 1.28 <version>2.2</version>
21     <date>2005-02-12</date>
22 swift 1.1
23     <chapter>
24     <title>Gentoo and Upgrades</title>
25     <section>
26     <title>Philosophy</title>
27     <body>
28    
29     <p>
30 vapier 1.7 Here in Gentoo land, the concept of upgrading is quite different compared to
31     the rest of the Linux world. You probably already know that we never got in
32     touch with the "classic" way of upgrading software: waiting for a new release,
33     downloading it, burning, putting it in the cdrom drive and then following the
34     upgrade instructions.
35 swift 1.1 </p>
36    
37     <p>
38 vapier 1.7 You know (being a Gentoo user after all) that this process is extremely
39     frustrating for power users that want to live on the bleeding edge. Even power
40     users from other distributions probably share the same feelings, given the
41     popularity and spread of tools like apt or apt-rpm which make it
42 vanquirius 1.23 possible to have quick and frequent updates. However, no distribution is more
43 swift 1.19 suited than Gentoo to satisfy these kind of demanding users. From the
44     beginning, Gentoo was designed around the concept of fast, incremental
45     updates.
46 swift 1.1 </p>
47    
48     <p>
49 neysx 1.16 Ideally, you install once and never bother with releases: just follow the
50     instructions in <uri
51     link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=1">A Portage
52     Introduction</uri> in the <uri link="/doc/en/handbook/">Gentoo Handbook</uri>
53     that explain how to keep your system up to date. While that's the way things
54     usually go, sometimes changes are made to the core system which require updates
55     to be done manually.
56 swift 1.1 </p>
57    
58     </body>
59     </section>
60     <section>
61     <title>Releases and Profiles</title>
62     <body>
63    
64     <p>
65     A recurring question about the Gentoo release process is: "Why roll out new
66     releases frequently, if they are not intended to let users update software?".
67     There are various reasons:
68     </p>
69    
70     <ul>
71     <li>
72 vanquirius 1.23 A new release means new Installation CDs with bugfixes and more features.
73 swift 1.1 </li>
74     <li>
75     A new release provides an updated set of GRP packages, so that users that
76 neysx 1.12 choose "the fast way" to install (stage3 + precompiled packages) end up
77 swift 1.1 with a system that is not outdated.
78     </li>
79     <li>
80 vapier 1.7 Finally, a new release may, from time to time, implement some features that
81 swift 1.1 are incompatible with previous releases.
82     </li>
83     </ul>
84    
85     <p>
86 vapier 1.7 When a release includes new incompatible features, or provides a set of core
87     packages and settings that deeply modify the behavior of the system, we say
88     that it provides a new <e>profile</e>.
89 swift 1.1 </p>
90    
91     <p>
92     A <e>profile</e> is a set of configuration files, stored in a subdirectory of
93 neysx 1.12 <path>/usr/portage/profiles</path>, that describe things such as the ebuilds
94 swift 1.1 that are considered <e>system</e> packages, the default USE flags, the default
95 neysx 1.12 mapping for virtual packages, and the architecture on which the system is running.
96 swift 1.1 </p>
97    
98     <p>
99     The profile in use is determined by the symbolic link
100 vapier 1.7 <path>/etc/make.profile</path>, which points to a subdirectory of
101 swift 1.19 <path>/usr/portage/profiles</path> which holds the profile files. For
102 neysx 1.24 instance, the default x86 2005.1 profile can be found
103     at <path>/usr/portage/profiles/default-linux/x86/2005.1</path>.
104 swift 1.20 The files in the parent directories are part of the profile as well (and
105     are therefore shared by different subprofiles). This is why we call these
106     <e>cascaded profiles</e>.
107 swift 1.1 </p>
108    
109     <p>
110     Profiles obsoleted by new ones are kept in <path>/usr/portage/profiles</path>
111 swift 1.19 along with the current ones, but they are marked as deprecated. When that
112     happens a file named <path>deprecated</path> is put in the profile directory.
113     The content of this file is the name of the profile that should be "upgraded
114     to"; portage uses this information to automatically warn you when you should
115     update to a new profile.
116 swift 1.1 </p>
117    
118     <p>
119 swift 1.19 There are various reasons that a new profile may be created: the release of
120     new versions of core packages (such as <c>baselayout</c>, <c>gcc</c>, or
121     <c>glibc</c>) that are incompatible with previous versions, a change in
122     the default USE flags or in the virtual mappings, or maybe a change in
123 neysx 1.24 system-wide settings.
124 swift 1.1 </p>
125    
126     </body>
127     </section>
128     </chapter>
129    
130     <chapter>
131     <title>Keeping up with new releases</title>
132     <section>
133     <title>Releases without profile changes</title>
134     <body>
135    
136     <p>
137 swift 1.20 If a new Gentoo release is announced that does not include a new profile
138     then you can safely pretend that it never happened :).
139 swift 1.1 </p>
140    
141     <p>
142 vapier 1.7 If you update your installed packages
143 neysx 1.11 <uri link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=1">as explained in
144 swift 1.1 the Gentoo Handbook</uri>, then your system will be exactly the same as one
145     that has been installed using the new release.
146     </p>
147    
148     </body>
149     </section>
150     <section>
151     <title>Releases with profile changes</title>
152     <body>
153    
154     <p>
155 neysx 1.24 If a release (such as 2005.1 for x86) introduces a new profile, you have the
156     choice to migrate to the new profile.
157 swift 1.1 </p>
158    
159     <p>
160 swift 1.19 Naturally, you are not forced to do so, and you can continue to use the old
161     profile and just update your packages
162     <uri link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=1">as explained
163     in the Gentoo Handbook</uri>.
164 swift 1.1 </p>
165    
166     <p>
167 swift 1.19 However, Gentoo strongly recommends updating your profile if it becomes
168     deprecated. When this happens, it means that Gentoo developers no longer
169     plan on supporting it. Using the table below, you can quickly check to
170     see what profiles are currently supported.
171 swift 1.1 </p>
172    
173     <p>
174     If you decide to migrate to the new profile, then you will have to manually
175 swift 1.19 perform the update. The way you update may vary significantly from release
176     to release; it depends on how deep the modifications introduced in the new
177     profile are.
178 swift 1.1 </p>
179    
180     <p>
181     In the simplest case you only have to change the <path>/etc/make.profile</path>
182 vapier 1.7 symlink, in the worst case you may have to recompile your system from scratch
183 neysx 1.12 while doing a neat voodoo dance. Migration is usually covered in the release
184 swift 1.20 notes. You can also find <uri link="#instructions">instructions</uri> at the
185     end of this guide.
186 swift 1.1 </p>
187    
188     </body>
189     </section>
190     <section>
191     <title>Supported profiles</title>
192     <body>
193    
194     <p>
195     The following profiles are officially supported by Gentoo developers:
196     </p>
197    
198     <table>
199     <tr>
200     <th>Architecture</th>
201 swift 1.20 <th>Most recent profiles</th>
202 swift 1.1 <th>Other supported profiles</th>
203     </tr>
204     <tr>
205 neysx 1.12 <th>alpha</th>
206 swift 1.20 <ti>2005.0, 2005.0/2.4</ti>
207 neysx 1.24 <ti></ti>
208 neysx 1.12 </tr>
209     <tr>
210 vapier 1.7 <th>arm</th>
211 neysx 1.12 <ti>2004.3</ti>
212 neysx 1.24 <ti></ti>
213 vapier 1.7 </tr>
214     <tr>
215     <th>amd64</th>
216 neysx 1.24 <ti>2005.1, 2005.1/no-multilib</ti>
217     <ti>2005.0, 2005.0/no-multilib, 2004.3</ti>
218 swift 1.1 </tr>
219     <tr>
220 neysx 1.12 <th>hppa</th>
221 swift 1.20 <ti>2005.0, 2005.0/2.4</ti>
222     <ti>2004.3, 2004.2</ti>
223 swift 1.1 </tr>
224     <tr>
225 neysx 1.12 <th>ia64</th>
226 swift 1.20 <ti>2005.0</ti>
227 neysx 1.24 <ti>2004.3</ti>
228 swift 1.1 </tr>
229     <tr>
230     <th>ppc</th>
231 neysx 1.24 <ti>2005.1</ti>
232     <ti>2005.0, 2004.3, 2004.0</ti>
233 swift 1.1 </tr>
234     <tr>
235     <th>mips</th>
236 swift 1.20 <ti>2005.0</ti>
237 neysx 1.12 <ti>2004.2</ti>
238 swift 1.1 </tr>
239     <tr>
240 neysx 1.12 <th>s390</th>
241     <ti>2004.3</ti>
242 neysx 1.24 <ti></ti>
243 swift 1.9 </tr>
244     <tr>
245 neysx 1.12 <th>sparc</th>
246 neysx 1.24 <ti>2005.1</ti>
247 swift 1.20 <ti>2005.0</ti>
248 swift 1.1 </tr>
249 dertobi123 1.5 <tr>
250 vapier 1.7 <th>x86</th>
251 neysx 1.24 <ti>2005.1, 2005.1/2.4</ti>
252 swift 1.20 <ti>2005.0, 2005.0/2.4</ti>
253 dertobi123 1.5 </tr>
254 swift 1.1 </table>
255    
256     </body>
257     </section>
258     </chapter>
259    
260 neysx 1.12 <chapter id="instructions">
261 swift 1.1 <title>Profile updating instructions</title>
262     <section>
263 neysx 1.24 <title>Updating to 2005.1</title>
264     <body>
265    
266     <p>
267     To switch to the 2005.1 profile, point the <path>/etc/make.profile</path>
268     symlink to the new location. Make sure your Portage is updated before you
269     change 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
279     specific 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
284     and a number of subprofiles for specific subarchitectures were created. Make
285     sure you choose the correct subprofile for your system when migrating to a
286     2005.1 profile.
287     </p>
288    
289     </body>
290     </section>
291     <section>
292 swift 1.20 <title>Updating to 2005.0</title>
293     <body>
294    
295     <p>
296     With the introduction of 2005.0, several architectures have decided to define
297     additional profiles. Make sure you read the description of said profiles before
298     you decide to migrate to one of them. Most architectures now also default to the
299     2.6 kernel tree where 2.4 was chosen previously.
300     </p>
301    
302     <p>
303     Some architectures require a bit more actions to be completed in order to
304     convert from one profile to another. If that is the case, the step-by-step
305     guides 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 rane 1.28 <ti></ti>
328 swift 1.20 </tr>
329     <tr>
330     <ti>default-linux/amd64/2005.0/no-multilib</ti>
331     <ti>AMD64 2005.0 profile for multilib-disabled system installations</ti>
332 rane 1.28 <ti></ti>
333 swift 1.20 </tr>
334     <tr>
335     <ti>default-linux/arm/2005.0</ti>
336     <ti>Default ARM 2005.0 profile for 2.6 kernels</ti>
337     <ti></ti>
338     </tr>
339     <tr>
340     <ti>default-linux/hppa/2005.0</ti>
341     <ti>Default HPPA 2005.0 profile for 2.6 kernels</ti>
342     <ti></ti>
343     </tr>
344     <tr>
345     <ti>default-linux/hppa/2005.0/2.4</ti>
346     <ti>HPPA 2005.0 profile for 2.4 kernels</ti>
347     <ti></ti>
348     </tr>
349     <tr>
350     <ti>default-linux/mips/2005.0</ti>
351     <ti>Default MIPS 2005.0 profile</ti>
352     <ti></ti>
353     </tr>
354     <tr>
355     <ti>default-linux/mips/cobalt/2005.0</ti>
356     <ti>Cobalt specific MIPS 2005.0 profile</ti>
357     <ti></ti>
358     </tr>
359     <tr>
360     <ti>default-linux/mips/mips64/n32/2005.0</ti>
361     <ti>2005.0 profile for n32-supporting MIPS platforms</ti>
362     <ti></ti>
363     </tr>
364     <tr>
365     <ti>default-linux/mips/mips64/ip28/2005.0</ti>
366     <ti>Indigo2 Impact specific 64-bit 2005.0 profile</ti>
367     <ti></ti>
368     </tr>
369     <tr>
370     <ti>default-linux/mips/mips64/2005.0</ti>
371     <ti>64-bit MIPS 2005.0 profile</ti>
372     <ti></ti>
373     </tr>
374     <tr>
375     <ti>default-linux/ppc/2005.0</ti>
376     <ti>Default PPC 2005.0 profile for 2.6 kernels</ti>
377     <ti></ti>
378     </tr>
379     <tr>
380     <ti>default-linux/ppc64/2005.0</ti>
381     <ti>Default PPC64 2005.0 profile for 2.6 kernels</ti>
382     <ti></ti>
383     </tr>
384     <tr>
385     <ti>default-linux/s390/2005.0</ti>
386     <ti>Default S390 2005.0 profile</ti>
387     <ti></ti>
388     </tr>
389     <tr>
390     <ti>default-linux/sparc/sparc32/2005.0</ti>
391     <ti>Default Sparc 32-bit 2005.0 profile</ti>
392     <ti></ti>
393     </tr>
394     <!-- http://dev.gentoo.org/~dsd/kernel-2.6.htm
395     No subprofiles for sparc
396     <tr>
397     <ti>default-linux/sparc/sparc32/2005.0/2.6</ti>
398     <ti>Sparc 32-bit 2005.0 profile for 2.6 kernels</ti>
399     <ti></ti>
400     </tr>
401     -->
402     <tr>
403     <ti>default-linux/sparc/sparc64/2005.0</ti>
404     <ti>Default Sparc 64-bit 2005.0 profile</ti>
405     <ti></ti>
406     </tr>
407     <!-- http://dev.gentoo.org/~dsd/kernel-2.6.htm
408     No subprofiles for sparc
409     <tr>
410     <ti>default-linux/sparc/sparc64/2005.0/2.6</ti>
411     <ti>Sparc 64-bit 2005.0 profile for 2.6 kernels</ti>
412     <ti></ti>
413     </tr>
414     -->
415     <tr>
416     <ti>default-linux/x86/2005.0</ti>
417     <ti>Default x86 2005.0 profile for 2.6 kernels</ti>
418     <ti></ti>
419     </tr>
420     <tr>
421     <ti>default-linux/x86/2005.0/2.4</ti>
422     <ti>x86 2005.0 profile for 2.4 kernels</ti>
423     <ti></ti>
424     </tr>
425     </table>
426    
427     <p>
428     To switch to the selected profile, point the <path>/etc/make.profile</path>
429     symlink to the new location. Make sure your Portage is updated before you change
430     your profile!
431     </p>
432    
433     <pre caption="Changing to a 2005.0 profile">
434     # <i>rm /etc/make.profile</i>
435     # <i>ln -s ../usr/portage/profiles/</i>&lt;selected profile&gt;<i> /etc/make.profile</i>
436     </pre>
437    
438     <p>
439     If you are running a Linux 2.4-based system but want to migrate to a 2.6-based
440     kernel, make sure you read our <uri link="/doc/en/migration-to-2.6.xml">Gentoo
441     Linux 2.6 Migration Guide</uri>.
442     </p>
443    
444     </body>
445     </section>
446     <section>
447 neysx 1.12 <title>Updating to 2004.3</title>
448     <body>
449    
450     <p>
451     With the introduction of the 2004.3 profiles, users are not going to see huge
452     modifications of their systems (see below for details). However, Gentoo
453     developers decided to push out this new profile and to deprecate quite a few of
454     the old ones to speed up the adoption of <e>stacked profiles</e>, that is, the
455     profiles that follow the new layout of the <path>/usr/portage/profiles</path>
456     directory, for instance
457     <path>/usr/portage/profiles/default-linux/x86/2004.3</path> (supported by
458     Portage 2.0.51 or later).
459     </p>
460    
461     <p>
462     To switch to the 2004.3 profile, point the <path>/etc/make.profile</path>
463     symlink to the new location:
464     </p>
465    
466 swift 1.14 <warn>
467     Don't forget to upgrade Portage <e>before</e> you change your profile!!!
468     </warn>
469    
470 neysx 1.12 <pre caption="Updating the /etc/make.profile symlink">
471     <comment>substitute &lt;arch&gt; with your arch</comment>
472     # <i>rm /etc/make.profile</i>
473     # <i>ln -s ../usr/portage/profiles/default-linux/&lt;arch&gt;/2004.3 /etc/make.profile</i>
474     </pre>
475    
476     <p>
477     <b>All archs</b> - As said above, there are no big changes introduced in this
478     profile. However, it should be noted that <c>sys-apps/slocate</c> and
479     <c>net-misc/dhcpcd</c> are no longer considered system packages. This means
480 cam 1.17 that if you run <c>emerge --depclean</c>, Portage will try to remove them from
481 neysx 1.12 your system. If you need any of those packages, add them to
482     <path>/var/lib/portage/world</path> after the profile switch, or manually
483     emerge them.
484     </p>
485    
486     <p>
487 swift 1.19 <b>ppc</b> - <c>sys-fs/udev</c> is now the default instead of
488     <c>sys-fs/devfs</c> for newly installed machines. This has no
489     effect on already installed machines, though.
490 neysx 1.12 </p>
491    
492     </body>
493     </section>
494     <section>
495 swift 1.25 <title>Updating Portage to Support Cascading Profiles</title>
496     <body>
497    
498     <p>
499     Although this section does not seem to integrate well in this upgrading guide,
500     it is quite important. Any profile listed above this section requires a Portage
501     version that supports cascading profiles. However, some obsoleted profiles don't
502     allow the user to upgrade Portage or the user is using a profile that isn't
503     available anymore - any attempt to upgrade Portage will result in a failure.
504     </p>
505    
506     <p>
507     To work around this problem, users can set a temporary symbolic link to the
508     <e>obsolete</e> profile, allowing them to upgrade their Portage after which
509 jkt 1.27 they can continue with the upgrade procedure set forth in this guide. Please
510     substitute <c>&lt;arch&gt;</c> with your respective architecture:
511 swift 1.25 </p>
512    
513     <pre caption="Updating Portage through the obsolete profile">
514     # <i>rm /etc/make.profile</i>
515     # <i>cd /etc</i>
516 jkt 1.27 # <i>ln -sf ../usr/portage/profiles/obsolete/&lt;arch&gt; make.profile</i>
517 swift 1.25 # <i>emerge -n '>=sys-apps/portage-2.0.51'</i>
518     </pre>
519    
520     </body>
521     </section>
522     <section>
523 dertobi123 1.5 <title>Updating to 2004.2</title>
524 swift 1.1 <body>
525    
526     <p>
527 swift 1.19 To switch to the 2004.2 profile, point the <path>/etc/make.profile</path>
528     symlink to the new location:
529 swift 1.1 </p>
530    
531 swift 1.15 <warn>
532     Don't forget to upgrade Portage <e>before</e> you change your profile!!!
533     </warn>
534    
535 vapier 1.7 <pre caption="Updating the /etc/make.profile symlink">
536 dertobi123 1.5 <comment>substitute &lt;arch&gt; with your arch</comment>
537 swift 1.1 # <i>rm /etc/make.profile</i>
538 swift 1.8 # <i>ln -s ../usr/portage/profiles/default-linux/&lt;arch&gt;/2004.2 /etc/make.profile</i>
539 swift 1.1 </pre>
540    
541 dertobi123 1.5 <p>
542     <b>x86</b> - This profile changes the default X11 implementation from
543     <c>x11-base/xfree</c> to <c>x11-base/xorg-x11</c>. This change only touches
544     the <e>default</e> value, and is only relevant for those who have not installed
545     an X server yet. If you already have one installed, then it will not affect
546 vapier 1.7 you at all; you are free to switch from one X server to the other exactly as
547 dertobi123 1.5 before.
548     </p>
549    
550     <p>
551     <b>amd64</b> - There are no fundamental changes from previous profiles, no
552     specific action needs to be performed.
553     </p>
554    
555     </body>
556     </section>
557     <section>
558     <title>Updating to 2004.0</title>
559     <body>
560    
561     <p>
562 swift 1.19 To switch to the 2004.0 profile, point the <path>/etc/make.profile</path>
563     symlink to the new location:
564 dertobi123 1.5 </p>
565    
566 vapier 1.7 <pre caption="Updating the /etc/make.profile symlink">
567 dertobi123 1.5 <comment>substitute &lt;arch&gt; with your arch</comment>
568     # <i>rm /etc/make.profile</i>
569     # <i>ln -s ../usr/portage/profiles/default-&lt;arch&gt;-2004.0 /etc/make.profile</i>
570     </pre>
571    
572     <p>
573     <b>All archs</b> - There are no fundamental changes from previous profiles, no
574     specific action needs to be performed.
575     </p>
576    
577 swift 1.1 </body>
578     </section>
579     <section>
580     <title>Updating from profiles older than 1.4 to 1.4</title>
581     <body>
582    
583     <p>
584     The instructions for this upgrade are quite complex, you can find them
585     <uri link="/doc/en/new-upgrade-to-gentoo-1.4.xml">here</uri>.
586     </p>
587    
588     </body>
589     </section>
590     </chapter>
591    
592     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20