[Buildroot] [PATCH 2 of 7 v3] infra: add comment describing single/double dollar-sign rules

[Thomas De Schampheleire <patrickdepinguin@gmail.com>]

As the rules with respect to variable and function references and the need
for single or double dollar signs are not trivial, add a comment in
pkg-generic.mk describing them.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
v3: expand exception for pkgdir and pkgname
v2: clarify exception for pkgdir and pkgname

 package/pkg-generic.mk |  23 +++++++++++++++++++++++
 1 files changed, 23 insertions(+), 0 deletions(-)

diff -r b1861ead4977 -r c09add9a59c5 package/pkg-generic.mk
--- a/package/pkg-generic.mk	Thu May 08 21:53:48 2014 +0200
+++ b/package/pkg-generic.mk	Sat May 10 10:04:45 2014 +0200
@@ -269,6 +269,29 @@
 #  argument 3 is the uppercase package name, without the HOST_ prefix
 #             for host packages
 #  argument 4 is the type (target or host)
+#
+# Note about variable and function references: inside all blocks that are
+# evaluated with $(eval), which includes all 'inner-xxx-package' blocks,
+# specific rules apply with respect to variable and function references.
+# - Numbered variables (parameters to the block) can be referenced with a single
+#   dollar sign: $(1), $(2), $(3), etc.
+# - pkgdir and pkgname should be referenced with a single dollar sign too. These
+#   functions rely on 'the most recently parsed makefile' which is supposed to
+#   be the package .mk file. If we defer the evaluation of these functions using
+#   double dollar signs, then they may be evaluated too late, when other
+#   makefiles have already been parsed. One specific case is when $$(pkgdir) is
+#   assigned to a variable using deferred evaluation with '=' and this variable
+#   is used in a target rule outside the eval'ed inner block. In this case, the
+#   pkgdir will be that of the last makefile parsed by buildroot, which is not
+#   the expected value. This mechanism is for example used for the TARGET_PATCH
+#   rule.
+# - All other variables should be referenced with a double dollar sign:
+#   $$(TARGET_DIR), $$($(2)_VERSION), etc. Also all make functions should be
+#   referenced with a double dollar sign: $$(subst), $$(call), $$(filter-out),
+#   etc. This rule ensures that these variables and functions are only expanded
+#   during the $(eval) step, and not earlier. Otherwise, unintuitive and
+#   undesired behavior occurs with respect to these variables and functions.
+#
 ################################################################################
 
 define inner-generic-package