diff options
| author | Thomas Petazzoni <thomas.petazzoni@free-electrons.com> | 2008-12-15 22:35:09 +0000 |
|---|---|---|
| committer | Thomas Petazzoni <thomas.petazzoni@free-electrons.com> | 2008-12-15 22:35:09 +0000 |
| commit | f3e8be761ab5ba3dae7a7ba0d9b62a02d8043314 (patch) | |
| tree | 48b24e3088ca99fc5f0bfc358ce4106e7b07ce95 /docs | |
| parent | 6844445ef73c62bf40b9cedc119526371117a0e2 (diff) | |
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>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/buildroot.html | 223 |
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<TAB> </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 :</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 :</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 :</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 "subscribes" 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> |