diff options
author | 2010-01-06 14:48:54 +0100 | |
---|---|---|
committer | 2010-01-06 14:48:54 +0100 | |
commit | 31ed46ec4264850e2824ee77586494501799c142 (patch) | |
tree | 45694740111f988758d1f0a6a10a8d0770c532a5 | |
parent | Limit version numbers to 18 digits. Thanks to Ulrich Müller <ulm AT gentoo ... (diff) | |
download | devmanual-31ed46ec4264850e2824ee77586494501799c142.tar.gz devmanual-31ed46ec4264850e2824ee77586494501799c142.tar.bz2 devmanual-31ed46ec4264850e2824ee77586494501799c142.zip |
Start porting the DevManual to (extended) DocBook 5.
The first step is to port a sample page (quickstart) to DocBook 5, and add
a new Makefile that works with DocBook.
The syntax is different, and kinks have to be fixed up, but at least we have
a starting point.
-rw-r--r-- | Makefile.docbook | 31 | ||||
-rw-r--r-- | chunk.toc | 9 | ||||
-rw-r--r-- | content/quickstart.xmli | 415 | ||||
-rw-r--r-- | main.docbook | 125 |
4 files changed, 580 insertions, 0 deletions
diff --git a/Makefile.docbook b/Makefile.docbook new file mode 100644 index 0000000..e63f277 --- /dev/null +++ b/Makefile.docbook @@ -0,0 +1,31 @@ +XSLTPROC = xsltproc + +XSL-NS-SS = http://docbook.sourceforge.net/release/xsl-ns/current/ + +generate: main.docbook + $(XSLTPROC) \ + --xinclude \ + --stringparam base.dir public/ \ + --stringparam chunk.toc chunk.toc \ + --stringparam section.autolabel 1 \ + --stringparam collect.xref.targets "yes" \ + --stringparam targets.filename "$(patsubst %.xhtml,%.olinkdb,$@)" \ + $(XSL-NS-SS)/xhtml-1_1/chunktoc.xsl \ + $< + +chunk.toc.new: + $(XSLTPROC) \ + --output $@ \ + --xinclude \ + --stringparam chunk.section.depth 8 \ + --stringparam chunk.first.sections 1 \ + --stringparam use.id.as.filename 1 \ + $(XSL-NS-SS)/xhtml-1_1/maketoc.xsl \ + main.docbook + +clean: + rm -f *~ *.olinkdb + find public -name '*.html' -delete + +.PHONY: generate chunk.toc.new clean + diff --git a/chunk.toc b/chunk.toc new file mode 100644 index 0000000..e2d6fb1 --- /dev/null +++ b/chunk.toc @@ -0,0 +1,9 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE toc PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> + +<toc xmlns="http://www.w3.org/1999/xhtml" role="chunk-toc"> + <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="index"><?dbhtml filename="index.html"?> + <d:tocentry linkend="quickstart"><?dbhtml filename="quickstart.html"?></d:tocentry> + </d:tocentry> +</toc> + diff --git a/content/quickstart.xmli b/content/quickstart.xmli new file mode 100644 index 0000000..1701b5c --- /dev/null +++ b/content/quickstart.xmli @@ -0,0 +1,415 @@ +<?xml version="1.0" encoding="utf-8"?> +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xl="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xmlns:gentoodv="http://www.gentoo.org/2010/DBDevManual" + xml:id="quickstart"> + <title>Quickstart Ebuild Guide</title> + + <para> + This page provides a <emphasis>very</emphasis> 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. + </para> + + <para> + For proper coverage of all the ins and outs, see <xref linkend="ebuild-writing" />. The <xref + linkend="general-concepts" /> chapter will also be of use. + </para> + + <para> + Note that the examples used here, whilst based upon real tree ebuilds, have had several parts chopped out, changed + and simplified. + </para> + + <section> + <title>First Ebuild</title> + + <para> + We'll start with an ebuild for the <emphasis>Exuberant Ctags</emphasis> utility, a source code indexing + tool. Here's a simplified <filename>dev-util/ctags/ctags-5.5.4.ebuild</filename> (you can see real ebuilds in the + main tree). + </para> + + <gentoodv:codesample lang="ebuild"><![CDATA[ +# 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 + emake || die "emake failed" +} + +src_install() { + emake DESTDIR="${D}" install || die "install failed" + + dodoc FAQ NEWS README || die + dohtml EXTENDING.html ctags.html +} +]]></gentoodv:codesample> + + <section> + <title>Basic Format</title> + + <para> + As you can see, ebuilds are just <command>bash</command> scripts that are executed within a special environment. + </para> + + <para> + At the top of the ebuild is a header block. This is present in all ebuilds. + </para> + + <para> + Ebuilds are indented using tabs, with each tab representing four places. See <xref + linkend="ebuild-writing.file-format" />. + </para> + </section> + + <section> + <title>Information Variables</title> + + <para> + Next, there are a series of variables. These tell Portage various things about the ebuild and package in + question. + </para> + + <para> + The <varname>DESCRIPTION</varname> variable is set to a <emphasis>short</emphasis> description of the package + and its purpose. + </para> + + <para> + The <varname>HOMEPAGE</varname> is a link to the package's homepage (remember to include the + <literal>http://</literal> part). + </para> + + <para> + The <varname>LICENSE</varname> is <constant>GPL-2</constant> (the GNU General Public License version 2). + </para> + + <para> + The <varname>SRC_URI</varname> tells Portage the address to use for downloading the source tarball. Here, + <literal>mirror://sourceforge/</literal> is a special notation meaning “any of the Sourceforge mirrors”. + <literal>${P}</literal> is a read-only variable set by Portage which is the package's name and version — in this + case, it would be <constant>ctags-5.5.4</constant>. + </para> + + <para> + The <varname>SLOT</varname> variable tells Portage which slot this package installs to. If you've not seen slots + before, either just use <constant>"0"</constant> or read <xref linkend="general-concepts.slotting" />. + </para> + + <para> + The <varname>KEYWORDS</varname> variable is set to archs upon which this ebuild has been tested. We use + <constant>~</constant> keywords for newly written ebuilds — packages are not committed straight to stable, even + if they seem to work. See <xref linkend="keywording" /> for details. + </para> + </section> + + <section> + <title>Build Functions</title> + + <para> + Next, a function named <function>src_compile</function>. Portage will call this function when it wants to + <emphasis>compile</emphasis> the package. The <command>econf</command> function is a wrapper for calling + <command>./configure</command>, and <command>emake</command> is a wrapper for <command>make</command>>. In the + case of emake, the common <command>|| die "something went wrong"</command> 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. Note that <command>econf</command> does not need the <command>|| die</command> idiom, as it dies by + itself if something failed. + </para> + + <para> + The <function>src_install</function> function is called by Portage when it wants to <emphasis>install</emphasis> + 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 <literal>${D}</literal> variable (Portage sets this — see <xref + linkend="general-concepts.install-destinations" /> and <xref linkend="general-concepts.sandbox" />). Again, we + check for errors using the <command>|| die</command> construct. + </para> + + <note> + <para> + The canonical install method is <command>emake DESTDIR="${D}" install</command>. This will work with + any properly written standard <filename>Makefile</filename>. If this gives sandbox errors, try + <command>einstall</command> instead. If this still fails, see <xref + linkend="ebuild-writing.functions.src_install" /> for how to do manual installs. + </para> + </note> + + <para> + The <command>dodoc</command> and <command>dohtml</command> are helper functions for installing files into the + relevant part of <filename>/usr/share/doc</filename> + </para> + + <para> + Ebuilds can define other functions (see <xref linkend="ebuild-writing.functions" />). In all cases, Portage + provides a reasonable default implementation which quite often does the 'right thing'. There was no need to + define a <function>src_unpack</function> 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 in this case. + </para> + </section> + </section> + + <section> + <title>Ebuild with Dependencies</title> + + <para> + 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 <xref + linkend="general-concepts.dependencies.implicit-system-dependency" /> for why we don't need to depend upon those + explicitly). However, life is rarely that simple. + </para> + + <para> + Here's <filename>app-misc/detox/detox-1.1.1.ebuild</filename>: + </para> + + <gentoodv:codesample lang="ebuild"><![CDATA[ +# 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 + emake || die "emake failed" +} + +src_install() { + emake DESTDIR="${D}" install || die "install failed" + dodoc README CHANGES || die +} +]]></gentoodv:codesample> + + <para> + Again, you can see the ebuild header and the various informational variables. In <varname>SRC_URI</varname>, + <literal>${PN}</literal> is used to get the package's name <emphasis>without</emphasis> the version suffix (there + are more of these variables — see <xref linkend="ebuild-writing.variables.predefined-ro-vars" />). + </para> + + <para> + Again, we define <function>src_compile</function> and <function>src_install</function> functions. + </para> + + <para> + The <varname>DEPEND</varname> and <varname>RDEPEND</varname> variables are how Portage determines which packages + are needed to build and run the package. The <varname>DEPEND</varname> variable lists compile-time dependencies, + and the <varname>RDEPEND</varname> lists runtime dependencies. See <xref linkend="general-concepts.dependencies" + /> for some more complex examples. + </para> + </section> + + <section> + <title>Ebuild with Patches</title> + + <para> + Often we need to apply patches. This is done in the <function>src_unpack</function> function + using the <command>epatch</command> helper function. To use <command>epatch</command> one must + first tell Portage that the <filename>eutils</filename> eclass (an eclass is like a library) + is required <d/> this is done via <command>inherit eutils</command> at the top of the + ebuild. Here's <filename>app-misc/detox/detox-1.1.0.ebuild</filename>: + </para> + + <gentoodv:codesample lang="ebuild"><![CDATA[ +# 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 + emake || die "emake failed" +} + +src_install() { + emake DESTDIR="${D}" install || die "install failed" + dodoc README CHANGES || die +} +]]></gentoodv:codesample> + + <para> + Note the <filename>${FILESDIR}/${P}-destdir.patch</filename> — this refers to + <filename>detox-1.1.0-destdir.patch</filename>, which lives in the <filename>files/</filename> + subdirectory in the Portage tree. Larger patch files must go on the mirrors rather than in + <filename>files/</filename> — see <xref linkend="ebuild-writing.functions.src_unpack.epatch" />. + </para> + </section> + + <section> + <title>Ebuild with USE Flags</title> + + <para> + Now for some <varname>USE</varname> flags. Here's + <filename>dev-libs/libiconv/libiconv-1.9.2.ebuild</filename>, a replacement iconv for + <filename>libc</filename> implementations which don't have their own. + </para> + + <gentoodv:codesample lang="ebuild"><![CDATA[ +# 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) + emake || die +} + +src_install() { + emake DESTDIR="${D}" install || die "install failed" +} +]]></gentoodv:codesample> + + <para> + Note the <varname>IUSE</varname> variable. This lists all (non-special) use flags that are + used by the ebuild. This is used for the <command>emerge -pv</command> output, amongst other + things. + </para> + + <para> + The package's <command>./configure</command> script takes the usual + <parameter>--enable-nls</parameter> or <parameter>--disable-nls</parameter> argument. We use + the <command>use_enable</command> utility function to generate this automatically, depending + on the user's <varname>USE</varname> flags (see <xref + linkend="function-reference.query-functions" />). + </para> + + <para> + Another more complicated example, this time based upon + <filename>mail-client/sylpheed/sylpheed-1.0.4.ebuild</filename>: + </para> + + <gentoodv:codesample lang="ebuild"><![CDATA[ +# 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) + + 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* || die +} +]]></gentoodv:codesample> + + <para> + Note the optional dependencies. Some of the <command>use_enable</command> lines use the + two-argument version — this is helpful when the USE flag name does not exactly match the + <command>./configure</command> argument. + </para> + </section> + +</chapter> diff --git a/main.docbook b/main.docbook new file mode 100644 index 0000000..64cc4b7 --- /dev/null +++ b/main.docbook @@ -0,0 +1,125 @@ +<?xml version="1.0" encoding="utf-8"?> +<book xmlns="http://docbook.org/ns/docbook" + xmlns:xl="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" xml:lang="en" + xml:id="index"> + <info> + <title>Gentoo Development Manual</title> + + <author> + <personname> + <firstname>Ciaran</firstname> + <surname>McCreesh</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Grant</firstname> + <surname>Goodyear</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Aaron</firstname> + <surname>Walker</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Robert</firstname> + <surname>Coie</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Tom</firstname> + <surname>Martin</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Paul</firstname> + <surname>Varner</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Ilya</firstname> + <surname>Volynets-Evenbakh</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Diego E.</firstname> + <surname>Pettenò</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Fernando J.</firstname> + <surname>Pereda</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Simon</firstname> + <surname>Stelling</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Alin</firstname> + <surname>Dobre</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Joseph</firstname> + <surname>Jezak</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Tim</firstname> + <surname>Yamin</surname> + </personname> + </author> + + <author> + <personname> + <firstname>Mark</firstname> + <surname>Loeser</surname> + </personname> + </author> + + <legalnotice> + <para> + This document is an ongoing work in progress. It contains gaps, inaccuracies, omissions, typos and the + occasional outright lie. The intent is to make a handbook giving developers and users correct, detailed, up to + date technical content. + </para> + + <para> + Contributions are encouraged. See the <xref linkend="contributing" /> section for how to get started. If you + have any corrections, suggestions or improvements please file a bug at <link + xl:href="http://bugs.gentoo.org">bugs.gentoo.org</link> and assign it to <email>qa@gentoo.org</email>. The <xref + linkend="contributors" /> section lists specific contributions to this manual. + </para> + </legalnotice> + </info> + + <xi:include parse="xml" href="content/quickstart.xmli" /> +</book> |