/[gentoo]/xml/htdocs/doc/en/gentoolkit.xml
Gentoo

Diff of /xml/htdocs/doc/en/gentoolkit.xml

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

Revision 1.19 Revision 1.20
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.19 2005/04/07 17:58:39 swift Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.20 2005/04/23 10:09:15 yoswink Exp $ -->
3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4 4
5<guide link="/doc/en/gentoolkit.xml"> 5<guide link="/doc/en/gentoolkit.xml">
6<title>Gentoolkit</title> 6<title>Gentoolkit</title>
7 7
8<author title="Author"> 8<author title="Author">
9 <mail link="mbutcher@aleph-null.tv">Matt Butcher</mail> 9 <mail link="mbutcher@aleph-null.tv">Matt Butcher</mail>
10</author> 10</author>
11<author title="Editor"> 11<author title="Editor">
12 <!-- zhen@gentoo.org -->John P. Davis 12 <!-- zhen@gentoo.org -->John P. Davis
13</author> 13</author>
14<author title="Editor"> 14<author title="Editor">
15 <mail link="erwin@gentoo.org">Erwin</mail> 15 <mail link="erwin@gentoo.org">Erwin</mail>
16</author> 16</author>
17<author title="Editor"> 17<author title="Editor">
18 <mail link="fox2mike@gmail.com">Shyam Mani</mail> 18 <mail link="fox2mike@gmail.com">Shyam Mani</mail>
19</author> 19</author>
20<author title="Editor"> 20<author title="Editor">
21 <mail link="neysx@gentoo.org">Xavier Neys</mail> 21 <mail link="neysx@gentoo.org">Xavier Neys</mail>
22</author> 22</author>
23 23<author title="Editor">
24<!-- Licensed under GFDL --> 24 <mail link="karltk@gentoo.org">Karl Trygve</mail>
25</author>
26<author title="Editor">
27 <mail link="yoswink@gentoo.org">José Luis Rivero</mail>
28</author>
25 29
26<abstract> 30<abstract>
27Gentoolkit is a suite of tools to ease the administration of a Gentoo system. 31Gentoolkit is a suite of tools to ease the administration of a Gentoo system.
28This document covers the basics of some of the tools present in Gentoolkit. 32This document covers the basics of some of the tools present in Gentoolkit.
29</abstract> 33</abstract>
30 34
35<!-- Licensed under GFDL -->
36
31<version>1.6</version> 37<version>1.7</version>
32<date>2005-04-07</date> 38<date>2005-04-23</date>
33 39
34<chapter> 40<chapter>
35<title>Introduction</title> 41<title>Introduction</title>
36<section> 42<section>
37<title>What is Gentoolkit?</title> 43<title>What is Gentoolkit?</title>
38<body> 44<body>
39 45
40<p> 46<p>
41Gentoo is a unique distribution and presents some complexities that simply 47Gentoo is a unique distribution and presents some complexities that simply
42don't exist for other distributions. As Gentoo developers and contributors 48don't exist for other distributions. As Gentoo developers and contributors
43discovered some of these complexities, they also wrote tools to help users and 49discovered some of these complexities, they also wrote tools to help users and
44administrators work around them. Many of these tools have been contributed to 50administrators work around them. Many of these tools have been contributed to
45the Gentoo project and are included in the package 51the Gentoo project and are included in the package
46<c>app-portage/gentoolkit</c>. 52<c>app-portage/gentoolkit</c>.
47</p> 53</p>
48 54
49<note> 55<note>
50As of now, there are two versions of gentoolkit: <c>app-portage/gentoolkit</c> 56As of now, there are two versions of gentoolkit: <c>app-portage/gentoolkit</c>
51and <c>app-portage/gentoolkit-dev</c>. While the former contains administration 57and <c>app-portage/gentoolkit-dev</c>. While the former contains administration
52scripts, the latter contains scripts specific to help development on Gentoo. 58scripts, the latter contains scripts specific to help development on Gentoo.
59If you are a developer, you can have your scripts included into
60<c>gentoolkit-dev</c> by contacting the Gentoolkit maintainer. This document
53This document discusses gentoolkit only. 61discusses gentoolkit only.
54</note> 62</note>
55 63
56<p> 64<p>
57Gentoolkit contains a whole bunch of useful tools to help manage your packages 65Gentoolkit contains a whole bunch of useful tools to help manage your packages
58and keep track of what is going on in your system. Most users --&nbsp;particularly 66and keep track of what is going on in your system. Most users --&nbsp;particularly
59those who update systems often&nbsp;-- will benefit from having gentoolkit 67those who update systems often&nbsp;-- will benefit from having gentoolkit
60installed. 68installed.
61</p> 69</p>
62 70
63</body> 71</body>
64</section> 72</section>
65<section> 73<section>
66<title>Installation</title> 74<title>Installation</title>
67<body> 75<body>
68 76
90Any documentation that a program might have (other than man pages) is stored in 98Any documentation that a program might have (other than man pages) is stored in
91<path>/usr/doc/gentoolkit-[version]/[program-name]/</path>. 99<path>/usr/doc/gentoolkit-[version]/[program-name]/</path>.
92</p> 100</p>
93 101
94</body> 102</body>
95</section> 103</section>
96</chapter> 104</chapter>
97 105
98<chapter> 106<chapter>
99<title>equery</title> 107<title>equery</title>
100<section> 108<section>
101<title>Introduction</title> 109<title>Introduction</title>
102<body> 110<body>
103 111
104<p> 112<p>
105<c>equery</c> is a tool that supports features that <c>epm</c> (and the 113<c>equery</c> is a tool that supports some features of <c>epm</c> (and the
106deprecated <c>qpkg</c>) has but has its own set of features that make it 114deprecated <c>qpkg</c>) together with its own set of features that make it
107really useful. <c>equery --help</c> gives you the full set of options. 115really useful. <c>equery --help</c> gives you the full set of options.
108<c>equery</c> will eventually replace <c>etcat</c> at some point of time. 116<c>equery</c> will eventually replace <c>etcat</c> in a future release of
117Gentoolkit.
109</p> 118</p>
110 119
111<note> 120<note>
112Not all features listed by <c>equery --help</c> have been implemented yet. 121Not all features listed by <c>equery --help</c> have been implemented yet.
113Those that have not been, are mentioned clearly. 122Those that have not been, are mentioned clearly. You will also see that
123every command has a short option, e.g. <c>b</c> instead of <c>belongs</c>.
114</note> 124</note>
115 125
126<note>
127Be aware that equery currently changes the format of the output if it is
128sent through a pipe. The piped format is intended to be easier to parse by
129tools, but has turned out to be less popular and will probably change in
130the future. If you write scripts that employ equery, you should be aware
131of this.
132</note>
133
116</body> 134</body>
117</section>
118<section> 135</section>
119<title>Finding out Package Sizes</title>
120<body>
121
122<p>
123Ever been curious to find out how much space a specific package is occupying?
124Since a package could have its files over a number of directories, the usual
125<c>du -hc</c> might not give you the correct figure. Not to worry, here comes
126<c>equery</c> to the rescue!
127</p>
128
129<pre caption="Package Size">
130# <i>equery size openoffice-bin</i>
131* app-office/openoffice-bin-1.1.2
132 Total Files : 2908
133 Total Size : 223353.31 KiB
134</pre>
135
136<p>
137As you can see, <c>equery</c> prints the total space used in kilobytes and also
138lists the total number of files the package has.
139</p>
140
141</body>
142</section> 136<section>
137<title>Finding the Package That a File Came From</title>
138<body>
139
140<p>
141<c>equery</c> also provides the functionality of finding the package that a
142file came from, using <c>belongs</c> command (or just <c>b</c>).
143</p>
144
145<pre caption="Finding the ebuild that installed a given file">
146# <i>equery belongs /usr/bin/xmms</i>
147[ Searching for file(s) /usr/bin/xmms in *... ]
148media-sound/xmms-1.2.10-r9 (/usr/bin/xmms)
149</pre>
150
151<p>
152By using the <c>-f</c> option, you may search for packages with files
153matching any regular expression. The <c>-e</c> option is useful for
154terminating your search immediately when a match is found.
155</p>
156
157</body>
143<section> 158</section>
144<title>Package-wise list of USE Flags</title>
145<body>
146
147<p>
148<c>equery</c> can be used to give us information about what USE flags are being
149used by a specific package. It tells us what our current USE flags are for a
150package and what USE flags are available for the package.
151</p>
152
153<pre caption="Set and Unset USE Flags">
154# <i>equery uses ethereal</i>
155[ Colour Code : set unset ]
156[ Legend : (U) Col 1 - Current USE flags ]
157[ : (I) Col 2 - Installed With USE flags ]
158
159 U I [ Found these USE variables in : net-analyzer/ethereal-0.10.6 ]
160 - - adns : Adds support for the adns DNS client library
161 + + gtk : Adds support for x11-libs/gtk+ (The GIMP Toolkit)
162 - - ipv6 : Adds support for IP version 6
163 - - snmp : Adds support for the Simple Network Management Protocol if available
164 + + ssl : Adds support for Secure Socket Layer connections
165 + + gtk2 : Use gtk+-2.0.0 over gtk+-1.2 in cases where a program supports both.
166 - - debug : Tells configure and the makefiles to build for debugging. Effects vary across packages,
167 but generally it will at least add -g to CFLAGS. Remember to set FEATURES=nostrip too
168</pre>
169
170<p>
171I have installed ethereal with only the gtk, ssl and gtk2 flags set, but the
172other USE flags for ethereal are adns, ipv6, snmp and debug. For more
173information on USE flags, please refer to the <uri
174link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>
175chapter of the <uri link="/doc/en/handbook/">Gentoo Handbook</uri>.
176</p>
177
178</body>
179</section> 159<section>
160<title>Verifying Package Integrity</title>
161<body>
162
163<p>
164Sometimes it is useful to check a package's integrity. <c>equery</c> can
165verify md5 sums as well as timestamps to indicate when a package might
166have been corrupted, replaced, or removed.
167</p>
168
169<pre caption="OK package integrity">
170# <i>equery check gentoolkit</i>
171[ Checking app-portage/gentoolkit-0.2.0 ]
172 * 54 out of 54 files good
173</pre>
174
175<p>
176Please note that if you change configuration files after installation,
177these may be reported as "not good".
178</p>
179
180</body>
180<section> 181</section>
181<title>Where's the ebuild?</title> 182<section>
183<title>List of all packages depending on ...</title>
182<body> 184<body>
183 185
184<p>
185We can also find out which ebuild is being used for a specific package using
186<c>equery</c>. This is done my using the <c>equery which</c> command which
187displays the full path to the ebuild.
188</p> 186<p>
187<c>equery</c> is able to list all direct dependencies matching a package.
188The function we should use to do this is <c>depends</c> and it's as easy as:
189</p>
189 190
190<pre caption="Displaying the ebuild path"> 191<pre caption="Looking for packages depending on pygtk">
191# <i>equery which cdrtools</i> 192# <i>equery depends pygtk</i>
192/usr/portage/app-cdr/cdrtools/cdrtools-2.01_alpha37.ebuild 193[ Searching for packages depending on pygtk... ]
194app-office/dia-0.93
195dev-python/gnome-python-2.0.0-r1
196gnome-extra/gdesklets-core-0.26.2
197media-gfx/gimp-2.0.4
198x11-libs/vte-0.11.11-r1
193</pre> 199</pre>
194 200
195</body> 201</body>
196</section> 202</section>
197<section> 203<section>
198<title>Dependency Graphs</title> 204<title>Dependency Graphs</title>
199<body> 205<body>
200 206
201<p> 207<p>
202<c>equery</c> is capable of giving us a dependency graph for a specified package. 208<c>equery</c> is capable of giving us a dependency graph for a specified
203The dependency graph gives a listing of all the packages that have direct and 209package. The dependency graph gives a listing of all the packages that have
204indirect dependencies on the package in question. 210direct and indirect dependencies on the package in question.
205</p> 211</p>
206 212
207<pre caption="Dependency Graph for cdrtools"> 213<pre caption="Dependency Graph for cdrtools">
208# <i>equery depgraph cdrtools</i> 214# <i>equery depgraph cdrtools</i>
209Displaying dependencies for app-cdr/cdrtools-2.01_alpha37 215Displaying dependencies for app-cdr/cdrtools-2.01_alpha37
210`-- app-cdr/cdrtools-2.01_alpha37 216`-- app-cdr/cdrtools-2.01_alpha37
211 `-- sys-libs/glibc-2.3.4.20040808 (virtual/libc) 217 `-- sys-libs/glibc-2.3.4.20040808 (virtual/libc)
212 `-- sys-kernel/linux-headers-2.4.22 (virtual/os-headers) 218 `-- sys-kernel/linux-headers-2.4.22 (virtual/os-headers)
213 `-- sys-apps/baselayout-1.10.4 219 `-- sys-apps/baselayout-1.10.4
214 `-- sys-apps/sysvinit-2.85-r1 220 `-- sys-apps/sysvinit-2.85-r1
215 `-- sys-apps/gawk-3.1.3-r1 221 `-- sys-apps/gawk-3.1.3-r1
216 `-- sys-apps/util-linux-2.12-r4 222 `-- sys-apps/util-linux-2.12-r4
217 `-- sys-apps/sed-4.0.9 223 `-- sys-apps/sed-4.0.9
218 `-- sys-libs/ncurses-5.4-r4 224 `-- sys-libs/ncurses-5.4-r4
219 `-- sys-apps/pam-login-3.14 225 `-- sys-apps/pam-login-3.14
220 `-- sys-libs/pam-0.77-r1 226 `-- sys-libs/pam-0.77-r1
221 `-- sys-libs/cracklib-2.7-r10 227 `-- sys-libs/cracklib-2.7-r10
222 `-- sys-apps/miscfiles-1.3-r1 228 `-- sys-apps/miscfiles-1.3-r1
223 `-- app-arch/gzip-1.3.5-r1 229 `-- app-arch/gzip-1.3.5-r1
224 `-- sys-apps/portage-2.0.50-r10 230 `-- sys-apps/portage-2.0.50-r10
225</pre> 231</pre>
226 232
227<p> 233<p>
228For example, while glibc may be a direct dependency for cdrtools, the linux-headers 234For example, while glibc is a direct dependency for cdrtools,linux-headers
229are an indirect dependency for cdrtools. 235are an indirect dependency. Note that the output also includes information
236about virtual packages. In the example above, <c>cdrtools</c> is actually
237written to require virtual/libc, not sys-libs/glibc, but on the given
238system in the example sys-libs/glibc provides virtual/libc.
239</p>
240
241</body>
242</section>
243<section>
244<title>Listing Files Belonging to an Ebuild</title>
245<body>
246
230</p> 247<p>
248<c>equery</c> can list the files that belong to an installed ebuild. If I
249don't know the files that Gentoolkit has installed on the system, I will
250use <c>equery</c> to show them.
251</p>
252
253<pre caption="Listing files">
254#<i> equery files gentoolkit</i>
255[ Searching for packages matching gentoolkit... ]
256app-portage/gentoolkit-0.2.0
257* Contents of app-portage/gentoolkit-0.2.0:
258/usr
259/usr/bin
260/usr/bin/equery
261/usr/bin/etcat
262/usr/bin/euse
263/usr/bin/glsa-check
264/usr/bin/qpkg
265/usr/bin/revdep-rebuild
266/usr/lib
267/usr/lib/gentoolkit
268/usr/lib/gentoolkit/pym
269/usr/lib/gentoolkit/pym/gentoolkit
270/usr/lib/gentoolkit/pym/gentoolkit/__init__.py
271/usr/lib/gentoolkit/pym/gentoolkit/gentoolkit.py
272/usr/lib/gentoolkit/pym/gentoolkit/pprinter.py
273/usr/lib/gentoolkit/pym/glsa.py
274/usr/sbin
275/usr/share
276/usr/share/doc
277/usr/share/doc/gentoolkit-0.2.0_pre10
278
279[...]
280</pre>
281
282<p>
283The command <c>files</c> of <c>equery</c> provide some options to modify
284the output. You can look them all up in the <c>equery</c> man page.
285</p>
286
287</body>
288</section>
289<section>
290<title>Looking for packages that use a specific USE flag</title>
291<body>
292
293<p>
294If you want to find which packages on your system that make use of a specific
295USE flag, <c>equery</c> has the function <c>hasuse</c>:
296</p>
297
298<pre caption="Searching packages which use mozilla USE flag">
299# <i>equery hasuse mozilla</i>
300[ Searching for USE flag mozilla in all categories among: ]
301 * installed packages
302[I--] [ ] dev-java/blackdown-jre-1.4.2.01 (1.4.2)
303[I--] [ ] mail-client/evolution-2.0.2 (2.0)
304</pre>
305
306</body>
307</section>
308<section>
309<title>Listing Packages</title>
310<body>
311
312<p>
313<c>equery</c> has a power feature to list packages belonging to our system,
314portage or even an overlay. Let's try this:
315</p>
316
317<pre caption="Listing packages with equery">
318# <i>equery list gentoolkit</i>
319[ Searching for package 'gentoolkit' in all categories among: ]
320 * installed packages
321[I--] [ ] app-portage/gentoolkit-0.2.0 (0)
322</pre>
323
324<p>
325The standard query will search our installed packages for the name given.
326If found, the following info will be displayed: the package location between
327the first square brackets (I for Installed packages, P for Portage, O for
328Overlay), the possibles masks between the second (~ by keyword, - by arch or
329M hard masked), then the category and complete name and last of all, the slot
330in which the package is stored.
331</p>
332
333<p>
334Another example, this time we are going to use the local options in order
335to look for packages in our portage tree and overlay.
336</p>
337
338<pre caption="Using local options with equery">
339# <i>equery list -p -o vim</i>
340[ Searching for package 'vim' in all categories among: ]
341 * installed packages
342[I--] [ ] app-editors/vim-6.3-r4 (0)
343 * Portage tree (/usr/portage)
344[-P-] [M~] app-editors/vim-7.0_alpha20050126 (0)
345[-P-] [M~] app-editors/vim-7.0_alpha20050201 (0)
346[-P-] [ ] app-editors/vim-6.3-r2 (0)
347[-P-] [M~] app-editors/vim-7.0_alpha20050122 (0)
348[-P-] [M~] app-editors/vim-core-7.0_alpha20050126 (0)
349[-P-] [ ] app-editors/vim-core-6.3-r3 (0)
350[-P-] [M~] app-editors/vim-core-7.0_alpha20050122 (0)
351[-P-] [M~] app-editors/vim-core-7.0_alpha20050201 (0)
352[-P-] [ ] app-editors/vim-core-6.3-r4 (0)
353 * overlay tree (/opt/ebuilds)
354</pre>
355
356</body>
357</section>
358<section>
359<title>Finding Package Sizes</title>
360<body>
361
362<p>
363Ever been curious to find out how much space a specific package is occupying?
364Since a package could have its files over a number of directories, the usual
365<c>du -hc</c> might not give you the correct figure. Not to worry, here comes
366<c>equery</c> to the rescue!
367</p>
368
369<pre caption="Package Size">
370# <i>equery size openoffice-bin</i>
371* app-office/openoffice-bin-1.1.2
372 Total Files : 2908
373 Total Size : 223353.31 KiB
374</pre>
375
376<p>
377As you can see, <c>equery</c> prints the total space used in kilobytes and
378also lists the total number of files the package has.
379</p>
380
381</body>
382</section>
383<section>
384<title>Package-wise list of USE Flags</title>
385<body>
386
387<p>
388<c>equery</c> can be used to give us information about what USE flags
389are being used by a specific package. It also tells us what our current USE
390flags are for a package and also what USE flags are available for the package.
391</p>
392
393<pre caption="Set and Unset USE Flags">
394# <i>equery uses ethereal</i>
395[ Colour Code : set unset ]
396[ Legend : (U) Col 1 - Current USE flags ]
397[ : (I) Col 2 - Installed With USE flags ]
398
399 U I [ Found these USE variables in : net-analyzer/ethereal-0.10.6 ]
400 - - adns : Adds support for the adns DNS client library
401 + + gtk : Adds support for x11-libs/gtk+ (The GIMP Toolkit)
402 - - ipv6 : Adds support for IP version 6
403 - - snmp : Adds support for the Simple Network Management Protocol if available
404 + + ssl : Adds support for Secure Socket Layer connections
405 + + gtk2 : Use gtk+-2.0.0 over gtk+-1.2 in cases where a program supports both.
406 - - debug : Tells configure and the makefiles to build for debugging. Effects vary across packages,
407 but generally it will at least add -g to CFLAGS. Remember to set FEATURES=nostrip too
408</pre>
409
410<p>
411I have installed ethereal with only the gtk, ssl and gtk2 flags set, but the
412other USE flags for ethereal are adns, ipv6, snmp and debug. For more
413information on USE flags, please refer to the <uri
414link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>
415chapter of the <uri link="/doc/en/handbook/">Gentoo Handbook</uri>.
416</p>
417
418</body>
419</section>
420<section>
421<title>Where's the ebuild?</title>
422<body>
423
424<p>
425We can also find out which ebuild is being used for a specific package using
426<c>equery</c>. This is done my using the <c>equery which</c> command which
427displays the full path to the ebuild.
428</p>
429
430<pre caption="Displaying the ebuild path">
431# <i>equery which cdrtools</i>
432/usr/portage/app-cdr/cdrtools/cdrtools-2.01_alpha37.ebuild
433</pre>
231 434
232</body> 435</body>
233</section> 436</section>
234</chapter> 437</chapter>
235 438
236<chapter> 439<chapter>
237<title>euse</title> 440<title>euse</title>
238<section> 441<section>
239<title>Introduction</title> 442<title>Introduction</title>
240<body> 443<body>
241 444
242<warn> 445<warn>
243<c>euse</c> is currently broken as it does not support cascading profiles well. 446<c>euse</c> is currently broken as it does not support cascading profiles well.
244</warn> 447</warn>
245 448

Legend:
Removed from v.1.19  
changed lines
  Added in v.1.20

  ViewVC Help
Powered by ViewVC 1.1.20