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 $(filename), $(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