From 16c1549fd22af9a5fedd98d173a4c229b909af4c Mon Sep 17 00:00:00 2001 From: Thomas Petazzoni Date: Fri, 27 Nov 2009 22:19:17 +0100 Subject: documentation: update about new package infrastructures Document the new generic package infrastructure, and how target/host packages are handled, both for the generic package infrastructure and the autotools package infrastructure. This documentation replaces the documentation that used to be present at the top of Makefile.autotools.in. Both tutorial and reference documentation are provided. Signed-off-by: Thomas Petazzoni --- docs/buildroot.html | 692 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 603 insertions(+), 89 deletions(-) diff --git a/docs/buildroot.html b/docs/buildroot.html index 0d254b619..dfa69e0dd 100644 --- a/docs/buildroot.html +++ b/docs/buildroot.html @@ -36,10 +36,8 @@
  • Using the uClibc toolchain outside Buildroot
  • Use an external toolchain
    • -
  • Location of downloaded packages -
    • -
  • Extending Buildroot with more - Software
    • +
  • Location of downloaded packages
    • +
  • Adding new packages to Buildroot
  • Creating your own board support
  • Resources
    • @@ -221,7 +219,9 @@ directory is not intended to be the root filesystem for the target: it contains a lot of development files, unstripped binaries and libraries that make it far too big for an embedded - system. + system. These development files are used to compile libraries + and applications for the target that depend on other + libraries.
  • target/ which contains almost the root filesystem for the target: everything needed is present except @@ -474,9 +474,9 @@ $ export BUILDROOT_COPYTO=/tftpboot uniformely named and handled by the different packages, so some understanding of the particular package is needed.

    -

    For packages relying on the autotools Buildroot - infrastructure (see this section for - details), the following stamp files are relevent:

    +

    For packages relying on Buildroot packages infrastructures (see + this section for details), the + following stamp files are relevent:

      @@ -493,7 +493,8 @@ $ export BUILDROOT_COPYTO=/tftpboot

      For other packages, an analysis of the specific package.mk file is needed. For example, the zlib Makefile - looks like:

      + used to look like this (before it was converted to the generic + package infrastructure):

       $(ZLIB_DIR)/.configured: $(ZLIB_DIR)/.patched
