Gentoo ebuild - 2 (funkce, eclass a příkazy)

19. 2. 2007 | David Watzke

Články - Gentoo ebuild - 2 (funkce, eclass a příkazy)  

Podrobný popis funkcí, pomocných souborů eclass a příkazů. Konfigurace, kompilace a instalace.

Funkce

Následující funkce nutné pro kompilaci a instalaci balíčku se běžně zapisují pod nezbytné proměnné, o kterých jsme mluvili v minulém díle.

pkg_nofetch()

Funkce, která se zavolá, když je v ebuildu RESTRICT="fetch" (tzn. zdrojové soubory je třeba ručně stáhnout a uložit je do (proměnné Portage) ${DISTDIR}). Používá se velmi zřídka a je nutná jen z licenčních důvodů. Její výchozí definice vypadá následovně:

[ -z "${SRC_URI}" ] && return

echo "!!! The following are listed in SRC_URI for ${PN}:"
local x
for x in $(echo ${SRC_URI}); do
	echo "!!!   ${x}"
done

Pokud někdy budete psát ebuild, ve kterém pkg_nofetch použijete, doporučuji funkci předefinovat na něco více uživatelsky přívětivého s odkazem a případně vysvětlením.

Poznámka: Když používáte pkg_nofetch(), do ${SRC_URI} patří jen názvy souborů.

pkg_setup()

Funkce vhodná pro různé kontroly konfigurace a podobně. Na následující ukázce vidíme, že když máme verzi Cairo 1.2.2 nebo novější sestavenou bez USE flagu "X", tak nás ebuild vyzve, abychom ji překompilovali s ním.

if has_version ">=x11-libs/cairo-1.2.2" && ! built_with_use x11-libs/cairo X; then
	einfo "Please re-emerge >=x11-libs/cairo-1.2.2 with the X USE flag set"
	die "Please emerge >=x11-libs/cairo-1.2.2 with the X flag set"
fi

Výchozí definice funkce je pouze return, z čehož plyne, že použití této funkce je naprosto volitelné.

src_unpack()

Tato funkce definuje, jak rozbalit zdrojové soubory. Patří do ní ovšem i patchování a eautoreconf. Výchozí definice vypadá následovně:

[[ -n ${A} ]] && unpack ${A}

Není třeba funkci redefinovat, pokud po rozbalení už stačí rozjet ./configure nebo rovnou make atp. Když je třeba patchovat, zavoláme inherit eutils (vizte výše) a funkce by pak mohla vypadat třeba takto:

unpack ${A}
cd "${S}"
epatch "${FILESDIR}"/${P}-as-needed.patch

src_compile()

Do této funkce patří spuštění ./configure a make nebo univerzálněji řečeno příkazy pro kompilaci. Zde bych podotkl, že se běžně nespouští ./configure a make jen tak, ale používají se wrappery econf a emake (popis příkazů vizte níže). Je vhodné je používat vždy, kromě speciálních případů, kdy k tomu je nějaký důvod. Výchozí definice funkce vypadá takto:

if [ -x ./configure ]; then
	econf
fi
if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then
	emake || die "emake failed"
fi

src_test()

Slouží k testování, zda kompilace proběhla úspěšně atp. V případě, že určitý test není možné provést v prostředí Portage, je třeba jej odstranit např. pomocí sedu na Makefile. O toto se ale v drtivé většině případů nemusíte starat, protože výchozí definice často postačuje:

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%:/}"

Pokud by se stalo, že test neprojde kvůli tomu, že je chybně napsaný, pak je třeba do ebuildu přidat RESTRICT="test", což zajistí vynechání testu. Vhodné je informovat o takové chybě upstream, protože vadný test je horší než žádný test.

src_install()

Účel této funkce je nainstalovat sestavený balíček do ${D}. Když tato instalace proběhne bez problémů (např. se nebude pokoušet něco smazat nebo jakkoliv manipulovat na systémem mimo temp), automaticky se odtud pak balíček nainstaluje do ${ROOT}. Ve výchozím stavu funkce nic nedělá (jen return), takže je třeba ji vždy definovat (nebo načíst eclass, která ji definuje, vizte níže).

Často stačí toto:

emake DESTDIR="${D}" install || die "Install failed"

Poznámka: emake může spouštět (v závislosti na nastavení proměnné Portage ${MAKEOPTS}) make paralelně, což u některých balíčků (s nevychytaným Makefile) působí potíže. V takovém případě použijte "make" nebo "emake -j1".

pkg_preinst()

