[Buildroot] [PATCH 1/7] docs/manual: update 'adding packages' with the new _AVAILABLE symbol

[Arnout Vandecappelle <arnout@mind.be>]

On 09/10/12 01:40, Yann E. MORIN wrote:
> Signed-off-by: "Yann E. MORIN"<yann.morin.1998@free.fr>
> ---
>   docs/manual/adding-packages-autotools.txt |   48 ++++++--
>   docs/manual/adding-packages-directory.txt |  190 +++++++++++++++--------------
>   docs/manual/adding-packages-generic.txt   |   85 ++++++++-----
>   3 files changed, 191 insertions(+), 132 deletions(-)
>
> diff --git a/docs/manual/adding-packages-autotools.txt b/docs/manual/adding-packages-autotools.txt
> index 9fb0918..0f14489 100644
> --- a/docs/manual/adding-packages-autotools.txt
> +++ b/docs/manual/adding-packages-autotools.txt
> @@ -20,10 +20,24 @@ package, with an example :
>   08: LIBFOO_SITE = http://www.foosoftware.org/download
>   09: LIBFOO_INSTALL_STAGING = YES
>   10: LIBFOO_INSTALL_TARGET = YES
> -11: LIBFOO_CONF_OPT = --enable-shared
> -12: LIBFOO_DEPENDENCIES = libglib2 host-pkg-config
> -13:
> -14: $(eval $(autotools-package))
> +11: LIBFOO_DEPENDENCIES = host-libaaa libbbb

  In the Config.in example, it's libbar, not libbb.

> +12:
> +13: ifeq ($(BR2_PACKAGE_LIBFOO_FROBBLE),y)
> +14: LIBFOO_CONF_OPT += --enable-frobble
> +15: else
> +16: LIBFOO_CONF_OPT += --disable-frobble
> +17: endif
> +18:
> +19: LIBFOO_CONF_OPT += --with-gazzle-level=$(BR2_PACKAGE_LIBFOO_GAZZLE_LEVEL)

  This one is going a bit too far...  And if you keep it, it should
probably have a qstrip.

> +20:
> +21: ifeq ($(BR2_PACKAGE_LIBFOO_GOO),y)
> +22: LIBFOO_DEPENDENCIES += goo
> +23: LIBFOO_CONF_OPT += --enable-goo
> +24: else
> +25: LIBFOO_CONF_OPT += --disable-goo
> +26: endif

  While you're at it, an automatic enable/disable example would
be nice too.

> +27:
> +28: $(eval $(autotools-package))
>   ------------------------
>
>   On line 6, we declare the version of the package.
> @@ -50,16 +64,26 @@ 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+ 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 11, we declare our dependencies, so that they are built before the
> +build process of our package starts.
>
> -On line 12, we declare our dependencies, so that they are built
> -before the build process of our package starts.
> +On lines 13 to 17, if the user selected the option 'frobble'
> ++BR2_PACKAGE_LIBFOO_FROBBLE+, we add the corresponding configure option
> +to enable 'frobble' (line 14), or disable it (line 16), that will be
> +passed to the +./configure+ script before configuring and building the
> +package.

  "before configuring and building the package" is redundant.

>
> -Finally, on line line 14, we invoke the +autotools-package+
> -macro that generates all the Makefile rules that actually allows the
> -package to be built.
> +Similarly, on line 19, we add the configure option that defines the
> +'bazzle level' +BR2_PACKAGE_LIBFOO_GAZZLE_LEVEL+.

  bazzle -> gazzle.

> +
> +On lines 21 to 26, if user selected the option 'goo' +BR2_PACKAGE_LIBFOO_GOO+,
> +we add a dependency on the package +goo+ (line 22), and add the corresponding
> +configure option to enable 'goo' (line 23); or if 'goo' support is not
> +selected, we pass the configure option to disable it (line 25).
> +
> +Finally, on line line 28, we invoke the +autotools-package+ macro that
> +generates all the Makefile rules that actually allows the package to be
> +built.
>
>   [[autotools-package-reference]]
>
> diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
> index 4a96415..4863332 100644
> --- a/docs/manual/adding-packages-directory.txt
> +++ b/docs/manual/adding-packages-directory.txt
> @@ -12,30 +12,37 @@ 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 +libfoo+ software that will be used
> -and displayed in the configuration tool. It should basically contain:
> +Then, create a file named +Config.in+. This file will contain the option
> +descriptions related to our +libfoo+ software that will be used and
> +displayed in the configuration tool. It should basically contain:
>
>   ---------------------------
> +config BR2_PACKAGE_LIBFOO_AVAILABLE
> +	def_bool y
> +
>   config BR2_PACKAGE_LIBFOO
>   	bool "libfoo"
> +	depends on BR2_PACKAGE_LIBFOO_AVAILABLE
>   	help
>   	  This is a comment that explains what libfoo is.
>
>   	  http://foosoftware.org/libfoo/
>   ---------------------------
>
> -The +bool+ line, +help+ line and other meta-informations about the
> -configuration option must be indented with one tab. The help text
> -itself should be indented with one tab and two spaces, and it must
> -mention the upstream URL of the project.
> +*Notes*
> +
> +* This is a very simple example, not really complete, for a very simple
> +  package with no dependency.
> +
> +* 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:
> +  https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=Documentation/kbuild/kconfig-language.txt[]

  http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt

> +
> +* The +bool+ line, +help+ line and other meta-informations about the
> +  configuration option must be indented with one tab. The help text
> +  itself should be indented with one tab and two spaces, and it must
> +  mention the upstream URL of the project.
>
> -Of course, you can add other sub-options into a +if
> -BR2_PACKAGE_LIBFOO...endif+ statement to configure particular 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
> @@ -47,103 +54,108 @@ supposed to contain anything but the 'bare' name of the package.
>   source "package/libfoo/Config.in"
>   --------------------------
>
> -The +Config.in+ file of your package must also ensure that
> -dependencies are enabled. Typically, Buildroot uses the following
> -rules:
> +The +Config.in+ file for your package must also ensure that its
> +dependencies are available. This is done in four steps:
>
> -* Use a +select+ type of dependency for dependencies on
> -  libraries. These dependencies are generally not obvious and it
> -  therefore make sense to have the kconfig system ensure that the
> -  dependencies are selected. For example, the _libgtk2_ package uses
> -  +select BR2_PACKAGE_LIBGLIB2+ to make sure this library is also
> -  enabled.
> +1. The +BR2_PACKAGE_LIBFOO_AVAILABLE+ symbol shall +depends on+ any
> +other package's +_AVAILABLE+ symbol. It may also depend on any other
> +symbol, such as toolchain features, but should not directly depend on
> +any package's main symbol.

  ... except for _XORG7, _PYTHON, etc.

>
> -* Use a +depends on+ type of dependency when the user really needs to
> -  be aware of the dependency. Typically, Buildroot uses this type of
> -  dependency for dependencies on toolchain options (large file
> -  support, RPC support, IPV6 support), or for dependencies on "big"
> -  things, such as the X.org system. In some cases, especially
> -  dependency on toolchain options, it is recommended to add a
> -  +comment+ displayed when the option is not enabled, so that the user
> -  knows why the package is not available.
> +1. The main +BR2_PACKAGE_LIBFOO+ symbol should directly +depends
> +on+ it's own +_AVAILABLE+ symbol, +BR2_PACKAGE_LIBFOO_AVAILABLE+, and
> +should not depend on any other symbol.
>
> -An example illustrates both the usage of +select+ and +depends on+.
> +1. For each +_AVAILABLE+ symbol your package's own +_AVAILABLE+
> +symbol depends on, your package's main symbol should +select+ the
> +corresponding package's main symbol.
> +
> +1. Add a +comment+ briefly explaining why your package is not
> +available. That +comment+ shall have a single negative dependency on
> +your package's +_AVAILABLE+ symbol.
> +
> +The example below illustrates this mechanism for our libfoo package:
>
>   --------------------------
> -config BR2_PACKAGE_ACL
> -        bool "acl"
> -        select BR2_PACKAGE_ATTR
> -        depends on BR2_LARGEFILE
> -        help
> -          POSIX Access Control Lists, which are used to define more
> -          fine-grained discretionary access rights for files and
> -          directories.
> -          This package also provides libacl.
> -
> -          http://savannah.nongnu.org/projects/acl
> -
> -comment "acl requires a toolchain with LARGEFILE support"
> -        depends on !BR2_LARGEFILE
> +config BR2_PACKAGE_LIBFOO_AVAILABLE
> +	def_bool y
> +	depends on BR2_LARGEFILE
> +	depends on BR2_PACKAGE_LIBBAR
> +
> +comment "libfoo requires libbar, and a toolchain with support for LARGEFILEs"
> +	depends on !BR2_PACKAGE_LIBFOO_AVAILABLE
> +
> +config BR2_PACKAGE_LIBFOO
> +	bool "libfoo"
> +	depends on BR2_PACKAGE_LIBFOO_AVAILABLE
> +	select BR2_PACKAGE_LIBBAR
> +	help
> +	  This is a comment that explains what libfoo is.
> +
> +	  http://foosoftware.org/libfoo/
>   --------------------------
>
> +*Notes*
> +
> +* Even if your package does not have any dependency, you should anyway
> +  add the corresponding +_AVAILABLE+ symbol. This way, other packages can
> +  safely use the mechanism above to select your package, even if it is later
> +  updated and dependencies are added (eg. a new version of the package is
> +  released; or features, initially disabled, are now enabled...)
> +
> +* The symbols and the comment should be in this order, so that the
> +  +menuconfig+ will be properly laid out.
> +
> +* The dependencies in +Config.in+ will make sure that your package's
> +  dependencies options are also enabled, but they will not necessarily be
> +  built before your package. To do so, these dependencies also need to be
> +  expressed in the +.mk+ file of the package (see below).
>
> -Note that these two dependency types are only transitive with the
> -dependencies of the same kind.
> +If your package can be fine-tuned, you can add sub-options, enclosed inside
> +an +if BR2_PACKAGE_LIBFOO ... endif+ block. You can even have each option
> +depend on other packages, using the +_AVAILABLE+ and main symbols for
> +those pacakges.
>
> -This means, in the following example:
> +Finally, here's our now-complete example package:
>
>   --------------------------
> -config BR2_PACKAGE_A
> -        bool "Package A"
> +config BR2_PACKAGE_LIBFOO_AVAILABLE
> +	def_bool y
> +	depends on BR2_LARGEFILE
> +	depends on BR2_PACKAGE_LIBBAR
>
> -config BR2_PACKAGE_B
> -        bool "Package B"
> -        depends on BR2_PACKAGE_A
> +comment "libfoo requires libbar"

  And largefile.  Copy the comment from above.