@@ -512,6 +513,10 @@ $(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
     you want to trigger only the recompilation, you need to remove
     output/build/zlib-version/libz.a.
      
 
+    
      Note that most packages, if not all, will progressively be
+    ported over the generic or the autotools infrastructure, making it
+    much easier to rebuild individual packages.
      
+
     
      How Buildroot
     works
      
 
@@ -522,7 +527,7 @@ $(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
     uClibc). 
      
 
     
      There is basically one Makefile per software package, and they are named with
-    the .mk extension. Makefiles are split into four
+    the .mk extension. Makefiles are split into three main
     sections:
      
 
     
        
@@ -779,124 +784,633 @@ It allows generating toolchains based on uClibc, glibc
 and eglibc for a wide range of architectures and has good
 community support.
        
 
-    
        Extending Buildroot with
-    more software
        
+    
        Adding new
+    packages to Buildroot
        
 
-    
        This section will only consider the case in which you want to
-    add user-space software. 
        
+    
        This section covers how new packages (userspace libraries or
+    applications) can be integrated into Buildroot. It also allows to
+    understand how existing packages are integrated, which is needed
+    to fix issues or tune their configuration.
        
 
-    
        Package directory
        
+    
+
+    
        Package directory
        
 
     
        First of all, create a directory under the package
     directory for your software, for example foo. 
        
 
-    
        Config.in file
        
+    
        Some packages have been grouped by topic in a sub-directory:
+    multimedia, java,
+    databases, editors, x11r7,
+    games. If your package fits in one of these
+    categories, then create your package directory in these.
        
+
+    
        Config.in file
        
 
     
        Then, create a file named Config.in. This file
     will contain the option descriptions related to our
-    foo software that will be used and displayed in the
-    configuration tool. It should basically contain:
        
+    libfoo software that will be used and displayed in the
+    configuration tool. It should basically contain :
        
 
 
        -config BR2_PACKAGE_FOO
-        bool "foo"
+config BR2_PACKAGE_LIBFOO
+        bool "libfoo"
         help
-	  This is a comment that explains what foo is.
+	  This is a comment that explains what libfoo is.
 
-	  http://foosoftware.org/foo/
+	  http://foosoftware.org/libfoo/
 
        
 
     
        Of course, you can add other options to configure particular
-    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
-    supposed to contain anything but the bare name of the package.
        
+    things in your software. You can look at examples in other
+    packages. The syntax of the Config.in file is the same as the one
+    for the kernel Kconfig file. The documentation for this syntax is
+    available at http://lxr.free-electrons.com/source/Documentation/kbuild/kconfig-language.txt
        
+
+    
        Finally you have to add your new libfoo/Config.in to
+    package/Config.in (or in a category subdirectory if
+    you decided to put your package in one of the existing
+    categories). The files included there are sorted
+    alphabetically per category and are NOT supposed to
+    contain anything but the bare name of the package.
        
 
        -source "package/procps/Config.in"
+source "package/libfoo/Config.in"
 
        
-   
        Note:
        
-   Generally all packages should live directly in the
-   package directory to make it easier to find them.
-   
        
-   
        The real Makefile
        
+
+   
        The .mk file
        
 
    
        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.
        
+   foo.mk. It describes how the package should be
+   downloaded, configured, built, installed, etc.
        
 
-   
        Two types of Makefiles can be written :
        
+   
        Depending on the package type, the .mk file must be
+   written in a different way, using different infrastructures:
        
 
    
          
-    
        • Makefiles for autotools-based (autoconf, automake, etc.)
-    software are very easy to write thanks to the infrastructure
-    available in package/Makefile.autotools.in.
          • 
-    
        • Makefiles for other types of packages are a little bit more
-    complex to write.
          • 
+
+     
        • Makefiles for generic packages (not using autotools), based
+     on an infrastructure similar to the one used for autotools-based
+     packages, but which requires a little more work from the
+     developer : specify what should be done at for the configuration,
+     compilation, installation and cleanup of the package. This
+     infrastructure must be used for all packages that do not use the
+     autotools as their build system. In the future, other specialized
+     infrastructures might be written for other build systems.
          We
+     cover them through a tutorial and a reference.
          • 
+
+     
        • Makefiles for autotools-based (autoconf, automake, etc.)
+     softwares. We provide a dedicated infrastructure for such
+     packages, since autotools is a very common build system. This
+     infrastructure must be used for new packages that rely on
+     the autotools as their build system.
          We cover them through a
+     tutorial and a reference.
          • 
+
+     
        • Manual Makefiles. These are currently obsolete and no new
+     manual Makefiles should be added. However, since there are still
+     many of them in the tree and because the , we keep them documented in a tutorial.
          • 
+
    
        
 
-   
        First, let's see how to write a Makefile for an
-   autotools-based package, with an example :
        
+   
        Makefile for generic packages :
+   tutorial
        
+
+   
        01: #############################################################
+02: #
+03: # libfoo
+04: #
+05: #############################################################
+06: LIBFOO_VERSION:=1.0
+07: LIBFOO_SOURCE:=libfoo-$(LIBFOO_VERSION).tar.gz
+08: LIBFOO_SITE:=http://www.foosoftware.org/download
+09: LIBFOO_INSTALL_STAGING=YES
+10: LIBFOO_DEPENDENCIES = host-libaaa libbbb
+11: 
+12: define LIBFOO_BUILD_CMDS
+13:         $(MAKE) CC=$(TARGET_CC) LD=$(TARGET_LD) -C $(@D) all
+14: endef
+15: 
+16: define LIBFOO_INSTALL_STAGING_CMDS
+17:         $(INSTALL) -D $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
+18:         $(INSTALL) -D $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
+19:         cp -dpf $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
+20: endef
+21: 
+22: define LIBFOO_INSTALL_TARGET_CMDS
+23:         cp -dpf $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
+24:         -$(STRIPCMP) $(STRIP_STRIP_UNNEEDED) $(TARGET_DIR)/isr/lib/libfoo.so*
+25: endef
+26: 
+27: $(eval $(call GENTARGETS,package,libfoo))
        
+
+   
        The Makefile begins on line 6 to 8 by metadata informations: the
+   version of the package (LIBFOO_VERSION), the name of
+   the tarball containing the package (LIBFOO_SOURCE) and
+   the Internet location at which the tarball can be downloaded
+   (LIBFOO_SITE). All variables must start with the same
+   prefix, LIBFOO_ in this case. This prefix is always
+   the uppercased version of the package name (see below to understand
+   where the package name is defined).
        
+
+   
        On line 9, we specify that this package wants to install
+   something to the staging space. This is often needed for libraries
+   since they must install header files and other development files in
+   the staging space. This will ensure that the commands listed in the
+   LIBFOO_INSTALL_STAGING_CMDS variable will be
+   executed.
        
+
+   
        On line 10, we specify the list of dependencies this package
+   relies on. These dependencies are listed in terms of lower-case
+   package names, which can be packages for the target (without the
+   host- prefix) or packages for the host (with the
+   host-) prefix). Buildroot will ensure that all these
+   packages are built and installed before the current package
+   starts its configuration.
        
