[Buildroot] [pull request] Pull request for branch for-2011.11/doc-updates

[Buildroot] [pull request] Pull request for branch for-2011.11/doc-updates

[Thomas Petazzoni]

Hello,

A few documentation updates that should go in 2011.11. It's far from
complete, but it's better to have this rather than nothing.

Thomas

The following changes since commit 296eb11299d1240b3570aba5abb8374a0911bf44:

  pulseaudio: needs host-intltool (2011-10-29 16:35:47 +0200)

are available in the git repository at:
  http://free-electrons.com/~thomas/buildroot.git for-2011.11/doc-updates

Thomas Petazzoni (5):
      doc: suggest how to add suboptions
      doc: mention how to format the Config.in file
      doc: more details about expressing dependencies in Config.in
      doc: mention the CMAKETARGETS infrastructure in the list of infrastructures
      doc: update GENTARGETS/AUTOTARGETS/CMAKETARGETS on the number of arguments

 docs/manual/adding-packages-autotargets.txt  |    2 +-
 docs/manual/adding-packages-cmaketargets.txt |    2 +-
 docs/manual/adding-packages-directory.txt    |   70 +++++++++++++++++++++++--
 docs/manual/adding-packages-gentargets.txt   |   29 +++--------
 4 files changed, 74 insertions(+), 29 deletions(-)

Thanks,
-- 
Thomas Petazzoni

[Buildroot] [PATCH 1/5] doc: suggest how to add suboptions

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/adding-packages-directory.txt |    9 +++++----
 1 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index 058ebad..a262a8c 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -24,10 +24,11 @@ config BR2_PACKAGE_LIBFOO
 	  http://foosoftware.org/libfoo/
 ---------------------------
 
-Of course, you can add other options 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
+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
-- 
1.7.4.1

[Buildroot] [PATCH 2/5] doc: mention how to format the Config.in file

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/adding-packages-directory.txt |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)

diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index a262a8c..b61eb54 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -24,6 +24,11 @@ config BR2_PACKAGE_LIBFOO
 	  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 but 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
-- 
1.7.4.1

[Buildroot] [PATCH 3/5] doc: more details about expressing dependencies in Config.in

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/adding-packages-directory.txt |   45 +++++++++++++++++++++++++++++
 1 files changed, 45 insertions(+), 0 deletions(-)

diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index b61eb54..a6b1f17 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -46,6 +46,51 @@ 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 also enabled. Typically, Buildroot uses the following
+rules:
+
+* 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.
+
+* 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.
+
+An example illustrates both the usage of +select+ and +depends on+.
+
+--------------------------
+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
+--------------------------
+
+
+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
 ~~~~~~~~~~~~~~
 
-- 
1.7.4.1

[Buildroot] [PATCH 4/5] doc: mention the CMAKETARGETS infrastructure in the list of infrastructures

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/adding-packages-directory.txt |   11 +++++++++--
 1 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index a6b1f17..0299c44 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -101,8 +101,8 @@ installed, etc.
 Depending on the package type, the +.mk+ file must be written in a
 different way, using different infrastructures:
 
-* *Makefiles for generic packages* (not using autotools): These are
-  based on an infrastructure similar to the one used for
+* *Makefiles for generic packages* (not using autotools or CMake):
+  These are based on an infrastructure similar to the one used for
   autotools-based packages, but requires a little more work from the
   developer. They specify what should be done for the configuration,
   compilation, installation and cleanup of the package. This
@@ -119,6 +119,13 @@ different way, using different infrastructures:
   system. We cover them through a xref:autotargets-tutorial[tutorial]
   and xref:autotargets-reference[reference].
 
+* *Makefiles for cmake-based software*: We provide a dedicated
+   infrastructure for such packages, as CMake is a more and more
+   commonly used build system and has a standardized behaviour. This
+   infrastructure 'must' be used for new packages that rely on
+   CMake. We cover them through a xref:cmaketargets-tutorial[tutorial]
+   and xref:cmaketargets-reference[reference].
+
 * *Hand-written Makefiles:* These are currently obsolete, and no new
   manual Makefiles should be added. However, since there are still
   many of them in the tree, we keep them documented in a
-- 
1.7.4.1

[Buildroot] [PATCH 5/5] doc: update GENTARGETS/AUTOTARGETS/CMAKETARGETS on the number of arguments

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/adding-packages-autotargets.txt  |    2 +-
 docs/manual/adding-packages-cmaketargets.txt |    2 +-
 docs/manual/adding-packages-gentargets.txt   |   29 +++++++------------------
 3 files changed, 10 insertions(+), 23 deletions(-)

