en/handbook/hb-working-use.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/1.0 -->

<!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-use.xml,v 1.7 2004/01/08 14:23:17 swift Exp $ -->

<sections>
<section>
<title>What are USE-flags?</title>
<subsection>
<title>The ideas behind USE-flags</title>
<body>

<p>
When you are installing Gentoo (or any other distribution, or even operating
system for that matter) you make choices depending on the environment you are 
working with. A setup for a server differs from a setup for a workstation.
A gaming workstation differs from a 3D rendering workstation.
</p>

<p>
This is not only true for choosing what packages you want to install, but also
what features a certain package should support. If you don't need OpenGL, why
would you bother installing OpenGL and build OpenGL support in most of your
packages? If you don't want to use KDE, why would you bother compiling packages
with KDE-support if those packages work flawlessly without?
</p>

<p>
To help users in deciding what to install/activate and what not, we wanted the
user to specify his environment in an easy way. This forces the user into
deciding what he really wants and eases the process for Portage, our package 
managment system, to make useful decisions.
</p>

</body>
</subsection>
<subsection>
<title>Definition of a USE-flag</title>
<body>

<p>
Enter the USE-flags. Such a flag is a keyword that embodies support and
dependency-information for a certain concept. If you define a certain USE-flag, 
Portage will know that you want support for the chosen keyword. Of course
this also alters the dependency information for a package.
</p>

<p>
Let us take a look at a specific example: the <c>kde</c> keyword. If you do not
have this keyword in your <c>USE</c> variable, all packages that have
<e>optional</e> KDE support will be compiled <e>without</e> KDE support. All
packages that have an <e>optional</e> KDE dependency will be installed
<e>without</e> installing the KDE libraries (as dependency). If you have defined
the <c>kde</c> keyword, then those packages <e>will</e> be compiled with KDE
support, and the KDE libraries will be installed as dependency.
</p>

<p>
By correctly defining the keywords you will receive a system tailored
specifically to your needs.
</p>

</body>
</subsection>
<subsection>
<title>What USE-flags exist?</title>
<body>

<p>
There are two types of USE-flags: <e>global</e> and <e>local</e> USE-flags.
</p>

<ul>
  <li>
    A <e>global</e> USE-flag is used by several packages, system-wide. This is 
    what most people see as USE-flags.
  </li>
  <li>
    A <e>local</e> USE-flag is used by a single package to make package-specific
    decisions.
  </li>
</ul>

<p>
A list of available global USE-flags can be found <uri
link="/dyn/use-index.xml">online</uri> or locally in
<path>/usr/portage/profiles/use.desc</path>. A short (<e>very</e> incomplete)
snippet:
</p>

<pre caption="A short snippet of available USE-flags">
gtk     - Adds support for x11-libs/gtk+ (The GIMP Toolkit)
gtk2    - Use gtk+-2.0.0 over gtk+-1.2 in cases where a program supports both.
gtkhtml - Adds support for gnome-extra/gtkhtml
guile   - Adds support for dev-util/guile (interpreter for Scheme)
icc     - Use the Intel C++ Compiler if the package supports it
icc-pgo - Enable PGO data generation or use when use icc.
imap    - Adds support for IMAP
</pre>

</body>
</subsection>
</section>
<section>
<title>Using USE-flags</title>
<subsection>
<title>Declare permanent USE-flags</title>
<body>

<p>
In the hope you are convinced of the importance of USE-flags we will now inform
you how to declare USE-flags.
</p>

<p>
As previously mentioned, all USE-flags are declared inside the <c>USE</c>
variable. To make it easy for users to search and pick USE-flags, we already
provide a <e>default</e> USE setting. This setting is a collection of USE-flags
we think are commonly used by the Gentoo users. This default setting is declared
in the <path>/etc/make.profile/make.defaults</path> file. Let us take a look at
this default setting:
</p>

<pre caption="/etc/make.profile/make.defaults USE variable">
USE="x86 oss apm arts avi berkdb crypt cups encode foomaticdb gdbm gif gpm gtk 
     imlib jpeg kde gnome libg++ libwww mad mikmod motif mpeg ncurses nls 
     oggvorbis opengl pam pdflib png python qt quicktime readline sdl slang 
     spell ssl svga tcpd truetype X xml2 xmms xv zlib"
</pre>

