diff options
Diffstat (limited to 'ebuild-writing')
106 files changed, 2482 insertions, 0 deletions
diff --git a/ebuild-writing/error-handling/error-handling-1.ebuild b/ebuild-writing/error-handling/error-handling-1.ebuild new file mode 100644 index 0000000..317029c --- /dev/null +++ b/ebuild-writing/error-handling/error-handling-1.ebuild @@ -0,0 +1,3 @@ +# Header + +[[ -f foorc ]] && ( update_foorc || die "Couldn't update foorc!" ) diff --git a/ebuild-writing/error-handling/error-handling-2.ebuild b/ebuild-writing/error-handling/error-handling-2.ebuild new file mode 100644 index 0000000..7ac1b45 --- /dev/null +++ b/ebuild-writing/error-handling/error-handling-2.ebuild @@ -0,0 +1,5 @@ +# Header + +if [[ -f foorc ]] ; then + update_foorc || die "Couldn't update foorc!" +fi diff --git a/ebuild-writing/error-handling/error-handling-3.ebuild b/ebuild-writing/error-handling/error-handling-3.ebuild new file mode 100644 index 0000000..daf667f --- /dev/null +++ b/ebuild-writing/error-handling/error-handling-3.ebuild @@ -0,0 +1,3 @@ +# Header + +cat list | while read file ; do epatch ${file} ; done diff --git a/ebuild-writing/error-handling/error-handling-4.ebuild b/ebuild-writing/error-handling/error-handling-4.ebuild new file mode 100644 index 0000000..ff45221 --- /dev/null +++ b/ebuild-writing/error-handling/error-handling-4.ebuild @@ -0,0 +1,3 @@ +# Header + +while read file ; do epatch ${file} ; done < list diff --git a/ebuild-writing/error-handling/error-handling-5.ebuild b/ebuild-writing/error-handling/error-handling-5.ebuild new file mode 100644 index 0000000..af0133f --- /dev/null +++ b/ebuild-writing/error-handling/error-handling-5.ebuild @@ -0,0 +1,4 @@ +# Header + +bunzip2 ${DISTDIR}/${VIM_RUNTIME_SNAP} | tar xf +assert diff --git a/ebuild-writing/error-handling/text.rst b/ebuild-writing/error-handling/text.rst new file mode 100644 index 0000000..5e27eab --- /dev/null +++ b/ebuild-writing/error-handling/text.rst @@ -0,0 +1,72 @@ +Error Handling +============== + +Importance of Error Handling +---------------------------- + +Decent error handling is important because: + +* Errors must be detected *before* portage tries to install a broken or + incomplete package onto the live filesystem. If build failures aren't caught, + a working package could be unmerged and replaced with nothing. + +* When receiving bug reports, it is a lot easier to figure out what went wrong + if you know exactly which function caused the error, rather than just knowing + that, say, something somewhere in ``src_compile`` broke. + +* Good error handling and notification can help cut down on the number of bug + reports received for a package. + +The ``die`` Function +-------------------- + +The ``die`` function should be used to indicate a fatal error and abort the +build. Its parameters should be the message to display. + +Although ``die`` will work with no parameters, a short message should always be +provided to ease error identification. This is especially important when a +function can die in multiple places. + +Some portage-provided functions will automatically die upon failure. Others will +not. It is safe to omit the ``|| die`` after a call to ``epatch``, but not +``econf`` or ``emake``. + +Sometimes displaying additional error information beforehand can be useful. Use +``eerror`` to do this. See `Messages`_. + +``die`` and Subshells +--------------------- + +.. Warning:: ``die`` **will not work in a subshell**. + +The following code will not work as expected, since the ``die`` is inside a +subshell: + +.. CODESAMPLE error-handling-1.ebuild + +The correct way to rewrite this is to use an ``if`` block: + +.. CODESAMPLE error-handling-2.ebuild + +When using pipes, a subshell is introduced, so the following is unsafe: + +.. CODESAMPLE error-handling-3.ebuild + +Using input redirection (see `Abuse of cat`_) avoids this problem: + +.. CODESAMPLE error-handling-4.ebuild + +The ``assert`` Function and ``$PIPESTATUS`` +------------------------------------------- + +When using pipes, simple conditionals and tests upon ``$?`` will not correctly +detect errors occurring in anything except the final command in the chain. To get +around this, ``bash`` provides the ``$PIPESTATUS`` variable, and portage +provides the ``assert`` function to check this variable. + +.. CODESAMPLE error-handling-5.ebuild + +If you need the gory details of ``$PIPESTATUS``, see `bash-1`_. Most of the +time, ``assert`` is enough. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/examples/text.rst b/ebuild-writing/examples/text.rst new file mode 100644 index 0000000..4975720 --- /dev/null +++ b/ebuild-writing/examples/text.rst @@ -0,0 +1,26 @@ +Further Ebuild Examples +======================= + +We'll finish the ebuild writing guide with a few examples. These are real +packages that the author has worked on that may or may not be in the tree -- +most of these are fairly simple apps that illustrate certain points nicely. + +Writing a ``detox`` Ebuild +-------------------------- + +.. Todo:: write this + + +Writing an ``msort`` Ebuild +--------------------------- + +.. Todo:: write this + + +Writing a ``hilite`` Ebuild +--------------------------- + +.. Todo:: write this + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/file-format/header-sample.ebuild b/ebuild-writing/file-format/header-sample.ebuild new file mode 100644 index 0000000..07b119f --- /dev/null +++ b/ebuild-writing/file-format/header-sample.ebuild @@ -0,0 +1,5 @@ +# Header + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ diff --git a/ebuild-writing/file-format/text.rst b/ebuild-writing/file-format/text.rst new file mode 100644 index 0000000..561a70a --- /dev/null +++ b/ebuild-writing/file-format/text.rst @@ -0,0 +1,78 @@ +Ebuild File Format +================== + +An ebuild is a ``bash`` script which is executed within a special environment. Files +should be simple text files with a ``.ebuild`` extension. + +File Naming Rules +----------------- + +An ebuild should be named in the form ``name-version.ebuild``. + +The name section should contain only lowercase non-accented letters, the digits +0-9, hyphens, underscores and plus characters. Uppercase characters are strongly +discouraged, but technically valid. + +.. Note:: This is the same as `IEEE1003.1-2004-3.276`_, with the addition of the plus + character to keep gtk+ and friends happy. + +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 +``1.2.3``, ``20050108``). The final number may have a single letter following it +(eg ``1.2b``). This letter should not be used to indicate 'beta' status -- +portage treats ``1.2b`` as being a later version than ``1.2`` or ``1.2a``. + +There can be a suffix to version indicating the kind of release. In the following table, what portage considers to be the 'lowest' version comes first. + +=============== =========================== +Suffix Meaning +=============== =========================== +``_alpha`` Alpha release (earliest) +``_beta`` Beta release +``_pre`` Pre release +``_rc`` Release candidate +(no suffix) Normal release +``_p`` Patch level +=============== =========================== + +Any of these suffixes may be followed by a non-zero positive integer. + +Finally, version may have a Gentoo revision number in the form ``-r1``. The initial +Gentoo version should have no revision suffix, the first revision should be +``-r1``, the second ``-r2`` and so on. See `Ebuild Revisions`_. + +Overall, this gives us a filename like ``libfoo-1.2.5b_pre5-r2.ebuild``. + +Ebuild Header +------------- + +All ebuilds committed to the tree should have a three line header immediately at +the start indicating copyright. This must be an exact copy of the contents of +``$(portageq portdir)/header.txt``. Ensure that the ``$Header: $`` line is not +modified manually -- CVS will handle this line specially. + +.. CODESAMPLE header-sample.ebuild + +Indenting and Whitespace +------------------------ + +Indenting in ebuilds must be done with tabs, one tab per indent level. Each tab +represents four spaces. Tabs should only be used for indenting, never inside +strings. + +Avoid trailing whitespace: repoman will warn you about this if your +ebuild contains trailing or leading whitespace (whitespace instead of +tabs for indentation) when you commit. + +Where possible, try to keep lines no wider than 80 positions. A 'position' is +generally the same as a character -- tabs are four positions wide, and multibyte +characters are just one position wide. + +Character Set +------------- + +All ebuilds (and eclasses, metadata files and ChangeLogs) must use the UTF-8 +character set. See `GLEP 31`_ for details, and `glep31check`_ for an easy way of +checking for validity. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. 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/pkg_config/pkg_config-1.ebuild b/ebuild-writing/functions/pkg_config/pkg_config-1.ebuild new file mode 100644 index 0000000..1c74945 --- /dev/null +++ b/ebuild-writing/functions/pkg_config/pkg_config-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_config() +{ + eerror "This ebuild does not have a config function." +} diff --git a/ebuild-writing/functions/pkg_config/pkg_config-2.ebuild b/ebuild-writing/functions/pkg_config/pkg_config-2.ebuild new file mode 100644 index 0000000..458569a --- /dev/null +++ b/ebuild-writing/functions/pkg_config/pkg_config-2.ebuild @@ -0,0 +1,16 @@ +# Headers. + +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 +} diff --git a/ebuild-writing/functions/pkg_config/text.rst b/ebuild-writing/functions/pkg_config/text.rst new file mode 100644 index 0000000..9622da2 --- /dev/null +++ b/ebuild-writing/functions/pkg_config/text.rst @@ -0,0 +1,30 @@ +pkg_config +========== + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_config`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Run any special post-install configuration | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | manual | ++------------------+---------------------------------------------------+ + +Default ``pkg_config`` +---------------------- + +.. CODESAMPLE pkg_config-1.ebuild + +Example ``pkg_config`` +---------------------- + +Taken from the ``mysql`` ebuilds. Note the use of ``${ROOT}``. + +.. CODESAMPLE pkg_config-2.ebuild + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-1.ebuild b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-1.ebuild new file mode 100644 index 0000000..e417c9b --- /dev/null +++ b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-1.ebuild @@ -0,0 +1,12 @@ +# Headers + +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 +} diff --git a/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-2.ebuild b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-2.ebuild new file mode 100644 index 0000000..179f780 --- /dev/null +++ b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-2.ebuild @@ -0,0 +1,8 @@ +# Headers + +pkg_nofetch() { + einfo "Please download" + einfo " - ${P}-main.tar.bz2" + einfo " - ${P}-extras.tar.bz2" + einfo "from ${HOMEPAGE} and place them in ${DISTDIR}" +} diff --git a/ebuild-writing/functions/pkg_nofetch/text.rst b/ebuild-writing/functions/pkg_nofetch/text.rst new file mode 100644 index 0000000..41c5c99 --- /dev/null +++ b/ebuild-writing/functions/pkg_nofetch/text.rst @@ -0,0 +1,35 @@ +pkg_nofetch +=========== + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_nofetch`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Tell the user how to deal with fetch-restricted | +| | packages. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Enabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild | ++------------------+---------------------------------------------------+ + +Default ``pkg_nofetch`` +----------------------- + +.. CODESAMPLE pkg_nofetch-1.ebuild + +Example ``pkg_nofetch`` +----------------------- + +.. CODESAMPLE pkg_nofetch-2.ebuild + +Notes on ``pkg_nofetch`` +------------------------ + +This function is only triggered for packages which have ``RESTRICT="fetch"`` +(see `Restricting Automatic Mirroring`_) set, and only if one or more components +listed in ``SRC_URI`` are not already available in the ``distfiles`` directory. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/pkg_postinst/pkg_postinst-1.ebuild b/ebuild-writing/functions/pkg_postinst/pkg_postinst-1.ebuild new file mode 100644 index 0000000..f4c376a --- /dev/null +++ b/ebuild-writing/functions/pkg_postinst/pkg_postinst-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_postinst() +{ + return +} diff --git a/ebuild-writing/functions/pkg_postinst/pkg_postinst-2.ebuild b/ebuild-writing/functions/pkg_postinst/pkg_postinst-2.ebuild new file mode 100644 index 0000000..1fbc039 --- /dev/null +++ b/ebuild-writing/functions/pkg_postinst/pkg_postinst-2.ebuild @@ -0,0 +1,13 @@ +# Headers. + +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 +} diff --git a/ebuild-writing/functions/pkg_postinst/text.rst b/ebuild-writing/functions/pkg_postinst/text.rst new file mode 100644 index 0000000..5f87394 --- /dev/null +++ b/ebuild-writing/functions/pkg_postinst/text.rst @@ -0,0 +1,35 @@ +pkg_postinst +============ + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_postinst`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Called after image is installed to ``${ROOT}`` | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild, binary | ++------------------+---------------------------------------------------+ + +Default ``pkg_postinst`` +------------------------ + +.. CODESAMPLE pkg_postinst-1.ebuild + +Sample ``pkg_postinst`` +----------------------- + +.. CODESAMPLE pkg_postinst-2.ebuild + +Common ``pkg_postinst`` Tasks +----------------------------- + +The most common use for ``pkg_postinst`` is to display post-install +informational messages or warnings. Note that ``has_version`` will operate on +the version that *was* installed, which can be useful for selective upgrade +messages. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/pkg_postrm/pkg_postrm-1.ebuild b/ebuild-writing/functions/pkg_postrm/pkg_postrm-1.ebuild new file mode 100644 index 0000000..83f20ca --- /dev/null +++ b/ebuild-writing/functions/pkg_postrm/pkg_postrm-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_postrm() +{ + return +} diff --git a/ebuild-writing/functions/pkg_postrm/pkg_postrm-2.ebuild b/ebuild-writing/functions/pkg_postrm/pkg_postrm-2.ebuild new file mode 100644 index 0000000..0abbd46 --- /dev/null +++ b/ebuild-writing/functions/pkg_postrm/pkg_postrm-2.ebuild @@ -0,0 +1,5 @@ +# Headers. + +pkg_postrm() { + fdo-mime_mime_database_update +} diff --git a/ebuild-writing/functions/pkg_postrm/text.rst b/ebuild-writing/functions/pkg_postrm/text.rst new file mode 100644 index 0000000..f878cc1 --- /dev/null +++ b/ebuild-writing/functions/pkg_postrm/text.rst @@ -0,0 +1,33 @@ +pkg_postrm +========== + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_postrm`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Called after a package is unmerged. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild, binary | ++------------------+---------------------------------------------------+ + +Default ``pkg_postrm`` +---------------------- + +.. CODESAMPLE pkg_postrm-1.ebuild + +Sample ``pkg_postrm`` +--------------------- + +.. CODESAMPLE pkg_postrm-2.ebuild + +Common ``pkg_postrm`` Tasks +--------------------------- + +``pkg_postrm`` is used to update symlinks, cache files and other generated +content after a package has been uninstalled. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/pkg_preinst/pkg_preinst-1.ebuild b/ebuild-writing/functions/pkg_preinst/pkg_preinst-1.ebuild new file mode 100644 index 0000000..107af7e --- /dev/null +++ b/ebuild-writing/functions/pkg_preinst/pkg_preinst-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_preinst() +{ + return +} diff --git a/ebuild-writing/functions/pkg_preinst/pkg_preinst-2.ebuild b/ebuild-writing/functions/pkg_preinst/pkg_preinst-2.ebuild new file mode 100644 index 0000000..32efaab --- /dev/null +++ b/ebuild-writing/functions/pkg_preinst/pkg_preinst-2.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_preinst() { + enewgroup foo + enewuser foo -1 /bin/false /dev/null foo +} diff --git a/ebuild-writing/functions/pkg_preinst/text.rst b/ebuild-writing/functions/pkg_preinst/text.rst new file mode 100644 index 0000000..b6d129e --- /dev/null +++ b/ebuild-writing/functions/pkg_preinst/text.rst @@ -0,0 +1,41 @@ +pkg_preinst +=========== + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_preinst`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Called before image is installed to ``${ROOT}`` | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild, binary | ++------------------+---------------------------------------------------+ + +Default ``pkg_preinst`` +----------------------- + +.. CODESAMPLE pkg_preinst-1.ebuild + +Sample ``pkg_preinst`` +---------------------- + +.. CODESAMPLE pkg_preinst-2.ebuild + +Common Tasks +------------ + +There are a few things that are often done in ``pkg_preinst``: + +* Adding users and groups -- see `Users and Groups`_ +* 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 -- a + ``pkg_preinst`` could check a configuration file in ``${ROOT}/etc/`` and + create a smart updated version in ``${IMAGE}/etc/`` (see `Install + Destinations`_) rather than always trying to install the default configuration + file (remember `Configuration File Protection`_). + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/pkg_prerm/pkg_prerm-1.ebuild b/ebuild-writing/functions/pkg_prerm/pkg_prerm-1.ebuild new file mode 100644 index 0000000..0ad76df --- /dev/null +++ b/ebuild-writing/functions/pkg_prerm/pkg_prerm-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_prerm() +{ + return +} diff --git a/ebuild-writing/functions/pkg_prerm/pkg_prerm-2.ebuild b/ebuild-writing/functions/pkg_prerm/pkg_prerm-2.ebuild new file mode 100644 index 0000000..c6fc71a --- /dev/null +++ b/ebuild-writing/functions/pkg_prerm/pkg_prerm-2.ebuild @@ -0,0 +1,6 @@ +# Headers + +pkg_prerm() { + # clean up temp files + [[ -d "${ROOT}/var/tmp/foo" ]] && rm -rf "${ROOT}/var/tmp/foo" +} diff --git a/ebuild-writing/functions/pkg_prerm/text.rst b/ebuild-writing/functions/pkg_prerm/text.rst new file mode 100644 index 0000000..3984806 --- /dev/null +++ b/ebuild-writing/functions/pkg_prerm/text.rst @@ -0,0 +1,33 @@ +pkg_prerm +========= + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_prerm`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Called before a package is unmerged. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild, binary | ++------------------+---------------------------------------------------+ + +Default ``pkg_prerm`` +--------------------- + +.. CODESAMPLE pkg_prerm-1.ebuild + +Sample ``pkg_prerm`` +-------------------- + +.. CODESAMPLE pkg_prerm-2.ebuild + +Common ``pkg_prerm`` Tasks +-------------------------- + +``pkg_prerm`` is used to clean up any files that would otherwise prevent a clean +unmerge. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/pkg_setup/pkg_setup-1.ebuild b/ebuild-writing/functions/pkg_setup/pkg_setup-1.ebuild new file mode 100644 index 0000000..978ac66 --- /dev/null +++ b/ebuild-writing/functions/pkg_setup/pkg_setup-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_setup() +{ + return +} diff --git a/ebuild-writing/functions/pkg_setup/pkg_setup-2.ebuild b/ebuild-writing/functions/pkg_setup/pkg_setup-2.ebuild new file mode 100644 index 0000000..280dd90 --- /dev/null +++ b/ebuild-writing/functions/pkg_setup/pkg_setup-2.ebuild @@ -0,0 +1,17 @@ +# Headers. + +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 +} diff --git a/ebuild-writing/functions/pkg_setup/text.rst b/ebuild-writing/functions/pkg_setup/text.rst new file mode 100644 index 0000000..e949cf9 --- /dev/null +++ b/ebuild-writing/functions/pkg_setup/text.rst @@ -0,0 +1,26 @@ +pkg_setup +========= + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_setup`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Pre-build environment configuration and checks. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild, binary | ++------------------+---------------------------------------------------+ + +Default ``pkg_setup`` +--------------------- + +.. CODESAMPLE pkg_setup-1.ebuild + +Example ``pkg_setup`` +--------------------- + +.. CODESAMPLE pkg_setup-2.ebuild + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_compile/buildenv/cpu-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/cpu-sample.ebuild new file mode 100644 index 0000000..22c9261 --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/cpu-sample.ebuild @@ -0,0 +1,4 @@ +# + + # Can't use ultrasparc or ultrasparc3 code, drop to v9 + replace-cpu-flags ultrasparc ultrasparc3 v9 diff --git a/ebuild-writing/functions/src_compile/buildenv/filter-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/filter-sample.ebuild new file mode 100644 index 0000000..0e19943 --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/filter-sample.ebuild @@ -0,0 +1,5 @@ +# + + # -fomit-frame-pointer leads to nasty broken code on sparc thanks to a + # rather icky asm function + use sparc && filter-flags -fomit-frame-pointer diff --git a/ebuild-writing/functions/src_compile/buildenv/ldflags-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/ldflags-sample.ebuild new file mode 100644 index 0000000..6968a8e --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/ldflags-sample.ebuild @@ -0,0 +1,7 @@ +# + + # If we're using selinux, we need to add a -D + use selinux && append-flags "-DWITH_SELINUX" + + # Secure linking needed, since we're setuid root + append-ldflags -Wl,-z,now diff --git a/ebuild-writing/functions/src_compile/buildenv/replace-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/replace-sample.ebuild new file mode 100644 index 0000000..c3c62e1 --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/replace-sample.ebuild @@ -0,0 +1,4 @@ +# + + # Seems to have issues with -Os, switch to -O2 + replace-flags -Os -O2 diff --git a/ebuild-writing/functions/src_compile/buildenv/strip-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/strip-sample.ebuild new file mode 100644 index 0000000..13b9628 --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/strip-sample.ebuild @@ -0,0 +1,4 @@ +# + + # Our app hates screwy flags + strip-flags diff --git a/ebuild-writing/functions/src_compile/buildenv/text.rst b/ebuild-writing/functions/src_compile/buildenv/text.rst new file mode 100644 index 0000000..d0718d7 --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/text.rst @@ -0,0 +1,78 @@ +Configuring Build Environment +============================= + +Sometimes it is necessary to manipulate certain aspects of the user's build +environment before running ``./configure``. The ``flag-o-matic`` eclass is the +best choice for manipulating ``CFLAGS``, ``LDFLAGS`` and suchlike. + +.. Note:: Except where otherwise specified, any function which operates on + ``CFLAGS`` also operates on ``CXXFLAGS``. + +Ebuilds must not simply ignore use ``CFLAGS`` -- see `Not Filtering Variables`_. + +Guidelines for Flag Filtering +----------------------------- + +If a package breaks with any reasonable ``CFLAGS``, it is best to filter the +problematic flag if a bug report is received. Reasonable ``CFLAGS`` are +``-march=``, ``-mcpu=``, ``-mtune=`` (depending upon arch), ``-O2``, ``-Os`` and +``-fomit-frame-pointer``. Note that ``-Os`` should usually be replaced with +``-O2`` rather than being stripped entirely. The ``-fstack-protector`` flag +should probably be in this group too, although our hardened team claim that this +flag never ever breaks anything... + +The ``-pipe`` flag doesn't affect the generated code, so it's not really +relevant here, but it's a sensible flag to have set globally. + +If a package breaks with other ``CFLAGS``, it is perfectly ok to close the bug +with a **WONTFIX** suggesting that the user picks more sensible global +``CFLAGS``. Similarly, if you suspect that a bug is caused by insane CFLAGS, an +**INVALID** resolution is suitable. + +All of the following assumes that the ebuild has an ``inherit flag-o-matic`` +line in the correct place. + +Simple Flag Stripping +--------------------- + +The ``filter-flags`` function can be used to remove a particular flag from +``CFLAGS``. Multiple arguments can be supplied; each is the name of a flag to +remove. + +.. CODESAMPLE filter-sample.ebuild + +There is a ``filter-ldflags`` function available which does the equivalent for +``LDFLAGS``. + +If a package is known to be very ``CFLAGS`` sensitive, the ``strip-flags`` +function will remove most flags, leaving only a minimal conservative set of +flags. + +.. CODESAMPLE strip-sample.ebuild + +Flag Replacement +---------------- + +To replace a flag with a different one, use ``replace-flags``. This is most +commonly used to replace ``-Os`` with ``-O2`` (or ``-O3`` with ``-O2`` if you +are feeling kind). + +.. CODESAMPLE replace-sample.ebuild + +There is also a special function named ``replace-cpu-flags`` for replacing CPU +(``-mtune``, ``-mcpu``, ``-march``) designation flags. The last argument is the +flag to use; previous arguments are the flags to be replaced. + +.. CODESAMPLE cpu-sample.ebuild + +Adding Additional Flags +----------------------- + +Sometimes it is necessary to add in additional ``CFLAGS`` or ``LDFLAGS``. The +``append-flags`` and ``append-ldflags`` functions can be used here. + +.. CODESAMPLE ldflags-sample.ebuild + +See `flag-o-matic.eclass Reference`_ for a full reference. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_compile/configure/text.rst b/ebuild-writing/functions/src_compile/configure/text.rst new file mode 100644 index 0000000..f717df3 --- /dev/null +++ b/ebuild-writing/functions/src_compile/configure/text.rst @@ -0,0 +1,30 @@ +Configuring a Package +===================== + +Many packages come with an autoconf-generated ``./configure`` script for +checking the build environment and configuring optional support for libraries. +The ``econf`` function should be used where possible -- this will provide +correct build and path specifications for a Gentoo environment. + +Often the configure script will try to automatically enable support for optional +components based upon installed packages. This must **not** be allowed to +happen. For example, if a user has ``perl`` installed but has ``USE="-perl"``, +packages with optional ``perl`` support must not link against ``perl``. This +automatic detection can usually be overridden using ``--enable-`` and +``--disable`` or ``--with-`` and ``--without-`` switches (but note that these +don't always work -- make sure these are tested properly). + +The ``use_enable`` and ``use_with`` utility functions should, where appropriate, +be used to generate these switches. + +.. CODESAMPLE use-sample.ebuild + +Sometimes the package's choice of name for the option will not exactly match the +name or case of the ``USE`` flag. This is *very* often the case with the ``X`` +flag. For these situations, there are two argument forms: + +.. CODESAMPLE use2-sample.ebuild + +To check for an unset ``USE`` flag, the ``use_enable !flag`` form can be used. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_compile/configure/use-sample.ebuild b/ebuild-writing/functions/src_compile/configure/use-sample.ebuild new file mode 100644 index 0000000..1127543 --- /dev/null +++ b/ebuild-writing/functions/src_compile/configure/use-sample.ebuild @@ -0,0 +1,21 @@ +# + +src_compile() { + # We have optional perl, python and ruby support + econf \ + $(use_enable perl ) \ + $(use_enable python ) \ + $(use_enable ruby ) \ + || die "Configure failed!" + + # ... +} + +src_compile() { + # Our package optional IPv6 support which uses --with rather than + # --enable / --disable + + econf $(use_with ipv6 ) || die "econf failed!" + + # ... +} diff --git a/ebuild-writing/functions/src_compile/configure/use2-sample.ebuild b/ebuild-writing/functions/src_compile/configure/use2-sample.ebuild new file mode 100644 index 0000000..fee17c3 --- /dev/null +++ b/ebuild-writing/functions/src_compile/configure/use2-sample.ebuild @@ -0,0 +1,16 @@ +# + +src_compile() { + # Our package has optional perl, python and ruby support + econf \ + $(use_enable perl perlinterp ) \ + $(use_enable python pythoninterp ) \ + $(use_enable ruby rubyinterp ) \ + || die "Configure failed!" + + # ... +} + +src_compile() { + econf $(use_with X x11 ) || die "econf failed!" +} diff --git a/ebuild-writing/functions/src_compile/default-sample.ebuild b/ebuild-writing/functions/src_compile/default-sample.ebuild new file mode 100644 index 0000000..cec696e --- /dev/null +++ b/ebuild-writing/functions/src_compile/default-sample.ebuild @@ -0,0 +1,10 @@ +# + +src_compile() { + if [ -x ./configure ]; then + econf + fi + if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then + emake || die "emake failed" + fi +} diff --git a/ebuild-writing/functions/src_compile/distutils/distutils-1.ebuild b/ebuild-writing/functions/src_compile/distutils/distutils-1.ebuild new file mode 100644 index 0000000..d2806bf --- /dev/null +++ b/ebuild-writing/functions/src_compile/distutils/distutils-1.ebuild @@ -0,0 +1,5 @@ +# Headers. + +inherit distutils + +DOCS="CHANGES" diff --git a/ebuild-writing/functions/src_compile/distutils/distutils-2.ebuild b/ebuild-writing/functions/src_compile/distutils/distutils-2.ebuild new file mode 100644 index 0000000..25cbfc9 --- /dev/null +++ b/ebuild-writing/functions/src_compile/distutils/distutils-2.ebuild @@ -0,0 +1,17 @@ +# Headers. + +src_compile() { + distutils_src_compile + # ... +} + +src_install() { + # From the docutils ebuild + distutils_src_install + cd ${S}/tools + for tool in *.py; do + newbin ${tool} docutils-${tool} + done + + # ... +} diff --git a/ebuild-writing/functions/src_compile/distutils/distutils-3.ebuild b/ebuild-writing/functions/src_compile/distutils/distutils-3.ebuild new file mode 100644 index 0000000..3115bcd --- /dev/null +++ b/ebuild-writing/functions/src_compile/distutils/distutils-3.ebuild @@ -0,0 +1,5 @@ +# Headers + +pkg_setup() { + distutils_python_tkinter +} diff --git a/ebuild-writing/functions/src_compile/distutils/text.rst b/ebuild-writing/functions/src_compile/distutils/text.rst new file mode 100644 index 0000000..54ae12f --- /dev/null +++ b/ebuild-writing/functions/src_compile/distutils/text.rst @@ -0,0 +1,42 @@ +Distutils +========= + +General overview +---------------- + +The python packaging system is known as "distutils", and the hallmark of a +python package using distutils is the presence of a ``setup.py`` file. +(One can think of the ``setup.py`` file as the python equivalent of a +Makefile.) Although distutils is straightforward to use by directly +running the ``setup.py`` with the appropriate arguments, the distutils +eclass makes the process much simpler (and dramatically lowers the chance of +sandbox violations). For example, for the ``dev-python/id3-py`` package the +body of the e-build (other than the header and URIs) could have been +written as: + +.. CODESAMPLE distutils-1.ebuild + +Any files listed in ``${DOCS}`` will be put in the docs directory when +installed. Note that older versions of the distutils eclass used +``${mydoc}`` instead, but the preferred variable is ``DOCS``. + +In practice, some tweaking is often required in the ``src_compile()`` or, +more commonly, in the ``src_install()`` steps, and the distutils eclass +provides ``distutils_src_compile()`` and ``distutils_src_install()`` +convenience functions: + +.. CODESAMPLE distutils-2.ebuild + +Tkinter (Tk) support +-------------------- + +Until portage gains the long-requested ability to depend on USE +flags, ebuild authors who package graphical python programs will +probably need to check at emerge-time whether or not python was +compiled with support for Tkinter. Since Tkinter requires Tk, +which requires X, default python builds do *not* include Tkinter. +It's easy enough to check: + +.. CODESAMPLE distutils-3.ebuild + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : diff --git a/ebuild-writing/functions/src_compile/make/getcc-sample.ebuild b/ebuild-writing/functions/src_compile/make/getcc-sample.ebuild new file mode 100644 index 0000000..c8eaf8e --- /dev/null +++ b/ebuild-writing/functions/src_compile/make/getcc-sample.ebuild @@ -0,0 +1,14 @@ +# + +inherit flag-o-matic toolchain-funcs + +src_compile() { + # -Os not happy + replace-flags -Os -O2 + + # We have a weird build.sh to work with which ignores our + # compiler preferences. yay! + sed -i -e "s:cc -O2:$(tc-getCC) ${CFLAGS}:" build.sh \ + || die "sed Fix failed. Uh-oh..." + ./build.sh || die "Build failed!" +} diff --git a/ebuild-writing/functions/src_compile/make/text.rst b/ebuild-writing/functions/src_compile/make/text.rst new file mode 100644 index 0000000..2128e92 --- /dev/null +++ b/ebuild-writing/functions/src_compile/make/text.rst @@ -0,0 +1,40 @@ +Building +======== + +The ``emake`` function should be used to call ``make``. This will ensure that +the user's ``MAKEOPTS`` are used correctly. The ``emake`` function passes on +any arguments provided, so it can be used to make non-default targets (``emake +extras``), for example. Occasionally you might encounter a screwy non-autotools +``Makefile`` that explodes with ``emake``, but this is rare. + +Builds should be tested with various ``-j`` settings in ``MAKEOPTS`` to ensure +that the build parallelises properly. If a package does *not* parallelise +cleanly, it should be patched. + +If patching *really* isn't an option, ``emake -j1`` should be used. However, +when doing this please remember that you are seriously hurting build times for +many non-x86 users in particular. Forcing a ``-j1`` can increase build times +from a few minutes to an hour on some MIPS and SPARC systems. + +Fixing Compiler Usage +--------------------- + +Sometimes a package will try to use a bizarre compiler, or will need to be told +which compiler to use. In these situations, the ``tc-getCC()`` function from +``toolchain-funcs.eclass`` should be used. Other similar functions are available +-- these are documented in `toolchain-funcs.eclass-5`_. + +.. Note:: It is *not* correct to use the ``${CC}`` variable for this purpose. + +Sometimes a package will not use the user's ``${CFLAGS}``. This must be worked +around, as sometimes this variable is used for specifying critical ABI options. +In these cases, the build scripts should be modified (for example, with ``sed``) +to use ``${CFLAGS}`` correctly. + +.. CODESAMPLE getcc-sample.ebuild + +.. Note:: When using ``sed`` with ``CFLAGS``, it is not safe to use a comma or a + slash as a delimiter. The vapier-recommended character is a colon. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-1.ebuild b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-1.ebuild new file mode 100644 index 0000000..45d9d17 --- /dev/null +++ b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +src_compile() { + $(tc-getCC ) ${CFLAGS} -o ${PN} ${P}.c \ + || die "Compile failed!" +} diff --git a/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-2.ebuild b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-2.ebuild new file mode 100644 index 0000000..c38adb3 --- /dev/null +++ b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-2.ebuild @@ -0,0 +1,11 @@ +# Headers. + +src_compile() { + CONFIG="-DLINUX -DGKRELLM2 -fPIC `pkg-config gtk+-2.0 --cflags`" + LIBS="`pkg-config gtk+-2.0 --libs` -shared" + OBJS="top_three2.o gkrelltop2.o" + + gcc -c $CONFIG $CFLAGS top_three.c -o top_three2.o || die + gcc -c $CONFIG $CFLAGS gkrelltop.c -o gkrelltop2.o || die + gcc $LIBS $CONFIG $CFLAGS -o gkrelltop2.so $OBJS || die +} diff --git a/ebuild-writing/functions/src_compile/nobuildsystem/text.rst b/ebuild-writing/functions/src_compile/nobuildsystem/text.rst new file mode 100644 index 0000000..7fed9c9 --- /dev/null +++ b/ebuild-writing/functions/src_compile/nobuildsystem/text.rst @@ -0,0 +1,19 @@ +No Build System +=============== + +Occasionally some really small packages are shipped simply as a single ``.c`` file. +In these circumstances, you can either write your own ``Makefile`` and ship it +with the source tarball, or just manually compile the thing from within the +ebuild. Here's an example, from ``app-misc/hilite``: + +.. CODESAMPLE nobuildsystem-1.ebuild + +Here's an example from ``x11-plugins/gkrelltop``, which ships with a +``Makefile`` that doesn't actually work: + +.. CODESAMPLE nobuildsystem-2.ebuild + +A possibly better alternative would be to patch the ``Makefile`` and send it +upstream. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_compile/sample-sample.ebuild b/ebuild-writing/functions/src_compile/sample-sample.ebuild new file mode 100644 index 0000000..12182c3 --- /dev/null +++ b/ebuild-writing/functions/src_compile/sample-sample.ebuild @@ -0,0 +1,13 @@ +# + +src_compile() { + use sparc && filter-flags -fomit-frame-pointer + append-ldflags -Wl,-z,now + + econf \ + $(use_enable ssl ) \ + $(use_enable perl perlinterp ) \ + || die "Configure failed!" + + emake || die "Make failed!" +} diff --git a/ebuild-writing/functions/src_compile/text.rst b/ebuild-writing/functions/src_compile/text.rst new file mode 100644 index 0000000..6e70721 --- /dev/null +++ b/ebuild-writing/functions/src_compile/text.rst @@ -0,0 +1,36 @@ +src_compile +=========== + ++------------------+---------------------------------------------------+ +| **Function** | ``src_compile`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Configure and build the package. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Enabled | ++------------------+---------------------------------------------------+ +| **Privilege** | user | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild | ++------------------+---------------------------------------------------+ + +Default ``src_compile`` +----------------------- + +.. CODESAMPLE default-sample.ebuild + +Sample ``src_compile`` +---------------------- + +.. CODESAMPLE sample-sample.ebuild + + +Build Processes +--------------- + +Depending upon the build process used by upstream, there are a number of +possible things that may be done during ``src_compile``: + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_install/src_install-1.ebuild b/ebuild-writing/functions/src_install/src_install-1.ebuild new file mode 100644 index 0000000..8f927a0 --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-1.ebuild @@ -0,0 +1,7 @@ +# Headers. + +src_install() +{ + return +} + diff --git a/ebuild-writing/functions/src_install/src_install-2.ebuild b/ebuild-writing/functions/src_install/src_install-2.ebuild new file mode 100644 index 0000000..c185882 --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-2.ebuild @@ -0,0 +1,6 @@ +# Headers. + +src_install() { + make DESTDIR="${D}" install || die "Install failed!" + dodoc README CHANGES +} diff --git a/ebuild-writing/functions/src_install/src_install-3.ebuild b/ebuild-writing/functions/src_install/src_install-3.ebuild new file mode 100644 index 0000000..d0abd9b --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-3.ebuild @@ -0,0 +1,3 @@ +# Headers. + + make DESTDIR="${D}" install || die "Install failed" diff --git a/ebuild-writing/functions/src_install/src_install-4.ebuild b/ebuild-writing/functions/src_install/src_install-4.ebuild new file mode 100644 index 0000000..ae493a2 --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-4.ebuild @@ -0,0 +1,3 @@ +# Headers. + + einstall || die "Install failed!" diff --git a/ebuild-writing/functions/src_install/src_install-5.ebuild b/ebuild-writing/functions/src_install/src_install-5.ebuild new file mode 100644 index 0000000..e827aff --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-5.ebuild @@ -0,0 +1,4 @@ +# Headers. + + dodir /usr/share/foo-styles/ + cp -R ${S}/ ${D}/ || die "Install failed!" diff --git a/ebuild-writing/functions/src_install/src_install-6.ebuild b/ebuild-writing/functions/src_install/src_install-6.ebuild new file mode 100644 index 0000000..d6cb68b --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-6.ebuild @@ -0,0 +1,50 @@ +# Headers. + +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 +} diff --git a/ebuild-writing/functions/src_install/text.rst b/ebuild-writing/functions/src_install/text.rst new file mode 100644 index 0000000..3e61a65 --- /dev/null +++ b/ebuild-writing/functions/src_install/text.rst @@ -0,0 +1,72 @@ +src_install +=========== + ++------------------+---------------------------------------------------+ +| **Function** | ``src_install`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Install a package image to ``${D}`` | ++------------------+---------------------------------------------------+ +| **Sandbox** | Enabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild | ++------------------+---------------------------------------------------+ + +Default ``src_install`` +----------------------- + +.. CODESAMPLE src_install-1.ebuild + +Sample ``src_install`` +---------------------- + +.. CODESAMPLE src_install-2.ebuild + +Easy Installs +------------- + +Often, especially with autotools-powered packages, there is a ``Makefile`` +``install`` target which will honour the ``DESTDIR`` variable to tell it to +install to a non-root location. If possible, this should be used: + +.. CODESAMPLE src_install-3.ebuild + +.. Note:: ``make`` should be used over ``emake`` here. Most installs are not + designed to be parallelised. + +Sometimes this will end up installing a few things into strange places. If and +only if this is the case, the ``einstall`` function can be used: + +.. CODESAMPLE src_install-4.ebuild + +It is usually necessary to include additional ``dodoc`` statements for the +``README``, ``ChangeLog`` etc in these cases. + +Trivial Installs +---------------- + +For some packages with no ``Makefile`` that only install a small number of +files, writing a manual install using ``cp`` is the easiest option. For example, +to do a simple install of some (no compilation required) themes: + +.. CODESAMPLE src_install-5.ebuild + +Or sometimes a combination of ``insinto`` and ``doins`` (plus related functions +-- see `Install Functions Reference`_) -- the following is based upon the +``sys-fs/udev`` install: + +.. CODESAMPLE src_install-6.ebuild + +This is, of course, considerably harder to handle than a simple ``Makefile`` +driven install. + +Other Installs +-------------- + +Sometimes, there will be a ``Makefile`` that does not honour ``DESTDIR`` and a +non-trivial number of files to install. In these situations, it is best to patch +the ``Makefile`` and contact upstream explaining the situation to them. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_test/default-sample.ebuild b/ebuild-writing/functions/src_test/default-sample.ebuild new file mode 100644 index 0000000..17fc795 --- /dev/null +++ b/ebuild-writing/functions/src_test/default-sample.ebuild @@ -0,0 +1,22 @@ +# + +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%:/}" +} diff --git a/ebuild-writing/functions/src_test/sample-sample.ebuild b/ebuild-writing/functions/src_test/sample-sample.ebuild new file mode 100644 index 0000000..b22bfa4 --- /dev/null +++ b/ebuild-writing/functions/src_test/sample-sample.ebuild @@ -0,0 +1,12 @@ +# + +src_compile() { + 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" +} diff --git a/ebuild-writing/functions/src_test/text.rst b/ebuild-writing/functions/src_test/text.rst new file mode 100644 index 0000000..4e37b24 --- /dev/null +++ b/ebuild-writing/functions/src_test/text.rst @@ -0,0 +1,64 @@ +src_test +======== + ++------------------+---------------------------------------------------+ +| **Function** | ``src_test`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Run pre-install test scripts. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Enabled | ++------------------+---------------------------------------------------+ +| **Privilege** | user | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild | ++------------------+---------------------------------------------------+ + +Default ``src_test`` +-------------------- + +.. CODESAMPLE default-sample.ebuild + +Sample ``src_test`` +------------------- + +.. CODESAMPLE sample-sample.ebuild + +Common ``src_test`` Tasks +------------------------- + +Often the default ``src_test`` 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: + +* Needing to use X. +* Needing to work with files which are disallowed by the sandbox. +* Requiring user input (``src_test`` must not be interactive). +* Requiring root privileges. + +Usually, removing the relevant test from the ``Makefile`` using ``sed`` or +skipping a particular ``make`` target is sufficient. + +.. Note:: ``emake`` should not be used for ``src_test`` -- trying to parallelise + tests unless the ``Makefile`` was specifically designed for this can cause all + sorts of strange problems. + +Try to ensure that tests work properly for your ebuild. A good test suite is +extremely helpful for arch maintainers. + +Skipping Tests +-------------- + +Sometimes it is necessary to skip tests entirely. This can be done using a dummy +``src_test`` function: + +.. CODESAMPLE true-sample.ebuild + +Another option would be to set ``RESTRICT="test"`` in the ebuild. + +.. 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. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_test/true-sample.ebuild b/ebuild-writing/functions/src_test/true-sample.ebuild new file mode 100644 index 0000000..6569c49 --- /dev/null +++ b/ebuild-writing/functions/src_test/true-sample.ebuild @@ -0,0 +1,6 @@ +# + +src_test() { + # Tests don't even remotely work inside portage + true +} diff --git a/ebuild-writing/functions/src_unpack/autopackage/text.rst b/ebuild-writing/functions/src_unpack/autopackage/text.rst new file mode 100644 index 0000000..dbefa92 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/autopackage/text.rst @@ -0,0 +1,27 @@ +Autopackage +=========== + +If a package is only supplied in autopackage format, you must **not** add it to +the tree, nor go anywhere near it. If a package is supplied in autopackage +format and some other sane standard format (for example a source tarball), use +the other format only. + +Autopackage packages are utterly unsuitable for Gentoo systems for a worryingly +large number of reasons: + +* To even *unpack* the package, you must run arbitrary code supplied by an + untrusted source. +* They install directly to the live filesystem. +* Their intrinsic dependency resolver is broken. +* They do not support the filesystem layout used by Gentoo. +* They do not support configuration protection. +* They can clobber arbitrary files on uninstall. +* The linking mechanism used is insufficiently flexible. +* The entire format is completely unportable and highly tied to x86 Linux + systems. + +Upstream are aware of these issues and have no desire to fix them -- indeed, +they pass off some of their most broken behaviour as 'features'. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_unpack/cvs/cvs-1.ebuild b/ebuild-writing/functions/src_unpack/cvs/cvs-1.ebuild new file mode 100644 index 0000000..ca4d64d --- /dev/null +++ b/ebuild-writing/functions/src_unpack/cvs/cvs-1.ebuild @@ -0,0 +1,19 @@ +# Headers. + +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 +} diff --git a/ebuild-writing/functions/src_unpack/cvs/cvs-2.ebuild b/ebuild-writing/functions/src_unpack/cvs/cvs-2.ebuild new file mode 100644 index 0000000..71f23c7 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/cvs/cvs-2.ebuild @@ -0,0 +1,14 @@ +# Headers. + +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. diff --git a/ebuild-writing/functions/src_unpack/cvs/text.rst b/ebuild-writing/functions/src_unpack/cvs/text.rst new file mode 100644 index 0000000..52d464f --- /dev/null +++ b/ebuild-writing/functions/src_unpack/cvs/text.rst @@ -0,0 +1,76 @@ +CVS Sources +=========== + +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. + +Disadvantages of CVS Sources +---------------------------- + +Note that CVS ebuilds should **not** generally be added to the tree (except +under ``package.mask``) for the following reasons: + +* Upstream CVS servers tend to be far less reliable than our mirroring system + (particularly if we're talking Sourceforge...). + +* CVS ebuilds create a very heavy server load -- 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. + +* Many users who are behind firewalls cannot use CVS. + +It is safer to make a snapshot instead. For example, ``vim`` snapshots are made +using: :: + + $ cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vim export -r HEAD vim + +Disadvantages of CVS Live Sources +--------------------------------- + +CVS ebuilds which work against ``HEAD`` rather than a specific date or revision +are even worse candidates for tree inclusion: + +* You can never be sure whether upstream's CVS will actually build at any given + point. + +* It is extremely difficult to track down bugs when you cannot install the same + version of a package as the reporter. + +* Many upstream packages tend to get upset if people aren't using a specific + released version. + +Using CVS Sources +----------------- + +To use a CVS source, ``cvs.eclass`` must be inherited, and then a number of +variables must be set. The following variables are often useful: + +================= ================ ======================== +Variable Purpose Example +================= ================ ======================== +``ECVS_SERVER`` Server and path ``"cvs.sourceforge.net:/cvsroot/vim"`` +``ECVS_MODULE`` Module ``"vim"`` +``ECVS_BRANCH`` Branch ``"HEAD"`` +``ECVS_AUTH`` Auth method ``"ext"`` +``ECVS_USER`` Username ``"anoncvs"`` +``ECVS_PASS`` Password ``""`` +``ECVS_TOPDIR`` Unpack location ``ECVS_TOP_DIR="${DISTDIR}/cvs-src/${ECVS_MODULE}"`` +================= ================ ======================== + +See the eclass itself for the full range of options. + +Then, to perform the actual checkout, use the ``cvs_src_unpack`` function. + +Here's a simple snippet, based upon the CVS options in ``vim.eclass``: + +.. CODESAMPLE cvs-1.ebuild + +Here's another approach, based upon the ``emacs-cvs`` ebuild, which relies upon +the default ``src_unpack`` provided in the eclass: + +.. CODESAMPLE cvs-2.ebuild + +This approach is simpler but less flexible. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_unpack/deb/text.rst b/ebuild-writing/functions/src_unpack/deb/text.rst new file mode 100644 index 0000000..e2f8edb --- /dev/null +++ b/ebuild-writing/functions/src_unpack/deb/text.rst @@ -0,0 +1,16 @@ +Deb Sources +=========== + +.. Todo:: write this. 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 / + + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/ebuild-writing/functions/src_unpack/epatch/epatch-1.ebuild b/ebuild-writing/functions/src_unpack/epatch/epatch-1.ebuild new file mode 100644 index 0000000..59c5e9e --- /dev/null +++ b/ebuild-writing/functions/src_unpack/epatch/epatch-1.ebuild @@ -0,0 +1,8 @@ +# Headers. + +src_unpack() { + unpack ${A} + cd ${S} + epatch ${FILESDIR}/${P}-destdir.patch + epatch ${FILESDIR}/${P}-parallel_build.patch +} diff --git a/ebuild-writing/functions/src_unpack/epatch/epatch-2.ebuild b/ebuild-writing/functions/src_unpack/epatch/epatch-2.ebuild new file mode 100644 index 0000000..5e9345d --- /dev/null +++ b/ebuild-writing/functions/src_unpack/epatch/epatch-2.ebuild @@ -0,0 +1,8 @@ +# Headers. + +src_unpack() { + unpack ${P}.tar.bz2 + cd ${S} + epatch ${DISTDIR}/${P}-suse-update.patch.bz2 + epatch ${FILESDIR}/${PV}-no-TIOCGDEV.patch +} diff --git a/ebuild-writing/functions/src_unpack/epatch/epatch-3.ebuild b/ebuild-writing/functions/src_unpack/epatch/epatch-3.ebuild new file mode 100644 index 0000000..42e0387 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/epatch/epatch-3.ebuild @@ -0,0 +1,8 @@ +# Headers. + +src_unpack() { + unpack ${A} + cd ${S} + EPATCH_SOURCE="${WORKDIR}/patches" EPATCH_SUFFIX="patch" \ + EPATCH_FORCE="yes" epatch +} diff --git a/ebuild-writing/functions/src_unpack/epatch/text.rst b/ebuild-writing/functions/src_unpack/epatch/text.rst new file mode 100644 index 0000000..287c45b --- /dev/null +++ b/ebuild-writing/functions/src_unpack/epatch/text.rst @@ -0,0 +1,69 @@ +Patching with ``epatch`` +======================== + +The canonical way of applying patches in ebuilds is to use ``epatch`` (from +``eutils.eclass``) inside ``src_unpack``. This function automatically handles +``-p`` levels, ``gunzip`` and so on as necessary. + +Note that distributing modified tarballs rather than a vanilla tarball and +patches is *highly* discouraged. + +Basic ``epatch`` Usage +---------------------- + +In its simplest form, ``epatch`` takes a single filename and applies that patch. +It will automatically ``die`` if the apply fails. The following is taken from +``app-misc/detox``: + +.. CODESAMPLE epatch-1.ebuild + +For larger patches, using ``mirror://gentoo/`` rather than ``files/`` is more +appropriate. In these situations, it is usually best to ``bzip2`` the patch in +question (as opposed to ``files/`` patches, which must **not** be compressed). +For example, from ``app-admin/showconsole``: + +.. CODESAMPLE epatch-2.ebuild + +Remember to add the patch to ``SRC_URI``. + +CVS Keyword Lines and Patches +''''''''''''''''''''''''''''' + +If your patch includes any changes to CVS ``$Id: $`` (or ``$Header: $``, or +``$Date: $``) lines, it cannot be distributed under ``files/``, since CVS will +clobber the patch when you commit. In these situations, either remove this hunk +of the patch manually, or mirror the file. + +Multiple Patches with ``epatch`` +-------------------------------- + +``epatch`` can also apply multiple patches (which can be selectively based upon +arch) from a single directory. This can be useful if upstream have a habit of +shipping severely broken releases that need dozens of patches. + +A simple example: + +.. CODESAMPLE epatch-3.ebuild + +Here, one of the ``SRC_URI`` components is a tarball containing many patches +with file extension ``.patch``. + +Variables which may be defined include: + +======================== ===================================================== +Variable Purpose +======================== ===================================================== +``EPATCH_SOURCE`` Specifies the directory in which ``epatch`` looks for + patches. +``EPATCH_SUFFIX`` File extension for patches. +``EPATCH_OPTS`` Default options to ``patch``. +``EPATCH_EXCLUDE`` List of patches to exclude. +``EPATCH_FORCE`` Force epatch to apply patches even if they do not + follow the canonical naming form (set to ``yes``). +======================== ===================================================== + +Bulk patches should be named in the form ``??_${ARCH}_foo.${EPATCH_SUFFIX}``. If +they are not, ``EPATCH_FORCE="yes"`` must be set. To apply a patch on all archs, +use ``all`` for the ``${ARCH}`` part. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_unpack/other-archive-formats/text.rst b/ebuild-writing/functions/src_unpack/other-archive-formats/text.rst new file mode 100644 index 0000000..b30d968 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/other-archive-formats/text.rst @@ -0,0 +1,28 @@ +Other Archive Formats +===================== + +There are a variety of other archive formats which you may encounter. + +Zip Files +--------- + +If a package is supplied as a ``.zip`` file, you should: + +* ``DEPEND`` upon ``app-arch/unzip`` +* Use ``unpack`` as normal + +Shar Files +---------- + +If a package is supplied as a ``.shar`` file, you should repackage it locally +into a ``.tar.bz2``. It may also be useful to ask upstream to use a friendlier +package format -- however, if they ship ``.shar``, chances are they haven't done +a release in at least ten years. + +RAR Files +--------- + +``.rar`` files must be repackaged locally into a ``.tar.bz2`` file. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_unpack/rpm/rpm-1.ebuild b/ebuild-writing/functions/src_unpack/rpm/rpm-1.ebuild new file mode 100644 index 0000000..4839e23 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/rpm/rpm-1.ebuild @@ -0,0 +1,3 @@ +# Headers. + +inherit rpm diff --git a/ebuild-writing/functions/src_unpack/rpm/rpm-2.ebuild b/ebuild-writing/functions/src_unpack/rpm/rpm-2.ebuild new file mode 100644 index 0000000..446bc6c --- /dev/null +++ b/ebuild-writing/functions/src_unpack/rpm/rpm-2.ebuild @@ -0,0 +1,8 @@ +# Headers. + +src_unpack () { + rpm_src_unpack ${A} + cd ${S} + + use ssl && epatch ${FILESDIR}/${PV}/${P}-ssl.patch +} diff --git a/ebuild-writing/functions/src_unpack/rpm/rpm-3.ebuild b/ebuild-writing/functions/src_unpack/rpm/rpm-3.ebuild new file mode 100644 index 0000000..d818c75 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/rpm/rpm-3.ebuild @@ -0,0 +1,39 @@ +# Headers. + +# 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 +} diff --git a/ebuild-writing/functions/src_unpack/rpm/text.rst b/ebuild-writing/functions/src_unpack/rpm/text.rst new file mode 100644 index 0000000..bbb4a53 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/rpm/text.rst @@ -0,0 +1,50 @@ +RPM Sources +=========== + +If a package is supplied as an .rpm file, you should: + +.. CODESAMPLE rpm-1.ebuild + + +If you don't need to do anything in the unpack phase, then you are finished as +the ``rpm.eclass`` exports a default ``src_unpack`` that will unpack the rpm +files. + +If you do need to apply patches then override ``src_unpack`` in a manner such +as: + +.. CODESAMPLE rpm-2.ebuild + +.. Note:: ``${A}`` can contain non-rpm files since the rpm eclass will call + the normal ``unpack`` function for files that are not in the rpm format. + + +Notes on Using ``rpm.eclass`` +----------------------------- + +There are two ways to unpack a rpm file -- using the ``rpmoffset`` program from +``rpm2targz`` and ``cpio``, or by using ``rpm2cpio`` from ``app-arch/rpm``. +Normally, for unpacking an rpm file, installing the entire rpm application is +overkill. Because of this, the eclass will only use ``rpm2cpio`` if ``rpm`` is +already installed on the system. If you want to force the eclass to only use +the rpm offset method, set ``USE_RPMOFFSET_ONLY=1``. + +Another issue that might arise is that ``rpmoffset`` and ``cpio`` are not able +to unpack the rpm file correctly. If this occurs, then you need to add +``app-arch/rpm`` to the ``DEPEND`` variable so that ``rpm2cpio`` will be used +instead. + +Example RPM Handling +-------------------- + +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 ``ebuild unpack`` +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 +``suse-fetchmail-6.2.5.54.1.ebuild``. + +.. CODESAMPLE rpm-3.ebuild + +Completion of the ebuild left as exercise to the reader. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_unpack/src_unpack-1.ebuild b/ebuild-writing/functions/src_unpack/src_unpack-1.ebuild new file mode 100644 index 0000000..1cc9c25 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/src_unpack-1.ebuild @@ -0,0 +1,7 @@ +# Headers. + +src_unpack() { + if [ "${A}" != "" ]; then + unpack ${A} + fi +} diff --git a/ebuild-writing/functions/src_unpack/src_unpack-2.ebuild b/ebuild-writing/functions/src_unpack/src_unpack-2.ebuild new file mode 100644 index 0000000..21018ef --- /dev/null +++ b/ebuild-writing/functions/src_unpack/src_unpack-2.ebuild @@ -0,0 +1,11 @@ +# Headers. + +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!" +} diff --git a/ebuild-writing/functions/src_unpack/svn/svn-1.ebuild b/ebuild-writing/functions/src_unpack/svn/svn-1.ebuild new file mode 100644 index 0000000..13ab1a7 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/svn/svn-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +inherit subversion + +ESVN_REPO_URI="http://tao.uab.es/ion/svn/libtu/trunk" +ESVN_PROJECT="libtu-snapshot" diff --git a/ebuild-writing/functions/src_unpack/svn/text.rst b/ebuild-writing/functions/src_unpack/svn/text.rst new file mode 100644 index 0000000..dcb5c84 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/svn/text.rst @@ -0,0 +1,59 @@ +Subversion Sources +================== + +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. + +Disavantages of Subversion Sources +---------------------------------- + +Note that Subversion ebuilds should **not** generally be added to the tree +(except under ``package.mask``) for much the same reasons that live CVS ebuilds +should not (see `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. + +It is far safer to make a snapshot instead. For example, ``gentoo-syntax`` +snapshots could be (but aren't, because ciaranm is so lazy he automated it) +made using: :: + + $ svn export svn://svn.berlios.de/svnroot/repos/gentoo-syntax -r HEAD gentoo-syntax + +Disadvantages of Subversion Live Sources +---------------------------------------- + +Live Subversion ebuilds that work against ``HEAD`` have the same disadvantages +as Live CVS ebuilds. + +Using Subversion Sources +------------------------ + +To use a Subversion source, ``subversion.eclass`` must be inherited, and then at +least ``ESVN_REPO_URI`` must be set. The following variables are also noteworthy: + +=================== ========================================= ================ +Variable Purpose Example +=================== ========================================= ================ +``ESVN_REPO_URI`` Server and path (http, https, svn) ``"svn://svn.example.com/foobar/trunk"`` +``ESVN_STORE_DIR`` Unpack location ``ESVN_STORE_DIR="${DISTDIR}/svn-src"`` +``ESVN_PROJECT`` Project name of ebuild ``ESVN_PROJECT="${PN/-svn}"`` +``ESVN_BOOTSTRAP`` Bootstrap command or script ``ESVN_BOOTSTRAP="autogen.sh"`` +``ESVN_PATCHES`` Patches to apply during bootstrap ``ESVN_PATCHES="${FILESDIR}/*.patch"`` +=================== ========================================= ================ + +See the eclass itself and `subversion.eclass Reference`_ for the full range of +options. + +To perform the actual checkout, use the ``subversion_src_unpack`` function, +which calls both ``subversion_svn_fetch`` and ``subversion_bootstrap`` itself. + +Here is a simple snippet, based upon the Subversion options in +``litu-svn-20040902.ebuild``: + +.. CODESAMPLE svn-1.ebuild + +This approach is sufficient for most Subversion ebuilds. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_unpack/text.rst b/ebuild-writing/functions/src_unpack/text.rst new file mode 100644 index 0000000..ba6060d --- /dev/null +++ b/ebuild-writing/functions/src_unpack/text.rst @@ -0,0 +1,47 @@ +src_unpack +========== + ++------------------+---------------------------------------------------+ +| **Function** | ``src_unpack`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Extract source packages and do any necessary | +| | patching or fixes. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Enabled | ++------------------+---------------------------------------------------+ +| **Privilege** | user | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild | ++------------------+---------------------------------------------------+ + +Default ``src_unpack`` +---------------------- + +.. CODESAMPLE src_unpack-1.ebuild + +Sample ``src_unpack`` +--------------------- + +.. CODESAMPLE src_unpack-2.ebuild + +Unpacking Tarballs +------------------ + +The ``unpack`` function should be used to unpack tarballs, compressed files and +so on. Do not use ``tar``, ``gunzip`` etc. manually. + +The ``${A}`` variable contains all of the ``SRC_URI`` components, except for any +which are excluded by USE-based conditionals inside ``SRC_URI`` itself. If +multiple archives require unpacking in a particular order it is usually simpler +to avoid working with ``${A}``. + +``src_unpack`` Actions +---------------------- + +The following subsections cover different topics which often occur when writing +``src_unpack`` functions. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_unpack/tla/text.rst b/ebuild-writing/functions/src_unpack/tla/text.rst new file mode 100644 index 0000000..d8ce2a6 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/tla/text.rst @@ -0,0 +1,8 @@ +Arch Sources +============ + +.. Todo:: anyone want to write this? You can probably mostly copy the `CVS + Sources`_ and `Subversion Sources`_ chapters. -- ciaranm + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/text.rst b/ebuild-writing/functions/text.rst new file mode 100644 index 0000000..b76c975 --- /dev/null +++ b/ebuild-writing/functions/text.rst @@ -0,0 +1,22 @@ +Ebuild Functions +================ + +When installing packages from source, the function call order is ``pkg_setup``, +``src_unpack``, ``src_compile``, ``src_test`` (optional, ``FEATURES="test"``), +``src_install``, ``pkg_preinst``, ``pkg_postinst``. When installing packages +from a binary, the function call order is ``pkg_setup``, ``pkg_preinst``, +``pkg_postinst``. + +.. figure:: diagram.png + :alt: ebuild function call order + +The ``pkg_prerm`` and ``pkg_postrm`` functions are called when uninstalling a +package. The ``pkg_config`` function is used for any special package +configuration -- it is only run when explicitly requested by the user. The +``pkg_nofetch`` function is used when a ``RESTRICT="fetch"`` package needs to +obtain some ``SRC_URI`` components. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/messages/messages-1.ebuild b/ebuild-writing/messages/messages-1.ebuild new file mode 100644 index 0000000..d567370 --- /dev/null +++ b/ebuild-writing/messages/messages-1.ebuild @@ -0,0 +1,7 @@ +# Headers + +pkg_postinst() { + einfo "You will need to set up your /etc/foo/foo.conf file before" + einfo "running foo for the first time. For details, please see the" + einfo "foo.conf(5) manual page." +} diff --git a/ebuild-writing/messages/messages-2.ebuild b/ebuild-writing/messages/messages-2.ebuild new file mode 100644 index 0000000..b7c000f --- /dev/null +++ b/ebuild-writing/messages/messages-2.ebuild @@ -0,0 +1,6 @@ +# Headers + +i=10 +while ((i--)) ; do + ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass" +done diff --git a/ebuild-writing/messages/messages-3.ebuild b/ebuild-writing/messages/messages-3.ebuild new file mode 100644 index 0000000..c1ab4e4 --- /dev/null +++ b/ebuild-writing/messages/messages-3.ebuild @@ -0,0 +1,8 @@ +# Headers + +ewarn "The 'frozbinate' function provided by eutils.eclass is deprecated" +ewarn "in favour of frozbinate.eclass, but this package has not been" +ewarn "updated yet. If this is a package from the main tree, please check" +ewarn "http://bugs.gentoo.org/ and file a bug if there is not one already." +ewarn "If this is your own package, please read the comments in the" +ewarn "frozbinate eclass for instructions on how to convert." diff --git a/ebuild-writing/messages/text.rst b/ebuild-writing/messages/text.rst new file mode 100644 index 0000000..53dd41d --- /dev/null +++ b/ebuild-writing/messages/text.rst @@ -0,0 +1,78 @@ +Messages +======== + +Sometimes it is necessary to display messages for the user. This can be for +errors, post-install help messages, pre-install warnings or simply to notify the +user of what's going on. It is considered good form to display a message +before any particularly long and silent task is carried out, for example (and it +also helps cut down on bogus "compiling foo froze!" bugs). + +.. Note:: It is a policy violation to use any of these functions to display a line + of characters (a banner header). The use of colours and special leading + characters provided by these functions is sufficient to make a message stand + out. + +In all cases, assume that the user's terminal is no wider than 79 columns, and +that the ``einfo``, ``ewarn`` and ``eerror`` functions will occupy 4 columns +with their fancy leading markers. + +Information Messages +-------------------- + +There are a number of functions available to assist here. The `echo` bash +internal is the simplest -- it simply displays its parameters as a message. + +The ``einfo`` function can be used to display an informational message which is +meant to 'stand out'. On a colour terminal, the message provided will be +prefixed with a green star. + +.. CODESAMPLE messages-1.ebuild + +Warning Messages +---------------- + +The ``ewarn`` function is similar, but displays a yellow star. This should be +used for warning messages rather than information. + +Error Messages +-------------- + +The ``eerror`` function displays a red star, and is used for displaying error +messages. It should almost always be followed by a ``die`` call. This function +is mainly used for displaying additional error details before bailing out. + +Important Messages +------------------ + +For *really* important messages, ``eutils.eclass`` provides ``ebeep`` and +``epause``. The former will beep a number of times, and the latter will pause +for several seconds to allow the user to read any messages. Both can be disabled +by the user -- you must **not** attempt to override the user's preference in +this. ``ebeep`` takes an optional parameter specifying how many times to beep. +``epause`` takes an optional parameter (which **must** be an exact whole number) +specifying for how long it should sleep. + +Do not abuse these functions -- better to save them for when things really are +important. + +See `Message Functions Reference`_ for a full list of functions. + +Good and Bad Messages +--------------------- + +Here is an example of a bad message: + +.. CODESAMPLE messages-2.ebuild + +* Displaying the same message repeatedly is excessive. +* The uppercase is excessive. +* The bad English looks unprofessional. +* The message will only confuse the end user and will not help them work out + whether they have a problem and how to solve it if they do. + +It would be better written as: + +.. CODESAMPLE messages-3.ebuild + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/misc-files/changelog/changelog b/ebuild-writing/misc-files/changelog/changelog new file mode 100644 index 0000000..96fa791 --- /dev/null +++ b/ebuild-writing/misc-files/changelog/changelog @@ -0,0 +1,10 @@ +# vim: set filetype=gentoo-changelog : + + *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 diff --git a/ebuild-writing/misc-files/changelog/text.rst b/ebuild-writing/misc-files/changelog/text.rst new file mode 100644 index 0000000..c54eff8 --- /dev/null +++ b/ebuild-writing/misc-files/changelog/text.rst @@ -0,0 +1,23 @@ +ChangeLog +========= + +.. _echangelog: .. + +The ``ChangeLog`` should be used to record all non-trivial changes to ebuilds, +*including keywording changes*. The `echangelog`_ tool should be used to create +``ChangeLog`` entries -- the format of a ``ChangeLog`` is now defined as +"whatever ``echangelog`` creates". + +You should include references to any relevant bugs. The standard format for +doing this is via the phrase ``bug #20600`` -- this format (with the hash sign +included) is recognised via `packages.gentoo.org <http://packages.gentoo.org/>`_ +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 -- some users prefer to be known only by a +nickname). + +A typical ``ChangeLog`` snippet might look like the following: + +.. CODESAMPLE changelog + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/misc-files/metadata/catmetadata.xml b/ebuild-writing/misc-files/metadata/catmetadata.xml new file mode 100644 index 0000000..0edec7e --- /dev/null +++ b/ebuild-writing/misc-files/metadata/catmetadata.xml @@ -0,0 +1,15 @@ +# Header + + <?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> + diff --git a/ebuild-writing/misc-files/metadata/pkgmetadata.xml b/ebuild-writing/misc-files/metadata/pkgmetadata.xml new file mode 100644 index 0000000..deccd06 --- /dev/null +++ b/ebuild-writing/misc-files/metadata/pkgmetadata.xml @@ -0,0 +1,16 @@ +# Header + + <?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> diff --git a/ebuild-writing/misc-files/metadata/text.rst b/ebuild-writing/misc-files/metadata/text.rst new file mode 100644 index 0000000..82c1699 --- /dev/null +++ b/ebuild-writing/misc-files/metadata/text.rst @@ -0,0 +1,47 @@ +Package and Category metadata.xml +================================= + +The ``metadata.xml`` file is used to specify additional data about a package or +category. + +Category Metadata +----------------- + +For categories, ``metadata.xml`` specifies a long description (in English and +optionally in other languages). The format is specified formally in `GLEP 34`_, +and the character set **must** be UTF-8 as specified by `GLEP 31`_. A typical +example: + +.. CODESAMPLE catmetadata.xml + + +When creating a new category, creating a ``metadata.xml`` file along with a +``<longdescription>`` in English is **mandatory**. Translations are handled by +any interested developer who speaks a language sufficiently well. + +The correct way to commit a *category* ``metadata.xml`` file is currently: :: + + xmllint --noout --valid metadata.xml + glep31check metadata.xml + cvs commit -m "blah" metadata.xml + +Package Metadata +---------------- + +For packages, ``metadata.xml`` 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: + +.. CODESAMPLE pkgmetadata.xml + + +All new packages **must** include a ``metadata.xml`` file which specifies *at +least* a herd. If no herd is suitable, ``no-herd`` should be used, and at least +one maintainer **must** be listed -- however, if at all possible, find a herd +willing to be listed. + +Commits of package metadata files are handled by ``repoman``. You should ensure +that you have ``dev-libs/libxml2`` installed so that the XML can be validated. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/misc-files/patches/sample-patch.patch b/ebuild-writing/misc-files/patches/sample-patch.patch new file mode 100644 index 0000000..7408c3c --- /dev/null +++ b/ebuild-writing/misc-files/patches/sample-patch.patch @@ -0,0 +1,17 @@ +# Header + +# 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 + + diff --git a/ebuild-writing/misc-files/patches/text.rst b/ebuild-writing/misc-files/patches/text.rst new file mode 100644 index 0000000..b0c754d --- /dev/null +++ b/ebuild-writing/misc-files/patches/text.rst @@ -0,0 +1,54 @@ +Patches +======= + +There is no fixed rule for patch naming. The following are guidelines only. + +Small patches (less than, say, a few KBytes) should be added to ``${FILESDIR}``. +If you anticipate having several patches, it often helps to create version +numbered subdirectories -- ``${FILESDIR}/${PV}/`` is conventional. Patches are +best named ``${P}-what-it-does.patch`` (or ``.diff``), where +``what-it-does`` 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 +-- for example, ``vim-7.0-cron-vars-79981.patch``. 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 -- +``fluxbox-0.9.12-3860-menu-backups.patch``. + +Patches included in ``${FILESDIR}`` should not be compressed. + +Larger patches should be mirrored. When mirroring patches, choosing a name that +will not cause conflicts is important -- the ``${P}`` prefix is highly +recommended here. Mirrored patches are often compressed with ``bzip2``. Remember +to list these patches in ``SRC_URI``. + +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. + +Patch Descriptions +------------------ + +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: + +* What the patch actually does. Bug numbers are good here. +* Where the patch came from. Is it an upstream CVS/SVN pull, something from + Bugzilla, something you wrote? +* Whether the patch has been sent upstream. + +To include the description, simply insert it at the top of the patch file. The +``patch`` 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 +``#``, or 'pound' to the USians) sign. It's also best to leave a single blank +line after the description and before the main patch. + +Here's a simple example (``023_all_vim-6.3-apache-83565.patch``) from the +``vim`` patch tarball: + +.. CODESAMPLE sample-patch.patch + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/misc-files/text.rst b/ebuild-writing/misc-files/text.rst new file mode 100644 index 0000000..63e2d5c --- /dev/null +++ b/ebuild-writing/misc-files/text.rst @@ -0,0 +1,9 @@ +Miscellaneous Files +=================== + +This section contains some notes on various miscellaneous files. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/text.rst b/ebuild-writing/text.rst new file mode 100644 index 0000000..afcffde --- /dev/null +++ b/ebuild-writing/text.rst @@ -0,0 +1,11 @@ +Ebuild Writing +============== + +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. + +.. FULLCHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/use-conditional-code/text.rst b/ebuild-writing/use-conditional-code/text.rst new file mode 100644 index 0000000..adef71d --- /dev/null +++ b/ebuild-writing/use-conditional-code/text.rst @@ -0,0 +1,28 @@ +USE Flag Conditional Code +========================= + +Often a particular block of code must only be executed if a given USE flag is +set (or unset). For large blocks, ``if use foo`` is best, or for inverse tests +either ``if ! use foo`` or ``if use !foo`` can be used (the former is more +common and is recommended for readability). For single-statement conditions, the +``use foo && blah`` (or ``use foo || blah`` for negatives) form is often more +readable. + +The ``if [ "`use foo`" ]`` and ``if [ -n "`use foo`" ]`` forms which are +occasionally seen in older code must **not** be used. + +.. Note:: ``die`` will not work as expected within a subshell, so code in the + form ``use foo && ( blah ; blah )`` should be avoided in favour of a proper if + statement. See `die and Subshells`_. + +.. CODESAMPLE use-sample.ebuild + +For echoing content based upon a USE flag, there is often a better helper +function available. + +You must not rely upon ``use`` producing an output -- this no longer happens. +If you really need output displayed, use the ``usev`` function. The +``useq`` function is available for explicitly requesting no output. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/use-conditional-code/use-sample.ebuild b/ebuild-writing/use-conditional-code/use-sample.ebuild new file mode 100644 index 0000000..26f2fca --- /dev/null +++ b/ebuild-writing/use-conditional-code/use-sample.ebuild @@ -0,0 +1,21 @@ +# header + + # USE conditional blocks... + if use livecd ; then + # remove some extra files for a small livecd install + rm -fr ${vimfiles}/{compiler,doc,ftplugin,indent} + fi + + # Inverse USE conditional blocks... + if ! use cscope ; then + # the --disable-cscope configure arg doesn't quite work properly, + # so sed it out of feature.h if we're not USEing cscope. + sed -i -e '/# define FEAT_CSCOPE/d' src/feature.h || die "couldn't disable cscope" + fi + + # USE conditional statements... + use ssl && epatch ${FILESDIR}/${P}-ssl.patch + use sparc && filter-flags -fomit-frame-pointer + + # Inverse USE conditional statements... + use ncurses || epatch ${FILESDIR}/${P}-no-ncurses.patch diff --git a/ebuild-writing/users-and-groups/text.rst b/ebuild-writing/users-and-groups/text.rst new file mode 100644 index 0000000..d805533 --- /dev/null +++ b/ebuild-writing/users-and-groups/text.rst @@ -0,0 +1,51 @@ +Users and Groups +================ + +If your ebuild requires a user or group to be added for a daemon, for example, +this should be performed via the functions available in ``eutils.eclass``. +Regardless of whether you are adding a group or a user, this should be performed +in the ``pkg_setup`` function and **not** somewhere else: pkg_setup is sandbox-safe, +is called before the compile process so a build that requires the user to exist will +have it, and is also called for both binary and source packages. + +Adding Groups +------------- + +To add a group, use the ``enewgroup`` function: :: + + enewgroup <name> [uid] + +By default the next available group ID is selected. To set a specfic group ID, +pass it an extra argument to ``enewgroup``. + +.. Note:: Group IDs should rarely be hardcoded. If this is the case, you should + probably check first on gentoo-dev. + +Adding Users +------------ + +To add a user, use the ``enewuser`` function: :: + + enewuser <user> [uid] [shell] [homedir] [groups] [params] + +By default, both ``enewuser`` and ``enewgroup`` allocate the next available user +ID or group ID to the new user or group - if not, you explicitly have to specify +one. + +Arguments for ``enewuser`` must be passed in the order as shown above: if you do +not want to specify a fixed user ID however but do want to set a specific shell, +for example, use ``-1`` for the ``uid`` parameter. The same applies for any other +parameter where you want to keep the default setting. + +Groups for the ``groups`` argument should be separated by a comma (``,``) and +wrapped correctly, for example: :: + + enewuser frozd -1 -1 -1 "backup,frozd" + +Finally, any data left over for the ``params`` argument is passed directly to +useradd. + +.. Note:: User IDs should rarely be hardcoded. If this is the case, you should + probably check first on gentoo-dev. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/using-eclasses/devtodo.ebuild b/ebuild-writing/using-eclasses/devtodo.ebuild new file mode 100644 index 0000000..28386be --- /dev/null +++ b/ebuild-writing/using-eclasses/devtodo.ebuild @@ -0,0 +1,49 @@ +# Header + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +inherit eutils bash-completion flag-o-matic + +DESCRIPTION="A nice command line todo list for developers" +HOMEPAGE="http://swapoff.org/DevTodo" +SRC_URI="http://swapoff.org/files/${PN}/${P}.tar.gz" + +LICENSE="GPL-2" +SLOT="0" +KEYWORDS="alpha amd64 arm hppa ia64 mips ppc s390 sparc x86 ppc64" +IUSE="" + +RDEPEND=">=sys-libs/ncurses-5.2 + >=sys-libs/readline-4.1" +DEPEND="${RDEPEND}" + +src_unpack() { + unpack ${A} + cd ${S} + epatch ${FILESDIR}/${P}-gentoo.diff +} + +src_compile() { + einfo "Running autoreconf" + autoreconf -f -i || die "autoreconf failed" + replace-flags -O? -O1 + econf --sysconfdir=/etc/devtodo || die "econf failed" + emake || die "emake failed" +} + +src_install() { + make DESTDIR=${D} install || die "make install failed" + dodoc AUTHORS ChangeLog QuickStart README TODO doc/scripts.sh \ + doc/scripts.tcsh doc/todorc.example contrib/tdrec || die "dodoc failed" + dobashcompletion ${FILESDIR}/${PN}.bash-completion ${PN} +} + +pkg_postinst() { + echo + einfo "Because of a conflict with app-misc/tdl, the tdl symbolic link" + einfo "and manual page have been removed." + bash-completion_pkg_postinst +} + diff --git a/ebuild-writing/using-eclasses/text.rst b/ebuild-writing/using-eclasses/text.rst new file mode 100644 index 0000000..b8abf7d --- /dev/null +++ b/ebuild-writing/using-eclasses/text.rst @@ -0,0 +1,33 @@ +Using Eclassses +=============== + +An eclass is a collection (library) of functions or functionality that is shared +between packages. See `Eclass Writing Guide`_ for the full story on what +eclasses can do, how they work and how to write them, and `Eclass Reference`_ +for documentation on various commonly used eclasses. This section only explains +how to use an eclass which has already been written. + +The ``inherit`` Function +------------------------ + +To use an eclass, it must be 'inherited'. This is done via the ``inherit`` +function, which is provided by ``ebuild.sh``. The ``inherit`` statement must +come at the top of the ebuild, *before* any functions. Conditional inherits are +illegal (except where the inheritance criteria are cache-constant -- see `The +Portage Cache`_). + +After inheriting an eclass, its provided functions can be used as normal. Here's +``devtodo-0.1.18-r2.ebuild``, which uses three eclasses: + +.. CODESAMPLE devtodo.ebuild + +Note the ``inherit`` immediately after the header. + +The ``eutils`` eclass (see `eutils.eclass Reference`_) is needed to get the +``epatch`` function. The ``flag-o-matic`` eclass (see `flag-o-matic.eclass +Reference`_) is needed for ``replace-flags``, and the ``bash-completion`` eclass +(`bash-completion.eclass Reference`_) is used to handle the bash completion file +via ``dobashcompletion`` and ``bash-completion_pkg_postinst``. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/variables/text.rst b/ebuild-writing/variables/text.rst new file mode 100644 index 0000000..1d6c06c --- /dev/null +++ b/ebuild-writing/variables/text.rst @@ -0,0 +1,187 @@ +Variables +========= + +There are a number of special variables which must be set in ebuilds, and many +more which can optionally be specified. There are also some predefined variables +which are of use throughout the ebuild. + +Predefined Read-Only Variables +------------------------------ + +The following variables are defined for you. You must not attempt to set +them. + +============= ======================================================= +Variable Purpose +============= ======================================================= +``P`` Package name and version (excluding revision, if any), for example ``vim-6.3`` +``PN`` Package name, for example ``vim`` +``PV`` Package version (excluding revision, if any), for example ``6.3`` +``PR`` Package revision, or ``r0`` if no revision exists. +``PVR`` Package version and revision, for example ``6.3-r0``, ``6.3-r1``. +``PF`` Package name, version and revision, for example + ``vim-6.3-r1`` +``A`` All the source files for the package (excluding those + which are not available because of ``USE`` flags) +``CATEGORY`` Package's category, for example ``app-editors``. +``FILESDIR`` Path to the ebuild's ``files/`` directory, commonly used + for small patches and files. Value: + ``"${PORTDIR}/${CATEGORY}/${PN}/files"``. +``WORKDIR`` Path to the ebuild's root build directory. Value: + ``"${PORTAGE_TMPDIR}/portage/${PF}/work"``. +``T`` Path to a temporary directory which may be used by the + ebuild. Value: ``"${PORTAGE_TMPDIR}/portage/${PF}/temp"`` +``D`` Path to the temporary install directory. Value: + ``"${PORTAGE_TMPDIR}/portage/${PF}/image"`` +``ROOT`` Path to the root directory. When not using ``${D}``, + always prepend ``${ROOT}`` to the path. +============= ======================================================= + +Required Variables +------------------ + +The following variables must be defined by every ebuild. + +====================== ======================================================= +Variable Purpose +====================== ======================================================= +``DESCRIPTION`` A short (less than 80 characters) description of the + package's purpose. +``SRC_URI`` A list of source URIs for the package. Can contain + ``USE``-conditional parts, see `SRC_URI`_. +``HOMEPAGE`` Package's homepage +``KEYWORDS`` See `KEYWORDS`_ and `Keywording`_. +``SLOT`` The package's ``SLOT``. See `SLOT`_. +``LICENSE`` The package's licence, corresponding exactly (including + case) to a file in ``licenses/``. See `LICENSE`_. +``IUSE`` A list of all ``USE`` flags (excluding arch and auto + expand flags) used within the ebuild. See `IUSE`_. +====================== ======================================================= + +Optional Variables +------------------ + +Specifying the following variables is optional: + +====================== ======================================================= +Variable Purpose +====================== ======================================================= +``S`` Path to the temporary build directory, used by + ``src_compile`` and ``src_install``. Default: + ``"${WORKDIR}/${P}"``. Ebuilds should **not** provide a + value for this ebuild if it is the default. +``DEPEND`` A list of the package's build dependencies. See + `Dependencies`_. +``RDEPEND`` A list of the package's runtime dependencies. See + `Dependencies`_. +``PDEPEND`` A list of packages to be installed after the package + is merged. Should only be used where ``RDEPEND`` is not + possible. See `Dependencies`_. +``RESTRICT`` A space-delimited list of portage features to restrict. + Valid values are ``nostrip``, ``nomirror``, ``nouserpriv`` + and ``fetch``. See `ebuild-5`_ for details. +``PROVIDE`` Any virtuals provided by this package, for example + ``"virtual/editor virtual/emacs"``. +====================== ======================================================= + +SLOT +---- + +When slots are not needed, use ``SLOT="0"``. Do **not** use ``SLOT=""``, as +this will disable slotting for this package. + +KEYWORDS +-------- + +The only valid construct involving a ``*`` inside ``KEYWORDS`` is a ``-*``. Do +**not** use ``KEYWORDS="*"`` or ``KEYWORDS="~*"``. + +See `Keywording`_ for how to handle this variable. + +SRC_URI +------- + +Conditional Sources +''''''''''''''''''' + +Conditional source files based upon USE flags are allowed using the usual +``flag? ( )`` syntax. This is often useful for arch-specific code or for binary +packages -- downloading sparc binaries on ppc would be a waste of bandwidth. + +.. CODESAMPLE variables-1.ebuild + +When creating digests it may be necessary to have *all* SRC_URI components +downloaded. If you have ``FEATURES="cvs"`` set, portage should get this right, +although you may end up downloading more than necessary. + +If a ``USE_EXPAND`` variable is used to control whether certain optional +components are installed, the correct thing to do if the variable is unset is +generally to install *all* available components. + +.. CODESAMPLE variables-2.ebuild + +IUSE +---- + +Note that the ``IUSE`` variable is cumulative, so there is no need to specify +USE flags used only within inherited eclasses within the ebuild's IUSE. Also +note that it's really really broken in portage versions before 2.0.51. + +Arch USE flags (``sparc``, ``mips``, ``x86-fbsd`` and so on) should not be +listed. Neither should auto-expand flags (``linguas_en`` and so on). + +LICENSE +------- + +It is possible to specify multiple ``LICENSE`` entries, and entries which only +apply if a particular ``USE`` flag is set. The format is the same as for +``DEPEND``. See `GLEP 23`_ for details. + +Version Formatting Issues +------------------------- + +Often upstream's tarball versioning format doesn't quite follow Gentoo +conventions. Differences in how underscores and hyphens are used are +particularly common. For example, what Gentoo calls ``foo-1.2.3b`` may be +expecting a tarball named ``foo-1.2-3b.tar.bz2``. Rather than hard coding version +numbers, it is preferable to make a ``MY_PV`` variable and use that. The easy +way to do this, which should be used unless you are sure you know what you are +doing, is to use the ``versionator`` eclass: + +.. CODESAMPLE variables-3.ebuild + +This code has the advantage that it will carry on working even if upstream +switches to a format like ``foo-1.3-4.5.tar.bz2`` (yes, this really happens). + +It is also possible to use bash substitution to achieve the same effect (this is +how versionator works internally), but this is complicated, error prone and hard +to read. + +Some ebuilds use calls to ``sed``, ``awk`` and / or ``cut`` to do this. This +must *not* be done for any new code, and should be fixed to use either +versionator or bash substitution where possible. Global scope non-bash code is +highly discouraged. + +The ``versionator`` eclass can also be used to extract particular components +from a version string. See `versionator.eclass-5`_ and the eclass source code +for further documentation and examples. A brief summary of the functions +follows. + +==================================== ======================================== +Function Purpose +==================================== ======================================== +``get_all_version_components`` Split up a version string into its + component parts. +``get_version_components`` Get important version components, + excluding '.', '-' and '_'. +``get_major_version`` Get the major version. +``get_version_component_range`` Extract a range of subparts from a version + string +``get_after_major_version`` Get everything after the major version. +``replace_version_separator`` Replace a particular version separator. +``replace_all_version_separators`` Replace all version separators. +``delete_version_separator`` Delete a version separator. +``delete_all_version_separators`` Delete all version separators. +==================================== ======================================== + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/variables/variables-1.ebuild b/ebuild-writing/variables/variables-1.ebuild new file mode 100644 index 0000000..c396d3e --- /dev/null +++ b/ebuild-writing/variables/variables-1.ebuild @@ -0,0 +1,7 @@ +# Headers + +SRC_URI="http://example.com/files/${P}-core.tar.bz2 + x86? ( http://example.com/files/${P}/${P}-sse-asm.tar.bz2 ) + ppc? ( http://example.com/files/${P}/${P}-vmx-asm.tar.bz2 ) + sparc? ( http://example.com/files/${P}/${P}-vis-asm.tar.bz2 ) + doc? ( http://example.com/files/${P}/${P}-docs.tar.bz2 )" diff --git a/ebuild-writing/variables/variables-2.ebuild b/ebuild-writing/variables/variables-2.ebuild new file mode 100644 index 0000000..b7b2560 --- /dev/null +++ b/ebuild-writing/variables/variables-2.ebuild @@ -0,0 +1,10 @@ +# Headers + +SRC_URI="http://example.com/files/${P}-core.tar.bz2 + examplecards_foo? ( http://example.com/files/${P}-foo.tar.bz2 ) + examplecards_bar? ( http://example.com/files/${P}-bar.tar.bz2 ) + examplecards_baz? ( http://example.com/files/${P}-baz.tar.bz2 ) + !examplecards_foo? ( !examplecards_bar? ( !examplecards_baz? ( + http://example.com/files/${P}-foo.tar.bz2 + http://example.com/files/${P}-bar.tar.bz2 + http://example.com/files/${P}-baz.tar.bz2 ) ) )" diff --git a/ebuild-writing/variables/variables-3.ebuild b/ebuild-writing/variables/variables-3.ebuild new file mode 100644 index 0000000..0927589 --- /dev/null +++ b/ebuild-writing/variables/variables-3.ebuild @@ -0,0 +1,4 @@ +# Headers + +inherit versionator +MY_PV=$(replace_version_separator 2 '-') |
