diff options
Diffstat (limited to 'ebuild-writing')
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 && 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 && 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> |