diff --git a/docs/manual/adding-packages-autotargets.txt b/docs/manual/adding-packages-autotargets.txt
index cb41ead..428a182 100644
--- a/docs/manual/adding-packages-autotargets.txt
+++ b/docs/manual/adding-packages-autotargets.txt
@@ -23,7 +23,7 @@ package, with an example :
 11: LIBFOO_CONF_OPT = --enable-shared
 12: LIBFOO_DEPENDENCIES = libglib2 host-pkg-config
 13:
-14: $(eval $(call AUTOTARGETS,package,libfoo))
+14: $(eval $(call AUTOTARGETS))
 ------------------------
 
 On line 6, we declare the version of the package.
diff --git a/docs/manual/adding-packages-cmaketargets.txt b/docs/manual/adding-packages-cmaketargets.txt
index b03eb68..3e400ec 100644
--- a/docs/manual/adding-packages-cmaketargets.txt
+++ b/docs/manual/adding-packages-cmaketargets.txt
@@ -23,7 +23,7 @@ with an example :
 11: LIBFOO_CONF_OPT = -DBUILD_DEMOS=ON
 12: LIBFOO_DEPENDENCIES = libglib2 host-pkg-config
 13:
-14: $(eval $(call CMAKETARGETS,package,libfoo))
+14: $(eval $(call CMAKETARGETS))
 ------------------------
 
 On line 6, we declare the version of the package.
diff --git a/docs/manual/adding-packages-gentargets.txt b/docs/manual/adding-packages-gentargets.txt
index 9a319d1..29fc640 100644
--- a/docs/manual/adding-packages-gentargets.txt
+++ b/docs/manual/adding-packages-gentargets.txt
@@ -38,7 +38,7 @@ system is based on hand-written Makefiles or shell scripts.
 24: 	$(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
 25: endef
 26:
-27: $(eval $(call GENTARGETS,package,libfoo))
+27: $(eval $(call GENTARGETS))
 --------------------------------
 
 The Makefile begins on line 6 to 8 with metadata information: the
@@ -84,32 +84,19 @@ Makefile code necessary to make your package working.
 +GENTARGETS+ 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+, then the variables in the +.mk+ file
-  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 is 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.
+The +GENTARGETS+ macro takes one optional argument. This argument can
+be used to tell if the package is 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))
+$(eval $(call GENTARGETS))
+$(eval $(call GENTARGETS,host))
 ----------------------
 
 This might be useful if the compilation of the target package requires
-- 
1.7.4.1

[Buildroot] [PATCH 2/5] doc: mention how to format the Config.in file

[Michael S. Zick]

On Sun November 13 2011, Thomas Petazzoni wrote:
> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
> ---
>  docs/manual/adding-packages-directory.txt |    5 +++++
>  1 files changed, 5 insertions(+), 0 deletions(-)
> 
> diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
> index a262a8c..b61eb54 100644
> --- a/docs/manual/adding-packages-directory.txt
> +++ b/docs/manual/adding-packages-directory.txt
> @@ -24,6 +24,11 @@ config BR2_PACKAGE_LIBFOO
>  	  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 but be indented with one tab and two spaces, and it must

s/but/should/

Mike
> +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

[Buildroot] [PATCH 3/5] doc: more details about expressing dependencies in Config.in

[Michael S. Zick]

On Sun November 13 2011, Thomas Petazzoni wrote:
> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
> ---
>  docs/manual/adding-packages-directory.txt |   45 +++++++++++++++++++++++++++++
>  1 files changed, 45 insertions(+), 0 deletions(-)
> 
> diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
> index b61eb54..a6b1f17 100644
> --- a/docs/manual/adding-packages-directory.txt
> +++ b/docs/manual/adding-packages-directory.txt
> @@ -46,6 +46,51 @@ 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 also enabled. Typically, Buildroot uses the following
> +rules:
> +
> +* 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

s/therefore make sense to have/is sensible that/

Mike
> +  dependencies are selected. For example, the _libgtk2_ package uses
> +  +select BR2_PACKAGE_LIBGLIB2+ to make sure this library is also
> +  enabled.
> +
> +* 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.
> +
> +An example illustrates both the usage of +select+ and +depends on+.
> +
> +--------------------------
> +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
> +--------------------------
> +
> +
> +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
>  ~~~~~~~~~~~~~~
>  

[Buildroot] [pull request] Pull request for branch for-2011.11/doc-updates

[Peter Korsgaard]

>>>>> "Thomas" == Thomas Petazzoni <thomas.petazzoni@free-electrons.com> writes:

 Thomas> Hello,
 Thomas> A few documentation updates that should go in 2011.11. It's far from
 Thomas> complete, but it's better to have this rather than nothing.

 Thomas> Thomas

Committed all 5, thanks.

-- 
Bye, Peter Korsgaard