portage/doc/manually-fixing-portage.xml

<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/portage/doc/manually-fixing-portage.xml,v 1.14 2010/03/21 00:54:54 zmedico Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide link="/proj/en/portage/doc/manually-fixing-portage.xml">

<title>Manually fixing broken portage installations</title>

<author>
  <mail link="genone@gentoo.org">Marius Mauch</mail>
</author>

<abstract>
This document attempts to help people to manually fix a broken sys-apps/portage
installation.
</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.3</version>
<date>2007-05-31</date>

<chapter>
<title>Manually fixing portage</title>
<section>
<title>Purpose</title>
<body>

<p>
This section will tell you how to manually update/fix your portage installation
in case you can't run <c>emerge sys-apps/portage</c>. While not hard it is
still to be done with great care, so please follow the listed steps exactly
(but apply common sense when necessary).
</p>

</body>
</section>
<section>
<title>Getting a portage tarball</title>
<body>

<p>
The first step to do is to get the tarball of a current portage version. In the
following text we will use <e>portage-2.1.8</e> as an example (as this is the
current stable version at the time of this writing), please replace that with a
version present in the tree if possible. 
</p>
<warn>
If your currently installed version of python reported by <c>python -V</c>
is less than 2.6 then you must choose a version of portage that is compatible with 
it. If you have at least python 2.6 then use <e>portage-2.1.8.tar.bz2</e>. If 
you have python 2.4 or 2.5 then use <e>portage-2.1.6.tar.bz2</e>.
</warn>

<p>
Depending on the exact reason portage doesn't work for you anymore it may still
be possible to use it to fetch the tarball for you, so as a first step please
try to run <c>emerge --fetchonly sys-apps/portage</c>, only if that doesn't
work you have to manually fetch the tarball with:
</p>

<pre caption="Fetching portage tarball with wget">
# <i>wget -P /usr/portage/distfiles http://distfiles.gentoo.org/distfiles/portage-2.1.8.tar.bz2</i>
</pre>

<p>
After that you should have the tarball available as
<path>/usr/portage/distfiles/portage-2.1.8.tar.bz2</path>.
</p>

</body>
</section>
<section>
<title>Replacing the installed version</title>
<body>

<p>
The next step is to unpack the tarball to a temporary location, using
<path>/root/portage-recover</path> as example the commands to do that are:
</p>

<pre caption="Unpacking portage tarball">
# <i>cd /root</i>
# <i>mkdir portage-recover</i>
# <i>cd portage-recover</i>
# <i>tar xfj /usr/portage/distfiles/portage-2.1.8.tar.bz2</i>
</pre>

<p>
After you have done this it's just a matter of replacing the python and bash
files of your existing installation with the ones from the tarball (in most
cases anyway). To do so please run:
</p>

<pre caption="Replacing installed files">
# <i>cd /root/portage-recover/portage-2.1.8</i>
# <i>cp -R pym bin /usr/lib/portage/</i>
</pre>

<p>
If you are not using Gentoo on FreeBSD then you should remove the sed wrapper
script since it's not needed and it is known to cause problems with old
versions of bash:
</p>

<pre caption="Removing the sed wrapper script">
# <i>rm -f /usr/lib/portage/bin/sed</i>
</pre>

<note>
If you accidently unmerged portage before or lost 
<path>/etc/make.globals</path> for other reasons you should also copy 
<path>cnf/make.globals</path> back into <path>/etc</path>, otherwise
portage might behave in strange ways.
</note>
<note>
If the previous version of portage was less than 2.1 then you should now run
<c>emerge --metadata</c> before continuing to the next step. This is necessary
in order to convert the ebuild metadata to the new format that is used by
portage 2.1 and above. It is okay to run this command even if you are not sure
what the previous version of portage was.
</note>

<p>
Now you should have a working portage install again. To ensure a consistent
system state however you should now run <c>emerge sys-apps/portage</c> again
immediately.
</p>

<p>
If you get a <e>command not found</e> error message when you try to run
<c>emerge</c> you have to recreate the symlink:
</p>

<pre caption="Recreating the emerge symlink">
# <i>ln -s ../lib/portage/bin/emerge /usr/bin/emerge</i>
</pre>

<p>
If these steps didn't work for you your problem is likely not a broken portage
installation but something else beyond the scope of this document. Please
recheck the <uri link="/proj/en/portage/doc/common-problems.xml">list of common
problems</uri> and also look in <uri
link="http://bugs.gentoo.org">bugzilla</uri> if the problem is reported there.
</p>

