From f3e8be761ab5ba3dae7a7ba0d9b62a02d8043314 Mon Sep 17 00:00:00 2001 From: Thomas Petazzoni Date: Mon, 15 Dec 2008 22:35:09 +0000 Subject: [PATCH] Documentation fixes and updates The biggest update is to document the Makefile.autotools.in way of writing .mk files. Signed-off-by: Thomas Petazzoni --- docs/buildroot.html | 223 +++++++++++++++++++++++++++++--------------- 1 file changed, 147 insertions(+), 76 deletions(-) diff --git a/docs/buildroot.html b/docs/buildroot.html index fbe69fb961..026791fccf 100644 --- a/docs/buildroot.html +++ b/docs/buildroot.html @@ -117,7 +117,7 @@

Obtaining Buildroot

Buildroot is available as daily SVN snapshots or directly using - SVN.

+ SVN. As of today, no stable releases of Buildroot are made.

The latest snapshot is always available at http://buildroot.uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2, @@ -444,7 +444,7 @@ $ make me<TAB>

The main Makefile do the job through the following steps (once the - configuration is done):

+ configuration is done) :

  1. Create the download directory (dl/ by default). This is @@ -890,7 +890,7 @@ config BR2_PACKAGE_FOO things in your software.

    Finally you have to add your new foo/Config.in to package/Config.in. The files included there are - sorted alphabetically per category and are NOT + sorted alphabetically per category and are NOT supposed to contain anything but the bare name of the package.

     if !BR2_PACKAGE_BUSYBOX_HIDE_OTHERS
@@ -906,68 +906,139 @@ endif
    
    Finally, here's the hardest part. Create a file named
    foo.mk. It will contain the Makefile rules that
    are in charge of downloading, configuring, compiling and installing
-   the software. Below is an example that we will comment
-   afterwards. 
    
+   the software.
    
+
+   
    Two types of Makefiles can be written :
    
+
+   
      
+    
    • Makefile for autotools-based (autoconf, automake, etc.)
+    softwares, are very easy to write thanks to the infrastructure
+    available in package/Makefile.autotools.in.
      • 
+    
    • Makefile for other types of packages are a little bit more
+    complex to write.
      • 
+   
    
+
+   
    First, let's see how to write a Makefile for an
+   autotools-based package, with an example :
    
+
+
    +     1  #############################################################
+     2  #
+     3  # foo
+     4  #
+     5  #############################################################
+     6  FOO_VERSION:=1.0
+     7  FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz
+     8  FOO_SITE:=http://www.foosoftware.org/downloads
+     9  FOO_INSTALL_STAGING = YES
+     10  FOO_INSTALL_TARGET = YES
+     11  FOO_CONF_OPT =  --enable-shared
+     12  FOO_DEPENDENCIES = libglib2 pkgconfig
+     13  $(eval $(call AUTOTARGETS,package,foo))
+
    
+
+    
    On line 6, we declare the version of
+    the package. On line 7 and 8, 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.
    
+
+    
    On line 9, we tell Buildroot to install
+    the application to the staging directory. The staging directory,
+    located in build_ARCH/staging_dir/ is the directory
+    where all the packages are installed, including their
+    documentation, etc. By default, packages are installed in this
+    location using the make install command.
    
+
+    
    On line 10, 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 make
+    install-strip command.
    
+
+    
    On line 11, we tell Buildroot to pass
+    a custom configure option, that will be passed to the
+    ./configure script before configuring and building
+    the package.
    
+
+    
    On line 12, we declare our
+    dependencies, so that they are built before the build process of
+    our package starts.
    
+
+    
    Finally, on line line 13, we invoke
+    the package/Makefile.autotools.in magic to get things
+    working.
    
+
+    
    For more details about the available variables and options, see
+    the comment at the top of
+    package/Makefile.autotools.in and the examples in all
+    the available packages.
    
+
+    
    The second solution, suitable for every type of package, looks
+    like this :
    
+
 
 
    -     1  #############################################################
