Re: [PATCH 17/30] Documentation: kconfig: document a new Kconfig macro language

[Randy Dunlap <rdunlap@infradead.org>]

On 04/12/18 22:06, Masahiro Yamada wrote:
> Add a document for the macro language introduced to Kconfig.
> 
> Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
> ---
> 
> Changes in v3: None
> Changes in v2: None
> 
>  Documentation/kbuild/kconfig-macro-language.txt | 179 ++++++++++++++++++++++++
>  MAINTAINERS                                     |   2 +-
>  2 files changed, 180 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/kbuild/kconfig-macro-language.txt
> 
> diff --git a/Documentation/kbuild/kconfig-macro-language.txt b/Documentation/kbuild/kconfig-macro-language.txt
> new file mode 100644
> index 0000000..1f6281b
> --- /dev/null
> +++ b/Documentation/kbuild/kconfig-macro-language.txt
> @@ -0,0 +1,179 @@
> +Concept
> +-------
> +
> +The basic idea was inspired by Make. When we look at Make, we notice sort of
> +two languages in one. One language describes dependency graphs consisting of
> +targets and prerequisites. The other is a macro language for performing textual
> +substitution.
> +
> +There is clear distinction between the two language stages. For example, you
> +can write a makefile like follows:
> +
> +    APP := foo
> +    SRC := foo.c
> +    CC := gcc
> +
> +    $(APP): $(SRC)
> +            $(CC) -o $(APP) $(SRC)
> +
> +The macro language replaces the variable references with their expanded form,
> +and handles as if the source file were input like follows:
> +
> +    foo: foo.c
> +            gcc -o foo foo.c
> +
> +Then, Make analyzes the dependency graph and determines the targets to be
> +updated.
> +
> +The idea is quite similar in Kconfig - it is possible to describe a Kconfig
> +file like this:
> +
> +    CC := gcc
> +
> +    config CC_HAS_FOO
> +            def_bool $(shell $(srctree)/scripts/gcc-check-foo.sh $(CC))
> +
> +The macro language in Kconfig processes the source file into the following
> +intermediate:
> +
> +    config CC_HAS_FOO
> +            def_bool y
> +
> +Then, Kconfig moves onto the evaluation stage to resolve inter-symbol
> +dependency, which is explained in kconfig-language.txt.
> +
> +
> +Variables
> +---------
> +
> +Like in Make, a variable in Kconfig works as a macro variable.  A macro
> +variable is expanded "in place" to yield a text string that may then expanded

                                                               may then be expanded

> +further. To get the value of a variable, enclose the variable name in $( ).
> +As a special case, single-letter variable names can omit the parentheses and is

                                                                            and are

> +simply referenced like $X. Unlike Make, Kconfig does not support curly braces
> +as in ${CC}.
> +
> +There are two types of variables: simply expanded variables and recursively
> +expanded variables.
> +
> +A simply expanded variable is defined using the := assignment operator. Its
> +righthand side is expanded immediately upon reading the line from the Kconfig
> +file.
> +
> +A recursively expanded variable is defined using the = assignment operator.
> +Its righthand side is simply stored as the value of the variable without
> +expanding it in any way. Instead, the expansion is performed when the variable
> +is used.
> +
> +There is another type of assignment operator; += is used to append text to a
> +variable. The righthand side of += is expanded immediately if the lefthand
> +side was originally defined as a simple variable. Otherwise, its evaluation is
> +deferred.
> +
> +
> +Functions
> +---------
> +
> +Like Make, Kconfig supports both built-in and user-defined functions. A
> +function invocation looks much like a variable reference, but includes one or
> +more parameters separated by commas:
> +
> +  $(function-name arg1, arg2, arg3)
> +
> +Some functions are implemented as a built-in function. Currently, Kconfig
> +supports the following:
> +
> + - $(shell command)
> +
> +  The 'shell' function accepts a single argument that is expanded and passed
> +  to a subshell for execution. The standard output of the command is then read
> +  and returned as the value of the function. Every newline in the output is
> +  replaced with a space. Any trailing newlines are deleted. The standard error
> +  is not returned, nor is any program exit status.
> +
> + - $(warning text)
> +
> +  The 'warning' function prints its arguments to stderr. The output is prefixed
> +  with the name of the current Kconfig file, the current line number. It

                                          file and the current line number. It

> +  evaluates to an empty string.
> +
> + - $(info text)
> +
> +  The 'info' function is similar to 'warning' except that it sends its argument
> +  to stdout without any Kconfig name or line number.

Are current Kconfig file name and line number available so that someone can
construct their own $(info message) messages?

> +
> +A user-defined function is defined by using the = operator. The parameters are
> +referenced within the body definition with $1, $2, etc. (or $(1), $(2), etc.)
> +In fact, a user-defined function is internally treated as a recursive variable.

so the difference is just whether there are arguments?
A recursive variable does not have arguments and a function always has at least
one argument?


> +
> +A user-defined function is referenced in the same way as a built-in function:
> +
> +    $(my_func, arg0, arg1, arg2)

Syntax given above is:
+  $(function-name arg1, arg2, arg3)

with no comma after the function name.  Which is it?

> +
> +Note 1:
> +There is a slight difference in the whitespace handling of the function call
> +between Make and Kconfig. In Make, leading whitespaces are trimmed from the
> +first argument. So, $(info    FOO) is equivalent to $(info FOO). Kconfig keeps
> +any leading whitespaces except the one right after the function name, which
> +works as a separator. So, $(info    FOO) prints "   FOO" to the stdout.
> +
> +Note 2:
> +In Make, a user-defined function is referenced by using a built-in function,
> +'call', like this:
> +
> +    $(call my_func, arg0, arg1, arg2)
> +
> +However, Kconfig did not adopt this form just for the purpose of shortening the
> +syntax.
> +
> +
> +Caveats
> +-------
> +
> +A variable (or function) can not be expanded across tokens. So, you can not use

                            cannot                                     cannot

> +a variable as a shorthand for an expression that consists of multiple tokens.
> +The following works:
> +
> +    RANGE_MIN := 1
> +    RANGE_MAX := 3
> +
> +    config FOO
> +            int "foo"
> +            range $(RANGE_MIN) $(RANGE_MAX)
> +
> +But, the following does not work:
> +
> +    RANGES := 1 3
> +
> +    config FOO
> +            int "foo"
> +            range $(RANGES)
> +
> +A variable can not be expanded to any keyword in Kconfig.  The following does

              cannot

> +not work:
> +
> +    MY_TYPE := tristate
> +
> +    config FOO
> +            $(MY_TYPE) "foo"
> +            default y
> +
> +Obviously from the design, $(shell command) is expanded in the textual
> +substitution phase.  You can not pass symbols to the 'shell' function.

                            cannot

> +The following does not work as expected.
> +
> +    config ENDIAN_OPTION
> +            string
> +            default "-mbig-endian" if CPU_BIG_ENDIAN
> +            default "-mlittle-endian" if CPU_LITTLE_ENDIAN
> +
> +    config CC_HAS_ENDIAN_OPTION
> +            def_bool $(shell $(srctree)/scripts/gcc-check-option ENDIAN_OPTION)
> +
> +Instead, you can do like follows so that any function call is statically
> +expanded.
> +
> +    config CC_HAS_ENDIAN_OPTION
> +            bool

fix indentation?

> +	    default $(shell $(srctree)/scripts/gcc-check-option -mbig-endian) if CPU_BIG_ENDIAN
> +	    default $(shell $(srctree)/scripts/gcc-check-option -mlittle-endian) if CPU_LITTLE_ENDIAN


-- 
~Randy