</body>
</section>
</chapter>
</guide>
1	genone	1.1	<?xml version='1.0' encoding="UTF-8"?>
2	zmedico	1.15	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/portage/doc/manually-fixing-portage.xml,v 1.14 2010/03/21 00:54:54 zmedico Exp $ -->
3	genone	1.1	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4	rane	1.6
5	genone	1.1	<guide link="/proj/en/portage/doc/manually-fixing-portage.xml">
6	rane	1.6
7	genone	1.1	<title>Manually fixing broken portage installations</title>
8	rane	1.6
9	genone	1.1	<author>
10			<mail link="genone@gentoo.org">Marius Mauch</mail>
11			</author>
12
13			<abstract>
14	rane	1.6	This document attempts to help people to manually fix a broken sys-apps/portage
15	genone	1.1	installation.
16			</abstract>
17
18	rane	1.6	<!-- The content of this document is licensed under the CC-BY-SA license -->
19			<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
20	genone	1.1	<license/>
21
22	genone	1.7	<version>0.3</version>
23			<date>2007-05-31</date>
24	genone	1.1
25			<chapter>
26			<title>Manually fixing portage</title>
27			<section>
28			<title>Purpose</title>
29			<body>
30	rane	1.6
31			<p>
32			This section will tell you how to manually update/fix your portage installation
33			in case you can't run <c>emerge sys-apps/portage</c>. While not hard it is
34			still to be done with great care, so please follow the listed steps exactly
35			(but apply common sense when necessary).
36			</p>
37
38	genone	1.1	</body>
39			</section>
40			<section>
41			<title>Getting a portage tarball</title>
42			<body>
43	rane	1.6
44			<p>
45			The first step to do is to get the tarball of a current portage version. In the
46	zmedico	1.15	following text we will use <e>portage-2.1.8</e> as an example (as this is the
47	rane	1.6	current stable version at the time of this writing), please replace that with a
48	genone	1.10	version present in the tree if possible.
49	rane	1.6	</p>
50	genone	1.10	<warn>
51			If your currently installed version of python reported by <c>python -V</c>
52	zmedico	1.14	is less than 2.6 then you must choose a version of portage that is compatible with
53	zmedico	1.15	it. If you have at least python 2.6 then use <e>portage-2.1.8.tar.bz2</e>. If
54	zmedico	1.14	you have python 2.4 or 2.5 then use <e>portage-2.1.6.tar.bz2</e>.
55	genone	1.10	</warn>
56	rane	1.6
57			<p>
58			Depending on the exact reason portage doesn't work for you anymore it may still
59	genone	1.1	be possible to use it to fetch the tarball for you, so as a first step please
60	rane	1.6	try to run <c>emerge --fetchonly sys-apps/portage</c>, only if that doesn't
61			work you have to manually fetch the tarball with:
62			</p>
63
64			<pre caption="Fetching portage tarball with wget">
65	zmedico	1.15	# <i>wget -P /usr/portage/distfiles http://distfiles.gentoo.org/distfiles/portage-2.1.8.tar.bz2</i>
66	genone	1.1	</pre>
67	rane	1.6
68			<p>
69			After that you should have the tarball available as
70	zmedico	1.15	<path>/usr/portage/distfiles/portage-2.1.8.tar.bz2</path>.
71	rane	1.6	</p>
72
73	genone	1.1	</body>
74			</section>
75			<section>
76			<title>Replacing the installed version</title>
77			<body>
78	rane	1.6
79			<p>
80			The next step is to unpack the tarball to a temporary location, using
81			<path>/root/portage-recover</path> as example the commands to do that are:
82			</p>
83
84			<pre caption="Unpacking portage tarball">
85			# <i>cd /root</i>
86			# <i>mkdir portage-recover</i>
87			# <i>cd portage-recover</i>
88	zmedico	1.15	# <i>tar xfj /usr/portage/distfiles/portage-2.1.8.tar.bz2</i>
89	genone	1.1	</pre>
90	rane	1.6
91			<p>
92			After you have done this it's just a matter of replacing the python and bash
93			files of your existing installation with the ones from the tarball (in most
94			cases anyway). To do so please run:
95			</p>
96
97			<pre caption="Replacing installed files">
98	zmedico	1.15	# <i>cd /root/portage-recover/portage-2.1.8</i>
99	rane	1.6	# <i>cp -R pym bin /usr/lib/portage/</i>
100	genone	1.1	</pre>
101	rane	1.6
102	zmedico	1.11	<p>
103			If you are not using Gentoo on FreeBSD then you should remove the sed wrapper
104			script since it's not needed and it is known to cause problems with old
105			versions of bash:
106			</p>
107
108			<pre caption="Removing the sed wrapper script">
109			# <i>rm -f /usr/lib/portage/bin/sed</i>
110			</pre>
111
112	genone	1.7	<note>
113			If you accidently unmerged portage before or lost
114			<path>/etc/make.globals</path> for other reasons you should also copy
115			<path>cnf/make.globals</path> back into <path>/etc</path>, otherwise
116			portage might behave in strange ways.
117			</note>
118	zmedico	1.8	<note>
119			If the previous version of portage was less than 2.1 then you should now run
120			<c>emerge --metadata</c> before continuing to the next step. This is necessary
121			in order to convert the ebuild metadata to the new format that is used by
122			portage 2.1 and above. It is okay to run this command even if you are not sure
123			what the previous version of portage was.
124			</note>
125	genone	1.7
126	rane	1.6	<p>
127			Now you should have a working portage install again. To ensure a consistent
128	genone	1.1	system state however you should now run <c>emerge sys-apps/portage</c> again
129	rane	1.6	immediately.
130			</p>
131
132			<p>
133			If you get a <e>command not found</e> error message when you try to run
134			<c>emerge</c> you have to recreate the symlink:
135			</p>
136
137			<pre caption="Recreating the emerge symlink">
138			# <i>ln -s ../lib/portage/bin/emerge /usr/bin/emerge</i>
139	genone	1.4	</pre>
140	rane	1.6
141			<p>
142			If these steps didn't work for you your problem is likely not a broken portage
143			installation but something else beyond the scope of this document. Please
144			recheck the <uri link="/proj/en/portage/doc/common-problems.xml">list of common
145			problems</uri> and also look in <uri
146			link="http://bugs.gentoo.org">bugzilla</uri> if the problem is reported there.
147			</p>
148
149	genone	1.1	</body>
150			</section>
151			</chapter>
152			</guide>