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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.22 - (hide annotations) (download) (as text)
Tue Nov 9 13:01:52 2004 UTC (9 years, 8 months ago) by swift
Branch: MAIN
Changes since 1.21: +5 -1 lines
File MIME type: application/xml
Adding version/date information in pages

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

  ViewVC Help
Powered by ViewVC 1.1.20