/[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.25 - (hide annotations) (download) (as text)
Sun Dec 26 14:56:32 2004 UTC (10 years ago) by swift
Branch: MAIN
Changes since 1.24: +10 -8 lines
File MIME type: application/xml
#75466 - Update to reflect cascading profiles changes - make.defaults is now sum of all make.defaults files

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.25 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-use.xml,v 1.24 2004/11/20 22:23:30 neysx Exp $ -->
8 swift 1.1
9     <sections>
10 swift 1.22
11 swift 1.25 <version>1.22</version>
12     <date>2004-12-26</date>
13 swift 1.22
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 swift 1.25 in the <path>make.defaults</path> files part of your profile. Let us take a
133     look at this default setting:
134 swift 1.2 </p>
135    
136 swift 1.25 <pre caption="/usr/portage/profiles/default-linux/x86/2004.3/make.defaults USE variable">
137     <comment>(This is an example and might have changed since it was taken)</comment>
138 neysx 1.14 USE="x86 oss apm arts avi berkdb crypt cups encode foomaticdb gdbm gif gpm
139     gtk gtk2 imlib jpeg kde gnome libg++ libwww mad mikmod motif mpeg ncurses
140     nls oggvorbis opengl pam pdflib png python qt quicktime readline sdl
141     slang spell ssl svga tcpd truetype X xml2 xmms xv zlib"
142 swift 1.2 </pre>
143    
144     <p>
145     As you can see, this variable already contains quite a lot of keywords. Do
146 swift 1.25 <b>not</b> alter any <path>make.defaults</path> file to tailor
147 swift 1.2 the <c>USE</c> variable to your needs: changes in this file will be undone when
148     you update Portage!
149     </p>
150    
151     <p>
152     To change this default setting, you need to add or remove keywords to the
153     <c>USE</c> variable. This is done globally by defining the <c>USE</c> variable
154     in <path>/etc/make.conf</path>. In this variable you add the extra USE-flags you
155     require, or remove the USE-flags you don't want. This latter is done by
156     prefixing the keyword with the minus-sign ("-").
157     </p>
158    
159     <p>
160     For instance, to remove support for KDE and QT but add support for ldap, the
161     following <c>USE</c> can be defined in <path>/etc/make.conf</path>:
162     </p>
163    
164     <pre caption="An example USE setting in /etc/make.conf">
165     USE="-kde -qt ldap"
166     </pre>
167    
168 swift 1.19 </body>
169     </subsection>
170     <subsection>
171     <title>Declaring USE flags for individual packages</title>
172     <body>
173    
174 swift 1.17 <p>
175     Sometimes you want to declare a certain USE flag for one (or a couple) of
176     applications but not system-wide. To accomplish this, you will need to create
177     the <path>/etc/portage</path> directory (if it doesn't exist yet) and edit
178     <path>/etc/portage/package.use</path>.
179     </p>
180    
181     <p>
182     For instance, if you don't want <c>berkdb</c> support globally but you do want
183     it for <c>mysql</c>, you would add:
184     </p>
185    
186     <pre caption="/etc/portage/package.use example">
187     dev-db/mysql berkdb
188     </pre>
189    
190     <p>
191     You can of course also explicitly <e>disable</e> USE flags for a certain
192     application. For instance, if you don't want <c>java</c> support in PHP:
193     </p>
194    
195     <pre caption="/etc/portage/package.use 2nd example">
196     dev-php/php -java
197     </pre>
198    
199 swift 1.1 </body>
200     </subsection>
201     <subsection>
202     <title>Declare temporary USE-flags</title>
203     <body>
204    
205 swift 1.2 <p>
206     Sometimes you want to set a certain USE-setting only once. Instead of editing
207     <path>/etc/make.conf</path> twice (to do and undo the USE-changes) you can just
208 swift 1.17 declare the USE-variable as environment variable. Remember that, when you
209     re-emerge or update this application (either explicitly or as part of a system
210     update) your changes will be lost!
211 swift 1.2 </p>
212    
213     <p>
214     As an example we will temporarily remove java from the USE-setting
215     during the installation of mozilla.
216     </p>
217    
218 swift 1.13 <pre caption="Using USE as environment variable">
219 swift 1.2 # <i>USE="-java" emerge mozilla</i>
220     </pre>
221    
222 swift 1.1 </body>
223     </subsection>
224     <subsection>
225     <title>Inheriting USE-flags</title>
226     <body>
227    
228 swift 1.2 <p>
229     Some packages don't only listen to USE-flags, but also provide USE-flags. When
230     you install such a package, the USE-flag they provide is added to your USE
231     setting. To view the list of packages that provide a USE-flag, check
232     <path>/etc/make.profile/use.defaults</path>:
233     </p>
234    
235     <pre caption="A snippet from /etc/make.profile/use.defaults">
236     gnome gnome-base/gnome
237     gtk x11-libs/gtk+
238     qt x11-libs/qt
239     kde kde-base/kdebase
240     motif x11-libs/openmotif
241     </pre>
242    
243     </body>
244     </subsection>
245     <subsection>
246 swift 1.15 <title>Precedence</title>
247 swift 1.2 <body>
248    
249     <p>
250 neysx 1.16 Of course there is a certain precedence on what setting has priority over the
251 swift 1.2 USE setting. You don't want to declare <c>USE="-java"</c> only to see that
252     <c>java</c> is declared anyway. The precedence for the USE setting is, ordered
253     by priority (first has lowest priority):
254     </p>
255    
256     <ol>
257     <li>
258 swift 1.25 Default USE setting declared in the <path>make.defaults</path> files part of
259     your profile
260 swift 1.2 </li>
261     <li>
262     Inherited USE setting if a package from
263     <path>/etc/make.profile/use.defaults</path> is installed
264     </li>
265     <li>
266     User-defined USE setting in <path>/etc/make.conf</path>
267     </li>
268     <li>
269 swift 1.17 User-defined USE setting in <path>/etc/portage/package.use</path>
270     </li>
271     <li>
272 swift 1.2 User-defined USE setting as environment variable
273     </li>
274     </ol>
275 swift 1.4
276     <p>
277     To view the final <c>USE</c> setting as seen by Portage, run <c>emerge info</c>.
278     This will list all relevant variables (including the <c>USE</c> variable) with
279     the content used by Portage.
280     </p>
281    
282     <pre caption="Running emerge info">
283     # <i>emerge info</i>
284     </pre>
285 swift 1.2
286 swift 1.1 </body>
287     </subsection>
288 swift 1.12 <subsection>
289     <title>Adapting your Entire System to New USE Flags</title>
290     <body>
291    
292     <p>
293     If you have altered your USE flags and you wish to update your entire system to
294 swift 1.21 use the new USE flags, use <c>emerge</c>'s <c>--newuse</c> option:
295 swift 1.12 </p>
296    
297     <pre caption="Rebuilding your entire system">
298 swift 1.21 # <i>emerge --update --deep --newuse world</i>
299 swift 1.12 </pre>
300    
301     <p>
302 swift 1.20 Next, run Portage's depclean to remove the conditional dependencies that
303 swift 1.12 were emerged on your "old" system but that have been obsoleted by the new USE
304     flags.
305     </p>
306    
307     <warn>
308     Running <c>emerge depclean</c> is a dangerous operation and should be handled
309     with care. Double-check the provided list of "obsoleted" packages to make sure
310     it doesn't remove packages you need. In the following example we add the
311     <c>-p</c> switch to have depclean only list the packages without removing them.
312     </warn>
313    
314     <pre caption="Removing obsoleted packages">
315     # <i>emerge -p depclean</i>
316     </pre>
317    
318     <p>
319 swift 1.21 When depclean has finished, run <c>revdep-rebuild</c> to rebuild the
320     applications that are dynamically linked against shared objects provided by
321     possibly removed packages. <c>revdep-rebuild</c> is part of the
322     <c>gentoolkit</c> package; don't forget to emerge it first.
323     </p>
324    
325     <pre caption="Running revdep-rebuild">
326     # <i>revdep-rebuild</i>
327     </pre>
328    
329     <p>
330     When all this is accomplished, your system is using the new USE flag settings.
331 swift 1.12 </p>
332    
333     </body>
334     </subsection>
335 swift 1.1 </section>
336     <section>
337     <title>Package specific USE-flags</title>
338     <subsection>
339 swift 1.2 <title>Viewing available USE-flags</title>
340 swift 1.1 <body>
341 swift 1.2
342     <p>
343     Let us take the example of <c>mozilla</c>: what USE-flags does it listen to? To
344 swift 1.21 find out, we use <c>emerge</c> with the <c>--pretend</c> and <c>--verbose</c>
345     options:
346 swift 1.2 </p>
347    
348     <pre caption="Viewing the used USE-flags">
349     # <i>emerge --pretend --verbose mozilla</i>
350     These are the packages that I would merge, in order:
351    
352     Calculating dependencies ...done!
353     [ebuild N ] net-www/mozilla-1.5-r1 +java +crypt -ipv6 -gtk2 +ssl +ldap
354     +gnome -debug +mozcalendar -mozaccess -mozxmlterm -moznoirc -moznomail
355     -moznocompose -moznoxft
356     </pre>
357    
358     <p>
359     <c>emerge</c> isn't the only tool for this job. In fact, we have a tool
360     dedicated to package information called <c>etcat</c> which resides in the
361     <c>gentoolkit</c> package. First, install <c>gentoolkit</c>:
362     </p>
363    
364     <pre caption="Installing gentoolkit">
365 swift 1.21 # <i>emerge gentoolkit</i>
366 swift 1.2 </pre>
367    
368     <p>
369     Now run <c>etcat</c> with the <c>uses</c> argument to view the USE-flags of a
370     certain package. For instance, for the <c>gnumeric</c> package:
371     </p>
372    
373     <pre caption="Using etcat to view used USE-flags">
374     # <i>etcat uses gnumeric</i>
375     [ Colour Code : <i>set</i> <comment>unset</comment> ]
376     [ Legend : (U) Col 1 - Current USE flags ]
377     [ : (I) Col 2 - Installed With USE flags ]
378    
379     U I [ Found these USE variables in : app-office/gnumeric-1.2.0 ]
380     - - <comment>libgda</comment> : Adds GNU Data Access (CORBA wrapper) support for gnumeric
381     - - <comment>gnomedb</comment> : unknown
382     + + <i>python</i> : Adds support/bindings for the Python language
383     + + <i>bonobo</i> : Adds support for gnome-base/bonobo (Gnome CORBA interfaces)
384     </pre>
385 swift 1.1
386     </body>
387     </subsection>
388     </section>
389     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20