1======================
2Kconfig macro language
3======================
4
5Concept
6-------
7
8The basic idea was inspired by Make. When we look at Make, we notice sort of
9two languages in one. One language describes dependency graphs consisting of
10targets and prerequisites. The other is a macro language for performing textual
11substitution.
12
13There is clear distinction between the two language stages. For example, you
14can write a makefile like follows::
15
16    APP := foo
17    SRC := foo.c
18    CC := gcc
19
20    $(APP): $(SRC)
21            $(CC) -o $(APP) $(SRC)
22
23The macro language replaces the variable references with their expanded form,
24and handles as if the source file were input like follows::
25
26    foo: foo.c
27            gcc -o foo foo.c
28
29Then, Make analyzes the dependency graph and determines the targets to be
30updated.
31
32The idea is quite similar in Kconfig - it is possible to describe a Kconfig
33file like this::
34
35    CC := gcc
36
37    config CC_HAS_FOO
38            def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC))
39
40The macro language in Kconfig processes the source file into the following
41intermediate::
42
43    config CC_HAS_FOO
44            def_bool y
45
46Then, Kconfig moves onto the evaluation stage to resolve inter-symbol
47dependency as explained in kconfig-language.rst.
48
49
50Variables
51---------
52
53Like in Make, a variable in Kconfig works as a macro variable.  A macro
54variable is expanded "in place" to yield a text string that may then be
55expanded further. To get the value of a variable, enclose the variable name in
56$( ). The parentheses are required even for single-letter variable names; $X is
57a syntax error. The curly brace form as in ${CC} is not supported either.
58
59There are two types of variables: simply expanded variables and recursively
60expanded variables.
61
62A simply expanded variable is defined using the := assignment operator. Its
63righthand side is expanded immediately upon reading the line from the Kconfig
64file.
65
66A recursively expanded variable is defined using the = assignment operator.
67Its righthand side is simply stored as the value of the variable without
68expanding it in any way. Instead, the expansion is performed when the variable
69is used.
70
71There is another type of assignment operator; += is used to append text to a
72variable. The righthand side of += is expanded immediately if the lefthand
73side was originally defined as a simple variable. Otherwise, its evaluation is
74deferred.
75
76The variable reference can take parameters, in the following form::
77
78  $(name,arg1,arg2,arg3)
79
80You can consider the parameterized reference as a function. (more precisely,
81"user-defined function" in contrast to "built-in function" listed below).
82
83Useful functions must be expanded when they are used since the same function is
84expanded differently if different parameters are passed. Hence, a user-defined
85function is defined using the = assignment operator. The parameters are
86referenced within the body definition with $(1), $(2), etc.
87
88In fact, recursively expanded variables and user-defined functions are the same
89internally. (In other words, "variable" is "function with zero argument".)
90When we say "variable" in a broad sense, it includes "user-defined function".
91
92
93Built-in functions
94------------------
95
96Like Make, Kconfig provides several built-in functions. Every function takes a
97particular number of arguments.
98
99In Make, every built-in function takes at least one argument. Kconfig allows
100zero argument for built-in functions, such as $(fileno), $(lineno). You could
101consider those as "built-in variable", but it is just a matter of how we call
102it after all. Let's say "built-in function" here to refer to natively supported
103functionality.
104
105Kconfig currently supports the following built-in functions.
106
107 - $(shell,command)
108
109  The "shell" function accepts a single argument that is expanded and passed
110  to a subshell for execution. The standard output of the command is then read
111  and returned as the value of the function. Every newline in the output is
112  replaced with a space. Any trailing newlines are deleted. The standard error
113  is not returned, nor is any program exit status.
114
115 - $(info,text)
116
117  The "info" function takes a single argument and prints it to stdout.
118  It evaluates to an empty string.
119
120 - $(warning-if,condition,text)
121
122  The "warning-if" function takes two arguments. If the condition part is "y",
123  the text part is sent to stderr. The text is prefixed with the name of the
124  current Kconfig file and the current line number.
125
126 - $(error-if,condition,text)
127
128  The "error-if" function is similar to "warning-if", but it terminates the
129  parsing immediately if the condition part is "y".
130
131 - $(filename)
132
133  The 'filename' takes no argument, and $(filename) is expanded to the file
134  name being parsed.
135
136 - $(lineno)
137
138  The 'lineno' takes no argument, and $(lineno) is expanded to the line number
139  being parsed.
140
141
142Make vs Kconfig
143---------------
144
145Kconfig adopts Make-like macro language, but the function call syntax is
146slightly different.
147
148A function call in Make looks like this::
149
150  $(func-name arg1,arg2,arg3)
151
152The function name and the first argument are separated by at least one
153whitespace. Then, leading whitespaces are trimmed from the first argument,
154while whitespaces in the other arguments are kept. You need to use a kind of
155trick to start the first parameter with spaces. For example, if you want
156to make "info" function print "  hello", you can write like follows::
157
158  empty :=
159  space := $(empty) $(empty)
160  $(info $(space)$(space)hello)
161
162Kconfig uses only commas for delimiters, and keeps all whitespaces in the
163function call. Some people prefer putting a space after each comma delimiter::
164
165  $(func-name, arg1, arg2, arg3)
166
167In this case, "func-name" will receive " arg1", " arg2", " arg3". The presence
168of leading spaces may matter depending on the function. The same applies to
169Make - for example, $(subst .c, .o, $(sources)) is a typical mistake; it
170replaces ".c" with " .o".
171
172In Make, a user-defined function is referenced by using a built-in function,
173'call', like this::
174
175    $(call my-func,arg1,arg2,arg3)
176
177Kconfig invokes user-defined functions and built-in functions in the same way.
178The omission of 'call' makes the syntax shorter.
179
180In Make, some functions treat commas verbatim instead of argument separators.
181For example, $(shell echo hello, world) runs the command "echo hello, world".
182Likewise, $(info hello, world) prints "hello, world" to stdout. You could say
183this is _useful_ inconsistency.
184
185In Kconfig, for simpler implementation and grammatical consistency, commas that
186appear in the $( ) context are always delimiters. It means::
187
188  $(shell, echo hello, world)
189
190is an error because it is passing two parameters where the 'shell' function
191accepts only one. To pass commas in arguments, you can use the following trick::
192
193  comma := ,
194  $(shell, echo hello$(comma) world)
195
196
197Caveats
198-------
199
200A variable (or function) cannot be expanded across tokens. So, you cannot use
201a variable as a shorthand for an expression that consists of multiple tokens.
202The following works::
203
204    RANGE_MIN := 1
205    RANGE_MAX := 3
206
207    config FOO
208            int "foo"
209            range $(RANGE_MIN) $(RANGE_MAX)
210
211But, the following does not work::
212
213    RANGES := 1 3
214
215    config FOO
216            int "foo"
217            range $(RANGES)
218
219A variable cannot be expanded to any keyword in Kconfig.  The following does
220not work::
221
222    MY_TYPE := tristate
223
224    config FOO
225            $(MY_TYPE) "foo"
226            default y
227
228Obviously from the design, $(shell command) is expanded in the textual
229substitution phase. You cannot pass symbols to the 'shell' function.
230
231The following does not work as expected::
232
233    config ENDIAN_FLAG
234            string
235            default "-mbig-endian" if CPU_BIG_ENDIAN
236            default "-mlittle-endian" if CPU_LITTLE_ENDIAN
237
238    config CC_HAS_ENDIAN_FLAG
239            def_bool $(shell $(srctree)/scripts/gcc-check-flag ENDIAN_FLAG)
240
241Instead, you can do like follows so that any function call is statically
242expanded::
243
244    config CC_HAS_ENDIAN_FLAG
245            bool
246            default $(shell $(srctree)/scripts/gcc-check-flag -mbig-endian) if CPU_BIG_ENDIAN
247            default $(shell $(srctree)/scripts/gcc-check-flag -mlittle-endian) if CPU_LITTLE_ENDIAN
248