diff options
Diffstat (limited to 'docs/usermanual/reference/class_autotools.xml')
| -rw-r--r-- | docs/usermanual/reference/class_autotools.xml | 153 |
1 files changed, 153 insertions, 0 deletions
diff --git a/docs/usermanual/reference/class_autotools.xml b/docs/usermanual/reference/class_autotools.xml new file mode 100644 index 0000000000..a9e1a5721a --- /dev/null +++ b/docs/usermanual/reference/class_autotools.xml @@ -0,0 +1,153 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="autotools_class" xreflabel="autotools class"> + <title>autotools class</title> + + <para>Autotools is one of the most commonly seen configuration methods for + applications. Anything that uses the standard <command>./configure; make; + make install</command> 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.</para> + + <para>The autotools class takes care of all of the details for you. It + defines appropriate tasks for <emphasis>configure</emphasis>, + <emphasis>compile</emphasis>, <emphasis>stage</emphasis> and + <emphasis>install</emphasis>. At it's simplest adding an inherit for the + autotools class is all that is required. The netcat recipe for example + is:<screen>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 autotools</screen>The header is defined, the location of the source + code and then the inherit. For the simplest cases this is all that is + required. If you need to pass additional parameters to the configure script, + such as for enabling and/or disabling options, then they can be specified + via the <command>EXTRA_OECONF</command> variable. This example from the lftp + recipe shows several extra options being passed to the configure + script:<screen>EXTRA_OECONF = "--disable-largefile --disable-rpath --with-included-readline=no"</screen>If + you define your own tasks for <emphasis>configure</emphasis>, + <emphasis>compile</emphasis>, <emphasis>stage</emphasis> or + <emphasis>install</emphasis> (via <command>do_<taskname></command>) + 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 <command>do_<task>_append</command> or + <command>do_<task>_prepend</command> methods. The following example + from the conserver recipe shows some additional items being + installed:<screen># 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 +}</screen></para> + + <section> + <title>oe_runconf / autotools_do_configure</title> + + <para>Autotools generates a configuration method called + <command>oe_runconf</command> which runs the actual configure script, and + a method called <command>autotools_do_configure</command> which generates + the configure file (runs automake and autoconf) and then calls + <command>oe_runconf</command>. The generated method for the + <emphasis>configure</emphasis> task, <command>do_configure</command>, just + calls the <command>autotools_do_configure</command> method.</para> + + <para>It is sometimes desirable to implement your own + <command>do_configure</command> method, where additional configuration is + required or where you wish to inhibit the running of automake and + autoconf, and then manually call <command>oe_runconf</command>.</para> + + <para>The following example from the ipacct recipe shows an example of + avoiding the use of automake/autoconf:<screen>do_configure() { + oe_runconf +}</screen>Sometimes manual manipulations of the autotools files is required + prior to calling autoconf/automake. In this case you can defined your own + <command>do_configure</command> method which performs the required actions + and then calls <command>autotools_do_configure</command>.</para> + </section> + + <section> + <title>Presetting autoconf variables (the site file)</title> + + <para>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 per-calculated results (since tests designed to + run on the target cannot be run when cross-compiling). These are defined + via the site file(s) for the architecture you are using and may be + specific to the package you are building.</para> + + <para>Autoconf uses site files as definied in the + <command>CONFIG_SITE</command> variable, which is a space seperate list of + files to load in the specified order. Details on how this variable is set + is provided in the <xref linkend="siteinfo_class" /> (the class + responsbile for setting the variable) section.</para> + + <para>There are some things that you should keep in mind about the caching + of configure tests:</para> + + <orderedlist> + <listitem> + <para>Check the other site files to see if there any entries for the + application you are attempting to build.</para> + + <para>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.</para> + </listitem> + + <listitem> + <para>Sometimes the same cache value is used by multiple + applications.</para> + + <para>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.</para> + </listitem> + + <listitem> + <para>Not all values can be stored in the cache</para> + + <para>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.</para> + </listitem> + </orderedlist> + + <para>All site files are shell scripts which are run by autoconf and + therefore the syntax is the same as you would use in sh. There are two + current methods of settings variables that is used in the existing site + files. This include explicitly settings the value of the variable:<screen>ac_cv_sys_restartable_syscalls=yes</screen>and + conditionally setting the value of the variable:<screen>ac_cv_uchar=${ac_cv_uchar=no}</screen>The + conditional version is using shell syntax to say "<emphasis>only set this + to the specified value if it is not currently set</emphasis>". The + conditional version allows the variable to be set in the shell prior to + calling configure and it will then not be replaced by the value from the + site file.</para> + + <note> + <para>Site files are applied in order, so the application specific site + files will be applied prior to the top level site file entries. The use + of conditional assignment means that the first definition found will + apply, while when not using conditionals the last definition found will + apply.</para> + </note> + + <para>It is possible to disable the use of the cached values from the site + file by clearing the definition of <command>CONFIG_SITE</command> prior to + running the configure script. Doing this will disable 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:<screen># Cancel the site stuff - it's set for db3 and destroys the +# configure. +CONFIG_SITE = "" +do_configure() { + oe_runconf +}</screen></para> + </section> +</section>
\ No newline at end of file |