doc/en/new-upgrade-to-gentoo-1.4.xml

<?xml version="1.0" encoding="UTF-8"?>

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/new-upgrade-to-gentoo-1.4.xml,v 1.16 2006/03/06 09:18:30 neysx Exp $ -->

<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide link="/doc/en/new-upgrade-to-gentoo-1.4.xml">

<title>Gentoo 1.4 Upgrade Guide</title>

<author title="Author">
  <mail link="rac@gentoo.org">Robert Coie</mail>
</author>
<author title="Copy Editor">
  <mail link="avenj@gentoo.org">Jon Portnoy</mail>
</author>

<abstract>
A method for upgrading older Gentoo installations in place to Gentoo 1.4
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>0.4</version>
<date>2005-07-02</date>

<chapter>
<title>Before you begin</title>
<section>
<title>Be prepared</title>
<body>

<p>
As with any major upgrade to the core of your Gentoo system, there is always the
possibility that unforeseen problems will ensue. It is always prudent to back
up all important data before beginning this process. If possible, try to
allocate a large block of time for this upgrade, so that you will not feel
rushed. All the software on your machine will need to be recompiled.
</p>

</body>
</section>
<section>
<title>Other options</title>
<body>

<p>
This is not the only way to upgrade your system. You can install a new 1.4
system onto a separate partition and reuse some of your system configuration
instead. This method also has the advantage that you can always go back to your
old system in the meantime as a fallback. You may also decide to simply not
upgrade your system. If you decide you want to upgrade in place, read on.
</p>

</body>
</section>
<section>
<title>General notes</title>
<body>

<p>
Whenever the code listings suggest running the <c>emerge</c> command, it is
always a good idea to make a test run of the command using the <c>-p</c> or
<c>--pretend</c> option to make sure that the command will do what you expect it
to do.
</p>

</body>
</section>
</chapter>
<chapter>
<title>Upgrading in place</title>
<section>
<title>Get Portage as current as possible</title>
<body>

<p>
Some of the syntax of current ebuilds is unreadable by older versions of
Portage. If you don't have at least Portage 2.0.44, try upgrading Portage.
</p>

<pre caption="Updating Portage">
# <i>emerge --sync</i>
# <i>emerge -u portage</i>
</pre>

<note>
If your Portage version is very old, you may get an error message containing the
phrase "unscriptable object". Read and follow the instructions in
<path>/usr/portage/sys-apps/portage/files/README.RESCUE</path>. Your Portage
install should then be current.
</note>

</body>
</section>
<section>
<title>Preparing GCC for cohabitation</title>
<body>

<p>
You will be installing a newer version of GCC during this upgrade. Versions of
GCC older than 2.95.3-r8 are not designed to have multiple versions of GCC
installed. You must therefore upgrade GCC to at least version 2.95.3-r8. This
will also have the beneficial side-effect of installing the <c>gcc-config</c>
package on your system, which can be used to switch back and forth between
various installed versions of GCC.
</p>

<pre caption="Updating GCC">
# <i>emerge -u gcc</i>
</pre>

<p>
You can now check to see if gcc-config is working properly:
</p>

<pre caption="Verifying GCC profile">
# <i>gcc-config --get-current-profile</i>
</pre>

<p>
This should return i686-pc-linux-gnu-2.95.3 on most x86 systems. Older systems
may return i586-pc-linux-gnu-2.95.3.
</p>

</body>
</section>
<section>
<title>Installing GCC 3</title>
<body>

<p>
Now you can install a newer version of GCC without damaging your current
compiler. Look in <path>/usr/portage/sys-devel/gcc</path> for a version of the
GCC ebuild that is at least 3.2.1-r6. Choose the highest version that is marked
stable for your architecture. To see if an ebuild is considered stable for your
architecture, look for the KEYWORDS line in the ebuild file. If it has your
architecture listed without a ~ in front of it, it is considered stable.
Assuming 3.2.2 is the most current stable version, we first need to remove the
glibc dependency from gcc.
</p>

<p>
Edit <path>/usr/portage/sys-devel/gcc/gcc-3.2.2.ebuild</path> and search for the
line containing <c>DEPEND</c>. Remove the <c>glibc</c> dependency and save the
ebuild.
</p>

<pre caption="Editing gcc-3.2.2.ebuild">
# <i>vim /usr/portage/sys-devel/gcc/gcc-3.2.2.ebuild</i>
</pre>

<p>
Now install the latest GCC version on your system:
</p>

<pre caption="Install the latest GCC">
# <i>USE="-java" emerge /usr/portage/sys-devel/gcc/gcc-3.2.2.ebuild</i>
</pre>

</body>
</section>
<section>
<title>Changing profiles</title>
<body>

<p>
Now you need to change two sets of profiles: your gcc-config profile and your
Portage profile.
</p>

<pre caption="Change the Portage profile">
# <i>cd /etc</i>
# <i>rm make.profile</i>
<comment>(Replace "x86" with your architecture)</comment>
# <i>ln -s ../usr/portage/profiles/default-x86-1.4 make.profile</i>
</pre>