Funkce, která se volá po src_install(), před instalací z ${D} do ${ROOT}. Spouští se s rootovskými právy a nehlídá ji sandbox. Běžné využití je například přidávání uživatelů a skupin do systému (vizte níže příkazy enewuser a enewgroup) a úprava balíčku pro konkrétní systém. Nejužitečnější příklad takové úpravy je patrně vytváření aktualizovaných verzí konfiguračních souborů v ${D}/etc na základě kontroly již nainstalovaných konfiguráků (pro jinou verzi) v adresáři ${ROOT}/etc. Zabráníte tak neustálé snaze o přepisování vaší konfigurace tou výchozí.

Poznámka: Pro přístup k ${D} se v této funkci používá proměnná ${IMAGE}.

pkg_postinst()

Tato funkce se volá po instalaci balíčku do ${ROOT}. Běžně se tato funkce používá pro vypsání informačních hlášek nebo varování, souvisejících s přechodem na novější verzi atp.

Poznámka: Pokud potřebujete v ebuildu popisovat aktualizační proces pro upgrade z různých verzí, je vhodné použít příkaz has_version (vizte níže). Pro příklad se můžete podívat třeba na ebuild sys-fs/udev.

pkg_prerm()

Funkce je volána před tím, než je balíček odinstalován. Je vhodná pro odstranění dočasných souborů, které si program mohl vytvořit. Výchozí definice spustí jen return (tzn. nic nedělá). Může vypadat třeba takto:

# clean up temp files
[[ -d "${ROOT}/var/tmp/${PN}" ]] && \
 rm -rf "${ROOT}/var/tmp/${PN}"

pkg_postrm()

Tato funkce se volá po odinstalování balíčku. Používá se pro aktualizaci symlinků, keše atp. Ve výchozím stavu nic nedělá.

pkg_config()

Funkce, která má za cíl spustit jakoukoliv zvláštní poinstalační konfiguraci. Výchozí definice vypadá takto:

eerror "This ebuild does not have a config function."

Ukázka z MySQL ebuildu:

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

Eclass

Eclassy jsou pomocné soubory obsahující funkce a proměnné pro různé účely. Jsou uloženy v ${PORTDIR}/eclass a mají vždy příponu .eclass. Jsou to opět klasické bashové skripty, které jsou určeny k použití uvnitř ebuildu. Můžete si samozřejmě napsat i své vlastní a uložit je do ${PORTDIR_OVERLAY}/eclass. Protože jsem toho názoru, že nejnázornější je vždy příklad, tak hned jeden přikládám. Slouží ke zjednodušení stahování z CVS na GNU.org - gnucvs.eclass, mé vlastní dílo. Tím se ještě budeme zabývat v dalším díle.

inherit cvs

SRC_URI=""
S="${WORKDIR}/${PN}"

ECVS_USER="anonymous"
ECVS_PASS=""
ECVS_AUTH="pserver"

gnucvs_src_unpack() {
        ECVS_MODULE="${1-${PN}}"
        ECVS_SERVER="cvs.savannah.gnu.org:/sources/${ECVS_MODULE}"
        cvs_src_unpack
}

gnucvs_cvs_gnulib() {
        ECVS_SERVER="cvs.savannah.gnu.org:/cvsroot/gnulib"
        ECVS_MODULE="gnulib"
        cvs_src_unpack
}

gnucvs_copy_gnulib() {
        mv "${WORKDIR}/gnulib" "${S}/" || die "Failed to move gnulib!"
}

gnucvs_all() {
        gnucvs_cvs_gnulib
        gnucvs_src_unpack ${1}
        gnucvs_copy_gnulib
}

inherit

Zvláštní funkce, která je dostupná úplně každému ebuildu a eclass. Je (svou funkčností) podobná shellovému source a načítá eclassy (takže eclass si pro vlastní potřebu může načíst jinou eclass, jak jste si mohli všimnout už v ukázce). Volá se úplně na začátku, případně po definování potřebné proměnné (například vyžádání konkrétní verze automake proměnnou WANT_AUTOMAKE před načtením autotools.eclass). Jako argument(y) zadejte seznam eclass, které chcete načíst (bez cesty a přípony, jako v ukázce).

Příkazy

Výpis některých základních příkazů, které se v ebuildech používají.

Základní příkazy

Následující příkazy a funkce se nacházejí v adresáři /usr/lib/portage/bin a jsou dostupné každému ebuildu a eclass. Automaticky používají ${D}.

