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.10 2004/09/23 12:23:42 swift Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide link="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>
  <license/>
<version>0.3</version>
<date>October 2, 2004</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>
# <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>
# <i>emerge -u gcc</i>
</pre>

                                <p>You can now check to see if gcc-config is working properly:</p>
                                <pre>
# <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>
# <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>
# <i>cd /etc</i>
# <i>rm make.profile</i>
# <i>ln -s ../usr/portage/profiles/default-x86-1.4 make.profile</i> <codenote>Replace "x86" with your architecture</codenote>
</pre>

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