<pre caption="Change the GCC profile">
<comment>(Note the one for the version you just emerged, use it below)</comment>
# <i>gcc-config --list-profiles</i>
<comment>(Replace with the version you noted above)</comment>
# <i>gcc-config i686-pc-linux-gnu-3.2.2</i>
</pre>

</body>
</section>
<section>
<title>Recompile toolchain</title>
<body>

<p>
Now you need to recompile your core toolchain with your new compiler. If you
are continuing in the same shell, you need to run <c>source /etc/profile</c> as
gcc-config instructed you to. Then emerge glibc and binutils using your new
compiler:
</p>

<pre caption="Rebuilding the toolchain">
# <i>emerge glibc binutils</i>
</pre>

<warn>
It is quite likely that you will upgrade glibc from a 2.2 or older version to
2.3. Do not downgrade glibc afterwards. Any software you have compiled against
glibc 2.3 will stop working, and this can make your system unusable.
</warn>

</body>
</section>
<section>
<title>Recompiling everything with your new compiler</title>
<body>

<p>
Now you may recompile everything on your system with your new compiler:
</p>

<pre caption="Rebuilding the entire system">
# <i>emerge -e world</i>
</pre>

<note>
If this command fails at any point due to errors, you
can use <c>emerge --resume</c> to continue the process where
you left off.  This requires Portage 2.0.47 or later.
</note>

