Documentation fixes and updates

The biggest update is to document the Makefile.autotools.in way of
writing .mk files.

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

1 files changed, 147 insertions, 76 deletions

diff --git a/docs/buildroot.html b/docs/buildroot.html
index fbe69fb96..026791fcc 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -117,7 +117,7 @@
     <h2><a name="download" id="download"></a>Obtaining Buildroot</h2>
 
     <p>Buildroot is available as daily SVN snapshots or directly using
-    SVN. </p>
+    SVN. As of today, no stable releases of Buildroot are made. </p>
 
     <p>The latest snapshot is always available at <a
     href="http://buildroot.uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2">http://buildroot.uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2</a>,
@@ -444,7 +444,7 @@ $ make me&lt;TAB&gt;
     </ul>
 
     <p>The main Makefile do the job through the following steps (once the
-    configuration is done):</p>
+    configuration is done) :</p>
 
     <ol>
       <li>Create the download directory (<code>dl/</code> by default). This is
@@ -890,7 +890,7 @@ config BR2_PACKAGE_FOO
     things in your software. </p>
     <p>Finally you have to add your new <code>foo/Config.in</code> to
     <code>package/Config.in</code>. The files included there are
-    <em>sorted alphabetically</em> per category and are <em>NOT<em>
+    <em>sorted alphabetically</em> per category and are <em>NOT</em>
     supposed to contain anything but the <em>bare</em> name of the package.</p>
 <pre>
 if !BR2_PACKAGE_BUSYBOX_HIDE_OTHERS
@@ -906,68 +906,139 @@ endif
    <p>Finally, here's the hardest part. Create a file named
    <code>foo.mk</code>. It will contain the <i>Makefile</i> rules that
    are in charge of downloading, configuring, compiling and installing
-   the software. Below is an example that we will comment
-   afterwards. </p>
+   the software.</p>
+
+   <p>Two types of <i>Makefiles</i> can be written&nbsp;:</p>
+
+   <ul>
+    <li>Makefile for autotools-based (autoconf, automake, etc.)
+    softwares, are very easy to write thanks to the infrastructure
+    available in <code>package/Makefile.autotools.in</code>.</li>
+    <li>Makefile for other types of packages are a little bit more
+    complex to write.</li>
+   </ul>
+
+   <p>First, let's see how to write a <i>Makefile</i> for an
+   autotools-based package, with an example&nbsp;:</p>
+
+<pre>
+     <a name="ex1line1" id="ex1line1">1</a>  #############################################################
+     <a name="ex1line2" id="ex1line2">2</a>  #
+     <a name="ex1line3" id="ex1line3">3</a>  # foo
+     <a name="ex1line4" id="ex1line4">4</a>  #
+     <a name="ex1line5" id="ex1line5">5</a>  #############################################################
+     <a name="ex1line6" id="ex1line6">6</a>  FOO_VERSION:=1.0
+     <a name="ex1line7" id="ex1line7">7</a>  FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz
+     <a name="ex1line8" id="ex1line8">8</a>  FOO_SITE:=http://www.foosoftware.org/downloads
+     <a name="ex1line9" id="ex1line9">9</a>  FOO_INSTALL_STAGING = YES
+     <a name="ex1line10" id="ex1line10">10</a>  FOO_INSTALL_TARGET = YES
+     <a name="ex1line11" id="ex1line11">11</a>  FOO_CONF_OPT =  --enable-shared
+     <a name="ex1line12" id="ex1line12">12</a>  FOO_DEPENDENCIES = libglib2 pkgconfig
+     <a name="ex1line13" id="ex1line13">13</a>  $(eval $(call AUTOTARGETS,package,foo))
+</pre>
+
+    <p>On <a href="#ex1line6">line 6</a>, we declare the version of
+    the package. On line <a href="#ex1line7">7</a> and <a
+    href="#ex1line8">8</a>, we declare the name of the tarball and the
+    location of the tarball on the Web. Buildroot will automatically
+    download the tarball from this location.</p>
+
+    <p>On <a href="#ex1line9">line 9</a>, we tell Buildroot to install
+    the application to the staging directory. The staging directory,
+    located in <code>build_ARCH/staging_dir/</code> is the directory
+    where all the packages are installed, including their
+    documentation, etc. By default, packages are installed in this
+    location using the <code>make install</code> command.</p>
+
+    <p>On <a href="#ex1line10">line 10</a>, we tell Buildroot to also
+    install the application to the target directory. This directory
+    contains what will become the root filesystem running on the
+    target. Usually, we try not to install the documentation, and to
+    install stripped versions of the binary. By default, packages are
+    installed in this location using the <code>make
+    install-strip</code> command.</p>
+
+    <p>On <a href="#ex1line11">line 11</a>, we tell Buildroot to pass
+    a custom configure option, that will be passed to the
+    <code>./configure</code> script before configuring and building
+    the package.</p>
+
+    <p>On <a href="#ex1line12">line 12</a>, we declare our
+    dependencies, so that they are built before the build process of
+    our package starts.</p>
+
+    <p>Finally, on line <a href="#ex1line13">line 13</a>, we invoke
+    the <code>package/Makefile.autotools.in</code> magic to get things
+    working.</p>
+
+    <p>For more details about the available variables and options, see
+    the comment at the top of
+    <code>package/Makefile.autotools.in</code> and the examples in all
+    the available packages.</p>
+
+    <p>The second solution, suitable for every type of package, looks
+    like this&nbsp;:</p>
+
 
 <pre>
