diff options
| author |   Mark Loeser <halcy0n@gentoo.org> | 2006-02-27 05:43:32 +0000 |
|---|---|---|
| committer | Mark Loeser <halcy0n@gentoo.org> | 2006-02-27 05:43:32 +0000 |
| commit | 274e7580177fc3e41d1bb7ca60ffd3a3eea1384f (patch) | |
| tree | c2f6cf92022a5fbd1e7416ba270fd897922a8161 /general-concepts | |
| parent | More goodies; change syntax highlighting mode within quotes for ebuilds. (diff) | |
| download | devmanual-274e7580177fc3e41d1bb7ca60ffd3a3eea1384f.tar.gz devmanual-274e7580177fc3e41d1bb7ca60ffd3a3eea1384f.tar.bz2 devmanual-274e7580177fc3e41d1bb7ca60ffd3a3eea1384f.zip | |
Add some more of general-concepts
git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@6 176d3534-300d-0410-8db8-84e73ed771c3
Diffstat (limited to 'general-concepts')
| -rw-r--r-- | general-concepts/config-protect/text.xml | 433 | ||||
| -rw-r--r-- | general-concepts/cvs-to-rsync/diagram.png | bin | 0 -> 32324 bytes | |||
| -rw-r--r-- | general-concepts/cvs-to-rsync/diagram.svg | 142 | ||||
| -rw-r--r-- | general-concepts/cvs-to-rsync/text.xml | 40 | ||||
| -rw-r--r-- | general-concepts/dependencies/text.xml | 396 | ||||
| -rw-r--r-- | general-concepts/digest-and-manifest/text.xml | 40 | ||||
| -rw-r--r-- | general-concepts/distributed-building/text.xml | 13 | ||||
| -rw-r--r-- | general-concepts/text.xml | 4 |
8 files changed, 648 insertions, 420 deletions
diff --git a/general-concepts/config-protect/text.xml b/general-concepts/config-protect/text.xml index 411613f..45b2976 100644 --- a/general-concepts/config-protect/text.xml +++ b/general-concepts/config-protect/text.xml @@ -5,433 +5,26 @@ <body> <p> -This page provides a <e>very</e> brief introduction to ebuild -writing. It does not attempt to cover many of the details or problems -that will be encountered by developers -- rather, it gives some -trivial examples which may be of use when trying to grasp the basic -idea of how ebuilds work. + Portage includes a system for configuration file protection which means ebuilds + don't have to worry about accidentally clobbering files in <c>/etc</c>. This is + known as 'protection', and it is controlled by the <c>CONFIG_PROTECT</c> and + <c>CONFIG_PROTECT_MASK</c> variables. </p> <p> -For proper coverage of all the ins and outs, see `Ebuild -Writing`_. The `General Concepts`_ chapter will also be of use. + Any directory which is listed in <c>CONFIG_PROTECT</c> (and any subdirectories + thereof), except for any which are listed in <c>CONFIG_PROTECT_MASK</c> (and + subdirectories) are automatically 'protected' by portage when copying an image + from <c>DESTDIR</c> to <c>ROOT</c>. Rather than installing protected files directly, + portage will install them as <c>._cfg0000_filename</c>. These can then be processed + by the <c>etc-update</c> or <c>dispatch-conf</c> files at the user's discretion. </p> <p> -Note that the examples used here, whilst based upon real tree ebuilds, -have had several parts chopped out, changed and simplified. + Packages must <b>not</b> attempt to override this system via <c>pkg_postinst</c> or + similar. If you need a file renamed, remove or changed in a particular way, you + should display a message informing the user. </p> </body> - -<section> -<title>First Ebuild</title> - -<body> -<p> -We'll start with an ebuild for the <e>Exuberant Ctags</e> utility, a source code -indexing tool. Here's a simplified <c>dev-util/ctags/ctags-5.5.4.ebuild</c> (you -can see real ebuilds in the main tree). -</p> - -<codesample lang="ebuild"> -# Copyright 1999-2005 Gentoo Foundation -# Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -DESCRIPTION="Exuberant ctags generates tags files for quick source navigation" -HOMEPAGE="http://ctags.sourceforge.net" -SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz" - -LICENSE="GPL-2" -SLOT="0" -KEYWORDS="~mips ~sparc ~x86" -IUSE="" - -src_compile() { - econf --with-posix-regex || die "econf failed" - emake || die "emake failed" -} - -src_install() { - make DESTDIR="${D}" install || die "install failed" - - dodoc FAQ NEWS README - dohtml EXTENDING.html ctags.html -} -</codesample> -</body> - -<subsection> -<title>Basic Format</title> - -<body> -<p> -As you can see, ebuilds are just <c>bash</c> scripts that are executed within a -special environment. -</p> - -<p> -At the top of the ebuild is a header block. This is present in all ebuilds. -</p> - -<p> -Ebuilds are indented using tabs, with each tab representing four places. See -`Ebuild File Format`_. -</p> -</body> -</subsection> - -<subsection> -<title>Information Variables</title> - -<body> -<p> -Next, there are a series of variables. These tell portage various things about -the ebuild and package in question. -</p> - -<p> -The <c>DESCRIPTION</c> variable is set to a <e>short</e> description -of the package and its purpose. -</p> - -<p> -The <c>HOMEPAGE</c> is a link to the package's homepage (remember to -include the <c>http://</c> part). -</p> - -<p> -The <c>LICENSE</c> is <c>GPL-2</c> (the GNU General Public License version 2). -</p> - -<p> -The <c>SRC_URI</c> tells Portage the address to use for downloading -the source tarball. Here, <c>mirror://sourceforge/</c> is a special -notation meaning "any of the Sourceforge mirrors". The -<c>${P}</c> is a read-only variable set by Portage which is the package's -name and version -- in this case, it would be <c>ctags-5.5.4</c>. -</p> - -<p> -The <c>SLOT</c> variable tells portage which slot this package installs to. If -you've not seen slots before, either just use <c>"0"</c> or read `Slotting`_. -</p> - -<p> -The <c>KEYWORDS</c> variable is set to archs upon which this ebuild has been -tested. We use <c>~</c> keywords for newly written ebuilds -- packages are not -committed straight to stable, even if they seem to work. See `Keywording`_ for -details. -</p> -</body> -</subsection> - -<subsection> -<title>Build Functions</title> - -<body> -<p> -Next, a function named <c>src_compile</c>. Portage will call this -function when it wants to <e>compile</e> the package. The <c>econf</c> -function is a wrapper for calling <c>./configure</c>, and <c>emake</c> -is a wrapper for <c>make</c>. In both cases, the common <c>|| die -"something went wrong"</c> idiom is used -- this is to -ensure that if for some reason an error occurs, portage will stop -rather than trying to continue with the install. -</p> - -<p> -The <c>src_install</c> function is called by portage when it wants -to <e>install</e> the package. A slight subtlety here -- rather than -installing straight to the live filesystem, we must install to a -special location which is given by the <c>${D}</c> variable (portage sets -this -- see `Install Destinations`_ and `Sandbox`_). Again, we check -for errors. -</p> - -<note> -The canonical install method is <c>make DESTDIR="${D}" -install</c>. This will work with any properly written standard -<c>Makefile</c>. If this gives sandbox errors, try <c>einstall</c> -instead. If this still fails, see `src_install`_ for how to do -manual installs. -</note> - -<p> -The <c>dodoc</c> and <c>dohtml</c> are helper functions for installing -files into the relevant part of <c>/usr/share/doc</c>. -</p> - -<p> -Ebuilds can define other functions (see `Ebuild Functions`_). In all cases, -portage provides a reasonable default implementation which quite often does the -'right thing'. There was no need to define a <c>src_unpack</c> function here, for -example -- this function is used to do any unpacking of tarballs or patching of -source files, but the default implementation does everything we need. -</p> -</body> -</subsection> - -</section> - -<section> -<title>Ebuild with Dependencies</title> - -<body> -<p> -In the ctags example, we didn't tell portage about any dependencies. As it -happens, that's ok, because ctags only needs a basic toolchain to compile and -run (see `Implicit System Dependency`_ for why we don't need to depend upon -those explicitly). However, life is rarely that simple. -</p> - -<p> -Here's <c>app-misc/detox/detox-1.1.1.ebuild</c>: -</p> - -<codesample lang="ebuild"> -# Copyright 1999-2005 Gentoo Foundation -# Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -DESCRIPTION="detox safely removes spaces and strange characters from filenames" -HOMEPAGE="http://detox.sourceforge.net/" -SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2" - -LICENSE="BSD" -SLOT="0" -KEYWORDS="~hppa mips sparc x86" -IUSE="" - -DEPEND="dev-libs/popt - sys-devel/flex - sys-devel/bison" -RDEPEND="dev-libs/popt" - -src_compile() { - econf --with-popt || die "econf failed" - emake || die "emake failed" -} - -src_install() { - make DESTDIR="${D}" install || die "install failed" - dodoc README CHANGES -} -</codesample> - -<p> -Again, you can see the ebuild header and the various informational variables. In -<c>SRC_URI</c>, <c>${PN}</c> is used to get the package's -name <e>without</e> the version suffix (there are more of these -variables -- see `Predefined Read-Only Variables`_). -</p> - -<p> -Again, we define <c>src_compile</c> and <c>src_install</c> functions. -</p> - -<p> -The <c>DEPEND</c> and <c>RDEPEND</c> variables are how portage determines which -packages are needed to build and run the package. The <c>DEPEND</c> variable lists -compile-time dependencies, and the <c>RDEPEND</c> lists runtime dependencies. See -`Dependencies`_ for some more complex examples. -</p> - -</body> -</section> - -<section> -<title>Ebuild with Patches</title> - -<body> -<p> -Often we need to apply patches. This is done in the <c>src_unpack</c> function -using the <c>epatch</c> helper function. To use <c>epatch</c> one must first tell -portage that the <c>eutils</c> eclass (an eclass is like a library) is required -- -this is done via <c>inherit eutils</c> at the top of the ebuild. Here's -<c>app-misc/detox/detox-1.1.0.ebuild</c>: -</p> - -<codesample lang="ebuild"> -# Copyright 1999-2005 Gentoo Foundation -# Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -inherit eutils - -DESCRIPTION="detox safely removes spaces and strange characters from filenames" -HOMEPAGE="http://detox.sourceforge.net/" -SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2" - -LICENSE="BSD" -SLOT="0" -KEYWORDS="~hppa ~mips ~sparc ~x86" -IUSE="" - -DEPEND="dev-libs/popt - sys-devel/flex - sys-devel/bison" -RDEPEND="dev-libs/popt" - -src_unpack() { - unpack ${A} - cd "${S}" - - epatch "${FILESDIR}"/${P}-destdir.patch - epatch "${FILESDIR}"/${P}-parallel_build.patch -} - -src_compile() { - econf --with-popt || die "econf failed" - emake || die "emake failed" -} - -src_install() { - make DESTDIR="${D}" install || die "install failed" - dodoc README CHANGES -} -</codesample> - -<p> -Note the <c>${FILESDIR}/${P}-destdir.patch</c> -- this refers to -<c>detox-1.1.0-destdir.patch</c>, which lives in the <c>files/</c> -subdirectory in the portage tree. Larger patch files must go on the -mirrors rather than in <c>files/</c> -- see `Basic epatch Usage`_. -</p> - -</body> -</section> - -<section> -<title>Ebuild with USE Flags</title> - -<body> -<p> -Now for some <c>USE</c> flags. Here's <c>dev-libs/libiconv/libiconv-1.9.2.ebuild</c>, a -replacement iconv for <c>libc</c> implementations which don't have their own. -</p> - -<codesample lang="ebuild"> -# Copyright 1999-2005 Gentoo Foundation -# Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -DESCRIPTION="GNU charset conversion library for libc which doesn't implement it" -SRC_URI="ftp://ftp.gnu.org/pub/gnu/libiconv/${P}.tar.gz" -HOMEPAGE="http://www.gnu.org/software/libiconv/" - -SLOT="0" -LICENSE="LGPL-2.1" -KEYWORDS="~amd64 ~ppc ~sparc ~x86" -IUSE="nls" - -DEPEND="virtual/libc - !sys-libs/glibc" - -src_compile() { - econf $(use_enable nls) || die "econf failed" - emake || die -} - -src_install() { - make DESTDIR="${D}" install || die "install failed" -} -</codesample> - -<p> -Note the <c>IUSE</c> variable. This lists all (non-special) use flags that are used -by the ebuild. This is used for the <c>emerge -pv</c> output, amongst other things. -</p> - -<p> -The package's <c>./configure</c> script takes the usual <c>--enable-nls</c> or -<c>--disable-nls</c> argument. We use the <c>use_enable</c> utility function to -generate this automatically (see `Query Functions Reference`_). -</p> - -<p> -Another more complicated example, this time based upon -<c>mail-client/sylpheed/sylpheed-1.0.4.ebuild</c>: -</p> - -<codesample lang="ebuild"> -# Copyright 1999-2005 Gentoo Foundation -# Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -inherit eutils - -DESCRIPTION="A lightweight email client and newsreader" -HOMEPAGE="http://sylpheed.good-day.net/" -SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2" - -LICENSE="GPL-2" -KEYWORDS="alpha amd64 hppa ia64 ppc ppc64 sparc x86" -SLOT="0" - -IUSE="crypt gnome imlib ipv6 ldap nls pda ssl xface" - -DEPEND="=x11-libs/gtk+-1.2* - nls? ( >=sys-devel/gettext-0.12.1 ) - crypt? ( >=app-crypt/gpgme-0.4.5 ) - gnome? ( media-libs/gdk-pixbuf ) - imlib? ( media-libs/imlib ) - ldap? ( >=net-nds/openldap-2.0.11 ) - pda? ( app-pda/jpilot ) - ssl? ( dev-libs/openssl ) - xface? ( >=media-libs/compface-1.4 )" -RDEPEND="${DEPEND} - app-misc/mime-types - x11-misc/shared-mime-info" - -src_unpack() { - unpack ${A} - cd "${S}" - - epatch "${FILESDIR}"/${PN}-namespace.diff - epatch "${FILESDIR}"/${PN}-procmime.diff -} - -src_compile() { - - econf \ - $(use_enable nls) \ - $(use_enable ssl) \ - $(use_enable crypt gpgme) \ - $(use_enable pda jpilot) \ - $(use_enable ldap) \ - $(use_enable ipv6) \ - $(use_enable imlib) \ - $(use_enable gnome gdk-pixbuf) \ - $(use_enable xface compface) \ - || die - - emake || die -} - -src_install() { - einstall || die "einstall failed" - dodir /usr/share/pixmaps - insinto /usr/share/pixmaps - doins *.png - - if use gnome ; then - dodir /usr/share/gnome/apps/Internet - insinto /usr/share/gnome/apps/Internet - doins sylpheed.desktop - fi - - dodoc [A-Z][A-Z]* ChangeLog* -} -</codesample> - -<p> -Note the optional dependencies. Some of the <c>use_enable</c> lines use the -two-argument version -- this is helpful when the USE flag name does not exactly -match the <c>./configure</c> argument. -</p> -</body> -</section> - </chapter> </guide> diff --git a/general-concepts/cvs-to-rsync/diagram.png b/general-concepts/cvs-to-rsync/diagram.png Binary files differnew file mode 100644 index 0000000..ade7a52 --- /dev/null +++ b/general-concepts/cvs-to-rsync/diagram.png diff --git a/general-concepts/cvs-to-rsync/diagram.svg b/general-concepts/cvs-to-rsync/diagram.svg new file mode 100644 index 0000000..bc7e308 --- /dev/null +++ b/general-concepts/cvs-to-rsync/diagram.svg @@ -0,0 +1,142 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg viewBox="0 0 700 250" xmlns="http://www.w3.org/2000/svg" version="1.1"> + <desc>CVS to RSYNC Propagation</desc> + + <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" /> + + <rect x="10" y="110" width="80" height="30" + fill="#ffcccc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="50" y="130">Developers</text> + + <line x1="90" y1="125" x2="130" y2="125" stroke-width="2" stroke="black" /> + <line x1="130" y1="125" x2="122" y2="120" stroke-width="2" stroke="black" /> + <line x1="130" y1="125" x2="122" y2="130" stroke-width="2" stroke="black" /> + + + <rect x="10" y="60" width="80" height="30" + fill="#ffcccc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="50" y="80">Developers</text> + + <path d="M 90 75 Q 110 75 110 100 Q 110 130 130 125" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="10" y="160" width="80" height="30" + fill="#ffcccc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="50" y="180">Developers</text> + + <path d="M 90 175 Q 110 175 110 150 Q 110 120 130 125" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="130" y="110" width="80" height="30" + fill="#ffffff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="170" y="130">CVS</text> + + <line x1="210" y1="125" x2="250" y2="125" stroke-width="2" stroke="black" /> + <line x1="250" y1="125" x2="242" y2="120" stroke-width="2" stroke="black" /> + <line x1="250" y1="125" x2="242" y2="130" stroke-width="2" stroke="black" /> + + + + <rect x="250" y="110" width="80" height="30" + fill="#ffffff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="290" y="123">Staging</text> + <text style="text-anchor: middle;" x="290" y="135">Box</text> + + <line x1="330" y1="125" x2="370" y2="125" stroke-width="2" stroke="black" /> + <line x1="370" y1="125" x2="362" y2="120" stroke-width="2" stroke="black" /> + <line x1="370" y1="125" x2="362" y2="130" stroke-width="2" stroke="black" /> + + + + <rect x="370" y="110" width="80" height="30" + fill="#ffffff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="410" y="130">rsync1</text> + + + + <line x1="490" y1="75" x2="482" y2="70" stroke-width="2" stroke="black" /> + <line x1="490" y1="75" x2="482" y2="80" stroke-width="2" stroke="black" /> + <path d="M 450 125 Q 470 125 470 100 Q 470 70 490 75" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="490" y="60" width="80" height="30" + fill="#ccffcc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="530" y="80">Public rsync</text> + + + + <line x1="450" y1="125" x2="490" y2="125" stroke-width="2" stroke="black" /> + <line x1="490" y1="125" x2="482" y2="120" stroke-width="2" stroke="black" /> + <line x1="490" y1="125" x2="482" y2="130" stroke-width="2" stroke="black" /> + + <rect x="490" y="110" width="80" height="30" + fill="#ccffcc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="530" y="130">Public rsync</text> + + + + <line x1="490" y1="175" x2="482" y2="170" stroke-width="2" stroke="black" /> + <line x1="490" y1="175" x2="482" y2="180" stroke-width="2" stroke="black" /> + <path d="M 450 125 Q 470 125 470 150 Q 470 180 490 175" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="490" y="160" width="80" height="30" + fill="#ccffcc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="530" y="180">Public rsync</text> + + + + <line x1="610" y1="25" x2="602" y2="20" stroke-width="2" stroke="black" /> + <line x1="610" y1="25" x2="602" y2="30" stroke-width="2" stroke="black" /> + <path d="M 570 75 Q 590 75 590 50 Q 590 20 610 25" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="610" y="10" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="650" y="30">Users</text> + + + + <line x1="570" y1="75" x2="610" y2="75" stroke-width="2" stroke="black" /> + <line x1="610" y1="75" x2="602" y2="70" stroke-width="2" stroke="black" /> + <line x1="610" y1="75" x2="602" y2="80" stroke-width="2" stroke="black" /> + + <rect x="610" y="60" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="650" y="80">Users</text> + + + + <line x1="570" y1="125" x2="610" y2="125" stroke-width="2" stroke="black" /> + <line x1="610" y1="125" x2="602" y2="120" stroke-width="2" stroke="black" /> + <line x1="610" y1="125" x2="602" y2="130" stroke-width="2" stroke="black" /> + + <rect x="610" y="110" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="650" y="130">Users</text> + + + <line x1="570" y1="175" x2="610" y2="175" stroke-width="2" stroke="black" /> + <line x1="610" y1="175" x2="602" y2="170" stroke-width="2" stroke="black" /> + <line x1="610" y1="175" x2="602" y2="180" stroke-width="2" stroke="black" /> + + <rect x="610" y="160" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="650" y="180">Users</text> + + + + <line x1="610" y1="225" x2="602" y2="220" stroke-width="2" stroke="black" /> + <line x1="610" y1="225" x2="602" y2="230" stroke-width="2" stroke="black" /> + <path d="M 570 175 Q 590 175 590 200 Q 590 230 610 225" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="610" y="210" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="650" y="230">Users</text> + +</svg> + +<!-- vim: set ft=xml sw=4 sts=4 et : --> diff --git a/general-concepts/cvs-to-rsync/text.xml b/general-concepts/cvs-to-rsync/text.xml new file mode 100644 index 0000000..9a379e6 --- /dev/null +++ b/general-concepts/cvs-to-rsync/text.xml @@ -0,0 +1,40 @@ +<?xml version="1.0"?> +<guide self="general-concepts/cvs-to-rsync/"> +<chapter> +<title>CVS to RSYNC</title> + +<body> + +<p> + Changes made to the tree are propagated to the users in stages: +</p> + +<ul> + <li> + Developer commits to CVS. + </li> + <li> + Staging box syncs from CVS and generates the metadata cache. + </li> + <li> + <c>rsync1</c> syncs from the staging box. + </li> + <li> + Public rsync servers sync from <c>rsync1</c>. + </li> + <li> + Users sync from the public rsync servers. + </li> +</ul> + +<figure short="CVS to RSYNC Propagation" link="diagram.png"> + Diagram showing CVS to RSYNC Propagation +</figure> + +<p> + The <c>emerge-websync</c> snapshot is made daily from the staging box. +</p> + +</body> +</chapter> +</guide> diff --git a/general-concepts/dependencies/text.xml b/general-concepts/dependencies/text.xml new file mode 100644 index 0000000..b6feeb4 --- /dev/null +++ b/general-concepts/dependencies/text.xml @@ -0,0 +1,396 @@ +<?xml version="1.0"?> +<guide self="general-concepts/dependencies/"> +<chapter> +<title>Dependencies</title> + +<body> + +<p> + Automatic dependency resolution is one of the most useful features provided by + <c>emerge</c>. +</p> + +<section> +<title>Build Dependencies</title> +<body> + +<p> +The <c>DEPEND</c> ebuild variable should specify any dependencies which are +required to unpack, patch, compile or install the package (but see +`Implicit System Dependency`_ for exemptions). +</p> + +</body> +</section> + +<section> +<title>Runtime Dependencies</title> +<body> + +<p> +The <c>RDEPEND</c> ebuild variable should specify any dependencies which are +required at runtime. This includes libraries (when dynamically linked), any data +packages and (for interpreted languages) the relevant interpreter. If this +variable is not specified, it defaults to the value of <c>DEPEND</c>. +</p> + +<p> +Note that when installing from a binary package, only <c>RDEPEND</c> will be +checked. It is therefore necessary to include items even if they are also listed +in <c>DEPEND</c>. +</p> + +<p> +Items which are in <c>RDEPEND</c> but not <c>DEPEND</c> could <i>in theory</i> be merged +<i>after</i> the target package. Portage does not currently do this. +</p> + +</body> +</section> + +<section> +<title>Post-Merge Dependencies</title> +<body> + +<p> +The <c>PDEPEND</c> variable specifies dependencies which must be merged <i>after</i> the +package. This is sometimes used for plugins which have a dependency upon the +package being merged. Generally <c>PDEPEND</c> should be avoided in favour of +<c>RDEPEND</c> except where this will create circular dependency chains. +</p> + +</body> +</section> + +<section> +<title>Implicit System Dependency</title> +<body> + +<p> +All packages have an implicit compile-time and runtime dependency upon the +entire <c>system</c> target. It is therefore not necessary, nor advisable, to +specify dependencies upon <c>gcc</c>, <c>libc</c> and so on, except where specific +versions or packages (for example, <c>glibc</c> over <c>uclibc</c>) are required. +</p> + +<p> +However, packages which are included in the <c>system</c> target, or are +dependencies of <c>system</c> target packages, should generally include a complete +dependency list (excluding bootstrap packages). This makes <c>emerge -e system</c> +possible when installing from a stage 1 or stage 2 tarball. +</p> + +</body> +</section> + +<section> +<title>Basic Dependency Syntax</title> +<body> + +<p> +A basic <c>*DEPEND</c> specification might look like the following: +</p> + +<codesample lang="ebuild"> +DEPEND="dev-lang/ruby + dev-ruby/ruby-gtk2 + dev-ruby/mysql-ruby" +</codesample> + +<p> +Each atom is the full category and name of a package. Atoms are separated by +arbitrary whitespace -- convention is to specify one atom per line for +readability purposes. When specifying names, the category part should be treated +as mandatory. +</p> + +</body> +</section> + +<section> +<title>Version Dependencies</title> +<body> + +<p> +Sometimes a particular version of a package is needed. Where this is known, it +should be specified. A simple example: +</p> + +<codesample lang="ebuild"> +DEPEND=">=dev-libs/openssl-0.9.7d" +</codesample> + +<p> +This states that at least version 0.9.7d of <c>openssl</c> is required. +</p> + +<subsection> +<title>Version Specifiers</title> +<body> + +<p> +Available version specifiers are: +</p> + +<p> +<table> + <tr> + <th>Specifier</th> + <th>Meaning</th> + </tr> + <tr> + <ti><c>>=app-misc/foo-1.23</c></ti> + <ti>Version 1.23 or later is required.</ti> + </tr> + <tr> + <ti><c>>app-misc/foo-1.23</c></ti> + <ti>A version strictly later than 1.23 is required.</ti> + </tr> + <tr> + <ti><c>~app-misc/foo-1.23</c></ti> + <ti>Version 1.23 (or any <c>1.23-r*</c>) is required.</ti> + </tr> + <tr> + <ti><c>=app-misc/foo-1.23</c></ti> + <ti> + Exactly version 1.23 is required. If at all possible, + use the <c>~</c> form to simplify revision bumps. + </ti> + </tr> + <tr> + <ti><c><=app-misc/foo-1.23</c></ti> + <ti>Version 1.23 or older is required.</ti> + </tr> + <tr> + <ti><c><app-misc/foo-1.23</c></ti> + <ti>A version strictly before 1.23 is required.</ti> + </tr> +</table> +</p> + +</body> +</subsection> + +<subsection> +<title>Ranged Dependencies</title> +<body> + +<p> +To specify "version 2.x (not 1.x or 3.x)" of a package, it is necessary to use +the asterix postfix. This is most commonly seen in situations like: +</p> + +<codesample lang="ebuild"> +DEPEND="gtk2? ( >=x11-libs/gtk+-2.4 ) + !gtk2? ( =x11-libs/gtk+-1.2* )" +</codesample> + +<p> +Note that the equals sign is mandatory, and that there is no dot before the +asterisk. +</p> + +</body> +</subsection> + +<subsection> +<title>Blockers</title> +<body> + +<p> +Sometimes two packages cannot be installed in parallel. This is handled by +blockers. A blocker is specified as follows: +</p> + +<codesample lang="ebuild"> +RDEPEND="!app-misc/foo" +</codesample> + +<p> +Note that blockers are usually <i>runtime</i> rather than buildtime. +</p> + +<p> +Specific versions can also be blocked: +</p> + +<codesample lang="ebuild"> +RDEPEND="!<app-misc/foo-1.3" +</codesample> + +<p> +Blockers can be optional based upon USE flags as per normal dependencies. +</p> + +</body> +</subsection> + +</body> +</section> + +<section> +<title>SLOT Dependencies</title> +<body> + +<p> +It is not currently possible to depend upon a package in a particular <c>SLOT</c>. +This is a shame. +</p> + +</body> +</section> + +<section> +<title>USE-Conditional Dependencies</title> +<body> + +<p> +To depend upon a certain package if and only if a given <c>USE</c> flag is set: +</p> + +<codesample language="ebuild"> +DEPEND="perl? ( dev-lang/perl ) + ruby? ( >=dev-lang/ruby-1.8 ) + python? ( dev-lang/python )" +</codesample> + +<p> +It is also possible to depend upon a certain package if a given <c>USE</c> flag is +<i>not</i> set: +</p> + +<codesample language="ebuild"> +RDEPEND="!crypt? ( net-misc/netkit-rsh )" +</codesample> + +<p> +This should <b>not</b> be used for disabling a certain <c>USE</c> flag on a given +architecture. In order to do this, the architecture should add the <c>USE</c> +flag to their <c>use.mask</c> file in the <c>profiles/default-linux/arch</c> +directory of the Portage tree. +</p> + +<p> +This can be nested: +</p> + +<codesample language="ebuild"> +DEPEND="gtk? ( + gtk2? ( >=x11-libs/gtk+-2.4 ) + !gtk2? ( =x11-libs/gtk+-1.2* ) ) + !gtk? ( sys-libs/ncurses )" +</codesample> + +</body> +</section> + +<section> +<title>Virtual Dependencies</title> +<body> + +<p> +To depend upon a virtual package, use <c>virtual/whatever</c> as the atom. +</p> + +<p> +Currently, you must not use any kind of version specification with virtuals -- +see `GLEP 37`_ for details and a proposed solution. +</p> + +</body> +</section> + +<section> +<title> +Any of Many Dependencies +</title> +<body> + +<p> +To depend on either <c>foo</c> or <c>bar</c>: +</p> + +<codesample lang="ebuild"> +DEPEND="|| ( app-misc/foo app-misc/bar )" +</codesample> + +<p> +To depend on either <c>foo</c> or <c>bar</c> if the <c>baz</c> <c>USE</c> flag is set: +</p> + +<codesample lang="ebuild"> +DEPEND="baz? ( || ( app-misc/foo app-misc/bar ) )" +</codesample> + +<subsection> +<title>Any of Many Versus USE</title> +<body> + +<p> +Say <c>fnord</c> can be built against either <c>foo</c> or <c>bar</c>. Then a USE flag is +not necessary if and only if all of the following hold: +</p> + +<ul> + <li> + <c>fnord</c> is merged on a system which has <c>foo</c> and not <c>bar</c> installed. + <c>foo</c> is then unmerged, and <c>bar</c> is installed. <c>fnord</c> must continue to + work correctly. + </li> + <li> + A binary package of <c>fnord</c> made on a system with <c>foo</c> and not <c>bar</c> + can be taken and installed on a system with <c>bar</c> and not <c>foo</c>. + </li> +</ul> + +</body> +</subsection> + +</body> +</section> + +<section> +<title>Built with USE Dependencies</title> +<body> + +<p> +Currently it is impossible to depend upon "<c>foo</c> built with the <c>bar</c> +<c>USE</c> flag enabled". This is a nuisance.</p> + +</body> +</section> + +<section> +<title>Legacy Inverse USE-Conditional Dependency Syntax</title> +<body> + +<p> +When looking through old ebuild versions or the occasional user-submitted +ebuild, you may see a <c>*DEPEND</c> atom in the form: +</p> + +<codesample lang="ebuild"> +DEPEND="use-flag? ( app-misc/foo ) : ( app-misc/bar )" +</codesample> + +<p> +<b>This syntax is no longer permitted</b>. It is exactly equivalent to the +following, which should be used instead: +</p> + +<codesample lang="ebuild"> +DEPEND="use-flag? ( app-misc/foo ) + !use-flag? ( app-misc/bar )" +</codesample> + +<p> +It is useful to recognise the legacy syntax and to know that it is no longer +valid. +</p> + +</body> +</section> + +</body> +</chapter> +</guide> diff --git a/general-concepts/digest-and-manifest/text.xml b/general-concepts/digest-and-manifest/text.xml new file mode 100644 index 0000000..abcce82 --- /dev/null +++ b/general-concepts/digest-and-manifest/text.xml @@ -0,0 +1,40 @@ +<?xml version="1.0"?> +<guide self="general-concepts/digest-and-manifest/"> +<chapter> +<title>Digest and Manifest</title> + +<body> +<p> +In the tree, every package has a <c>Manifest</c> file. This file lives in the same +directory as the ebuilds for the package. The <c>Manifest</c> file contains digests +(currently MD5) and file size data for every file in the directory and any +subdirectories. This is used to verify integrity. +</p> + +<p> +The <c>Manifest</c> may be digitally signed. +</p> + +<p> +Inside the <c>files/</c> subdirectory, there is exactly one <c>digest</c> file per +ebuild. Each file contains a digest (currently MD5) and a file size for every +file listed in <c>SRC_URI</c> for the ebuild. This is used to verify downloads and +to catch any changed source files. +</p> + +<p> +When generating digests, it is necessary to include <i>all</i> of the files which +<i>could</i> be downloaded (<c>SRC_URI</c> can contain conditional entries). Portage +will do this automatically if <c>cvs</c> is included in <c>FEATURES</c>. +</p> + +<p> +To generate digests and <c>Manifest</c>, use <c>ebuild foo.ebuild digest</c>. When +committing, the <c>Manifest</c> file must be regenerated to handle any CVS keyword +expansion changes -- <c>repoman</c> will do this automatically. +</p> + +</body> + +</chapter> +</guide> diff --git a/general-concepts/distributed-building/text.xml b/general-concepts/distributed-building/text.xml new file mode 100644 index 0000000..3803327 --- /dev/null +++ b/general-concepts/distributed-building/text.xml @@ -0,0 +1,13 @@ +<?xml version="1.0"?> +<guide self="general-concepts/distributed-building/"> +<chapter> +<title>Distributed and Parallel Building</title> + +<body> + +<todo>write this</todo> + +</body> +</chapter> +</guide> + diff --git a/general-concepts/text.xml b/general-concepts/text.xml index 02a7c09..178b327 100644 --- a/general-concepts/text.xml +++ b/general-concepts/text.xml @@ -21,6 +21,10 @@ writing ebuilds or working with the portage tree. <include href="autotools/"/> <include href="config-protect/"/> +<include href="cvs-to-rsync/"/> +<include href="dependencies/"/> +<include href="digest-and-manifest/"/> +<include href="distributed-building/"/> <include href="licenses/"/> <include href="linguas/"/> <include href="mirrors/"/> |
