Pull request for branch for-2011.11/doc-updates

index 058ebad..a262a8c 100644
@@ -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

index a262a8c..b61eb54 100644
@@ -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

index b61eb54..a6b1f17 100644
@@ -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
 ~~~~~~~~~~~~~~
 

index a6b1f17..0299c44 100644
@@ -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

index cb41ead..428a182 100644
@@ -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.

index b03eb68..3e400ec 100644
@@ -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.

index 9a319d1..29fc640 100644
@@ -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