Commit | Line | Data |
---|---|---|
cd238eff MCC |
1 | ====================== |
2 | Kconfig macro language | |
3 | ====================== | |
4 | ||
316d55d5 MY |
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 | |
cd238eff | 14 | can write a makefile like follows:: |
316d55d5 MY |
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, | |
cd238eff | 24 | and handles as if the source file were input like follows:: |
316d55d5 MY |
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 | |
cd238eff | 33 | file like this:: |
316d55d5 MY |
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 | |
cd238eff | 41 | intermediate:: |
316d55d5 MY |
42 | |
43 | config CC_HAS_FOO | |
44 | def_bool y | |
45 | ||
46 | Then, Kconfig moves onto the evaluation stage to resolve inter-symbol | |
2eebb7ab | 47 | dependency as explained in kconfig-language.rst. |
316d55d5 MY |
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 | ||
cd238eff | 76 | The variable reference can take parameters, in the following form:: |
316d55d5 MY |
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 | |
90d39628 | 100 | zero argument for built-in functions, such as $(filename), $(lineno). You could |
316d55d5 MY |
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 | ||
cd238eff | 148 | A function call in Make looks like this:: |
316d55d5 MY |
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 | |
cd238eff | 156 | to make "info" function print " hello", you can write like follows:: |
316d55d5 MY |
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 | |
cd238eff | 163 | function call. Some people prefer putting a space after each comma delimiter:: |
316d55d5 MY |
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, | |
cd238eff | 173 | 'call', like this:: |
316d55d5 MY |
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 | |
cd238eff | 186 | appear in the $( ) context are always delimiters. It means:: |
316d55d5 MY |
187 | |
188 | $(shell, echo hello, world) | |
189 | ||
190 | is an error because it is passing two parameters where the 'shell' function | |
cd238eff | 191 | accepts only one. To pass commas in arguments, you can use the following trick:: |
316d55d5 MY |
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. | |
cd238eff | 202 | The following works:: |
316d55d5 MY |
203 | |
204 | RANGE_MIN := 1 | |
205 | RANGE_MAX := 3 | |
206 | ||
207 | config FOO | |
208 | int "foo" | |
209 | range $(RANGE_MIN) $(RANGE_MAX) | |
210 | ||
cd238eff | 211 | But, the following does not work:: |
316d55d5 MY |
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 | |
cd238eff | 220 | not work:: |
316d55d5 MY |
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. | |
cd238eff MCC |
230 | |
231 | The following does not work as expected:: | |
316d55d5 MY |
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 | |
cd238eff | 242 | expanded:: |
316d55d5 MY |
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 |