-     <a name="line1" id="line1">1</a>  #############################################################
-     <a name="line2" id="line2">2</a>  #
-     <a name="line3" id="line3">3</a>  # foo
-     <a name="line4" id="line4">4</a>  #
-     <a name="line5" id="line5">5</a>  #############################################################
-     <a name="line6" id="line6">6</a>  FOO_VERSION:=1.0
-     <a name="line7" id="line7">7</a>  FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz
-     <a name="line8" id="line8">8</a>  FOO_SITE:=http://www.foosoftware.org/downloads
-     <a name="line9" id="line9">9</a>  FOO_DIR:=$(BUILD_DIR)/foo-$(FOO_VERSION)
-    <a name="line10" id="line10">10</a>  FOO_BINARY:=foo
-    <a name="line11" id="line11">11</a>  FOO_TARGET_BINARY:=usr/bin/foo
-    <a name="line12" id="line12">12</a>
-    <a name="line13" id="line13">13</a>  $(DL_DIR)/$(FOO_SOURCE):
-    <a name="line14" id="line14">14</a>          $(WGET) -P $(DL_DIR) $(FOO_SITE)/$(FOO_SOURCE)
-    <a name="line15" id="line15">15</a>
-    <a name="line16" id="line16">16</a>  $(FOO_DIR)/.source: $(DL_DIR)/$(FOO_SOURCE)
-    <a name="line17" id="line17">17</a>          $(ZCAT) $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
-    <a name="line18" id="line18">18</a>          touch $@
-    <a name="line19" id="line19">19</a>
-    <a name="line20" id="line20">20</a>  $(FOO_DIR)/.configured: $(FOO_DIR)/.source
-    <a name="line21" id="line21">21</a>          (cd $(FOO_DIR); rm -rf config.cache; \
-    <a name="line22" id="line22">22</a>                  $(TARGET_CONFIGURE_OPTS) \
-    <a name="line23" id="line23">23</a>                  $(TARGET_CONFIGURE_ARGS) \
-    <a name="line24" id="line24">24</a>                  ./configure \
-    <a name="line25" id="line25">25</a>                  --target=$(GNU_TARGET_NAME) \
-    <a name="line26" id="line26">26</a>                  --host=$(GNU_TARGET_NAME) \
-    <a name="line27" id="line27">27</a>                  --build=$(GNU_HOST_NAME) \
-    <a name="line28" id="line28">28</a>                  --prefix=/usr \
-    <a name="line29" id="line29">29</a>                  --sysconfdir=/etc \
-    <a name="line30" id="line30">30</a>          )
-    <a name="line31" id="line31">31</a>          touch $@
-    <a name="line32" id="line32">32</a>
-    <a name="line33" id="line33">33</a>  $(FOO_DIR)/$(FOO_BINARY): $(FOO_DIR)/.configured
-    <a name="line34" id="line34">34</a>          $(MAKE) CC=$(TARGET_CC) -C $(FOO_DIR)
-    <a name="line35" id="line35">35</a>
-    <a name="line36" id="line36">36</a>  $(TARGET_DIR)/$(FOO_TARGET_BINARY): $(FOO_DIR)/$(FOO_BINARY)
-    <a name="line37" id="line37">37</a>          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) install
-    <a name="line38" id="line38">38</a>          rm -Rf $(TARGET_DIR)/usr/man
-    <a name="line39" id="line39">39</a>
-    <a name="line40" id="line40">40</a>  foo: uclibc ncurses $(TARGET_DIR)/$(FOO_TARGET_BINARY)
-    <a name="line41" id="line41">41</a>
-    <a name="line42" id="line42">42</a>  foo-source: $(DL_DIR)/$(FOO_SOURCE)
-    <a name="line43" id="line43">43</a>
-    <a name="line44" id="line44">44</a>  foo-clean:
-    <a name="line45" id="line45">45</a>          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) uninstall
-    <a name="line46" id="line46">46</a>          -$(MAKE) -C $(FOO_DIR) clean
-    <a name="line47" id="line47">47</a>
-    <a name="line48" id="line48">48</a>  foo-dirclean:
-    <a name="line49" id="line49">49</a>          rm -rf $(FOO_DIR)
-    <a name="line50" id="line50">50</a>
-    <a name="line51" id="line51">51</a> #############################################################
-    <a name="line52" id="line52">52</a> #
-    <a name="line53" id="line53">53</a> # Toplevel Makefile options
-    <a name="line54" id="line54">54</a> #
-    <a name="line55" id="line55">55</a> #############################################################
-    <a name="line56" id="line56">56</a> ifeq ($(BR2_PACKAGE_FOO),y)
-    <a name="line57" id="line57">57</a> TARGETS+=foo
-    <a name="line58" id="line58">58</a> endif
+     <a name="ex2line1" id="ex2line1">1</a>  #############################################################
+     <a name="ex2line2" id="ex2line2">2</a>  #
+     <a name="ex2line3" id="ex2line3">3</a>  # foo
+     <a name="ex2line4" id="ex2line4">4</a>  #
+     <a name="ex2line5" id="ex2line5">5</a>  #############################################################
+     <a name="ex2line6" id="ex2line6">6</a>  FOO_VERSION:=1.0
+     <a name="ex2line7" id="ex2line7">7</a>  FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz
+     <a name="ex2line8" id="ex2line8">8</a>  FOO_SITE:=http://www.foosoftware.org/downloads
+     <a name="ex2line9" id="ex2line9">9</a>  FOO_DIR:=$(BUILD_DIR)/foo-$(FOO_VERSION)
+    <a name="ex2line10" id="ex2line10">10</a>  FOO_BINARY:=foo
+    <a name="ex2line11" id="ex2line11">11</a>  FOO_TARGET_BINARY:=usr/bin/foo
+    <a name="ex2line12" id="ex2line12">12</a>
+    <a name="ex2line13" id="ex2line13">13</a>  $(DL_DIR)/$(FOO_SOURCE):
+    <a name="ex2line14" id="ex2line14">14</a>          $(WGET) -P $(DL_DIR) $(FOO_SITE)/$(FOO_SOURCE)
+    <a name="ex2line15" id="ex2line15">15</a>
+    <a name="ex2line16" id="ex2line16">16</a>  $(FOO_DIR)/.source: $(DL_DIR)/$(FOO_SOURCE)
+    <a name="ex2line17" id="ex2line17">17</a>          $(ZCAT) $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
+    <a name="ex2line18" id="ex2line18">18</a>          touch $@
+    <a name="ex2line19" id="ex2line19">19</a>
+    <a name="ex2line20" id="ex2line20">20</a>  $(FOO_DIR)/.configured: $(FOO_DIR)/.source
+    <a name="ex2line21" id="ex2line21">21</a>          (cd $(FOO_DIR); rm -rf config.cache; \
+    <a name="ex2line22" id="ex2line22">22</a>                  $(TARGET_CONFIGURE_OPTS) \
+    <a name="ex2line23" id="ex2line23">23</a>                  $(TARGET_CONFIGURE_ARGS) \
+    <a name="ex2line24" id="ex2line24">24</a>                  ./configure \
+    <a name="ex2line25" id="ex2line25">25</a>                  --target=$(GNU_TARGET_NAME) \
+    <a name="ex2line26" id="ex2line26">26</a>                  --host=$(GNU_TARGET_NAME) \
+    <a name="ex2line27" id="ex2line27">27</a>                  --build=$(GNU_HOST_NAME) \
+    <a name="ex2line28" id="ex2line28">28</a>                  --prefix=/usr \
+    <a name="ex2line29" id="ex2line29">29</a>                  --sysconfdir=/etc \
+    <a name="ex2line30" id="ex2line30">30</a>          )
+    <a name="ex2line31" id="ex2line31">31</a>          touch $@
+    <a name="ex2line32" id="ex2line32">32</a>
+    <a name="ex2line33" id="ex2line33">33</a>  $(FOO_DIR)/$(FOO_BINARY): $(FOO_DIR)/.configured
+    <a name="ex2line34" id="ex2line34">34</a>          $(MAKE) CC=$(TARGET_CC) -C $(FOO_DIR)
+    <a name="ex2line35" id="ex2line35">35</a>
+    <a name="ex2line36" id="ex2line36">36</a>  $(TARGET_DIR)/$(FOO_TARGET_BINARY): $(FOO_DIR)/$(FOO_BINARY)
+    <a name="ex2line37" id="ex2line37">37</a>          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) install
+    <a name="ex2line38" id="ex2line38">38</a>          rm -Rf $(TARGET_DIR)/usr/man
+    <a name="ex2line39" id="ex2line39">39</a>
+    <a name="ex2line40" id="ex2line40">40</a>  foo: uclibc ncurses $(TARGET_DIR)/$(FOO_TARGET_BINARY)
+    <a name="ex2line41" id="ex2line41">41</a>
+    <a name="ex2line42" id="ex2line42">42</a>  foo-source: $(DL_DIR)/$(FOO_SOURCE)
+    <a name="ex2line43" id="ex2line43">43</a>
+    <a name="ex2line44" id="ex2line44">44</a>  foo-clean:
+    <a name="ex2line45" id="ex2line45">45</a>          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) uninstall
+    <a name="ex2line46" id="ex2line46">46</a>          -$(MAKE) -C $(FOO_DIR) clean
+    <a name="ex2line47" id="ex2line47">47</a>
+    <a name="ex2line48" id="ex2line48">48</a>  foo-dirclean:
+    <a name="ex2line49" id="ex2line49">49</a>          rm -rf $(FOO_DIR)
+    <a name="ex2line50" id="ex2line50">50</a>
+    <a name="ex2line51" id="ex2line51">51</a> #############################################################
+    <a name="ex2line52" id="ex2line52">52</a> #
+    <a name="ex2line53" id="ex2line53">53</a> # Toplevel Makefile options
+    <a name="ex2line54" id="ex2line54">54</a> #
+    <a name="ex2line55" id="ex2line55">55</a> #############################################################
+    <a name="ex2line56" id="ex2line56">56</a> ifeq ($(BR2_PACKAGE_FOO),y)
+    <a name="ex2line57" id="ex2line57">57</a> TARGETS+=foo
+    <a name="ex2line58" id="ex2line58">58</a> endif
 
 </pre>
 
