/[gentoo]/xml/htdocs/doc/en/handbook/hb-working-use.xml
Gentoo

Diff of /xml/htdocs/doc/en/handbook/hb-working-use.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.1 Revision 1.38
1<?xml version='1.0' encoding='UTF-8'?>
2<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
1<!-- The content of this document is licensed under the CC-BY-SA license --> 4<!-- The content of this document is licensed under the CC-BY-SA license -->
2<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> 5<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
3 6
4<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-use.xml,v 1.1 2003/11/20 10:52:35 swift Exp $ --> 7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-use.xml,v 1.38 2006/01/13 22:15:20 neysx Exp $ -->
5 8
6<sections> 9<sections>
10
11<version>1.32</version>
12<date>2006-01-13</date>
13
7<section> 14<section>
8<title>What are USE-flags?</title> 15<title>What are USE-flags?</title>
9<subsection> 16<subsection>
10<title>The ideas behind USE-flags</title> 17<title>The ideas behind USE-flags</title>
11<body> 18<body>
12 19
20<p>
21When you are installing Gentoo (or any other distribution, or even operating
22system for that matter) you make choices depending on the environment you are
23working with. A setup for a server differs from a setup for a workstation.
24A gaming workstation differs from a 3D rendering workstation.
25</p>
26
27<p>
28This is not only true for choosing what packages you want to install, but also
29what features a certain package should support. If you don't need OpenGL, why
30would you bother installing OpenGL and build OpenGL support in most of your
31packages? If you don't want to use KDE, why would you bother compiling packages
32with KDE-support if those packages work flawlessly without?
33</p>
34
35<p>
36To help users in deciding what to install/activate and what not, we wanted the
37user to specify his/her environment in an easy way. This forces the user into
38deciding what they really want and eases the process for Portage, our package
39managment system, to make useful decisions.
40</p>
41
13</body> 42</body>
14</subsection> 43</subsection>
15<subsection> 44<subsection>
16<title>Definition of a USE-flag</title> 45<title>Definition of a USE-flag</title>
17<body> 46<body>
18 47
48<p>
49Enter the USE-flags. Such a flag is a keyword that embodies support and
50dependency-information for a certain concept. If you define a certain USE-flag,
51Portage will know that you want support for the chosen keyword. Of course
52this also alters the dependency information for a package.
53</p>
54
55<p>
56Let us take a look at a specific example: the <c>kde</c> keyword. If you do not
57have this keyword in your <c>USE</c> variable, all packages that have
58<e>optional</e> KDE support will be compiled <e>without</e> KDE support. All
59packages that have an <e>optional</e> KDE dependency will be installed
60<e>without</e> installing the KDE libraries (as dependency). If you have defined
61the <c>kde</c> keyword, then those packages <e>will</e> be compiled with KDE
62support, and the KDE libraries will be installed as dependency.
63</p>
64
65<p>
66By correctly defining the keywords you will receive a system tailored
67specifically to your needs.
68</p>
69
19</body> 70</body>
20</subsection> 71</subsection>
21<subsection> 72<subsection>
22<title>What USE-flags exist?</title> 73<title>What USE-flags exist?</title>
23<body> 74<body>
75
76<p>
77There are two types of USE-flags: <e>global</e> and <e>local</e> USE-flags.
78</p>
79
80<ul>
81 <li>
82 A <e>global</e> USE-flag is used by several packages, system-wide. This is
83 what most people see as USE-flags.
84 </li>
85 <li>
86 A <e>local</e> USE-flag is used by a single package to make package-specific
87 decisions.
88 </li>
89</ul>
90
91<p>
92A list of available global USE-flags can be found <uri
93link="/dyn/use-index.xml">online</uri> or locally in
94<path>/usr/portage/profiles/use.desc</path>.
95</p>
96
97<p>
98A list of available local USE-flags can be found locally in
99<path>/usr/portage/profiles/use.local.desc</path>.
100</p>
24 101
25</body> 102</body>
26</subsection> 103</subsection>
27</section> 104</section>
28<section> 105<section>
29<title>Using USE-flags</title> 106<title>Using USE-flags</title>
30<subsection> 107<subsection>
31<title>Declare permanent USE-flags</title> 108<title>Declare permanent USE-flags</title>
32<body> 109<body>
33 110
111<p>
112In the hope you are convinced of the importance of USE-flags we will now inform
113you how to declare USE-flags.
114</p>
115
116<p>
117As previously mentioned, all USE-flags are declared inside the <c>USE</c>
118variable. To make it easy for users to search and pick USE-flags, we already
119provide a <e>default</e> USE setting. This setting is a collection of USE-flags
120we think are commonly used by the Gentoo users. This default setting is declared
121in the <path>make.defaults</path> files part of your profile.
122</p>
123
124<p>
125The profile your system listens to is pointed to by the
126<path>/etc/make.profile</path> symlink. Each profile works on top of another,
127larger profile, the end result is therefore the sum of all profiles. The top
128profile is the <path>base</path> profile
129(<path>/usr/portage/profiles/base</path>).
130</p>
131
132<p>
133Let us take a look at this default setting for the 2004.3 profile:
134</p>
135
136<pre caption="Cumulative make.defaults USE variable for the 2004.3 profile">
137<comment>(This example is the sum of the settings in base, default-linux,
138 default-linux/x86 and default-linux/x86/2004.3)</comment>
139USE="x86 oss apm arts avi berkdb bitmap-fonts crypt cups encode fortran f77
140 foomaticdb gdbm gif gpm gtk imlib jpeg kde gnome libg++ libwww mad
141 mikmod motif mpeg ncurses nls oggvorbis opengl pam pdflib png python qt
142 quicktime readline sdl spell ssl svga tcpd truetype X xml2 xmms xv zlib"
143</pre>
144
145<p>
146As you can see, this variable already contains quite a lot of keywords. Do
147<b>not</b> alter any <path>make.defaults</path> file to tailor
148the <c>USE</c> variable to your needs: changes in this file will be undone when
149you update Portage!
150</p>
151
152<p>
153To change this default setting, you need to add or remove keywords to the
154<c>USE</c> variable. This is done globally by defining the <c>USE</c> variable
155in <path>/etc/make.conf</path>. In this variable you add the extra USE-flags you
156require, or remove the USE-flags you don't want. This latter is done by
157prefixing the keyword with the minus-sign ("-").
158</p>
159
160<p>
161For instance, to remove support for KDE and QT but add support for ldap, the
162following <c>USE</c> can be defined in <path>/etc/make.conf</path>:
163</p>
164
165<pre caption="An example USE setting in /etc/make.conf">
166USE="-kde -qt ldap"
167</pre>
168
169</body>
170</subsection>
171<subsection>
172<title>Declaring USE flags for individual packages</title>
173<body>
174
175<p>
176Sometimes you want to declare a certain USE flag for one (or a couple) of
177applications but not system-wide. To accomplish this, you will need to create
178the <path>/etc/portage</path> directory (if it doesn't exist yet) and edit
179<path>/etc/portage/package.use</path>.
180</p>
181
182<p>
183For instance, if you don't want <c>berkdb</c> support globally but you do want
184it for <c>mysql</c>, you would add:
185</p>
186
187<pre caption="/etc/portage/package.use example">
188dev-db/mysql berkdb
189</pre>
190
191<p>
192You can of course also explicitly <e>disable</e> USE flags for a certain
193application. For instance, if you don't want <c>java</c> support in PHP:
194</p>
195
196<pre caption="/etc/portage/package.use 2nd example">
197dev-php/php -java
198</pre>
199
34</body> 200</body>
35</subsection> 201</subsection>
36<subsection> 202<subsection>
37<title>Declare temporary USE-flags</title> 203<title>Declare temporary USE-flags</title>
38<body> 204<body>
39 205
206<p>
207Sometimes you want to set a certain USE-setting only once. Instead of editing
208<path>/etc/make.conf</path> twice (to do and undo the USE-changes) you can just
209declare the USE-variable as environment variable. Remember that, when you
210re-emerge or update this application (either explicitly or as part of a system
211update) your changes will be lost!
212</p>
213
214<p>
215As an example we will temporarily remove java from the USE-setting
216during the installation of mozilla.
217</p>
218
219<pre caption="Using USE as environment variable">
220# <i>USE="-java" emerge mozilla</i>
221</pre>
222
40</body> 223</body>
41</subsection>
42<subsection> 224</subsection>
43<title>Inheriting USE-flags</title> 225<subsection>
226<title>Automatic USE Flags</title>
227<body>
228
229<p>
230After certain packages are installed, additional USE flags will automatically
231be enabled for you if you do not explicitly disable them. To view the list
232of packages that trigger automatic USE-flags, check
233<path>/etc/make.profile/use.defaults</path> and the <path>use.defaults</path>
234files of the parent profiles.
235</p>
236
237<pre caption="A snippet from /etc/make.profile/use.defaults">
238gnome gnome-base/gnome
239gtk x11-libs/gtk+
240qt x11-libs/qt
241kde kde-base/kdebase
242motif x11-libs/openmotif
243</pre>
244
44<body> 245</body>
246</subsection>
247<subsection>
248<title>Precedence</title>
249<body>
250
251<p>
252Of course there is a certain precedence on what setting has priority over the
253USE setting. You don't want to declare <c>USE="-java"</c> only to see that
254<c>java</c> is still used due to a setting that has a higher priority.
255The precedence for the USE setting is, ordered
256by priority (first has lowest priority):
257</p>
258
259<ol>
260 <li>
261 Default USE setting declared in the <path>make.defaults</path> files part of
262 your profile
263 </li>
264 <li>
265 Inherited USE setting if a package from profile <path>use.defaults</path>
266 is installed
267 </li>
268 <li>
269 User-defined USE setting in <path>/etc/make.conf</path>
270 </li>
271 <li>
272 User-defined USE setting in <path>/etc/portage/package.use</path>
273 </li>
274 <li>
275 User-defined USE setting as environment variable
276 </li>
277</ol>
278
279<p>
280To view the final <c>USE</c> setting as seen by Portage, run <c>emerge
281--info</c>. This will list all relevant variables (including the <c>USE</c>
282variable) with the content used by Portage.
283</p>
284
285<pre caption="Running emerge --info">
286# <i>emerge --info</i>
287</pre>
288
289</body>
290</subsection>
291<subsection>
292<title>Adapting your Entire System to New USE Flags</title>
293<body>
294
295<p>
296If you have altered your USE flags and you wish to update your entire system to
297use the new USE flags, use <c>emerge</c>'s <c>--newuse</c> option:
298</p>
299
300<pre caption="Rebuilding your entire system">
301# <i>emerge --update --deep --newuse world</i>
302</pre>
303
304<p>
305Next, run Portage's depclean to remove the conditional dependencies that
306were emerged on your "old" system but that have been obsoleted by the new USE
307flags.
308</p>
309
310<warn>
311Running <c>emerge --depclean</c> is a dangerous operation and should be handled
312with care. Double-check the provided list of "obsoleted" packages to make sure
313it doesn't remove packages you need. In the following example we add the
314<c>-p</c> switch to have depclean only list the packages without removing them.
315</warn>
316
317<pre caption="Removing obsoleted packages">
318# <i>emerge -p --depclean</i>
319</pre>
320
321<p>
322When depclean has finished, run <c>revdep-rebuild</c> to rebuild the
323applications that are dynamically linked against shared objects provided by
324possibly removed packages. <c>revdep-rebuild</c> is part of the
325<c>gentoolkit</c> package; don't forget to emerge it first.
326</p>
327
328<pre caption="Running revdep-rebuild">
329# <i>revdep-rebuild</i>
330</pre>
331
332<p>
333When all this is accomplished, your system is using the new USE flag settings.
334</p>
45 335
46</body> 336</body>
47</subsection> 337</subsection>
48</section> 338</section>
49<section> 339<section>
50<title>Package specific USE-flags</title> 340<title>Package specific USE-flags</title>
51<subsection> 341<subsection>
52<title>Viewing used USE-flags</title> 342<title>Viewing available USE-flags</title>
53<body> 343<body>
344
345<p>
346Let us take the example of <c>mozilla</c>: what USE-flags does it listen to? To
347find out, we use <c>emerge</c> with the <c>--pretend</c> and <c>--verbose</c>
348options:
349</p>
350
351<pre caption="Viewing the used USE-flags">
352# <i>emerge --pretend --verbose mozilla</i>
353These are the packages that I would merge, in order:
354
355Calculating dependencies ...done!
356[ebuild R ] www-client/mozilla-1.7.12-r2 USE="crypt gnome java mozsvg ssl
357truetype xprint -debug -ipv6 -ldap -mozcalendar -mozdevelop -moznocompose
358-moznoirc -moznomail -moznoxft -postgres -xinerama" 0 kB
359</pre>
360
361<p>
362<c>emerge</c> isn't the only tool for this job. In fact, we have a tool
363dedicated to package information called <c>equery</c> which resides in the
364<c>gentoolkit</c> package. First, install <c>gentoolkit</c>:
365</p>
366
367<pre caption="Installing gentoolkit">
368# <i>emerge gentoolkit</i>
369</pre>
370
371<p>
372Now run <c>equery</c> with the <c>uses</c> argument to view the USE-flags of a
373certain package. For instance, for the <c>gnumeric</c> package:
374</p>
375
376<pre caption="Using equery to view used USE-flags">
377# <i>equery uses gnumeric</i>
378[ Colour Code : <i>set</i> <comment>unset</comment> ]
379[ Legend : (U) Col 1 - Current USE flags ]
380[ : (I) Col 2 - Installed With USE flags ]
381
382 U I [ Found these USE variables in : app-office/gnumeric-1.2.0 ]
383 - - <comment>libgda</comment> : Adds GNU Data Access (CORBA wrapper) support for gnumeric
384 - - <comment>gnomedb</comment> : unknown
385 + + <i>python</i> : Adds support/bindings for the Python language
386 + + <i>bonobo</i> : Adds support for gnome-base/bonobo (Gnome CORBA interfaces)
387</pre>
54 388
55</body> 389</body>
56</subsection> 390</subsection>
57</section> 391</section>
58</sections> 392</sections>

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.38

  ViewVC Help
Powered by ViewVC 1.1.20