diff options
Diffstat (limited to 'xml/htdocs/doc/en/gentoolkit.xml')
| -rw-r--r-- | xml/htdocs/doc/en/gentoolkit.xml | 569 |
1 files changed, 0 insertions, 569 deletions
diff --git a/xml/htdocs/doc/en/gentoolkit.xml b/xml/htdocs/doc/en/gentoolkit.xml deleted file mode 100644 index efbfb5cba6..0000000000 --- a/xml/htdocs/doc/en/gentoolkit.xml +++ /dev/null @@ -1,569 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.7 2003/12/01 12:06:21 erwin Exp $ --> -<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> - -<guide link = "/doc/en/gentoolkit.xml"> -<title>Gentoolkit</title> -<author title="Author"><mail link="mbutcher@aleph-null.tv"> -Matt Butcher</mail> -</author> - -<author title="Editor"><!-- zhen@gentoo.org --> - John P. Davis -</author> -<author title="Editor"> - <mail link="erwin@gentoo.org">Erwin</mail> -</author> -<!-- Licensed under GFDL --> - -<abstract> - Gentoolkit is a suite of tools to ease the administration of a Gentoo system. - This document covers the basics of - some of the tools present in Gentoolkit. -</abstract> - -<version>1.2</version> -<date>December 1, 2003</date> - -<chapter> - <title>Introduction</title> - <section> - <title>What is Gentoolkit?</title> - <body> - <p>Gentoo is a unique distribution, and presents some complexities that - simply don't exist for other distributions. As Gentoo developers - and contributors discovered some of these complexities, they also - wrote tools to help users and administrators work around them. - Many of these tools have been contributed to the Gentoo project, - and are included in the package <path>app-portage/gentoolkit</path>. - </p> - - <p>Gentoolkit contains a whole bunch of useful tools to help manage - Portage and the ebuild architecture. Most users -- particularly - those who update systems often -- will benefit from having - gentoolkit installed.</p> - </body> - </section> - <section> - <title>Installation</title> - <body> - <p>Just as with any Gentoo package, installation is just a simple - emerge. - </p> - - <pre> -<i>emerge gentoolkit </i> - </pre> - <note>Many of the tools in gentoolkit reveal important information - about your system or require root permissions. For that reason, - some of the programs may only be executed (or only function - properly) if run by a user with root permissions.</note> - </body> - </section> - <section> - <title>Finding Documentation</title> - <body> - - <p> - At the time of this writing, not all of the programs in gentoolkit - are well documented. Some have man pages, but not all. Any documentation - that a program might have (other than man pages) is stored in - <path>/usr/doc/gentoolkit-[version]/[program-name]/</path>. - </p> - </body> - </section> -</chapter> -<chapter> - <title>Querying Package Data with qpkg</title> - <section> - - <title>Introduction</title> - <body> - <p><c>qpkg</c> is flexible tool for determining information about ebuilds, - whether installed or not. It can provide information about what files belong - to which ebuilds, whether multiple versions of the same package are installed, - and what a particular ebuild does. - </p> - <p>Calling <c>qpkg</c> with no arguments prints a list of all ebuilds, with asterisks - (*) next to the packages that are installed on the system. - </p> - <note>By default, <c>qpkg</c> prints output in color. To turn this off on the command - line, use the <c>--no-color</c> or <c>-nc</c> flag.</note> - - </body> - </section> - <section> - <title>Querying Package Information</title> - <body> - <p>One of the most common uses for <c>qpkg</c> is determining what a given package - is. For instance, while looking through <path>net-misc</path>, I saw a package - called <path>neon</path>. Having no idea what it was, I ran qpkg. - </p> - - <pre> -hebron root # <i>qpkg -i net-misc/neon -net-misc/neon-0.15.3-r1 - HTTP and WebDAV client library [ http://www.webdav.org/neon ] -net-misc/neon-0.18.5 - HTTP and WebDAV client library [ http://www.webdav.org/neon ] -net-misc/neon-0.19.2 - HTTP and WebDAV client library [ http://www.webdav.org/neon ] -net-misc/neon-0.19.2-r1 - HTTP and WebDAV client library [ http://www.webdav.org/neon ] -net-misc/neon-0.21.1 - HTTP and WebDAV client library [ http://www.webdav.org/neon ] </i> - </pre> - <p> - <c>qpkg</c> read through the ebuild files for the five <path>net-misc/neon</path> - ebuilds and printed out the information stored in DESCRIPTION and HOMEPAGE. - </p> - </body> - - </section> - <section> - <title>Listing Files Belonging to an Ebuild</title> - <body> - <p> - <c>qpkg</c> can also list the files that belong to an installed ebuild. I - Know that gentoolkit installed several tools, but I don't know what they - all are. To find out, I can do a <c>qpkg -l</c> - - </p> - <pre> -hebron portage # <i>qpkg -l app-portage/gentoolkit -app-portage/gentoolkit-0.1.14-r1 * -CONTENTS: -/usr -/usr/share -/usr/share/gentoolkit -/usr/share/gentoolkit/histogram.awk -/usr/share/doc -/usr/share/doc/gentoolkit-0.1.14-r1 -/usr/share/doc/gentoolkit-0.1.14-r1/gentool -/usr/share/doc/gentoolkit-0.1.14-r1/gentool/ChangeLog.gz -/usr/share/doc/gentoolkit-0.1.14-r1/lintool -/usr/share/doc/gentoolkit-0.1.14-r1/lintool/checklist-for-ebuilds.gz -/usr/share/doc/gentoolkit-0.1.14-r1/lintool/ChangeLog.gz -/usr/share/doc/gentoolkit-0.1.14-r1/etc-update -/usr/share/doc/gentoolkit-0.1.14-r1/etc-update/ChangeLog.gz -/usr/share/man -/usr/share/man/man1 -/usr/share/man/man1/qpkg.1.gz -/usr/share/man/man1/lintool.1.gz -/usr/share/man/man1/etc-update.1.gz -/usr/bin -/usr/bin/gentool-bump-revision -/usr/bin/gentool-total-coverage -/usr/bin/gentool-author-coverage -/usr/bin/gentool-package-count -/usr/bin/qpkg -/usr/bin/pkg-size -/usr/bin/lintool -/usr/sbin -/usr/sbin/pkg-clean -/usr/sbin/mkebuild -/usr/sbin/emerge-webrsync -/usr/sbin/epm -/usr/sbin/etc-update -/etc -/etc/etc-update.conf </i> - </pre> - </body> - </section> - <section> - <title>Finding the Package from Where a File Came</title> - <body> - - <p> - To find the package that a file came from, use the <c>-f</c> - or <c>--find-file</c> flag. - </p> - <pre> - hebron portage # <i>qpkg -f net-www/mozilla * </i> - </pre> - - </body> - </section> - <section> - <title>Listing Duplicate Packages</title> - <body> - <p> - Sometimes multiple versions of the same package may exist. <c>qpkg --dup</c> - - will print a list of duplicate packages. The existence of a duplicate package - though may not indicate that the older version may be removed. They may fill - different slots. To look for duplicates in the same slot, use - <c>qpkg --dups --slot</c>. I just updated KDE from 3.0 to 3.0.2, so I have some - duplicates in the same slot. - </p> - <pre> -hebron portage # <i>qpkg --dups --slot -app-portage/gentoolkit -kde-base/kdeaddons -kde-base/kdeadmin -kde-base/kdeartwork -kde-base/kdebase -kde-base/kdegames -kde-base/kdelibs -kde-base/kdemultimedia -kde-base/kdenetwork -kde-base/kdetoys -kde-base/kdeutils -media-libs/freetype -x11-libs/qt </i> - </pre> - </body> - </section> - <section> - <title>Verifying Package Integrity</title> - - <body> - <p> - Sometimes it is useful to check a package's integrity to know that files - have not been replaced since they were installed. <c>qpkg</c> can - verify md5 sums as well as install times to indicate whether or not files - for the package might have been corrupted, replaced, or removed. - </p> - <p>To check both mtimes and md5 sums, use the <c>-c</c> flag.</p> - <pre> - -hebron portage # <i>qpkg gnupg -c -v -app-crypt/gnupg-1.0.6 * -/usr/lib/gnupg/rndunix !md5! !mtime! -/usr/lib/gnupg/rndegd !md5! !mtime! -/usr/lib/gnupg/tiger !md5! !mtime! -/usr/bin/gpg !md5! !mtime! -/usr/bin/gpgv !md5! !mtime! -/usr/share/gnupg/options.skel !md5! !mtime! -/usr/share/gnupg/FAQ !md5! !mtime! -/usr/share/gnupg/faq.html !md5! !mtime! -/usr/share/locale/da/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/de/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/eo/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/et/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/fr/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/id/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/it/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/ja/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/nl/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/pl/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/pt_BR/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/sv/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/locale/tr/LC_MESSAGES/gnupg.mo !md5! !mtime! -/usr/share/info/gpgv.info.gz !md5! !mtime! -/usr/share/man/man1/gpg.1.gz !md5! !mtime! -/usr/share/man/man1/gpgv.1.gz !md5! !mtime! -24/92 - -app-crypt/gnupg-1.0.7 * -0/101 </i> - </pre> - <p> - As you can see, I have more than one version of GnuPG installed. <c>qpkg</c> - reports that many of the files from the older version have been changed since I - installed it. Those packages were most likely modified when I updated - from <path>gnupg-1.0.6</path> to <path>gnupg-1.0.7</path>. Note that the last two -lines indicate - that 0 of 101 files from <path>gnupg-1.0.7</path> have been changed since I -installed. That - is good. If any of them had been changed, I would be worried. - </p> - - </body> - </section> - <section> - <title>But Wait... There's More</title> - <body> - <p> - <c>qpkg</c> can be used for other querying tasks that I will not go over here. There -is a very complete - manpage for <c>qpkg</c>. Consult that for more information. - </p> - - </body> - </section> -</chapter> -<chapter> - <title>lintool</title> - <section> - <title>Introduction</title> - <body> - <p> - - <c>lintool</c> is a program that checks ebuild scripts for conformance to - standards and requirements. It is important for ebuild developers to use <c>lintool</c> - to ensure that they are doing things correctly and not requiring the core team - to do more than they already have to in order to include the ebuild in the Gentoo - repository. - </p> - </body> - </section> - <section> - <title>Use</title> - - <body> - <p> - Running <c>lintool</c> will produce a nicely formatted list of checks and results that - it performs. - </p> - <pre> -hebron portage # <i>lintool app-crypt/gnupg/gnupg-1.0.7.ebuild -app-crypt/gnupg/gnupg-1.0.7.ebuild : Not OK - -------------------------------------------------------------------------------- - Summary for all 1 ebuild(s) checked # errors/warns - ------------------------------------------------------------------------------- - Testing for illegal space characters, weird backslash formatting : 0 / 0 - Testing for malformed headers : 0 / 1 - Testing for occurence of deprecated try : 0 / 0 - Testing for superfluous A=${P}.tar.gz : 0 / 0 - Testing for empty DEPEND : 0 / 0 - Testing for empty HOMEPAGE : 0 / 0 - Testing for empty DESCRIPTION : 0 / 0 - Testing for presence of env vars : 1 / 1 - Testing for sane USE flag usage : 0 / 0 - - Total number of ebuilds with errors : 1 (100%) - Total number of ebuilds with warnings : 1 (100%) - </i> </pre> - <p> - The first line summarizes whether the ebuild is okay or not. In the case of - <c>gnupg-1.0.7.ebuild</c>, it's not. Reading through the list of checks, we can see - that it got a warning for malformed headers and an error for presence of env - vars. - </p> - - <p> - Looking at the ebuild, I see that it is missing a couple of required - env vars (LICENSE and RDEPEND). Adding those fixes the error. But there are - still two warnings -- one for malformed headers and one for env vars. To help - me find those, I can run <c>lintool</c> again with <c>--show-details</c> - </p> - <pre> -hebron gnupg # <i>lintool --show-details ./gnupg-1.0.7.ebuild - -------------------------------------------------------------------------------- -# Some data cut for brevity.... - - Status for ./gnupg-1.0.7.ebuild -* Testing for malformed headers : passed -- (W) Has illegal or suspect headers: - |Suspect copyright year: # Copyright 1999-2000 Gentoo Technologies, Inc. - * Testing for occurence of deprecated try : passed - * Testing for superfluous A=${P}.tar.gz : passed - * Testing for empty DEPEND : passed - * Testing for empty HOMEPAGE : passed - * Testing for empty DESCRIPTION : passed - * Testing for presence of env vars : passed - - (W) Missing SLOT= - * Testing for sane USE flag usage : passed - - ------------------------------------------------------------------------------- - Summary for all 1 ebuild(s) checked # errors/warns - ------------------------------------------------------------------------------- - Testing for illegal space characters, weird backslash formatting : 0 / 0 - Testing for malformed headers : 0 / 1 - Testing for occurence of deprecated try : 0 / 0 - Testing for superfluous A=${P}.tar.gz : 0 / 0 - Testing for empty DEPEND : 0 / 0 - Testing for empty HOMEPAGE : 0 / 0 - Testing for empty DESCRIPTION : 0 / 0 - Testing for presence of env vars : 0 / 1 - Testing for sane USE flag usage : 0 / 0 - - Total number of ebuilds with errors : 0 (0%) - Total number of ebuilds with warnings : 1 (100%) - </i> </pre> - <p>Now I can see that the year in the ebuild is probably wrong, and that it is - missing the SLOT variable. Fixing those eliminates all warnings.</p> - - </body> - </section> -</chapter> -<chapter> - - <title>epm</title> - <section> - <title>Introduction</title> - <body> - <p> - <c>epm</c> is a package managing tool that clones Red Hat rpm commands. As it stands - now, it does not offer all of the features of rpm, but it offers some of the more - powerful rpm query options. - </p> - - <p> - It also handles removing packages, which is not covered here. Use <c>epm --help</c> - to learn more about deleting packages with <c>epm</c>. - </p> - </body> - </section> - <section> - - <title>Querying Packages with epm</title> - <body> - <p> - <c>epm</c> functions with essentially the same command line functions as Red Hat's - rpm. <c>epm -qa</c> lists all packages installed. <c>epm -ql</c> lists all the - files from a specific ebuild. - </p> - - <pre> -hebron etc # <i>epm -ql ethereal -/usr/lib/ethereal/plugins/0.8.20/gryphon.so -/usr/lib/ethereal/plugins/0.8.20/gryphon.la -/usr/lib/ethereal/plugins/0.8.20/gryphon.a -/usr/lib/ethereal/plugins/0.8.20/mgcp.so -/usr/lib/ethereal/plugins/0.8.20/mgcp.la -/usr/lib/ethereal/plugins/0.8.20/mgcp.a -/usr/lib/ethereal/plugins/0.8.20/cosnaming.so -/usr/lib/ethereal/plugins/0.8.20/cosnaming.la -/usr/lib/ethereal/plugins/0.8.20/cosnaming.a -/usr/lib/ethereal/plugins/0.8.20/coseventcomm.so -/usr/lib/ethereal/plugins/0.8.20/coseventcomm.la -/usr/lib/ethereal/plugins/0.8.20/coseventcomm.a -/usr/bin/ethereal -/usr/bin/editcap -/usr/bin/mergecap -/usr/bin/tethereal -/usr/bin/text2pcap -/usr/bin/idl2eth -/usr/share/man/man1/idl2eth.1.gz -/usr/share/man/man1/tethereal.1.gz -/usr/share/man/man1/text2pcap.1.gz -/usr/share/man/man1/editcap.1.gz -/usr/share/man/man1/ethereal.1.gz -/usr/share/man/man1/mergecap.1.gz -/usr/share/doc/ethereal-0.8.20/AUTHORS.gz -/usr/share/doc/ethereal-0.8.20/COPYING.gz -/usr/share/doc/ethereal-0.8.20/NEWS.gz -/usr/share/doc/ethereal-0.8.20/ChangeLog.gz -/usr/share/doc/ethereal-0.8.20/README.gz -/usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz -/usr/share/doc/ethereal-0.8.20/TODO.gz -/usr/share/doc/ethereal-0.8.20/README.aix.gz -/usr/share/doc/ethereal-0.8.20/README.bsd.gz -/usr/share/doc/ethereal-0.8.20/README.hpux.gz -/usr/share/doc/ethereal-0.8.20/README.irix.gz -/usr/share/doc/ethereal-0.8.20/README.linux.gz -/usr/share/doc/ethereal-0.8.20/README.tru64.gz -/usr/share/doc/ethereal-0.8.20/README.win32.gz -/usr/share/doc/ethereal-0.8.20/README.vmware.gz -/etc/ethereal/manuf </i> - </pre> - <p> - <c>epm</c> offers a few advanced query options that are not present in <c>qpkg</c> -at the - time of this writing. For instance, it can query for just configuration files or -just documentation - files. - </p> - <pre> - -hebron etc # <i>epm -qc ethereal -/etc/ethereal/manuf - -hebron etc # epm -qd ethereal -/usr/share/man/man1/idl2eth.1.gz -/usr/share/man/man1/tethereal.1.gz -/usr/share/man/man1/text2pcap.1.gz -/usr/share/man/man1/editcap.1.gz -/usr/share/man/man1/ethereal.1.gz -/usr/share/man/man1/mergecap.1.gz -/usr/share/doc/ethereal-0.8.20/AUTHORS.gz -/usr/share/doc/ethereal-0.8.20/COPYING.gz -/usr/share/doc/ethereal-0.8.20/NEWS.gz -/usr/share/doc/ethereal-0.8.20/ChangeLog.gz -/usr/share/doc/ethereal-0.8.20/README.gz -/usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz -/usr/share/doc/ethereal-0.8.20/TODO.gz -/usr/share/doc/ethereal-0.8.20/README.aix.gz -/usr/share/doc/ethereal-0.8.20/README.bsd.gz -/usr/share/doc/ethereal-0.8.20/README.hpux.gz -/usr/share/doc/ethereal-0.8.20/README.irix.gz -/usr/share/doc/ethereal-0.8.20/README.linux.gz -/usr/share/doc/ethereal-0.8.20/README.tru64.gz -/usr/share/doc/ethereal-0.8.20/README.win32.gz -/usr/share/doc/ethereal-0.8.20/README.vmware.gz - </i> </pre> - <note> - <c>emp --help</c> lists the options that epm <e>will eventually</e> support. Note, -however, that - options prefixed with asterisks (*) are not yet implemented. - </note> - </body> - </section> -</chapter> - -<chapter> - <title>Others</title> - <section> - <title>etc-update</title> - <body> - <!-- - - Feel free to add more to this. It probably deserves its own chapter, but I don't - - use it, so I can't really write much about it. - --> - <p> - <c>etc-update</c> provides a convenient alternative to updating configuration - files by hand. After running an emerge that changes configuration files, you - can run etc-update to step you through the process of updating all impacted - configuration files. - </p> - - <p> - It is driven by a menu-based interface and includes the ability to view and merge - in config files before deciding what to do. - </p> - </body> - </section> - <section> - <title>gentool</title> - <body> - <p>gentool is a collective name for several small scripts that analyze ebuild -statistics. - For instance, gentool-total-coverage prints a list of email addresses and the - number of ebuilds each has in the portage tree. - </p> - - </body> - </section> - <section> - <title>pkg-size</title> - <body> - <p><c>pkg-size</c> prints the size of the installed files in a given package. - </p> - <pre> - -hebron portage # <i>pkg-size nmap -net-analyzer/nmap-2.54_beta24-r1 897024 (876KB) </i> - </pre> - </body> - </section> - <section> - <title>mkebuild</title> - <body> - <p><c>mkebuild</c> simplifies the process of creating a new ebuild by automating as -much - of the process as possible. Running <c>mkebuild [filename]</c> will create an - ebuild for that file. the file should be an archive of some kind. As it works, it - will provide - feedback about changes you may need to make. - </p> - - </body> - </section> - <section> - <title>emerge-webrsync</title> - <body> - <!-- Can't find any documentation on this anywhere... not even a comment in the -code. --> - <p>Downloads the daily snapshot over HTTP with wget, and (optionally) syncs with -portage. - </p> - </body> - - </section> -</chapter> -</guide> - |