@@ -977,7 +1048,7 @@ endif
     the other <code>*.mk</code> files in the <code>package</code>
     directory. </p>
 
-    <p>At lines <a href="#line6">6-11</a>, a couple of useful variables are 
+    <p>At lines <a href="#ex2line6">6-11</a>, a couple of useful variables are 
     defined :</p>
 
     <ul>
@@ -1007,21 +1078,21 @@ endif
 
     </ul>
 
-    <p>Lines <a href="#line13">13-14</a> defines a target that downloads the 
+    <p>Lines <a href="#ex2line13">13-14</a> defines a target that downloads the 
     tarball from the remote site to the download directory
     (<code>DL_DIR</code>). </p>
 
-    <p>Lines <a href="#line16">16-18</a> defines a target and associated rules 
+    <p>Lines <a href="#ex2line16">16-18</a> defines a target and associated rules 
     that uncompress the downloaded tarball. As you can see, this target
     depends on the tarball file, so that the previous target (line
-    <a href="#line13">13-14</a>) is called before executing the rules of the 
+    <a href="#ex2line13">13-14</a>) is called before executing the rules of the 
     current target. Uncompressing is followed by <i>touching</i> a hidden file
     to mark the software has having been uncompressed. This trick is
     used everywhere in Buildroot <i>Makefile</i> to split steps
     (download, uncompress, configure, compile, install) while still
     having correct dependencies. </p>
 
