]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | Introduction |
2 | ------------ | |
3 | ||
e95be9a5 | 4 | The configuration database is a collection of configuration options |
1da177e4 LT |
5 | organized in a tree structure: |
6 | ||
7 | +- Code maturity level options | |
8 | | +- Prompt for development and/or incomplete code/drivers | |
9 | +- General setup | |
10 | | +- Networking support | |
11 | | +- System V IPC | |
12 | | +- BSD Process Accounting | |
13 | | +- Sysctl support | |
14 | +- Loadable module support | |
15 | | +- Enable loadable module support | |
16 | | +- Set version information on all module symbols | |
17 | | +- Kernel module loader | |
18 | +- ... | |
19 | ||
20 | Every entry has its own dependencies. These dependencies are used | |
21 | to determine the visibility of an entry. Any child entry is only | |
22 | visible if its parent entry is also visible. | |
23 | ||
24 | Menu entries | |
25 | ------------ | |
26 | ||
0486bc90 | 27 | Most entries define a config option; all other entries help to organize |
1da177e4 LT |
28 | them. A single configuration option is defined like this: |
29 | ||
30 | config MODVERSIONS | |
31 | bool "Set version information on all module symbols" | |
bef1f402 | 32 | depends on MODULES |
1da177e4 LT |
33 | help |
34 | Usually, modules have to be recompiled whenever you switch to a new | |
35 | kernel. ... | |
36 | ||
37 | Every line starts with a key word and can be followed by multiple | |
38 | arguments. "config" starts a new config entry. The following lines | |
39 | define attributes for this config option. Attributes can be the type of | |
40 | the config option, input prompt, dependencies, help text and default | |
41 | values. A config option can be defined multiple times with the same | |
42 | name, but every definition can have only a single input prompt and the | |
43 | type must not conflict. | |
44 | ||
45 | Menu attributes | |
46 | --------------- | |
47 | ||
48 | A menu entry can have a number of attributes. Not all of them are | |
49 | applicable everywhere (see syntax). | |
50 | ||
51 | - type definition: "bool"/"tristate"/"string"/"hex"/"int" | |
52 | Every config option must have a type. There are only two basic types: | |
0486bc90 | 53 | tristate and string; the other types are based on these two. The type |
1da177e4 LT |
54 | definition optionally accepts an input prompt, so these two examples |
55 | are equivalent: | |
56 | ||
57 | bool "Networking support" | |
58 | and | |
59 | bool | |
60 | prompt "Networking support" | |
61 | ||
62 | - input prompt: "prompt" <prompt> ["if" <expr>] | |
63 | Every menu entry can have at most one prompt, which is used to display | |
64 | to the user. Optionally dependencies only for this prompt can be added | |
65 | with "if". | |
66 | ||
67 | - default value: "default" <expr> ["if" <expr>] | |
68 | A config option can have any number of default values. If multiple | |
69 | default values are visible, only the first defined one is active. | |
83dcde4e JE |
70 | Default values are not limited to the menu entry where they are |
71 | defined. This means the default can be defined somewhere else or be | |
1da177e4 LT |
72 | overridden by an earlier definition. |
73 | The default value is only assigned to the config symbol if no other | |
74 | value was set by the user (via the input prompt above). If an input | |
75 | prompt is visible the default value is presented to the user and can | |
76 | be overridden by him. | |
83dcde4e | 77 | Optionally, dependencies only for this default value can be added with |
1da177e4 LT |
78 | "if". |
79 | ||
6e66b900 RD |
80 | - type definition + default value: |
81 | "def_bool"/"def_tristate" <expr> ["if" <expr>] | |
82 | This is a shorthand notation for a type definition plus a value. | |
83 | Optionally dependencies for this default value can be added with "if". | |
84 | ||
85 | - dependencies: "depends on" <expr> | |
1da177e4 | 86 | This defines a dependency for this menu entry. If multiple |
83dcde4e | 87 | dependencies are defined, they are connected with '&&'. Dependencies |
1da177e4 LT |
88 | are applied to all other options within this menu entry (which also |
89 | accept an "if" expression), so these two examples are equivalent: | |
90 | ||
91 | bool "foo" if BAR | |
92 | default y if BAR | |
93 | and | |
94 | depends on BAR | |
95 | bool "foo" | |
96 | default y | |
97 | ||
98 | - reverse dependencies: "select" <symbol> ["if" <expr>] | |
99 | While normal dependencies reduce the upper limit of a symbol (see | |
100 | below), reverse dependencies can be used to force a lower limit of | |
101 | another symbol. The value of the current menu symbol is used as the | |
102 | minimal value <symbol> can be set to. If <symbol> is selected multiple | |
103 | times, the limit is set to the largest selection. | |
104 | Reverse dependencies can only be used with boolean or tristate | |
105 | symbols. | |
f8a74594 JP |
106 | Note: |
107 | select is evil.... select will by brute force set a symbol | |
108 | equal to 'y' without visiting the dependencies. So abusing | |
109 | select you are able to select a symbol FOO even if FOO depends | |
110 | on BAR that is not set. In general use select only for | |
0486bc90 | 111 | non-visible symbols (no prompts anywhere) and for symbols with |
f8a74594 JP |
112 | no dependencies. That will limit the usefulness but on the |
113 | other hand avoid the illegal configurations all over. kconfig | |
114 | should one day warn about such things. | |
1da177e4 LT |
115 | |
116 | - numerical ranges: "range" <symbol> <symbol> ["if" <expr>] | |
117 | This allows to limit the range of possible input values for int | |
118 | and hex symbols. The user can only input a value which is larger than | |
119 | or equal to the first symbol and smaller than or equal to the second | |
120 | symbol. | |
121 | ||
122 | - help text: "help" or "---help---" | |
123 | This defines a help text. The end of the help text is determined by | |
124 | the indentation level, this means it ends at the first line which has | |
125 | a smaller indentation than the first line of the help text. | |
126 | "---help---" and "help" do not differ in behaviour, "---help---" is | |
53cb4726 | 127 | used to help visually separate configuration logic from help within |
1da177e4 LT |
128 | the file as an aid to developers. |
129 | ||
130 | ||
131 | Menu dependencies | |
132 | ----------------- | |
133 | ||
134 | Dependencies define the visibility of a menu entry and can also reduce | |
135 | the input range of tristate symbols. The tristate logic used in the | |
136 | expressions uses one more state than normal boolean logic to express the | |
137 | module state. Dependency expressions have the following syntax: | |
138 | ||
139 | <expr> ::= <symbol> (1) | |
140 | <symbol> '=' <symbol> (2) | |
141 | <symbol> '!=' <symbol> (3) | |
142 | '(' <expr> ')' (4) | |
143 | '!' <expr> (5) | |
144 | <expr> '&&' <expr> (6) | |
145 | <expr> '||' <expr> (7) | |
146 | ||
147 | Expressions are listed in decreasing order of precedence. | |
148 | ||
149 | (1) Convert the symbol into an expression. Boolean and tristate symbols | |
150 | are simply converted into the respective expression values. All | |
151 | other symbol types result in 'n'. | |
152 | (2) If the values of both symbols are equal, it returns 'y', | |
153 | otherwise 'n'. | |
154 | (3) If the values of both symbols are equal, it returns 'n', | |
155 | otherwise 'y'. | |
156 | (4) Returns the value of the expression. Used to override precedence. | |
157 | (5) Returns the result of (2-/expr/). | |
158 | (6) Returns the result of min(/expr/, /expr/). | |
159 | (7) Returns the result of max(/expr/, /expr/). | |
160 | ||
161 | An expression can have a value of 'n', 'm' or 'y' (or 0, 1, 2 | |
162 | respectively for calculations). A menu entry becomes visible when it's | |
163 | expression evaluates to 'm' or 'y'. | |
164 | ||
0486bc90 RD |
165 | There are two types of symbols: constant and non-constant symbols. |
166 | Non-constant symbols are the most common ones and are defined with the | |
167 | 'config' statement. Non-constant symbols consist entirely of alphanumeric | |
1da177e4 LT |
168 | characters or underscores. |
169 | Constant symbols are only part of expressions. Constant symbols are | |
83dcde4e | 170 | always surrounded by single or double quotes. Within the quote, any |
1da177e4 LT |
171 | other character is allowed and the quotes can be escaped using '\'. |
172 | ||
173 | Menu structure | |
174 | -------------- | |
175 | ||
176 | The position of a menu entry in the tree is determined in two ways. First | |
177 | it can be specified explicitly: | |
178 | ||
179 | menu "Network device support" | |
bef1f402 | 180 | depends on NET |
1da177e4 LT |
181 | |
182 | config NETDEVICES | |
183 | ... | |
184 | ||
185 | endmenu | |
186 | ||
187 | All entries within the "menu" ... "endmenu" block become a submenu of | |
188 | "Network device support". All subentries inherit the dependencies from | |
189 | the menu entry, e.g. this means the dependency "NET" is added to the | |
190 | dependency list of the config option NETDEVICES. | |
191 | ||
192 | The other way to generate the menu structure is done by analyzing the | |
193 | dependencies. If a menu entry somehow depends on the previous entry, it | |
194 | can be made a submenu of it. First, the previous (parent) symbol must | |
195 | be part of the dependency list and then one of these two conditions | |
196 | must be true: | |
197 | - the child entry must become invisible, if the parent is set to 'n' | |
198 | - the child entry must only be visible, if the parent is visible | |
199 | ||
200 | config MODULES | |
201 | bool "Enable loadable module support" | |
202 | ||
203 | config MODVERSIONS | |
204 | bool "Set version information on all module symbols" | |
bef1f402 | 205 | depends on MODULES |
1da177e4 LT |
206 | |
207 | comment "module support disabled" | |
bef1f402 | 208 | depends on !MODULES |
1da177e4 LT |
209 | |
210 | MODVERSIONS directly depends on MODULES, this means it's only visible if | |
211 | MODULES is different from 'n'. The comment on the other hand is always | |
212 | visible when MODULES is visible (the (empty) dependency of MODULES is | |
213 | also part of the comment dependencies). | |
214 | ||
215 | ||
216 | Kconfig syntax | |
217 | -------------- | |
218 | ||
219 | The configuration file describes a series of menu entries, where every | |
220 | line starts with a keyword (except help texts). The following keywords | |
221 | end a menu entry: | |
222 | - config | |
223 | - menuconfig | |
224 | - choice/endchoice | |
225 | - comment | |
226 | - menu/endmenu | |
227 | - if/endif | |
228 | - source | |
229 | The first five also start the definition of a menu entry. | |
230 | ||
231 | config: | |
232 | ||
233 | "config" <symbol> | |
234 | <config options> | |
235 | ||
236 | This defines a config symbol <symbol> and accepts any of above | |
237 | attributes as options. | |
238 | ||
239 | menuconfig: | |
240 | "menuconfig" <symbol> | |
241 | <config options> | |
242 | ||
53cb4726 | 243 | This is similar to the simple config entry above, but it also gives a |
1da177e4 LT |
244 | hint to front ends, that all suboptions should be displayed as a |
245 | separate list of options. | |
246 | ||
247 | choices: | |
248 | ||
249 | "choice" | |
250 | <choice options> | |
251 | <choice block> | |
252 | "endchoice" | |
253 | ||
83dcde4e | 254 | This defines a choice group and accepts any of the above attributes as |
1da177e4 LT |
255 | options. A choice can only be of type bool or tristate, while a boolean |
256 | choice only allows a single config entry to be selected, a tristate | |
257 | choice also allows any number of config entries to be set to 'm'. This | |
258 | can be used if multiple drivers for a single hardware exists and only a | |
259 | single driver can be compiled/loaded into the kernel, but all drivers | |
260 | can be compiled as modules. | |
261 | A choice accepts another option "optional", which allows to set the | |
262 | choice to 'n' and no entry needs to be selected. | |
263 | ||
264 | comment: | |
265 | ||
266 | "comment" <prompt> | |
267 | <comment options> | |
268 | ||
269 | This defines a comment which is displayed to the user during the | |
270 | configuration process and is also echoed to the output files. The only | |
271 | possible options are dependencies. | |
272 | ||
273 | menu: | |
274 | ||
275 | "menu" <prompt> | |
276 | <menu options> | |
277 | <menu block> | |
278 | "endmenu" | |
279 | ||
280 | This defines a menu block, see "Menu structure" above for more | |
281 | information. The only possible options are dependencies. | |
282 | ||
283 | if: | |
284 | ||
285 | "if" <expr> | |
286 | <if block> | |
287 | "endif" | |
288 | ||
289 | This defines an if block. The dependency expression <expr> is appended | |
290 | to all enclosed menu entries. | |
291 | ||
292 | source: | |
293 | ||
294 | "source" <prompt> | |
295 | ||
296 | This reads the specified configuration file. This file is always parsed. | |
6e66b900 RD |
297 | |
298 | mainmenu: | |
299 | ||
300 | "mainmenu" <prompt> | |
301 | ||
302 | This sets the config program's title bar if the config program chooses | |
303 | to use it. | |
0486bc90 RD |
304 | |
305 | ||
306 | Kconfig hints | |
307 | ------------- | |
308 | This is a collection of Kconfig tips, most of which aren't obvious at | |
309 | first glance and most of which have become idioms in several Kconfig | |
310 | files. | |
311 | ||
312 | Build as module only | |
313 | ~~~~~~~~~~~~~~~~~~~~ | |
314 | To restrict a component build to module-only, qualify its config symbol | |
315 | with "depends on m". E.g.: | |
316 | ||
317 | config FOO | |
318 | depends on BAR && m | |
319 | ||
320 | limits FOO to module (=m) or disabled (=n). | |
321 | ||
322 | ||
323 | Build limited by a third config symbol which may be =y or =m | |
324 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
325 | A common idiom that we see (and sometimes have problems with) is this: | |
326 | ||
327 | When option C in B (module or subsystem) uses interfaces from A (module | |
328 | or subsystem), and both A and B are tristate (could be =y or =m if they | |
329 | were independent of each other, but they aren't), then we need to limit | |
330 | C such that it cannot be built statically if A is built as a loadable | |
331 | module. (C already depends on B, so there is no dependency issue to | |
332 | take care of here.) | |
333 | ||
334 | If A is linked statically into the kernel image, C can be built | |
335 | statically or as loadable module(s). However, if A is built as loadable | |
336 | module(s), then C must be restricted to loadable module(s) also. This | |
337 | can be expressed in kconfig language as: | |
338 | ||
339 | config C | |
340 | depends on A = y || A = B | |
341 | ||
342 | or for real examples, use this command in a kernel tree: | |
343 | ||
344 | $ find . -name Kconfig\* | xargs grep -ns "depends on.*=.*||.*=" | grep -v orig | |
345 |