1 ======================
2 Kconfig macro language
3 ======================
4
5 Concept
6 -------
7
8 The basic idea was inspired by Make. When we look at Make, we notice sort of
9 two languages in one. One language describes dependency graphs consisting of
10 targets and prerequisites. The other is a macro language for performing textual
11 substitution.
12
13 There is clear distinction between the two language stages. For example, you
14 can 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
23 The macro language replaces the variable references with their expanded form,
24 and handles as if the source file were input like follows::
25
26 foo: foo.c
27 gcc -o foo foo.c
28
29 Then, Make analyzes the dependency graph and determines the targets to be
30 updated.
31
32 The idea is quite similar in Kconfig - it is possible to describe a Kconfig
33 file like this::
34
35 CC := gcc
36
37 config CC_HAS_FOO
38 def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC))
39
40 The macro language in Kconfig processes the source file into the following
41 intermediate::
42
43 config CC_HAS_FOO
44 def_bool y
45
46 Then, Kconfig moves onto the evaluation stage to resolve inter-symbol
47 dependency as explained in kconfig-language.rst.
48
49
50 Variables
51 ---------
52
53 Like in Make, a variable in Kconfig works as a macro variable. A macro
54 variable is expanded "in place" to yield a text string that may then be
55 expanded 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
57 a syntax error. The curly brace form as in ${CC} is not supported either.
58
59 There are two types of variables: simply expanded variables and recursively
60 expanded variables.
61
62 A simply expanded variable is defined using the := assignment operator. Its
63 righthand side is expanded immediately upon reading the line from the Kconfig
64 file.
65
66 A recursively expanded variable is defined using the = assignment operator.
67 Its righthand side is simply stored as the value of the variable without
68 expanding it in any way. Instead, the expansion is performed when the variable
69 is used.
70
71 There is another type of assignment operator; += is used to append text to a
72 variable. The righthand side of += is expanded immediately if the lefthand
73 side was originally defined as a simple variable. Otherwise, its evaluation is
74 deferred.
75
76 The variable reference can take parameters, in the following form::
77
78 $(name,arg1,arg2,arg3)
79
80 You can consider the parameterized reference as a function. (more precisely,
81 "user-defined function" in contrast to "built-in function" listed below).
82
83 Useful functions must be expanded when they are used since the same function is
84 expanded differently if different parameters are passed. Hence, a user-defined
85 function is defined using the = assignment operator. The parameters are
86 referenced within the body definition with $(1), $(2), etc.
87
88 In fact, recursively expanded variables and user-defined functions are the same
89 internally. (In other words, "variable" is "function with zero argument".)
90 When we say "variable" in a broad sense, it includes "user-defined function".
91
92
93 Built-in functions
94 ------------------
95
96 Like Make, Kconfig provides several built-in functions. Every function takes a
97 particular number of arguments.
98
99 In Make, every built-in function takes at least one argument. Kconfig allows
100 zero argument for built-in functions, such as $(filename), $(lineno). You could
101 consider those as "built-in variable", but it is just a matter of how we call
102 it after all. Let's say "built-in function" here to refer to natively supported
103 functionality.
104
105 Kconfig 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
142 Make vs Kconfig
143 ---------------
144
145 Kconfig adopts Make-like macro language, but the function call syntax is
146 slightly different.
147
148 A function call in Make looks like this::
149
150 $(func-name arg1,arg2,arg3)
151
152 The function name and the first argument are separated by at least one
153 whitespace. Then, leading whitespaces are trimmed from the first argument,
154 while whitespaces in the other arguments are kept. You need to use a kind of
155 trick to start the first parameter with spaces. For example, if you want
156 to make "info" function print " hello", you can write like follows::
157
158 empty :=
159 space := $(empty) $(empty)
160 $(info $(space)$(space)hello)
161
162 Kconfig uses only commas for delimiters, and keeps all whitespaces in the
163 function call. Some people prefer putting a space after each comma delimiter::
164
165 $(func-name, arg1, arg2, arg3)
166
167 In this case, "func-name" will receive " arg1", " arg2", " arg3". The presence
168 of leading spaces may matter depending on the function. The same applies to
169 Make - for example, $(subst .c, .o, $(sources)) is a typical mistake; it
170 replaces ".c" with " .o".
171
172 In 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
177 Kconfig invokes user-defined functions and built-in functions in the same way.
178 The omission of 'call' makes the syntax shorter.
179
180 In Make, some functions treat commas verbatim instead of argument separators.
181 For example, $(shell echo hello, world) runs the command "echo hello, world".
182 Likewise, $(info hello, world) prints "hello, world" to stdout. You could say
183 this is _useful_ inconsistency.
184
185 In Kconfig, for simpler implementation and grammatical consistency, commas that
186 appear in the $( ) context are always delimiters. It means::
187
188 $(shell, echo hello, world)
189
190 is an error because it is passing two parameters where the 'shell' function
191 accepts only one. To pass commas in arguments, you can use the following trick::
192
193 comma := ,
194 $(shell, echo hello$(comma) world)
195
196
197 Caveats
198 -------
199
200 A variable (or function) cannot be expanded across tokens. So, you cannot use
201 a variable as a shorthand for an expression that consists of multiple tokens.
202 The 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
211 But, the following does not work::
212
213 RANGES := 1 3
214
215 config FOO
216 int "foo"
217 range $(RANGES)
218
219 A variable cannot be expanded to any keyword in Kconfig. The following does
220 not work::
221
222 MY_TYPE := tristate
223
224 config FOO
225 $(MY_TYPE) "foo"
226 default y
227
228 Obviously from the design, $(shell command) is expanded in the textual
229 substitution phase. You cannot pass symbols to the 'shell' function.
230
231 The 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
241 Instead, you can do like follows so that any function call is statically
242 expanded::
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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.