-    <p>Lines <a href="#line20">20-31</a> defines a target and associated rules 
+    <p>Lines <a href="#ex2line20">20-31</a> defines a target and associated rules 
     that configures the software. It depends on the previous target (the
     hidden <code>.source</code> file) so that we are sure the software has
     been uncompressed. In order to configure it, it basically runs the
@@ -1033,14 +1104,14 @@ endif
     filesystem. Finally it creates a <code>.configured</code> file to
     mark the software as configured. </p>
 
-    <p>Lines <a href="#line33">33-34</a> defines a target and a rule that 
+    <p>Lines <a href="#ex2line33">33-34</a> defines a target and a rule that 
     compiles the software. This target will create the binary file in the
     compilation directory, and depends on the software being already
     configured (hence the reference to the <code>.configured</code>
     file). It basically runs <code>make</code> inside the source
     directory. </p>
 
-    <p>Lines <a href="#line36">36-38</a> defines a target and associated rules 
+    <p>Lines <a href="#ex2line36">36-38</a> defines a target and associated rules 
     that install the software inside the target filesystem. It depends on the
     binary file in the source directory, to make sure the software has
     been compiled. It uses the <code>install</code> target of the
@@ -1051,7 +1122,7 @@ endif
     <code>/usr/man</code> directory inside the target filesystem is
     removed to save space. </p>
 