<p>
As you can see, this variable already contains quite a lot of keywords. Do
<b>not</b> alter the <path>/etc/make.profile/make.defaults</path> file to tailor
the <c>USE</c> variable to your needs: changes in this file will be undone when
you update Portage!
</p>

<p>
To change this default setting, you need to add or remove keywords to the
<c>USE</c> variable. This is done globally by defining the <c>USE</c> variable 
in <path>/etc/make.conf</path>. In this variable you add the extra USE-flags you
require, or remove the USE-flags you don't want. This latter is done by
prefixing the keyword with the minus-sign ("-").
</p>

<p>
For instance, to remove support for KDE and QT but add support for ldap, the
following <c>USE</c> can be defined in <path>/etc/make.conf</path>:
</p>

<pre caption="An example USE setting in /etc/make.conf">
USE="-kde -qt ldap"
</pre>

</body>
</subsection>
<subsection>
<title>Declare temporary USE-flags</title>
<body>

<p>
Sometimes you want to set a certain USE-setting only once. Instead of editing
<path>/etc/make.conf</path> twice (to do and undo the USE-changes) you can just 
declare the USE-variable as environment variable.
</p>

<p>
As an example we will temporarily remove java from the USE-setting
during the installation of mozilla.
</p>

<note>
The <c>emerge</c> command will be discussed more thoroughly in <uri
link="?part=2&amp;chap=2">Portage and Software</uri>.
</note>

<pre caption="Using USE as evironment variable">
# <i>USE="-java" emerge mozilla</i>
</pre>

</body>
</subsection>
<subsection>
<title>Inheriting USE-flags</title>
<body>

<p>
Some packages don't only listen to USE-flags, but also provide USE-flags. When
you install such a package, the USE-flag they provide is added to your USE
setting. To view the list of packages that provide a USE-flag, check
<path>/etc/make.profile/use.defaults</path>:
</p>

<pre caption="A snippet from /etc/make.profile/use.defaults">
gnome           gnome-base/gnome
gtk             x11-libs/gtk+
qt              x11-libs/qt
kde             kde-base/kdebase
motif           x11-libs/openmotif
</pre>

</body>
</subsection>
<subsection>
<title>Precendence</title>
<body>

<p>
Of course there is a certain precendence on what setting has priority over the
USE setting. You don't want to declare <c>USE="-java"</c> only to see that
<c>java</c> is declared anyway. The precedence for the USE setting is, ordered
by priority (first has lowest priority):
</p>

<ol>
  <li>
    Default USE setting declared in <path>/etc/make.profile/make.defaults</path>
  </li>
  <li>
    Inherited USE setting if a package from
    <path>/etc/make.profile/use.defaults</path> is installed
  </li>
  <li>
    User-defined USE setting in <path>/etc/make.conf</path>
  </li>
  <li>
    User-defined USE setting as environment variable
  </li>
</ol>

<p>
To view the final <c>USE</c> setting as seen by Portage, run <c>emerge info</c>.
This will list all relevant variables (including the <c>USE</c> variable) with
the content used by Portage.
</p>

<pre caption="Running emerge info">
# <i>emerge info</i>
</pre>

</body>
</subsection>
</section>
<section>
<title>Package specific USE-flags</title>
<subsection>
<title>Viewing available USE-flags</title>
<body>

<p>
In the next chapter on <uri link="?part=2&amp;chap=2">Portage and Software</uri>
we will explain how to manage your installed software and how to work with 
<c>emerge</c>. However, we will give you a primer on <c>emerge</c> by showing
you how to view what USE-flags a package uses.
</p>

<p>
Let us take the example of <c>mozilla</c>: what USE-flags does it listen to? To
find out, we use <c>emerge</c> with the <c>--pretend</c> (don't really do
anything) and <c>--verbose</c> (give more output) options:
</p>

<pre caption="Viewing the used USE-flags">
# <i>emerge --pretend --verbose mozilla</i>
These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild  N    ] net-www/mozilla-1.5-r1 +java +crypt -ipv6 -gtk2 +ssl +ldap 
+gnome -debug +mozcalendar -mozaccess -mozxmlterm -moznoirc -moznomail
-moznocompose -moznoxft 
</pre>

<p>
<c>emerge</c> isn't the only tool for this job. In fact, we have a tool
dedicated to package information called <c>etcat</c> which resides in the
<c>gentoolkit</c> package. First, install <c>gentoolkit</c>:
</p>