</body>
</section>
</chapter>
</guide>
1	neysx	1.13	<?xml version="1.0" encoding="UTF-8"?>
2
3	swift	1.17	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/new-upgrade-to-gentoo-1.4.xml,v 1.16 2006/03/06 09:18:30 neysx Exp $ -->
4	neysx	1.13
5	rac	1.1	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
6
7	neysx	1.16	<guide link="/doc/en/new-upgrade-to-gentoo-1.4.xml">
8	rac	1.1
9			<title>Gentoo 1.4 Upgrade Guide</title>
10
11	neysx	1.13	<author title="Author">
12			<mail link="rac@gentoo.org">Robert Coie</mail>
13	rac	1.1	</author>
14	neysx	1.13	<author title="Copy Editor">
15			<mail link="avenj@gentoo.org">Jon Portnoy</mail>
16	rac	1.1	</author>
17
18	swift	1.15	<abstract>
19			A method for upgrading older Gentoo installations in place to Gentoo 1.4
20			</abstract>
21	neysx	1.13
22			<!-- The content of this document is licensed under the CC-BY-SA license -->
23	swift	1.15	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
24	neysx	1.13	<license/>
25
26	swift	1.14	<version>0.4</version>
27			<date>2005-07-02</date>
28	neysx	1.13
29			<chapter>
30			<title>Before you begin</title>
31			<section>
32			<title>Be prepared</title>
33			<body>
34
35			<p>
36			As with any major upgrade to the core of your Gentoo system, there is always the
37			possibility that unforeseen problems will ensue. It is always prudent to back
38			up all important data before beginning this process. If possible, try to
39			allocate a large block of time for this upgrade, so that you will not feel
40			rushed. All the software on your machine will need to be recompiled.
41			</p>
42	rac	1.1
43	neysx	1.13	</body>
44			</section>
45			<section>
46			<title>Other options</title>
47			<body>
48
49			<p>
50			This is not the only way to upgrade your system. You can install a new 1.4
51			system onto a separate partition and reuse some of your system configuration
52			instead. This method also has the advantage that you can always go back to your
53			old system in the meantime as a fallback. You may also decide to simply not
54			upgrade your system. If you decide you want to upgrade in place, read on.
55			</p>
56
57			</body>
58			</section>
59			<section>
60			<title>General notes</title>
61			<body>
62
63			<p>
64			Whenever the code listings suggest running the <c>emerge</c> command, it is
65			always a good idea to make a test run of the command using the <c>-p</c> or
66			<c>--pretend</c> option to make sure that the command will do what you expect it
67			to do.
68			</p>
69	swift	1.4
70	neysx	1.13	</body>
71			</section>
72			</chapter>
73			<chapter>
74			<title>Upgrading in place</title>
75			<section>
76			<title>Get Portage as current as possible</title>
77			<body>
78	rac	1.1
79	neysx	1.13	<p>
80			Some of the syntax of current ebuilds is unreadable by older versions of
81			Portage. If you don't have at least Portage 2.0.44, try upgrading Portage.
82			</p>
83
84	swift	1.14	<pre caption="Updating Portage">
85	cam	1.11	# <i>emerge --sync</i>
86	rac	1.1	# <i>emerge -u portage</i>
87			</pre>
88
89	neysx	1.13	<note>
90			If your Portage version is very old, you may get an error message containing the
91			phrase "unscriptable object". Read and follow the instructions in
92			<path>/usr/portage/sys-apps/portage/files/README.RESCUE</path>. Your Portage
93			install should then be current.
94			</note>
95
96			</body>
97			</section>
98			<section>
99			<title>Preparing GCC for cohabitation</title>
100			<body>
101
102			<p>
103			You will be installing a newer version of GCC during this upgrade. Versions of
104			GCC older than 2.95.3-r8 are not designed to have multiple versions of GCC
105			installed. You must therefore upgrade GCC to at least version 2.95.3-r8. This
106			will also have the beneficial side-effect of installing the <c>gcc-config</c>
107			package on your system, which can be used to switch back and forth between
108			various installed versions of GCC.
109			</p>
110
111	swift	1.14	<pre caption="Updating GCC">
112	rac	1.1	# <i>emerge -u gcc</i>
113			</pre>
114
115	neysx	1.13	<p>
116			You can now check to see if gcc-config is working properly:
117			</p>
118
119	swift	1.14	<pre caption="Verifying GCC profile">
120	cam	1.8	# <i>gcc-config --get-current-profile</i>
121	rac	1.1	</pre>
122	neysx	1.13
123			<p>
124			This should return i686-pc-linux-gnu-2.95.3 on most x86 systems. Older systems
125			may return i586-pc-linux-gnu-2.95.3.
126			</p>
127
128			</body>
129			</section>
130			<section>
131			<title>Installing GCC 3</title>
132			<body>
133
134			<p>
135			Now you can install a newer version of GCC without damaging your current
136			compiler. Look in <path>/usr/portage/sys-devel/gcc</path> for a version of the
137			GCC ebuild that is at least 3.2.1-r6. Choose the highest version that is marked
138			stable for your architecture. To see if an ebuild is considered stable for your
139			architecture, look for the KEYWORDS line in the ebuild file. If it has your
140			architecture listed without a ~ in front of it, it is considered stable.
141			Assuming 3.2.2 is the most current stable version, we first need to remove the
142			glibc dependency from gcc.
143			</p>
144	swift	1.10
145			<p>
146			Edit <path>/usr/portage/sys-devel/gcc/gcc-3.2.2.ebuild</path> and search for the
147			line containing <c>DEPEND</c>. Remove the <c>glibc</c> dependency and save the
148			ebuild.
149			</p>
150
151			<pre caption="Editing gcc-3.2.2.ebuild">
152			# <i>vim /usr/portage/sys-devel/gcc/gcc-3.2.2.ebuild</i>
153			</pre>
154
155			<p>
156			Now install the latest GCC version on your system:
157			</p>
158
159	swift	1.14	<pre caption="Install the latest GCC">
160	swift	1.10	# <i>USE="-java" emerge /usr/portage/sys-devel/gcc/gcc-3.2.2.ebuild</i>
161	rac	1.1	</pre>
162	neysx	1.13
163			</body>
164			</section>
165			<section>
166			<title>Changing profiles</title>
167			<body>
168
169			<p>
170			Now you need to change two sets of profiles: your gcc-config profile and your
171			Portage profile.
172			</p>
173
174	swift	1.14	<pre caption="Change the Portage profile">
175	rac	1.1	# <i>cd /etc</i>
176			# <i>rm make.profile</i>
177	neysx	1.13	<comment>(Replace "x86" with your architecture)</comment>
178			# <i>ln -s ../usr/portage/profiles/default-x86-1.4 make.profile</i>
179			</pre>
180
181	swift	1.14	<pre caption="Change the GCC profile">
182	neysx	1.13	<comment>(Note the one for the version you just emerged, use it below)</comment>
183	swift	1.17	# <i>gcc-config --list-profiles</i>
184	neysx	1.13	<comment>(Replace with the version you noted above)</comment>
185			# <i>gcc-config i686-pc-linux-gnu-3.2.2</i>
186	rac	1.1	</pre>
187
188	neysx	1.13	</body>
189			</section>
190			<section>
191			<title>Recompile toolchain</title>
192			<body>
193
194			<p>
195			Now you need to recompile your core toolchain with your new compiler. If you
196			are continuing in the same shell, you need to run <c>source /etc/profile</c> as
197			gcc-config instructed you to. Then emerge glibc and binutils using your new
198			compiler:
199			</p>
200
201	swift	1.14	<pre caption="Rebuilding the toolchain">
202	rac	1.1	# <i>emerge glibc binutils</i>
203			</pre>
204	neysx	1.13
205			<warn>
206			It is quite likely that you will upgrade glibc from a 2.2 or older version to
207			2.3. Do not downgrade glibc afterwards. Any software you have compiled against
208			glibc 2.3 will stop working, and this can make your system unusable.
209			</warn>
210
211			</body>
212			</section>
213			<section>
214			<title>Recompiling everything with your new compiler</title>
215			<body>
216
217			<p>
218			Now you may recompile everything on your system with your new compiler:
219			</p>
220
221	swift	1.14	<pre caption="Rebuilding the entire system">
222	rac	1.1	# <i>emerge -e world</i>
223			</pre>
224	neysx	1.13
225			<note>
226			If this command fails at any point due to errors, you
227			can use <c>emerge --resume</c> to continue the process where
228			you left off. This requires Portage 2.0.47 or later.
229			</note>
230
231			</body>
232			</section>
233			</chapter>
234	rac	1.1	</guide>