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.0 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-branches.xml,v 1.11 2005/04/25 14:29:19 neysx Exp $ -->

<sections>

<version>1.6</version>
<date>2005-08-11</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/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.keywords file</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.keywords</path>. For instance, to use the testing
branch for <c>gnumeric</c>:
</p>

<pre caption="/etc/portage/package.keywords setting for gnumeric, full line">
app-office/gnumeric ~x86
</pre>

</body>
</subsection>
<subsection>
<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.keywords</path> file. 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 ~x86
</pre>

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

<p>
The Gentoo developers do <b>not</b> support the use of these files. 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.
</p>

<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
<e>exact</e> same line in <path>/etc/portage/package.unmask</path>. 
</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> file:
</p>

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

</body>
</subsection>
<subsection>
<title>The package.mask file</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
<path>/etc/portage/package.mask</path>.
</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 to
<path>package.mask</path>:
</p>

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

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