<pre caption="Installing gentoolkit">
# <i>emerge --usepkg gentoolkit</i>
</pre>

<p>
Now run <c>etcat</c> with the <c>uses</c> argument to view the USE-flags of a
certain package. For instance, for the <c>gnumeric</c> package:
</p>

<pre caption="Using etcat to view used USE-flags">
# <i>etcat uses gnumeric</i>
[ Colour Code : <i>set</i> <comment>unset</comment> ]
[ Legend      : (U) Col 1 - Current USE flags        ]
[             : (I) Col 2 - Installed With USE flags ]

 U I [ Found these USE variables in : app-office/gnumeric-1.2.0 ]
 - - <comment>libgda</comment>  : Adds GNU Data Access (CORBA wrapper) support for gnumeric
 - - <comment>gnomedb</comment> : unknown
 + + <i>python</i>  : Adds support/bindings for the Python language
 + + <i>bonobo</i>  : Adds support for gnome-base/bonobo (Gnome CORBA interfaces)
</pre>

</body>
</subsection>
</section>
</sections>
1	swift	1.7	<?xml version='1.0' encoding='UTF-8'?>
2			<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4	swift	1.1	<!-- The content of this document is licensed under the CC-BY-SA license -->
5			<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
6
7	swift	1.8	<!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-use.xml,v 1.7 2004/01/08 14:23:17 swift Exp $ -->
8	swift	1.1
9			<sections>
10			<section>
11			<title>What are USE-flags?</title>
12			<subsection>
13			<title>The ideas behind USE-flags</title>
14			<body>
15
16	swift	1.2	<p>
17			When you are installing Gentoo (or any other distribution, or even operating
18			system for that matter) you make choices depending on the environment you are
19			working with. A setup for a server differs from a setup for a workstation.
20			A gaming workstation differs from a 3D rendering workstation.
21			</p>
22
23			<p>
24			This is not only true for choosing what packages you want to install, but also
25			what features a certain package should support. If you don't need OpenGL, why
26			would you bother installing OpenGL and build OpenGL support in most of your
27			packages? If you don't want to use KDE, why would you bother compiling packages
28	swift	1.5	with KDE-support if those packages work flawlessly without?
29	swift	1.2	</p>
30
31			<p>
32			To help users in deciding what to install/activate and what not, we wanted the
33			user to specify his environment in an easy way. This forces the user into
34			deciding what he really wants and eases the process for Portage, our package
35	swift	1.5	managment system, to make useful decisions.
36	swift	1.2	</p>
37
38	swift	1.1	</body>
39			</subsection>
40			<subsection>
41			<title>Definition of a USE-flag</title>
42			<body>
43
44	swift	1.2	<p>
45			Enter the USE-flags. Such a flag is a keyword that embodies support and
46			dependency-information for a certain concept. If you define a certain USE-flag,
47	swift	1.3	Portage will know that you want support for the chosen keyword. Of course
48	swift	1.2	this also alters the dependency information for a package.
49			</p>
50
51			<p>
52	swift	1.6	Let us take a look at a specific example: the <c>kde</c> keyword. If you do not
53	swift	1.2	have this keyword in your <c>USE</c> variable, all packages that have
54			<e>optional</e> KDE support will be compiled <e>without</e> KDE support. All
55			packages that have an <e>optional</e> KDE dependency will be installed
56			<e>without</e> installing the KDE libraries (as dependency). If you have defined
57			the <c>kde</c> keyword, then those packages <e>will</e> be compiled with KDE
58			support, and the KDE libraries will be installed as dependency.
59			</p>
60
61			<p>
62			By correctly defining the keywords you will receive a system tailored
63			specifically to your needs.
64			</p>
65
66	swift	1.1	</body>
67			</subsection>
68			<subsection>
69			<title>What USE-flags exist?</title>
70			<body>
71
72	swift	1.2	<p>
73			There are two types of USE-flags: <e>global</e> and <e>local</e> USE-flags.
74			</p>
75
76			<ul>
77			<li>
78			A <e>global</e> USE-flag is used by several packages, system-wide. This is
79			what most people see as USE-flags.
80			</li>
81			<li>
82	swift	1.8	A <e>local</e> USE-flag is used by a single package to make package-specific
83	swift	1.2	decisions.
84			</li>
85			</ul>
86
87			<p>
88			A list of available global USE-flags can be found <uri
89			link="/dyn/use-index.xml">online</uri> or locally in
90			<path>/usr/portage/profiles/use.desc</path>. A short (<e>very</e> incomplete)
91			snippet:
92			</p>
93
94			<pre caption="A short snippet of available USE-flags">
95			gtk - Adds support for x11-libs/gtk+ (The GIMP Toolkit)
96			gtk2 - Use gtk+-2.0.0 over gtk+-1.2 in cases where a program supports both.
97			gtkhtml - Adds support for gnome-extra/gtkhtml
98			guile - Adds support for dev-util/guile (interpreter for Scheme)
99			icc - Use the Intel C++ Compiler if the package supports it
100			icc-pgo - Enable PGO data generation or use when use icc.
101			imap - Adds support for IMAP
102			</pre>
103
104	swift	1.1	</body>
105			</subsection>
106			</section>
107			<section>
108			<title>Using USE-flags</title>
109			<subsection>
110			<title>Declare permanent USE-flags</title>
111			<body>
112
113	swift	1.2	<p>
114			In the hope you are convinced of the importance of USE-flags we will now inform
115			you how to declare USE-flags.
116			</p>
117
118			<p>
119			As previously mentioned, all USE-flags are declared inside the <c>USE</c>
120			variable. To make it easy for users to search and pick USE-flags, we already
121			provide a <e>default</e> USE setting. This setting is a collection of USE-flags
122			we think are commonly used by the Gentoo users. This default setting is declared
123			in the <path>/etc/make.profile/make.defaults</path> file. Let us take a look at
124			this default setting:
125			</p>
126
127			<pre caption="/etc/make.profile/make.defaults USE variable">
128			USE="x86 oss apm arts avi berkdb crypt cups encode foomaticdb gdbm gif gpm gtk
129			imlib jpeg kde gnome libg++ libwww mad mikmod motif mpeg ncurses nls
130			oggvorbis opengl pam pdflib png python qt quicktime readline sdl slang
131			spell ssl svga tcpd truetype X xml2 xmms xv zlib"
132			</pre>
133
134			<p>
135			As you can see, this variable already contains quite a lot of keywords. Do
136			<b>not</b> alter the <path>/etc/make.profile/make.defaults</path> file to tailor
137			the <c>USE</c> variable to your needs: changes in this file will be undone when
138			you update Portage!
139			</p>
140
141			<p>
142			To change this default setting, you need to add or remove keywords to the
143			<c>USE</c> variable. This is done globally by defining the <c>USE</c> variable
144			in <path>/etc/make.conf</path>. In this variable you add the extra USE-flags you
145			require, or remove the USE-flags you don't want. This latter is done by
146			prefixing the keyword with the minus-sign ("-").
147			</p>
148
149			<p>
150			For instance, to remove support for KDE and QT but add support for ldap, the
151			following <c>USE</c> can be defined in <path>/etc/make.conf</path>:
152			</p>
153
154			<pre caption="An example USE setting in /etc/make.conf">
155			USE="-kde -qt ldap"
156			</pre>
157
158	swift	1.1	</body>
159			</subsection>
160			<subsection>
161			<title>Declare temporary USE-flags</title>
162			<body>
163
164	swift	1.2	<p>
165			Sometimes you want to set a certain USE-setting only once. Instead of editing
166			<path>/etc/make.conf</path> twice (to do and undo the USE-changes) you can just
167			declare the USE-variable as environment variable.
168			</p>
169
170			<p>
171			As an example we will temporarily remove java from the USE-setting
172			during the installation of mozilla.
173			</p>
174
175			<note>
176			The <c>emerge</c> command will be discussed more thoroughly in <uri
177			link="?part=2&chap=2">Portage and Software</uri>.
178			</note>
179
180			<pre caption="Using USE as evironment variable">
181			# <i>USE="-java" emerge mozilla</i>
182			</pre>
183
184	swift	1.1	</body>
185			</subsection>
186			<subsection>
187			<title>Inheriting USE-flags</title>
188			<body>
189
190	swift	1.2	<p>
191			Some packages don't only listen to USE-flags, but also provide USE-flags. When
192			you install such a package, the USE-flag they provide is added to your USE
193			setting. To view the list of packages that provide a USE-flag, check
194			<path>/etc/make.profile/use.defaults</path>:
195			</p>
196
197			<pre caption="A snippet from /etc/make.profile/use.defaults">
198			gnome gnome-base/gnome
199			gtk x11-libs/gtk+
200			qt x11-libs/qt
201			kde kde-base/kdebase
202			motif x11-libs/openmotif
203			</pre>
204
205			</body>
206			</subsection>
207			<subsection>
208			<title>Precendence</title>
209			<body>
210
211			<p>
212	swift	1.3	Of course there is a certain precendence on what setting has priority over the
213	swift	1.2	USE setting. You don't want to declare <c>USE="-java"</c> only to see that
214			<c>java</c> is declared anyway. The precedence for the USE setting is, ordered
215			by priority (first has lowest priority):
216			</p>
217
218			<ol>
219			<li>
220			Default USE setting declared in <path>/etc/make.profile/make.defaults</path>
221			</li>
222			<li>
223			Inherited USE setting if a package from
224			<path>/etc/make.profile/use.defaults</path> is installed
225			</li>
226			<li>
227			User-defined USE setting in <path>/etc/make.conf</path>
228			</li>
229			<li>
230			User-defined USE setting as environment variable
231			</li>
232			</ol>
233	swift	1.4
234			<p>
235			To view the final <c>USE</c> setting as seen by Portage, run <c>emerge info</c>.
236			This will list all relevant variables (including the <c>USE</c> variable) with
237			the content used by Portage.
238			</p>
239
240			<pre caption="Running emerge info">
241			# <i>emerge info</i>
242			</pre>
243	swift	1.2
244	swift	1.1	</body>
245			</subsection>
246			</section>
247			<section>
248			<title>Package specific USE-flags</title>
249			<subsection>
250	swift	1.2	<title>Viewing available USE-flags</title>
251	swift	1.1	<body>
252	swift	1.2
253			<p>
254			In the next chapter on <uri link="?part=2&chap=2">Portage and Software</uri>
255			we will explain how to manage your installed software and how to work with
256			<c>emerge</c>. However, we will give you a primer on <c>emerge</c> by showing
257			you how to view what USE-flags a package uses.
258			</p>
259
260			<p>
261			Let us take the example of <c>mozilla</c>: what USE-flags does it listen to? To
262			find out, we use <c>emerge</c> with the <c>--pretend</c> (don't really do
263			anything) and <c>--verbose</c> (give more output) options:
264			</p>
265
266			<pre caption="Viewing the used USE-flags">
267			# <i>emerge --pretend --verbose mozilla</i>
268			These are the packages that I would merge, in order:
269
270			Calculating dependencies ...done!
271			[ebuild N ] net-www/mozilla-1.5-r1 +java +crypt -ipv6 -gtk2 +ssl +ldap
272			+gnome -debug +mozcalendar -mozaccess -mozxmlterm -moznoirc -moznomail
273			-moznocompose -moznoxft
274			</pre>
275
276			<p>
277			<c>emerge</c> isn't the only tool for this job. In fact, we have a tool
278			dedicated to package information called <c>etcat</c> which resides in the
279			<c>gentoolkit</c> package. First, install <c>gentoolkit</c>:
280			</p>
281
282			<pre caption="Installing gentoolkit">
283			# <i>emerge --usepkg gentoolkit</i>
284			</pre>
285
286			<p>
287			Now run <c>etcat</c> with the <c>uses</c> argument to view the USE-flags of a
288			certain package. For instance, for the <c>gnumeric</c> package:
289			</p>
290
291			<pre caption="Using etcat to view used USE-flags">
292			# <i>etcat uses gnumeric</i>
293			[ Colour Code : <i>set</i> <comment>unset</comment> ]
294			[ Legend : (U) Col 1 - Current USE flags ]
295			[ : (I) Col 2 - Installed With USE flags ]
296
297			U I [ Found these USE variables in : app-office/gnumeric-1.2.0 ]
298			- - <comment>libgda</comment> : Adds GNU Data Access (CORBA wrapper) support for gnumeric
299			- - <comment>gnomedb</comment> : unknown
300			+ + <i>python</i> : Adds support/bindings for the Python language
301			+ + <i>bonobo</i> : Adds support for gnome-base/bonobo (Gnome CORBA interfaces)
302			</pre>
303	swift	1.1
304			</body>
305			</subsection>
306			</section>
307			</sections>