+
+   
        The rest of the Makefile defines what should be done at the
+   different steps of the package configuration, compilation and
+   installation. LIBFOO_BUILD_CMDS tells what steps
+   should be performed to build the
+   package. LIBFOO_INSTALL_STAGING_CMDS tells what steps
+   should be performed to install the package in the staging
+   space. LIBFOO_INSTALL_TARGET_CMDS tells what steps
+   should be performed to install the package in the target space.
        
+
+   
        All these steps rely on the $(@D) variable, which
+   contains the directory where the source code of the package has
+   been extracted.
        
+
+   
        Finally, on line 27, we call the GENTARGETS which
+   generates, according to the variables defined previously, all the
+   Makefile code necessary to make your package working.
        
+
+   
        Makefile for generic packages :
+   reference
        
+
+   
        The GENTARGETS macro takes three arguments:
        
+
+   
          
+
+     
        • The first argument is the package directory prefix. If your
+     package is in package/libfoo, then the directory
+     prefix is package. If your package is in
+     package/editors/foo, then the directory prefix must
+     be package/editors.
          • 
+
+     
        • The second argument is the lower-cased package name. It must
+     match the prefix of the variables in the .mk file
+     and must match the configuration option name in the
+     Config.in file. For example, if the package name is
+     libfoo, so the variables in the .mk
+     must start with LIBFOO_ and the configuration option
+     in the Config.in file must be
+     BR2_PACKAGE_LIBFOO.
          • 
+
+     
        • The third argument is optional. It can be used to tell if the
+     package if a target package (cross-compiled for the target) or a
+     host package (natively compiled for the host). If unspecified, it
+     is assumed that it is a target package. See below for
+     details.
          • 
+
+   
        
+
+   
        For a given package, in a single .mk file, it is
+   possible to call GENTARGETS twice, once to create the rules to
+   generate a target package and once to create the rules to generate
+   a host package:
        
+
+
        +$(eval $(call GENTARGETS,package,libfoo))
+$(eval $(call GENTARGETS,package,libfoo,host))
+
        
+
+   
        This might be useful if the compilation of the target package
+   requires some tools to be installed on the host. If the package
+   name is libfoo, then the name of the package for the
+   target is also libfoo, while the name of the package
+   for the host is host-libfoo. These names should be
+   used in the DEPENDENCIES variables of other packages if they depend
+   on libfoo or host-libfoo.
        
+
+   
        The call to the GENTARGETS macro must be at
