diff options
| author |   Tim Yamin <plasmaroo@gentoo.org> | 2006-02-20 14:23:21 +0000 |
|---|---|---|
| committer | Tim Yamin <plasmaroo@gentoo.org> | 2006-02-20 14:23:21 +0000 |
| commit | 64c84bfc95d60bb4aa7f29b7ad3769c0572f164a (patch) | |
| tree | 5d98ee25a8f4f84e1cc6d46c3990d00a27339ee6 /quickstart | |
| parent | Set up basic repo structure (diff) | |
| download | devmanual-64c84bfc95d60bb4aa7f29b7ad3769c0572f164a.tar.gz devmanual-64c84bfc95d60bb4aa7f29b7ad3769c0572f164a.tar.bz2 devmanual-64c84bfc95d60bb4aa7f29b7ad3769c0572f164a.zip | |
Initial commit :)
git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@2 176d3534-300d-0410-8db8-84e73ed771c3
Diffstat (limited to 'quickstart')
| -rw-r--r-- | quickstart/text.xml | 437 |
1 files changed, 437 insertions, 0 deletions
diff --git a/quickstart/text.xml b/quickstart/text.xml new file mode 100644 index 0000000..5eb5753 --- /dev/null +++ b/quickstart/text.xml @@ -0,0 +1,437 @@ +<?xml version="1.0"?> +<guide self="quickstart/"> +<chapter> +<title>Quickstart Ebuild Guide</title> + +<body> +<p> +This page provides a <e>very</e> brief introduction to ebuild +writing. It does not attempt to cover many of the details or problems +that will be encountered by developers -- rather, it gives some +trivial examples which may be of use when trying to grasp the basic +idea of how ebuilds work. +</p> + +<p> +For proper coverage of all the ins and outs, see `Ebuild +Writing`_. The `General Concepts`_ chapter will also be of use. +</p> + +<p> +Note that the examples used here, whilst based upon real tree ebuilds, +have had several parts chopped out, changed and simplified. +</p> +</body> + +<section> +<title>First Ebuild</title> + +<body> +<p> +We'll start with an ebuild for the <e>Exuberant Ctags</e> utility, a source code +indexing tool. Here's a simplified <c>dev-util/ctags/ctags-5.5.4.ebuild</c> (you +can see real ebuilds in the main tree). +</p> + +<codesample lang="ebuild"> +# 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 +} +</codesample> +</body> + +<subsection> +<title>Basic Format</title> + +<body> +<p> +As you can see, ebuilds are just <c>bash</c> scripts that are executed within a +special environment. +</p> + +<p> +At the top of the ebuild is a header block. This is present in all ebuilds. +</p> + +<p> +Ebuilds are indented using tabs, with each tab representing four places. See +`Ebuild File Format`_. +</p> +</body> +</subsection> + +<subsection> +<title>Information Variables</title> + +<body> +<p> +Next, there are a series of variables. These tell portage various things about +the ebuild and package in question. +</p> + +<p> +The <c>DESCRIPTION</c> variable is set to a <e>short</e> description +of the package and its purpose. +</p> + +<p> +The <c>HOMEPAGE</c> is a link to the package's homepage (remember to +include the <c>http://</c> part). +</p> + +<p> +The <c>LICENSE</c> is <c>GPL-2</c> (the GNU General Public License version 2). +</p> + +<p> +The <c>SRC_URI</c> tells Portage the address to use for downloading +the source tarball. Here, <c>mirror://sourceforge/</c> is a special +notation meaning "any of the Sourceforge mirrors". The +<c>${P}</c> is a read-only variable set by Portage which is the package's +name and version -- in this case, it would be <c>ctags-5.5.4</c>. +</p> + +<p> +The <c>SLOT</c> variable tells portage which slot this package installs to. If +you've not seen slots before, either just use <c>"0"</c> or read `Slotting`_. +</p> + +<p> +The <c>KEYWORDS</c> variable is set to archs upon which this ebuild has been +tested. We use <c>~</c> keywords for newly written ebuilds -- packages are not +committed straight to stable, even if they seem to work. See `Keywording`_ for +details. +</p> +</body> +</subsection> + +<subsection> +<title>Build Functions</title> + +<body> +<p> +Next, a function named <c>src_compile</c>. Portage will call this +function when it wants to <e>compile</e> the package. The <c>econf</c> +function is a wrapper for calling <c>./configure</c>, and <c>emake</c> +is a wrapper for <c>make</c>. In both cases, the common <c>|| die +"something went wrong"</c> idiom is used -- this is to +ensure that if for some reason an error occurs, portage will stop +rather than trying to continue with the install. +</p> + +<p> +The <c>src_install</c> function is called by portage when it wants +to <e>install</e> the package. A slight subtlety here -- rather than +installing straight to the live filesystem, we must install to a +special location which is given by the <c>${D}</c> variable (portage sets +this -- see `Install Destinations`_ and `Sandbox`_). Again, we check +for errors. +</p> + +<note> +The canonical install method is <c>make DESTDIR="${D}" +install</c>. This will work with any properly written standard +<c>Makefile</c>. If this gives sandbox errors, try <c>einstall</c> +instead. If this still fails, see `src_install`_ for how to do +manual installs. +</note> + +<p> +The <c>dodoc</c> and <c>dohtml</c> are helper functions for installing +files into the relevant part of <c>/usr/share/doc</c>. +</p> + +<p> +Ebuilds can define other functions (see `Ebuild Functions`_). In all cases, +portage provides a reasonable default implementation which quite often does the +'right thing'. There was no need to define a <c>src_unpack</c> function here, for +example -- this function is used to do any unpacking of tarballs or patching of +source files, but the default implementation does everything we need. +</p> +</body> +</subsection> + +</section> + +<section> +<title>Ebuild with Dependencies</title> + +<body> +<p> +In the ctags example, we didn't tell portage about any dependencies. As it +happens, that's ok, because ctags only needs a basic toolchain to compile and +run (see `Implicit System Dependency`_ for why we don't need to depend upon +those explicitly). However, life is rarely that simple. +</p> + +<p> +Here's <c>app-misc/detox/detox-1.1.1.ebuild</c>: +</p> + +<codesample lang="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 +} +</codesample> + +<p> +Again, you can see the ebuild header and the various informational variables. In +<c>SRC_URI</c>, <c>${PN}</c> is used to get the package's +name <e>without</e> the version suffix (there are more of these +variables -- see `Predefined Read-Only Variables`_). +</p> + +<p> +Again, we define <c>src_compile</c> and <c>src_install</c> functions. +</p> + +<p> +The <c>DEPEND</c> and <c>RDEPEND</c> variables are how portage determines which +packages are needed to build and run the package. The <c>DEPEND</c> variable lists +compile-time dependencies, and the <c>RDEPEND</c> lists runtime dependencies. See +`Dependencies`_ for some more complex examples. +</p> + +</body> +</section> + +<section> +<title>Ebuild with Patches</title> + +<body> +<p> +Often we need to apply patches. This is done in the <c>src_unpack</c> function +using the <c>epatch</c> helper function. To use <c>epatch</c> one must first tell +portage that the <c>eutils</c> eclass (an eclass is like a library) is required -- +this is done via <c>inherit eutils</c> at the top of the ebuild. Here's +<c>app-misc/detox/detox-1.1.0.ebuild</c>: +</p> + +<codesample lang="ebuild"> +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +inherit eutils + +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 +} +</codesample> + +<p> +Note the <c>${FILESDIR}/${P}-destdir.patch</c> -- this refers to +<c>detox-1.1.0-destdir.patch</c>, which lives in the <c>files/</c> +subdirectory in the portage tree. Larger patch files must go on the +mirrors rather than in <c>files/</c> -- see `Basic epatch Usage`_. +</p> + +</body> +</section> + +<section> +<title>Ebuild with USE Flags</title> + +<body> +<p> +Now for some <c>USE</c> flags. Here's <c>dev-libs/libiconv/libiconv-1.9.2.ebuild</c>, a +replacement iconv for <c>libc</c> implementations which don't have their own. +</p> + +<codesample lang="ebuild"> +# 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" +} +</codesample> + +<p> +Note the <c>IUSE</c> variable. This lists all (non-special) use flags that are used +by the ebuild. This is used for the <c>emerge -pv</c> output, amongst other things. +</p> + +<p> +The package's <c>./configure</c> script takes the usual <c>--enable-nls</c> or +<c>--disable-nls</c> argument. We use the <c>use_enable</c> utility function to +generate this automatically (see `Query Functions Reference`_). +</p> + +<p> +Another more complicated example, this time based upon +<c>mail-client/sylpheed/sylpheed-1.0.4.ebuild</c>: +</p> + +<codesample lang="ebuild"> +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +inherit eutils + +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* +} +</codesample> + +<p> +Note the optional dependencies. Some of the <c>use_enable</c> lines use the +two-argument version -- this is helpful when the USE flag name does not exactly +match the <c>./configure</c> argument. +</p> +</body> +</section> + +</chapter> +</guide> |