en/handbook/hb-portage-branches.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

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

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-branches.xml,v 1.18 2011/03/02 09:46:22 nightmorph Exp $ -->

<sections>

<abstract>
Gentoo provides software separated in several branches, depending on stability
and architectural support. "Mixing Software Branches" inform you how these
branches can be configured and how you can override this separation
individually.
</abstract>

<version>4</version>
<date>2012-07-24</date>

<section>
<title>Using One Branch</title>
<subsection>
<title>The Stable Branch</title>
<body>

<p>
The ACCEPT_KEYWORDS variable defines what software branch you use on your
system. It defaults to the stable software branch for your architecture, for
instance <c>x86</c>.
</p>

<p>
We recommend that you only use the stable branch. However, if you don't care
about stability this much and you want to help out Gentoo by submitting
bugreports to <uri>http://bugs.gentoo.org</uri>, read on.
</p>

</body>
</subsection>
<subsection>
<title>The Testing Branch</title>
<body>

<p>
If you want to use more recent software, you can consider using the testing
branch instead. To have Portage use the testing branch, add a ~ in front of your
architecture.
</p>

<p>
The testing branch is exactly what it says - <e>Testing</e>. If a package is in
testing, it means that the developers feel that it is functional but has not
been thoroughly tested. You could very well be the first to discover a bug in
the package in which case you could file a <uri
link="http://bugs.gentoo.org">bugreport</uri> to let the developers know about
it.
</p>

<p>
Beware though, you might notice stability issues, imperfect package handling
(for instance wrong/missing dependencies), too frequent updates (resulting in
lots of building) or broken packages. If you do not know how Gentoo works and
how to solve problems, we recommend that you stick with the stable and tested
branch.
</p>

<p>
For example, to select the testing branch for the x86 architecture, edit
<path>/etc/portage/make.conf</path> and set:
</p>

<pre caption="Setting the ACCEPT_KEYWORDS variable">
ACCEPT_KEYWORDS="~x86"
</pre>

<p>
If you update your system now, you will find out that <e>lots</e> of packages
will be updated. Mind you though: when you have updated your system to use the
testing branch there is usually no easy way back to the stable, official branch 
(except for using backups of course).
</p>

</body>
</subsection>
</section>
<section>
<title>Mixing Stable with Testing</title>
<subsection>
<title>The package.accept_keywords location</title>
<body>

<p>
You can ask Portage to allow the testing branch for particular packages but use
the stable branch for the rest of the system. To achieve this, add the package
category and name you want to use the testing branch of in
<path>/etc/portage/package.accept_keywords</path>. You can also create a
directory (with the same name) and list the package in the files under that
directory. For instance, to use the testing branch for <c>gnumeric</c>:
</p>

<pre caption="/etc/portage/package.accept_keywords setting for gnumeric">
app-office/gnumeric
</pre>

</body>
</subsection>
<subsection id="versions">
<title>Test Particular Versions</title>
<body>

<p>
If you want to use a specific software version from the testing branch but you
don't want Portage to use the testing branch for subsequent versions, you can
add in the version in the <path>package.accept_keywords</path> location. In this
case you <e>must</e> use the = operator. You can also enter a version range
using the &lt;=, &lt;, &gt; or &gt;= operators.
</p>

<p>
In any case, if you add version information, you <e>must</e> use an operator. If
you leave out version information, you <e>cannot</e> use an operator.
</p>

<p>
In the following example we ask Portage to accept gnumeric-1.2.13:
</p>

<pre caption="Enabling a particular gnumeric test version">
=app-office/gnumeric-1.2.13
</pre>

</body>
</subsection>
</section>
<section>
<title>Using Masked Packages</title>
<subsection>
<title>The package.unmask location</title>
<body>

<impo>
The Gentoo developers do <b>not</b> support the use of this location. Please
exercise due caution when doing so. Support requests related to
<c>package.unmask</c> and/or <c>package.mask</c> will not be answered. You have
been warned.
</impo>

<p>
When a package has been masked by the Gentoo developers and you still want to
use it despite the reason mentioned in the <path>package.mask</path> file
(situated in <path>/usr/portage/profiles</path> by default), add the
desired version (usually this will be the exact same line from
<path>profiles</path>) in the <path>/etc/portage/package.unmask</path> file
(or in a file in that directory if it is a directory). 
</p>