Funkce	Popis
insinto	Nastavuje cílový adresář pro příkazy doins a newins
exeinto	Nastavuje cílový adresář pro příkazy doexe a newexe
docinto	Nastavuje cílový adresář pro příkazy dodoc a newdoc
insopts	Nastavuje argumenty, které se použijí pro install.
diropts	Nastavuje argumenty, které se použijí pro install pro adresáře.
exeopts	Nastavuje argumenty, které se použijí pro install pro spustitelné soubory.
libopts	Nastavuje argumenty, které se použijí pro install pro knihovny.
dobin	Nainstaluje binárky do /usr/bin.
doconfd	Nainstaluje konfigurační soubor(y) pro init-skript(y) do /etc/conf.d.
dodir	Nainstaluje adresář(e) (používejte místo mkdir).
dodoc	Nainstaluje dokumentační soubor(y).
doenvd	Nainstaluje soubor(y) do /etc/env.d.
doexe	Nainstaluje spustitelné soubory.
dohard	Vytvoří hardlink z druhého argumentu na první.
dohtml	Nainstaluje dokumentační soubor(y) v HTML.
doinfo	Nainstaluje GNU Info dokument(y)
doinitd	Nainstaluje init-skript(y) do /etc/init.d.
doins	Nainstaluje jakékoliv soubory.
dojar	Nainstaluje .jar soubor(y).
dolib	Nainstaluje knihovny.
dolib.a	Nainstaluje .a knihovny.
dolib.so	Nainstaluje .so knihovny.
doman	Nainstaluje manuál(y).
domo	Nainstaluje gettextový .mo soubor(y).
dosbin	Nainstaluje binárky do /usr/sbin.
dosym	Vytvoří symbolický odkaz (symlink) z druhého argumentu na první.
fowners	Spouští chown.
fperms	Spouští chmod.
keepdir	Vytvoří adresář s prázdným souborem .keep uvnitř.
newbin	Nainstaluje binárku do /usr/bin.
newconfd	Nainstaluje konfigurační soubor pro init-skript do /etc/conf.d.
newdoc	Nainstaluje dokumentační soubor.
newenvd	Nainstaluje soubor do /etc/env.d.
newexe	Nainstaluje spustitelný soubor.
newinitd	Nainstaluje init-skript do /etc/init.d.
newins	Nainstaluje jakýkoliv soubor.
newlib.a	Nainstaluje .a knihovnu.
newlib.so	Nainstaluje .so knihovnu.
newman	Nainstaluje manuál.
newsbin	Nainstaluje binárku do /usr/sbin.

Poznámka: Patrně se divíte, k čemu jsou stejné příkazy začínající jednou na "new" a podruhé na "do". Rozdíl je tento: do* příkazy berou libovolný počet argumentů, kdežto new* příkazy berou přesně dva argumenty - první je zdrojový soubor a druhý název, se kterým bude soubor nainstalován.

Příkazy z eclass

Příkazy, které se objeví pod tímto podnadpisem, můžete v ebuildech používat po spuštění inherit s použitím názvů potřebných eclass (které jsou uvedeny v závorkách) jako parametrů.

eaclocal (autotools)

Spouští aclocal. Používá proměnnou AT_M4DIR pro přídavné adresáře, ve kterých se mají hledat makra.

eautoconf (autotools)

Spouští autoconf.

eautoheader (autotools)

Spouští autoheader.

eautomake (autotools)

Spouští automake.

eutoreconf (autotools)

Spouští autoreconf. Umí pracovat s přídavnými adresáři specifikovanými v proměnné AC_CONFIG_SUBDIRS.

built_with_use (eutils)

Zjistí, zda byl zadaný balíček zkompilovaný s danými USE flagy. Použití:

built_with_use [--missing <akce>] [-a|-o] \
 <kategorie/zavislost> <seznam USE flagů>

Volitelný přepínač "--missing" s povinným argumentem true, false nebo die, nastavuje, co se má provést, když daný USE-flag pro verzi balíčku, kterou používáte, neexistuje. Volitelný přepínač '-a' zajistí, že příkaz vrátí true jen tehdy, když je balík zkompilován se všemi USE-flagy ze seznamu, a '-o' vrátí true, když je balík zkompilován alespoň s jedním z nich. Výchozí je '-a'.

emktemp (eutils)

Náhrada za mktemp.

enewgroup (eutils)

Přidá do systému novou skupinu. Funkce se spouští s parametry v tomto pořadí (v závorce je výchozí nastavení): název skupiny (nutno zadat!), GID (další dostupné), volitelné vlastní argumenty pro groupadd (žádné).

enewuser (eutils)