> +	depends on !BR2_PACKAGE_LIBFOO_AVAILABLE
>
> -config BR2_PACKAGE_C
> -        bool "Package C"
> -        depends on BR2_PACKAGE_B
> +config BR2_PACKAGE_LIBFOO
> +	bool "libfoo"
> +	depends on BR2_PACKAGE_LIBFOO_AVAILABLE
> +	select BR2_PACKAGE_LIBBAR
> +	help
> +	  This is a comment that explains what libfoo is.
>
> -config BR2_PACKAGE_D
> -        bool "Package D"
> -        select BR2_PACKAGE_B
> +	  http://foosoftware.org/libfoo/
>
> -config BR2_PACKAGE_E
> -        bool "Package E"
> -        select BR2_PACKAGE_D
> ---------------------------
> +if BR2_PACKAGE_LIBFOO
>
> -* Selecting +Package C+ will be visible if +Package B+ has been
> -  selected, which in turn is only visible if +Package A+ has been
> -  selected.
> +config BR2_PACKAGE_LIBFOO_FROBBLE
> +	bool "Frobble the foo"
>
> -* Selecting +Package E+ will select +Package D+, which will select
> -  +Package B+, it will not check for the dependencies of +Package B+,
> -  so it will not select +Package A+.
> +config BR2_PACKAGE_LIBFOO_GAZZLE_LEVEL
> +	int "Gazzle level"
> +	range 0 10

  We currently don't have a single range config option, and only one int.
So the example is a bit contrived...  If you add an extra example, a string
option that is qstripped in the .mk file is more appropriate.

>
> -* Since +Package B+ is selected but +Package A+ is not, this violates
> -  the dependency of +Package B+ on +Package A+.  Therefore, in such a
> -  situation, the transitive dependency has to be added explicitly:
> +comment "goo option requires package goo"
> +	depends on !BR2_PACKAGE_GOO_AVAILABLE
>
> ---------------------------
> -config BR2_PACKAGE_D
> -	bool "Package D"
> -	select BR2_PACKAGE_B
> -	depends on BR2_PACKAGE_A
> -
> -config BR2_PACKAGE_E
> -	bool "Package E"
> -	select BR2_PACKAGE_D
> -	depends on BR2_PACKAGE_A
> ---------------------------
> +config BR2_PACKAGE_LIBFOO_GOO
> +	bool "goo"
> +	depends on BR2_PACKAGE_GOO_AVAILABLE
> +	select BR2_PACKAGE_GOO
>
> -Overall, for package library dependencies, +select+ should be
> -preferred.
> +endif
> +--------------------------
>
> -Note that such dependencies will make sure that the dependency option
> -is also enabled, but not necessarily built before your package. To do
> -so, the dependency also needs to be expressed in the +.mk+ file of the
> -package.
>
>   The +.mk+ file
>   ~~~~~~~~~~~~~~
> diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt
> index d3a4abb..3e4c864 100644
> --- a/docs/manual/adding-packages-generic.txt
> +++ b/docs/manual/adding-packages-generic.txt
> @@ -23,30 +23,45 @@ system is based on hand-written Makefiles or shell scripts.
>   09: LIBFOO_INSTALL_STAGING = YES
>   10: LIBFOO_DEPENDENCIES = host-libaaa libbbb

  libbar

