/[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.39 - (show annotations) (download) (as text)
Tue Mar 14 19:29:29 2006 UTC (8 years, 1 month ago) by neysx
Branch: MAIN
Changes since 1.38: +2 -2 lines
File MIME type: application/xml
#126195 bump license version in comment, **no content change**

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.5 -->
6
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 $ -->
8
9 <sections>
10
11 <version>1.32</version>
12 <date>2006-01-13</date>
13
14 <section>
15 <title>What are USE-flags?</title>
16 <subsection>
17 <title>The ideas behind USE-flags</title>
18 <body>
19
20 <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 with KDE-support if those packages work flawlessly without?
33 </p>
34
35 <p>
36 To help users in deciding what to install/activate and what not, we wanted the
37 user to specify his/her environment in an easy way. This forces the user into
38 deciding what they really want and eases the process for Portage, our package
39 managment system, to make useful decisions.
40 </p>
41
42 </body>
43 </subsection>
44 <subsection>
45 <title>Definition of a USE-flag</title>
46 <body>
47
48 <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 Portage will know that you want support for the chosen keyword. Of course
52 this also alters the dependency information for a package.
53 </p>
54
55 <p>
56 Let us take a look at a specific example: the <c>kde</c> keyword. If you do not
57 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 </body>
71 </subsection>
72 <subsection>
73 <title>What USE-flags exist?</title>
74 <body>
75
76 <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 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>
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>.
95 </p>
96
97 <p>
98 A list of available local USE-flags can be found locally in
99 <path>/usr/portage/profiles/use.local.desc</path>.
100 </p>
101
102 </body>
103 </subsection>
104 </section>
105 <section>
106 <title>Using USE-flags</title>
107 <subsection>
108 <title>Declare permanent USE-flags</title>
109 <body>
110
111 <p>
112 In the hope you are convinced of the importance of USE-flags we will now inform
113 you how to declare USE-flags.
114 </p>
115
116 <p>
117 As previously mentioned, all USE-flags are declared inside the <c>USE</c>
118 variable. To make it easy for users to search and pick USE-flags, we already
119 provide a <e>default</e> USE setting. This setting is a collection of USE-flags
120 we think are commonly used by the Gentoo users. This default setting is declared
121 in the <path>make.defaults</path> files part of your profile.
122 </p>
123
124 <p>
125 The profile your system listens to is pointed to by the
126 <path>/etc/make.profile</path> symlink. Each profile works on top of another,
127 larger profile, the end result is therefore the sum of all profiles. The top
128 profile is the <path>base</path> profile
129 (<path>/usr/portage/profiles/base</path>).
130 </p>
131
132 <p>
133 Let 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>
139 USE="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>
146 As 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
148 the <c>USE</c> variable to your needs: changes in this file will be undone when
149 you update Portage!
150 </p>
151
152 <p>
153 To 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
155 in <path>/etc/make.conf</path>. In this variable you add the extra USE-flags you
156 require, or remove the USE-flags you don't want. This latter is done by
157 prefixing the keyword with the minus-sign ("-").
158 </p>
159
160 <p>
161 For instance, to remove support for KDE and QT but add support for ldap, the
162 following <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">
166 USE="-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>
176 Sometimes you want to declare a certain USE flag for one (or a couple) of
177 applications but not system-wide. To accomplish this, you will need to create
178 the <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>
183 For instance, if you don't want <c>berkdb</c> support globally but you do want
184 it for <c>mysql</c>, you would add:
185 </p>
186
187 <pre caption="/etc/portage/package.use example">
188 dev-db/mysql berkdb
189 </pre>
190
191 <p>
192 You can of course also explicitly <e>disable</e> USE flags for a certain
193 application. 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">
197 dev-php/php -java
198 </pre>
199
200 </body>
201 </subsection>
202 <subsection>
203 <title>Declare temporary USE-flags</title>
204 <body>
205
206 <p>
207 Sometimes 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
209 declare the USE-variable as environment variable. Remember that, when you
210 re-emerge or update this application (either explicitly or as part of a system
211 update) your changes will be lost!
212 </p>
213
214 <p>
215 As an example we will temporarily remove java from the USE-setting
216 during 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
223 </body>
224 </subsection>
225 <subsection>
226 <title>Automatic USE Flags</title>
227 <body>
228
229 <p>
230 After certain packages are installed, additional USE flags will automatically
231 be enabled for you if you do not explicitly disable them. To view the list
232 of packages that trigger automatic USE-flags, check
233 <path>/etc/make.profile/use.defaults</path> and the <path>use.defaults</path>
234 files of the parent profiles.
235 </p>
236
237 <pre caption="A snippet from /etc/make.profile/use.defaults">
238 gnome gnome-base/gnome
239 gtk x11-libs/gtk+
240 qt x11-libs/qt
241 kde kde-base/kdebase
242 motif x11-libs/openmotif
243 </pre>
244
245 </body>
246 </subsection>
247 <subsection>
248 <title>Precedence</title>
249 <body>
250
251 <p>
252 Of course there is a certain precedence on what setting has priority over the
253 USE 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.
255 The precedence for the USE setting is, ordered
256 by 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>
280 To 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>
282 variable) 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>
296 If you have altered your USE flags and you wish to update your entire system to
297 use 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>
305 Next, run Portage's depclean to remove the conditional dependencies that
306 were emerged on your "old" system but that have been obsoleted by the new USE
307 flags.
308 </p>
309
310 <warn>
311 Running <c>emerge --depclean</c> is a dangerous operation and should be handled
312 with care. Double-check the provided list of "obsoleted" packages to make sure
313 it 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>
322 When depclean has finished, run <c>revdep-rebuild</c> to rebuild the
323 applications that are dynamically linked against shared objects provided by
324 possibly 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>
333 When all this is accomplished, your system is using the new USE flag settings.
334 </p>
335
336 </body>
337 </subsection>
338 </section>
339 <section>
340 <title>Package specific USE-flags</title>
341 <subsection>
342 <title>Viewing available USE-flags</title>
343 <body>
344
345 <p>
346 Let us take the example of <c>mozilla</c>: what USE-flags does it listen to? To
347 find out, we use <c>emerge</c> with the <c>--pretend</c> and <c>--verbose</c>
348 options:
349 </p>
350
351 <pre caption="Viewing the used USE-flags">
352 # <i>emerge --pretend --verbose mozilla</i>
353 These are the packages that I would merge, in order:
354
355 Calculating dependencies ...done!
356 [ebuild R ] www-client/mozilla-1.7.12-r2 USE="crypt gnome java mozsvg ssl
357 truetype 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
363 dedicated 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>
372 Now run <c>equery</c> with the <c>uses</c> argument to view the USE-flags of a
373 certain 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>
388
389 </body>
390 </subsection>
391 </section>
392 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20