Update to new upstream release (v0.3.9)

[openwrt.git] / docs / buildroot-documentation.html

diff --git a/docs/buildroot-documentation.html b/docs/buildroot-documentation.html
index 91becd8..48b0572 100644 (file)
--- a/docs/buildroot-documentation.html
+++ b/docs/buildroot-documentation.html
@@ -264,11 +264,11 @@
       is your architecture). This is where the cross compilation toolchain will
       be compiled.</li>
 
       is your architecture). This is where the cross compilation toolchain will
       be compiled.</li>
 

-      <li>Setup the staging directory (<code>build_ARCH/staging_dir/</code> by
+      <li>Setup the staging directory (<code>staging_dir_ARCH/</code> by

       default). This is where the cross-compilation toolchain will be
       installed. If you want to use the same cross-compilation toolchain for
       other purposes, such as compiling third-party applications, you can add
       default). This is where the cross-compilation toolchain will be
       installed. If you want to use the same cross-compilation toolchain for
       other purposes, such as compiling third-party applications, you can add

-      <code>build_ARCH/staging_dir/bin</code> to your PATH, and then use
+      <code>staging_dir_ARCH/bin</code> to your PATH, and then use

       <code>arch-linux-gcc</code> to compile your application. In order to
       setup this staging directory, it first removes it, and then it creates
       various subdirectories and symlinks inside it.</li>
       <code>arch-linux-gcc</code> to compile your application. In order to
       setup this staging directory, it first removes it, and then it creates
       various subdirectories and symlinks inside it.</li>


@@ -292,8 +292,8 @@
     use the toolchain that was generated by the Buildroot.</p>
 
     <p>The toolchain generated by the Buildroot by default is located in
     use the toolchain that was generated by the Buildroot.</p>
 
     <p>The toolchain generated by the Buildroot by default is located in

-    <code>build_ARCH/staging_dir/</code>. The simplest way to use it
-    is to add <code>build_ARCH/staging_dir/bin/</code> to your PATH
+    <code>staging_dir_ARCH</code>. The simplest way to use it
+    is to add <code>staging_dir_ARCH/bin/</code> to your PATH

     environment variable, and then to use
     <code>arch-linux-gcc</code>, <code>arch-linux-objdump</code>,
     <code>arch-linux-ld</code>, etc.</p>
     environment variable, and then to use
     <code>arch-linux-gcc</code>, <code>arch-linux-objdump</code>,
     <code>arch-linux-ld</code>, etc.</p>


@@ -304,7 +304,7 @@
     <code>~/buildroot/</code>) :</p>
 
 <pre>
     <code>~/buildroot/</code>) :</p>
 
 <pre>

-export PATH=$PATH:~/buildroot/build_mipsel/staging_dir/bin/
+export PATH=$PATH:~/buildroot/staging_dir_mipsel/bin/

 </pre>
 
     <p>Then you can simply do :</p>
 </pre>
 
     <p>Then you can simply do :</p>


@@ -324,9 +324,9 @@ mipsel-linux-uclibc-gcc -o foo foo.c
     uClibc toolchain outside of buildroot</h2>
 
     <p>By default, the cross-compilation toolchain is generated inside
     uClibc toolchain outside of buildroot</h2>
 
     <p>By default, the cross-compilation toolchain is generated inside

-    <code>build_ARCH/staging_dir/</code>. But sometimes, it may be useful to
+    <code>staging_dir_ARCH/</code>. But sometimes, it may be useful to

     install it somewhere else, so that it can be used to compile other programs
     install it somewhere else, so that it can be used to compile other programs

-    or by other users. Moving the <code>build_ARCH/staging_dir/</code>
+    or by other users. Moving the <code>staging_dir_ARCH/</code>

     directory elsewhere is <b>not possible</b>, because they are some hardcoded
     paths in the toolchain configuration.</p>
 
     directory elsewhere is <b>not possible</b>, because they are some hardcoded
     paths in the toolchain configuration.</p>
 


