aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTim Yamin <plasmaroo@gentoo.org>2006-03-11 01:20:28 +0000
committerTim Yamin <plasmaroo@gentoo.org>2006-03-11 01:20:28 +0000
commitcff18dbaed0136793dcdeaf739394acf017e3591 (patch)
treea3b834b943d8fe2e84434ed0f7fe4295f05dff49 /ebuild-writing
parentFix the code sample. (diff)
downloaddevmanual-cff18dbaed0136793dcdeaf739394acf017e3591.tar.gz
devmanual-cff18dbaed0136793dcdeaf739394acf017e3591.tar.bz2
devmanual-cff18dbaed0136793dcdeaf739394acf017e3591.zip
Add src_compile, fix valigns.
git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@25 176d3534-300d-0410-8db8-84e73ed771c3
Diffstat (limited to 'ebuild-writing')
-rw-r--r--ebuild-writing/functions/src_compile/build-environment/text.xml149
-rw-r--r--ebuild-writing/functions/src_compile/building/text.xml75
-rw-r--r--ebuild-writing/functions/src_compile/configuring/text.xml84
-rw-r--r--ebuild-writing/functions/src_compile/distutils/text.xml85
-rw-r--r--ebuild-writing/functions/src_compile/no-build-system/text.xml46
-rw-r--r--ebuild-writing/functions/src_compile/text.xml85
-rw-r--r--ebuild-writing/functions/text.xml1
7 files changed, 525 insertions, 0 deletions
diff --git a/ebuild-writing/functions/src_compile/build-environment/text.xml b/ebuild-writing/functions/src_compile/build-environment/text.xml
new file mode 100644
index 0000000..c2ec07e
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/build-environment/text.xml
@@ -0,0 +1,149 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_compile/build-environment/">
+<chapter>
+<title>Configuring Build Environment</title>
+
+<body>
+<p>
+Sometimes it is necessary to manipulate certain aspects of the user's
+build environment before running <c>./configure</c>. The <c>flag-o-matic</c>
+eclass is the best choice for manipulating <c>CFLAGS</c>, <c>LDFLAGS</c>
+and suchlike.
+</p>
+
+<note>
+Except where otherwise specified, any function which operates on
+<c>CFLAGS</c> also operates on <c>CXXFLAGS</c>.
+</note>
+
+<p>
+Ebuilds must not simply ignore use CFLAGS <d/> see <uri link="::general-concepts/user-environment#Not Filtering Variables"/>.
+</p>
+</body>
+
+<section>
+<title>Guidelines for Flag Filtering</title>
+<body>
+
+<p>
+If a package breaks with any reasonable <c>CFLAGS</c>, it is best to filter the
+problematic flag if a bug report is received. Reasonable <c>CFLAGS</c> are
+<c>-march=</c>, <c>-mcpu=</c>, <c>-mtune=</c> (depending upon
+arch), <c>-O2</c>, <c>-Os</c> and <c>-fomit-frame-pointer</c>. Note that
+<c>-Os</c> should usually be replaced with <c>-O2</c> rather than being
+stripped entirely. The <c>-fstack-protector</c> flag should probably be
+in this group too, although our hardened team claim that this flag
+never ever breaks anything...
+</p>
+
+<p>
+The <c>-pipe</c> flag doesn't affect the generated code, so it's not really
+relevant here, but it's a sensible flag to have set globally.
+</p>
+
+<p>
+If a package breaks with other (insane) <c>CFLAGS</c>, it is perfectly
+OK to close the bug with a <b>WONTFIX</b> suggesting that the user
+picks more sensible global <c>CFLAGS</c>. Similarly, if you suspect
+that a bug is caused by insane <c>CFLAGS</c>, an <b>INVALID</b> resolution is
+suitable.
+</p>
+
+<p>
+All of the following assumes that the ebuild has an <c>inherit flag-o-matic</c>
+line in the correct place.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Simple Flag Stripping</title>
+<body>
+
+<p>
+The <c>filter-flags</c> function can be used to remove a particular flag from
+<c>CFLAGS</c>. Multiple arguments can be supplied; each is the name of a flag to
+remove.
+</p>
+
+<codesample lang="ebuild">
+ # -fomit-frame-pointer leads to nasty broken code on sparc thanks to a
+ # rather icky asm function
+ use sparc &amp;&amp; filter-flags -fomit-frame-pointer
+</codesample>
+
+<p>
+There is a <c>filter-ldflags</c> function available which does the equivalent
+for <c>LDFLAGS</c>.
+</p>
+
+<p>
+If a package is known to be very <c>CFLAGS</c> sensitive, the
+<c>strip-flags</c> function will remove most flags, leaving only a minimal
+conservative set of flags.
+</p>
+
+<codesample lang="ebuild">
+ # Our app hates screwy flags
+ strip-flags
+</codesample>
+
+</body>
+</section>
+
+<section>
+<title>Flag Replacement</title>
+<body>
+
+<p>
+To replace a flag with a different one, use <c>replace-flags</c>. This
+is most commonly used to replace <c>-Os</c> with <c>-O2</c>
+(or <c>-O3</c> with <c>-O2</c> if you are feeling kind).
+</p>
+
+<codesample lang="ebuild">
+ # Seems to have issues with -Os, switch to -O2
+ replace-flags -Os -O2
+</codesample>
+
+<p>
+There is also a special function named <c>replace-cpu-flags</c> for
+replacing CPU (<c>-mtune</c>, <c>-mcpu</c>, <c>-march</c>) designation
+flags. The last argument is the flag to use; previous arguments are
+the flags to be replaced.
+</p>
+
+<codesample lang="ebuild">
+ # Can't use ultrasparc or ultrasparc3 code, drop to v9
+ replace-cpu-flags ultrasparc ultrasparc3 v9
+</codesample>
+
+</body>
+</section>
+
+<section>
+<title>Adding Additional Flags</title>
+<body>
+<p>
+Sometimes it is necessary to add in additional <c>CFLAGS</c>
+or <c>LDFLAGS</c>. The <c>append-flags</c> and <c>append-ldflags</c>
+functions can be used here.
+</p>
+
+<codesample lang="ebuild">
+ # If we're using selinux, we need to add a -D
+ use selinux &amp;&amp; append-flags "-DWITH_SELINUX"
+
+ # Secure linking needed, since we're setuid root
+ append-ldflags -Wl,-z,now
+</codesample>
+
+<p>
+See `flag-o-matic.eclass Reference`_ for a full reference.
+</p>
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_compile/building/text.xml b/ebuild-writing/functions/src_compile/building/text.xml
new file mode 100644
index 0000000..171429e
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/building/text.xml
@@ -0,0 +1,75 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_compile/building/">
+<chapter>
+<title>Building a Package</title>
+
+<body>
+<p>
+The <c>emake</c> function should be used to call <c>make</c>. This will ensure that
+the user's <c>MAKEOPTS</c> are used correctly. The <c>emake</c> function passes on
+any arguments provided, so it can be used to make non-default targets (<c>emake
+extras</c>), for example. Occasionally you might encounter a screwy non-autotools
+<c>Makefile</c> that explodes with <c>emake</c>, but this is rare.
+</p>
+
+<p>
+Builds should be tested with various <c>-j</c> settings in <c>MAKEOPTS</c> to ensure
+that the build parallelises properly. If a package does <e>not</e> parallelise
+cleanly, it should be patched.
+</p>
+
+<p>
+If patching <e>really</e> isn't an option, <c>emake -j1</c> should be
+used. However, when doing this please remember that you are seriously
+hurting build times for many non-x86 users in particular. Forcing
+a <c>-j1</c> can increase build times from a few minutes to an hour on
+some MIPS and SPARC systems.
+</p>
+</body>
+
+<section>
+<title>Fixing Compiler Usage</title>
+<body>
+
+<p>
+Sometimes a package will try to use a bizarre compiler, or will need to be told
+which compiler to use. In these situations, the <c>tc-getCC()</c> function from
+<c>toolchain-funcs.eclass</c> should be used. Other similar functions are available
+<d/> these are documented in `toolchain-funcs.eclass-5`_.
+</p>
+
+<note>
+It is <e>not</e> correct to use the <c>${CC}</c> variable for this purpose.
+</note>
+
+<p>
+Sometimes a package will not use the user's <c>${CFLAGS}</c>. This must be worked
+around, as sometimes this variable is used for specifying critical ABI options.
+In these cases, the build scripts should be modified (for example, with <c>sed</c>)
+to use <c>${CFLAGS}</c> correctly.
+</p>
+
+<codesample lang="ebuild">
+inherit flag-o-matic toolchain-funcs
+
+src_compile() {
+ # -Os not happy
+ replace-flags -Os -O2
+
+ # We have a weird build.sh to work with which ignores our
+ # compiler preferences. yay!
+ sed -i -e "s:cc -O2:$(tc-getCC) ${CFLAGS}:" build.sh \
+ || die "sed fix failed. Uh-oh..."
+ ./build.sh || die "Build failed!"
+}
+</codesample>
+
+<note>
+When using <c>sed</c> with <c>CFLAGS</c>, it is not safe to use a comma or a
+slash as a delimiter. The vapier-recommended character is a colon.
+</note>
+
+</body>
+</section>
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_compile/configuring/text.xml b/ebuild-writing/functions/src_compile/configuring/text.xml
new file mode 100644
index 0000000..b085906
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/configuring/text.xml
@@ -0,0 +1,84 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_compile/configuring/">
+<chapter>
+<title>Configuring a Package</title>
+
+<body>
+<p>
+Many packages come with an autoconf-generated <c>./configure</c>
+script for checking the build environment and configuring optional
+support for libraries. The <c>econf</c> function should be used where
+possible <d/> this will provide correct build and path specifications for
+a Gentoo environment.
+</p>
+
+<p>
+Often the configure script will try to automatically enable support
+for optional components based upon installed packages. This
+must <b>not</b> be allowed to happen. For example, if a user has Perl
+installed but has <c>USE="-perl"</c>, packages with <e>optional</e>
+Perl support must not link against Perl. This automatic detection can
+usually be overridden using <c>--enable-</c> and <c>--disable</c>
+or <c>--with-</c> and <c>--without-</c> switches (but note that these
+don't always work <d/> make sure these are tested properly!).
+</p>
+
+<p>
+The <c>use_enable</c> and <c>use_with</c> utility functions should,
+where appropriate, be used to generate these switches.
+</p>
+
+<codesample lang="ebuild">
+src_compile() {
+ # We have optional perl, python and ruby support
+ econf \
+ $(use_enable perl ) \
+ $(use_enable python ) \
+ $(use_enable ruby ) \
+ || die "Configure failed!"
+
+ # ...
+}
+
+src_compile() {
+ # Our package optional IPv6 support which uses --with rather than
+ # --enable / --disable
+
+ econf $(use_with ipv6 ) || die "econf failed!"
+
+ # ...
+}
+</codesample>
+
+<p>
+Sometimes the package's choice of name for the option will not exactly
+match the name or case of the <c>USE</c> flag. This is very often the
+case with the <c>X</c> flag. For these situations, there are two
+argument forms:
+</p>
+
+<codesample lang="ebuild">
+src_compile() {
+ # Our package has optional perl, python and ruby support
+ econf \
+ $(use_enable perl perlinterp ) \
+ $(use_enable python pythoninterp ) \
+ $(use_enable ruby rubyinterp ) \
+ || die "Configure failed!"
+
+ # ...
+}
+
+src_compile() {
+ econf $(use_with X x11 ) || die "econf failed!"
+}
+</codesample>
+
+<p>
+To check for an unset <c>USE</c> flag, the <c>use_enable !flag</c>
+form can be used.
+</p>
+</body>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_compile/distutils/text.xml b/ebuild-writing/functions/src_compile/distutils/text.xml
new file mode 100644
index 0000000..15f1132
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/distutils/text.xml
@@ -0,0 +1,85 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_compile/distutils/">
+<chapter>
+<title>Distutils</title>
+
+<section>
+<title>General overview</title>
+
+<body>
+<p>
+The Python packaging system is known as "distutils", and the hallmark
+of a Python package using distutils is the presence of a <c>setup.py</c>
+file. (One can think of the <c>setup.py</c> file as the Python equivalent of
+a Makefile.) Although distutils is straightforward to use by directly
+running the <c>setup.py</c> with the appropriate arguments, the distutils
+eclass makes the process much simpler (and dramatically lowers the
+chance of sandbox violations). For example, for the <c>dev-python/id3-py</c>
+package the body of the ebuild (other than the header and URIs) could
+have been written as just:
+</p>
+
+<codesample lang="ebuild">
+inherit distutils
+
+DOCS="CHANGES"
+</codesample>
+
+<p>
+Any files listed in <c>${DOCS}</c> will be put in the docs directory when
+installed. Note that older versions of the distutils eclass used
+<c>${mydoc}</c> instead, but the preferred variable is <c>DOCS</c>.
+</p>
+
+<p>
+In practice, some tweaking is often required in
+the <c>src_compile()</c> or, more commonly, in
+the <c>src_install()</c> steps, and the distutils eclass provides
+the <c>distutils_src_compile()</c> and
+the <c>distutils_src_install()</c> convenience functions:
+</p>
+
+<codesample lang="ebuild">
+src_compile() {
+ distutils_src_compile
+ # ...
+}
+
+src_install() {
+ # From the docutils ebuild
+ distutils_src_install
+ cd ${S}/tools
+ for tool in *.py; do
+ newbin ${tool} docutils-${tool}
+ done
+
+ # ...
+}
+</codesample>
+
+</body>
+</section>
+
+<section>
+<title>Tkinter (Tk) support</title>
+<body>
+
+<p>
+Until Portage gains the long-requested ability to depend on <c>USE</c>
+flags, ebuild authors who package graphical Python programs will
+probably need to check at emerge-time whether or not Python was
+compiled with support for Tkinter. Since Tkinter requires Tk, which
+requires X, default Python builds do not include Tkinter. It's easy
+enough to check:
+</p>
+
+<codesample lang="ebuild">
+pkg_setup() {
+ distutils_python_tkinter
+}
+</codesample>
+
+</body>
+</section>
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_compile/no-build-system/text.xml b/ebuild-writing/functions/src_compile/no-build-system/text.xml
new file mode 100644
index 0000000..22649be
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/no-build-system/text.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_compile/no-build-system/">
+<chapter>
+<title>No Build System</title>
+
+<body>
+<p>
+Occasionally some really small packages are shipped simply as a single
+<c>.c</c> file. In these circumstances, you can either write your own
+<c>Makefile</c> and ship it with the source tarball, or just manually
+compile the thing from within the ebuild. Here's an example, from
+<c>app-misc/hilite</c>:
+</p>
+
+<codesample lang="ebuild">
+src_compile() {
+ $(tc-getCC ) ${CFLAGS} -o ${PN} ${P}.c \
+ || die "Compile failed!"
+}
+</codesample>
+
+<p>
+Here's an example from <c>x11-plugins/gkrelltop</c>, which ships with a
+<c>Makefile</c> that doesn't actually work:
+</p>
+
+<codesample lang="ebuild">
+src_compile() {
+ CONFIG="-DLINUX -DGKRELLM2 -fPIC `pkg-config gtk+-2.0 --cflags`"
+ LIBS="`pkg-config gtk+-2.0 --libs` -shared"
+ OBJS="top_three2.o gkrelltop2.o"
+
+ gcc -c $CONFIG $CFLAGS top_three.c -o top_three2.o || die
+ gcc -c $CONFIG $CFLAGS gkrelltop.c -o gkrelltop2.o || die
+ gcc $LIBS $CONFIG $CFLAGS -o gkrelltop2.so $OBJS || die
+}
+</codesample>
+
+<p>
+A possibly better alternative would be to patch the <c>Makefile</c>
+and send it upstream.
+</p>
+
+</body>
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/src_compile/text.xml b/ebuild-writing/functions/src_compile/text.xml
new file mode 100644
index 0000000..4e0709b
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/text.xml
@@ -0,0 +1,85 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/functions/src_compile/">
+<chapter>
+<title>src_compile</title>
+
+<body>
+<table>
+ <tr>
+ <th>Function</th>
+ <ti><c>src_compile</c></ti>
+ </tr>
+ <tr>
+ <th>Purpose</th>
+ <ti>Configure and build the package.</ti>
+ </tr>
+ <tr>
+ <th>Sandbox</th>
+ <ti>Enabled</ti>
+ </tr>
+ <tr>
+ <th>Privilege</th>
+ <ti>user</ti>
+ </tr>
+ <tr>
+ <th>Called for</th>
+ <ti>ebuild</ti>
+ </tr>
+</table>
+</body>
+
+<section>
+<title>Default <c>src_compile</c></title>
+<body>
+<codesample lang="ebuild">
+src_compile() {
+ if [ -x ./configure ]; then
+ econf
+ fi
+ if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then
+ emake || die "emake failed"
+ fi
+}
+</codesample>
+</body>
+</section>
+
+<section>
+<title>Sample <c>src_compile</c></title>
+<body>
+<codesample lang="ebuild">
+src_compile() {
+ use sparc &amp;&amp; filter-flags -fomit-frame-pointer
+ append-ldflags -Wl,-z,now
+
+ econf \
+ $(use_enable ssl ) \
+ $(use_enable perl perlinterp ) \
+ || die "Configure failed!"
+
+ emake || die "Make failed!"
+}
+</codesample>
+</body>
+</section>
+
+<section>
+<title><c>src_compile</c> Processes</title>
+<body>
+<p>
+The following subsections cover different topics which often occur when writing
+<c>src_compile</c> functions.
+</p>
+
+<contentsTree/>
+</body>
+</section>
+
+</chapter>
+
+<include href="build-environment/"/>
+<include href="configuring/"/>
+<include href="building/"/>
+<include href="distutils/"/>
+<include href="no-build-system/"/>
+</guide>
diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml
index 25e8966..3bed50d 100644
--- a/ebuild-writing/functions/text.xml
+++ b/ebuild-writing/functions/text.xml
@@ -32,4 +32,5 @@ obtain some <c>SRC_URI</c> components.
</chapter>
<include href="src_unpack/"/>
+<include href="src_compile/"/>
</guide>