Initial commit :)

git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@2 176d3534-300d-0410-8db8-84e73ed771c3

5 files changed, 608 insertions, 0 deletions

diff --git a/general-concepts/autotools/diagram.png b/general-concepts/autotools/diagram.png
new file mode 100644
index 0000000..5ee2ab8
--- /dev/null
+++ b/general-concepts/autotools/diagram.png
diff --git a/general-concepts/autotools/diagram.svg b/general-concepts/autotools/diagram.svg
new file mode 100644
index 0000000..1f3eda8
--- /dev/null
+++ b/general-concepts/autotools/diagram.svg
@@ -0,0 +1,102 @@
+<?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 50 510 360" xmlns="http://www.w3.org/2000/svg" version="1.1">
+    <desc>Autotools Build Process</desc>
+    <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" />
+
+    <rect x="0" y="70" width="470" height="122"
+        stroke-width="1" stroke="black" fill="none"
+        stroke-dasharray="5,5" rx="10" ry="10" />
+    <text style="text-anchor: middle; font-style: italic;"
+        x="400" y="150">Usually handled</text>
+    <text style="text-anchor: middle; font-style: italic;"
+        x="400" y="164">by upstream</text>
+
+    <rect x="130" y="197" width="330" height="63"
+        stroke-width="1" stroke="black" fill="none"
+        stroke-dasharray="5,5" rx="10" ry="10" />
+    <text style="text-anchor: middle; font-style: italic;"
+        x="410" y="225">Shipped with</text>
+    <text style="text-anchor: middle; font-style: italic;"
+        x="410" y="239">the package</text>
+
+    <rect x="10" y="150" width="80" height="30"
+        fill="#ccccff" stroke="black" stroke-width="2" />
+    <text style="text-anchor: middle;" x="50" y="170">Makefile.am</text>
+
+    <line x1="90"  y1="165" x2="130" y2="165" stroke-width="2" stroke="black" />
+    <line x1="130" y1="165" x2="122" y2="160" stroke-width="2" stroke="black" />
+    <line x1="130" y1="165" x2="122" y2="170" stroke-width="2" stroke="black" />
+
+    <polygon points="130,165 180,145 230,165 180,185" fill="#ffffff"
+        stroke="black" stroke-width="2" />
+    <text style="text-anchor: middle;" x="180" y="169">automake</text>
+
+    <line x1="180" y1="185" x2="180" y2="215" stroke-width="2" stroke="black" />
+    <line x1="185" y1="207" x2="180" y2="215" stroke-width="2" stroke="black" />
+    <line x1="175" y1="207" x2="180" y2="215" stroke-width="2" stroke="black" />
+
+    <rect x="140" y="215" width="80" height="30"
+        fill="#ccffcc" stroke="black" stroke-width="2" />
+    <text style="text-anchor: middle;" x="180" y="235">Makefile.in</text>
+
+    <line x1="220" y1="230" x2="260" y2="230" stroke-width="2" stroke="black" />
+    <line x1="260" y1="230" x2="252" y2="235" stroke-width="2" stroke="black" />
+    <line x1="260" y1="230" x2="252" y2="225" stroke-width="2" stroke="black" />
+
+    <polygon points="260,230 310,210 360,230 310,250" fill="#ccffcc"
+        stroke="black" stroke-width="2" />
+    <text style="text-anchor: middle;" x="310" y="234">configure</text>
+
+    <line x1="310" y1="115"  x2="310" y2="210" stroke-width="2" stroke="black" />
+    <line x1="315" y1="202"  x2="310" y2="210" stroke-width="2" stroke="black" />
+    <line x1="305" y1="202"  x2="310" y2="210" stroke-width="2" stroke="black" />
+
+    <polygon points="260,95 310,75 360,95 310,115" fill="#ffffff"
+        stroke="black" stroke-width="2" />
+    <text style="text-anchor: middle;" x="310" y="99">autoconf</text>
+
+
+    <line x1="220" y1="95" x2="260" y2="95" stroke-width="2" stroke="black" />
+    <line x1="260" y1="95" x2="252" y2="90" stroke-width="2" stroke="black" />
+    <line x1="260" y1="95" x2="252" y2="100" stroke-width="2" stroke="black" />
+
+
+    <rect x="140" y="80" width="80" height="30"
+        fill="#ccccff" stroke="black" stroke-width="2" />
+    <text style="text-anchor: middle;" x="180" y="93" >configure.in /</text>
+    <text style="text-anchor: middle;" x="180" y="105">configure.ac</text>
+
+    <line x1="90"  y1="165" x2="130" y2="165" stroke-width="2" stroke="black" />
+    <line x1="130" y1="165" x2="122" y2="160" stroke-width="2" stroke="black" />
+    <line x1="130" y1="165" x2="122" y2="170" stroke-width="2" stroke="black" />
+
+    <line x1="310" y1="250"  x2="310" y2="285" stroke-width="2" stroke="black" />
+    <line x1="315" y1="278"  x2="310" y2="285" stroke-width="2" stroke="black" />
+    <line x1="305" y1="278"  x2="310" y2="285" stroke-width="2" stroke="black" />
+
+    <rect x="270" y="285" width="80" height="30"
+        fill="#ccffcc" stroke="black" stroke-width="2" />
+    <text style="text-anchor: middle;" x="310" y="305">Makefile</text>
+
+    <line x1="350"  y1="300" x2="390" y2="300" stroke-width="2" stroke="black" />
+    <line x1="390"  y1="300" x2="382" y2="295" stroke-width="2" stroke="black" />
+    <line x1="390"  y1="300" x2="382" y2="305" stroke-width="2" stroke="black" />
+
+    <polygon points="390,300 440,280 490,300 440,320" fill="#ffffff"
+        stroke="black" stroke-width="2" />
+    <text style="text-anchor: middle;" x="440" y="304">make</text>
+
+    <line x1="440" y1="320"  x2="440" y2="355" stroke-width="2" stroke="black" />
+    <line x1="435" y1="348"  x2="440" y2="355" stroke-width="2" stroke="black" />
+    <line x1="445" y1="348"  x2="440" y2="355" stroke-width="2" stroke="black" />
+
+    <ellipse cx="440" cy="375" rx="50" ry="20" stroke-width="2" stroke="black"
+        fill="#ffcccc" />
+    <text style="text-anchor: middle;" x="440" y="378">program</text>
+
+</svg>
+
+<!-- vim: set ft=xml sw=4 sts=4 et : -->
+
diff --git a/general-concepts/autotools/text.xml b/general-concepts/autotools/text.xml
new file mode 100644
index 0000000..3541d70
--- /dev/null
+++ b/general-concepts/autotools/text.xml
@@ -0,0 +1,53 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/autotools/">
+<chapter>
+<title>The Basics of Autotools</title>
+
+<body>
+<todo>
+This is too long for `General Concepts`_. It needs to be split up and
+moved somewhere, either to a top-level of its own or into `Appendices`_.
+</todo>
+
+<p>
+An understanding of GNU autotools (<c>automake</c>, <c>autoconf</c> etc.) can be useful
+when working with ebuilds:
+</p>
+
+<ul>
+  <li>
+  Finding and correcting build issues is often easier if the build system is
+  not seen simply as a scary black box.
+  </li>
+  <li>
+  The autotools input files can help when determining a package's build-time
+  dependencies.
+  </li>
+  <li>
+  The risk of accidentally breaking something by patching the wrong file at the
+  wrong time is greatly reduced if the relationship between the build system
+  files is understood.
+  </li>
+</ul>
+</body>
+
+<section>
+<title>Major Autotools Components</title>
+
+<body>
+<p>
+Autotools is a collection of related packages which, when used together, remove
+much of the difficulty involved in creating portable software. These tools,
+together with a few relatively simple upstream-supplied input files, are used to
+create the build system for a package.
+</p>
+
+<figure short="How autotools fits together" link="diagram.png">
+A basic overview of how the main autotools components fit together.
+</figure>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/general-concepts/config-protect/text.xml b/general-concepts/config-protect/text.xml
new file mode 100644
index 0000000..411613f
--- /dev/null
+++ b/general-concepts/config-protect/text.xml
@@ -0,0 +1,437 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/config-protect/">
+<chapter>
+<title>Configuration File Protection</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 &quot;any of the Sourceforge mirrors&quot;. 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>&quot;0&quot;</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
+&quot;something went wrong&quot;</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=&quot;${D}&quot;
+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>
diff --git a/general-concepts/text.xml b/general-concepts/text.xml
new file mode 100644
index 0000000..6c7a5c9
--- /dev/null
+++ b/general-concepts/text.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/">
+<chapter>
+<title>General Concepts</title>
+
+<body>
+<p>
+This section covers some general concepts with which you should be familiar when
+writing ebuilds or working with the portage tree.
+</p>
+</body>
+</chapter>
+
+<include href="autotools/text.xml"/>
+<include href="config-protect/text.xml"/>
+</guide>