diff options
| author |   Tim Yamin <plasmaroo@gentoo.org> | 2006-03-11 01:20:28 +0000 |
|---|---|---|
| committer | Tim Yamin <plasmaroo@gentoo.org> | 2006-03-11 01:20:28 +0000 |
| commit | cff18dbaed0136793dcdeaf739394acf017e3591 (patch) | |
| tree | a3b834b943d8fe2e84434ed0f7fe4295f05dff49 /ebuild-writing | |
| parent | Fix the code sample. (diff) | |
| download | devmanual-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')
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 && 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 && 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 && 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> |