From 3dc9d384a8812b506c0132fd76318d228430d211 Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Wed, 9 Aug 2006 09:39:47 +0000 Subject: usermanual: Add details on the autotools class to the reference section. --- usermanual/reference/class_autotools.xml | 143 +++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 usermanual/reference/class_autotools.xml (limited to 'usermanual/reference') diff --git a/usermanual/reference/class_autotools.xml b/usermanual/reference/class_autotools.xml new file mode 100644 index 0000000000..0538da3597 --- /dev/null +++ b/usermanual/reference/class_autotools.xml @@ -0,0 +1,143 @@ + +
+ autotools + + Autotools is one of the most commonly seen configuration methods for + applications. Anything that uses the standard ./configure; make; + make install sequence is using autotools. Usually the configure + script will support a large number of options to specify various + installation directories, to disable and/or enable various features and + options to specify search paths for headers and libraries. + + The autotools class takes care of all of the details for you. It + defines appropriate tasks for do_configure, + do_compile, do_stage and + do_install. At it's simplest adding an inherit for the + autotools class is all that is required. The netcat recipe for example + is:DESCRIPTION = "GNU Netcat" +HOMEPAGE = "http://netcat.sourceforge.net" +LICENSE = "GPLv2" +MAINTAINER = "Your name <yname@example.com>" +SECTION = "console/networking" +PR = "r1" + +SRC_URI = "${SOURCEFORGE_MIRROR}/netcat/netcat-${PV}.tar.bz2" + +inherit autotoolsThe header is defined, the location of the source + code and then inherit. For the simplest cases that is all that is required. + If you need to pass addition parameters to the configure script, such as for + enabling and/or disabling options, then they can be specified via the + EXTRA_OECONF variable. This example from the lftp recipe + shows several extra options being passed to the configure script:EXTRA_OECONF = "--disable-largefile --disable-rpath --with-included-readline=no"If + you define your own tasks for do_configure, + do_compile, do_stage or + do_install then they will override the methods generated + by the autotools class. If you need to perform additional operations (rather + than replacing the generated operations) you can use the + do_<task>_append or + do_<task>_prepend methods. The following example + from the conserver recipe shows some additional items being + installed:# Include the init script and default settings in the package +do_install_append () { + install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d + install -m 0644 ${WORKDIR}/conserver.default ${D}${sysconfdir}/default/conserver + install -m 0755 ${WORKDIR}/conserver.init ${D}${sysconfdir}/init.d/conserver +} + +
+ oe_runconf / autotools_do_configure + + Autotools generates a configuration method called + oe_runconf which runs the actual configure script, and + a method called autotools_do_configure which generates + the configure file (runs automake and autoconf) and then calls + oe_runconf. The generated + do_configure task just calls + autotools_do_configure. + + It is sometimes desirable to implement your own + do_configure method, where additional configuration is + required or where you wish to inhibit the running of automake and + autoconf, and then manually call oe_runconf. + + The following example from the ipacct recipe shows an example of + avoiding the use of automake/autoconf:do_configure() { + oe_runconf +}Sometimes manual manipulations of the autotools files is required + prior to calling autoconf/automake. In this case you can defined your own + do_configure which performs the required actions and then calls + autotools_do_configure. +
+ +
+ Presetting autoconf variables (the site file) + + The autotools configuration method has support for caching the + results of tests. In the cross-compilation case it is sometimes necessary + to prime the cache with pre-calculated results (since tests designed to + run on the target cannot be run when cross-compiling). These are defined + via the site file for the architecture you are using which is found in + org.openembedded.dev/site/<arch>-<target-os>. + + There are some things that you should keep in mind about the caching + of configure tests: + + + + Check the other site files to see if there any entries for the + application you are attempting to build. + + Sometimes entries are only updated for the target that the + developer has access to. If they exist for another target then it may + provide a good idea of what needs to be defined. + + + + Sometimes the same cache value is used by multiple + applications. + + This can have the side effect where a value added for one + application breaks the build of another. It is a very good idea to + empty the site file of all other values if you are having build + problems to ensure that none of the existing values are causing + problems. + + + + Not all values can be stored in the cache + + Caching of variables is defined by the author of the configure + script, so sometimes not all variables can be set via the cache. In + this case it often means resorting to patching the original configure + scripts to achieve the desired result. + + + + Sometimes it's useful to manually check values from the site file. + This can prove useful in situations where autotools is not used but you + still need some of the same information that an autotools configure script + would require. The following from the net-snmp recipe shows an example of + using the existing site file entries for endianess to pass the required + endianess option to the configure script:do_configure() { + # endianness fun.. inspired by openssl.inc + . ${CONFIG_SITE} + if test "x$ac_cv_c_bigendian" = "xyes"; then + ENDIANESS=" --with-endianness=big" + elif test "x$ac_cv_c_littleendian" = "xyes"; then + ENDIANESS=" --with-endianness=little" + else + oefatal do_configure cannot determine endianess + fi + oe_runconf $ENDIANESS +}It is also possible to disable the use of the cached values from the + site file by clearing the definition of CONFIG_SITE + prior to running the configure script. Doing this disables the use of the + site file entirely. This however should be used as a last resort. The + following example from the db recipe shows an example of this:# Cancel the site stuff - it's set for db3 and destroys the +# configure. +CONFIG_SITE = "" +do_configure() { + oe_runconf +} +
+
\ No newline at end of file -- cgit 1.2.3-korg