@@ -334,7 +334,7 @@ mipsel-linux-uclibc-gcc -o foo foo.c
     you can configure Buildroot to generate it elsewhere using the
     option of the configuration tool : <code>Build options -&gt;
     Toolchain and header file location</code>, which defaults to
     you can configure Buildroot to generate it elsewhere using the
     option of the configuration tool : <code>Build options -&gt;
     Toolchain and header file location</code>, which defaults to

-    <code>$(BUILD_DIR)/staging_dir/</code>.</p>
+    <code>staging_dir_ARCH/</code>.</p>

 
     <h2><a name="downloaded_packages"
     id="downloaded_packages"></a>Location of downloaded packages</h2>
 
     <h2><a name="downloaded_packages"
     id="downloaded_packages"></a>Location of downloaded packages</h2>


@@ -427,56 +427,57 @@ foo-compile: bar-compile
    afterwards.</p>
 
 <pre>
    afterwards.</p>
 
 <pre>

-     1  #############################################################
-     2  # foo
-     3  #############################################################
-     4  PKG_NAME:=foo
-     5  PKG_VERSION:=1.0
-     6  PKG_RELEASE:=1
-     7  PKG_SOURCE:=$(PKG_NAME)-$(PKG_VERSION).tar.gz
-     8  PKG_SITE:=http://www.foosoftware.org/downloads
-     9  PKG_DIR:=$(BUILD_DIR)/$(PKG_NAME)-$(PKG_VERSION)
-    10  PKG_IPK:=$(PACKAGE_DIR)/$(PKG_NAME)_$(PKG_VERSION)-$(PKG_RELEASE)_$(ARCH).ipk
-    11  PKG_IPK_DIR:=$(PKG_DIR)/ipkg
-    12
-    13  $(DL_DIR)/$(PKG_SOURCE):
-    14          $(WGET) -P $(DL_DIR) $(PKG_SITE)/$(PKG_SOURCE)
-    15
-    16  $(PKG_DIR)/.source: $(DL_DIR)/$(PKG_SOURCE)
-    17          zcat $(DL_DIR)/$(PKG_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
-    18          touch $(PKG_DIR)/.source
-    19
-    20  $(PKG_DIR)/.configured: $(PKG_DIR)/.source
-    21          (cd $(PKG_DIR); \
-    22                  $(TARGET_CONFIGURE_OPTS) \
-    23                  CFLAGS="$(TARGET_CFLAGS)" \
-    24                  ./configure \
-    25                  --target=$(GNU_TARGET_NAME) \
-    26                  --host=$(GNU_TARGET_NAME) \
-    27                  --build=$(GNU_HOST_NAME) \
-    28                  --prefix=/usr \
-    29                  --sysconfdir=/etc \
-    30          );
-    31          touch $(PKG_DIR)/.configured;
-    32
-    33  $(PKG_DIR)/foo $(PKG_DIR)/.configured
-    34          $(MAKE) CC=$(TARGET_CC) -C $(PKG_DIR)
-    35
-    36  $(PKG_IPK): $(PKG_DIR)/$(PKG_BINARY)
-    37         $(SCRIPT_DIR)/make-ipkg-dir.sh $(PKG_IPK_DIR) $(PKG_NAME).control $(PKG_VERSION)-$(PKG_RELEASE) $(ARCH)
-    38          $(MAKE) prefix=$(PKG_IPK_DIR)/usr -C $(PKG_DIR) install
-    39          rm -Rf $(PKG_IPK_DIR)/usr/man
-    40         $(IPKG_BUILD) $(PKG_IPK_DIR) $(PACKAGE_DIR)
-    41
-    42  $(IPKG_STATE_DIR)/info/$(PKG_NAME).list: $(PKG_IPK)  
-    43         $(IPKG) install $(PKG_IPK) 
-    44  
-    45  prepare: $(PKG_DIR)/.source
-    46  compile: $(PKG_IPK)
-    47  install: $(IPKG_STATE_DIR)/info/$(PKG_NAME).list
-    48  clean:
-    49         rm -rf $(PKG_DIR)
-    50         rm -f $(PKG_IPK)
+     1  # $Id$
+     2  include $(TOPDIR)/rules.mk
+     3  PKG_NAME:=foo
+     4  PKG_VERSION:=1.0
+     5  PKG_RELEASE:=1
+     6  PKG_MD5SUM:=4584f226523776a3cdd2fb6f8212ba8d
+     7
+     8  PKG_SOURCE:=$(PKG_NAME)-$(PKG_VERSION).tar.gz
+     9  PKG_SOURCE_URL:=http://www.foosoftware.org/downloads
+    10  PKG_DIR:=$(BUILD_DIR)/$(PKG_NAME)-$(PKG_VERSION)
+    11  PKG_IPK:=$(PACKAGE_DIR)/$(PKG_NAME)_$(PKG_VERSION)-$(PKG_RELEASE)_$(ARCH).ipk
+    12  PKG_IPK_DIR:=$(PKG_DIR)/ipkg
+    13
+    14  $(DL_DIR)/$(PKG_SOURCE):
+    15          $(SCRIPT_DIR)/download.pl $(DL_DIR) $(PKG_SOURCE) $(PKG_MD5SUM) $(PKG_SOURCE_URL)
+    16
+    17  $(PKG_DIR)/.source: $(DL_DIR)/$(PKG_SOURCE)
+    18          zcat $(DL_DIR)/$(PKG_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
+    19          touch $(PKG_DIR)/.source
+    20
+    21  $(PKG_DIR)/.configured: $(PKG_DIR)/.source
+    22          (cd $(PKG_DIR); \
+    23                  $(TARGET_CONFIGURE_OPTS) \
+    24                  CFLAGS="$(TARGET_CFLAGS)" \
+    25                  ./configure \
+    26                  --target=$(GNU_TARGET_NAME) \
+    27                  --host=$(GNU_TARGET_NAME) \
+    28                  --build=$(GNU_HOST_NAME) \
+    29                  --prefix=/usr \
+    30                  --sysconfdir=/etc \
+    31          );
+    32          touch $(PKG_DIR)/.configured;
+    33
+    34  $(PKG_DIR)/$(PKG_NAME): $(PKG_DIR)/.configured
+    35          $(MAKE) CC=$(TARGET_CC) -C $(PKG_DIR)
+    36
+    37  $(PKG_IPK): $(PKG_DIR)/$(PKG_NAME)
+    38         $(SCRIPT_DIR)/make-ipkg-dir.sh $(PKG_IPK_DIR) $(PKG_NAME).control $(PKG_VERSION)-$(PKG_RELEASE) $(ARCH)
+    39          $(MAKE) prefix=$(PKG_IPK_DIR)/usr -C $(PKG_DIR) install
+    40          rm -Rf $(PKG_IPK_DIR)/usr/man
+    41         $(IPKG_BUILD) $(PKG_IPK_DIR) $(PACKAGE_DIR)
+    42
+    43  $(IPKG_STATE_DIR)/info/$(PKG_NAME).list: $(PKG_IPK)  
+    44         $(IPKG) install $(PKG_IPK) 
+    45  
+    46  prepare: $(PKG_DIR)/.source
+    47  compile: $(PKG_IPK)
+    48  install: $(IPKG_STATE_DIR)/info/$(PKG_NAME).list
+    49  clean:
+    50         rm -rf $(PKG_DIR)
+    51         rm -f $(PKG_IPK)

 </pre>
 
     <p>First of all, this <i>Makefile</i> example works for a single
 </pre>
 
     <p>First of all, this <i>Makefile</i> example works for a single


@@ -485,7 +486,7 @@ foo-compile: bar-compile
     the other <code>Makefile</code> files in the <code>package</code>
     directory.</p>
 
     the other <code>Makefile</code> files in the <code>package</code>
     directory.</p>
 

-    <p>At lines 4-11, a couple of useful variables are defined :</p>
+    <p>At lines 3-12, a couple of useful variables are defined :</p>

 
     <ul>
      <li><code>PKG_NAME</code> : The package name, e.g. <i>foo</i>.</li>
 
     <ul>
      <li><code>PKG_NAME</code> : The package name, e.g. <i>foo</i>.</li>


@@ -496,12 +497,14 @@ foo-compile: bar-compile
      <li><code>PKG_RELEASE</code> : The release number that will be
      appended to the version number of your <i>ipkg</i> package.
 
      <li><code>PKG_RELEASE</code> : The release number that will be
      appended to the version number of your <i>ipkg</i> package.
 

+     <li><code>PKG_MD5SUM</code> : The md5sum of the software archive.
+

      <li><code>PKG_SOURCE</code> : The name of the tarball of
      your package on the download website of FTP site. As you can see
      <code>PKG_NAME</code> and <code>PKG_VERSION</code> are used.</li>
 
      <li><code>PKG_SOURCE</code> : The name of the tarball of
      your package on the download website of FTP site. As you can see
      <code>PKG_NAME</code> and <code>PKG_VERSION</code> are used.</li>
 

-     <li><code>PKG_SITE</code> : The HTTP or FTP site from which
-     the archive is downloaded. It must include the complete
+     <li><code>PKG_SOURCE_URL</code> : Space separated list of the HTTP
+     or FTP sites from which the archive is downloaded. It must include the complete

      path to the directory where <code>FOO_SOURCE</code> can be
      found.</li>
 
      path to the directory where <code>FOO_SOURCE</code> can be
      found.</li>
 


@@ -514,21 +517,21 @@ foo-compile: bar-compile
 
     </ul>
 
 
     </ul>
 

-    <p>Lines 13-14 defines a target that downloads the tarball from
+    <p>Lines 14-15 defines a target that downloads the tarball from

     the remote site to the download directory
     (<code>DL_DIR</code>).</p>
 
     the remote site to the download directory
     (<code>DL_DIR</code>).</p>
 

-    <p>Lines 16-18 defines a target and associated rules that
+    <p>Lines 17-19 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
     uncompress the downloaded tarball. As you can see, this target
     depends on the tarball file, so that the previous target (line

-    13-14) is called before executing the rules of the current
+    14-15) 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>
 
     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 20-31 defines a target and associated rules that
+    <p>Lines 21-32 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
     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


@@ -540,14 +543,14 @@ foo-compile: bar-compile
     filesystem. Finally it creates a <code>.configured</code> file to
     mark the software as configured.</p>
 
     filesystem. Finally it creates a <code>.configured</code> file to
     mark the software as configured.</p>
 

-    <p>Lines 33-34 defines a target and a rule that compiles the
+    <p>Lines 34-35 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>
 
     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 36-40 defines a target and associated rules that create
+    <p>Lines 37-41 defines a target and associated rules that create

     the <i>ipkg</i> package which can optionally be embedded into
     the resulting firmware image. It depends on the binary file in 
     the source directory, to make sure the software has been compiled.
     the <i>ipkg</i> package which can optionally be embedded into
     the resulting firmware image. It depends on the binary file in 
     the source directory, to make sure the software has been compiled.


@@ -563,10 +566,10 @@ foo-compile: bar-compile
     removed to save space.
     Finally <code>IPKG_BUILD</code> is called to create the package.</p>
 
     removed to save space.
     Finally <code>IPKG_BUILD</code> is called to create the package.</p>
 

-    <p>Line 42 and 43 define the installation target of your package,
+    <p>Line 43 and 44 define the installation target of your package,

     which will embed the software into the target filesystem.</p>
 
     which will embed the software into the target filesystem.</p>
 

-    <p>Lines 45-50 define the main targets that the Makefile in the
+    <p>Lines 46-51 define the main targets that the Makefile in the

     <code>package</code> dir calls.
     <ul>
       <li><code>prepare</code> : Download and unpack the source</li>
     <code>package</code> dir calls.
     <ul>
       <li><code>prepare</code> : Download and unpack the source</li>