-    <p>Line <a href="#line40">40</a> defines the main target of the software, 
+    <p>Line <a href="#ex2line40">40</a> defines the main target of the software, 
     the one that will be eventually be used by the top level
     <code>Makefile</code> to download, compile, and then install
     this package. This target should first of all depends on all
@@ -1060,7 +1131,7 @@ endif
     final binary. This last dependency will call all previous
     dependencies in the correct order. </p>
 
-    <p>Line <a href="#line42">42</a> defines a simple target that only 
+    <p>Line <a href="#ex2line42">42</a> defines a simple target that only 
     downloads the code source. This is not used during normal operation of 
     Buildroot, but is needed if you intend to download all required sources at 
     once for later offline build. Note that if you add a new package providing
@@ -1068,25 +1139,25 @@ endif
     users that wish to do offline-builds. Furthermore it eases checking
     if all package-sources are downloadable. </p>
 
-    <p>Lines <a href="#line44">44-46</a> define a simple target to clean the 
+    <p>Lines <a href="#ex2line44">44-46</a> define a simple target to clean the 
     software build by calling the <i>Makefiles</i> with the appropriate option.
     The <code>-clean</code> target should run <code>make clean</code>
     on $(BUILD_DIR)/package-version and MUST uninstall all files of the
     package from $(STAGING_DIR) and from $(TARGET_DIR). </p>
 
-    <p>Lines <a href="#line48">48-49</a> define a simple target to completely 
+    <p>Lines <a href="#ex2line48">48-49</a> define a simple target to completely 
     remove the directory in which the software was uncompressed, configured and
     compiled. The <code>-dirclean</code> target MUST completely rm $(BUILD_DIR)/
     package-version. </p>
 
-    <p>Lines <a href="#line51">51-58</a> adds the target <code>foo</code> to 
+    <p>Lines <a href="#ex2line51">51-58</a> adds the target <code>foo</code> to 
     the list of targets to be compiled by Buildroot by first checking if
     the configuration option for this package has been enabled
     using the configuration tool, and if so then &quot;subscribes&quot;
     this package to be compiled by adding it to the TARGETS
     global variable.  The name added to the TARGETS global
     variable is the name of this package's target, as defined on
-    line <a href="#line40">40</a>, which is used by Buildroot to download, 
+    line <a href="#ex2line40">40</a>, which is used by Buildroot to download, 
     compile, and then install this package. </p>