Documentation/kbuild/kconfig-macro-language.txt

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