>   11:
> -12: define LIBFOO_BUILD_CMDS
> -13: 	$(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all
> -14: endef
> +12: ifeq ($(BR2_PACKAGE_LIBFOO_FROBBLE),y)
> +13: LIBFOO_CFLAGS += -DFROBBLE
> +14: endif
>   15:
> -16: define LIBFOO_INSTALL_STAGING_CMDS
> -17: 	$(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
> -18: 	$(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
> -19: 	$(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
> -20: endef
> -21:
> -22: define LIBFOO_INSTALL_TARGET_CMDS
> -23: 	$(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
> -24: 	$(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
> -25: endef
> -26:
> -27: define LIBFOO_DEVICES
> -28: 	/dev/foo  c  666  0  0  42  0  -  -  -
> +16: LIBFOO_CFLAGS += -DGAZZLE_LEVEL=$(BR2_PACKAGE_LIBFOO_GAZZLE_LEVEL)
> +17:
> +18: ifeq ($(BR2_PACKAGE_LIBFOO_GOO),y)
> +19: LIBFOO_DEPENDENCIES += goo
> +20: LIBFOO_CFLAGS       += -DGOO
> +21: LIBFOO_LDFLAGS      += -lgoo
> +22: endif
> +23:
> +24: define LIBFOO_BUILD_CMDS
> +25: 	$(MAKE) -C $(@D)                                        \
> +26: 	        CC="$(TARGET_CC)" CFLAGS="$(LIBFOO_CFLAGS)"     \
> +27: 	        LD="$(TARGET_LD)" LDFLAGS="$(LIBFOO_LDFLAGS)"   \
> +28: 	        all
>   29: endef
>   30:
> -31: define LIBFOO_PERMISSIONS
> -32: 	/bin/foo  f  4755  0  0  -  -  -  -  -
> -33: endef
> -34:
> -35: $(eval $(generic-package))
> +31: define LIBFOO_INSTALL_STAGING_CMDS
> +32: 	$(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
> +33: 	$(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
> +34: 	$(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
> +35: endef
> +36:
> +37: define LIBFOO_INSTALL_TARGET_CMDS
> +38: 	$(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
> +39: 	$(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
> +40: endef
> +41:
> +42: define LIBFOO_DEVICES
> +43: 	/dev/foo  c  666  0  0  42  0  -  -  -
> +44: endef
> +45:
> +46: define LIBFOO_PERMISSIONS
> +47: 	/bin/foo  f  4755  0  0  -  -  -  -  -
> +48: endef
> +49:
> +50: $(eval $(generic-package))
>   --------------------------------
>
>   The Makefile begins on line 6 to 8 with metadata information: the
> @@ -64,12 +79,20 @@ 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.
> +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.
> +
> +On lines 12 to 14, if the user did select the option
> ++BR2_PACKAGE_LIBFOO_FROBBLE+ (see above, in the +Config.in+), we
> +conditionnally add a value to the +CFLAGS+. On line 16, we add the 'gazzle

  conditionally

> +level' +BR2_PACKAGE_LIBFOO_GAZZLE_LEVEL+ to the +CFLAGS+. And on lines 18
> +to 22, if the user selected 'goo' support, +BR2_PACKAGE_LIBFOO_GOO+, we
> +add a dependency on the package +goo+, and add appropriate +CFLAGS+ and
> ++LDFLAGS+.
>
>   The rest of the Makefile defines what should be done at the different
>   steps of the package configuration, compilation and installation.
> @@ -79,11 +102,11 @@ 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.

  Shouldn't _DEVICES and _PERMISSIONS be explained?

>
> -All these steps rely on the +$(@D)+ variable, which
> -contains the directory where the source code of the package has been
> -extracted.
> +All these steps rely on the +$(@D)+ variable, which contains the directory
> +where the source code of the package has been extracted, and where the
> +package is being built.
>
> -Finally, on line 35, we call the +generic-package+ which
> +Finally, on line 50, we call the +generic-package+ which
>   generates, according to the variables defined previously, all the
>   Makefile code necessary to make your package working.
>


  Overall, a very good addition to the doc, regardless of the _AVAILABLE stuff!

  Regards,
  Arnout
-- 
Arnout Vandecappelle                               arnout at mind be
Senior Embedded Software Architect                 +32-16-286540
Essensium/Mind                                     http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium                BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F