+   the end of the .mk file, after all variable
+   definitions.
        
+
+   
        For the target package, the GENTARGETS uses the
+   variables defined by the .mk file and prefixed by the uppercased
+   package name: LIBFOO_*. For target package, it uses
+   the HOST_LIBFOO_*. For some variables, if the
+   HOST_LIBFOO_ prefixed variable doesn't exist, the
+   package infrastructure uses the corresponding variable prefixed by
+   LIBFOO_. This is done for variables that are likely to
+   have the same value for both the target and host packages. See
+   below for details.
        
+
+   
        The list of variables that can be set in a .mk file
+   to give metadata informations is (assuming the package name is
+   libfoo) :
        
+
+   
          
+
+     
        • LIBFOO_VERSION, mandatory, must contain the
+     version of the package. Note that if
+     HOST_LIBFOO_VERSION doesn't exist, it is assumed to
+     be the same as LIBFOO_VERSION.
          Example:
+     LIBFOO_VERSION=0.1.2
          • 
+
+     
        • LIBFOO_SOURCE may contain the name of the
+     tarball of the package. If HOST_LIBFOO_SOURCE is not
+     specified, it defaults to LIBFOO_VERSION. If none
+     are specified, then the value is assumed to be
+     packagename-$(LIBFOO_VERSION).tar.gz.
          Example:
+     LIBFOO_SOURCE =
+     foobar-$(LIBFOO_VERSION).tar.bz2
          • 
+
+     
        • LIBFOO_PATCH may contain the name of a patch,
+     that will be downloaded from the same location as the tarball
+     indicated in LIBFOO_SOURCE. If
+     HOST_LIBFOO_PATCH is not specified, it defaults to
+     LIBFOO_PATCH. Also note that another mechanism is
+     available to patch a package: all files of the form
+     packagename-packageversion-description.patch present
+     in the package directory inside Buildroot will be applied to the
+     package after extraction.
          • 
+
+     
        • LIBFOO_SITE may contain the Internet location of
+     the tarball of the package. If HOST_LIBFOO_SITE is
+     not specified, it defaults to LIBFOO_SITE. If none
+     are specified, then the location is assumed to be
+     http://$$(BR2_SOURCEFORGE_MIRROR).dl.sourceforge.net/sourceforge/packagename.
          Example:
+     LIBFOO_SITE=http://www.foosoftware.org/libfoo.
          • 
+
+     
        • LIBFOO_DEPENDENCIES lists the dependencies (in
+     terms of package name) that are required for the current target
+     package to compile. These dependencies are guaranteed to be
+     compiled and installed before the configuration of the current
+     package starts. In a similar way,
+     HOST_LIBFOO_DEPENDENCIES lists the dependency for
+     the current host package.
          • 
+
+     
        • LIBFOO_INSTALL_STAGING can be set to
+     YES or NO (default). If set to
+     YES, then the commands in the
+     LIBFOO_INSTALL_STAGING_CMDS variables are executed
+     to install the package into the staging directory.
          
+
+     
        • LIBFOO_INSTALL_TARGET can be set to
+     YES (default) or NO. If set to
+     YES, then the commands in the
+     LIBFOO_INSTALL_TARGET_CMDS variables are executed
+     to install the package into the target directory.
          
+
+     
        
+
+     
        The recommended way to define these variables is to use the
+     following syntax:
        
 
 
        -     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 host-pkgconfig
-     13  $(eval $(call AUTOTARGETS,package,foo))
+LIBFOO_VERSION=2.32
 
        
 
-    
        On line 6, we declare the version of
-    the package. On lines 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 output/staging/ is the directory
-    where all the packages are installed, including their
-    documentation, etc. By default, packages are installed in this
+     
        Now, the variables that define what should be performed at the
+     different steps of the build process.
        
+
+     
          
+
+       
        • LIBFOO_CONFIGURE_CMDS, used to list the
+       actions to be performed to configure the package before its
+       compilation
          • 
