aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTim Yamin <plasmaroo@gentoo.org>2006-03-03 21:21:51 +0000
committerTim Yamin <plasmaroo@gentoo.org>2006-03-03 21:21:51 +0000
commit7ff328709a028aee2fe8e29422ac9d4d9ce9dd71 (patch)
treee11c22f738f112dd7f15f635cec149f5f0564535 /ebuild-writing
parentAdd <uri/> tag. (diff)
downloaddevmanual-7ff328709a028aee2fe8e29422ac9d4d9ce9dd71.tar.gz
devmanual-7ff328709a028aee2fe8e29422ac9d4d9ce9dd71.tar.bz2
devmanual-7ff328709a028aee2fe8e29422ac9d4d9ce9dd71.zip
Complete src_unpack.
git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@13 176d3534-300d-0410-8db8-84e73ed771c3
Diffstat (limited to 'ebuild-writing')
-rw-r--r--ebuild-writing/ebuild-functions/src_unpack/epatch/text.xml13
-rw-r--r--ebuild-writing/ebuild-functions/src_unpack/text.xml14
-rw-r--r--ebuild-writing/ebuild-functions/text.xml14
-rw-r--r--ebuild-writing/file-format/text.xml9
-rw-r--r--ebuild-writing/functions/diagram.svg71
-rw-r--r--ebuild-writing/functions/src_unpack/autopackage/text.xml42
-rw-r--r--ebuild-writing/functions/src_unpack/cvs-sources/text.xml182
-rw-r--r--ebuild-writing/functions/src_unpack/deb-sources/text.xml12
-rw-r--r--ebuild-writing/functions/src_unpack/epatch/text.xml148
-rw-r--r--ebuild-writing/functions/src_unpack/other-formats/text.xml53
-rw-r--r--ebuild-writing/functions/src_unpack/rpm-sources/text.xml123
-rw-r--r--ebuild-writing/functions/src_unpack/svn-sources/text.xml109
-rw-r--r--ebuild-writing/functions/src_unpack/text.xml100
-rw-r--r--ebuild-writing/functions/src_unpack/tla-sources/text.xml12
-rw-r--r--ebuild-writing/functions/text.xml35
-rw-r--r--ebuild-writing/messages/text.xml2
-rw-r--r--ebuild-writing/text.xml9
-rw-r--r--ebuild-writing/using-eclasses/text.xml6
18 files changed, 901 insertions, 53 deletions
diff --git a/ebuild-writing/ebuild-functions/src_unpack/epatch/text.xml b/ebuild-writing/ebuild-functions/src_unpack/epatch/text.xml
deleted file mode 100644
index cee1465..0000000
--- a/ebuild-writing/ebuild-functions/src_unpack/epatch/text.xml
+++ /dev/null
@@ -1,13 +0,0 @@
-<?xml version="1.0"?>
-<guide self="ebuild-writing/ebuild-functions/src_unpack/epatch/">
-<chapter>
-<title>Patching with epatch</title>
-
-<body>
-<p>
-This section covers some general concepts with which you should be familiar when
-writing ebuilds or working with the portage tree.
-</p>
-</body>
-</chapter>
-</guide>
diff --git a/ebuild-writing/ebuild-functions/src_unpack/text.xml b/ebuild-writing/ebuild-functions/src_unpack/text.xml
deleted file mode 100644
index 966e7d5..0000000
--- a/ebuild-writing/ebuild-functions/src_unpack/text.xml
+++ /dev/null
@@ -1,14 +0,0 @@
-<?xml version="1.0"?>
-<guide self="ebuild-writing/ebuild-functions/src_unpack/">
-<chapter>
-<title>src_unpack</title>
-
-<body>
-<p>
-This section covers some general concepts with which you should be familiar when
-writing ebuilds or working with the portage tree.
-</p>
-</body>
-</chapter>
-<include href="epatch/"/>
-</guide>
diff --git a/ebuild-writing/ebuild-functions/text.xml b/ebuild-writing/ebuild-functions/text.xml
deleted file mode 100644
index c076315..0000000
--- a/ebuild-writing/ebuild-functions/text.xml
+++ /dev/null
@@ -1,14 +0,0 @@
-<?xml version="1.0"?>
-<guide self="ebuild-writing/ebuild-functions/">
-<chapter>
-<title>Ebuild Functions</title>
-
-<body>
-<p>
-This section covers some general concepts with which you should be familiar when
-writing ebuilds or working with the portage tree.
-</p>
-</body>
-</chapter>
-<include href="src_unpack/"/>
-</guide>
diff --git a/ebuild-writing/file-format/text.xml b/ebuild-writing/file-format/text.xml
index 2a439da..8fc0db6 100644
--- a/ebuild-writing/file-format/text.xml
+++ b/ebuild-writing/file-format/text.xml
@@ -25,15 +25,16 @@ discouraged, but technically valid.
</p>
<note>
-This is the same as `IEEE1003.1-2004-3.276`_, with the addition of the plus
-character to keep GTK+ and friends happy.
+This is the same as <uri link="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_276">
+IEEE1003.1-2004-3.276</uri>, with the addition of the plus character to keep GTK+
+and friends happy.
</note>
<p>
The version section is more complicated. It consists of one or more numbers
separated by full stop (or period, or dot, or decimal point) characters (eg
<c>1.2.3</c>, <c>20050108</c>). The final number may have a single letter following it
-(e.g. <c>1.2b</c>). This letter should not be used to indicate 'beta' status --
+(e.g. <c>1.2b</c>). This letter should not be used to indicate 'beta' status <d/>
portage treats <c>1.2b</c> as being a later version than <c>1.2</c> or <c>1.2a</c>.
</p>
@@ -80,7 +81,7 @@ Any of these suffixes may be followed by a non-zero positive integer.
<p>
Finally, version may have a Gentoo revision number in the form <c>-r1</c>. The initial
Gentoo version should have no revision suffix, the first revision should be
-<c>-r1</c>, the second <c>-r2</c> and so on. See `Ebuild Revisions`_.
+<c>-r1</c>, the second <c>-r2</c> and so on. See <uri link="::general-concepts/ebuild-revisions"/>.
</p>
<p>
diff --git a/ebuild-writing/functions/diagram.svg b/ebuild-writing/functions/diagram.svg
new file mode 100644
index 0000000..5834bec
--- /dev/null
+++ b/ebuild-writing/functions/diagram.svg
@@ -0,0 +1,71 @@
+<?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 100 830 80" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <desc>Ebuild Function Order</desc>
+ <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" />
+
+ <rect x="10" y="110" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="50" y="130">pkg_setup</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="130" y="110" width="80" height="30"
+ fill="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="170" y="130">src_unpack</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="130">src_compile</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" />
+
+ <path d="M 330 125 Q 350 125 350 137 Q 350 150 370 150
+ L 450 150 Q 470 150 470 137 Q 470 125 490 125"
+ stroke-width="2" stroke="black" fill="none" />
+
+ <rect x="370" y="110" width="80" height="30"
+ fill="#ccffcc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="410" y="130">src_test</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="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="530" y="130">src_install</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">pkg_preinst</text>
+
+ <line x1="690" y1="125" x2="730" y2="125" stroke-width="2" stroke="black" />
+ <line x1="730" y1="125" x2="722" y2="120" stroke-width="2" stroke="black" />
+ <line x1="730" y1="125" x2="722" y2="130" stroke-width="2" stroke="black" />
+
+ <rect x="730" y="110" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="770" y="130">pkg_postinst</text>
+
+ <path d="M 90 125 Q 110 125 110 142 Q 110 160 130 160
+ L 570 160 Q 590 160 590 142 Q 590 125 610 125"
+ stroke-width="2" stroke="black" fill="none" />
+
+</svg>
+
+<!-- vim: set ft=xml sw=4 sts=4 et : -->
+
diff --git a/ebuild-writing/functions/src_unpack/autopackage/text.xml b/ebuild-writing/functions/src_unpack/autopackage/text.xml
new file mode 100644
index 0000000..dfde1c5
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/autopackage/text.xml
@@ -0,0 +1,42 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_unpack/autopackage/">
+<chapter>
+<title>Autopackage</title>
+
+<body>
+<p>
+If a package is only supplied in autopackage format, you must not add
+it to the tree. If a package is supplied in autopackage format and
+some other sane standard format (for example a source tarball), use
+the other format only.
+</p>
+
+<p>
+Autopackage packages are totally unsuitable for Gentoo systems for a
+large number of reasons:
+</p>
+
+<ul>
+ <li>
+ To even unpack the package, you must run arbitrary code supplied by an untrusted source.
+ </li>
+ <li>They install directly to the live filesystem.</li>
+ <li>Their intrinsic dependency resolver is broken.</li>
+ <li>They do not support the filesystem layout used by Gentoo.</li>
+ <li>They do not support configuration protection.</li>
+ <li>They can clobber arbitrary files on uninstall.</li>
+ <li>The linking mechanism used is insufficiently flexible.</li>
+ <li>
+ The entire format is completely unportable and highly tied to x86
+ Linux systems.
+ </li>
+</ul>
+
+<p>
+Upstream are aware of these issues and have no desire to fix them <d/>
+indeed, they pass off some of their most broken behaviour as
+'features'.
+</p>
+</body>
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_unpack/cvs-sources/text.xml b/ebuild-writing/functions/src_unpack/cvs-sources/text.xml
new file mode 100644
index 0000000..26b770e
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/cvs-sources/text.xml
@@ -0,0 +1,182 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_unpack/cvs-sources/">
+<chapter>
+<title>CVS Sources</title>
+
+<body>
+<p>
+Rather than working with a source tarball, it is possible to use
+upstream's CVS server directly. This can be useful when there is a
+need to test unreleased snapshots on a regular basis.
+</p>
+</body>
+
+<section>
+<title>Disadvantages of CVS Sources</title>
+<body>
+
+<p>
+Note that CVS ebuilds should <b>not</b> generally be added to the tree
+(except under <c>package.mask</c>) for the following reasons:
+</p>
+
+<ul>
+ <li>
+ Upstream CVS servers tend to be far less reliable than our mirroring
+ system.
+ </li>
+ <li>
+ CVS ebuilds create a very heavy server load <d/> not only is CVS not
+ mirrored, but allowing a CVS checkout is considerably more work for
+ a server than simply serving up a file via HTTP or FTP.
+ </li>
+ <li>
+ Many users who are behind strict firewalls cannot use CVS.
+ </li>
+</ul>
+
+<p>
+It is safer to make a snapshot instead. For example, vim snapshots are made using:
+</p>
+
+<pre>
+$ cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vim export -r HEAD vim
+</pre>
+</body>
+</section>
+
+<section>
+<title>Disadvantages of CVS Live Sources</title>
+<body>
+
+<p>
+CVS ebuilds which work against CVS <c>HEAD</c> rather than a specific
+date or revision are even worse candidates for tree inclusion:
+</p>
+
+<ul>
+ <li>
+ You can never be sure whether upstream's CVS will actually
+ build at any given point; which will most likely cause QA issues.
+ </li>
+ <li>
+ It is extremely difficult to track down bugs when you cannot install
+ the same version of a package as the reporter.
+ </li>
+ <li>
+ Many upstream package maintainers tend to get upset if people aren't
+ using a specific released version.
+ </li>
+</ul>
+
+</body>
+</section>
+
+<section>
+<title>Using CVS Sources</title>
+<body>
+
+<p>
+To use a CVS source, <c>cvs.eclass</c> must be inherited, and then a
+number of variables must be set. The following variables are often
+useful:
+</p>
+
+<table>
+ <tr>
+ <th>Variable</th>
+ <th>Purpose</th>
+ <th>Example</th>
+ </tr>
+ <tr>
+ <ti><c>ECVS_SERVER</c></ti>
+ <ti>Server and path</ti>
+ <ti><c>"cvs.sourceforge.net:/cvsroot/vim"</c></ti>
+ </tr>
+ <tr>
+ <ti><c>ECVS_MODULE</c></ti>
+ <ti>Module</ti>
+ <ti><c>"vim"</c></ti>
+ </tr>
+ <tr>
+ <ti><c>ECVS_BRANCH</c></ti>
+ <ti>Branch</ti>
+ <ti><c>"HEAD"</c></ti>
+ </tr>
+ <tr>
+ <ti><c>ECVS_AUTH</c></ti>
+ <ti>Auth method</ti>
+ <ti><c>"ext"</c></ti>
+ </tr>
+ <tr>
+ <ti><c>ECVS_USER</c></ti>
+ <ti>Username</ti>
+ <ti><c>"anoncvs"</c></ti>
+ </tr>
+ <tr>
+ <ti><c>ECVS_PASSWORD</c></ti>
+ <ti>Password</ti>
+ <ti><c>""</c></ti>
+ </tr>
+ <tr>
+ <ti><c>ECVS_TOPDIR</c></ti>
+ <ti>Unpack location</ti>
+ <ti><c>"${DISTDIR}/cvs-src/${ECVS_MODULE}"</c></ti>
+ </tr>
+</table>
+
+<p>
+See the eclass itself for the full range of options. To perform the
+actual checkout, use the <c>cvs_src_unpack</c> function.
+</p>
+
+<p>
+Here's a simple example, based upon the CVS options in vim.eclass:
+</p>
+
+<codesample lang="ebuild">
+inherit cvs
+
+SRC_URI=""
+
+src_unpack() {
+ ECVS_SERVER="cvs.sourceforge.net:/cvsroot/vim"
+ ECVS_USER="anonymous"
+ ECVS_PASS=""
+ ECVS_AUTH="pserver"
+ if [[ $(get_major_version ) -ge 7 ]] ; then
+ ECVS_MODULE="vim7"
+ else
+ ECVS_MODULE="vim"
+ fi
+ ECVS_TOP_DIR="${DISTDIR}/cvs-src/${ECVS_MODULE}"
+ cvs_src_unpack
+}
+</codesample>
+
+<p>
+Here's another approach, based upon the <c>emacs-cvs</c> ebuild, which
+relies upon the default <c>src_unpack</c> provided in the eclass; this
+approach is simpler but less flexible:
+</p>
+
+<codesample lang="ebuild">
+inherit cvs
+
+ECVS_AUTH="ext"
+CVS_RSH="ssh"
+ECVS_SERVER="savannah.gnu.org:/cvsroot/emacs"
+ECVS_MODULE="emacs"
+ECVS_BRANCH="emacs-unicode-2"
+ECVS_USER="anoncvs"
+ECVS_PASS=""
+ECVS_CVS_OPTIONS="-dP"
+
+# ...and so on. No src_unpack() is specified.
+</codesample>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_unpack/deb-sources/text.xml b/ebuild-writing/functions/src_unpack/deb-sources/text.xml
new file mode 100644
index 0000000..bdbadb4
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/deb-sources/text.xml
@@ -0,0 +1,12 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_unpack/deb-sources/">
+<chapter>
+<title>Debian Sources</title>
+
+<body>
+<todo>
+from vapier: we dont have to 'handle' these because all debian packages have a source tarball ... the .deb format is pretty simple though, it's managed by the 'ar' utility from binutils. you can unpack a .deb by simply doing ar x blah.deb ... this will give you three files: debian-binary: plain text file which just contains version number of the .deb format control.tar.gz: a few files which control installing/verifying of package data.tar.gz: all the compiled files ... you could just extract it to /
+</todo>
+</body>
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_unpack/epatch/text.xml b/ebuild-writing/functions/src_unpack/epatch/text.xml
new file mode 100644
index 0000000..f74cb62
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/epatch/text.xml
@@ -0,0 +1,148 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_unpack/epatch/">
+<chapter>
+<title>Patching with epatch</title>
+
+<body>
+<p>
+The canonical way of applying patches in ebuilds is to
+use <c>epatch</c> (from <c>eutils.eclass</c>, which you must make sure
+to import!) inside <c>src_unpack</c>. This function automatically
+handles <c>-p</c> levels, <c>gunzip</c> and so on as necessary.
+</p>
+
+<p>
+Note that distributing modified tarballs rather than a vanilla tarball
+and patches is <e>highly</e> discouraged.
+</p>
+</body>
+
+<section>
+<title>Basic <c>epatch</c></title>
+<body>
+
+<p>
+In its simplest form, <c>epatch</c> takes a single filename and
+applies that patch. It will automatically <c>die</c> if the apply
+fails. The following is taken from <c>app-misc/detox</c>:
+</p>
+
+<codesample lang="ebuild">
+src_unpack() {
+ unpack ${A}
+ cd ${S}
+ epatch ${FILESDIR}/${P}-destdir.patch
+ epatch ${FILESDIR}/${P}-parallel_build.patch
+}
+</codesample>
+
+<p>
+For larger patches, using <c>mirror://gentoo/</c> rather
+than <c>files/</c> is more appropriate. In these situations, it is
+usually best to <c>bzip2</c> the patch in question (as opposed to
+<c>files/</c> patches, which must not be compressed). For example,
+from <c>app-admin/showconsole</c>:
+</p>
+
+<codesample lang="ebuild">
+src_unpack() {
+ unpack ${P}.tar.bz2
+ cd ${S}
+ epatch ${DISTDIR}/${P}-suse-update.patch.bz2
+ epatch ${FILESDIR}/${PV}-no-TIOCGDEV.patch
+}
+</codesample>
+
+<p>
+Remember to add the patch to <c>SRC_URI</c>.
+</p>
+</body>
+
+<subsection>
+<title>CVS Keyword Lines and Patches</title>
+<body>
+<p>
+If your patch includes any changes to CVS <c>$Id: $</c>
+(or <c>$Header: $</c>, or <c>$Date: $</c>) lines, it cannot be
+distributed under <c>files/</c>, since CVS will clobber the patch when
+you commit. In these situations, either remove this hunk of the patch
+manually, or mirror the file.
+</p>
+</body>
+</subsection>
+
+</section>
+
+<section>
+<title>Multiple Patches with <c>epatch</c></title>
+<body>
+
+<p>
+epatch can also apply multiple patches (which can be selectively based
+upon arch) from a single directory. This can be useful if upstream
+have releases that need more patches.
+</p>
+
+<p>
+A simple example:
+</p>
+
+<codesample lang="ebuild">
+src_unpack() {
+ unpack ${A}
+ cd ${S}
+ EPATCH_SOURCE="${WORKDIR}/patches" EPATCH_SUFFIX="patch" \
+ EPATCH_FORCE="yes" epatch
+}
+</codesample>
+
+<p>
+Here, one of the <c>SRC_URI</c> components is a tarball containing
+many patches with file extension <c>.patch</c>.
+</p>
+
+<p>
+Variables which may be defined include:
+</p>
+
+<table>
+ <tr>
+ <th>Variable</th>
+ <th>Purpose</th>
+ </tr>
+ <tr>
+ <ti><c>EPATCH_SOURCE</c></ti>
+ <ti>Specifies the directory in which epatch looks for patches.</ti>
+ </tr>
+ <tr>
+ <ti><c>EPATCH_SUFFIX</c></ti>
+ <ti>File extension for patches.</ti>
+ </tr>
+ <tr>
+ <ti><c>EPATCH_OPTS</c></ti>
+ <ti>Default options to <c>patch</c>.</ti>
+ </tr>
+ <tr>
+ <ti><c>EPATCH_EXCLUDE</c></ti>
+ <ti>List of patches to exclude.</ti>
+ </tr>
+ <tr>
+ <ti><c>EPATCH_FORCE</c></ti>
+ <ti>
+ Force epatch to apply patches even if they do not follow the
+ canonical naming form (set to <c>yes</c>).
+ </ti>
+ </tr>
+</table>
+
+<p>
+Bulk patches should be named in the form
+<c>??_${ARCH}_foo.${EPATCH_SUFFIX}</c>. If they are
+not, <c>EPATCH_FORCE="yes"</c> must be set. To apply a patch on <c>all</c>
+archs, use all for the <c>${ARCH}</c> part.
+</p>
+
+</body>
+</section>
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_unpack/other-formats/text.xml b/ebuild-writing/functions/src_unpack/other-formats/text.xml
new file mode 100644
index 0000000..3647c80
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/other-formats/text.xml
@@ -0,0 +1,53 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_unpack/other-formats/">
+<chapter>
+<title>Other Archive Formats</title>
+
+<body>
+<p>
+There are a variety of other archive formats which you may encounter.
+Instructions for some of them are detailed below:
+</p>
+</body>
+
+<section>
+<title>Zip Files</title>
+<body>
+
+<p>
+If a package is supplied as a .zip file, you should:
+</p>
+
+<ul>
+ <li><c>DEPEND</c> upon <c>app-arch/unzip</c></li>
+ <li>Use <c>unpack</c> as normal</li>
+</ul>
+
+</body>
+</section>
+
+<section>
+<title>Shar Files</title>
+<body>
+<p>
+If a package is supplied as a <c>.shar</c> file, you should repackage it locally
+into a <c>.tar.bz2</c>. It may also be useful to ask upstream to use a friendlier
+package format <d/> however, if they ship <c>.shar</c>, chances are they haven't
+done a release in at least ten years.
+</p>
+</body>
+</section>
+
+<section>
+<title>RAR Files</title>
+<body>
+
+<p>
+<c>.rar</c> files must be repackaged locally into a <c>.tar.bz2</c> file.
+</p>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_unpack/rpm-sources/text.xml b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml
new file mode 100644
index 0000000..45bddb0
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml
@@ -0,0 +1,123 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_unpack/rpm-sources/">
+<chapter>
+<title>RPM Sources</title>
+
+<body>
+<p>
+If a package is supplied as an .rpm file, you should:
+</p>
+
+<codesample lang="ebuild">
+inherit rpm
+</codesample>
+
+<p>
+If you don't need to do anything in the unpack phase, then you are
+finished as the <c>rpm.eclass</c> exports a default <c>src_unpack</c>
+that will unpack the RPM files.
+</p>
+
+<p>
+If you do need to apply patches then override <c>src_unpack</c> in a
+manner such as:
+</p>
+
+<codesample lang="ebuild">
+src_unpack () {
+ rpm_src_unpack ${A}
+ cd ${S}
+
+ use ssl &amp;&amp; epatch ${FILESDIR}/${PV}/${P}-ssl.patch
+}
+</codesample>
+
+<note>
+<c>${A}</c> can contain non-rpm files since the rpm eclass will call
+the normal <c>unpack</c> function for files that are not in the RPM
+format.
+</note>
+</body>
+
+<section>
+<title>Notes on Using <c>rpm.eclass</c></title>
+<body>
+
+<p>
+There are two ways to unpack a rpm file <d/> using
+the <c>rpmoffset</c> program from <c>rpm2targz</c> and <c>cpio</c>, or
+by using <c>rpm2cpio</c> from <c>app-arch/rpm</c>. Normally, for
+unpacking an RPM file, installing the entire RPM application is
+overkill. Because of this, the eclass will only use <c>rpm2cpio</c>
+if <c>rpm</c> is already installed on the system. If you want to force
+the eclass to only use the RPM offset method, set
+<c>USE_RPMOFFSET_ONLY=1</c>.
+</p>
+
+<p>
+Another issue that might arise is that <c>rpmoffset</c> and cpio are not able
+to unpack the RPM file correctly. If this occurs, then you need to add
+<c>app-arch/rpm</c> to the <c>DEPEND</c> variable so
+that <c>rpm2cpio</c> will be used instead.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Example RPM Handling</title>
+<body>
+
+<p>
+Here is an ebuild snippet that is based upon the fetchmail source RPM
+from SuSE 9.2. The ebuild snippet is complete enough to work with the
+<c>ebuild unpack</c> command. The ebuild will download the source file from
+the OSU SuSE mirror, unpack the file and apply the included
+patches. The filename should be <c>suse-fetchmail-6.2.5.54.1.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 versionator rpm
+
+MY_PV=$(replace_version_separator 3 '-')
+MY_P=fetchmail-${MY_PV}
+
+SRC_URI="http://suse.osuosl.org/suse/i386/9.2/suse/src/${MY_P}.src.rpm"
+DESCRIPTION="SuSE 9.2 Fetchmail Source Package"
+HOMEPAGE="http://www.suse.com"
+LICENSE="GPL-2 public-domain"
+SLOT="0"
+KEYWORDS="-*"
+IUSE=""
+
+RESTRICT="nomirror"
+
+# Need to test if the file can be unpacked with rpmoffset and cpio
+# If it can't then set:
+
+#DEPEND="app-arch/rpm"
+
+# To force the use of rpmoffset and cpio instead of rpm2cpio from
+# app-arch/rpm, then set the following:
+
+#USE_RPMOFFSET_ONLY=1
+
+S=${WORKDIR}/fetchmail-$(get_version_component_range 1-3)
+
+src_unpack () {
+ rpm_src_unpack ${A}
+ cd ${S}
+ EPATCH_SOURCE="${WORKDIR}" EPATCH_SUFFIX="patch" \
+ EPATCH_FORCE="yes" epatch
+}
+</codesample>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_unpack/svn-sources/text.xml b/ebuild-writing/functions/src_unpack/svn-sources/text.xml
new file mode 100644
index 0000000..06f17e8
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/svn-sources/text.xml
@@ -0,0 +1,109 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_unpack/svn-sources/">
+<chapter>
+<title>Subversion Sources</title>
+
+<body>
+<p>
+As with CVS, an eclass exists for working directly with upstream
+Subversion repositories. See `subversion.eclass Reference`_ for a full
+list of functions and variables. Also see
+the <uri link="::ebuild-writing/functions/src_unpack/cvs-sources"/>
+ection.
+</p>
+</body>
+
+<section>
+<title>Disadvantages of Subversion Sources</title>
+<body>
+
+<p>
+Note that Subversion ebuilds should <b>not</b> generally be added to
+the tree (except under <c>package.mask</c>) for much the same reasons
+that live CVS ebuilds should not (see
+<uri link="::ebuild-writing/functions/src_unpack/cvs-sources#Disadvantages of CVS Sources"/>). Indeed, there should be even less
+impetus to add a live Subversion ebuild than a live CVS ebuild, as
+Subversion checkouts are roughly a factor of five larger than an
+equivalent CVS checkout.
+</p>
+
+<p>
+It is safer (and better for the user) to make a snapshot instead. For
+example, <c>gentoo-syntax</c> snapshots could be made using:
+</p>
+
+<pre>
+$ svn export svn://svn.berlios.de/svnroot/repos/gentoo-syntax -r HEAD gentoo-syntax
+</pre>
+</body>
+</section>
+
+<section>
+<title>Using Subversion Sources</title>
+<body>
+
+<p>
+To use a Subversion source, <c>subversion.eclass</c> must be
+inherited, and then at least <c>ESVN_REPO_URI</c> must be set. The
+following variables are also noteworthy:
+</p>
+
+<table>
+ <tr>
+ <th>Variable</th>
+ <th>Purpose</th>
+ <th>Example</th>
+ </tr>
+ <tr>
+ <ti><c>ESVN_REPO_URI</c></ti>
+ <ti>Server and path (http, https, svn)</ti>
+ <ti><c>"svn://svn.example.com/foobar/trunk"</c></ti>
+ </tr>
+ <tr>
+ <ti><c>ESVN_STORE_DIR</c></ti>
+ <ti>Unpack location</ti>
+ <ti><c>ESVN_STORE_DIR="${DISTDIR}/svn-src"</c></ti>
+ </tr>
+ <tr>
+ <ti><c>ESVN_PROJECT</c></ti>
+ <ti>Project name of ebuild</ti>
+ <ti><c>ESVN_PROJECT="${PN/-svn}"</c></ti>
+ </tr>
+ <tr>
+ <ti><c>ESVN_BOOTSTRAP</c></ti>
+ <ti>Bootstrap command or script</ti>
+ <ti><c>ESVN_BOOTSTRAP="autogen.sh"</c></ti>
+ </tr>
+ <tr>
+ <ti><c>ESVN_PATCHES</c></ti>
+ <ti>Patches to apply during bootstrap</ti>
+ <ti><c>ESVN_PATCHES="${FILESDIR}/*.patch"</c></ti>
+ </tr>
+</table>
+
+<p>
+See the eclass itself and `subversion.eclass Reference`_ for the full
+range of options. To perform the actual checkout, use
+the <c>subversion_src_unpack</c> function, which calls
+both <c>subversion_svn_fetch</c> and <c>subversion_bootstrap</c>
+itself.
+</p>
+
+<p>
+Here is a simple example, based upon the Subversion options in
+<c>litu-svn-20040902.ebuild</c>; this approach is sufficient for most
+Subversion ebuilds:
+</p>
+
+<codesample lang="ebuild">
+inherit subversion
+
+ESVN_REPO_URI="http://tao.uab.es/ion/svn/libtu/trunk"
+ESVN_PROJECT="libtu-snapshot"
+</codesample>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_unpack/text.xml b/ebuild-writing/functions/src_unpack/text.xml
new file mode 100644
index 0000000..aee4f5d
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/text.xml
@@ -0,0 +1,100 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_unpack/">
+<chapter>
+<title>src_unpack</title>
+
+<body>
+<table>
+ <tr>
+ <th>Function</th>
+ <ti><c>src_unpack</c></ti>
+ </tr>
+ <tr>
+ <th>Purpose</th>
+ <ti>Extract source packages and do any necessary patching or fixes.</ti>
+ </tr>
+ <tr>
+ <th>Sandbox</th>
+ <ti>Enabled</ti>
+ </tr>
+ <tr>
+ <th>Privilege</th>
+ <ti>user</ti>
+ </tr>
+ <tr>
+ <th>Called for</th>
+ <ti>ebuild</ti>
+ </tr>
+</table>
+</body>
+
+<section>
+<title>Default <c>src_unpack</c></title>
+<body>
+<codesample lang="ebuild">
+src_unpack() {
+ if [ "${A}" != "" ]; then
+ unpack ${A}
+ fi
+}
+</codesample>
+</body>
+</section>
+
+<section>
+<title>Sample <c>src_unpack</c></title>
+<body>
+<codesample lang="ebuild">
+src_unpack() {
+ unpack ${A}
+ cd ${S}
+
+ epatch ${FILESDIR}/${PV}/${P}-fix-bogosity.patch
+ use pam &amp;&amp; epatch ${FILESDIR}/${PV}/${P}-pam.patch
+
+ sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!"
+}
+</codesample>
+</body>
+</section>
+
+<section>
+<title>Unpacking Tarballs</title>
+<body>
+<p>
+The <c>unpack</c> function should be used to unpack tarballs, compressed
+files and so on. Do not use <c>tar</c>, <c>gunzip</c> etc. manually.
+</p>
+
+<p>
+The <c>${A}</c> variable contains all of the <c>SRC_URI</c> components, except
+for any which are excluded by USE-based conditionals inside <c>SRC_URI</c>
+itself. If multiple archives require unpacking in a particular order it is
+usually simpler to avoid working with <c>${A}</c>.
+</p>
+</body>
+</section>
+
+<section>
+<title><c>src_unpack</c> Actions</title>
+<body>
+<p>
+The following subsections cover different topics which often occur when writing
+<c>src_unpack</c> functions.
+</p>
+
+<contentsTree/>
+</body>
+</section>
+
+</chapter>
+
+<include href="epatch/"/>
+<include href="cvs-sources/"/>
+<include href="svn-sources/"/>
+<include href="tla-sources/"/>
+<include href="rpm-sources/"/>
+<include href="deb-sources/"/>
+<include href="autopackage/"/>
+<include href="other-formats/"/>
+</guide>
diff --git a/ebuild-writing/functions/src_unpack/tla-sources/text.xml b/ebuild-writing/functions/src_unpack/tla-sources/text.xml
new file mode 100644
index 0000000..97a8b40
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/tla-sources/text.xml
@@ -0,0 +1,12 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_unpack/tla-sources/">
+<chapter>
+<title>Arch Sources</title>
+
+<body>
+<todo>
+Anyone want to write this? You can probably mostly copy the CVS Sources and Subversion Sources chapters.
+</todo>
+</body>
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml
new file mode 100644
index 0000000..25e8966
--- /dev/null
+++ b/ebuild-writing/functions/text.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/">
+<chapter>
+<title>Ebuild Functions</title>
+
+<body>
+<p>
+When installing packages from source, the function call order is <c>pkg_setup</c>,
+<c>src_unpack</c>, <c>src_compile</c>, <c>src_test</c> (optional, <c>FEATURES="test"</c>),
+<c>src_install</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. When installing packages
+from a binary, the function call order is <c>pkg_setup</c>, <c>pkg_preinst</c>,
+<c>pkg_postinst</c>.
+</p>
+
+<figure short="How the ebuild functions are processed" link="diagram.png"/>
+
+<p>
+The <c>pkg_prerm</c> and <c>pkg_postrm</c> functions are called when uninstalling a
+package. The <c>pkg_config</c> function is used for any special package
+configuration <d/> it is only run when explicitly requested by the user. The
+<c>pkg_nofetch</c> function is used when a <c>RESTRICT="fetch"</c> package needs to
+obtain some <c>SRC_URI</c> components.
+</p>
+</body>
+
+<section>
+<title>Contents</title>
+<body>
+<contentsTree/>
+</body>
+</section>
+</chapter>
+
+<include href="src_unpack/"/>
+</guide>
diff --git a/ebuild-writing/messages/text.xml b/ebuild-writing/messages/text.xml
index fdc5477..de3c476 100644
--- a/ebuild-writing/messages/text.xml
+++ b/ebuild-writing/messages/text.xml
@@ -1,5 +1,5 @@
<?xml version="1.0"?>
-<guide self="ebuild-writing/users-and-groups/">
+<guide self="ebuild-writing/messages/">
<chapter>
<title>Messages</title>
diff --git a/ebuild-writing/text.xml b/ebuild-writing/text.xml
index ace7fa2..b51d746 100644
--- a/ebuild-writing/text.xml
+++ b/ebuild-writing/text.xml
@@ -5,8 +5,9 @@
<body>
<p>
-This section covers some general concepts with which you should be familiar when
-writing ebuilds or working with the portage tree.
+This section describes how to write an ebuild. It covers the basic format
+of an ebuild and the variables and functions available, and finishes off
+with some general notes and extended examples.
</p>
</body>
@@ -16,8 +17,8 @@ writing ebuilds or working with the portage tree.
<contentsTree/>
</body>
</section>
-
</chapter>
+
<include href="file-format/"/>
<include href="use-conditional-code/"/>
<include href="error-handling/"/>
@@ -25,5 +26,5 @@ writing ebuilds or working with the portage tree.
<include href="messages/"/>
<include href="variables/"/>
<include href="using-eclasses/"/>
-<include href="ebuild-functions/"/>
+<include href="functions/"/>
</guide>
diff --git a/ebuild-writing/using-eclasses/text.xml b/ebuild-writing/using-eclasses/text.xml
index fdf8da0..6e8c15b 100644
--- a/ebuild-writing/using-eclasses/text.xml
+++ b/ebuild-writing/using-eclasses/text.xml
@@ -20,9 +20,9 @@ how to use an eclass which has already been written.
<p>
To use an eclass, it must be 'inherited'. This is done via the <c>inherit</c>
function, which is provided by <c>ebuild.sh</c>. The <c>inherit</c> statement must
-come at the top of the ebuild, *before* any functions. Conditional inherits are
-illegal (except where the inheritance criteria are cache-constant <d/> see `The
-Portage Cache`_).
+come at the top of the ebuild, <e>before</e> any functions. Conditional inherits are
+illegal (except where the inheritance criteria are cache-constant <d/> see <uri
+link="::general-concepts/portage-cache"/>).
</p>
<p>