/[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.41 - (show annotations) (download) (as text)
Sun Jul 16 09:10:55 2006 UTC (8 years, 2 months ago) by neysx
Branch: MAIN
Changes since 1.40: +3 -29 lines
File MIME type: application/xml
#140538 Removed auto USE flags

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.40 2006/03/27 19:45:15 nightmorph Exp $ -->
8
9 <sections>
10
11 <version>1.33</version>
12 <date>2006-07-16</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 management 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>Precedence</title>
227 <body>
228
229 <p>
230 Of course there is a certain precedence on what setting has priority over the
231 USE setting. You don't want to declare <c>USE="-java"</c> only to see that
232 <c>java</c> is still used due to a setting that has a higher priority.
233 The precedence for the USE setting is, ordered
234 by priority (first has lowest priority):
235 </p>
236
237 <ol>
238 <li>
239 Default USE setting declared in the <path>make.defaults</path> files part of
240 your profile
241 </li>
242 <li>
243 User-defined USE setting in <path>/etc/make.conf</path>
244 </li>
245 <li>
246 User-defined USE setting in <path>/etc/portage/package.use</path>
247 </li>
248 <li>
249 User-defined USE setting as environment variable
250 </li>
251 </ol>
252
253 <p>
254 To view the final <c>USE</c> setting as seen by Portage, run <c>emerge
255 --info</c>. This will list all relevant variables (including the <c>USE</c>
256 variable) with the content used by Portage.
257 </p>
258
259 <pre caption="Running emerge --info">
260 # <i>emerge --info</i>
261 </pre>
262
263 </body>
264 </subsection>
265 <subsection>
266 <title>Adapting your Entire System to New USE Flags</title>
267 <body>
268
269 <p>
270 If you have altered your USE flags and you wish to update your entire system to
271 use the new USE flags, use <c>emerge</c>'s <c>--newuse</c> option:
272 </p>
273
274 <pre caption="Rebuilding your entire system">
275 # <i>emerge --update --deep --newuse world</i>
276 </pre>
277
278 <p>
279 Next, run Portage's depclean to remove the conditional dependencies that
280 were emerged on your "old" system but that have been obsoleted by the new USE
281 flags.
282 </p>
283
284 <warn>
285 Running <c>emerge --depclean</c> is a dangerous operation and should be handled
286 with care. Double-check the provided list of "obsoleted" packages to make sure
287 it doesn't remove packages you need. In the following example we add the
288 <c>-p</c> switch to have depclean only list the packages without removing them.
289 </warn>
290
291 <pre caption="Removing obsoleted packages">
292 # <i>emerge -p --depclean</i>
293 </pre>
294
295 <p>
296 When depclean has finished, run <c>revdep-rebuild</c> to rebuild the
297 applications that are dynamically linked against shared objects provided by
298 possibly removed packages. <c>revdep-rebuild</c> is part of the
299 <c>gentoolkit</c> package; don't forget to emerge it first.
300 </p>
301
302 <pre caption="Running revdep-rebuild">
303 # <i>revdep-rebuild</i>
304 </pre>
305
306 <p>
307 When all this is accomplished, your system is using the new USE flag settings.
308 </p>
309
310 </body>
311 </subsection>
312 </section>
313 <section>
314 <title>Package specific USE-flags</title>
315 <subsection>
316 <title>Viewing available USE-flags</title>
317 <body>
318
319 <p>
320 Let us take the example of <c>mozilla</c>: what USE-flags does it listen to? To
321 find out, we use <c>emerge</c> with the <c>--pretend</c> and <c>--verbose</c>
322 options:
323 </p>
324
325 <pre caption="Viewing the used USE-flags">
326 # <i>emerge --pretend --verbose mozilla</i>
327 These are the packages that I would merge, in order:
328
329 Calculating dependencies ...done!
330 [ebuild R ] www-client/mozilla-1.7.12-r2 USE="crypt gnome java mozsvg ssl
331 truetype xprint -debug -ipv6 -ldap -mozcalendar -mozdevelop -moznocompose
332 -moznoirc -moznomail -moznoxft -postgres -xinerama" 0 kB
333 </pre>
334
335 <p>
336 <c>emerge</c> isn't the only tool for this job. In fact, we have a tool
337 dedicated to package information called <c>equery</c> which resides in the
338 <c>gentoolkit</c> package. First, install <c>gentoolkit</c>:
339 </p>
340
341 <pre caption="Installing gentoolkit">
342 # <i>emerge gentoolkit</i>
343 </pre>
344
345 <p>
346 Now run <c>equery</c> with the <c>uses</c> argument to view the USE-flags of a
347 certain package. For instance, for the <c>gnumeric</c> package:
348 </p>
349
350 <pre caption="Using equery to view used USE-flags">
351 # <i>equery uses gnumeric</i>
352 [ Colour Code : <i>set</i> <comment>unset</comment> ]
353 [ Legend : (U) Col 1 - Current USE flags ]
354 [ : (I) Col 2 - Installed With USE flags ]
355
356 U I [ Found these USE variables in : app-office/gnumeric-1.2.0 ]
357 - - <comment>libgda</comment> : Adds GNU Data Access (CORBA wrapper) support for gnumeric
358 - - <comment>gnomedb</comment> : unknown
359 + + <i>python</i> : Adds support/bindings for the Python language
360 + + <i>bonobo</i> : Adds support for gnome-base/bonobo (Gnome CORBA interfaces)
361 </pre>
362
363 </body>
364 </subsection>
365 </section>
366 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20