+
+       
        • LIBFOO_BUILD_CMDS, used to list the actions to
+       be performed to compile the package
          • 
+
+       
        • HOST_LIBFOO_INSTALL_CMDS, used to list the
+       actions to be performed to install the package, when the
+       package is a host package. The package must install its files
+       to the directory given by $(HOST_DIR). All files,
+       including development files such as headers should be
+       installed, since other packages might be compiled on top of
+       this package.
          • 
+
+       
        • LIBFOO_INSTALL_TARGET_CMDS, used to list the
+       actions to be performed to install the package to the target
+       directory, when the package is a target package. The package
+       must install its files to the directory given by
+       $(TARGET_DIR). Only the files required for
+       execution of the package should be installed. Header
+       files and documentation should not be installed.
          • 
+
+       
        • LIBFOO_INSTALL_STAGING_CMDS, used to list the
+       actions to be performed to install the package to the staging
+       directory, when the package is a target package. The package
+       must install its files to the directory given by
+       $(STAGING_DIR). All development files should be
+       installed, since they might be needed to compile other
+       packages.
          • 
+
+       
        • LIBFOO_CLEAN_CMDS, used to list the actions to
+       perform to clean up the build directory of the package.
          • 
+
+       
        • LIBFOO_UNINSTALL_TARGET_CMDS, used to list the
+       actions to uninstall the package from the target directory
+       $(TARGET_DIR)
          • 
+
+       
        • LIBFOO_UNINSTALL_STAGING_CMDS
          • , used to
+       list the actions to uninstall the package from the staging
+       directory $(STAGING_DIR).
+
+     
        
+
+     
        The preferred way to define these variables is:
        
+
+
        +define LIBFOO_CONFIGURE_CMDS
+ action 1
+ action 2
+ action 3
+endef
        
+
+     
        In the action definitions, you can use the following
+     variables:
        
+
+     
          
+
+       
        • $(@D), which contains the directory in which
+       the package source code has been uncompressed.
          • 
+
+       
        • $(TARGET_CC), $(TARGET_LD),
+       etc. to get the target cross-compilation utilities
          • 
+
+       
        • $(TARGET_CROSS) to get the cross-compilation
+       toolchain prefix
          • 
+
+       
        • Of course the $(HOST_DIR),
+       $(STAGING_DIR) and $(TARGET_DIR)
+       variables to install the packages properly.
          • 
+
+     
        
+
+
+     
        The last feature of the generic infrastructure is the ability
+     to add hook more actions after existing steps. These hooks aren't
+     really useful for generic packages, since the .mk
+     file already has full control over the actions performed in each
+     step of the package construction. The hooks are more useful for
+     packages using the autotools infrastructure described below. But
+     since they are provided by the generic infrastructure, they are
+     documented here.
        
+
+     
        The following hook points are available:
        
+
+     
          
+       
        • LIBFOO_POST_PATCH_HOOKS
          • 
+       
        • LIBFOO_POST_CONFIGURE_HOOKS
          • 
+       
        • LIBFOO_POST_BUILD_HOOKS
          • 
+       
        • LIBFOO_POST_INSTALL_HOOKS (for host packages only)
          • 
+       
        • LIBFOO_POST_INSTALL_STAGING_HOOKS (for target packages only)
          • 
+       
        • LIBFOO_POST_INSTALL_TARGET_HOOKS (for target packages only)
          • 
+     
        
+
+     
        This variables are lists of variable names containing
+     actions to be performed at this hook point. This allows several
+     hooks to be registered at a given hook point. Here is an
+     example:
        
+
+     
        +define LIBFOO_POST_PATCH_FIXUP
+  action1
+  action2
+endef
+
+LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
+
        
+
+   
        Makefile for autotools-based
+   packages : tutorial
        
+
+   
        First, let's see how to write a .mk file for an
+   autotools-based package, with an example :
        
+
+
        01: #############################################################
