Commit | Line | Data |
---|---|---|
316d55d5 MY |
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 |