diff options
| author |   Tim Yamin <plasmaroo@gentoo.org> | 2006-04-13 20:54:07 +0000 |
|---|---|---|
| committer | Tim Yamin <plasmaroo@gentoo.org> | 2006-04-13 20:54:07 +0000 |
| commit | d8b2acc63f74f4163f3f791acd59b19c4ca65ad8 (patch) | |
| tree | e13a69bd360f14e72b41e90a8752eda5f527855e | |
| parent | Add very brief draft of "Contributing to This Document". The DevBook XML will... (diff) | |
| download | devmanual-d8b2acc63f74f4163f3f791acd59b19c4ca65ad8.tar.gz devmanual-d8b2acc63f74f4163f3f791acd59b19c4ca65ad8.tar.bz2 devmanual-d8b2acc63f74f4163f3f791acd59b19c4ca65ad8.zip | |
Complete 'Ebuild Writing' section.
git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@32 176d3534-300d-0410-8db8-84e73ed771c3
| -rw-r--r-- | devbook.xsl | 4 | ||||
| -rw-r--r-- | ebuild-writing/functions/pkg_config/text.xml | 70 | ||||
| -rw-r--r-- | ebuild-writing/functions/pkg_nofetch/text.xml | 76 | ||||
| -rw-r--r-- | ebuild-writing/functions/pkg_postinst/text.xml | 75 | ||||
| -rw-r--r-- | ebuild-writing/functions/pkg_postrm/text.xml | 65 | ||||
| -rw-r--r-- | ebuild-writing/functions/pkg_preinst/text.xml | 82 | ||||
| -rw-r--r-- | ebuild-writing/functions/pkg_prerm/text.xml | 66 | ||||
| -rw-r--r-- | ebuild-writing/functions/pkg_setup/text.xml | 67 | ||||
| -rw-r--r-- | ebuild-writing/functions/src_install/text.xml | 182 | ||||
| -rw-r--r-- | ebuild-writing/functions/src_test/text.xml | 144 | ||||
| -rw-r--r-- | ebuild-writing/functions/text.xml | 9 | ||||
| -rw-r--r-- | ebuild-writing/misc-files/changelog/text.xml | 106 | ||||
| -rw-r--r-- | ebuild-writing/misc-files/metadata/text.xml | 104 | ||||
| -rw-r--r-- | ebuild-writing/misc-files/patches/text.xml | 104 | ||||
| -rw-r--r-- | ebuild-writing/misc-files/text.xml | 23 | ||||
| -rw-r--r-- | general-concepts/mirrors/text.xml | 6 |
16 files changed, 1178 insertions, 5 deletions
diff --git a/devbook.xsl b/devbook.xsl index 03d1e76..45a3b84 100644 --- a/devbook.xsl +++ b/devbook.xsl @@ -454,10 +454,10 @@ </xsl:call-template> </xsl:variable> - <h3><a name="${anchor}"><xsl:apply-templates select="title"/></a></h3> + <h3><a name="{$anchor}"><xsl:apply-templates select="title"/></a></h3> <xsl:apply-templates select="(body)"/> - <!-- If you need, change here to add more nesting --> + <!-- If you need, change here to add more nesting levels --> </div> </xsl:template> diff --git a/ebuild-writing/functions/pkg_config/text.xml b/ebuild-writing/functions/pkg_config/text.xml new file mode 100644 index 0000000..6a82f14 --- /dev/null +++ b/ebuild-writing/functions/pkg_config/text.xml @@ -0,0 +1,70 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/functions/pkg_config/"> +<chapter> +<title>pkg_config</title> + +<body> +<table> + <tr> + <th>Function</th> + <ti><c>pkg_config</c></ti> + </tr> + <tr> + <th>Purpose</th> + <ti>Run any special post-install configuration</ti> + </tr> + <tr> + <th>Sandbox</th> + <ti>Disabled</ti> + </tr> + <tr> + <th>Privilege</th> + <ti>root</ti> + </tr> + <tr> + <th>Called for</th> + <ti>manual</ti> + </tr> +</table> +</body> + +<section> +<title>Default <c>pkg_config</c></title> +<body> +<codesample lang="ebuild"> +pkg_config() +{ + eerror "This ebuild does not have a config function." +} +</codesample> +</body> +</section> + +<section> +<title>Example <c>pkg_config</c></title> +<body> +<p> +Taken from the <c>mysql</c> ebuilds. Note the use of <c>${ROOT}</c>. +</p> + +<codesample lang="ebuild"> +pkg_config() { + if [ ! -d ${ROOT}/var/lib/mysql/mysql ] ; then + einfo "Press ENTER to create the mysql database and set proper" + einfo "permissions on it, or Control-C to abort now..." + read + ${ROOT}/usr/bin/mysql_install_db + else + einfo "Hmm, it appears as though you already have the mysql" + einfo "database in place. If you are having problems trying" + einfo "to start mysqld, perhaps you need to manually run" + einfo "/usr/bin/mysql_install_db and/or check your config" + einfo "file(s) and/or database(s) and/or logfile(s)." + fi +} +</codesample> +</body> +</section> + +</chapter> +</guide> diff --git a/ebuild-writing/functions/pkg_nofetch/text.xml b/ebuild-writing/functions/pkg_nofetch/text.xml new file mode 100644 index 0000000..f360607 --- /dev/null +++ b/ebuild-writing/functions/pkg_nofetch/text.xml @@ -0,0 +1,76 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/functions/pkg_nofetch/"> +<chapter> +<title>pkg_nofetch</title> + +<body> +<table> + <tr> + <th>Function</th> + <ti><c>pkg_nofetch</c></ti> + </tr> + <tr> + <th>Purpose</th> + <ti>Tell the user how to deal with fetch-restricted packages</ti> + </tr> + <tr> + <th>Sandbox</th> + <ti>Enabled</ti> + </tr> + <tr> + <th>Privilege</th> + <ti>root</ti> + </tr> + <tr> + <th>Called for</th> + <ti>ebuild</ti> + </tr> +</table> +</body> + +<section> +<title>Default <c>pkg_nofetch</c></title> +<body> +<codesample lang="ebuild"> +pkg_nofetch() +{ + [ -z "${SRC_URI}" ] && return + + echo "!!! The following are listed in SRC_URI for ${PN}:" + for MYFILE in `echo ${SRC_URI}`; do + echo "!!! $MYFILE" + done + return +} +</codesample> +</body> +</section> + +<section> +<title>Sample <c>pkg_nofetch</c></title> +<body> +<codesample lang="ebuild"> +pkg_nofetch() { + einfo "Please download" + einfo " - ${P}-main.tar.bz2" + einfo " - ${P}-extras.tar.bz2" + einfo "from ${HOMEPAGE} and place them in ${DISTDIR}" +} +</codesample> +</body> +</section> + +<section> +<title>Notes on <c>pkg_nofetch</c></title> +<body> +<p> +This function is only triggered for packages which +have <c>RESTRICT="fetch"</c> (see <uri link="::general-concepts/mirrors#Restricting Automatic Mirroring"/>) +set, and only if one or more components listed in <c>SRC_URI</c> are not +already available in the <c>distfiles</c> directory. +</p> +</body> +</section> + +</chapter> +</guide> diff --git a/ebuild-writing/functions/pkg_postinst/text.xml b/ebuild-writing/functions/pkg_postinst/text.xml new file mode 100644 index 0000000..254fcfe --- /dev/null +++ b/ebuild-writing/functions/pkg_postinst/text.xml @@ -0,0 +1,75 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/functions/pkg_postinst/"> +<chapter> +<title>pkg_postinst</title> + +<body> +<table> + <tr> + <th>Function</th> + <ti><c>pkg_postinst</c></ti> + </tr> + <tr> + <th>Purpose</th> + <ti>Called after image is installed to <c>${ROOT}</c></ti> + </tr> + <tr> + <th>Sandbox</th> + <ti>Disabled</ti> + </tr> + <tr> + <th>Privilege</th> + <ti>root</ti> + </tr> + <tr> + <th>Called for</th> + <ti>ebuild, binary</ti> + </tr> +</table> +</body> + +<section> +<title>Default <c>pkg_postinst</c></title> +<body> +<codesample lang="ebuild"> +pkg_postinst() +{ + return +} +</codesample> +</body> +</section> + +<section> +<title>Sample <c>pkg_postinst</c></title> +<body> +<codesample lang="ebuild"> +pkg_postinst() { + if has_version '<x11-wm/fluxbox-0.9.10-r3' ; then + ewarn "You must restart fluxbox before using the [include] /directory/" + ewarn "feature if you are upgrading from an older fluxbox!" + ewarn " " + fi + einfo "If you experience font problems, or if fluxbox takes a very" + einfo "long time to start up, please try the 'disablexmb' USE flag." + einfo "If that fails, please report bugs upstream." + epause +} +</codesample> +</body> +</section> + +<section> +<title>Common <c>pkg_postinst</c> Tasks</title> +<body> +<p> +The most common use for <c>pkg_postinst</c> is to display post-install +informational messages or warnings. Note that <c>has_version</c> will +operate on the version that <e>was</e> installed, which can be useful +for selective upgrade messages. +</p> +</body> +</section> + +</chapter> +</guide> diff --git a/ebuild-writing/functions/pkg_postrm/text.xml b/ebuild-writing/functions/pkg_postrm/text.xml new file mode 100644 index 0000000..fa2a21d --- /dev/null +++ b/ebuild-writing/functions/pkg_postrm/text.xml @@ -0,0 +1,65 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/functions/pkg_postrm/"> +<chapter> +<title>pkg_postrm</title> + +<body> +<table> + <tr> + <th>Function</th> + <ti><c>pkg_postrm</c></ti> + </tr> + <tr> + <th>Purpose</th> + <ti>Called after a package is unmerged</ti> + </tr> + <tr> + <th>Sandbox</th> + <ti>Disabled</ti> + </tr> + <tr> + <th>Privilege</th> + <ti>root</ti> + </tr> + <tr> + <th>Called for</th> + <ti>ebuild, binary</ti> + </tr> +</table> +</body> + +<section> +<title>Default <c>pkg_postrm</c></title> +<body> +<codesample lang="ebuild"> +pkg_postrm() +{ + return +} +</codesample> +</body> +</section> + +<section> +<title>Sample <c>pkg_postrm</c></title> +<body> +<codesample lang="ebuild"> +pkg_postrm() { + fdo-mime_mime_database_update +} +</codesample> +</body> +</section> + +<section> +<title>Common <c>pkg_postrm</c> Tasks</title> +<body> +<p> +<c>pkg_postrm</c> is is used to update symlinks, cache files and other +generated content after a package has been uninstalled. +</p> +</body> +</section> + +</chapter> +</guide> diff --git a/ebuild-writing/functions/pkg_preinst/text.xml b/ebuild-writing/functions/pkg_preinst/text.xml new file mode 100644 index 0000000..9052d4f --- /dev/null +++ b/ebuild-writing/functions/pkg_preinst/text.xml @@ -0,0 +1,82 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/functions/pkg_preinst/"> +<chapter> +<title>pkg_preinst</title> + +<body> +<table> + <tr> + <th>Function</th> + <ti><c>pkg_preinst</c></ti> + </tr> + <tr> + <th>Purpose</th> + <ti>Called before image is installed to <c>${ROOT}</c></ti> + </tr> + <tr> + <th>Sandbox</th> + <ti>Disabled</ti> + </tr> + <tr> + <th>Privilege</th> + <ti>root</ti> + </tr> + <tr> + <th>Called for</th> + <ti>ebuild, binary</ti> + </tr> +</table> +</body> + +<section> +<title>Default <c>pkg_preinst</c></title> +<body> +<codesample lang="ebuild"> +pkg_preinst() +{ + return +} +</codesample> +</body> +</section> + +<section> +<title>Sample <c>pkg_preinst</c></title> +<body> +<codesample lang="ebuild"> +pkg_preinst() { + enewgroup foo + enewuser foo -1 /bin/false /dev/null foo +} +</codesample> +</body> +</section> + +<section> +<title>Common <c>pkg_preinst</c> Tasks</title> +<body> +<p> +There are a few things that are often done in <c>pkg_preinst</c>: +</p> + +<ul> + <li> + Adding users and groups <d/> see <uri link="::ebuild-writing/users-and-groups"/>. + </li> + <li> + Modifying the install image for a particular system. This function + allows system-specific customisation to be done even when installing + from a binary. The most useful example is probably smart + configuration file updating <d/> a <c>pkg_preinst</c> could check a + configuration file in <c>${ROOT}/etc/</c> and create a smart updated + version in <c>${IMAGE}/etc/</c> (see + <uri link="::general-concepts/install-destinations"/>) rather than + always trying to install the default configuration file (remember + <uri link="::general-concepts/config-protect"/>). + </li> +</ul> +</body> +</section> + +</chapter> +</guide> diff --git a/ebuild-writing/functions/pkg_prerm/text.xml b/ebuild-writing/functions/pkg_prerm/text.xml new file mode 100644 index 0000000..d9f8a6f --- /dev/null +++ b/ebuild-writing/functions/pkg_prerm/text.xml @@ -0,0 +1,66 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/functions/pkg_prerm/"> +<chapter> +<title>pkg_prerm</title> + +<body> +<table> + <tr> + <th>Function</th> + <ti><c>pkg_prerm</c></ti> + </tr> + <tr> + <th>Purpose</th> + <ti>Called before a package is unmerged</ti> + </tr> + <tr> + <th>Sandbox</th> + <ti>Disabled</ti> + </tr> + <tr> + <th>Privilege</th> + <ti>root</ti> + </tr> + <tr> + <th>Called for</th> + <ti>ebuild, binary</ti> + </tr> +</table> +</body> + +<section> +<title>Default <c>pkg_prerm</c></title> +<body> +<codesample lang="ebuild"> +pkg_prerm() +{ + return +} +</codesample> +</body> +</section> + +<section> +<title>Sample <c>pkg_prerm</c></title> +<body> +<codesample lang="ebuild"> +pkg_prerm() { + # clean up temp files + [[ -d "${ROOT}/var/tmp/foo" ]] && rm -rf "${ROOT}/var/tmp/foo" +} +</codesample> +</body> +</section> + +<section> +<title>Common <c>pkg_prerm</c> Tasks</title> +<body> +<p> +<c>pkg_prerm</c> is used to clean up any files that would otherwise prevent +a clean unmerge. +</p> +</body> +</section> + +</chapter> +</guide> diff --git a/ebuild-writing/functions/pkg_setup/text.xml b/ebuild-writing/functions/pkg_setup/text.xml new file mode 100644 index 0000000..a7fe9d2 --- /dev/null +++ b/ebuild-writing/functions/pkg_setup/text.xml @@ -0,0 +1,67 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/functions/pkg_setup/"> +<chapter> +<title>pkg_setup</title> + +<body> +<table> + <tr> + <th>Function</th> + <ti><c>pkg_setup</c></ti> + </tr> + <tr> + <th>Purpose</th> + <ti>Pre-build environment configuration and checks</ti> + </tr> + <tr> + <th>Sandbox</th> + <ti>Disabled</ti> + </tr> + <tr> + <th>Privilege</th> + <ti>root</ti> + </tr> + <tr> + <th>Called for</th> + <ti>ebuild, binary</ti> + </tr> +</table> +</body> + +<section> +<title>Default <c>pkg_setup</c></title> +<body> +<codesample lang="ebuild"> +pkg_setup() +{ + return +} +</codesample> +</body> +</section> + +<section> +<title>Sample <c>pkg_setup</c></title> +<body> +<codesample lang="ebuild"> +pkg_setup() { + # We need to know which GUI we're building in several + # different places, so work it out here. + if use gtk ; then + if use gtk2 ; then + export mypkg_gui="gtk2" + else + export mypkg_gui="gtk1" + fi + elif use motif then + export mypkg_gui="motif" + else + export mypkg_gui="athena" + fi +} +</codesample> +</body> +</section> + +</chapter> +</guide> diff --git a/ebuild-writing/functions/src_install/text.xml b/ebuild-writing/functions/src_install/text.xml new file mode 100644 index 0000000..98c96ad --- /dev/null +++ b/ebuild-writing/functions/src_install/text.xml @@ -0,0 +1,182 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/functions/src_install/"> +<chapter> +<title>src_install</title> + +<body> +<table> + <tr> + <th>Function</th> + <ti><c>src_install</c></ti> + </tr> + <tr> + <th>Purpose</th> + <ti>Install a package to <c>${D}</c></ti> + </tr> + <tr> + <th>Sandbox</th> + <ti>Enabled</ti> + </tr> + <tr> + <th>Privilege</th> + <ti>root</ti> + </tr> + <tr> + <th>Called for</th> + <ti>ebuild</ti> + </tr> +</table> +</body> + +<section> +<title>Default <c>src_install</c></title> +<body> +<codesample lang="ebuild"> +src_install() +{ + return +} +</codesample> +</body> +</section> + +<section> +<title>Sample <c>src_install</c></title> +<body> +<codesample lang="ebuild"> +src_install() { + make DESTDIR="${D}" install || die "Install failed!" + dodoc README CHANGES +} +</codesample> +</body> +</section> + +<section> +<title>Easy Installs</title> +<body> +<p> +Often, especially with autotools-powered packages, there is a <c>Makefile</c> +<c>install</c> target which will honour the <c>DESTDIR</c> variable to tell it to +install to a non-root location. If possible, this should be used: +</p> + +<codesample lang="ebuild"> + make DESTDIR="${D}" install || die "Install failed" +</codesample> + +<note> +<c>make</c> should be used over <c>emake</c> here. Most installs are +not designed to be parallelised. +</note> + +<p> +Sometimes this will end up installing a few things into strange +places. If and only if this is the case, the <c>einstall</c> function +can be used: +</p> + +<codesample lang="ebuild"> + einstall || die "Install failed!" +</codesample> + +<p> +It is usually necessary to include additional <c>dodoc</c> statements for the +<c>README</c>, <c>ChangeLog</c>, etc in these cases. +</p> +</body> +</section> + +<section> +<title>Trivial Installs</title> +<body> +<p> +For some packages with no <c>Makefile</c> that only install a small +number of files, writing a manual install using <c>cp</c> is the +easiest option. For example, to do a simple install of some (no +compilation required) themes: +</p> + +<codesample lang="ebuild"> + dodir /usr/share/foo-styles/ + cp -R ${S}/ ${D}/ || die "Install failed!" +</codesample> + +<p> +Or sometimes a combination of <c>insinto</c> and <c>doins</c> (plus related +functions -- see Install Functions Reference) <d/> the following is based +upon the <c>sys-fs/udev</c> install: +</p> + +<codesample lang="ebuild"> +src_install() { + dobin udevinfo + dobin udevtest + into / + dosbin udev + dosbin udevd + dosbin udevsend + dosbin udevstart + dosbin extras/scsi_id/scsi_id + dosbin extras/volume_id/udev_volume_id + + exeinto /etc/udev/scripts + doexe extras/ide-devfs.sh + doexe extras/scsi-devfs.sh + doexe extras/cdsymlinks.sh + doexe extras/dvb.sh + + insinto /etc/udev + newins ${FILESDIR}/udev.conf.post_050 udev.conf + doins extras/cdsymlinks.conf + + # For devfs style layout + insinto /etc/udev/rules.d/ + newins etc/udev/gentoo/udev.rules 50-udev.rules + + # scsi_id configuration + insinto /etc + doins extras/scsi_id/scsi_id.config + + # set up symlinks in /etc/hotplug.d/default + dodir /etc/hotplug.d/default + dosym ../../../sbin/udevsend /etc/hotplug.d/default/10-udev.hotplug + + # set up the /etc/dev.d directory tree + dodir /etc/dev.d/default + dodir /etc/dev.d/net + exeinto /etc/dev.d/net + doexe etc/dev.d/net/hotplug.dev + + doman *.8 + doman extras/scsi_id/scsi_id.8 + + dodoc COPYING ChangeLog FAQ HOWTO-udev_for_dev README TODO + dodoc docs/{overview,udev-OLS2003.pdf,udev_vs_devfs,RFC-dev.d,libsysfs.txt} + dodoc docs/persistent_naming/* docs/writing_udev_rules/* + + newdoc extras/volume_id/README README_volume_id +} +</codesample> + +<p> +This is, of course, considerably harder to handle than a +simple <c>Makefile</c> driven install. +</p> +</body> +</section> + +<section> +<title>Other Installs</title> +<body> +<p> +Sometimes, there will be a <c>Makefile</c> that does not +honour <c>DESTDIR</c> and a non-trivial number of files to install. In +these situations, it is best to patch the <c>Makefile</c> and contact +upstream explaining the situation to them. +</p> +</body> +</section> + +</chapter> +</guide> diff --git a/ebuild-writing/functions/src_test/text.xml b/ebuild-writing/functions/src_test/text.xml new file mode 100644 index 0000000..47fa884 --- /dev/null +++ b/ebuild-writing/functions/src_test/text.xml @@ -0,0 +1,144 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/functions/src_test/"> +<chapter> +<title>src_test</title> + +<body> +<table> + <tr> + <th>Function</th> + <ti><c>src_test</c></ti> + </tr> + <tr> + <th>Purpose</th> + <ti>Run pre-install test scripts</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_test</c></title> +<body> +<codesample lang="ebuild"> +src_test() +{ + addpredict / + if make check -n &> /dev/null; then + echo ">>> Test phase [check]: ${CATEGORY}/${PF}" + if ! make check; then + hasq maketest $FEATURES && die "Make check failed. See above for details." + hasq maketest $FEATURES || eerror "Make check failed. See above for details." + fi + elif make test -n &> /dev/null; then + echo ">>> Test phase [test]: ${CATEGORY}/${PF}" + if ! make test; then + hasq maketest $FEATURES && die "Make test failed. See above for details." + hasq maketest $FEATURES || eerror "Make test failed. See above for details." + fi + else + echo ">>> Test phase [none]: ${CATEGORY}/${PF}" + fi + SANDBOX_PREDICT="${SANDBOX_PREDICT%:/}" +} +</codesample> +</body> +</section> + +<section> +<title>Sample <c>src_test</c></title> +<body> +<codesample lang="ebuild"> +src_test() { + cd ${S}/src/testdir + + # Test 49 won't work inside a portage environment + sed -i -e 's~test49.out~~g' Makefile + + # Try to run the non-gui tests only + make test-nongui \ + || die "At least one test failed" +} +</codesample> +</body> +</section> + +<section> +<title>Common <c>src_test</c> Tasks</title> +<body> +<p> +Often the default <c>src_test</c> is fine. Sometimes it is necessary +to remove certain tests from the list if they cannot be used with a +portage environment. Reasons for such a failure could include: +</p> + +<ul> + <li>Needing to use X.</li> + <li> + Needing to work with files which are disallowed by the sandbox. + </li> + <li>Requiring user input (src_test must not be interactive).</li> + <li>Requiring root privileges.</li> +</ul> + +<p> +Usually, removing the relevant test from the <c>Makefile</c> +using <c>sed</c> or skipping a particular <c>make</c> target is +sufficient. +</p> + +<note> +<c>emake</c> should not be used for <c>src_test</c> <d/> trying to +parallelise tests unless the <c>Makefile</c> was specifically designed +for this can cause all sorts of strange problems. +</note> + +<p> +Try to ensure that tests work properly for your ebuild. A good test +suite is extremely helpful for arch maintainers. +</p> + +</body> +</section> + +<section> +<title>Skipping Tests</title> +<body> +<p> +Sometimes it is necessary to skip tests entirely. This can be done +using a dummy <c>src_test</c> function: +</p> + +<codesample lang="ebuild"> +src_test() { + # Tests don't even remotely work inside portage + true +} +</codesample> + +<p> +Another option would be to set <c>RESTRICT="test"</c> in the ebuild. +</p> + +<note> +If upstream provide a test suite which doesn't work, consider talking +to them about getting it fixed. A broken test suite is worse than no +test suite at all, since we are unable to tell whether a test failure +indicates a genuine fault. +</note> +</body> +</section> + +</chapter> +</guide> diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml index 3bed50d..5014ba7 100644 --- a/ebuild-writing/functions/text.xml +++ b/ebuild-writing/functions/text.xml @@ -31,6 +31,15 @@ obtain some <c>SRC_URI</c> components. </section> </chapter> +<include href="pkg_nofetch/"/> +<include href="pkg_setup/"/> <include href="src_unpack/"/> <include href="src_compile/"/> +<include href="src_test/"/> +<include href="src_install/"/> +<include href="pkg_preinst/"/> +<include href="pkg_postinst/"/> +<include href="pkg_prerm/"/> +<include href="pkg_postrm/"/> +<include href="pkg_config/"/> </guide> diff --git a/ebuild-writing/misc-files/changelog/text.xml b/ebuild-writing/misc-files/changelog/text.xml new file mode 100644 index 0000000..85ec332 --- /dev/null +++ b/ebuild-writing/misc-files/changelog/text.xml @@ -0,0 +1,106 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/misc-files/changelog/"> +<chapter> +<title>ChangeLog</title> + +<body> +<p> +The <c>ChangeLog</c> should be used to record all non-trivial changes +to ebuilds, including <e>keywording changes</e>. The echangelog tool +should be used to create <c>ChangeLog</c> entries — the format of a +<c>ChangeLog</c> is now defined as "whatever <c>echangelog</c> +creates". +</p> + +<p> +You should include references to any relevant bugs. The standard +format for doing this is via the phrase <c>bug #20600</c> — this +format (with the hash sign included) is recognised via +<uri link="http://packages.gentoo.org">packages.gentoo.org</uri> and +similar tools. When including user-submitted ebuilds or patches, you +should credit the user with their full name and email address (or +whatever they use to identify themselves on bugzilla <d/> some users +prefer to be known only by a nickname). +</p> + +<p> +If you are changing keywords, make sure you clearly state what +keywords you add or remove. "Marked stable" is a nuisance for +architecture teams, even if there was only one keyword in the ebuild +at the time. "Stable on all archs" isn't generally any better (and +should you really be stabling on all archs?) — do you mean "all", or +"all the ones that are currently keyworded"? A list like "x86 sparc +mips" is much more useful. +</p> + +<p> +A typical <c>ChangeLog</c> snippet might look like the following: +</p> + +<pre> + *vim-6.3.068 (25 Mar 2005) + + 25 Mar 2005; Ciaran McCreesh <ciaranm@gentoo.org> +vim-6.3.068.ebuild: + New release. Fixes bug #79981, bug #81289, bug #83383, bug #83416, bug + #83565, bug #85758, upstream patches up to 6.3.068. + + 22 Mar 2005; Aron Griffis <agriffis@gentoo.org> vim-6.3-r4.ebuild: + Stable on alpha +</pre> + +<section> +<title>Writing correct ChangeLog messages</title> +<body> +<note> +It is <b>very</b> important that your <c>cvs commit</c> messages are +also informative to aid the QA team or architecture teams as well as +other developers if they are trying to troubleshoot issues which are +known to not have occured in previous versions of ebuilds, for +example. If your ChangeLog message is concise there is usually nothing +wrong with using it as the <c>cvs commit</c> message. +</note> + +<p> +Your message should explain what specifically you changed and, if +relevant, why. You don't need to write an essay or even a complete +sentence (<c>ChangeLog</c> messages, however, are required to be in +'proper' English so no <c>fixed that bug kthx Bob</c> messages — +please do use punctuation), so long as it is easily understandable and +(preferably) greppable. Bad and good examples, all of which are based +upon real messages: +</p> + +<ul> + <li><b>BAD:</b> Changed keywords</li> + <li><e>GOOD:</e> Added ~x86 keyword</li> +</ul> + +<ul> + <li><b>BAD:</b> Stable</li> + <li><e>GOOD:</e> Stable on x86, sparc, mips</li> +</ul> + +<ul> + <li><b>BAD:</b> Fix stuff</li> + <li><e>GOOD:</e> Fix USE=foo logic error</li> +</ul> + +<ul> + <li><b>BAD:</b> .</li> + <li><e>GOOD:</e> Purge old ebuilds</li> +</ul> + +<ul> + <li> + <b>BAD:</b> Who the fuck reads this anyway? (<b>Editor's note</b>: + No, seriously, this is a genuine example. Do <e>not</e> do + this...) + </li> + <li><e>GOOD:</e> Version bump to 0.5.1.</li> +</ul> + +</body> +</section> +</body> +</chapter> +</guide> diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml new file mode 100644 index 0000000..9e34145 --- /dev/null +++ b/ebuild-writing/misc-files/metadata/text.xml @@ -0,0 +1,104 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/misc-files/metadata/"> +<chapter> +<title>Package and Category <c>metadata.xml</c></title> + +<body> +<p> +The <c>metadata.xml</c> file is used to specify additional data about a +package or category. +</p> + +<section> +<title>Category Metadata</title> +<body> +<p> +For categories, <c>metadata.xml</c> specifies a long description (in +English and optionally in other languages). The format is specified +formally in <uri link="http://www.gentoo.org/proj/en/glep/glep-0034.html"> +GLEP 34</uri>, and the character set <b>must</b> be UTF-8 as specified +by <uri link="http://www.gentoo.org/proj/en/glep/glep-0031.html">GLEP +31</uri>. A typical example: +</p> + +<codesample lang="sgml"> + <?xml version="1.0" encoding="UTF-8"?> + <!DOCTYPE catmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> + <catmetadata> + <longdescription lang="en"> + The app-vim category contains plugins and syntax file + packages for the Vim text editor. + </longdescription> + <longdescription lang="de"> + Die Kategorie app-vim enthält Plugins und Syntax-Pakete + für den Vim Texteditor. + </longdescription> + </catmetadata> +</codesample> + +<p> +When creating a new category, creating a <c>metadata.xml</c> file +along with a <c><longdescription></c> in English is +<b>mandatory</b>. Translations are handled by any interested developer +who speaks a language sufficiently well. +</p> + +<p> +The correct way to commit a <e>category</e> <c>metadata.xml</c> file +is currently: +</p> + +<pre> +xmllint --noout --valid metadata.xml +glep31check metadata.xml +cvs commit -m "Adding category metadata.xml for my-category" metadata.xml +</pre> + +</body> +</section> + +<section> +<title>Package Metadata</title> +<body> +<p> +For packages, <c>metadata.xml</c> can specify a long description and +maintainer information. If a long description in any language is +provided, an English long description must be present. A typical +example might look like: +</p> + +<codesample lang="sgml"> + <?xml version="1.0" encoding="UTF-8"?> + <!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> + <pkgmetadata> + <herd>vim</herd> + <maintainer> + <email>ciaranm@gentoo.org</email> + <name>Ciaran McCreesh</name> + </maintainer> + <longdescription lang="en"> + This package provides Vim syntax highlighting for Cfengine configuration + files, and automatic filetype detection for these files based upon + filename. + </longdescription> + </pkgmetadata> +</codesample> + +<p> +All new packages <b>must</b> include a <c>metadata.xml</c> file which +specifies at <e>least</e> a herd. If no herd is suitable, <c>no-herd</c> +should be used, and at least one maintainer must be listed <d/> however, +if at all possible, find a herd willing to be listed. +</p> + +<p> +Commits of package metadata files are handled by <c>repoman</c>. You +should ensure that you have <c>dev-libs/libxml2</c> installed so that +the XML can be validated. +</p> + +</body> +</section> +</body> +</chapter> +</guide> diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml new file mode 100644 index 0000000..905b514 --- /dev/null +++ b/ebuild-writing/misc-files/patches/text.xml @@ -0,0 +1,104 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/misc-files/patches/"> +<chapter> +<title>Patches</title> + +<body> +<p> +There is no fixed rule for patch naming. The following are guidelines +only. +</p> + +<p> +Small patches (less than, say, a few KBytes) should be added to +<c>${FILESDIR}</c>. If you anticipate having several patches, it often +helps to create version numbered subdirectories <d/> <c>${FILESDIR}/${PV}/</c> +is conventional. Patches are best named <c>${P}-what-it-does.patch</c> (or +<c>.diff</c>), where <c>what-it-does</c> is a two or three word +description of what the patch is for. If the patch is to fix a +specific bug, it is often useful to add in the bug number <d/> for +example, <c>vim-7.0-cron-vars-79981.patch</c>. If the patch is pulled from +upstream's CVS / SVN repository, it can help to include the revision +number in the patch name as a suffix to the version part <d/> +<c>fluxbox-0.9.12-3860-menu-backups.patch</c>. +</p> + +<p> +Larger patches should be mirrored. When mirroring patches, choosing a +name that will not cause conflicts is important — the <c>${P}</c> +prefix is highly recommended here. Mirrored patches are often +compressed with <c>bzip2</c>. Remember to list these patches in +<c>SRC_URI</c>. +</p> + +<note> +Patches included in <c>${FILESDIR}</c> should never be compressed. +</note> + +<p> +If a package requires many patches, even if they are individually +small, it is often best to create a patch tarball to avoid cluttering +up the tree too much. +</p> + +<section> +<title>Patch Descriptions</title> +<body> +<p> +It is possible to include a description with a patch. This is often +helpful when others come to work with your packages, or, indeed when +you come back to take a look at your own package a few months +later. Good things to include in comments are: +</p> + +<ul> + <li> + What the patch actually does. Bug numbers are good here. + </li> + <li> + Where the patch came from. Is it an upstream CVS/SVN pull, + something from Bugzilla, something you wrote? + </li> + <li> + Whether the patch has been sent upstream, if applicable. + </li> +</ul> + +<p> +To include the description, simply insert it at the top of the patch +file. The <c>patch</c> tool will ignore leading text until it finds +something that looks like it might be a 'start patching' instruction, +so as long as each description line starts with letters (rather than +numbers, symbols or whitespace) there shouldn't be a +problem. Alternatively, prefix each description line with a hash +(that's <c>#</c>, or 'pound' to the USians) sign. It's also best to +leave a single blank line after the description and before the main +patch. +</p> + +<p> +Here's a simple example (<c>023_all_vim-6.3-apache-83565.patch</c>) +from the <c>vim</c> patch tarball: +</p> + +<pre> +# Detect Gentoo apache files properly. Gentoo bug 83565. + +--- runtime/filetype.vim.orig 2005-03-25 01:44:12.000000000 +0000 ++++ runtime/filetype.vim 2005-03-25 01:45:15.000000000 +0000 +@@ -93,6 +93,9 @@ + " Gentoo apache config file locations (Gentoo bug #76713) + au BufNewFile,BufRead /etc/apache2/conf/*/* setf apache + ++" More Gentoo apache config file locations (Gentoo bug #83565) ++au BufNewFile,BufRead /etc/apache2/{modules,vhosts}.d/*.conf setf apache ++ + " XA65 MOS6510 cross assembler + au BufNewFile,BufRead *.a65 setf a65 +</pre> + +</body> +</section> +</body> +</chapter> +</guide> diff --git a/ebuild-writing/misc-files/text.xml b/ebuild-writing/misc-files/text.xml new file mode 100644 index 0000000..31f1421 --- /dev/null +++ b/ebuild-writing/misc-files/text.xml @@ -0,0 +1,23 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/misc-files/"> +<chapter> +<title>Miscellaneous Files</title> + +<body> +<p> +This section contains some notes on various miscellaneous files. +</p> +</body> + +<section> +<title>Contents</title> +<body> +<contentsTree/> +</body> +</section> +</chapter> + +<include href="metadata/"/> +<include href="changelog/"/> +<include href="patches/"/> +</guide> diff --git a/general-concepts/mirrors/text.xml b/general-concepts/mirrors/text.xml index b3cae8c..db4c2c8 100644 --- a/general-concepts/mirrors/text.xml +++ b/general-concepts/mirrors/text.xml @@ -40,9 +40,9 @@ have a reliable mirror setup. <p> There is also <c>RESTRICT="fetch"</c>, which prevents portage from trying to -fetch anything manually. The `pkg_nofetch`_ function will be called if any -<c>SRC_URI</c> components cannot be found. This should only be used if a license -requires it. +fetch anything manually. The <uri link="::ebuild-writing/functions/pkg_nofetch"> +pkg_nofetch</uri> function will be called if any <c>SRC_URI</c> components cannot be +found. This should only be used if a license requires it. </p> </body> </subsection> |