+02: #
+03: # foo
+04: #
+05: #############################################################
+06: 
+07: FOO_VERSION:=1.0
+08: FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz
+09: FOO_SITE:=http://www.foosoftware.org/downloads
+10: FOO_INSTALL_STAGING = YES
+11: FOO_INSTALL_TARGET = YES
+12: FOO_CONF_OPT =  --enable-shared
+13: FOO_DEPENDENCIES = libglib2 host-pkg-config
+14: 
+15: $(eval $(call AUTOTARGETS,package,foo))
        
+
+    
        On line 7, we declare the version of the package. On line 8 and
+    9, 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 10, we tell Buildroot to install the package to the
+    staging directory. The staging directory, located in
+    output/staging/ is the directory where all the
+    packages are installed, including their development files, etc. By
+    default, packages are not installed to the staging directory,
+    since usually, only libraries need to be installed in the staging
+    directory: their development files are needed to compile other
+    libraries or applications depending on them. Also by default, when
+    staging installation is enabled, 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 to install stripped binaries and
-    to not install the documentation.  By default, packages are
+    
        On line 11, we tell Buildroot to also install the package 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, target installation is enabled, so in fact,
+    this line is not strictly necessary. Also 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 to the
-    ./configure script when configuring the
-    the package.
        
+    
        On line 12, 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 13, we declare our dependencies, so that they are built
+    before the build process of our package starts.
        
+
+    
        Finally, on line line 14, we invoke the
+    AUTOTARGETS macro that generates all the Makefile
+    rules that actually allows the package to be built.
        
+
+    
        Makefile for autotools
+    packages : reference
        
+
+    
        The main macro of the autotools package infrastructure is
+    AUTOTARGETS. It has the same number of arguments and
+    the same semantic as the GENTARGETS macro, which is
+    the main macro of the generic package infrastructure. For
+    autotools packages, the ability to have target and host packages
+    is also available (and is actually widely used).
        
+
+    
        Just like the generic infrastructure, the autotools
+    infrastructure works by defining a number of variables before
+    calling the AUTOTARGETS macro.
        
+
+    
        First, all the package meta-information variables that exist in
+    the generic infrastructure also exist in the autotools
+    infrastructure: LIBFOO_VERSION,
+    LIBFOO_SOURCE, LIBFOO_PATCH,
+    LIBFOO_SITE, LIBFOO_SUBDIR,
+    LIBFOO_DEPENDENCIES,
+    LIBFOO_INSTALL_STAGING,
+    LIBFOO_INSTALL_TARGET.
        
+
+    
        A few additional variables, specific to the autotools
+    infrastructure, can also be defined. Many of them are only useful
+    in very specific cases, typical packages will therefore only use a
+    few of them.
        
+
+    
          
+
+      
        • LIBFOO_SUBDIR may contain the name of a
+      subdirectory inside the package that contains the configure
+      script. This is useful, if for example, the main configure
+      script is not at the root of the tree extracted by the
+      tarball. If HOST_LIBFOO_SUBDIR is not specified, it
+      defaults to LIBFOO_SUBDIR.
          • 
+
+      
        • LIBFOO_CONF_ENV, to specify additional
+      environment variables to pass to the configure script. By
+      default, empty.
          • 
+
+      
        • LIBFOO_CONF_OPT, to specify additional
+      configure options to pass to the configure script. By default,
+      empty.
          • 
+
+      
        • LIBFOO_MAKE, to specify an
+      alternate make command. This is typically useful
+      when parallel make it enabled in the configuration
+      (using BR2_JLEVEL) but that this feature should be
+      disabled for the given package, for one reason or another. By
+      default, set to $(MAKE). If parallel building is
+      not supported by the package, then it should
+      do LIBFOO_MAKE=$(MAKE1).
          • 
+
+      
        • LIBFOO_MAKE_ENV, to specify additional
+      environment variables to pass to make in the build step. These
+      are passed before the make command. By default,
+      empty.
          • 
+
+      
        • LIBFOO_MAKE_OPT, to specify additional