<p>
For instance, if <c>=net-mail/hotwayd-0.8</c> is masked, you can unmask it by
adding the exact same line in the <path>package.unmask</path> location:
</p>

<pre caption="/etc/portage/package.unmask">
=net-mail/hotwayd-0.8
</pre>

<note>
If an entry in <path>/usr/portage/profiles/package.mask</path> contains a range
of package versions, you will need to unmask only the version(s) you actually
want. Please read the <uri link="#versions">previous section</uri> to learn how
to specify versions in <path>package.unmask</path>.
</note>

</body>
</subsection>
<subsection>
<title>The package.mask location</title>
<body>

<p>
When you don't want Portage to take a certain package or a specific version of a
package into account you can mask it yourself by adding an appropriate line to
the <path>/etc/portage/package.mask</path> location (either in that file or
in a file in this directory).
</p>

<p>
For instance, if you don't want Portage to install newer kernel sources than
<c>gentoo-sources-2.6.8.1</c>, you add the following line at the
<path>package.mask</path> location:
</p>

<pre caption="/etc/portage/package.mask example">
&gt;sys-kernel/gentoo-sources-2.6.8.1
</pre>

</body>
</subsection>
</section>
</sections>
1	swift	1.1	<?xml version='1.0' encoding='UTF-8'?>
2			<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4			<!-- The content of this document is licensed under the CC-BY-SA license -->
5	neysx	1.13	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6	swift	1.1
7	swift	1.19	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-branches.xml,v 1.18 2011/03/02 09:46:22 nightmorph Exp $ -->
8	swift	1.1
9			<sections>
10	swift	1.2
11	neysx	1.15	<abstract>
12			Gentoo provides software separated in several branches, depending on stability
13			and architectural support. "Mixing Software Branches" inform you how these
14			branches can be configured and how you can override this separation
15			individually.
16			</abstract>
17
18	swift	1.19	<version>4</version>
19			<date>2012-07-24</date>
20	swift	1.2
21	swift	1.1	<section>
22			<title>Using One Branch</title>
23			<subsection>
24			<title>The Stable Branch</title>
25			<body>
26
27			<p>
28			The ACCEPT_KEYWORDS variable defines what software branch you use on your
29			system. It defaults to the stable software branch for your architecture, for
30			instance <c>x86</c>.
31			</p>
32
33			<p>
34			We recommend that you only use the stable branch. However, if you don't care
35			about stability this much and you want to help out Gentoo by submitting
36			bugreports to <uri>http://bugs.gentoo.org</uri>, read on.
37			</p>
38
39			</body>
40			</subsection>
41			<subsection>
42			<title>The Testing Branch</title>
43			<body>
44
45			<p>
46	neysx	1.10	If you want to use more recent software, you can consider using the testing
47	swift	1.1	branch instead. To have Portage use the testing branch, add a ~ in front of your
48			architecture.
49			</p>
50
51			<p>
52	neysx	1.10	The testing branch is exactly what it says - <e>Testing</e>. If a package is in
53			testing, it means that the developers feel that it is functional but has not
54			been thoroughly tested. You could very well be the first to discover a bug in
55			the package in which case you could file a <uri
56			link="http://bugs.gentoo.org">bugreport</uri> to let the developers know about
57			it.
58			</p>
59
60			<p>
61	swift	1.12	Beware though, you might notice stability issues, imperfect package handling
62			(for instance wrong/missing dependencies), too frequent updates (resulting in
63			lots of building) or broken packages. If you do not know how Gentoo works and
64			how to solve problems, we recommend that you stick with the stable and tested
65			branch.
66			</p>
67
68			<p>
69	neysx	1.10	For example, to select the testing branch for the x86 architecture, edit
70	swift	1.19	<path>/etc/portage/make.conf</path> and set:
71	swift	1.1	</p>
72
73			<pre caption="Setting the ACCEPT_KEYWORDS variable">
74			ACCEPT_KEYWORDS="~x86"
75			</pre>
76
77			<p>
78			If you update your system now, you will find out that <e>lots</e> of packages
79			will be updated. Mind you though: when you have updated your system to use the
80			testing branch there is usually no easy way back to the stable, official branch
81			(except for using backups of course).
82			</p>
83
84			</body>
85			</subsection>
86			</section>
87			<section>
88			<title>Mixing Stable with Testing</title>
89			<subsection>
90	nightmorph	1.17	<title>The package.accept_keywords location</title>
91	swift	1.1	<body>
92
93			<p>
94			You can ask Portage to allow the testing branch for particular packages but use
95			the stable branch for the rest of the system. To achieve this, add the package
96			category and name you want to use the testing branch of in
97	nightmorph	1.17	<path>/etc/portage/package.accept_keywords</path>. You can also create a
98			directory (with the same name) and list the package in the files under that
99			directory. For instance, to use the testing branch for <c>gnumeric</c>:
100	swift	1.1	</p>
101
102	nightmorph	1.17	<pre caption="/etc/portage/package.accept_keywords setting for gnumeric">
103	nightmorph	1.16	app-office/gnumeric
104	swift	1.1	</pre>
105
106			</body>
107			</subsection>
108	nightmorph	1.18	<subsection id="versions">
109	swift	1.1	<title>Test Particular Versions</title>
110			<body>
111
112			<p>
113			If you want to use a specific software version from the testing branch but you
114			don't want Portage to use the testing branch for subsequent versions, you can
115	nightmorph	1.17	add in the version in the <path>package.accept_keywords</path> location. In this
116			case you <e>must</e> use the = operator. You can also enter a version range
117	swift	1.1	using the <=, <, > or >= operators.
118			</p>
119
120			<p>
121			In any case, if you add version information, you <e>must</e> use an operator. If
122			you leave out version information, you <e>cannot</e> use an operator.
123			</p>
124
125			<p>
126			In the following example we ask Portage to accept gnumeric-1.2.13:
127			</p>
128
129	vapier	1.8	<pre caption="Enabling a particular gnumeric test version">
130	nightmorph	1.16	=app-office/gnumeric-1.2.13
131	swift	1.1	</pre>
132
133			</body>
134			</subsection>
135			</section>
136			<section>
137			<title>Using Masked Packages</title>
138			<subsection>
139	swift	1.14	<title>The package.unmask location</title>
140	swift	1.1	<body>
141
142	nightmorph	1.16	<impo>
143	swift	1.14	The Gentoo developers do <b>not</b> support the use of this location. Please
144	neysx	1.11	exercise due caution when doing so. Support requests related to
145	neysx	1.10	<c>package.unmask</c> and/or <c>package.mask</c> will not be answered. You have
146			been warned.
147	nightmorph	1.16	</impo>
148	neysx	1.10
149			<p>
150	swift	1.1	When a package has been masked by the Gentoo developers and you still want to
151			use it despite the reason mentioned in the <path>package.mask</path> file
152			(situated in <path>/usr/portage/profiles</path> by default), add the
153	nightmorph	1.18	desired version (usually this will be the exact same line from
154			<path>profiles</path>) in the <path>/etc/portage/package.unmask</path> file
155	swift	1.14	(or in a file in that directory if it is a directory).
156	swift	1.1	</p>
157
158			<p>
159			For instance, if <c>=net-mail/hotwayd-0.8</c> is masked, you can unmask it by
160	swift	1.14	adding the exact same line in the <path>package.unmask</path> location:
161	swift	1.1	</p>
162
163			<pre caption="/etc/portage/package.unmask">
164			=net-mail/hotwayd-0.8
165			</pre>
166
167	nightmorph	1.18	<note>
168			If an entry in <path>/usr/portage/profiles/package.mask</path> contains a range
169			of package versions, you will need to unmask only the version(s) you actually
170			want. Please read the <uri link="#versions">previous section</uri> to learn how
171			to specify versions in <path>package.unmask</path>.
172			</note>
173
174	swift	1.1	</body>
175			</subsection>
176			<subsection>
177	swift	1.14	<title>The package.mask location</title>
178	swift	1.1	<body>
179
180			<p>
181			When you don't want Portage to take a certain package or a specific version of a
182			package into account you can mask it yourself by adding an appropriate line to
183	swift	1.14	the <path>/etc/portage/package.mask</path> location (either in that file or
184			in a file in this directory).
185	swift	1.1	</p>
186
187			<p>
188			For instance, if you don't want Portage to install newer kernel sources than
189	swift	1.14	<c>gentoo-sources-2.6.8.1</c>, you add the following line at the
190			<path>package.mask</path> location:
191	swift	1.1	</p>
192
193			<pre caption="/etc/portage/package.mask example">
194	dertobi123	1.9	>sys-kernel/gentoo-sources-2.6.8.1
195	swift	1.1	</pre>
196
197			</body>
198			</subsection>
199			</section>
200			</sections>