-     2  #
-     3  # foo
-     4  #
-     5  #############################################################
-     6  FOO_VERSION:=1.0
-     7  FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz
-     8  FOO_SITE:=http://www.foosoftware.org/downloads
-     9  FOO_DIR:=$(BUILD_DIR)/foo-$(FOO_VERSION)
-    10  FOO_BINARY:=foo
-    11  FOO_TARGET_BINARY:=usr/bin/foo
-    12
-    13  $(DL_DIR)/$(FOO_SOURCE):
-    14          $(WGET) -P $(DL_DIR) $(FOO_SITE)/$(FOO_SOURCE)
-    15
-    16  $(FOO_DIR)/.source: $(DL_DIR)/$(FOO_SOURCE)
-    17          $(ZCAT) $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
-    18          touch $@
-    19
-    20  $(FOO_DIR)/.configured: $(FOO_DIR)/.source
-    21          (cd $(FOO_DIR); rm -rf config.cache; \
-    22                  $(TARGET_CONFIGURE_OPTS) \
-    23                  $(TARGET_CONFIGURE_ARGS) \
-    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 $@
-    32
-    33  $(FOO_DIR)/$(FOO_BINARY): $(FOO_DIR)/.configured
-    34          $(MAKE) CC=$(TARGET_CC) -C $(FOO_DIR)
-    35
-    36  $(TARGET_DIR)/$(FOO_TARGET_BINARY): $(FOO_DIR)/$(FOO_BINARY)
-    37          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) install
-    38          rm -Rf $(TARGET_DIR)/usr/man
-    39
-    40  foo: uclibc ncurses $(TARGET_DIR)/$(FOO_TARGET_BINARY)
-    41
-    42  foo-source: $(DL_DIR)/$(FOO_SOURCE)
-    43
-    44  foo-clean:
-    45          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) uninstall
-    46          -$(MAKE) -C $(FOO_DIR) clean
-    47
-    48  foo-dirclean:
-    49          rm -rf $(FOO_DIR)
-    50
-    51 #############################################################
-    52 #
-    53 # Toplevel Makefile options
-    54 #
-    55 #############################################################
-    56 ifeq ($(BR2_PACKAGE_FOO),y)
-    57 TARGETS+=foo
-    58 endif
+     1  #############################################################
+     2  #
+     3  # foo
+     4  #
+     5  #############################################################
+     6  FOO_VERSION:=1.0
+     7  FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz
+     8  FOO_SITE:=http://www.foosoftware.org/downloads
+     9  FOO_DIR:=$(BUILD_DIR)/foo-$(FOO_VERSION)
+    10  FOO_BINARY:=foo
+    11  FOO_TARGET_BINARY:=usr/bin/foo
+    12
+    13  $(DL_DIR)/$(FOO_SOURCE):
+    14          $(WGET) -P $(DL_DIR) $(FOO_SITE)/$(FOO_SOURCE)
+    15
+    16  $(FOO_DIR)/.source: $(DL_DIR)/$(FOO_SOURCE)
+    17          $(ZCAT) $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
+    18          touch $@
+    19
+    20  $(FOO_DIR)/.configured: $(FOO_DIR)/.source
+    21          (cd $(FOO_DIR); rm -rf config.cache; \
+    22                  $(TARGET_CONFIGURE_OPTS) \
+    23                  $(TARGET_CONFIGURE_ARGS) \
+    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 $@
+    32
+    33  $(FOO_DIR)/$(FOO_BINARY): $(FOO_DIR)/.configured
+    34          $(MAKE) CC=$(TARGET_CC) -C $(FOO_DIR)
+    35
+    36  $(TARGET_DIR)/$(FOO_TARGET_BINARY): $(FOO_DIR)/$(FOO_BINARY)
+    37          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) install
+    38          rm -Rf $(TARGET_DIR)/usr/man
+    39
+    40  foo: uclibc ncurses $(TARGET_DIR)/$(FOO_TARGET_BINARY)
+    41
+    42  foo-source: $(DL_DIR)/$(FOO_SOURCE)
+    43
+    44  foo-clean:
+    45          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) uninstall
+    46          -$(MAKE) -C $(FOO_DIR) clean
+    47
+    48  foo-dirclean:
+    49          rm -rf $(FOO_DIR)
+    50
+    51 #############################################################
+    52 #
+    53 # Toplevel Makefile options
+    54 #
+    55 #############################################################
+    56 ifeq ($(BR2_PACKAGE_FOO),y)
+    57 TARGETS+=foo
+    58 endif
 
 
    
 
@@ -977,7 +1048,7 @@ endif
     the other *.mk files in the package
     directory. 
    
 
-    
    At lines 6-11, a couple of useful variables are 
+    
    At lines 6-11, a couple of useful variables are 
     defined :
    
 
     
      
@@ -1007,21 +1078,21 @@ endif
 
     
    
 
-    
    Lines 13-14 defines a target that downloads the 
+    
    Lines 13-14 defines a target that downloads the 
     tarball from the remote site to the download directory
     (DL_DIR). 
    
 
-    
    Lines 16-18 defines a target and associated rules 
+    
    Lines 16-18 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
-    13-14) is called before executing the rules of the 
+    13-14) is called before executing the rules of the 
     current target. Uncompressing is followed by touching a hidden file
     to mark the software has having been uncompressed. This trick is
     used everywhere in Buildroot Makefile to split steps
     (download, uncompress, configure, compile, install) while still
     having correct dependencies. 
    
 
-    
    Lines 20-31 defines a target and associated rules 
+    
    Lines 20-31 defines a target and associated rules 
     that configures the software. It depends on the previous target (the
     hidden .source 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 .configured file to
     mark the software as configured. 
    
 
-    
    Lines 33-34 defines a target and a rule that 
+    
    Lines 33-34 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 .configured
     file). It basically runs make inside the source
     directory. 
    
 
-    
    Lines 36-38 defines a target and associated rules 
+    
    Lines 36-38 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 install target of the
@@ -1051,7 +1122,7 @@ endif
     /usr/man directory inside the target filesystem is
     removed to save space. 
    
 
-    
    Line 40 defines the main target of the software, 
+    
    Line 40 defines the main target of the software, 
     the one that will be eventually be used by the top level
     Makefile 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. 
    
 
-    
    Line 42 defines a simple target that only 
+    
    Line 42 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. 
    
 
-    
    Lines 44-46 define a simple target to clean the 
+    
    Lines 44-46 define a simple target to clean the 
     software build by calling the Makefiles with the appropriate option.
     The -clean target should run make clean
     on $(BUILD_DIR)/package-version and MUST uninstall all files of the
     package from $(STAGING_DIR) and from $(TARGET_DIR). 
    
 
-    
    Lines 48-49 define a simple target to completely 
+    
    Lines 48-49 define a simple target to completely 
     remove the directory in which the software was uncompressed, configured and
     compiled. The -dirclean target MUST completely rm $(BUILD_DIR)/
     package-version. 
    
 
-    
    Lines 51-58 adds the target foo to 
+    
    Lines 51-58 adds the target foo 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 40, which is used by Buildroot to download, 
+    line 40, which is used by Buildroot to download, 
     compile, and then install this package. 
    
 
 
-- 
2.30.2