docs/usermanual/reference/class_autotools.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <section id="autotools_class" xreflabel="autotools class">
   3   <title>autotools class</title>
   4
   5   <para>Autotools is one of the most commonly seen configuration methods for
   6   applications. Anything that uses the standard <command>./configure; make;
   7   make install</command> sequence is using autotools. Usually the configure
   8   script will support a large number of options to specify various
   9   installation directories, to disable and/or enable various features and
  10   options to specify search paths for headers and libraries.</para>
  11
  12   <para>The autotools class takes care of all of the details for you. It
  13   defines appropriate tasks for <emphasis>configure</emphasis>,
  14   <emphasis>compile</emphasis>, <emphasis>stage</emphasis> and
  15   <emphasis>install</emphasis>. At it's simplest adding an inherit for the
  16   autotools class is all that is required. The netcat recipe for example
  17   is:<screen>DESCRIPTION = "GNU Netcat"
  18 HOMEPAGE = "http://netcat.sourceforge.net"
  19 LICENSE = "GPLv2"
  20 MAINTAINER = "Your name &lt;yname@example.com&gt;"
  21 SECTION = "console/networking"
  22 PR = "r1"
  23
  24 SRC_URI = "${SOURCEFORGE_MIRROR}/netcat/netcat-${PV}.tar.bz2"
  25
  26 inherit autotools</screen>The header is defined, the location of the source
  27   code and then the inherit. For the simplest cases this is all that is
  28   required. If you need to pass additional parameters to the configure script,
  29   such as for enabling and/or disabling options, then they can be specified
  30   via the <command>EXTRA_OECONF</command> variable. This example from the lftp
  31   recipe shows several extra options being passed to the configure
  32   script:<screen>EXTRA_OECONF = "--disable-largefile --disable-rpath --with-included-readline=no"</screen>If
  33   you define your own tasks for <emphasis>configure</emphasis>,
  34   <emphasis>compile</emphasis>, <emphasis>stage</emphasis> or
  35   <emphasis>install</emphasis> (via <command>do_&lt;taskname&gt;</command>)
  36   then they will override the methods generated by the autotools class. If you
  37   need to perform additional operations (rather than replacing the generated
  38   operations) you can use the <command>do_&lt;task&gt;_append</command> or
  39   <command>do_&lt;task&gt;_prepend</command> methods. The following example
  40   from the conserver recipe shows some additional items being
  41   installed:<screen># Include the init script and default settings in the package
  42 do_install_append () {
  43     install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d
  44     install -m 0644 ${WORKDIR}/conserver.default ${D}${sysconfdir}/default/conserver
  45     install -m 0755 ${WORKDIR}/conserver.init ${D}${sysconfdir}/init.d/conserver
  46 }</screen></para>
  47
  48   <section>
  49     <title>oe_runconf / autotools_do_configure</title>
  50
  51     <para>Autotools generates a configuration method called
  52     <command>oe_runconf</command> which runs the actual configure script, and
  53     a method called <command>autotools_do_configure</command> which generates
  54     the configure file (runs automake and autoconf) and then calls
  55     <command>oe_runconf</command>. The generated method for the
  56     <emphasis>configure</emphasis> task, <command>do_configure</command>, just
  57     calls the <command>autotools_do_configure</command> method.</para>
  58
  59     <para>It is sometimes desirable to implement your own
  60     <command>do_configure</command> method, where additional configuration is
  61     required or where you wish to inhibit the running of automake and
  62     autoconf, and then manually call <command>oe_runconf</command>.</para>
  63
  64     <para>The following example from the ipacct recipe shows an example of
  65     avoiding the use of automake/autoconf:<screen>do_configure() {
  66     oe_runconf
  67 }</screen>Sometimes manual manipulations of the autotools files is required
  68     prior to calling autoconf/automake. In this case you can defined your own
  69     <command>do_configure</command> method which performs the required actions
  70     and then calls <command>autotools_do_configure</command>.</para>
  71   </section>
  72
  73   <section>
  74     <title>Presetting autoconf variables (the site file)</title>
  75
  76     <para>The autotools configuration method has support for caching the
  77     results of tests. In the cross-compilation case it is sometimes necessary
  78     to prime the cache with per-calculated results (since tests designed to
  79     run on the target cannot be run when cross-compiling). These are defined
  80     via the site file(s) for the architecture you are using and may be
  81     specific to the package you are building.</para>
  82
  83     <para>Autoconf uses site files as definied in the
  84     <command>CONFIG_SITE</command> variable, which is a space seperate list of
  85     files to load in the specified order. Details on how this variable is set
  86     is provided in the <xref linkend="siteinfo_class" /> (the class
  87     responsbile for setting the variable) section.</para>
  88
  89     <para>There are some things that you should keep in mind about the caching
  90     of configure tests:</para>
  91
  92     <orderedlist>
  93       <listitem>
  94         <para>Check the other site files to see if there any entries for the
  95         application you are attempting to build.</para>
  96
  97         <para>Sometimes entries are only updated for the target that the
  98         developer has access to. If they exist for another target then it may
  99         provide a good idea of what needs to be defined.</para>
 100       </listitem>
 101
 102       <listitem>
 103         <para>Sometimes the same cache value is used by multiple
 104         applications.</para>
 105
 106         <para>This can have the side effect where a value added for one
 107         application breaks the build of another. It is a very good idea to
 108         empty the site file of all other values if you are having build
 109         problems to ensure that none of the existing values are causing
 110         problems.</para>
 111       </listitem>
 112
 113       <listitem>
 114         <para>Not all values can be stored in the cache</para>
 115
 116         <para>Caching of variables is defined by the author of the configure
 117         script, so sometimes not all variables can be set via the cache. In
 118         this case it often means resorting to patching the original configure
 119         scripts to achieve the desired result.</para>
 120       </listitem>
 121     </orderedlist>
 122
 123     <para>All site files are shell scripts which are run by autoconf and
 124     therefore the syntax is the same as you would use in sh. There are two
 125     current methods of settings variables that is used in the existing site
 126     files. This include explicitly settings the value of the variable:<screen>ac_cv_sys_restartable_syscalls=yes</screen>and
 127     conditionally setting the value of the variable:<screen>ac_cv_uchar=${ac_cv_uchar=no}</screen>The
 128     conditional version is using shell syntax to say "<emphasis>only set this
 129     to the specified value if it is not currently set</emphasis>". The
 130     conditional version allows the variable to be set in the shell prior to
 131     calling configure and it will then not be replaced by the value from the
 132     site file.</para>
 133
 134     <note>
 135       <para>Site files are applied in order, so the application specific site
 136       files will be applied prior to the top level site file entries. The use
 137       of conditional assignment means that the first definition found will
 138       apply, while when not using conditionals the last definition found will
 139       apply.</para>
 140     </note>
 141
 142     <para>It is possible to disable the use of the cached values from the site
 143     file by clearing the definition of <command>CONFIG_SITE</command> prior to
 144     running the configure script. Doing this will disable the use of the site
 145     file entirely. This however should be used as a last resort. The following
 146     example from the db recipe shows an example of this:<screen># Cancel the site stuff - it's set for db3 and destroys the
 147 # configure.
 148 CONFIG_SITE = ""
 149 do_configure() {
 150     oe_runconf
 151 }</screen></para>
 152   </section>
 153 </section>