Přidá do systému nového uživatele. Funkce se spouští s parametry v tomto pořadí (v závorce je výchozí nastavení): jméno uživatele (nutno zadat!), UID (další dostupné), shell (/bin/false), domovský adresář (/dev/null), skupiny (žádná) a dále můžete zadat vlastní argumenty pro useradd. Volitelné hodnoty můžete vynechat. Pokud chcete zadat například (kromě jména uživatele) jen shell a skupiny, pamatujte, že je nutné dodržovat pořadí argumentů. Vypadalo by to takto:

enewuser myuser -1 /bin/sh -1 "cdrom,audio"

epatch (eutils)

Spouští patch. Není třeba zadávat přepínač '-p', protože se bude zkoušet '-p0' až '-p5', dokud se patch neaplikuje (nebo patchování selže na '-p5'). Patchování lze ovládat několika proměnnými.

Když chcete aplikovat hromadu patchů z nějakého adresáře, tak místo vypisování po jednom adresář zadáte do proměnné EPATCH_SOURCE (výchozí je ${WORKDIR}/patch; použije se, když zavoláte epatch bez argumentů). Příponu pro patche, které mají být ze zadaného adresáře aplikovány, nastavuje proměnná EPATCH_SUFFIX (výchozí je patch.bz2). Vlastní přepínače pro patch můžete zadat do proměnné EPATCH_OPTS (výchozí jsou "-g0 -E --no-backup-if-mismatch"). Seznam patchů, které nemají být aplikovány, patří do proměnné EPATCH_EXCLUDE (pouze názvy bez cesty). Pokud patche v ${EPATCH_SOURCE} nemají názvy ve stylu ??_${ARCH}_popis.${EPATCH_SUFFIX}, je třeba pro jejich aplikování nastavit proměnnou EPATCH_FORCE na hodnotu "yes".

epunt_cxx (eutils)

Odstraní z configure skriptů zbytečné C++ kontroly (Gentoo bug #73450).

fdo-mime_desktop_database_update (fdo-mime)

Generuje seznam MIME typů svázaných s aplikacemi, které je umí zpracovávat (update-desktop-database).

fdo-mime_mime_database_update (fdo-mime)

Aktualizuje sdílenou databázi s MIME typy (update-mime-database).

append-flags (flag-o-matic)

Přidá zadané argumenty do proměnných CFLAGS a CXXFLAGS.

filter-flags (flag-o-matic)

Odstraní zadané argumenty z CFLAGS a CXXFLAGS.

replace-flags (flag-o-matic)

Nahradí první argument za druhý v CFLAGS a CXXFLAGS. Například:

replace-flags -O3 -O2

elibtoolize (libtool)

Spouští libtoolize.

get_version_components (versionator)

Vypíše z verze programu jen to nejdůležitější, například:

Původní	Výstup
0.8.3	0 8 3
7c	7 c
3.0_p2	3 0 p2
20040905	20040905
3.0c-r1	3 0 c r1

Výstup je vhodný pro uložení do pole:

version=($(get_version_components))

Verze se zadává jako první argument, když žádnou nezadáte, použije se ${PV}.

replace_version_separator (versionator)

Nahradí $1-tý oddělovač za $2 v $3. První argument ($2) může být buď číslo nebo znak oddělovače - v takovém případě je vybrán první oddělovač tohoto typu. Druhý argument ($2) je oddělovač, který chceme místo původního. Třetí argument ($3) může být verze, ale když jej nezadáte, použije se ${PV}.

Argumenty	Výstup
1 '_' 1.2.3	1_2.3
2 '_' 1.2.3	1.2_3
1 '_' 1b-2.3	1b_2.3
. _ 2007.01.01	2007_01.01

Příště

Třetí díl bude o live (CVS/Subversion/Darcs/GIT/Mercurial) ebuildech.

Seriál Gentoo ebuild (dílů: 8)

První díl: Gentoo ebuild - 1 (začínáme: názvy ebuildů a proměnné), poslední díl: Gentoo ebuild - 8 (EAPI 2).
Předchozí díl: Gentoo ebuild - 1 (začínáme: názvy ebuildů a proměnné)
Následující díl: Gentoo ebuild - 3 (live ebuildy)

Diskuse k tomuto článku

[Jan Kundrát (jkt)]

src_unpack() Tato funkce definuje, jak rozbalit zdrojové soubory. Patří do ní ovšem i patchování a automake.

Automake?

[David Watzke]

Hmm, eautoreconf... My bad.

[Robert Krátký]

Opraveno.

[David Watzke]

Díky.