diff options
Diffstat (limited to 'app-doc/gentoo-web/files/xml/gentoo-howto.xml')
| -rwxr-xr-x | app-doc/gentoo-web/files/xml/gentoo-howto.xml | 636 |
1 files changed, 0 insertions, 636 deletions
diff --git a/app-doc/gentoo-web/files/xml/gentoo-howto.xml b/app-doc/gentoo-web/files/xml/gentoo-howto.xml deleted file mode 100755 index 861212ed7140..000000000000 --- a/app-doc/gentoo-web/files/xml/gentoo-howto.xml +++ /dev/null @@ -1,636 +0,0 @@ -<?xml version='1.0'?> -<!-- gentoo-howto.xml,v 1.20 2001/08/17 21:52:07 drobbins Exp --> - -<guide link="/doc/gentoo-howto.html"> -<title>Gentoo Linux Developers HOWTO</title> -<author title="Author"><mail link="woodchip@gentoo.org">Donny Davies</mail></author> -<author title="Author"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author> -<author title="Author"><mail link="pete@gentoo.org">Peter Gavin</mail></author> -<abstract>This document describes the Gentoo Linux Portage system, how -to create new packages for Gentoo, and is also meant to be somewhat of -a standard for the Gentoo Developers. It is a work in progress, and is -constantly being updated and changed. It is by no means -complete.</abstract> -<version>1.1</version> -<date>21 Sep 2001</date> - -<!-- - -Contents - -I. Introduction -II. The Portage Tree - A. What (Not) to Put in the Portage Tree - B. Categories - C. The files Directory -III. .ebuild Files - A. Naming .ebuild Files - B. Contents of an .ebuild File - C. Rules for Writing an .ebuild File -IV. Filesystem Locations - A. Introduction to the FHS - B. How to Fit Your Packages into the Filesystem -V. The Portage Scripts and Utilities - A. Public Scripts - B. Private Scripts -VI. Package Dependencies - ---> - - -<chapter> -<title>The Portage tree</title> - -<section> -<title>Introduction</title> -<body><p>The Portage tree is typically found at <path>/usr/portage</path> -and is organized in a heirarchical structure consisting of category directories, -followed by specific package directories. Here's an example; you can find -the <path>util-linux-2.11g.ebuild</path> file in the <path>/usr/portage/sys-apps/util-linux</path> -directory. There may be several other versions of <c>util-linux</c> ebuilds alongside -<path>util-linux-2.11g.ebuild</path>. This is because <e>all ebuilds for a particular -package (irregardless of version)</e>, share the same <path>mycat/mypkg</path> directory in -<path>/usr/portage</path>. -</p></body> -</section> - -<section> -<title> What (not) to put in the Portage tree</title> - -<body><p>In general, the Portage tree should only be used for storing -<path>.ebuild</path> files, as well as any relatively small companion files, -such as patches or sample configuration files. These types of files should be -placed in the <path>/usr/portage/mycat/mypkg/files</path> directory to keep the -main <path>mycat/mypkg</path> directory uncluttered. Also, in general, it's -not a good idea for developers to add binary (non-ASCII) files to CVS. -However, if this is necessary (for example, if you need to add a small PNG -graphic for whatever reason, be sure to add it to CVS by using the <c>-kb</c> -option, like so: </p> - -<pre> -# <i>cvs add -kb myphoto.png</i> -</pre> - -<p>The <c>-kb</c> option tells CVS that <path>myphoto.png</path> is a binary -file and should be treated specially. For example, merging the differences -between two different versions of this file should not be allowed to happen, -for obvious reasons. Also, speaking of merging changes, any patches you add to -Portage should generally <e>not</e> be compressed. This will allow CVS to -merge changes and inform developers of conflicts correctly. </p> - -</body> -</section> -<!-- -<section> -<title>Categories</title> -<body><p>The categories are defined as follows:</p> -<table><tr><th>Category</th><th>Description</th></tr> -<tr><ti><path>app-admin</path></ti><ti>non-critical system administration utilities</ti></tr> -<tr><ti><path>app-arch</path></ti><ti>non-critical archival/compression utilities </ti></tr> -<tr><ti><path>app-cdr</path></ti><ti> CD recording utilities </ti></tr> -<tr><ti><path>app-crypt</path></ti><ti> Cryptography related apps </ti></tr> -<tr><ti><path>app-doc</path></ti><ti>application documentation </ti></tr> -<tr><ti><path>app-editors</path></ti><ti>non-critical text editors </ti></tr> -<tr><ti><path>app-emulation</path></ti><ti>packages for emulating other systems/OSes </ti></tr> -<tr><ti><path>app-games</path></ti><ti>Games!!! 'Nough said </ti></tr> -<tr><ti><path>app-misc</path></ti><ti>applications that don't fit anywhere else </ti></tr> -<tr><ti><path>app-office</path></ti><ti>office-type (word processing, spreadsheet, etc.) packages </ti></tr> -<tr><ti><path>app-shells</path></ti><ti>non-critical shells and command interpreters </ti></tr> -<tr><ti><path>app-text</path></ti><ti>text processing, spell checkers, and document formatting packages </ti></tr> -<tr><ti><path>dev-db</path></ti><ti>database libraries </ti></tr> -<tr><ti><path>dev-java</path></ti><ti>java classes/packages/etc. </ti></tr> -<tr><ti><path>dev-lang</path></ti><ti>compilers and interpreters for different languages </ti></tr> -<tr><ti><path>dev-libs</path></ti><ti>miscellaneous developer's libraries </ti></tr> -<tr><ti><path>dev-perl</path></ti><ti>perl modules </ti></tr> -<tr><ti><path>dev-python</path></ti><ti>python modules </ti></tr> -<tr><ti><path>dev-ruby</path></ti><ti>ruby modules </ti></tr> -<tr><ti><path>dev-tcltk</path></ti><ti>Tcl-Tk modules </ti></tr> -<tr><ti><path>dev-util</path></ti><ti>various developers utilities </ti></tr> -<tr><ti><path>gnome-apps</path></ti><ti>applications for GNOME </ti></tr> -<tr><ti><path>gnome-base</path></ti><ti>base GNOME packages </ti></tr> -<tr><ti><path>gnome-libs</path></ti><ti>non-essential GNOME libraries </ti></tr> -<tr><ti><path>gnome-office</path></ti><ti>office packages for gnome </ti></tr> -<tr><ti><path>kde-base</path></ti><ti>main KDE distribution </ti></tr> -<tr><ti><path>kde-i18n</path></ti><ti>KDE internationalization packages </ti></tr> -<tr><ti><path>media-gfx</path></ti><ti>graphics-related programs </ti></tr> -<tr><ti><path>media-libs</path></ti><ti> libraries for manipulating different media, including accessing multimedia peripherals of your computer (sound card, video card, etc.) </ti></tr> -<tr><ti><path>media-sound</path></ti><ti>programs related to sound, including cd-audio and sound encoding </ti></tr> -<tr><ti><path>media-video</path></ti><ti>programs related to video, including video codecs and players </ti></tr> -<tr><ti><path>net-analyzer</path></ti><ti>network usage statistics monitors/analyzers </ti></tr> -<tr><ti><path>net-dialup</path></ti><ti>network dialup clients and servers such as pppd </ti></tr> -<tr><ti><path>net-fs</path></ti><ti>network filesystems </ti></tr> -<tr><ti><path>net-ftp</path></ti><ti>ftp servers and clients </ti></tr> -<tr><ti><path>net-im</path></ti><ti>Instant Messaging servers and clients </ti></tr> -<tr><ti><path>net-irc</path></ti><ti>irc servers and clients </ti></tr> -<tr><ti><path>net-libs</path></ti><ti>networking-related libraries </ti></tr> -<tr><ti><path>net-mail</path></ti><ti>MTAs and MUAs </ti></tr> -<tr><ti><path>net-misc</path></ti><ti>miscellaneous servers, clients, firewalls, etc. </ti></tr> -<tr><ti><path>net-nds</path></ti><ti>NIS/NIS+ and other network directory services </ti></tr> -<tr><ti><path>net-news</path></ti><ti>Usenet servers and clients </ti></tr> -<tr><ti><path>net-print</path></ti><ti>print servers and clients </ti></tr> -<tr><ti><path>net-www</path></ti><ti>http/www servers and clients </ti></tr> -<tr><ti><path>sys-apps</path></ti><ti>system-critical applications and utilities </ti></tr> -<tr><ti><path>sys-devel</path></ti><ti>base development packages, such as gcc and make </ti></tr> -<tr><ti><path>sys-kernel</path></ti><ti>Linux kernels and kernel source packages </ti></tr> -<tr><ti><path>sys-libs</path></ti><ti>system-critical libraries such as glibc </ti></tr> -<tr><ti><path>x11-base</path></ti><ti>base X packages, such as XFree86 and drivers for various video cards </ti></tr> -<tr><ti><path>x11-libs</path></ti><ti>widget sets and other X-specific libraries</ti></tr> -<tr><ti><path>x11-terms</path></ti><ti>X-based terminal emulators </ti></tr> -<tr><ti><path>x11-wm</path></ti><ti>X window managers </ti></tr> -</table> -<note>If a new category is created (please get permission first!), -then the category needs to be added to -<path>/usr/lib/python2.0/portage.py</path>. -</note> -</body> -</section> ---> -<section> -<title>The files Directory</title> -<body> - -<p>As noted earlier, under each package subdirectory is a <path>files</path> -directory. Any patches, configuration files, or other ancillary files your -package might require should be added to this directory. You may want to -consider naming patches you create yourself just to get your package to build -with a version-specific name, such as <path>mypkg-1.0-gentoo.diff</path>. Also -note that the <path>gentoo</path> extension informs people that this patch was -created by us, the Gentoo Linux developers, rather than having been grabbed -from a mailing list or somewhere else. Again, you should not compress these -diffs because cvs does not play well with binary files. </p> - -<p>Consider adding a suffix such as <path>mypkg-1.0</path> to the tail of every -file you put into the <path>files</path> directory, so that the files used for -each individual version of your ebuild scripts are distinguishable from one -another, and so that the changes between different revisions are visible. This -is generally a really good idea. :) You may want to use a different suffix if -coarser or finer granularity is required.</p> - -<p>If you have many files that should go into the files directory, consider -creating subdirectories such as <path>files/mypkg-1.0</path> and putting the -relevant files in the appropriate subdirectory. If you use this method, you do -not need to add suffix the names of the files in this directory, which is often -more convenient.</p> - -</body> -</section> -</chapter> - -<chapter> -<title>ebuild scripts</title> -<section> -<title>Introduction</title> -<body> - -<p>ebuild scripts are the basis for the entire portage system. They contain all -the information required to download, unpack, compile and install a set of -sources, as well as how to perform any optional pre/post install/removal or -configuration functions. While most of Portage is written in Python, the ebuild -scripts themselves are written in bash, since using bash allows us to call commands -as we would from the command-line. One of the important design principles behind -ebuild scripts is to have the commands therein be analogs of those one would type -on the command-line if installing the package manually. For this purpose, having -bash syntax is a good thing.</p> - -<p> -Ebuild scripts are interpreted by the <c>ebuild</c> and <c>emerge</c> commands. -Think of the <c>ebuild</c> command as a low-level building tool. It can build -and install a single ebuild, but no more. It will check to see if dependencies -are satisfied, but it will not attempt to auto-resolve them. On the other hand -<c>emerge</c> is a high level engine for <c>ebuild</c>, and has the ability to -auto-merge dependencies if needed, perform "pretend" merges so that user can see -what ebuilds <e>would</e> be merged, and more. Generally, <c>emerge</c> blows -<c>ebuild</c> out of the water except in one area. With <c>ebuild</c>, you can -incrementally step through the various parts of a package installation (fetching, -unpacking, compiling, installing and merging) one at a time. For developers, -this is an invaluable debugging tool, because it allows you to isolate ebuild -problems to a specific portion of the build process. -</p> - -</body> -</section> - -<section> -<title>Naming ebuild Files</title> -<body> - -<p>Ebuild file names consist of four logical sections:</p> - -<p>The first section is the package name, which should only contain lowercase -letters, the digits 0-9, and any number of single hyphen ('-') characters. -Some examples are <c>util-linux</c>, <c>sysklogd</c> and <c>glibc</c>. </p> - -<p>The second section is the version of the package, which should normally be -same as the version on the main source tarball. The version is normally made up -of two or three numbers separated by periods, such as <c>1.2</c> or -<c>4.5.2</c> (although very long period-separated number sequences <e>are</e> -supported), and may have a single letter immediately following the last digit, -e.g., <c>1.4b</c> or <c>2.6h</c>. The package version is joined to the package -name with a hyphen; for example: <c>foo-1.0</c>, <c>bar-2.4.6</c>, etc.</p> - -<impo>If you're thinking of using a trailing letter in your version string, -note that the trailing letter should <e>not</e> be used to signify alpha or beta -status for the package, since alphas and betas are <e>prereleases</e> and -letter revisions are <e>newer versions</e>. This is an important distinction -because Portage uses an ebuild's version number to determine if it is newer -or older than other packages with the same category and name. It's very -important that version numbers faithfully represent the version of the -package so that Portage properly performs its dependency checking duties.</impo> - -<p>The third (optional) section contains a special suffix; either -<c>_alpha</c>, <c>_beta</c>, <c>_pre</c> or <c>_rc</c>. Any of these suffixes -may be immediately followed my a number, e.g., <c>linux-2.4.0_pre10</c>; -Assuming identical version parts, an <c>_alpha</c> package is older than -<c>_beta</c>, <c>_beta</c> older than <c>_pre</c>, and <c>_pre</c> older than -<c>_rc</c>. -</p> - -<note>An <c>_rc</c> package is older than a package without an underscore -prefix (i.e. <c>linux-2.4.0</c>), and <c>linux-2.4.0</c> is older than a -package with a single letter prefix, i.e. <c>linux-2.4.0b</c>. As you would -expect, the <c>linux-2.4.0b</c> package is considered older than -<c>linux-2.4.0c</c>. Again this versioning information is important, as -Portage uses it internally to determine whether one package or ebuild is newer -than another with the same category and name.</note> - -<p>The fourth (optional) section of the package name is the Gentoo Linux-specific <e>revision</e> number, -which is specified by <c>-r#</c>, where <c>#</c> is an integer, -e.g. <c>package-4.5.3-r3</c>. This revision number is independent of -the version of the source tarball and is used to inform people that -a new and improved Gentoo Linux rev of a particular package is available. -</p> - -<p> -If you make non-trivial improvements to an existing ebuild file, you should -copy the ebuild file to a new file with the revision number incremented by 1. -Initial releases normally have no revision number, e.g. -<path>package-4.5.3</path> and are considered by Portage to have a a revision -number of zero. This means that counting goes as follows: <c>1.0</c> (initial -version), <c>1.0-r1</c>, <c>1.0-r2</c>, etc. -</p> - -<p>And I suppose that we actually have a <e>fifth</e> section of the ebuild name -- the -<c>.ebuild</c> extension itself. -</p> - -</body> -</section> - -<section> -<title>Contents of an ebuild File</title> -<body><p>1. Variable Settings:</p> -<p>The first part of every ebuild file is made up of a number of -variable settings. The variables you can set are:</p> -<table> -<tr><ti><c>P</c></ti><ti>the name name and version of the package; you should not need to set this, as it is determined from the name of the ebuild file</ti></tr> -<tr><ti><c>A</c></ti><ti>the name (without the path) of the main archive file for your package</ti></tr> -<tr><ti><c>S</c></ti><ti>the source directory for your package; normally ${WORKDIR}/${P}</ti></tr> -<tr><ti><c>DESCRIPTION</c></ti><ti>a short, one line description of your package</ti></tr> -<tr><ti><c>SRC_URI</c></ti><ti>the URIs for every source file in your package, separated by whitespace; normally the first one is something like "ftp://ftp.company.com/pub/somepackage/${A}"</ti></tr> -<tr><ti><c>HOMEPAGE</c></ti><ti>your package's homepage</ti></tr> -<tr><ti><c>DEPEND</c></ti><ti>build dependencies; see the section <uri link="#dependencies">Package Dependencies</uri></ti></tr> -<tr><ti><c>RDEPEND</c></ti><ti>runtime dependencies; see the section <uri link="#dependencies">Package Dependencies</uri></ti></tr> -</table> -<p>2. ebuild Functions</p> -<p>There are a number of different functions that you can define in ebuild files that control the building and installation process of your package.</p> -<table> -<tr><ti><c>src_unpack</c></ti><ti>Use this function to unpack your sources and apply patches, and run autoconf/automake/etc. if necessary. By default, unpacks the packages in <c>${A}</c> and applies <c>${PF}-gentoo.diff</c>. The default starting directory is <c>${WORKDIR}</c>.</ti></tr> -<tr><ti><c>src_compile</c></ti><ti>Use this function to configure and build the package. Default starting directory is <c>${S}</c>.</ti></tr> -<tr><ti><c>src_install</c></ti><ti>Use this function install the package to an image in <c>${D}</c>. If your package uses automake, you can do this simply with <c>make DESTDIR=${D} install</c>. <emph>Make sure your package installs all its files using <c>${D}</c> as the root!</emph></ti></tr> -<tr><ti><c>pkg_preinst</c></ti><ti>The commands in this function are run just prior to merging a package image into the filesystem.</ti></tr> -<tr><ti><c>pkg_postinst</c></ti><ti>The commands in this function are run just following merging a package image into the filesystem.</ti></tr> -<tr><ti><c>pkg_prerm</c></ti><ti>The commands in this function are run just prior to unmerging a package image from the filesystem.</ti></tr> -<tr><ti><c>pkg_postrm</c></ti><ti>The commands in this function are run just following unmerging a package image from the filesystem.</ti></tr> -</table> -</body> -</section> - -<section> -<title>Rules for writing an ebuild File</title> -<body><p>Since ebuild files are really just shell scripts, you should -use your editor's shell-script mode for editing them. You should use -proper indentation, using only tab characters -- no spaces. Make sure -you set up your editor to put tabstops at 4 spaces. Always make sure -you use braces around your environment variables; e.g. <c>${P}</c> -instead of just <c>$P</c>.</p> -<p>If you're using Vim, you can put the following snippet at the bottom of your .vimrc to make sure you're using the right settings when editing anything Gentoo-related.</p> -<pre> -if (getcwd() =~ 'gentoo-x86\|gentoo-src\|portage') - set tabstop=4 shiftwidth=4 noexpandtab -endif -</pre> -<p>TODO: add stuff about emacs.</p></body> -</section> - -<section> -<title><c>USE</c> Variables</title> - -<body> - -<p>The purpose of USE variables is to allow you to configure Portage to globally -and automatically enable or disable certain <e>optional build-time</e> -features. Here's an example. Let's say you're a GNOME fan, and you'd like any -ebuild that has the option of compiling-in optional GNOME support to do -so. In this case, you'd add <c>gnome</c> to the <c>USE</c> variable in -<path>/etc/make.conf</path>, and then Portage will automatically add optional -GNOME functionality to packages if it is available. Likewise, if you don't -want optional GNOME features to be added to your ebuilds if they are available, -simply edit <path>/etc/make.conf</path> and make sure that <c>gnome</c> is -<e>not</e> set in the <c>USE</c> variable. Gentoo Linux has an almost -overwhelming number of USE options, allowing you to have your system configured -exactly the way you want it. - -<note> If you unset a USE variable (for example, removing <c>gnome</c> from -<c>USE</c>), this will only instruct Portage to disable <e>optional</e> -build-time support for GNOME. However, if you <c>emerge</c> an ebuild that -<e>requires</e> GNOME, the package will obviously have GNOME support enabled, as you -would expect. This also means that -GNOME will be automatically installed (as a dependency) if it hasn't been already. That's why -it's always a good idea to do an <c>emerge --pretend</c> before doing the -"real" <c>emerge</c>; that way, you'll always know that you're going to get! -</note> - -In your own ebuilds, you can check whether a USE variable is set by using the -<c>use <variable></c> command. The <c>use</c> command prints out the name -of every variable that is present in both <c>USE</c> and its command line. You -would normally use this command as follows:</p> - -<p><c>if [ "`use X`" ]; then commands; fi</c></p> - - -<p>USE variables can also be used to set dependencies. For example, you may -only want to require a package if a certain USE variable is set. This is done -by using the syntax <c>variable? ( mycat/mypackage-1.0-r1 )</c> in the DEPEND -variable for your ebuild. In this example, <c>mycat/mypackage-1.0-r1</c> will -only be required if <c>variable</c> is present in <c>USE</c></p> - -<p>Here's an important tip about how to use <c>USE</c>. Most of the time, -a package will have a <c>./configure</c> script used to perform configuration -steps. Generally, if your ebuild uses <c>./configure</c>, any optional build-time -functionality will be enabled or disabled by passing the appropriate arguments to -the <c>./configure</c> command. Here's the best way to handle this. First, -find out whether the particular <c>./configure</c> option that you want to add -<c>USE</c> support for is is <e>enabled</e> or <e>disabled</e> by default. If -it's <e>enabled</e> by default, then do things as follows:</p> -<pre> -DEPEND="gnome? ( >=gnome-base/gnome-1.4 )" - -src_compile() { - local myvar - myvar="" - if [ -z "`use gnome`" ] - then - myvar="--disable-gnome" - fi - try ./configure ${myvar} --prefix=/usr --host=${CHOST} - try emake -} -</pre> -<p> -Above, we only check to see if the <c>gnome</c> USE variable is disabled (<c>-z</c> -is <c>bash</c>'s way of saying "if empty string"). There's no need to explicitly -enable GNOME, since for this package, GNOME is enabled by default. However, if a -particular feature is <e>disabled</e> by default, you can use this approach:</p> -<pre> -DEPEND="gnome? ( >=gnome-base/gnome-1.4 )" - -src_compile() { - local myvar - myvar="" - if [ -n "`use gnome`" ] - then - myvar="--enable-gnome" - fi - try ./configure ${myvar} --prefix=/usr --host=${CHOST} - try emake -} -</pre> -<p>This time, we only explicitly enable GNOME if the <c>GNOME</c> USE variable is set. -Note that in bash, <c>[ -n "`use gnome`" ]</c> is equivalent to <c>[ "`use gnome`" ]</c>, -and will be true only if the <c>gnome</c> USE variable is set.</p> - -<p>The following USE variables are currently used in Gentoo Linux:</p> - -<table> -<tr><th>Variable</th><th>Description</th></tr> -<tr><ti>X</ti><ti>enable use of X. Often used to enable "token X app" included in a mostly console-based ebuild.</ti></tr> -<tr><ti>alsa</ti><ti>enable built-in support for the Advanced Linux Sound Architecture.</ti></tr> -<tr><ti>berkdb</ti><ti>enable built-in support for the Berkeley DB library (any version, as needed)</ti></tr> - - -<tr><ti>bonobo</ti><ti>enable Bonobo</ti><ti><c>gnome</c> packages and others</ti></tr> -<tr><ti>esd</ti><ti>enable ESound</ti><ti><c>gnome</c> packages and others</ti></tr> -<tr><ti>gdbm</ti><ti>use GNU dbm</ti><ti></ti></tr> -<tr><ti>glibc22</ti><ti>use GNU libc 2.2</ti><ti></ti></tr> -<tr><ti>gnome</ti><ti>use GNOME; also enables use of GNOME related packages such as gdk-pixbuf</ti><ti></ti></tr> -<tr><ti>gpm</ti><ti>use gpm</ti><ti></ti></tr> -<tr><ti>kde</ti><ti>enable features of the K Desktop Environment</ti><ti></ti></tr> -<tr><ti>ldap</ti><ti>use ldap</ti><ti></ti></tr> -<tr><ti>lm_sensors</ti><ti>enable lm_sensors</ti><ti><c>sys-kernel</c> packages</ti></tr> -<tr><ti>lvm</ti><ti>enable the Linux Volume Manager</ti><ti><c>sys-kernel</c> packages</ti></tr> -<tr><ti>motif</ti><ti>enable Motif</ti><ti></ti></tr> -<tr><ti>mysql</ti><ti>enable MySQL</ti><ti></ti></tr> -<tr><ti>odbc</ti><ti>enable odbc</ti><ti></ti></tr> -<tr><ti>ogg</ti><ti>enable the Ogg multimedia libraries</ti><ti></ti></tr> -<tr><ti>opengl</ti><ti>use OpenGL 3D graphics</ti><ti></ti></tr> -<tr><ti>pcmcia-cs</ti><ti>enable PCMCIA</ti><ti><c>sys-kernel</c> packages</ti></tr> -<tr><ti>postgres</ti><ti>use PostgreSQL</ti><ti></ti></tr> -<tr><ti>qt</ti><ti>use the Qt widget set</ti><ti></ti></tr> -<tr><ti>readline</ti><ti>use readline</ti><ti></ti></tr> -<tr><ti>slang</ti><ti>use slang</ti><ti></ti></tr> -<tr><ti>ssl</ti><ti>use SSL</ti><ti></ti></tr> -<tr><ti>tcltk</ti><ti>use Tcl/TK</ti><ti></ti></tr> -<tr><ti>tcpd</ti><ti>use tcpd/tcp_wrappers</ti><ti></ti></tr> -<tr><ti>xfs</ti><ti>enable the SGI XFS journaling filesystem</ti><ti><c>sys-kernel</c> packages</ti></tr> -</table> -</body> -</section> -</chapter> - -<chapter> -<title>Filesystem Locations</title> - -<section> -<title>Introduction to the FHS</title> -<body> -<p>The filesystem layout standards used in Gentoo Linux closely follow the FHS, -short for <e>Filesystem Hierarchy Standard</e>. A simplified -description of the standard is given here; for a complete -specification go to <uri>http://www.pathname.com/fhs/</uri>.</p> -<note> The <path>/opt</path> hierarchy is addressed in section 3.12 of the FHS. -Section 4.4 deals with the <path>/usr/X11R6</path> directory. KDE and GNOME are -not specifically addressed, and are in fact not even mentioned in the current -version of the FHS. -</note> -</body> -</section> - -<section> -<title>How to fit your packages into the filesystem</title> -<body><p>Usually, if the package uses autoconf and automake, the -default installation destinations are mostly correct, with a few exceptions:</p> -<ul> - -<li>If you're installing a program into <path>/bin</path>, <path>/sbin</path>, -<path>/usr/bin</path> or <path>/usr/sbin</path>, then the program's -corresponding man page should be installed into the <path>/usr/share/man</path> -tree. This can often be accomplished by specifying a <c>./configure ---mandir=/usr/share/man</c> in the ebuild.</li> - -<li>GNU info files should always be installed to <path>/usr/share/info</path>, -<e>even if the info files are about X11, GNOME or KDE-specific programs or -tools</e>. Make a note: <path>/usr/share/info</path> is the <e>only</e> -official location for GNU info files. Since most <c>./configure</c> scripts -default to installing GNU info files in <c>/usr/info</c>, it's often necessary -to call <c>./configure</c> with the <c>--infodir=/usr/share/info</c> argument.</li> - -<li>Documentation files are installed in <path>/usr/share/doc</path>, into a -subdirectory reflecting the name, version and revision of the particular -program. This applies to all programs: GNOME, KDE, X11 and console alike. -However, some programs may install additional documentation and support files -into a <path>/usr/share</path> hierarchy for their own purposes. -</li> - -<li>X11-specific programs and libraries should always be installed into <path>/usr</path>, not -directly into <path>/usr/X11R6</path>. We reserve the <path>/usr/X11R6</path> hierarchy for -the X Window System, Version 11 Release 6 <e>itself</e>. This is perhaps a more to-the-letter -interpretation of the FHS than some other distributions have made.</li> - -<li>GNOME and KDE programs, similarly, should always be installed into -<path>/usr</path>.</li> - -</ul> -<impo> Some distributions choose to install GNOME and KDE into <path>/opt</path>. There -exists no standard for these desktop environments in terms of where to actually install -their files. In the interests of simplicity and consistency, we elect to install all -KDE and GNOME packages into the <path>/usr</path> hierarchy.</impo> - -<p>In general, you should have ebuilds install their files into the <path>/usr</path> -tree. <e>Some</e> programs can be compiled and linked with or without GNOME, KDE and X11 libraries, -which can cause confusion. Our solution is to install everything into <path>/usr</path> -which avoids ambiguity and needless complexity for ebuild authors. The location in which to -install a program's files should <e>not</e> depend on the presence or abscence of specific -<c>USE</c> variables. Therefore, the ebuilds in the portage tree <e>almost always</e> -install into the <path>/usr</path> hierarchy exclusively.</p> - -<note>The <path>/opt</path> directory is reserved in Gentoo Linux for binary-only packages. -Examples include mozilla-bin, acroread, netscape and realplayer. Packages that get -installed here will usually require a <path>/etc/env.d/foo</path> stub file. This is -so that paths and additional variables can be included into the environment.</note> - -</body> -</section> -</chapter> - -<chapter> -<title>The Portage scripts and utilities</title> - -<section> -<title>Public scripts</title> -<body><p>These are scripts used by the system-administrator to install and remove packages, and maintain the package database.</p> -<p><c>ebuild</c></p> -<p><c>ebuild</c> is the main engine of the Portage system; it performs all major tasks such as unpacking, compiling, installing, merging, and unmerging packages. It is called using the command: <c>ebuild path/to/package.ebuild command</c>. The commands available are:</p> -<table> -<tr><th>Command</th><th>Description</th><th>Related <c>ebuild</c> Function</th></tr> -<tr><ti><c>depend</c></ti><ti>displays the dependencies required to build the package</ti><ti>n/a</ti></tr> -<tr><ti><c>check</c></ti><ti>checks that the package dependencies are fulfilled</ti><ti>n/a</ti></tr> -<tr><ti><c>rcheck</c></ti><ti>checks that the package runtime dependencies are fulfilled</ti><ti>n/a</ti></tr> -<tr><ti><c>merge</c></ti><ti>unpacks, compiles, installs, and merges the package into your filesystem</ti><ti>n/a</ti></tr> -<tr><ti>*<c>qmerge</c></ti><ti>merges the package into your filesystem, assuming that the the unpack, compile, and install stages have already been executed</ti><ti>n/a</ti></tr> -<tr><ti>*<c>unpack</c></ti><ti>unpacks the source tarballs into the work directory</ti><ti><c>src_unpack</c></ti></tr> -<tr><ti>*<c>compile</c></ti><ti>compiles the package</ti><ti><c>src_compile</c></ti></tr> -<tr><ti><c>rpm</c></ti><ti>creates an RPM from the package</ti><ti>n/a</ti></tr> -<tr><ti><c>package</c></ti><ti>creates a Gentoo <c>tbz2</c> package</ti><ti>n/a</ti></tr> -<tr><ti>*<c>prerm</c></ti><ti>executes the pre-removal stage of the package</ti><ti><c>pkg_prerm</c></ti></tr> -<tr><ti>*<c>postrm</c></ti><ti>executes the post-removal stage of the package</ti><ti><c>pkg_postrm</c></ti></tr> -<tr><ti>*<c>preinst</c></ti><ti>executes the pre-installation stage of the package</ti><ti><c>pkg_preinst</c></ti></tr> -<tr><ti>*<c>postinst</c></ti><ti>executes the post-installation stage of the package</ti><ti><c>pkg_postinst</c></ti></tr> -<tr><ti><c>config</c></ti><ti>sets up a default configuration once the package is merged</ti><ti><c>src_config</c></ti></tr> -<tr><ti>*<c>touch</c></ti><ti>updates the mtimes for each source archive in the package</ti><ti>n/a</ti></tr> -<tr><ti>*<c>clean</c></ti><ti>cleans the work directory for the package</ti><ti>n/a</ti></tr> -<tr><ti>*<c>fetch</c></ti><ti>fetches the package source tarballs</ti><ti>n/a</ti></tr> -<tr><ti>*<c>digest</c></ti><ti>creates a digest file for the package</ti><ti>n/a</ti></tr> -<tr><ti>*<c>install</c></ti><ti>installs the package into the image directory</ti><ti><c>src_install</c></ti></tr> -<tr><ti><c>unmerge</c></ti><ti>unmerges the package from your filesystem</ti><ti>n/a</ti></tr> -</table> -<p>Note: commands with an asterisk (*) are normally only used by the developer.</p> - -<p><c>emerge</c></p> -<p><c>emerge</c> recursively merges a package and all of its dependencies into your filesystem.</p> - -<p><c>pkgmerge</c></p> -<p><c>pkgmerge</c> merges a Gentoo <c>tbz2</c> package.</p> - -<p><c>env-update</c></p> -<p><c>env-update</c> updates the configuration files (including, but not limited to <path>/etc/ld.so.conf</path> and <path>/etc/profile.env</path>) to include changes made by installed packages.</p> -</body> -</section> - -<section> -<title>Private Scripts and Commands</title> -<body><p>These are scripts you can use in your ebuild files to perform common tasks.</p> -<table> -<tr><ti>dobin</ti><ti>installs the specified binaries into <path>DESTTREE/bin</path></ti></tr> -<tr><ti>into</ti><ti>sets the target prefix (<path>DESTTREE</path>) for <c>dobin</c>, <c>dolib</c>, <c>doman</c>, etc.</ti></tr> -<tr><ti>dodoc</ti><ti>installs the specified files into the packages documentation directory (<path>/usr/share/doc/${PF}</path>)</ti></tr> -<tr><ti>doexe</ti><ti></ti></tr> -<tr><ti>dohard</ti><ti></ti></tr> -<tr><ti>doinfo</ti><ti></ti></tr> -<tr><ti>doins</ti><ti></ti></tr> -<tr><ti>dolib</ti><ti></ti></tr> -<tr><ti>dolib.a</ti><ti></ti></tr> -<tr><ti>dolib.so</ti><ti></ti></tr> -<tr><ti>doman</ti><ti></ti></tr> -<tr><ti>domo</ti><ti></ti></tr> -<tr><ti>donewins</ti><ti></ti></tr> -<tr><ti>dopython</ti><ti></ti></tr> -<tr><ti>dosbin</ti><ti></ti></tr> -<tr><ti>dosed</ti><ti></ti></tr> -<tr><ti>dosym</ti><ti></ti></tr> -<tr><ti>find-packages</ti><ti></ti></tr> -<tr><ti>find-requires</ti><ti></ti></tr> -<tr><ti>fowners</ti><ti></ti></tr> -<tr><ti>fperms</ti><ti></ti></tr> -<tr><ti>import-configsettings</ti><ti></ti></tr> -<tr><ti>import-settings</ti><ti></ti></tr> -<tr><ti>megadigest</ti><ti></ti></tr> -<tr><ti>megadownload</ti><ti></ti></tr> -<tr><ti>megatouch</ti><ti></ti></tr> -<tr><ti>newbin</ti><ti></ti></tr> -<tr><ti>newdoc</ti><ti></ti></tr> -<tr><ti>newexe</ti><ti></ti></tr> -<tr><ti>newins</ti><ti></ti></tr> -<tr><ti>newlib.a</ti><ti></ti></tr> -<tr><ti>newlib.so</ti><ti></ti></tr> -<tr><ti>newman</ti><ti></ti></tr> -<tr><ti>newsbin</ti><ti></ti></tr> -<tr><ti>pkgmerge</ti><ti></ti></tr> -<tr><ti>pkgname</ti><ti></ti></tr> -<tr><ti>pmake</ti><ti></ti></tr> -<tr><ti>prepall</ti><ti></ti></tr> -<tr><ti>prepalldocs</ti><ti></ti></tr> -<tr><ti>prepallinfo</ti><ti></ti></tr> -<tr><ti>prepallman</ti><ti></ti></tr> -<tr><ti>try</ti><ti></ti></tr> -</table> -</body> -</section> -</chapter> - -<chapter> -<title>Package Dependencies</title> - -<section> -<title>Why dependencies are important</title> -<body><p>(TODO)<!-- todo --> -</p></body> -</section> - -<section> -<title>How to Specify Dependencies in Your ebuild Files</title> -<body><p>(TODO)<!-- todo --> -</p></body> -</section> -</chapter> - -</guide> |