diff options
Diffstat (limited to 'xml/htdocs/doc/en/gentoo-howto.xml')
| -rw-r--r-- | xml/htdocs/doc/en/gentoo-howto.xml | 1707 |
1 files changed, 0 insertions, 1707 deletions
diff --git a/xml/htdocs/doc/en/gentoo-howto.xml b/xml/htdocs/doc/en/gentoo-howto.xml deleted file mode 100644 index bb8d36debf..0000000000 --- a/xml/htdocs/doc/en/gentoo-howto.xml +++ /dev/null @@ -1,1707 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/Attic/gentoo-howto.xml,v 1.35 2004/02/12 08:57:24 swift Exp $ --> -<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> - -<guide link="/doc/en/gentoo-howto.xml"> -<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> -<author title="Author"> - <mail link="karltk@gentoo.org">Karl Trygve Kalleberg</mail> -</author> -<author title="Author"><!-- zhen@gentoo.org --> - John P. Davis -</author> -<author title="Author"> - <mail link="vapier@gentoo.org">Mike Frysinger</mail> -</author> -<author title="Editor"> - <mail link="peesh@gentoo.org">Jorge Paulo</mail> -</author> -<author title="Editor"> - <mail link="swift@gentoo.org">Sven Vermeulen</mail> -</author> -<author title="Editor"> - <mail link="klasikahl@gentoo.org">Zack Gilburd</mail> -</author> -<author title="Editor"> - <mail link="bennyc@gentoo.org">Benny Chuang</mail> -</author> -<author title="Editor"> - <mail link="erwin@gentoo.org">Erwin</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. You should <e>always</e> use this in -conjunction with the manpages provided by portage (especially ebuild(5)) -and the <uri link="http://www.gentoo.org/doc/en/policy.xml">Gentoo Linux -Development Policy</uri>. -</abstract> - -<version>1.4.7</version> -<date>February 12, 2004</date> - -<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 hierarchical structure consisting of category directories, -followed by specific package directories. Here's an example; you can find -the <path>util-linux-2.11y.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.11y.ebuild</path>. This is because <e>all ebuilds for -a particular package (regardless of version)</e>, share the same -<path>mycat/mypkg</path> directory in <path>/usr/portage</path>. -</p> - -</body> -</section> - -<section> -<title>Checking Out the Portage Tree from CVS</title> -<body> - -<p> -If you are unfamiliar with the CVS system, please read the -<uri link="http://www.gentoo.org/doc/en/cvs-tutorial.xml">CVS Tutorial</uri> -for more information. -</p> - -<p> -The Portage tree can be found in the <c>gentoo-x86</c> module of the -Gentoo Linux tree. To check out the module (about 350 megabytes) you -would first set up CVS via the above guide, then check out the -<c>gentoo-x86</c> module. -</p> - -</body> -</section> - -<section> -<title>What (not) to put in the Portage tree</title> -<body> - -<p> -Before writing any ebuild, check <uri -link="http://bugs.gentoo.org/">bugs.gentoo.org</uri> for an ebuild -corresponding to the ebuild you want to write, but that has not yet been put -into the Portage tree. Go to <uri -link="http://bugs.gentoo.org/">bugs.gentoo.org</uri>, choose query; as product -select <e>Gentoo Linux</e>, as component select <e>ebuilds</e>. In the search -field put the name of the ebuild and as status select NEW, ASSIGNED, REOPENED -and RESOLVED (RESOLVED is important), then submit the query. For you lazy -people, click <uri link="http://bugs.gentoo.org/query.cgi?product=Gentoo%20Linux&component=Ebuilds&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=RESOLVED">here</uri>. -</p> - -<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. -Exceptions to this rule are for larger patch files which should be put onto -the Gentoo mirrors so that people do not waste excessive amounts of -bandwidth and hard drive space. 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 caption="Adding binary files to CVS"> -# <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 correctly inform -developers of conflicts. -</p> - -<p> -Remember, the packages that you commit must be <e>ready</e> <e>out of the -box</e> for end users when committed as stable. Make sure that you have a good -set of default settings that will satisfy the majority of systems and -users that will use your package. If your package is broken, and you are -not sure how to get it to work, check some other distributions that have -done their own versions of the package. You can check -<uri link="http://cvs.mandrakesoft.com/cgi-bin/cvsweb.cgi/SPECS/">Mandrake</uri> -or <uri link="http://www.debian.org/distrib/packages">Debian</uri> for some -examples. -</p> - -<p> -Double-check the ebuild and cross it with the <uri -link="/doc/en/ebuild-mistakes.xml">Common Gentoo Ebuild Mistakes</uri> document. -</p> - -<p> -When committing to CVS, all developers should use <c>repoman commit</c> -instead of <c>cvs commit</c> to submit their ebuilds. Before committing, -please run <c>repoman full</c> to make sure you didn't forget something. -</p> - -</body> -</section> - -<section> -<title>CVS Commit Policy</title> -<body> - -<ul> -<li>Always run <c>repoman scan</c> before you commit.</li> -<li>Please run <c>repoman full</c> before you commit.</li> -<li>Always test that <path>package.mask</path> is okay by doing -<c>emerge --pretend mypkg</c> before you commit and check -that it doesn't contain any conflicts.</li> -<li>Always update the <path>ChangeLog</path> before you commit.</li> -<li>Always commit the updated <path>package.mask</path> before -the updated package, in case conflicts occur while you commit -<path>package.mask</path>.</li> -<li>Always do atomic commits; if you commit a package with a new license, -or that is masked, then first commit the revised <path>package.mask</path>, -then commit the ebuild, <path>ChangeLog</path> and license all in _one_ go, -unless you want to break the users' installations.</li> -</ul> - -</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>, -or more simply, <path>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 prefixing or suffixing (such as <path>mypkg-1.0</path>) every file -you put into the <path>files/</path> directory, so that the files used for -each individual version on an ebuild 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 you wish to -convey more meaning with the patch name. -</p> - -<p> -If you have many files that should go into the <path>files/</path> directory, -consider creating subdirectories such as <path>files/1.0/</path> and putting the -relevant files in the appropriate subdirectory. If you use this method, -you do not need to add version information to the names of the files, -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 steps. 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, using -bash syntax is a very 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 <e>pretend</e> merges so that user can see what ebuilds -would 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 -emerge (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 ebuild. -</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 ('-') or -underscore ('_') characters. Some examples are <c>util-linux</c>, -<c>sysklogd</c>, <c>mod_php</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> (pre-release), <c>_rc</c> (release -candidate), or <c>_p</c> (patch). 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>, <c>_pre</c> older than <c>_rc</c>, and <c>_rc</c> older -than <c>_p</c>. This section is meant to reflect upstream versions only. -</p> - -<note> -An <c>_rc</c> package is older than a package without an underscore suffix -(i.e. <c>linux-2.4.0</c>), and <c>linux-2.4.0</c> is older than a package -with a single letter suffix, 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 version 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. Remember -to <e>always</e> make mentions of your changes in the <path>ChangeLog</path>. -You are in serious trouble if you do not do this, your CVS access may be -revoked. -</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 <e>ebuild</e> File</title> -<body> - -<note> -This section is an introduction to ebuilds. For the full listing of everything -possible in an ebuild, there is a manpage which talks about the internal -format, variables, and functions in an ebuild script: <c>man 5 ebuild</c>. -</note> - -<p><b>Variables</b></p> - -<p> -The first part of every ebuild file is made up of a number of variables. -They fall under 3 categories (and are marked below with these numbers): -</p> - -<ul> -<li>READ: variables you can utilize but <e>never set</e></li> -<li>MUST: variables you <e>must always set</e></li> -<li>OPT: variables that you should set</li> -</ul> - -<table> -<tr> - <th>Variable</th> - <th>Usage</th> - <th>Description</th> -</tr> -<tr> - <ti><c>P</c></ti> - <ti>READ</ti> - <ti>The name and version of the package.</ti> -</tr> -<tr> - <ti><c>PN</c></ti> - <ti>READ</ti> - <ti>The name of the package.</ti> -</tr> -<tr> - <ti><c>PV</c></ti> - <ti>READ</ti> - <ti>The version of the package.</ti> -</tr> -<tr> - <ti><c>PR</c></ti> - <ti>READ</ti> - <ti>Contains the revision number or <c>r0</c> if no revision number exists.</ti> -</tr> -<tr> - <ti><c>PVR</c></ti> - <ti>READ</ti> - <ti>Contains the version number with the revision.</ti> -</tr> -<tr> - <ti><c>PF</c></ti> - <ti>READ</ti> - <ti>Contains the full package name <c>${PN}-${PV}-${PR}</c>.</ti> -</tr> -<tr> - <ti><c>A</c></ti> - <ti>READ</ti> - <ti> - Space delimited list of the filenames in <c>SRC_URI</c>. This does not - contain the URL paths, just the filename. - </ti> -</tr> -<tr> - <ti><c>WORKDIR</c></ti> - <ti>READ</ti> - <ti> - Base of the build root for the ebuild. Nothing should be built outside of - this directory. - </ti> -</tr> -<tr> - <ti><c>FILESDIR</c></ti> - <ti>READ</ti> - <ti> - Contains the path to the <path>files</path> sub folder in the package specific location in the portage tree. Do not modify this variable. - </ti> -</tr> -<tr> - <ti><c>S</c></ti> - <ti>OPT</ti> - <ti> - The source directory for your package; commonly <c>${WORKDIR}/${P}</c>. - Portage will default to this value so you may not have to set it! - </ti> -</tr> -<tr> - <ti><c>T</c></ti> - <ti>READ</ti> - <ti> - The temporary directory for your package. It is used as a virtual - <path>/tmp</path> directory while processing the ebuild. - </ti> -</tr> -<tr> - <ti><c>D</c></ti> - <ti>READ</ti> - <ti> - The root directory that the package is installed to, treat it as the - virtual <path>/</path>. - </ti> -</tr> -<tr> - <ti><c>SLOT</c></ti> - <ti>MUST</ti> - <ti> - Portage handles different versions of the same installed programs. If you - would want, say GCC 2.95 and GCC 3.2 installed at the same time, you would - specify the <c>SLOT</c> in each ebuild. Here we would set the <c>SLOT</c> - of GCC 2.95 to <c>2</c> while we would set the <c>SLOT</c> of GCC 3.2 to - <c>3</c>. - <note> - Using <c>0</c> as the <c>SLOT</c> value signifies that this package only - has 1 <c>SLOT</c> setting (in other words, this package is not SLOTable). - </note> - </ti> -</tr> -<tr> - <ti><c>LICENSE</c></ti> - <ti>MUST</ti> - <ti> - This variable specifies what license the program is covered under, i.e. - GPL-2, BSD, etc... This field must be set to a valid license (which is - any license found in <path>/usr/portage/license/</path>). If the license - does not already exist there, it must be added before the ebuild can be - added to the portage tree. - </ti> -</tr> -<tr> - <ti><c>KEYWORDS</c></ti> - <ti>MUST</ti> - <ti> - This variable now supports a couple of different functions. First of all, - this variable specifies what architecture the ebuild is meant for. These - keywords include: <e>x86, ppc, sparc, mips, alpha, arm, hppa, amd64, - ia64</e>. Obviously, you would set this to reflect the architecture of the - target machine. Portage will not allow an x86 machine to build anything - but x86, as specified by the <c>KEYWORDS</c> variable. Packages that do - no support the native architecture are automatically masked by Portage. - If the <c>KEYWORDS</c> flag has a preceding <e>~</e>, then that indicates - that the particular ebuild works, but needs to be tested in several - environments before being moved to the stable profile with the given - keyword. If the <c>KEYWORDS</c> flag has a preceding <e>-</e>, then - the package does not work with the given keyword. If there is nothing - leading <c>KEYWORDS</c>, then the package is considered stable. You can - allow installation of these different types of packages through the - <c>ACCEPT_KEYWORDS</c> variable in <path>make.conf</path>. - </ti> -</tr> -<tr> - <ti><c>DESCRIPTION</c></ti> - <ti>MUST</ti> - <ti>A <e>short</e>, one line description of your package.</ti> -</tr> -<tr> - <ti><c>SRC_URI</c></ti> - <ti>MUST</ti> - <ti> - The URLs for every source file in your package, separated by whitespace. - Normally the first one is something like - "ftp://ftp.company.com/pub/somepackage/${P}.tar.bz2" - </ti> -</tr> -<tr> - <ti><c>HOMEPAGE</c></ti> - <ti>MUST</ti> - <ti> - The homepage of the package. If you are unable to locate an official one, - try to provide a link from <uri - link="http://freshmeat.net/">freshmeat.net</uri> or a similar package - tracking site. - </ti> -</tr> -<tr> - <ti><c>IUSE</c></ti> - <ti>MUST</ti> - <ti> - This is set to whatever <c>USE</c> variables your package utilizes. - Remember that <c>KEYWORDS</c> should not be listed in here! - </ti> -</tr> -<tr> - <ti><c>DEPEND</c></ti> - <ti>OPT</ti> - <ti> - The package's build dependencies are listed here. See the section - <uri link="#doc_chap5">Package Dependencies</uri> for more details on - proper syntax. - </ti> -</tr> -<tr> - <ti><c>RDEPEND</c></ti> - <ti>OPT</ti> - <ti> - The package's runtime dependencies are listed here. Once again, see - <uri link="#doc_chap5">Package Dependencies</uri> for more details. - </ti> -</tr> -</table> - -<p><b>Functions</b></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>pkg_setup</c></ti> - <ti> - Use this function to perform any miscellaneous prerequisite tasks. This - might include adding system accounts or checking for an existing - configuration file. - </ti> -</tr> -<tr> - <ti><c>pkg_nofetch</c></ti> - <ti> - Inform the user about required actions if for some reason (such as - licensing issues) the sources may not be downloaded by Portage - automatically. Use this in conjunction with - <c>RESTRICT="fetch"</c>. - You only should display messages in this function, never call <c>die</c>. - </ti> -</tr> -<tr> - <ti><c>src_unpack</c></ti> - <ti> - Use this function to unpack your sources, apply patches, and run - auxiliary programs such as the autotools. By default, this function - unpacks the packages listed in <c>A</c>. The initial working directory is - defined by <c>WORKDIR</c>. - </ti> -</tr> -<tr> - <ti><c>src_compile</c></ti> - <ti> - Use this function to configure and build the package. The initial working - 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>. <e>Make sure your package installs all - its files using <c>D</c> as the root!</e> The initial working directory is - <c>S</c>. - </ti> -</tr> -<tr> - <ti><c>pkg_preinst</c></ti> - <ti> - The commands in this function are run just <e>prior to merging</e> a - package image into the file system. - </ti> -</tr> -<tr> - <ti><c>pkg_postinst</c></ti> - <ti> - The commands in this function are run just <e>following merging</e> a - package image into the file system. - </ti> -</tr> -<tr> - <ti><c>pkg_prerm</c></ti> - <ti> - The commands in this function are run just <e>prior to unmerging</e> a - package image from the file system. - </ti> -</tr> -<tr> - <ti><c>pkg_postrm</c></ti> - <ti> - The commands in this function are run just <e>following unmerging</e> a - package image from the file system. - </ti> -</tr> -<tr> - <ti><c>pkg_config</c></ti> - <ti> - You use this function to setup an initial configuration for the package - after it's installed. All paths in this function should be prefixed with - <c>ROOT</c>. This function is <e>only</e> executed if and when the user - runs: <c>ebuild /var/db/pkg/${CATEGORY}/${PF}/${PF}.ebuild config</c>. - </ti> -</tr> -</table> - -<p><b>Helper Functions</b></p> - -<p> -You can also use the following helper functions in your ebuilds. -</p> - -<table> -<tr> - <ti><c>use</c></ti> - <ti> - Check if one or more given use-flags are defined. If so, the function will - echo the flags that exist in <c>USE</c>. To check the existence of a - use-flag, you can use <c>[ `use foobar` ]</c>. - </ti> -</tr> -<tr> - <ti><c>has_version</c></ti> - <ti> - Returns 1 if the system has the requested version of a certain package. - For instance <c>has_version >=glibc-2.3.0</c>. - </ti> -</tr> -<tr> - <ti><c>best_version</c></ti> - <ti> - Returns <path>category/package-version</path> of the requested - <path>category/package</path>. For instance <c>best_version - x11-libs/gtk+extra</c>. - </ti> -</tr> -<tr> - <ti><c>use_with</c></ti> - <ti> - This function checks if a use-flag has been defined and returns - "--with-foobar" or "--without-foobar" accordingly. If - you only use one argument, that argument is both use-flag and - with(out)-string. Otherwise the first argument is the use-flag and the - second argument the with(out)-string. For instance <c>use_with truetype - freetype</c> will echo "--with-freetype" if truetype is in - <c>USE</c>. - </ti> -</tr> -<tr> - <ti><c>use_enable</c></ti> - <ti> - The same as <c>use_with</c>, but returns "--enable-foobar" or - "--disable-foobar" accordingly. - </ti> -</tr> -<tr> - <ti><c>check_KV</c></ti> - <ti> - Checks if Portage knows kernel version. If not, display an error and - die. If you need the kernel version in your script, use the <c>KV</c> - variable which is automatically defined by Portage. On system running - gentoo-sources-2.4.20-r6, <c>KV</c> would have the value "2.4.20". - </ti> -</tr> -<tr> - <ti><c>keepdir</c></ti> - <ti> - Creates (if necessary) a <path>.keep</path> file in the given directory - so that it isn't auto-cleaned. <e>Never</e> create a <path>.keep</path> - file yourself. If portage changes how <c>keepdir</c> works, then creating - the file yourself will break the package. - </ti> -</tr> -<tr> - <ti><c>econf</c></ti> - <ti> - Issues <c>./configure</c> with the necessary path-changes (prefix, host, - mandir, infodir, datadir, sysconfdir, localstatedir). You can optionally - pass extra arguments to <c>./configure</c> by specifying them when you - call <c>econf</c>, and/or you can set the the environment variable - <c>EXTRA_ECONF</c>. Options passed to configure take precedence in the - reverse order that they were given. In other words, the first argument - passed will always by overridden by the last. - </ti> -</tr> -<tr> - <ti><c>einstall</c></ti> - <ti> - Issues <c>make install</c> with the necessary path-changes (prefix, datadir, - mandir, infodir, datadir, sysconfdir, localstatedir). Again, you can pass - extra arguments to the make command by specifying them when you call - <c>einstall</c>. Please note that the preferred way to install a package is - via the <c>make install DESTDIR=${D}</c> command and not via - <c>einstall</c>. This command is only a fall back to override broken make - files. - </ti> -</tr> -<tr> - <ti><c>die</c></ti> - <ti> - Causes the current process to be aborted. It will notify the user using - the given arguments as a reason. Do not neglect to pass a message to - <c>die</c> if you have more than one call to it in a single function. It - is harder to track down a failure if you're not sure <c>where</c> the - package failed. - </ti> -</tr> -<tr> - <ti><c>einfo</c></ti> - <ti> - Inform the user about something important. The argument given to - <c>einfo</c> is the message that the user will see. Do not use - <c>einfo</c> to display banners such as - "*************************************". The fact that you're - using <c>einfo</c> is enough to get the user's attention. - </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 -- <e>no spaces</e>. Make sure -you set up your editor to put tab stops 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> -Long lines are wrapped with ' \', thus: -</p> - -<pre caption="Wrapping lines in ebuilds"> -./configure \ ---prefix=/usr || die "configure failed" -</pre> - -<p> -For further details, refer to <path>skel.ebuild</path> (usually -residing in <path>/usr/portage</path>). -</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 caption="Configuring vimrc for ebuild-editing"> -if (getcwd() =~ 'gentoo-x86\|gentoo-src\|portage') - set tabstop=4 shiftwidth=4 noexpandtab -endif -</pre> - -<p> -If you're using Emacs, you can put the following snippet at the bottom of -.emacsrc file (for GNU Emacs) or init.el (for XEmacs) to make sure your using -the correct settings when editing anything Gentoo-related. -</p> - -<pre caption="Configuring emacsrc for ebuild-editing"> -(defun ebuild-mode () - (shell-script-mode) - (sh-set-shell "bash") - (make-local-variable 'tab-width) - (setq tab-width 4)) -(setq auto-mode-alist (cons '("\\.ebuild\\'" . ebuild-mode) auto-mode-alist)) -(setq auto-mode-alist (cons '("\\.eclass\\'" . ebuild-mode) auto-mode-alist)) -</pre> - -<p> -If you're using nano, then you're in luck! Just edit <path>/etc/nanorc</path> -and uncomment the section referring to ebuild's. -</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. -</p> - -<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 exactly what you're going to get! -</note> - -<p> -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 -<c><variable></c> if it is present in the user's <c>USE</c>. You would -normally use this command as follows: -</p> - -<pre caption="Finding out if a USE-flag is set"> -if [ `use X` ] ; then - commands specific to X -fi -</pre> - -<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 )</c> in the <c>DEPEND</c> -variable for your ebuild. In this example, <c>mycat/mypackage</c> will -only be required if <c>variable</c> is present in <c>USE</c>. It is also -possible to specify what dependency should be used if some useflag is -set, and what dependency to use if it is <e>not</e> set: <c>variable? ( -mycat/mypackage) : ( othercat/otherpackage )</c>. In this case, if -<c>variable</c> is not set, <c>othercat/otherpackage</c> is used instead -of <c>mycat/mypackage</c>. Finally, you can also specify a dependency in -case a certain variable is <e>not</e> set. Just prefix the variable with -"!", like this: <c>!variable? ( mycat/mypackage )</c>. Make sure -that your ebuilds use this syntax and not Bash IFS. Bash conditionals -interfere with Portage's dependency caching, and the use of them will -ultimately break your ebuild. -</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: -</p> - -<pre caption="Conditionals based on USE-settings"> -DEPEND="X? ( >=x11-base/xfree-4.3 ) -mysql? ( >=dev-db/mysql-3.23.49 ) -apache2? ( >=net-www/apache-2 ) : ( =net-www/apache-1.* )" - -src_compile() { - econf \ - `use_enable X x11` \ - `use_enable mysql` \ - || die "configure failed" - emake || die "emake failed" -} -</pre> - -<p> -This approach has a very nice result. We don't have to worry about what the -default setting is for mysql or X (enable/disabled), we explicitly tell -<c>econf</c> what we want it to do based upon the <c>USE</c> variable. Not to -mention it's quite clean in terms of readability :). -</p> - -<p> -To view a continuously updated table of USE variables, please go -<uri link="http://www.gentoo.org/dyn/use-index.xml">here</uri>. -</p> - -</body> -</section> -</chapter> -<chapter> -<title>File system Locations</title> -<section> -<title>Introduction to the FHS</title> -<body> - -<p> -The file system layout standards used in Gentoo Linux closely follow the FHS, -short for <e>File system 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 file system</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 many <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 absence 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. For more information on -<path>/etc/env.d</path>, please visit <uri -link="http://www.gentoo.org/doc/en/env.d-howto.xml">this</uri> document. -</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> 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>setup</c>*</ti> - <ti> - Performs any miscellaneous commands required before the ebuild can proceed - </ti> - <ti><c>pkg_setup</c></ti> -</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>merge</c>*</ti> - <ti> - Unpacks, compiles, installs, and merges the package into your file system - </ti> - <ti>N/A</ti> -</tr> -<tr> - <ti><c>qmerge</c>*</ti> - <ti> - Merges the package into your file system, 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>pkg_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 file system</ti> - <ti>N/A</ti> -</tr> -</table> - -<note> -Commands with an asterisk (*) are normally only used by the developer. -</note> - -<p> -<c>emerge</c> recursively merges a package and all of its dependencies into -your file system. This command has many options, try <c>emerge --help</c> for -a list of them. -</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> - -<p> -For you down and dirty people, look at the scripts themselves in -<path>/usr/lib/portage/bin</path>. -</p> - -<table> -<tr> - <th>Command</th> - <th>Default Value</th> - <th>Description</th> - <th>Example</th> -</tr> -<tr> - <ti><c>diropts</c></ti> - <ti>-m0755</ti> - <ti>Sets the options used when running <c>dodir</c></ti> - <ti><c>diropts -m0750</c></ti> -</tr> -<tr> - <ti><c>dobin</c></ti> - <ti>N/A</ti> - <ti>Installs the specified binaries into <path>DESTTREE/bin</path></ti> - <ti><c>dobin wmacpi</c></ti> -</tr> -<tr> - <ti><c>docinto</c></ti> - <ti><path>""</path></ti> - <ti> - Sets the relative subdir (<e>DOCDESTTREE</e>) used by <c>dodoc</c> - </ti> - <ti><c>docinto examples</c></ti> -</tr> -<tr> - <ti><c>dodir</c></ti> - <ti>N/A</ti> - <ti>Creates a directory, handling ${D} transparently</ti> - <ti><c>dodir /usr/lib/newpackage</c></ti> -</tr> -<tr> - <ti><c>dodoc</c></ti> - <ti>N/A</ti> - <ti> - Installs the specified files into the package's documentation directory - (<path>/usr/share/doc/${PF}/DOCDESTTREE</path>) (see <c>docinto</c>) - </ti> - <ti><c>dodoc README *.txt</c></ti> -</tr> -<tr> - <ti><c>doexe</c></ti> - <ti>N/A</ti> - <ti> - Installs the specified files with mode <e>EXEOPTIONS</e> (see - <c>exeopts</c>) into <path>EXEDESTTREE</path> (see <c>exeinto</c>) - </ti> - <ti><c>doexe ${FILESDIR}/quake3</c></ti> -</tr> -<tr> - <ti><c>dohard</c></ti> - <ti>N/A</ti> - <ti>Creates a hard link, handling ${D} transparently</ti> - <ti><c>dohard ls /bin/dir</c></ti> -</tr> -<tr> - <ti><c>dohtml</c></ti> - <ti>N/A</ti> - <ti> - Installs the specified files and directories into - <path>/usr/share/doc/${PF}/html</path> - </ti> - <ti><c>dohtml -r doc/html/*</c></ti> -</tr> -<tr> - <ti><c>doinfo</c></ti> - <ti>N/A</ti> - <ti> - Installs the specified files into /usr/share/info, then compresses them - with gzip - </ti> - <ti><c>doinfo doc/*.info</c></ti> -</tr> -<tr> - <ti><c>doins</c></ti> - <ti>N/A</ti> - <ti> - Installs the specified files with mode <c>INSOPTIONS</c> (see - <c>insopts</c>) into <path>INSDESTTREE</path> (see <c>insinto</c>) - </ti> - <ti><c>doins *.png icon.xpm</c></ti> -</tr> -<tr> - <ti><c>dolib</c></ti> - <ti>N/A</ti> - <ti> - Installs the specified libraries into <path>DESTTREE/lib</path> with mode - 0644 - </ti> - <ti><c>dolib *.a *.so</c></ti> -</tr> -<tr> - <ti><c>dolib.a</c></ti> - <ti>N/A</ti> - <ti> - Installs the specified libraries into <path>DESTTREE/lib</path> with mode - 0644 - </ti> - <ti><c>dolib.a *.a</c></ti> -</tr> -<tr> - <ti><c>dolib.so</c></ti> - <ti>N/A</ti> - <ti> - Installs the specified libraries into <path>DESTTREE/lib</path> with mode - 0755 - </ti> - <ti><c>dolib.so *.so</c></ti> -</tr> -<tr> - <ti><c>doman</c></ti> - <ti>N/A</ti> - <ti> - Installs the specified files into <path>/usr/share/man/manX</path>, - according to the suffix of the file (file.1 will go into <path>man1</path>) - </ti> - <ti><c>doman *.1 *.5</c></ti> -</tr> -<tr> - <ti><c>dosbin</c></ti> - <ti>N/A</ti> - <ti> - Installs the files into <path>DESTTREE/sbin</path>, making sure they are - executable - </ti> - <ti><c>dosbin ksymoops</c></ti> -</tr> -<tr> - <ti><c>dosym</c></ti> - <ti>N/A</ti> - <ti>Creates a symlink, handles ${D} transparently</ti> - <ti><c>dosym gzip /bin/zcat</c></ti> -</tr> -<tr> - <ti><c>emake</c></ti> - <ti>N/A</ti> - <ti> - Runs make with <c>MAKEOPTS</c>. some packages cannot be made in parallel; - use <c>emake -j1</c> instead - </ti> - <ti><c>emake</c></ti> -</tr> -<tr> - <ti><c>exeinto</c></ti> - <ti><path>/</path></ti> - <ti>Sets the root (<e>EXEDESTTREE</e>) for the <c>doexe</c> command</ti> - <ti><c>exeinto /usr/lib/${PN}</c></ti> -</tr> -<tr> - <ti><c>exeopts</c></ti> - <ti>-m0755</ti> - <ti>Sets the options used when running <c>doexe</c></ti> - <ti><c>exeopts -m1770</c></ti> -</tr> -<tr> - <ti><c>fowners</c></ti> - <ti>N/A</ti> - <ti> - Applies the specified ownership to the specified file via the chown - command, handles ${D} transparently - </ti> - <ti><c>fowners root:root /sbin/functions.sh</c></ti> -</tr> -<tr> - <ti><c>fperms</c></ti> - <ti>N/A</ti> - <ti> - Applies the specified permissions to the specified file via the chmod - command, handles ${D} transparently - </ti> - <ti><c>fperms 700 /var/consoles</c></ti> -</tr> -<tr> - <ti><c>insinto</c></ti> - <ti><path>/usr</path></ti> - <ti>Sets the root (<e>INSDESTTREE</e>) for the <c>doins</c> command</ti> - <ti><c>insinto /usr/include</c></ti> -</tr> -<tr> - <ti><c>insopts</c></ti> - <ti>-m0644</ti> - <ti>Sets the options used when running <c>doins</c></ti> - <ti><c>insopts -m0444</c></ti> -</tr> -<tr> - <ti><c>into</c></ti> - <ti><path>/usr</path></ti> - <ti> - Sets the target prefix (<path>DESTTREE</path>) for all the 'do' commands - (like <c>dobin</c>, <c>dolib</c>, <c>dolib.a</c>, <c>dolib.so</c>, - <c>domo</c>, <c>dosbin</c>) - </ti> - <ti><c>into /</c></ti> -</tr> -<tr> - <ti><c>libopts</c></ti> - <ti>-m0644</ti> - <ti>Sets the options used when running <c>dolib</c></ti> - <ti><c>libopts -m0555</c></ti> -</tr> -<tr> - <ti><c>newbin</c></ti> - <ti>N/A</ti> - <ti> - Wrapper around <c>dobin</c> which installs the specified binary - transparently renaming to the second argument - </ti> - <ti><c>newbin ${FILESDIR}/vmware.sh vmware</c></ti> -</tr> -<tr> - <ti><c>newdoc</c></ti> - <ti>N/A</ti> - <ti> - Wrapper around <c>dodoc</c> which installs the specified file transparently - renaming to the second argument - </ti> - <ti><c>newdoc README README.opengl</c></ti> -</tr> -<tr> - <ti><c>newexe</c></ti> - <ti>N/A</ti> - <ti> - Wrapper around <c>doexe</c> which installs the specified file transparently - renaming to the second argument - </ti> - <ti><c>newexe ${FILESDIR}/xinetd.rc xinetd</c></ti> -</tr> -<tr> - <ti><c>newins</c></ti> - <ti>N/A</ti> - <ti> - Wrapper around <c>doins</c> which installs the specified file transparently - renaming to the second argument - </ti> - <ti><c>newins ntp.conf.example ntp.conf</c></ti> -</tr> -<tr> - <ti><c>newman</c></ti> - <ti>N/A</ti> - <ti> - Wrapper around <c>doman</c> which installs the specified file transparently - renaming to the second argument - </ti> - <ti><c>newman xboing.man xboing.6</c></ti> -</tr> -<tr> - <ti><c>newsbin</c></ti> - <ti>N/A</ti> - <ti> - Wrapper around <c>dosbin</c> which installs the specified file transparently - renaming to the second argument - </ti> - <ti><c>newsbin strings strings-static</c></ti> -</tr> -<tr> - <ti><c>prepall</c></ti> - <ti>N/A</ti> - <ti> - Runs <c>prepallman</c>, <c>prepallinfo</c> and <c>prepallstrip</c>. Also - ensures all libraries in <path>/opt/*/lib</path>, <path>/lib</path>, - <path>/usr/lib</path> and <path>/usr/X11R6/lib</path> are executable. also - moves any stray aclocal macros into <path>/usr/share/aclocal</path> - </ti> - <ti><c>prepall</c></ti> -</tr> -<tr> - <ti><c>prepalldocs</c></ti> - <ti>N/A</ti> - <ti> - Recursively gzips all doc files in <path>/usr/share/doc</path>, - transparently fixing up any symlink paths - </ti> - <ti><c>prepalldocs</c></ti> -</tr> -<tr> - <ti><c>prepallinfo</c></ti> - <ti>N/A</ti> - <ti>Recursively gzips all info files in <path>/usr/share/info</path></ti> - <ti><c>prepallinfo</c></ti> -</tr> -<tr> - <ti><c>prepallman</c></ti> - <ti>N/A</ti> - <ti> - Recursively gzips all man pages in <path>/opt/*/man/*</path>, - <path>/usr/share/man/*</path>, <path>/usr/local/man/*</path>, - <path>/usr/X11R6/share/man/*</path> and transparently fixes up any symlink - paths - </ti> - <ti><c>prepallman</c></ti> -</tr> -</table> - -</body> -</section> -</chapter> -<chapter> -<title>Package Dependencies</title> -<section> -<title>Why dependencies are important</title> -<body> - -<p> -Portage is more than just a convenience script that gives you a unified -way to build any one project (program, library) from source. It will also -fetch and install any necessary dependencies if you take care to specify -these in your ebuild. -</p> - -<p> -In the official ebuilds, all dependencies have already been specified, -so when you issue <c>emerge net-www/mozilla/mozilla-1.0</c>, Portage will -insure that all libraries necessary for Mozilla to build and run are -properly installed before Mozilla itself is built. -</p> - -<p> -Portage even distinguishes between build-time dependencies and run-time -dependencies. (Caveat: Currently, Portage installs all build-time and run-time -dependencies and leaves it at that. At a later stage, it will be possible to -trim your installation so that only the run-time dependencies are left -installed). -</p> - -</body> -</section> -<section> -<title>How to Specify Dependencies in Your ebuild Files (a.k.a. DEPEND Atoms)</title> -<body> - -<p> -The <c>DEPEND</c> variable inside your <path>foo-x.y.z.ebuild</path> tells -Portage about which packages are needed to build <path>foo</path>. The -<c>RDEPEND</c> variable specifies which packages are needed for <path>foo</path> -to run. -</p> - -<pre caption="Depend example"> -DEPEND="virtual/glibc - sys-libs/zlib" -RDEPEND="virtual/glibc" -</pre> - -<p> -This tells Portage that to build <path>foo-x.y.z</path>, the packages -<path>virtual/glibc</path> (more on virtuals in a bit) and -<path>sys-libs/zlib</path> are needed. It does not say anything about which -version of glibc or zlib that are needed, which means "anything goes". -</p> - -<p> -The "anything goes" is of course a bit scary, and will not work in the general -case. But for central libraries like glibc, which strives very hard to be 100% -binary compatible all the time, it actually works. For other libraries, we can -of course specify version dependencies. -</p> - -<pre caption="Version example"> ->=sys-apps/bar-1.2 -=sys-apps/baz-1.0 -</pre> - -<p> ->= and = do what you would expect; sys-apps/bar version 1.2 or newer is okay -(this means that sys-apps/bar-2.0 is okay), while sys-apps/baz version 1.0 is -the only version that is accepted. For more information on the version schema of -packages, see the section above on <uri link="#doc_chap2_sect2">Naming ebuild -Files</uri>. -</p> - -<p> -Other methods of specifying version dependencies are follow: -</p> - -<pre caption="Specifying version dependencies"> -~sys-apps/qux-1.0 -=sys-apps/foo-1.2* -!sys-libs/gdbm -</pre> - -<p> -~sys-apps/qux-1.0 will select the newest portage revision of qux-1.0. -</p> - -<p> -=sys-apps/foo-1.2* will select the newest member of the 1.2 series, but will -ignore 1.3 and later/earlier series. That is, foo-1.2.3 and foo-1.2.0 are both -valid, while foo-1.3.3, foo-1.3.0, and foo-1.1.0 are not. -</p> - -<p> -!sys-libs/gdbm will prevent this package from being emerged while gdbm is -already emerged. -</p> - -<note> -For all the latest details about these DEPEND Atoms, please see the section 5 -manpage on ebuilds. <c>man 5 ebuilds</c>. -</note> - -</body> -</section> -</chapter> - -<chapter> -<title>Testing and deploying</title> -<section> -<title>ChangeLog</title> -<body> - -<p> -Whenever you update a (or write a new) ebuild, you must also update its (or -create a new) ChangeLog. The <path>skel.ChangeLog</path> contains a sample -ChangeLog that you can use as a basis. -</p> - -<p> -The purpose of the ChangeLog is to document <e>what</e> is being done, -<e>why</e> it is being done, and by <e>whom</e>. This allows both -developers and users to trace the changes made in an easy way. -</p> - -<p> -The ChangeLog is primarily targeted at users, so be sure to keep your -writing short, to the point, and avoid getting verbose about the internal -technical details. -</p> - -</body> -</section> - -<section> -<title>Storing your own ebuilds locally</title> -<body> - -<p> -In order to be able to test your ebuilds and let Portage know about them, you -must place those in a known directory. Portage will use the -<c>PORTDIR_OVERLAY</c> variable which you can define in -<path>/etc/make.conf</path>. You should set this variable to your directory -(e.g. <path>/usr/local/portage</path>). -</p> - -<p> -In that directory, you must use the same structure (and categories) as in -<path>/usr/portage</path>. -</p> - -<p> -Using this <c>PORTDIR_OVERLAY</c>, your ebuilds remain on your system, even -after an <c>emerge sync</c>, and they are still known to Portage. -</p> - -</body> -</section> - -<section> -<title>Useful testing tools</title> -<body> - -<p> -We have a few useful tools to help you with writing and maintaining your -ebuilds. -</p> - -<warn> -<c>lintool</c> is broken. Use repoman instead. -</warn> - -<table> -<tr> - <th>Tool</th> - <th>Package</th> - <th>Description</th> -</tr> -<tr> - <ti><c>repoman</c></ti> - <ti>sys-apps/portage</ti> - <ti> - Developer-only tool to assist with the CVS checkin procedure. It does a - lot of common QA and tries to make sure that files added to cvs will not - break the portage tree. - </ti> -</tr> -<tr> - <ti><c>ccache</c></ti> - <ti>dev-util/ccache</ti> - <ti> - Tool that keeps pre-processed files so that recompilation gets done - <e>much</e> faster. Be sure to add <c>ccache</c> to the <c>FEATURES</c> - variable in <path>/etc/make.conf</path>! - </ti> -</tr> -<tr> - <ti><c>sandboxshell</c></ti> - <ti>app-shells/sandboxshell</ti> - <ti> - Launch a shell that creates a sandbox environment. Useful for entering the - same environment that portage builds packages inside of and debugging - things by hand. - </ti> -</tr> -<tr> - <ti><c>echangelog</c></ti> - <ti>app-portage/gentoolkit</ti> - <ti>Can create a new ChangeLog or add an entry to an existing one.</ti> -</tr> -<tr> - <ti><c>gentool-bump-revision</c></ti> - <ti>app-portage/gentoolkit</ti> - <ti> - Developer-only tool that bumps the revision number, adds the new revision - to CVS, removed the old revision and updates the ChangeLog accordingly. - </ti> -</tr> -<tr> - <ti><c>qpkg</c></ti> - <ti>app-portage/gentoolkit</ti> - <ti>A tool to gather misc information about installed packages.</ti> -</tr> -</table> - -</body> -</section> -</chapter> -</guide> |