+      variables to pass to make in the build step. These are passed
+      after the make command. By default, empty.
          • 
+
+      
        • LIBFOO_AUTORECONF, tells whether the package
+      should be autoreconfigured or not (i.e, if the configure script
+      and Makefile.in files should be re-generated by re-running
+      autoconf, automake, libtool, etc.). Valid values
+      are YES and NO. By default, the value
+      is NO
          • 
+
+      
        • LIBFOO_AUTORECONF_OPT to specify additional
+      options passed to the autoreconf program
+      if LIBFOO_AUTORECONF=YES. By default, empty.
          • 
+
+      
        • LIBFOO_LIBTOOL_PATCH tells whether the
+      Buildroot patch to fix libtool cross-compilation issues should
+      be applied or not. Valid values are YES
+      and NO. By default, the value
+      is YES
          • 
+
+      
        • LIBFOO_USE_CONFIG_CACHE tells whether the
+      configure script should really on a cache file that caches test
+      results from previous configure script. Usually, this variable
+      should be left to its default value. Only for specific packages
+      having issues with the configure cache can set this variable to
+      the NO value (but this is more a work-around than a
+      really fix)
          • 
+
+      
        • LIBFOO_INSTALL_STAGING_OPT contains the make
+      options used to install the package to the staging directory. By
+      default, the value is DESTDIR=$$(STAGING_DIR)
+      install, which is correct for most autotools packages. It
+      is still possible to override it.
          • 
+
+      
        • LIBFOO_INSTALL_TARGET_OPT contains the make
+      options used to install the package to the target directory. By
+      default, the value is DESTDIR=$$(TARGET_DIR)
+      install-strip if BR2_ENABLE_DEBUG is not
+      set, and DESTDIR=$$(TARGET_DIR) install-exec
+      if BR2_ENABLE_DEBUG is set. These default values
+      are correct for most autotools packages, but it is still
+      possible to override them if needed.
          • 
+
+      
        • LIBFOO_CLEAN_OPT contains the make options used
+      to clean the package. By default, the value
+      is clean.
          • 
+
+      
        • LIBFOO_UNINSTALL_STAGING_OPT, contains the make
+      options used to uninstall the package from the staging
+      directory. By default, the value is
+      DESTDIR=$$(STAGING_DIR) uninstall.
          • 
+
+      
        • LIBFOO_UNINSTALL_TARGET_OPT, contains the make
+      options used to uninstall the package from the target
+      directory. By default, the value is
+      DESTDIR=$$(TARGET_DIR) uninstall.
          • 
+
+    
        
 
-    
        On line 12, we declare our
-    dependencies so that they are built before the build process of
-    our package starts.
        
+    
        With the autotools infrastructure, all the steps required to
+    build and install the packages are already defined, and they
+    generally work well for most autotools-based packages. However,
+    when required, it is still possible to customize what is done in
+    particular step:
        
 
-    
        Finally, on line line 13, we invoke
-    the package/Makefile.autotools.in magic to get things
-    working.
        
+    
          
+
+      
        • By adding a post-operation hook (after extract, patch,
+      configure, build or install). See the reference documentation of
+      the generic infrastructure for details.
          • 
 
-    
          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.
          
+      
        • By overriding one of the steps. For example, even if the
+      autotools infrastructure is used, if the package
+      .mk defines its own
+      LIBFOO_CONFIGURE_CMDS variable, it will be used
+      instead of the default autotools one. However, using this method
+      should be restricted to very specific cases. Do not use it in
+      the general case.
          • 
+
+    
        
 
-    
        The second solution, suitable for every type of package, looks
-    like this :
        
+    
        Manual Makefile : tutorial
        
 
+    
        NOTE: new manual makefiles should not be created, and
+    existing manual makefiles should be converted either to the
+    generic infrastructure or the autotools infrastructure. This
+    section is only kept to document the existing manual makefiles and
+    help understanding how they work.
        
 
 
              1  #############################################################
-- 
cgit v1.2.3