diff options
| author |   Tim Yamin <plasmaroo@gentoo.org> | 2006-03-03 21:21:51 +0000 |
|---|---|---|
| committer | Tim Yamin <plasmaroo@gentoo.org> | 2006-03-03 21:21:51 +0000 |
| commit | 7ff328709a028aee2fe8e29422ac9d4d9ce9dd71 (patch) | |
| tree | e11c22f738f112dd7f15f635cec149f5f0564535 | |
| parent | Add <uri/> tag. (diff) | |
| download | devmanual-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
19 files changed, 909 insertions, 55 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> @@ -5,13 +5,19 @@ <body> <p> -This document is an ongoing work in progress. It contains gaps, inaccuracies, omissions, typos and the occasional outright lie. The intent is to make an handbook giving developers and users correct, detailed, up to date technical content. +This document is an ongoing work in progress. It contains gaps, +inaccuracies, omissions, typos and the occasional outright lie. The +intent is to make an handbook giving developers and users correct, +detailed, up to date technical content. </p> <p> -Contributions are encouraged. See the Contributing to This Document section for how to get started. Thanks for Ciaran for permitting me to continue this and sending me the RST source and needed scripts. +Contributions are encouraged. See the Contributing to This Document +section for how to get started. </p> </body> +<!-- FIXME: Add Authors --> + <section> <title>Contents</title> <body> |
