Questa guida fornisce una breve introduzione sulla scrittura degli ebuild. Non entra nel dettaglio né prende in considerazione i problemi incontrati dagli sviluppatori ma piuttosto, fornisce alcuni esempi che possono essere usati per capire l'idea di base di come funzionano gli ebuild.
Da notare che gli esempi utilizzati in questa guida sono basati su ebuild reali presenti nell'albero del portage, anche se possono avere alcune parti mancanti, modificate o semplificate.
Si utilizzerà l'ebuild per l'utility Exuberant Ctags, uno strumento per l'indicizzazione del codice sorgente. Ecco una semplificazione di dev-util/ctags/ctags-5.5.4.ebuild (si può trovare l'ebuild reale nell'albero principale del portage):
# Copyright 1999-2005 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
HOMEPAGE="http://ctags.sourceforge.net"
SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz"
LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~mips ~sparc ~x86"
IUSE=""
src_compile() {
econf --with-posix-regex || die "econf failed"
emake || die "emake failed"
}
src_install() {
make DESTDIR="${D}" install || die "install failed"
dodoc FAQ NEWS README
dohtml EXTENDING.html ctags.html
}
Dall'esempio, si nota che un ebuild non è altro che uno script bash che viene eseguito all'interno di un'ambiente speciale.
La prima parte dell'ebuild è un'intestazione che è presente in tutti gli ebuild.
Negli ebuild viene usata un'indentazione utilizzando i tab con ogni tab rappresentante quattro spazi. Vedere il formato dei file ebuild.
Proseguendo la scorsa dell'ebuild, si notano una serie di variabili. Queste forniscono al portage varie informazioni circa l'ebuild ed il pacchetto in questione.
La variabile DESCRIPTION contiene una breve descrizione del pacchetto e del suo scopo.
La HOMEPAGE è un collegamento alla homepage del pacchetto (ricordarsi di includere la parte http://)
La LICENSE è GPL-2 (la GNU General Public License versione 2).
La SRC_URI dice al portage l'indirizzo da usare per scaricare il tarball dei sorgenti. Nel caso in esempio, mirror://sourceforge/, è una notazione speciale per "qualsiasi mirror di Sourceforge". La ${P} è una variabile in sola lettura impostata dal portage che identifica il nome e la versione del pacchetto, nel caso in esempio dovrebbe essere ctags-5.5.4.
La variabile SLOT istruisce il portage sullo slot nel quale installare il pacchetto. Se non si sa cos'è uno slot, impostare la variabile a "0". Per maggiori informazioni vedere Slotting.
La variabile KEYWORDS viene impostata con le architetture nelle quali è stato testato l'ebuild. Nell'esempio viene usata la parola chiave ~ per gli ebuild di nuove applicazioni che non sono state ancora definite come stabili anche se sembrano funzionare correttamente. Per maggiori informazioni vedere Utilizzare le KEYWORDS.
Proseguendo l'analisi dell'ebuild, si trova una funzione chiamata src_compile. Portage invocherà questa funzione per compilare il pacchetto. La funzione econf è un wrapper per eseguire ./configure, e emake è un wrapper per make. In entrambi i casi viene usato l'idioma ||die "qualcosa è andato storto" che assicura che, in caso di errore, il portage non continui con l'installazione.
La funzione src_install viene utilizzata dal portage quando è necessario installare il pacchetto. Questa funzione non installa il pacchetto nel filesystem ma in una speciale locazione che è data dalla variabile ${D} impostata dal portage. Anche questa finezza viene utilizzata per evitare errori di qualsiasi sorta. (Vedere Destinazione delle installazioni e Sandbox.)
Nota
Il metodo di installazione canonico è make DESTDIR="${D}" install il quale funzionerà con qualsiasi Makefile standard scritto in modo appropriato. Se questo genera errori di sandbox, provare einstall. MODIFICARE If this still fails, see src_install for how to do manual installs.
Le funzioni dodoc e dohtml forniscono una scorciatoia per installare file in parti rilevanti di /usr/share/doc.
Gli ebuild possono definire altre funzioni, ma in tutti i casi, portage fornisce, di default, un'implementazione ragionevole che molto spesso fa la 'cosa giusta'. Per esempio, non c'è bisogno di definire una funzione src_unpack in questo caso (questa funzione esegue l'unpack dei tarball o il patch dei file sorgente) dato che l'implementazione di default esegue tutto quello di cui si necessita, tra cui, appunto, l'unpack del tarball.
Nell'esempio di ctags, non occorre fornire al portage alcuna dipendenza dato che il pacchetto in questione non necessita di altro che della normale sequenza di compilazione ed installazione, ma questo è un caso raro.
Ecco l'ebuild app-misc/detox/detox-1.1.1.ebuild:
# Copyright 1999-2005 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
DESCRIPTION="detox safely removes spaces and strange characters from filenames"
HOMEPAGE="http://detox.sourceforge.net/"
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"
LICENSE="BSD"
SLOT="0"
KEYWORDS="~hppa mips sparc x86"
IUSE=""
DEPEND="dev-libs/popt
sys-devel/flex
sys-devel/bison"
RDEPEND="dev-libs/popt"
src_compile() {
econf --with-popt || die "econf failed"
emake || die "emake failed"
}
src_install() {
make DESTDIR="${D}" install || die "install failed"
dodoc README CHANGES
}
Anche in questo caso si possono notare l'intestazione e le variabili informative. In SRC_URI, la variabile ${P} viene usata per ottenere il nome del pacchetto senza il suffisso della versione. (Ci sono molte altre variabili come queste. Vedere Variabili).
Si utilizzano nuovamente le funzioni src_compile e src_install.
Le variabili DEPEND e RDEPEND forniscono al portage le informazioni per determinare le dipendenze necessarie per compilare ed eseguire il pacchetto. La variabile DEPEND elenca le dipendenze per la compilazione, mentre RDEPEND elenca le dipendenze per l'esecuzione. See Dependencies for me more complex examples.
Spesso occorre applicare delle patch al pacchetto. Questo viene fatto nella funzione src_unpack usando la funzione epatch. Per usare epatch si deve prima dire al portage che è richiesta l'eclass eutils (una eclass è come una libreria) e questo lo si fa con l'istruzione inherit eutils in testa all'ebuild. Ecco app-misc/detox/detox-1.1.0.ebuild:
# Copyright 1999-2005 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
inherit eutils
DESCRIPTION="detox safely removes spaces and strange characters from filenames"
HOMEPAGE="http://detox.sourceforge.net/"
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"
LICENSE="BSD"
SLOT="0"
KEYWORDS="~hppa ~mips ~sparc ~x86"
IUSE=""
DEPEND="dev-libs/popt
sys-devel/flex
sys-devel/bison"
RDEPEND="dev-libs/popt"
src_unpack() {
unpack ${A}
cd "${S}"
epatch "${FILESDIR}"/${P}-destdir.patch
epatch "${FILESDIR}"/${P}-parallel_build.patch
}
src_compile() {
econf --with-popt || die "econf failed"
emake || die "emake failed"
}
src_install() {
make DESTDIR="${D}" install || die "install failed"
dodoc README CHANGES
}
Notare che ${FILESDIR}/${P}-destdir.patch si riferisce al file detox-1.1.0-destdir.patch che è nella sottodirectory files/ nell'albero del portage. Patch molto grosse devono risiedere su un mirror invece che in files/.
L'esempio è dev-libs/libiconv/libiconv-1.9.2.ebuild, un sostituto di iconv per implementazioni libc che non ne posseggono uno proprio:
# Copyright 1999-2005 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
DESCRIPTION="GNU charset conversion library for libc which doesn't implement it"
SRC_URI="ftp://ftp.gnu.org/pub/gnu/libiconv/${P}.tar.gz"
HOMEPAGE="http://www.gnu.org/software/libiconv/"
SLOT="0"
LICENSE="LGPL-2.1"
KEYWORDS="~amd64 ~ppc ~sparc ~x86"
IUSE="nls"
DEPEND="virtual/libc
!sys-libs/glibc"
src_compile() {
econf $(use_enable nls) || die "econf failed"
emake || die
}
src_install() {
make DESTDIR="${D}" install || die "install failed"
}
Notare la variabile IUSE la quale elenca tutte i flag USE (non speciali) usati dall'ebuild e che vengono usati per l'output di emerge -pv.
Lo script ./configure del pacchetto riceve gli argomenti usuali --enable-nls o --disable-nls attraverso la funzione use_enable che li genera automaticamente.
Un esempio più complicato basato questa volta su mail-client/sylpheed/sylpheed-1.0.4.ebuild:
# Copyright 1999-2005 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
inherit eutils
DESCRIPTION="A lightweight email client and newsreader"
HOMEPAGE="http://sylpheed.good-day.net/"
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"
LICENSE="GPL-2"
KEYWORDS="alpha amd64 hppa ia64 ppc ppc64 sparc x86"
SLOT="0"
IUSE="crypt gnome imlib ipv6 ldap nls pda ssl xface"
DEPEND="=x11-libs/gtk+-1.2*
nls? ( >=sys-devel/gettext-0.12.1 )
crypt? ( >=app-crypt/gpgme-0.4.5 )
gnome? ( media-libs/gdk-pixbuf )
imlib? ( media-libs/imlib )
ldap? ( >=net-nds/openldap-2.0.11 )
pda? ( app-pda/jpilot )
ssl? ( dev-libs/openssl )
xface? ( >=media-libs/compface-1.4 )"
RDEPEND="${DEPEND}
app-misc/mime-types
x11-misc/shared-mime-info"
src_unpack() {
unpack ${A}
cd "${S}"
epatch "${FILESDIR}"/${PN}-namespace.diff
epatch "${FILESDIR}"/${PN}-procmime.diff
}
src_compile() {
econf \
$(use_enable nls) \
$(use_enable ssl) \
$(use_enable crypt gpgme) \
$(use_enable pda jpilot) \
$(use_enable ldap) \
$(use_enable ipv6) \
$(use_enable imlib) \
$(use_enable gnome gdk-pixbuf) \
$(use_enable xface compface) \
|| die
emake || die
}
src_install() {
einstall || die "einstall failed"
dodir /usr/share/pixmaps
insinto /usr/share/pixmaps
doins *.png
if use gnome ; then
dodir /usr/share/gnome/apps/Internet
insinto /usr/share/gnome/apps/Internet
doins sylpheed.desktop
fi
dodoc [A-Z][A-Z]* ChangeLog*
}
Si notano qui le dipendenze opzionali. Alcune delle righe use_enable usano due argomenti; questo è utile quando il nome del flag USE non corrisponde esattamente con l'argomento del ./configure.