Documentation/kbuild/kconfig-macro-language.rst

   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