1 # Copyright (c) 2011-2019, Ulf Magnusson
2 # SPDX-License-Identifier: ISC
8 Kconfiglib is a Python 2/3 library for scripting and extracting information
9 from Kconfig (https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt)
10 configuration systems.
12 See the homepage at https://github.com/ulfalizer/Kconfiglib for a longer
15 Since Kconfiglib 12.0.0, the library version is available in
16 kconfiglib.VERSION, which is a (<major>, <minor>, <patch>) tuple, e.g.
20 Using Kconfiglib on the Linux kernel with the Makefile targets
21 ==============================================================
23 For the Linux kernel, a handy interface is provided by the
24 scripts/kconfig/Makefile patch, which can be applied with either 'git am' or
27 $ wget -qO- https://raw.githubusercontent.com/ulfalizer/Kconfiglib/master/makefile.patch | git am
28 $ wget -qO- https://raw.githubusercontent.com/ulfalizer/Kconfiglib/master/makefile.patch | patch -p1
30 Warning: Not passing -p1 to patch will cause the wrong file to be patched.
32 Please tell me if the patch does not apply. It should be trivial to apply
33 manually, as it's just a block of text that needs to be inserted near the other
34 *conf: targets in scripts/kconfig/Makefile.
36 Look further down for a motivation for the Makefile patch and for instructions
37 on how you can use Kconfiglib without it.
39 If you do not wish to install Kconfiglib via pip, the Makefile patch is set up
40 so that you can also just clone Kconfiglib into the kernel root:
42 $ git clone git://github.com/ulfalizer/Kconfiglib.git
43 $ git am Kconfiglib/makefile.patch (or 'patch -p1 < Kconfiglib/makefile.patch')
45 Warning: The directory name Kconfiglib/ is significant in this case, because
46 it's added to PYTHONPATH by the new targets in makefile.patch.
48 The targets added by the Makefile patch are described in the following
55 This target runs the curses menuconfig interface with Python 3. As of
56 Kconfiglib 12.2.0, both Python 2 and Python 3 are supported (previously, only
57 Python 3 was supported, so this was a backport).
63 This target runs the Tkinter menuconfig interface. Both Python 2 and Python 3
64 are supported. To change the Python interpreter used, pass
65 PYTHONCMD=<executable> to 'make'. The default is 'python'.
68 make [ARCH=<arch>] iscriptconfig
69 --------------------------------
71 This target gives an interactive Python prompt where a Kconfig instance has
72 been preloaded and is available in 'kconf'. To change the Python interpreter
73 used, pass PYTHONCMD=<executable> to 'make'. The default is 'python'.
75 To get a feel for the API, try evaluating and printing the symbols in
76 kconf.defined_syms, and explore the MenuNode menu tree starting at
77 kconf.top_node by following 'next' and 'list' pointers.
79 The item contained in a menu node is found in MenuNode.item (note that this can
80 be one of the constants kconfiglib.MENU and kconfiglib.COMMENT), and all
81 symbols and choices have a 'nodes' attribute containing their menu nodes
82 (usually only one). Printing a menu node will print its item, in Kconfig
85 If you want to look up a symbol by name, use the kconf.syms dictionary.
88 make scriptconfig SCRIPT=<script> [SCRIPT_ARG=<arg>]
89 ----------------------------------------------------
91 This target runs the Python script given by the SCRIPT parameter on the
92 configuration. sys.argv[1] holds the name of the top-level Kconfig file
93 (currently always "Kconfig" in practice), and sys.argv[2] holds the SCRIPT_ARG
96 See the examples/ subdirectory for example scripts.
102 This target prints a list of all environment variables referenced from the
103 Kconfig files, together with their values. See the
104 Kconfiglib/examples/dumpvars.py script.
106 Only environment variables that are referenced via the Kconfig preprocessor
107 $(FOO) syntax are included. The preprocessor was added in Linux 4.18.
110 Using Kconfiglib without the Makefile targets
111 =============================================
113 The make targets are only needed to pick up environment variables exported from
114 the Kbuild makefiles and referenced inside Kconfig files, via e.g.
115 'source "arch/$(SRCARCH)/Kconfig" and commands run via '$(shell,...)'.
117 These variables are referenced as of writing (Linux 4.18), together with sample
123 KERNELVERSION (4.18.0)
127 CC_VERSION_TEXT (gcc (Ubuntu 7.3.0-16ubuntu3) 7.3.0)
129 Older kernels only reference ARCH, SRCARCH, and KERNELVERSION.
131 If your kernel is recent enough (4.18+), you can get a list of referenced
132 environment variables via 'make dumpvarsconfig' (see above). Note that this
133 command is added by the Makefile patch.
135 To run Kconfiglib without the Makefile patch, set the environment variables
138 $ srctree=. ARCH=x86 SRCARCH=x86 KERNELVERSION=`make kernelversion` ... python(3)
139 >>> import kconfiglib
140 >>> kconf = kconfiglib.Kconfig() # filename defaults to "Kconfig"
142 Search the top-level Makefile for "Additional ARCH settings" to see other
143 possibilities for ARCH and SRCARCH.
146 Intro to symbol values
147 ======================
149 Kconfiglib has the same assignment semantics as the C implementation.
151 Any symbol can be assigned a value by the user (via Kconfig.load_config() or
152 Symbol.set_value()), but this user value is only respected if the symbol is
153 visible, which corresponds to it (currently) being visible in the menuconfig
156 For symbols with prompts, the visibility of the symbol is determined by the
157 condition on the prompt. Symbols without prompts are never visible, so setting
158 a user value on them is pointless. A warning will be printed by default if
159 Symbol.set_value() is called on a promptless symbol. Assignments to promptless
160 symbols are normal within a .config file, so no similar warning will be printed
163 Dependencies from parents and 'if'/'depends on' are propagated to properties,
164 including prompts, so these two configurations are logically equivalent:
188 tristate "foo" if A && B && C && D
189 default y if A && B && C
193 In this example, A && B && C && D (the prompt condition) needs to be non-n for
194 FOO to be visible (assignable). If its value is m, the symbol can only be
195 assigned the value m: The visibility sets an upper bound on the value that can
196 be assigned by the user, and any higher user value will be truncated down.
198 'default' properties are independent of the visibility, though a 'default' will
199 often get the same condition as the prompt due to dependency propagation.
200 'default' properties are used if the symbol is not visible or has no user
203 Symbols with no user value (or that have a user value but are not visible) and
204 no (active) 'default' default to n for bool/tristate symbols, and to the empty
205 string for other symbol types.
207 'select' works similarly to symbol visibility, but sets a lower bound on the
208 value of the symbol. The lower bound is determined by the value of the
209 select*ing* symbol. 'select' does not respect visibility, so non-visible
210 symbols can be forced to a particular (minimum) value by a select as well.
212 For non-bool/tristate symbols, it only matters whether the visibility is n or
213 non-n: m visibility acts the same as y visibility.
215 Conditions on 'default' and 'select' work in mostly intuitive ways. If the
216 condition is n, the 'default' or 'select' is disabled. If it is m, the
217 'default' or 'select' value (the value of the selecting symbol) is truncated
220 When writing a configuration with Kconfig.write_config(), only symbols that are
221 visible, have an (active) default, or are selected will get written out (note
222 that this includes all symbols that would accept user values). Kconfiglib
223 matches the .config format produced by the C implementations down to the
224 character. This eases testing.
226 For a visible bool/tristate symbol FOO with value n, this line is written to
229 # CONFIG_FOO is not set
231 The point is to remember the user n selection (which might differ from the
232 default value the symbol would get), while at the same sticking to the rule
233 that undefined corresponds to n (.config uses Makefile format, making the line
234 above a comment). When the .config file is read back in, this line will be
235 treated the same as the following assignment:
239 In Kconfiglib, the set of (currently) assignable values for a bool/tristate
240 symbol appear in Symbol.assignable. For other symbol types, just check if
241 sym.visibility is non-0 (non-n) to see whether the user value will have an
245 Intro to the menu tree
246 ======================
248 The menu structure, as seen in e.g. menuconfig, is represented by a tree of
249 MenuNode objects. The top node of the configuration corresponds to an implicit
250 top-level menu, the title of which is shown at the top in the standard
251 menuconfig interface. (The title is also available in Kconfig.mainmenu_text in
254 The top node is found in Kconfig.top_node. From there, you can visit child menu
255 nodes by following the 'list' pointer, and any following menu nodes by
256 following the 'next' pointer. Usually, a non-None 'list' pointer indicates a
257 menu or Choice, but menu nodes for symbols can sometimes have a non-None 'list'
258 pointer too due to submenus created implicitly from dependencies.
260 MenuNode.item is either a Symbol or a Choice object, or one of the constants
261 MENU and COMMENT. The prompt of the menu node can be found in MenuNode.prompt,
262 which also holds the title for menus and comments. For Symbol and Choice,
263 MenuNode.help holds the help text (if any, otherwise None).
265 Most symbols will only have a single menu node. A symbol defined in multiple
266 locations will have one menu node for each location. The list of menu nodes for
267 a Symbol or Choice can be found in the Symbol/Choice.nodes attribute.
269 Note that prompts and help texts for symbols and choices are stored in their
270 menu node(s) rather than in the Symbol or Choice objects themselves. This makes
271 it possible to define a symbol in multiple locations with a different prompt or
272 help text in each location. To get the help text or prompt for a symbol with a
273 single menu node, do sym.nodes[0].help and sym.nodes[0].prompt, respectively.
274 The prompt is a (text, condition) tuple, where condition determines the
275 visibility (see 'Intro to expressions' below).
277 This organization mirrors the C implementation. MenuNode is called
278 'struct menu' there, but I thought "menu" was a confusing name.
280 It is possible to give a Choice a name and define it in multiple locations,
281 hence why Choice.nodes is also a list.
283 As a convenience, the properties added at a particular definition location are
284 available on the MenuNode itself, in e.g. MenuNode.defaults. This is helpful
285 when generating documentation, so that symbols/choices defined in multiple
286 locations can be shown with the correct properties at each location.
292 Expressions can be evaluated with the expr_value() function and printed with
293 the expr_str() function (these are used internally as well). Evaluating an
294 expression always yields a tristate value, where n, m, and y are represented as
295 0, 1, and 2, respectively.
297 The following table should help you figure out how expressions are represented.
298 A, B, C, ... are symbols (Symbol instances), NOT is the kconfiglib.NOT
301 Expression Representation
302 ---------- --------------
304 "A" A (constant symbol)
307 A && B && C (AND, A, (AND, B, C))
309 A || (B && C && D) (OR, A, (AND, B, (AND, C, D)))
311 A != "foo" (UNEQUAL, A, foo (constant symbol))
312 A && B = C && D (AND, A, (AND, (EQUAL, B, C), D))
313 n Kconfig.n (constant symbol)
314 m Kconfig.m (constant symbol)
315 y Kconfig.y (constant symbol)
316 "y" Kconfig.y (constant symbol)
318 Strings like "foo" in 'default "foo"' or 'depends on SYM = "foo"' are
319 represented as constant symbols, so the only values that appear in expressions
320 are symbols***. This mirrors the C implementation.
322 ***For choice symbols, the parent Choice will appear in expressions as well,
323 but it's usually invisible as the value interfaces of Symbol and Choice are
324 identical. This mirrors the C implementation and makes different choice modes
327 Manual evaluation examples:
329 - The value of A && B is min(A.tri_value, B.tri_value)
331 - The value of A || B is max(A.tri_value, B.tri_value)
333 - The value of !A is 2 - A.tri_value
335 - The value of A = B is 2 (y) if A.str_value == B.str_value, and 0 (n)
336 otherwise. Note that str_value is used here instead of tri_value.
338 For constant (as well as undefined) symbols, str_value matches the name of
339 the symbol. This mirrors the C implementation and explains why
340 'depends on SYM = "foo"' above works as expected.
342 n/m/y are automatically converted to the corresponding constant symbols
343 "n"/"m"/"y" (Kconfig.n/m/y) during parsing.
345 Kconfig.const_syms is a dictionary like Kconfig.syms but for constant symbols.
347 If a condition is missing (e.g., <cond> when the 'if <cond>' is removed from
348 'default A if <cond>'), it is actually Kconfig.y. The standard __str__()
349 functions just avoid printing 'if y' conditions to give cleaner output.
355 Kconfiglib includes a couple of Kconfig extensions:
357 'source' with relative path
358 ---------------------------
360 The 'rsource' statement sources Kconfig files with a path relative to directory
361 of the Kconfig file containing the 'rsource' statement, instead of relative to
364 Consider following directory tree:
378 In this example, assume that src/SubSystem1/Kconfig wants to source
379 src/SubSystem1/ModuleA/Kconfig.
381 With 'source', this statement would be used:
383 source "src/SubSystem1/ModuleA/Kconfig"
385 With 'rsource', this turns into
387 rsource "ModuleA/Kconfig"
389 If an absolute path is given to 'rsource', it acts the same as 'source'.
391 'rsource' can be used to create "position-independent" Kconfig trees that can
392 be moved around freely.
398 'source' and 'rsource' accept glob patterns, sourcing all matching Kconfig
399 files. They require at least one matching file, raising a KconfigError
402 For example, the following statement might source sub1/foofoofoo and
405 source "sub[12]/foo*foo"
407 The glob patterns accepted are the same as for the standard glob.glob()
410 Two additional statements are provided for cases where it's acceptable for a
411 pattern to match no files: 'osource' and 'orsource' (the o is for "optional").
413 For example, the following statements will be no-ops if neither "foo" nor any
414 files matching "bar*" exist:
419 'orsource' does a relative optional source.
421 'source' and 'osource' are analogous to 'include' and '-include' in Make.
424 Generalized def_* keywords
425 --------------------------
427 def_int, def_hex, and def_string are available in addition to def_bool and
428 def_tristate, allowing int, hex, and string symbols to be given a type and a
429 default at the same time.
432 Extra optional warnings
433 -----------------------
435 Some optional warnings can be controlled via environment variables:
437 - KCONFIG_WARN_UNDEF: If set to 'y', warnings will be generated for all
438 references to undefined symbols within Kconfig files. The only gotcha is
439 that all hex literals must be prefixed with "0x" or "0X", to make it
440 possible to distinguish them from symbol references.
442 Some projects (e.g. the Linux kernel) use multiple Kconfig trees with many
443 shared Kconfig files, leading to some safe undefined symbol references.
444 KCONFIG_WARN_UNDEF is useful in projects that only have a single Kconfig
447 KCONFIG_STRICT is an older alias for this environment variable, supported
448 for backwards compatibility.
450 - KCONFIG_WARN_UNDEF_ASSIGN: If set to 'y', warnings will be generated for
451 all assignments to undefined symbols within .config files. By default, no
452 such warnings are generated.
454 This warning can also be enabled/disabled via the Kconfig.warn_assign_undef
458 Preprocessor user functions defined in Python
459 ---------------------------------------------
461 Preprocessor functions can be defined in Python, which makes it simple to
462 integrate information from existing Python tools into Kconfig (e.g. to have
463 Kconfig symbols depend on hardware information stored in some other format).
465 Putting a Python module named kconfigfunctions(.py) anywhere in sys.path will
466 cause it to be imported by Kconfiglib (in Kconfig.__init__()). Note that
467 sys.path can be customized via PYTHONPATH, and includes the directory of the
468 module being run by default, as well as installation directories.
470 If the KCONFIG_FUNCTIONS environment variable is set, it gives a different
471 module name to use instead of 'kconfigfunctions'.
473 The imported module is expected to define a global dictionary named 'functions'
474 that maps function names to Python functions, as follows:
476 def my_fn(kconf, name, arg_1, arg_2, ...):
481 # Name of the user-defined function ("my-fn"). Think argv[0].
484 # Arguments passed to the function from Kconfig (strings)
486 # Returns a string to be substituted as the result of calling the
490 def my_other_fn(kconf, name, arg_1, arg_2, ...):
494 "my-fn": (my_fn, <min.args>, <max.args>/None),
495 "my-other-fn": (my_other_fn, <min.args>, <max.args>/None),
501 <min.args> and <max.args> are the minimum and maximum number of arguments
502 expected by the function (excluding the implicit 'name' argument). If
503 <max.args> is None, there is no upper limit to the number of arguments. Passing
504 an invalid number of arguments will generate a KconfigError exception.
506 Functions can access the current parsing location as kconf.filename/linenr.
507 Accessing other fields of the Kconfig object is not safe. See the warning
510 Keep in mind that for a variable defined like 'foo = $(fn)', 'fn' will be
511 called only when 'foo' is expanded. If 'fn' uses the parsing location and the
512 intent is to use the location of the assignment, you want 'foo := $(fn)'
513 instead, which calls the function immediately.
515 Once defined, user functions can be called from Kconfig in the same way as
516 other preprocessor functions:
520 depends on $(my-fn,arg1,arg2)
522 If my_fn() returns "n", this will result in
531 User-defined preprocessor functions are called as they're encountered at parse
532 time, before all Kconfig files have been processed, and before the menu tree
533 has been finalized. There are no guarantees that accessing Kconfig symbols or
534 the menu tree via the 'kconf' parameter will work, and it could potentially
537 Preferably, user-defined functions should be stateless.
543 Send bug reports, suggestions, and questions to ulfalizer a.t Google's email
544 service, or open a ticket on the GitHub page.
552 # Get rid of some attribute lookups. These are obvious in context.
553 from glob import iglob
554 from os.path import dirname, exists, expandvars, islink, join, realpath
557 VERSION = (12, 14, 0)
567 # Line length: 79 columns
575 class Kconfig(object):
577 Represents a Kconfig configuration, e.g. for x86 or ARM. This is the set of
578 symbols, choices, and menu nodes appearing in the configuration. Creating
579 any number of Kconfig objects (including for different architectures) is
580 safe. Kconfiglib doesn't keep any global state.
582 The following attributes are available. They should be treated as
583 read-only, and some are implemented through @property magic.
586 A dictionary with all symbols in the configuration, indexed by name. Also
587 includes all symbols that are referenced in expressions but never
588 defined, except for constant (quoted) symbols.
590 Undefined symbols can be recognized by Symbol.nodes being empty -- see
591 the 'Intro to the menu tree' section in the module docstring.
594 A dictionary like 'syms' for constant (quoted) symbols
597 A dictionary like 'syms' for named choices (choice FOO)
600 A list with all defined symbols, in the same order as they appear in the
601 Kconfig files. Symbols defined in multiple locations appear multiple
604 Note: You probably want to use 'unique_defined_syms' instead. This
605 attribute is mostly maintained for backwards compatibility.
608 A list like 'defined_syms', but with duplicates removed. Just the first
609 instance is kept for symbols defined in multiple locations. Kconfig order
610 is preserved otherwise.
612 Using this attribute instead of 'defined_syms' can save work, and
613 automatically gives reasonable behavior when writing configuration output
614 (symbols defined in multiple locations only generate output once, while
615 still preserving Kconfig order for readability).
618 A list with all choices, in the same order as they appear in the Kconfig
621 Note: You probably want to use 'unique_choices' instead. This attribute
622 is mostly maintained for backwards compatibility.
625 Analogous to 'unique_defined_syms', for choices. Named choices can have
626 multiple definition locations.
629 A list with all menus, in the same order as they appear in the Kconfig
633 A list with all comments, in the same order as they appear in the Kconfig
637 A list with the filenames of all Kconfig files included in the
638 configuration, relative to $srctree (or relative to the current directory
639 if $srctree isn't set), except absolute paths (e.g.
640 'source "/foo/Kconfig"') are kept as-is.
642 The files are listed in the order they are source'd, starting with the
643 top-level Kconfig file. If a file is source'd multiple times, it will
644 appear multiple times. Use set() to get unique filenames.
646 Note that Kconfig.sync_deps() already indirectly catches any file
647 modifications that change configuration output.
650 A set() with the names of all environment variables referenced in the
653 Only environment variables referenced with the preprocessor $(FOO) syntax
654 will be registered. The older $FOO syntax is only supported for backwards
657 Also note that $(FOO) won't be registered unless the environment variable
658 $FOO is actually set. If it isn't, $(FOO) is an expansion of an unset
659 preprocessor variable (which gives the empty string).
661 Another gotcha is that environment variables referenced in the values of
662 recursively expanded preprocessor variables (those defined with =) will
663 only be registered if the variable is actually used (expanded) somewhere.
665 The note from the 'kconfig_filenames' documentation applies here too.
668 The predefined constant symbols n/m/y. Also available in const_syms.
671 The Symbol instance for the modules symbol. Currently hardcoded to
672 MODULES, which is backwards compatible. Kconfiglib will warn if
673 'option modules' is set on some other symbol. Tell me if you need proper
674 'option modules' support.
676 'modules' is never None. If the MODULES symbol is not explicitly defined,
677 its tri_value will be 0 (n), as expected.
679 A simple way to enable modules is to do 'kconf.modules.set_value(2)'
680 (provided the MODULES symbol is defined and visible). Modules are
681 disabled by default in the kernel Kconfig files as of writing, though
682 nearly all defconfig files enable them (with 'CONFIG_MODULES=y').
685 The Symbol instance for the 'option defconfig_list' symbol, or None if no
686 defconfig_list symbol exists. The defconfig filename derived from this
687 symbol can be found in Kconfig.defconfig_filename.
690 The filename given by the defconfig_list symbol. This is taken from the
691 first 'default' with a satisfied condition where the specified file
692 exists (can be opened for reading). If a defconfig file foo/defconfig is
693 not found and $srctree was set when the Kconfig was created,
694 $srctree/foo/defconfig is looked up as well.
696 'defconfig_filename' is None if either no defconfig_list symbol exists,
697 or if the defconfig_list symbol has no 'default' with a satisfied
698 condition that specifies a file that exists.
700 Gotcha: scripts/kconfig/Makefile might pass --defconfig=<defconfig> to
701 scripts/kconfig/conf when running e.g. 'make defconfig'. This option
702 overrides the defconfig_list symbol, meaning defconfig_filename might not
703 always match what 'make defconfig' would use.
706 The menu node (see the MenuNode class) of the implicit top-level menu.
707 Acts as the root of the menu tree.
710 The prompt (title) of the top menu (top_node). Defaults to "Main menu".
711 Can be changed with the 'mainmenu' statement (see kconfig-language.txt).
714 A dictionary with all preprocessor variables, indexed by name. See the
718 Set this variable to True/False to enable/disable warnings. See
721 When 'warn' is False, the values of the other warning-related variables
724 This variable as well as the other warn* variables can be read to check
725 the current warning settings.
728 Set this variable to True/False to enable/disable warnings on stderr. See
732 Set this variable to True to generate warnings for assignments to
733 undefined symbols in configuration files.
735 This variable is False by default unless the KCONFIG_WARN_UNDEF_ASSIGN
736 environment variable was set to 'y' when the Kconfig instance was
739 warn_assign_override:
740 Set this variable to True to generate warnings for multiple assignments
741 to the same symbol in configuration files, where the assignments set
742 different values (e.g. CONFIG_FOO=m followed by CONFIG_FOO=y, where the
743 last value would get used).
745 This variable is True by default. Disabling it might be useful when
746 merging configurations.
749 Like warn_assign_override, but for multiple assignments setting a symbol
752 This variable is True by default. Disabling it might be useful when
753 merging configurations.
756 A list of strings containing all warnings that have been generated, for
757 cases where more flexibility is needed.
759 See the 'warn_to_stderr' parameter to Kconfig.__init__() and the
760 Kconfig.warn_to_stderr variable as well. Note that warnings still get
761 added to Kconfig.warnings when 'warn_to_stderr' is True.
763 Just as for warnings printed to stderr, only warnings that are enabled
764 will get added to Kconfig.warnings. See the various Kconfig.warn*
768 A list with (name, value) tuples for all assignments to undefined symbols
769 within the most recently loaded .config file(s). 'name' is the symbol
770 name without the 'CONFIG_' prefix. 'value' is a string that gives the
771 right-hand side of the assignment verbatim.
773 See Kconfig.load_config() as well.
776 The value of the $srctree environment variable when the configuration was
777 loaded, or the empty string if $srctree wasn't set. This gives nice
778 behavior with os.path.join(), which treats "" as the current directory,
781 Kconfig files are looked up relative to $srctree (unless absolute paths
782 are used), and .config files are looked up relative to $srctree if they
783 are not found in the current directory. This is used to support
784 out-of-tree builds. The C tools use this environment variable in the same
787 Changing $srctree after creating the Kconfig instance has no effect. Only
788 the value when the configuration is loaded matters. This avoids surprises
789 if multiple configurations are loaded with different values for $srctree.
792 The value of the $CONFIG_ environment variable when the configuration was
793 loaded. This is the prefix used (and expected) on symbol names in .config
794 files and C headers. Defaults to "CONFIG_". Used in the same way in the C
797 Like for srctree, only the value of $CONFIG_ when the configuration is
801 The current parsing location, for use in Python preprocessor functions.
802 See the module docstring.
810 "_warn_assign_no_prompt",
829 "unique_defined_syms",
832 "warn_assign_override",
856 def __init__(self, filename="Kconfig", warn=True, warn_to_stderr=True,
859 Creates a new Kconfig object by parsing Kconfig files.
860 Note that Kconfig files are not the same as .config files (which store
861 configuration symbol values).
863 See the module docstring for some environment variables that influence
864 default warning settings (KCONFIG_WARN_UNDEF and
865 KCONFIG_WARN_UNDEF_ASSIGN).
867 Raises KconfigError on syntax/semantic errors, and OSError or (possibly
868 a subclass of) IOError on IO errors ('errno', 'strerror', and
869 'filename' are available). Note that IOError is an alias for OSError on
870 Python 3, so it's enough to catch OSError there. If you need Python 2/3
871 compatibility, it's easiest to catch EnvironmentError, which is a
872 common base class of OSError/IOError on Python 2 and an alias for
875 filename (default: "Kconfig"):
876 The Kconfig file to load. For the Linux kernel, you'll want "Kconfig"
877 from the top-level directory, as environment variables will make sure
878 the right Kconfig is included from there (arch/$SRCARCH/Kconfig as of
881 If $srctree is set, 'filename' will be looked up relative to it.
882 $srctree is also used to look up source'd files within Kconfig files.
883 See the class documentation.
885 If you are using Kconfiglib via 'make scriptconfig', the filename of
886 the base base Kconfig file will be in sys.argv[1]. It's currently
887 always "Kconfig" in practice.
889 warn (default: True):
890 True if warnings related to this configuration should be generated.
891 This can be changed later by setting Kconfig.warn to True/False. It
892 is provided as a constructor argument since warnings might be
893 generated during parsing.
895 See the other Kconfig.warn_* variables as well, which enable or
896 suppress certain warnings when warnings are enabled.
898 All generated warnings are added to the Kconfig.warnings list. See
899 the class documentation.
901 warn_to_stderr (default: True):
902 True if warnings should be printed to stderr in addition to being
903 added to Kconfig.warnings.
905 This can be changed later by setting Kconfig.warn_to_stderr to
908 encoding (default: "utf-8"):
909 The encoding to use when reading and writing files, and when decoding
910 output from commands run via $(shell). If None, the encoding
911 specified in the current locale will be used.
913 The "utf-8" default avoids exceptions on systems that are configured
914 to use the C locale, which implies an ASCII encoding.
916 This parameter has no effect on Python 2, due to implementation
917 issues (regular strings turning into Unicode strings, which are
918 distinct in Python 2). Python 2 doesn't decode regular strings
921 Related PEP: https://www.python.org/dev/peps/pep-0538/
923 self._encoding = encoding
925 self.srctree = os.getenv("srctree", "")
926 # A prefix we can reliably strip from glob() results to get a filename
927 # relative to $srctree. relpath() can cause issues for symlinks,
928 # because it assumes symlink/../foo is the same as foo/.
929 self._srctree_prefix = realpath(self.srctree) + os.sep
932 self.warn_to_stderr = warn_to_stderr
933 self.warn_assign_undef = os.getenv("KCONFIG_WARN_UNDEF_ASSIGN") == "y"
934 self.warn_assign_override = True
935 self.warn_assign_redun = True
936 self._warn_assign_no_prompt = True
940 self.config_prefix = os.getenv("CONFIG_", "CONFIG_")
941 # Regular expressions for parsing .config files
942 self._set_match = _re_match(self.config_prefix + r"([^=]+)=(.*)")
943 self._unset_match = _re_match(r"# {}([^ ]+) is not set".format(
948 self.defined_syms = []
949 self.missing_syms = []
950 self.named_choices = {}
955 for nmy in "n", "m", "y":
959 sym.is_constant = True
960 sym.orig_type = TRISTATE
961 sym._cached_tri_val = STR_TO_TRI[nmy]
963 self.const_syms[nmy] = sym
965 self.n = self.const_syms["n"]
966 self.m = self.const_syms["m"]
967 self.y = self.const_syms["y"]
969 # Make n/m/y well-formed symbols
970 for nmy in "n", "m", "y":
971 sym = self.const_syms[nmy]
972 sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n
974 # Maps preprocessor variables names to Variable instances
977 # Predefined preprocessor functions, with min/max number of arguments
979 "info": (_info_fn, 1, 1),
980 "error-if": (_error_if_fn, 2, 2),
981 "filename": (_filename_fn, 0, 0),
982 "lineno": (_lineno_fn, 0, 0),
983 "shell": (_shell_fn, 1, 1),
984 "warning-if": (_warning_if_fn, 2, 2),
987 # Add any user-defined preprocessor functions
989 self._functions.update(
990 importlib.import_module(
991 os.getenv("KCONFIG_FUNCTIONS", "kconfigfunctions")
996 # This determines whether previously unseen symbols are registered.
997 # They shouldn't be if we parse expressions after parsing, as part of
998 # Kconfig.eval_string().
999 self._parsing_kconfigs = True
1001 self.modules = self._lookup_sym("MODULES")
1002 self.defconfig_list = None
1004 self.top_node = MenuNode()
1005 self.top_node.kconfig = self
1006 self.top_node.item = MENU
1007 self.top_node.is_menuconfig = True
1008 self.top_node.visibility = self.y
1009 self.top_node.prompt = ("Main menu", self.y)
1010 self.top_node.parent = None
1011 self.top_node.dep = self.y
1012 self.top_node.filename = filename
1013 self.top_node.linenr = 1
1014 self.top_node.include_path = ()
1016 # Parse the Kconfig files
1018 # Not used internally. Provided as a convenience.
1019 self.kconfig_filenames = [filename]
1020 self.env_vars = set()
1022 # Keeps track of the location in the parent Kconfig files. Kconfig
1023 # files usually source other Kconfig files. See _enter_file().
1024 self._filestack = []
1025 self._include_path = ()
1027 # The current parsing location
1028 self.filename = filename
1031 # Used to avoid retokenizing lines when we discover that they're not
1032 # part of the construct currently being parsed. This is kinda like an
1034 self._reuse_tokens = False
1036 # Open the top-level Kconfig file. Store the readline() method directly
1037 # as a small optimization.
1038 self._readline = self._open(join(self.srctree, filename), "r").readline
1041 # Parse the Kconfig files
1042 self._parse_block(None, self.top_node, self.top_node)
1043 self.top_node.list = self.top_node.next
1044 self.top_node.next = None
1045 except UnicodeDecodeError as e:
1046 _decoding_error(e, self.filename)
1048 # Close the top-level Kconfig file. __self__ fetches the 'file' object
1050 self._readline.__self__.close()
1052 self._parsing_kconfigs = False
1054 # Do various menu tree post-processing
1055 self._finalize_node(self.top_node, self.y)
1057 self.unique_defined_syms = _ordered_unique(self.defined_syms)
1058 self.unique_choices = _ordered_unique(self.choices)
1060 # Do sanity checks. Some of these depend on everything being finalized.
1061 self._check_sym_sanity()
1062 self._check_choice_sanity()
1064 # KCONFIG_STRICT is an older alias for KCONFIG_WARN_UNDEF, supported
1065 # for backwards compatibility
1066 if os.getenv("KCONFIG_WARN_UNDEF") == "y" or \
1067 os.getenv("KCONFIG_STRICT") == "y":
1069 self._check_undef_syms()
1071 # Build Symbol._dependents for all symbols and choices
1074 # Check for dependency loops
1075 check_dep_loop_sym = _check_dep_loop_sym # Micro-optimization
1076 for sym in self.unique_defined_syms:
1077 check_dep_loop_sym(sym, False)
1079 # Add extra dependencies from choices to choice symbols that get
1080 # awkward during dependency loop detection
1081 self._add_choice_deps()
1084 def mainmenu_text(self):
1086 See the class documentation.
1088 return self.top_node.prompt[0]
1091 def defconfig_filename(self):
1093 See the class documentation.
1095 if self.defconfig_list:
1096 for filename, cond in self.defconfig_list.defaults:
1097 if expr_value(cond):
1099 with self._open_config(filename.str_value) as f:
1101 except EnvironmentError:
1106 def load_config(self, filename=None, replace=True, verbose=None):
1108 Loads symbol values from a file in the .config format. Equivalent to
1109 calling Symbol.set_value() to set each of the values.
1111 "# CONFIG_FOO is not set" within a .config file sets the user value of
1112 FOO to n. The C tools work the same way.
1114 For each symbol, the Symbol.user_value attribute holds the value the
1115 symbol was assigned in the .config file (if any). The user value might
1116 differ from Symbol.str/tri_value if there are unsatisfied dependencies.
1118 Calling this function also updates the Kconfig.missing_syms attribute
1119 with a list of all assignments to undefined symbols within the
1120 configuration file. Kconfig.missing_syms is cleared if 'replace' is
1121 True, and appended to otherwise. See the documentation for
1122 Kconfig.missing_syms as well.
1124 See the Kconfig.__init__() docstring for raised exceptions
1125 (OSError/IOError). KconfigError is never raised here.
1127 filename (default: None):
1128 Path to load configuration from (a string). Respects $srctree if set
1129 (see the class documentation).
1131 If 'filename' is None (the default), the configuration file to load
1132 (if any) is calculated automatically, giving the behavior you'd
1135 1. If the KCONFIG_CONFIG environment variable is set, it gives the
1136 path to the configuration file to load. Otherwise, ".config" is
1137 used. See standard_config_filename().
1139 2. If the path from (1.) doesn't exist, the configuration file
1140 given by kconf.defconfig_filename is loaded instead, which is
1141 derived from the 'option defconfig_list' symbol.
1143 3. If (1.) and (2.) fail to find a configuration file to load, no
1144 configuration file is loaded, and symbols retain their current
1145 values (e.g., their default values). This is not an error.
1147 See the return value as well.
1149 replace (default: True):
1150 If True, all existing user values will be cleared before loading the
1151 .config. Pass False to merge configurations.
1153 verbose (default: None):
1154 Limited backwards compatibility to prevent crashes. A warning is
1155 printed if anything but None is passed.
1157 Prior to Kconfiglib 12.0.0, this option enabled printing of messages
1158 to stdout when 'filename' was None. A message is (always) returned
1159 now instead, which is more flexible.
1161 Will probably be removed in some future version.
1163 Returns a string with a message saying which file got loaded (or
1164 possibly that no file got loaded, when 'filename' is None). This is
1165 meant to reduce boilerplate in tools, which can do e.g.
1166 print(kconf.load_config()). The returned message distinguishes between
1167 loading (replace == True) and merging (replace == False).
1169 if verbose is not None:
1170 _warn_verbose_deprecated("load_config")
1173 if filename is None:
1174 filename = standard_config_filename()
1175 if not exists(filename) and \
1176 not exists(join(self.srctree, filename)):
1177 defconfig = self.defconfig_filename
1178 if defconfig is None:
1179 return "Using default symbol values (no '{}')" \
1182 msg = " default configuration '{}' (no '{}')" \
1183 .format(defconfig, filename)
1184 filename = defconfig
1187 msg = " configuration '{}'".format(filename)
1189 # Disable the warning about assigning to symbols without prompts. This
1190 # is normal and expected within a .config file.
1191 self._warn_assign_no_prompt = False
1193 # This stub only exists to make sure _warn_assign_no_prompt gets
1196 self._load_config(filename, replace)
1197 except UnicodeDecodeError as e:
1198 _decoding_error(e, filename)
1200 self._warn_assign_no_prompt = True
1202 return ("Loaded" if replace else "Merged") + msg
1204 def _load_config(self, filename, replace):
1205 with self._open_config(filename) as f:
1207 self.missing_syms = []
1209 # If we're replacing the configuration, keep track of which
1210 # symbols and choices got set so that we can unset the rest
1211 # later. This avoids invalidating everything and is faster.
1212 # Another benefit is that invalidation must be rock solid for
1213 # it to work, making it a good test.
1215 for sym in self.unique_defined_syms:
1216 sym._was_set = False
1218 for choice in self.unique_choices:
1219 choice._was_set = False
1221 # Small optimizations
1222 set_match = self._set_match
1223 unset_match = self._unset_match
1224 get_sym = self.syms.get
1226 for linenr, line in enumerate(f, 1):
1227 # The C tools ignore trailing whitespace
1228 line = line.rstrip()
1230 match = set_match(line)
1232 name, val = match.groups()
1234 if not sym or not sym.nodes:
1235 self._undef_assign(name, val, filename, linenr)
1238 if sym.orig_type in _BOOL_TRISTATE:
1239 # The C implementation only checks the first character
1240 # to the right of '=', for whatever reason
1241 if not (sym.orig_type is BOOL
1242 and val.startswith(("y", "n")) or
1243 sym.orig_type is TRISTATE
1244 and val.startswith(("y", "m", "n"))):
1245 self._warn("'{}' is not a valid value for the {} "
1246 "symbol {}. Assignment ignored."
1247 .format(val, TYPE_TO_STR[sym.orig_type],
1248 _name_and_loc(sym)),
1254 if sym.choice and val != "n":
1255 # During .config loading, we infer the mode of the
1256 # choice from the kind of values that are assigned
1257 # to the choice symbols
1259 prev_mode = sym.choice.user_value
1260 if prev_mode is not None and \
1261 TRI_TO_STR[prev_mode] != val:
1263 self._warn("both m and y assigned to symbols "
1264 "within the same choice",
1267 # Set the choice's mode
1268 sym.choice.set_value(val)
1270 elif sym.orig_type is STRING:
1271 match = _conf_string_match(val)
1273 self._warn("malformed string literal in "
1274 "assignment to {}. Assignment ignored."
1275 .format(_name_and_loc(sym)),
1279 val = unescape(match.group(1))
1282 match = unset_match(line)
1284 # Print a warning for lines that match neither
1285 # set_match() nor unset_match() and that are not blank
1286 # lines or comments. 'line' has already been
1287 # rstrip()'d, so blank lines show up as "" here.
1288 if line and not line.lstrip().startswith("#"):
1289 self._warn("ignoring malformed line '{}'"
1295 name = match.group(1)
1297 if not sym or not sym.nodes:
1298 self._undef_assign(name, "n", filename, linenr)
1301 if sym.orig_type not in _BOOL_TRISTATE:
1306 # Done parsing the assignment. Set the value.
1309 self._assigned_twice(sym, val, filename, linenr)
1314 # If we're replacing the configuration, unset the symbols that
1317 for sym in self.unique_defined_syms:
1318 if not sym._was_set:
1321 for choice in self.unique_choices:
1322 if not choice._was_set:
1323 choice.unset_value()
1325 def _undef_assign(self, name, val, filename, linenr):
1326 # Called for assignments to undefined symbols during .config loading
1328 self.missing_syms.append((name, val))
1329 if self.warn_assign_undef:
1331 "attempt to assign the value '{}' to the undefined symbol {}"
1332 .format(val, name), filename, linenr)
1334 def _assigned_twice(self, sym, new_val, filename, linenr):
1335 # Called when a symbol is assigned more than once in a .config file
1337 # Use strings for bool/tristate user values in the warning
1338 if sym.orig_type in _BOOL_TRISTATE:
1339 user_val = TRI_TO_STR[sym.user_value]
1341 user_val = sym.user_value
1343 msg = '{} set more than once. Old value "{}", new value "{}".'.format(
1344 _name_and_loc(sym), user_val, new_val)
1346 if user_val == new_val:
1347 if self.warn_assign_redun:
1348 self._warn(msg, filename, linenr)
1349 elif self.warn_assign_override:
1350 self._warn(msg, filename, linenr)
1352 def write_autoconf(self, filename,
1353 header="/* Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib) */\n"):
1355 Writes out symbol values as a C header file, matching the format used
1356 by include/generated/autoconf.h in the kernel.
1358 The ordering of the #defines matches the one generated by
1359 write_config(). The order in the C implementation depends on the hash
1360 table implementation as of writing, and so won't match.
1362 If 'filename' exists and its contents is identical to what would get
1363 written out, it is left untouched. This avoids updating file metadata
1364 like the modification time and possibly triggering redundant work in
1370 header (default: "/* Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib) */\n"):
1371 Text that will be inserted verbatim at the beginning of the file. You
1372 would usually want it enclosed in '/* */' to make it a C comment,
1373 and include a final terminating newline.
1375 self._write_if_changed(filename, self._autoconf_contents(header))
1377 def _autoconf_contents(self, header):
1378 # write_autoconf() helper. Returns the contents to write as a string,
1379 # with 'header' at the beginning.
1385 for sym in self.unique_defined_syms:
1386 # _write_to_conf is determined when the value is calculated. This
1387 # is a hidden function call due to property magic.
1389 # Note: In client code, you can check if sym.config_string is empty
1390 # instead, to avoid accessing the internal _write_to_conf variable
1391 # (though it's likely to keep working).
1393 if not sym._write_to_conf:
1396 if sym.orig_type in _BOOL_TRISTATE:
1398 add("#define {}{} 1\n"
1399 .format(self.config_prefix, sym.name))
1401 add("#define {}{}_MODULE 1\n"
1402 .format(self.config_prefix, sym.name))
1404 elif sym.orig_type is STRING:
1405 add('#define {}{} "{}"\n'
1406 .format(self.config_prefix, sym.name, escape(val)))
1408 else: # sym.orig_type in _INT_HEX:
1409 if sym.orig_type is HEX and \
1410 not val.startswith(("0x", "0X")):
1413 add("#define {}{} {}\n"
1414 .format(self.config_prefix, sym.name, val))
1416 return "".join(chunks)
1418 def write_config(self, filename=None,
1419 header="# Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib)\n",
1420 save_old=True, verbose=None):
1422 Writes out symbol values in the .config format. The format matches the
1423 C implementation, including ordering.
1425 Symbols appear in the same order in generated .config files as they do
1426 in the Kconfig files. For symbols defined in multiple locations, a
1427 single assignment is written out corresponding to the first location
1428 where the symbol is defined.
1430 See the 'Intro to symbol values' section in the module docstring to
1431 understand which symbols get written out.
1433 If 'filename' exists and its contents is identical to what would get
1434 written out, it is left untouched. This avoids updating file metadata
1435 like the modification time and possibly triggering redundant work in
1438 See the Kconfig.__init__() docstring for raised exceptions
1439 (OSError/IOError). KconfigError is never raised here.
1441 filename (default: None):
1442 Filename to save configuration to (a string).
1444 If None (the default), the filename in the environment variable
1445 KCONFIG_CONFIG is used if set, and ".config" otherwise. See
1446 standard_config_filename().
1448 header (default: "# Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib)\n"):
1449 Text that will be inserted verbatim at the beginning of the file. You
1450 would usually want each line to start with '#' to make it a comment,
1451 and include a final terminating newline.
1453 save_old (default: True):
1454 If True and <filename> already exists, a copy of it will be saved to
1455 <filename>.old in the same directory before the new configuration is
1458 Errors are silently ignored if <filename>.old cannot be written (e.g.
1459 due to being a directory, or <filename> being something like
1462 verbose (default: None):
1463 Limited backwards compatibility to prevent crashes. A warning is
1464 printed if anything but None is passed.
1466 Prior to Kconfiglib 12.0.0, this option enabled printing of messages
1467 to stdout when 'filename' was None. A message is (always) returned
1468 now instead, which is more flexible.
1470 Will probably be removed in some future version.
1472 Returns a string with a message saying which file got saved. This is
1473 meant to reduce boilerplate in tools, which can do e.g.
1474 print(kconf.write_config()).
1476 if verbose is not None:
1477 _warn_verbose_deprecated("write_config")
1479 if filename is None:
1480 filename = standard_config_filename()
1482 contents = self._config_contents(header)
1483 if self._contents_eq(filename, contents):
1484 return "No change to '{}'".format(filename)
1489 with self._open(filename, "w") as f:
1492 return "Configuration saved to '{}'".format(filename)
1494 def _config_contents(self, header):
1495 # write_config() helper. Returns the contents to write as a string,
1496 # with 'header' at the beginning.
1498 # More memory friendly would be to 'yield' the strings and
1499 # "".join(_config_contents()), but it was a bit slower on my system.
1501 # node_iter() was used here before commit 3aea9f7 ("Add '# end of
1502 # <menu>' after menus in .config"). Those comments get tricky to
1503 # implement with it.
1505 for sym in self.unique_defined_syms:
1506 sym._visited = False
1508 # Did we just print an '# end of ...' comment?
1509 after_end_comment = False
1515 node = self.top_node
1517 # Jump to the next node with an iterative tree walk
1526 # Add a comment when leaving visible menus
1527 if node.item is MENU and expr_value(node.dep) and \
1528 expr_value(node.visibility) and \
1529 node is not self.top_node:
1530 add("# end of {}\n".format(node.prompt[0]))
1531 after_end_comment = True
1538 return "".join(chunks)
1540 # Generate configuration output for the node
1544 if item.__class__ is Symbol:
1547 item._visited = True
1549 conf_string = item.config_string
1553 if after_end_comment:
1554 # Add a blank line before the first symbol printed after an
1555 # '# end of ...' comment
1556 after_end_comment = False
1560 elif expr_value(node.dep) and \
1561 ((item is MENU and expr_value(node.visibility)) or
1564 add("\n#\n# {}\n#\n".format(node.prompt[0]))
1565 after_end_comment = False
1567 def write_min_config(self, filename,
1568 header="# Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib)\n"):
1570 Writes out a "minimal" configuration file, omitting symbols whose value
1571 matches their default value. The format matches the one produced by
1572 'make savedefconfig'.
1574 The resulting configuration file is incomplete, but a complete
1575 configuration can be derived from it by loading it. Minimal
1576 configuration files can serve as a more manageable configuration format
1577 compared to a "full" .config file, especially when configurations files
1578 are merged or edited by hand.
1580 See the Kconfig.__init__() docstring for raised exceptions
1581 (OSError/IOError). KconfigError is never raised here.
1586 header (default: "# Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib)\n"):
1587 Text that will be inserted verbatim at the beginning of the file. You
1588 would usually want each line to start with '#' to make it a comment,
1589 and include a final terminating newline.
1591 Returns a string with a message saying which file got saved. This is
1592 meant to reduce boilerplate in tools, which can do e.g.
1593 print(kconf.write_min_config()).
1595 contents = self._min_config_contents(header)
1596 if self._contents_eq(filename, contents):
1597 return "No change to '{}'".format(filename)
1599 with self._open(filename, "w") as f:
1602 return "Minimal configuration saved to '{}'".format(filename)
1604 def _min_config_contents(self, header):
1605 # write_min_config() helper. Returns the contents to write as a string,
1606 # with 'header' at the beginning.
1611 for sym in self.unique_defined_syms:
1612 # Skip symbols that cannot be changed. Only check
1613 # non-choice symbols, as selects don't affect choice
1615 if not sym.choice and \
1616 sym.visibility <= expr_value(sym.rev_dep):
1619 # Skip symbols whose value matches their default
1620 if sym.str_value == sym._str_default():
1623 # Skip symbols that would be selected by default in a
1624 # choice, unless the choice is optional or the symbol type
1625 # isn't bool (it might be possible to set the choice mode
1626 # to n or the symbol to m in those cases).
1628 not sym.choice.is_optional and \
1629 sym.choice._selection_from_defaults() is sym and \
1630 sym.orig_type is BOOL and \
1634 add(sym.config_string)
1636 return "".join(chunks)
1638 def sync_deps(self, path):
1640 Creates or updates a directory structure that can be used to avoid
1641 doing a full rebuild whenever the configuration is changed, mirroring
1642 include/config/ in the kernel.
1644 This function is intended to be called during each build, before
1645 compiling source files that depend on configuration symbols.
1647 See the Kconfig.__init__() docstring for raised exceptions
1648 (OSError/IOError). KconfigError is never raised here.
1653 sync_deps(path) does the following:
1655 1. If the directory <path> does not exist, it is created.
1657 2. If <path>/auto.conf exists, old symbol values are loaded from it,
1658 which are then compared against the current symbol values. If a
1659 symbol has changed value (would generate different output in
1660 autoconf.h compared to before), the change is signaled by
1661 touch'ing a file corresponding to the symbol.
1663 The first time sync_deps() is run on a directory, <path>/auto.conf
1664 won't exist, and no old symbol values will be available. This
1665 logically has the same effect as updating the entire
1668 The path to a symbol's file is calculated from the symbol's name
1669 by replacing all '_' with '/' and appending '.h'. For example, the
1670 symbol FOO_BAR_BAZ gets the file <path>/foo/bar/baz.h, and FOO
1671 gets the file <path>/foo.h.
1673 This scheme matches the C tools. The point is to avoid having a
1674 single directory with a huge number of files, which the underlying
1675 filesystem might not handle well.
1677 3. A new auto.conf with the current symbol values is written, to keep
1678 track of them for the next build.
1680 If auto.conf exists and its contents is identical to what would
1681 get written out, it is left untouched. This avoids updating file
1682 metadata like the modification time and possibly triggering
1683 redundant work in build tools.
1686 The last piece of the puzzle is knowing what symbols each source file
1687 depends on. Knowing that, dependencies can be added from source files
1688 to the files corresponding to the symbols they depends on. The source
1689 file will then get recompiled (only) when the symbol value changes
1690 (provided sync_deps() is run first during each build).
1692 The tool in the kernel that extracts symbol dependencies from source
1693 files is scripts/basic/fixdep.c. Missing symbol files also correspond
1694 to "not changed", which fixdep deals with by using the $(wildcard) Make
1695 function when adding symbol prerequisites to source files.
1697 In case you need a different scheme for your project, the sync_deps()
1698 implementation can be used as a template.
1700 if not exists(path):
1701 os.mkdir(path, 0o755)
1703 # Load old values from auto.conf, if any
1704 self._load_old_vals(path)
1706 for sym in self.unique_defined_syms:
1707 # _write_to_conf is determined when the value is calculated. This
1708 # is a hidden function call due to property magic.
1710 # Note: In client code, you can check if sym.config_string is empty
1711 # instead, to avoid accessing the internal _write_to_conf variable
1712 # (though it's likely to keep working).
1715 # n tristate values do not get written to auto.conf and autoconf.h,
1716 # making a missing symbol logically equivalent to n
1718 if sym._write_to_conf:
1719 if sym._old_val is None and \
1720 sym.orig_type in _BOOL_TRISTATE and \
1722 # No old value (the symbol was missing or n), new value n.
1726 if val == sym._old_val:
1727 # New value matches old. No change.
1730 elif sym._old_val is None:
1731 # The symbol wouldn't appear in autoconf.h (because
1732 # _write_to_conf is false), and it wouldn't have appeared in
1733 # autoconf.h previously either (because it didn't appear in
1734 # auto.conf). No change.
1737 # 'sym' has a new value. Flag it.
1738 _touch_dep_file(path, sym.name)
1740 # Remember the current values as the "new old" values.
1742 # This call could go anywhere after the call to _load_old_vals(), but
1743 # putting it last means _sync_deps() can be safely rerun if it fails
1744 # before this point.
1745 self._write_old_vals(path)
1747 def _load_old_vals(self, path):
1748 # Loads old symbol values from auto.conf into a dedicated
1749 # Symbol._old_val field. Mirrors load_config().
1751 # The extra field could be avoided with some trickery involving dumping
1752 # symbol values and restoring them later, but this is simpler and
1753 # faster. The C tools also use a dedicated field for this purpose.
1755 for sym in self.unique_defined_syms:
1759 auto_conf = self._open(join(path, "auto.conf"), "r")
1760 except EnvironmentError as e:
1761 if e.errno == errno.ENOENT:
1766 with auto_conf as f:
1768 match = self._set_match(line)
1770 # We only expect CONFIG_FOO=... (and possibly a header
1771 # comment) in auto.conf
1774 name, val = match.groups()
1775 if name in self.syms:
1776 sym = self.syms[name]
1778 if sym.orig_type is STRING:
1779 match = _conf_string_match(val)
1782 val = unescape(match.group(1))
1784 self.syms[name]._old_val = val
1786 # Flag that the symbol no longer exists, in
1787 # case something still depends on it
1788 _touch_dep_file(path, name)
1790 def _write_old_vals(self, path):
1791 # Helper for writing auto.conf. Basically just a simplified
1792 # write_config() that doesn't write any comments (including
1793 # '# CONFIG_FOO is not set' comments). The format matches the C
1794 # implementation, though the ordering is arbitrary there (depends on
1795 # the hash table implementation).
1797 # A separate helper function is neater than complicating write_config()
1798 # by passing a flag to it, plus we only need to look at symbols here.
1800 self._write_if_changed(
1801 os.path.join(path, "auto.conf"),
1802 self._old_vals_contents())
1804 def _old_vals_contents(self):
1805 # _write_old_vals() helper. Returns the contents to write as a string.
1807 # Temporary list instead of generator makes this a bit faster
1809 sym.config_string for sym in self.unique_defined_syms
1810 if not (sym.orig_type in _BOOL_TRISTATE and not sym.tri_value)
1813 def node_iter(self, unique_syms=False):
1815 Returns a generator for iterating through all MenuNode's in the Kconfig
1816 tree. The iteration is done in Kconfig definition order (each node is
1817 visited before its children, and the children of a node are visited
1818 before the next node).
1820 The Kconfig.top_node menu node is skipped. It contains an implicit menu
1821 that holds the top-level items.
1823 As an example, the following code will produce a list equal to
1824 Kconfig.defined_syms:
1826 defined_syms = [node.item for node in kconf.node_iter()
1827 if isinstance(node.item, Symbol)]
1829 unique_syms (default: False):
1830 If True, only the first MenuNode will be included for symbols defined
1831 in multiple locations.
1833 Using kconf.node_iter(True) in the example above would give a list
1834 equal to unique_defined_syms.
1837 for sym in self.unique_defined_syms:
1838 sym._visited = False
1840 node = self.top_node
1842 # Jump to the next node with an iterative tree walk
1857 if unique_syms and node.item.__class__ is Symbol:
1858 if node.item._visited:
1860 node.item._visited = True
1864 def eval_string(self, s):
1866 Returns the tristate value of the expression 's', represented as 0, 1,
1867 and 2 for n, m, and y, respectively. Raises KconfigError on syntax
1868 errors. Warns if undefined symbols are referenced.
1870 As an example, if FOO and BAR are tristate symbols at least one of
1871 which has the value y, then eval_string("y && (FOO || BAR)") returns
1874 To get the string value of non-bool/tristate symbols, use
1875 Symbol.str_value. eval_string() always returns a tristate value, and
1876 all non-bool/tristate symbols have the tristate value 0 (n).
1878 The expression parsing is consistent with how parsing works for
1879 conditional ('if ...') expressions in the configuration, and matches
1880 the C implementation. m is rewritten to 'm && MODULES', so
1881 eval_string("m") will return 0 (n) unless modules are enabled.
1883 # The parser is optimized to be fast when parsing Kconfig files (where
1884 # an expression can never appear at the beginning of a line). We have
1885 # to monkey-patch things a bit here to reuse it.
1887 self.filename = None
1889 self._tokens = self._tokenize("if " + s)
1890 # Strip "if " to avoid giving confusing error messages
1892 self._tokens_i = 1 # Skip the 'if' token
1894 return expr_value(self._expect_expr_and_eol())
1896 def unset_values(self):
1898 Removes any user values from all symbols, as if Kconfig.load_config()
1899 or Symbol.set_value() had never been called.
1901 self._warn_assign_no_prompt = False
1903 # set_value() already rejects undefined symbols, and they don't
1904 # need to be invalidated (because their value never changes), so we
1905 # can just iterate over defined symbols
1906 for sym in self.unique_defined_syms:
1909 for choice in self.unique_choices:
1910 choice.unset_value()
1912 self._warn_assign_no_prompt = True
1914 def enable_warnings(self):
1916 Do 'Kconfig.warn = True' instead. Maintained for backwards
1921 def disable_warnings(self):
1923 Do 'Kconfig.warn = False' instead. Maintained for backwards
1928 def enable_stderr_warnings(self):
1930 Do 'Kconfig.warn_to_stderr = True' instead. Maintained for backwards
1933 self.warn_to_stderr = True
1935 def disable_stderr_warnings(self):
1937 Do 'Kconfig.warn_to_stderr = False' instead. Maintained for backwards
1940 self.warn_to_stderr = False
1942 def enable_undef_warnings(self):
1944 Do 'Kconfig.warn_assign_undef = True' instead. Maintained for backwards
1947 self.warn_assign_undef = True
1949 def disable_undef_warnings(self):
1951 Do 'Kconfig.warn_assign_undef = False' instead. Maintained for
1952 backwards compatibility.
1954 self.warn_assign_undef = False
1956 def enable_override_warnings(self):
1958 Do 'Kconfig.warn_assign_override = True' instead. Maintained for
1959 backwards compatibility.
1961 self.warn_assign_override = True
1963 def disable_override_warnings(self):
1965 Do 'Kconfig.warn_assign_override = False' instead. Maintained for
1966 backwards compatibility.
1968 self.warn_assign_override = False
1970 def enable_redun_warnings(self):
1972 Do 'Kconfig.warn_assign_redun = True' instead. Maintained for backwards
1975 self.warn_assign_redun = True
1977 def disable_redun_warnings(self):
1979 Do 'Kconfig.warn_assign_redun = False' instead. Maintained for
1980 backwards compatibility.
1982 self.warn_assign_redun = False
1986 Returns a string with information about the Kconfig object when it is
1987 evaluated on e.g. the interactive Python prompt.
1990 return "enabled" if flag else "disabled"
1992 return "<{}>".format(", ".join((
1993 "configuration with {} symbols".format(len(self.syms)),
1994 'main menu prompt "{}"'.format(self.mainmenu_text),
1995 "srctree is current directory" if not self.srctree else
1996 'srctree "{}"'.format(self.srctree),
1997 'config symbol prefix "{}"'.format(self.config_prefix),
1998 "warnings " + status(self.warn),
1999 "printing of warnings to stderr " + status(self.warn_to_stderr),
2000 "undef. symbol assignment warnings " +
2001 status(self.warn_assign_undef),
2002 "overriding symbol assignment warnings " +
2003 status(self.warn_assign_override),
2004 "redundant symbol assignment warnings " +
2005 status(self.warn_assign_redun)
2017 def _open_config(self, filename):
2018 # Opens a .config file. First tries to open 'filename', then
2019 # '$srctree/filename' if $srctree was set when the configuration was
2023 return self._open(filename, "r")
2024 except EnvironmentError as e:
2025 # This will try opening the same file twice if $srctree is unset,
2026 # but it's not a big deal
2028 return self._open(join(self.srctree, filename), "r")
2029 except EnvironmentError as e2:
2030 # This is needed for Python 3, because e2 is deleted after
2033 # https://docs.python.org/3/reference/compound_stmts.html#the-try-statement
2036 raise _KconfigIOError(
2037 e, "Could not open '{}' ({}: {}). Check that the $srctree "
2038 "environment variable ({}) is set correctly."
2039 .format(filename, errno.errorcode[e.errno], e.strerror,
2040 "set to '{}'".format(self.srctree) if self.srctree
2041 else "unset or blank"))
2043 def _enter_file(self, filename):
2044 # Jumps to the beginning of a sourced Kconfig file, saving the previous
2045 # position and file object.
2048 # Absolute path to file
2050 # Path relative to $srctree, stored in e.g. self.filename (which makes
2051 # it indirectly show up in MenuNode.filename). Equals 'filename' for
2052 # absolute paths passed to 'source'.
2053 if filename.startswith(self._srctree_prefix):
2054 # Relative path (or a redundant absolute path to within $srctree,
2055 # but it's probably fine to reduce those too)
2056 rel_filename = filename[len(self._srctree_prefix):]
2059 rel_filename = filename
2061 self.kconfig_filenames.append(rel_filename)
2063 # The parent Kconfig files are represented as a list of
2064 # (<include path>, <Python 'file' object for Kconfig file>) tuples.
2066 # <include path> is immutable and holds a *tuple* of
2067 # (<filename>, <linenr>) tuples, giving the locations of the 'source'
2068 # statements in the parent Kconfig files. The current include path is
2069 # also available in Kconfig._include_path.
2071 # The point of this redundant setup is to allow Kconfig._include_path
2072 # to be assigned directly to MenuNode.include_path without having to
2073 # copy it, sharing it wherever possible.
2075 # Save include path and 'file' object (via its 'readline' function)
2076 # before entering the file
2077 self._filestack.append((self._include_path, self._readline))
2079 # _include_path is a tuple, so this rebinds the variable instead of
2080 # doing in-place modification
2081 self._include_path += ((self.filename, self.linenr),)
2083 # Check for recursive 'source'
2084 for name, _ in self._include_path:
2085 if name == rel_filename:
2087 "\n{}:{}: recursive 'source' of '{}' detected. Check that "
2088 "environment variables are set correctly.\n"
2090 .format(self.filename, self.linenr, rel_filename,
2091 "\n".join("{}:{}".format(name, linenr)
2092 for name, linenr in self._include_path)))
2095 self._readline = self._open(filename, "r").readline
2096 except EnvironmentError as e:
2097 # We already know that the file exists
2098 raise _KconfigIOError(
2099 e, "{}:{}: Could not open '{}' (in '{}') ({}: {})"
2100 .format(self.filename, self.linenr, filename,
2102 errno.errorcode[e.errno], e.strerror))
2104 self.filename = rel_filename
2107 def _leave_file(self):
2108 # Returns from a Kconfig file to the file that sourced it. See
2111 # Restore location from parent Kconfig file
2112 self.filename, self.linenr = self._include_path[-1]
2113 # Restore include path and 'file' object
2114 self._readline.__self__.close() # __self__ fetches the 'file' object
2115 self._include_path, self._readline = self._filestack.pop()
2117 def _next_line(self):
2118 # Fetches and tokenizes the next line from the current Kconfig file.
2119 # Returns False at EOF and True otherwise.
2121 # We might already have tokens from parsing a line and discovering that
2122 # it's part of a different construct
2123 if self._reuse_tokens:
2124 self._reuse_tokens = False
2125 # self._tokens_i is known to be 1 here, because _parse_properties()
2126 # leaves it like that when it can't recognize a line (or parses
2130 # readline() returns '' over and over at EOF, which we rely on for help
2131 # texts at the end of files (see _line_after_help())
2132 line = self._readline()
2137 # Handle line joining
2138 while line.endswith("\\\n"):
2139 line = line[:-2] + self._readline()
2142 self._tokens = self._tokenize(line)
2143 # Initialize to 1 instead of 0 to factor out code from _parse_block()
2144 # and _parse_properties(). They immediately fetch self._tokens[0].
2149 def _line_after_help(self, line):
2150 # Tokenizes a line after a help text. This case is special in that the
2151 # line has already been fetched (to discover that it isn't part of the
2154 # An earlier version used a _saved_line variable instead that was
2155 # checked in _next_line(). This special-casing gets rid of it and makes
2156 # _reuse_tokens alone sufficient to handle unget.
2158 # Handle line joining
2159 while line.endswith("\\\n"):
2160 line = line[:-2] + self._readline()
2163 self._tokens = self._tokenize(line)
2164 self._reuse_tokens = True
2166 def _write_if_changed(self, filename, contents):
2167 # Writes 'contents' into 'filename', but only if it differs from the
2168 # current contents of the file.
2170 # Another variant would be write a temporary file on the same
2171 # filesystem, compare the files, and rename() the temporary file if it
2172 # differs, but it breaks stuff like write_config("/dev/null"), which is
2173 # used out there to force evaluation-related warnings to be generated.
2174 # This simple version is pretty failsafe and portable.
2176 if not self._contents_eq(filename, contents):
2177 with self._open(filename, "w") as f:
2180 def _contents_eq(self, filename, contents):
2181 # Returns True if the contents of 'filename' is 'contents' (a string),
2182 # and False otherwise (including if 'filename' can't be opened/read)
2185 with self._open(filename, "r") as f:
2186 # Robust re. things like encoding and line endings (mmap()
2188 return f.read(len(contents) + 1) == contents
2189 except EnvironmentError:
2190 # If the error here would prevent writing the file as well, we'll
2198 def _lookup_sym(self, name):
2199 # Fetches the symbol 'name' from the symbol table, creating and
2200 # registering it if it does not exist. If '_parsing_kconfigs' is False,
2201 # it means we're in eval_string(), and new symbols won't be registered.
2203 if name in self.syms:
2204 return self.syms[name]
2209 sym.is_constant = False
2210 sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n
2212 if self._parsing_kconfigs:
2213 self.syms[name] = sym
2215 self._warn("no symbol {} in configuration".format(name))
2219 def _lookup_const_sym(self, name):
2220 # Like _lookup_sym(), for constant (quoted) symbols
2222 if name in self.const_syms:
2223 return self.const_syms[name]
2228 sym.is_constant = True
2229 sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n
2231 if self._parsing_kconfigs:
2232 self.const_syms[name] = sym
2236 def _tokenize(self, s):
2237 # Parses 's', returning a None-terminated list of tokens. Registers any
2238 # new symbols encountered with _lookup(_const)_sym().
2240 # Tries to be reasonably speedy by processing chunks of text via
2241 # regexes and string operations where possible. This is the biggest
2242 # hotspot during parsing.
2244 # It might be possible to rewrite this to 'yield' tokens instead,
2245 # working across multiple lines. Lookback and compatibility with old
2246 # janky versions of the C tools complicate things though.
2248 self._line = s # Used for error reporting
2250 # Initial token on the line
2251 match = _command_match(s)
2253 if s.isspace() or s.lstrip().startswith("#"):
2255 self._parse_error("unknown token at start of line")
2257 # Tricky implementation detail: While parsing a token, 'token' refers
2258 # to the previous token. See _STRING_LEX for why this is needed.
2259 token = _get_keyword(match.group(1))
2261 # Backwards compatibility with old versions of the C tools, which
2262 # (accidentally) accepted stuff like "--help--" and "-help---".
2263 # This was fixed in the C tools by commit c2264564 ("kconfig: warn
2264 # of unhandled characters in Kconfig commands"), committed in July
2265 # 2015, but it seems people still run Kconfiglib on older kernels.
2266 if s.strip(" \t\n-") == "help":
2267 return (_T_HELP, None)
2269 # If the first token is not a keyword (and not a weird help token),
2270 # we have a preprocessor variable assignment (or a bare macro on a
2272 self._parse_assignment(s)
2276 # The current index in the string being tokenized
2279 # Main tokenization loop (for tokens past the first one)
2281 # Test for an identifier/keyword first. This is the most common
2283 match = _id_keyword_match(s, i)
2285 # We have an identifier or keyword
2287 # Check what it is. lookup_sym() will take care of allocating
2288 # new symbols for us the first time we see them. Note that
2289 # 'token' still refers to the previous token.
2291 name = match.group(1)
2292 keyword = _get_keyword(name)
2299 elif token not in _STRING_LEX:
2300 # It's a non-const symbol, except we translate n, m, and y
2301 # into the corresponding constant symbols, like the C
2305 # Macro expansion within symbol name
2306 name, s, i = self._expand_name(s, i)
2310 token = self.const_syms[name] if name in STR_TO_TRI else \
2311 self._lookup_sym(name)
2314 # It's a case of missing quotes. For example, the
2315 # following is accepted:
2317 # menu unquoted_title
2320 # tristate unquoted_prompt
2324 # Named choices ('choice FOO') also end up here.
2326 if token is not _T_CHOICE:
2327 self._warn("style: quotes recommended around '{}' in '{}'"
2328 .format(name, self._line.strip()),
2329 self.filename, self.linenr)
2335 # Neither a keyword nor a non-const symbol
2337 # We always strip whitespace after tokens, so it is safe to
2338 # assume that s[i] is the start of a token here.
2342 if "$" not in s and "\\" not in s:
2343 # Fast path for lines without $ and \. Find the
2345 end_i = s.find(c, i + 1) + 1
2347 self._parse_error("unterminated string")
2348 val = s[i + 1:end_i - 1]
2352 s, end_i = self._expand_str(s, i)
2354 # os.path.expandvars() and the $UNAME_RELEASE replace()
2355 # is a backwards compatibility hack, which should be
2356 # reasonably safe as expandvars() leaves references to
2357 # undefined env. vars. as is.
2359 # The preprocessor functionality changed how
2360 # environment variables are referenced, to $(FOO).
2361 val = expandvars(s[i + 1:end_i - 1]
2362 .replace("$UNAME_RELEASE",
2367 # This is the only place where we don't survive with a
2368 # single token of lookback: 'option env="FOO"' does not
2369 # refer to a constant symbol named "FOO".
2371 val if token in _STRING_LEX or tokens[0] is _T_OPTION \
2372 else self._lookup_const_sym(val)
2374 elif s.startswith("&&", i):
2378 elif s.startswith("||", i):
2386 elif s.startswith("!=", i):
2395 token = _T_OPEN_PAREN
2399 token = _T_CLOSE_PAREN
2408 elif s.startswith("<=", i):
2409 token = _T_LESS_EQUAL
2416 elif s.startswith(">=", i):
2417 token = _T_GREATER_EQUAL
2426 self._parse_error("unknown tokens in line")
2429 # Skip trailing whitespace
2430 while i < len(s) and s[i].isspace():
2435 tokens.append(token)
2437 # None-terminating the token list makes token fetching simpler/faster
2442 # Helpers for syntax checking and token fetching. See the
2443 # 'Intro to expressions' section for what a constant symbol is.
2445 # More of these could be added, but the single-use cases are inlined as an
2448 def _expect_sym(self):
2449 token = self._tokens[self._tokens_i]
2452 if token.__class__ is not Symbol:
2453 self._parse_error("expected symbol")
2457 def _expect_nonconst_sym(self):
2458 # Used for 'select' and 'imply' only. We know the token indices.
2460 token = self._tokens[1]
2463 if token.__class__ is not Symbol or token.is_constant:
2464 self._parse_error("expected nonconstant symbol")
2468 def _expect_str_and_eol(self):
2469 token = self._tokens[self._tokens_i]
2472 if token.__class__ is not str:
2473 self._parse_error("expected string")
2475 if self._tokens[self._tokens_i] is not None:
2476 self._trailing_tokens_error()
2480 def _expect_expr_and_eol(self):
2481 expr = self._parse_expr(True)
2483 if self._tokens[self._tokens_i] is not None:
2484 self._trailing_tokens_error()
2488 def _check_token(self, token):
2489 # If the next token is 'token', removes it and returns True
2491 if self._tokens[self._tokens_i] is token:
2497 # Preprocessor logic
2500 def _parse_assignment(self, s):
2501 # Parses a preprocessor variable assignment, registering the variable
2502 # if it doesn't already exist. Also takes care of bare macros on lines
2503 # (which are allowed, and can be useful for their side effects).
2505 # Expand any macros in the left-hand side of the assignment (the
2510 i = _assignment_lhs_fragment_match(s, i).end()
2511 if s.startswith("$(", i):
2512 s, i = self._expand_macro(s, i, ())
2517 # We also accept a bare macro on a line (e.g.
2518 # $(warning-if,$(foo),ops)), provided it expands to a blank string
2525 # Extract assignment operator (=, :=, or +=) and value
2526 rhs_match = _assignment_rhs_match(s, i)
2528 self._parse_error("syntax error")
2530 op, val = rhs_match.groups()
2533 if name in self.variables:
2534 # Already seen variable
2535 var = self.variables[name]
2541 var._n_expansions = 0
2542 self.variables[name] = var
2544 # += acts like = on undefined variables (defines a recursive
2550 var.is_recursive = True
2553 var.is_recursive = False
2554 var.value = self._expand_whole(val, ())
2556 # += does immediate expansion if the variable was last set
2558 var.value += " " + (val if var.is_recursive else
2559 self._expand_whole(val, ()))
2561 def _expand_whole(self, s, args):
2562 # Expands preprocessor macros in all of 's'. Used whenever we don't
2563 # have to worry about delimiters. See _expand_macro() re. the 'args'
2566 # Returns the expanded string.
2573 s, i = self._expand_macro(s, i, args)
2576 def _expand_name(self, s, i):
2577 # Expands a symbol name starting at index 'i' in 's'.
2579 # Returns the expanded name, the expanded 's' (including the part
2580 # before the name), and the index of the first character in the next
2581 # token after the name.
2583 s, end_i = self._expand_name_iter(s, i)
2585 # isspace() is False for empty strings
2586 if not name.strip():
2587 # Avoid creating a Kconfig symbol with a blank name. It's almost
2588 # guaranteed to be an error.
2589 self._parse_error("macro expanded to blank string")
2591 # Skip trailing whitespace
2592 while end_i < len(s) and s[end_i].isspace():
2595 return name, s, end_i
2597 def _expand_name_iter(self, s, i):
2598 # Expands a symbol name starting at index 'i' in 's'.
2600 # Returns the expanded 's' (including the part before the name) and the
2601 # index of the first character after the expanded name in 's'.
2604 match = _name_special_search(s, i)
2606 if match.group() == "$(":
2607 s, i = self._expand_macro(s, match.start(), ())
2609 return (s, match.start())
2611 def _expand_str(self, s, i):
2612 # Expands a quoted string starting at index 'i' in 's'. Handles both
2613 # backslash escapes and macro expansion.
2615 # Returns the expanded 's' (including the part before the string) and
2616 # the index of the first character after the expanded string in 's'.
2619 i += 1 # Skip over initial "/'
2621 match = _string_special_search(s, i)
2623 self._parse_error("unterminated string")
2626 if match.group() == quote:
2627 # Found the end of the string
2628 return (s, match.end())
2630 elif match.group() == "\\":
2631 # Replace '\x' with 'x'. 'i' ends up pointing to the character
2632 # after 'x', which allows macros to be canceled with '\$(foo)'.
2634 s = s[:match.start()] + s[i:]
2636 elif match.group() == "$(":
2637 # A macro call within the string
2638 s, i = self._expand_macro(s, match.start(), ())
2641 # A ' quote within " quotes or vice versa
2644 def _expand_macro(self, s, i, args):
2645 # Expands a macro starting at index 'i' in 's'. If this macro resulted
2646 # from the expansion of another macro, 'args' holds the arguments
2647 # passed to that macro.
2649 # Returns the expanded 's' (including the part before the macro) and
2650 # the index of the first character after the expanded macro in 's'.
2653 i += 2 # Skip over "$("
2655 # Start of current macro argument
2658 # Arguments of this macro call
2662 match = _macro_special_search(s, i)
2664 self._parse_error("missing end parenthesis in macro expansion")
2667 if match.group() == ")":
2668 # Found the end of the macro
2670 new_args.append(s[arg_start:match.start()])
2674 # $(1) is replaced by the first argument to the function, etc.,
2675 # provided at least that many arguments were passed
2678 # Does the macro look like an integer, with a corresponding
2679 # argument? If so, expand it to the value of the argument.
2680 prefix += args[int(new_args[0])]
2681 except (ValueError, IndexError):
2682 # Regular variables are just functions without arguments,
2683 # and also go through the function value path
2684 prefix += self._fn_val(new_args)
2686 return (prefix + s[match.end():],
2689 elif match.group() == ",":
2690 # Found the end of a macro argument
2691 new_args.append(s[arg_start:match.start()])
2692 arg_start = i = match.end()
2694 else: # match.group() == "$("
2695 # A nested macro call within the macro
2696 s, i = self._expand_macro(s, match.start(), args)
2698 def _fn_val(self, args):
2699 # Returns the result of calling the function args[0] with the arguments
2700 # args[1..len(args)-1]. Plain variables are treated as functions
2701 # without arguments.
2705 if fn in self.variables:
2706 var = self.variables[fn]
2710 if var._n_expansions:
2711 self._parse_error("Preprocessor variable {} recursively "
2712 "references itself".format(var.name))
2713 elif var._n_expansions > 100:
2714 # Allow functions to call themselves, but guess that functions
2715 # that are overly recursive are stuck
2716 self._parse_error("Preprocessor function {} seems stuck "
2717 "in infinite recursion".format(var.name))
2719 var._n_expansions += 1
2720 res = self._expand_whole(self.variables[fn].value, args)
2721 var._n_expansions -= 1
2724 if fn in self._functions:
2725 # Built-in or user-defined function
2727 py_fn, min_arg, max_arg = self._functions[fn]
2729 if len(args) - 1 < min_arg or \
2730 (max_arg is not None and len(args) - 1 > max_arg):
2732 if min_arg == max_arg:
2733 expected_args = min_arg
2734 elif max_arg is None:
2735 expected_args = "{} or more".format(min_arg)
2737 expected_args = "{}-{}".format(min_arg, max_arg)
2739 raise KconfigError("{}:{}: bad number of arguments in call "
2740 "to {}, expected {}, got {}"
2741 .format(self.filename, self.linenr, fn,
2742 expected_args, len(args) - 1))
2744 return py_fn(self, *args)
2746 # Environment variables are tried last
2747 if fn in os.environ:
2748 self.env_vars.add(fn)
2749 return os.environ[fn]
2757 def _make_and(self, e1, e2):
2758 # Constructs an AND (&&) expression. Performs trivial simplification.
2766 if e1 is self.n or e2 is self.n:
2769 return (AND, e1, e2)
2771 def _make_or(self, e1, e2):
2772 # Constructs an OR (||) expression. Performs trivial simplification.
2780 if e1 is self.y or e2 is self.y:
2785 def _parse_block(self, end_token, parent, prev):
2786 # Parses a block, which is the contents of either a file or an if,
2787 # menu, or choice statement.
2790 # The token that ends the block, e.g. _T_ENDIF ("endif") for ifs.
2794 # The parent menu node, corresponding to a menu, Choice, or 'if'.
2795 # 'if's are flattened after parsing.
2798 # The previous menu node. New nodes will be added after this one (by
2799 # modifying their 'next' pointer).
2801 # 'prev' is reused to parse a list of child menu nodes (for a menu or
2802 # Choice): After parsing the children, the 'next' pointer is assigned
2803 # to the 'list' pointer to "tilt up" the children above the node.
2805 # Returns the final menu node in the block (or 'prev' if the block is
2806 # empty). This allows chaining.
2808 while self._next_line():
2809 t0 = self._tokens[0]
2811 if t0 is _T_CONFIG or t0 is _T_MENUCONFIG:
2812 # The tokenizer allocates Symbol objects for us
2813 sym = self._tokens[1]
2815 if sym.__class__ is not Symbol or sym.is_constant:
2816 self._parse_error("missing or bad symbol name")
2818 if self._tokens[2] is not None:
2819 self._trailing_tokens_error()
2821 self.defined_syms.append(sym)
2826 node.is_menuconfig = (t0 is _T_MENUCONFIG)
2827 node.prompt = node.help = node.list = None
2828 node.parent = parent
2829 node.filename = self.filename
2830 node.linenr = self.linenr
2831 node.include_path = self._include_path
2833 sym.nodes.append(node)
2835 self._parse_properties(node)
2837 if node.is_menuconfig and not node.prompt:
2838 self._warn("the menuconfig symbol {} has no prompt"
2839 .format(_name_and_loc(sym)))
2846 # due to tricky Python semantics. The order matters.
2847 prev.next = prev = node
2853 elif t0 in _SOURCE_TOKENS:
2854 pattern = self._expect_str_and_eol()
2856 if t0 in _REL_SOURCE_TOKENS:
2858 pattern = join(dirname(self.filename), pattern)
2860 # - glob() doesn't support globbing relative to a directory, so
2861 # we need to prepend $srctree to 'pattern'. Use join()
2862 # instead of '+' so that an absolute path in 'pattern' is
2865 # - Sort the glob results to ensure a consistent ordering of
2866 # Kconfig symbols, which indirectly ensures a consistent
2867 # ordering in e.g. .config files
2868 filenames = sorted(iglob(join(self._srctree_prefix, pattern)))
2870 if not filenames and t0 in _OBL_SOURCE_TOKENS:
2872 "{}:{}: '{}' not found (in '{}'). Check that "
2873 "environment variables are set correctly (e.g. "
2874 "$srctree, which is {}). Also note that unset "
2875 "environment variables expand to the empty string."
2876 .format(self.filename, self.linenr, pattern,
2878 "set to '{}'".format(self.srctree)
2879 if self.srctree else "unset or blank"))
2881 for filename in filenames:
2882 self._enter_file(filename)
2883 prev = self._parse_block(None, parent, prev)
2886 elif t0 is end_token:
2887 # Reached the end of the block. Terminate the final node and
2890 if self._tokens[1] is not None:
2891 self._trailing_tokens_error()
2898 node.item = node.prompt = None
2899 node.parent = parent
2900 node.dep = self._expect_expr_and_eol()
2902 self._parse_block(_T_ENDIF, node, node)
2903 node.list = node.next
2905 prev.next = prev = node
2910 node.item = t0 # _T_MENU == MENU
2911 node.is_menuconfig = True
2912 node.prompt = (self._expect_str_and_eol(), self.y)
2913 node.visibility = self.y
2914 node.parent = parent
2915 node.filename = self.filename
2916 node.linenr = self.linenr
2917 node.include_path = self._include_path
2919 self.menus.append(node)
2921 self._parse_properties(node)
2922 self._parse_block(_T_ENDMENU, node, node)
2923 node.list = node.next
2925 prev.next = prev = node
2927 elif t0 is _T_COMMENT:
2930 node.item = t0 # _T_COMMENT == COMMENT
2931 node.is_menuconfig = False
2932 node.prompt = (self._expect_str_and_eol(), self.y)
2934 node.parent = parent
2935 node.filename = self.filename
2936 node.linenr = self.linenr
2937 node.include_path = self._include_path
2939 self.comments.append(node)
2941 self._parse_properties(node)
2943 prev.next = prev = node
2945 elif t0 is _T_CHOICE:
2946 if self._tokens[1] is None:
2948 choice.direct_dep = self.n
2951 name = self._expect_str_and_eol()
2952 choice = self.named_choices.get(name)
2956 choice.direct_dep = self.n
2957 self.named_choices[name] = choice
2959 self.choices.append(choice)
2962 node.kconfig = choice.kconfig = self
2964 node.is_menuconfig = True
2965 node.prompt = node.help = None
2966 node.parent = parent
2967 node.filename = self.filename
2968 node.linenr = self.linenr
2969 node.include_path = self._include_path
2971 choice.nodes.append(node)
2973 self._parse_properties(node)
2974 self._parse_block(_T_ENDCHOICE, node, node)
2975 node.list = node.next
2977 prev.next = prev = node
2979 elif t0 is _T_MAINMENU:
2980 self.top_node.prompt = (self._expect_str_and_eol(), self.y)
2983 # A valid endchoice/endif/endmenu is caught by the 'end_token'
2986 "no corresponding 'choice'" if t0 is _T_ENDCHOICE else
2987 "no corresponding 'if'" if t0 is _T_ENDIF else
2988 "no corresponding 'menu'" if t0 is _T_ENDMENU else
2989 "unrecognized construct")
2991 # End of file reached. Terminate the final node and return it.
2995 "expected '{}' at end of '{}'"
2996 .format("endchoice" if end_token is _T_ENDCHOICE else
2997 "endif" if end_token is _T_ENDIF else
3004 def _parse_cond(self):
3005 # Parses an optional 'if <expr>' construct and returns the parsed
3006 # <expr>, or self.y if the next token is not _T_IF
3008 expr = self._parse_expr(True) if self._check_token(_T_IF) else self.y
3010 if self._tokens[self._tokens_i] is not None:
3011 self._trailing_tokens_error()
3015 def _parse_properties(self, node):
3016 # Parses and adds properties to the MenuNode 'node' (type, 'prompt',
3017 # 'default's, etc.) Properties are later copied up to symbols and
3018 # choices in a separate pass after parsing, in e.g.
3019 # _add_props_to_sym().
3021 # An older version of this code added properties directly to symbols
3022 # and choices instead of to their menu nodes (and handled dependency
3023 # propagation simultaneously), but that loses information on where a
3024 # property is added when a symbol or choice is defined in multiple
3025 # locations. Some Kconfig configuration systems rely heavily on such
3026 # symbols, and better docs can be generated by keeping track of where
3027 # properties are added.
3030 # The menu node we're parsing properties on
3032 # Dependencies from 'depends on'. Will get propagated to the properties
3036 while self._next_line():
3037 t0 = self._tokens[0]
3039 if t0 in _TYPE_TOKENS:
3040 # Relies on '_T_BOOL is BOOL', etc., to save a conversion
3041 self._set_type(node, t0)
3042 if self._tokens[1] is not None:
3043 self._parse_prompt(node)
3045 elif t0 is _T_DEPENDS:
3046 if not self._check_token(_T_ON):
3047 self._parse_error("expected 'on' after 'depends'")
3049 node.dep = self._make_and(node.dep,
3050 self._expect_expr_and_eol())
3053 self._parse_help(node)
3055 elif t0 is _T_SELECT:
3056 if node.item.__class__ is not Symbol:
3057 self._parse_error("only symbols can select")
3059 node.selects.append((self._expect_nonconst_sym(),
3060 self._parse_cond()))
3066 elif t0 is _T_DEFAULT:
3067 node.defaults.append((self._parse_expr(False),
3068 self._parse_cond()))
3070 elif t0 in _DEF_TOKEN_TO_TYPE:
3071 self._set_type(node, _DEF_TOKEN_TO_TYPE[t0])
3072 node.defaults.append((self._parse_expr(False),
3073 self._parse_cond()))
3075 elif t0 is _T_PROMPT:
3076 self._parse_prompt(node)
3078 elif t0 is _T_RANGE:
3079 node.ranges.append((self._expect_sym(), self._expect_sym(),
3080 self._parse_cond()))
3082 elif t0 is _T_IMPLY:
3083 if node.item.__class__ is not Symbol:
3084 self._parse_error("only symbols can imply")
3086 node.implies.append((self._expect_nonconst_sym(),
3087 self._parse_cond()))
3089 elif t0 is _T_VISIBLE:
3090 if not self._check_token(_T_IF):
3091 self._parse_error("expected 'if' after 'visible'")
3093 node.visibility = self._make_and(node.visibility,
3094 self._expect_expr_and_eol())
3096 elif t0 is _T_OPTION:
3097 if self._check_token(_T_ENV):
3098 if not self._check_token(_T_EQUAL):
3099 self._parse_error("expected '=' after 'env'")
3101 env_var = self._expect_str_and_eol()
3102 node.item.env_var = env_var
3104 if env_var in os.environ:
3105 node.defaults.append(
3106 (self._lookup_const_sym(os.environ[env_var]),
3109 self._warn("{1} has 'option env=\"{0}\"', "
3110 "but the environment variable {0} is not "
3111 "set".format(node.item.name, env_var),
3112 self.filename, self.linenr)
3114 if env_var != node.item.name:
3115 self._warn("Kconfiglib expands environment variables "
3116 "in strings directly, meaning you do not "
3117 "need 'option env=...' \"bounce\" symbols. "
3118 "For compatibility with the C tools, "
3119 "rename {} to {} (so that the symbol name "
3120 "matches the environment variable name)."
3121 .format(node.item.name, env_var),
3122 self.filename, self.linenr)
3124 elif self._check_token(_T_DEFCONFIG_LIST):
3125 if not self.defconfig_list:
3126 self.defconfig_list = node.item
3128 self._warn("'option defconfig_list' set on multiple "
3129 "symbols ({0} and {1}). Only {0} will be "
3130 "used.".format(self.defconfig_list.name,
3132 self.filename, self.linenr)
3134 elif self._check_token(_T_MODULES):
3135 # To reduce warning spam, only warn if 'option modules' is
3136 # set on some symbol that isn't MODULES, which should be
3137 # safe. I haven't run into any projects that make use
3138 # modules besides the kernel yet, and there it's likely to
3139 # keep being called "MODULES".
3140 if node.item is not self.modules:
3141 self._warn("the 'modules' option is not supported. "
3142 "Let me know if this is a problem for you, "
3143 "as it wouldn't be that hard to implement. "
3144 "Note that modules are supported -- "
3145 "Kconfiglib just assumes the symbol name "
3146 "MODULES, like older versions of the C "
3147 "implementation did when 'option modules' "
3149 self.filename, self.linenr)
3151 elif self._check_token(_T_ALLNOCONFIG_Y):
3152 if node.item.__class__ is not Symbol:
3153 self._parse_error("the 'allnoconfig_y' option is only "
3154 "valid for symbols")
3156 node.item.is_allnoconfig_y = True
3159 self._parse_error("unrecognized option")
3161 elif t0 is _T_OPTIONAL:
3162 if node.item.__class__ is not Choice:
3163 self._parse_error('"optional" is only valid for choices')
3165 node.item.is_optional = True
3168 # Reuse the tokens for the non-property line later
3169 self._reuse_tokens = True
3172 def _set_type(self, node, new_type):
3174 if node.item.orig_type and node.item.orig_type is not new_type:
3175 self._warn("{} defined with multiple types, {} will be used"
3176 .format(_name_and_loc(node.item),
3177 TYPE_TO_STR[new_type]))
3179 node.item.orig_type = new_type
3181 def _parse_prompt(self, node):
3182 # 'prompt' properties override each other within a single definition of
3183 # a symbol, but additional prompts can be added by defining the symbol
3187 self._warn(_name_and_loc(node.item) +
3188 " defined with multiple prompts in single location")
3190 prompt = self._tokens[1]
3193 if prompt.__class__ is not str:
3194 self._parse_error("expected prompt string")
3196 if prompt != prompt.strip():
3197 self._warn(_name_and_loc(node.item) +
3198 " has leading or trailing whitespace in its prompt")
3200 # This avoid issues for e.g. reStructuredText documentation, where
3201 # '*prompt *' is invalid
3202 prompt = prompt.strip()
3204 node.prompt = (prompt, self._parse_cond())
3206 def _parse_help(self, node):
3207 if node.help is not None:
3208 self._warn(_name_and_loc(node.item) + " defined with more than "
3209 "one help text -- only the last one will be used")
3211 # Micro-optimization. This code is pretty hot.
3212 readline = self._readline
3214 # Find first non-blank (not all-space) line and get its
3221 self._empty_help(node, line)
3223 if not line.isspace():
3226 len_ = len # Micro-optimization
3228 # Use a separate 'expline' variable here and below to avoid stomping on
3229 # any tabs people might've put deliberately into the first line after
3231 expline = line.expandtabs()
3232 indent = len_(expline) - len_(expline.lstrip())
3234 self._empty_help(node, line)
3237 # The help text goes on till the first non-blank line with less indent
3238 # than the first line
3240 # Add the first line
3241 lines = [expline[indent:]]
3242 add_line = lines.append # Micro-optimization
3247 # No need to preserve the exact whitespace in these
3253 expline = line.expandtabs()
3254 if len_(expline) - len_(expline.lstrip()) < indent:
3256 add_line(expline[indent:])
3258 self.linenr += len_(lines)
3259 node.help = "".join(lines).rstrip()
3261 self._line_after_help(line)
3263 def _empty_help(self, node, line):
3264 self._warn(_name_and_loc(node.item) +
3265 " has 'help' but empty help text")
3268 self._line_after_help(line)
3270 def _parse_expr(self, transform_m):
3271 # Parses an expression from the tokens in Kconfig._tokens using a
3272 # simple top-down approach. See the module docstring for the expression
3276 # True if m should be rewritten to m && MODULES. See the
3277 # Kconfig.eval_string() documentation.
3281 # expr: and_expr ['||' expr]
3282 # and_expr: factor ['&&' and_expr]
3283 # factor: <symbol> ['='/'!='/'<'/... <symbol>]
3287 # It helps to think of the 'expr: and_expr' case as a single-operand OR
3288 # (no ||), and of the 'and_expr: factor' case as a single-operand AND
3289 # (no &&). Parsing code is always a bit tricky.
3291 # Mind dump: parse_factor() and two nested loops for OR and AND would
3292 # work as well. The straightforward implementation there gives a
3293 # (op, (op, (op, A, B), C), D) parse for A op B op C op D. Representing
3294 # expressions as (op, [list of operands]) instead goes nicely with that
3295 # version, but is wasteful for short expressions and complicates
3296 # expression evaluation and other code that works on expressions (more
3297 # complicated code likely offsets any performance gain from less
3298 # recursion too). If we also try to optimize the list representation by
3299 # merging lists when possible (e.g. when ANDing two AND expressions),
3300 # we end up allocating a ton of lists instead of reusing expressions,
3303 and_expr = self._parse_and_expr(transform_m)
3305 # Return 'and_expr' directly if we have a "single-operand" OR.
3306 # Otherwise, parse the expression on the right and make an OR node.
3307 # This turns A || B || C || D into (OR, A, (OR, B, (OR, C, D))).
3308 return and_expr if not self._check_token(_T_OR) else \
3309 (OR, and_expr, self._parse_expr(transform_m))
3311 def _parse_and_expr(self, transform_m):
3312 factor = self._parse_factor(transform_m)
3314 # Return 'factor' directly if we have a "single-operand" AND.
3315 # Otherwise, parse the right operand and make an AND node. This turns
3316 # A && B && C && D into (AND, A, (AND, B, (AND, C, D))).
3317 return factor if not self._check_token(_T_AND) else \
3318 (AND, factor, self._parse_and_expr(transform_m))
3320 def _parse_factor(self, transform_m):
3321 token = self._tokens[self._tokens_i]
3324 if token.__class__ is Symbol:
3325 # Plain symbol or relation
3327 if self._tokens[self._tokens_i] not in _RELATIONS:
3330 # For conditional expressions ('depends on <expr>',
3331 # '... if <expr>', etc.), m is rewritten to m && MODULES.
3332 if transform_m and token is self.m:
3333 return (AND, self.m, self.modules)
3339 # _T_EQUAL, _T_UNEQUAL, etc., deliberately have the same values as
3340 # EQUAL, UNEQUAL, etc., so we can just use the token directly
3342 return (self._tokens[self._tokens_i - 1], token,
3346 # token == _T_NOT == NOT
3347 return (token, self._parse_factor(transform_m))
3349 if token is _T_OPEN_PAREN:
3350 expr_parse = self._parse_expr(transform_m)
3351 if self._check_token(_T_CLOSE_PAREN):
3354 self._parse_error("malformed expression")
3357 # Caching and invalidation
3360 def _build_dep(self):
3361 # Populates the Symbol/Choice._dependents sets, which contain all other
3362 # items (symbols and choices) that immediately depend on the item in
3363 # the sense that changing the value of the item might affect the value
3364 # of the dependent items. This is used for caching/invalidation.
3366 # The calculated sets might be larger than necessary as we don't do any
3367 # complex analysis of the expressions.
3369 make_depend_on = _make_depend_on # Micro-optimization
3371 # Only calculate _dependents for defined symbols. Constant and
3372 # undefined symbols could theoretically be selected/implied, but it
3373 # wouldn't change their value, so it's not a true dependency.
3374 for sym in self.unique_defined_syms:
3375 # Symbols depend on the following:
3377 # The prompt conditions
3378 for node in sym.nodes:
3380 make_depend_on(sym, node.prompt[1])
3382 # The default values and their conditions
3383 for value, cond in sym.defaults:
3384 make_depend_on(sym, value)
3385 make_depend_on(sym, cond)
3387 # The reverse and weak reverse dependencies
3388 make_depend_on(sym, sym.rev_dep)
3389 make_depend_on(sym, sym.weak_rev_dep)
3391 # The ranges along with their conditions
3392 for low, high, cond in sym.ranges:
3393 make_depend_on(sym, low)
3394 make_depend_on(sym, high)
3395 make_depend_on(sym, cond)
3397 # The direct dependencies. This is usually redundant, as the direct
3398 # dependencies get propagated to properties, but it's needed to get
3399 # invalidation solid for 'imply', which only checks the direct
3400 # dependencies (even if there are no properties to propagate it
3402 make_depend_on(sym, sym.direct_dep)
3404 # In addition to the above, choice symbols depend on the choice
3405 # they're in, but that's handled automatically since the Choice is
3406 # propagated to the conditions of the properties before
3407 # _build_dep() runs.
3409 for choice in self.unique_choices:
3410 # Choices depend on the following:
3412 # The prompt conditions
3413 for node in choice.nodes:
3415 make_depend_on(choice, node.prompt[1])
3417 # The default symbol conditions
3418 for _, cond in choice.defaults:
3419 make_depend_on(choice, cond)
3421 def _add_choice_deps(self):
3422 # Choices also depend on the choice symbols themselves, because the
3423 # y-mode selection of the choice might change if a choice symbol's
3424 # visibility changes.
3426 # We add these dependencies separately after dependency loop detection.
3427 # The invalidation algorithm can handle the resulting
3428 # <choice symbol> <-> <choice> dependency loops, but they make loop
3429 # detection awkward.
3431 for choice in self.unique_choices:
3432 for sym in choice.syms:
3433 sym._dependents.add(choice)
3435 def _invalidate_all(self):
3436 # Undefined symbols never change value and don't need to be
3437 # invalidated, so we can just iterate over defined symbols.
3438 # Invalidating constant symbols would break things horribly.
3439 for sym in self.unique_defined_syms:
3442 for choice in self.unique_choices:
3443 choice._invalidate()
3446 # Post-parsing menu tree processing, including dependency propagation and
3447 # implicit submenu creation
3450 def _finalize_node(self, node, visible_if):
3451 # Finalizes a menu node and its children:
3453 # - Copies properties from menu nodes up to their contained
3456 # - Propagates dependencies from parent to child nodes
3458 # - Creates implicit menus (see kconfig-language.txt)
3460 # - Removes 'if' nodes
3462 # - Sets 'choice' types and registers choice symbols
3464 # menu_finalize() in the C implementation is similar.
3467 # The menu node to finalize. This node and its children will have
3468 # been finalized when the function returns, and any implicit menus
3469 # will have been created.
3472 # Dependencies from 'visible if' on parent menus. These are added to
3473 # the prompts of symbols and choices.
3475 if node.item.__class__ is Symbol:
3476 # Copy defaults, ranges, selects, and implies to the Symbol
3477 self._add_props_to_sym(node)
3479 # Find any items that should go in an implicit menu rooted at the
3482 while cur.next and _auto_menu_dep(node, cur.next):
3483 # This makes implicit submenu creation work recursively, with
3484 # implicit menus inside implicit menus
3485 self._finalize_node(cur.next, visible_if)
3490 # Found symbols that should go in an implicit submenu. Tilt
3492 node.list = node.next
3493 node.next = cur.next
3497 # The menu node is a choice, menu, or if. Finalize each child node.
3499 if node.item is MENU:
3500 visible_if = self._make_and(visible_if, node.visibility)
3502 # Propagate the menu node's dependencies to each child menu node.
3504 # This needs to go before the recursive _finalize_node() call so
3505 # that implicit submenu creation can look ahead at dependencies.
3506 self._propagate_deps(node, visible_if)
3508 # Finalize the children
3511 self._finalize_node(cur, visible_if)
3515 # node's children have been individually finalized. Do final steps
3516 # to finalize this "level" in the menu tree.
3520 # Empty choices (node.list None) are possible, so this needs to go
3522 if node.item.__class__ is Choice:
3523 # Add the node's non-node-specific properties to the choice, like
3524 # _add_props_to_sym() does
3526 choice.direct_dep = self._make_or(choice.direct_dep, node.dep)
3527 choice.defaults += node.defaults
3529 _finalize_choice(node)
3531 def _propagate_deps(self, node, visible_if):
3532 # Propagates 'node's dependencies to its child menu nodes
3534 # If the parent node holds a Choice, we use the Choice itself as the
3535 # parent dependency. This makes sense as the value (mode) of the choice
3536 # limits the visibility of the contained choice symbols. The C
3537 # implementation works the same way.
3539 # Due to the similar interface, Choice works as a drop-in replacement
3541 basedep = node.item if node.item.__class__ is Choice else node.dep
3545 dep = cur.dep = self._make_and(cur.dep, basedep)
3547 if cur.item.__class__ in _SYMBOL_CHOICE:
3548 # Propagate 'visible if' and dependencies to the prompt
3550 cur.prompt = (cur.prompt[0],
3553 self._make_and(visible_if, dep)))
3555 # Propagate dependencies to defaults
3557 cur.defaults = [(default, self._make_and(cond, dep))
3558 for default, cond in cur.defaults]
3560 # Propagate dependencies to ranges
3562 cur.ranges = [(low, high, self._make_and(cond, dep))
3563 for low, high, cond in cur.ranges]
3565 # Propagate dependencies to selects
3567 cur.selects = [(target, self._make_and(cond, dep))
3568 for target, cond in cur.selects]
3570 # Propagate dependencies to implies
3572 cur.implies = [(target, self._make_and(cond, dep))
3573 for target, cond in cur.implies]
3575 elif cur.prompt: # Not a symbol/choice
3576 # Propagate dependencies to the prompt. 'visible if' is only
3577 # propagated to symbols/choices.
3578 cur.prompt = (cur.prompt[0],
3579 self._make_and(cur.prompt[1], dep))
3583 def _add_props_to_sym(self, node):
3584 # Copies properties from the menu node 'node' up to its contained
3585 # symbol, and adds (weak) reverse dependencies to selected/implied
3588 # This can't be rolled into _propagate_deps(), because that function
3589 # traverses the menu tree roughly breadth-first, meaning properties on
3590 # symbols defined in multiple locations could end up in the wrong
3595 # See the Symbol class docstring
3596 sym.direct_dep = self._make_or(sym.direct_dep, node.dep)
3598 sym.defaults += node.defaults
3599 sym.ranges += node.ranges
3600 sym.selects += node.selects
3601 sym.implies += node.implies
3603 # Modify the reverse dependencies of the selected symbol
3604 for target, cond in node.selects:
3605 target.rev_dep = self._make_or(
3607 self._make_and(sym, cond))
3609 # Modify the weak reverse dependencies of the implied
3611 for target, cond in node.implies:
3612 target.weak_rev_dep = self._make_or(
3613 target.weak_rev_dep,
3614 self._make_and(sym, cond))
3620 def _check_sym_sanity(self):
3621 # Checks various symbol properties that are handiest to check after
3622 # parsing. Only generates errors and warnings.
3624 def num_ok(sym, type_):
3625 # Returns True if the (possibly constant) symbol 'sym' is valid as a value
3626 # for a symbol of type type_ (INT or HEX)
3628 # 'not sym.nodes' implies a constant or undefined symbol, e.g. a plain
3631 return _is_base_n(sym.name, _TYPE_TO_BASE[type_])
3633 return sym.orig_type is type_
3635 for sym in self.unique_defined_syms:
3636 if sym.orig_type in _BOOL_TRISTATE:
3637 # A helper function could be factored out here, but keep it
3638 # speedy/straightforward
3640 for target_sym, _ in sym.selects:
3641 if target_sym.orig_type not in _BOOL_TRISTATE_UNKNOWN:
3642 self._warn("{} selects the {} symbol {}, which is not "
3644 .format(_name_and_loc(sym),
3645 TYPE_TO_STR[target_sym.orig_type],
3646 _name_and_loc(target_sym)))
3648 for target_sym, _ in sym.implies:
3649 if target_sym.orig_type not in _BOOL_TRISTATE_UNKNOWN:
3650 self._warn("{} implies the {} symbol {}, which is not "
3652 .format(_name_and_loc(sym),
3653 TYPE_TO_STR[target_sym.orig_type],
3654 _name_and_loc(target_sym)))
3656 elif sym.orig_type: # STRING/INT/HEX
3657 for default, _ in sym.defaults:
3658 if default.__class__ is not Symbol:
3660 "the {} symbol {} has a malformed default {} -- expected "
3662 .format(TYPE_TO_STR[sym.orig_type], _name_and_loc(sym),
3665 if sym.orig_type is STRING:
3666 if not default.is_constant and not default.nodes and \
3667 not default.name.isupper():
3668 # 'default foo' on a string symbol could be either a symbol
3669 # reference or someone leaving out the quotes. Guess that
3670 # the quotes were left out if 'foo' isn't all-uppercase
3671 # (and no symbol named 'foo' exists).
3672 self._warn("style: quotes recommended around "
3673 "default value for string symbol "
3674 + _name_and_loc(sym))
3676 elif not num_ok(default, sym.orig_type): # INT/HEX
3677 self._warn("the {0} symbol {1} has a non-{0} default {2}"
3678 .format(TYPE_TO_STR[sym.orig_type],
3680 _name_and_loc(default)))
3682 if sym.selects or sym.implies:
3683 self._warn("the {} symbol {} has selects or implies"
3684 .format(TYPE_TO_STR[sym.orig_type],
3685 _name_and_loc(sym)))
3688 self._warn("{} defined without a type"
3689 .format(_name_and_loc(sym)))
3693 if sym.orig_type not in _INT_HEX:
3695 "the {} symbol {} has ranges, but is not int or hex"
3696 .format(TYPE_TO_STR[sym.orig_type],
3697 _name_and_loc(sym)))
3699 for low, high, _ in sym.ranges:
3700 if not num_ok(low, sym.orig_type) or \
3701 not num_ok(high, sym.orig_type):
3703 self._warn("the {0} symbol {1} has a non-{0} "
3705 .format(TYPE_TO_STR[sym.orig_type],
3708 _name_and_loc(high)))
3710 def _check_choice_sanity(self):
3711 # Checks various choice properties that are handiest to check after
3712 # parsing. Only generates errors and warnings.
3714 def warn_select_imply(sym, expr, expr_type):
3715 msg = "the choice symbol {} is {} by the following symbols, but " \
3716 "select/imply has no effect on choice symbols" \
3717 .format(_name_and_loc(sym), expr_type)
3720 for si in split_expr(expr, OR):
3721 msg += "\n - " + _name_and_loc(split_expr(si, AND)[0])
3725 for choice in self.unique_choices:
3726 if choice.orig_type not in _BOOL_TRISTATE:
3727 self._warn("{} defined with type {}"
3728 .format(_name_and_loc(choice),
3729 TYPE_TO_STR[choice.orig_type]))
3731 for node in choice.nodes:
3735 self._warn(_name_and_loc(choice) + " defined without a prompt")
3737 for default, _ in choice.defaults:
3738 if default.__class__ is not Symbol:
3740 "{} has a malformed default {}"
3741 .format(_name_and_loc(choice), expr_str(default)))
3743 if default.choice is not choice:
3744 self._warn("the default selection {} of {} is not "
3745 "contained in the choice"
3746 .format(_name_and_loc(default),
3747 _name_and_loc(choice)))
3749 for sym in choice.syms:
3751 self._warn("default on the choice symbol {} will have "
3752 "no effect, as defaults do not affect choice "
3753 "symbols".format(_name_and_loc(sym)))
3755 if sym.rev_dep is not sym.kconfig.n:
3756 warn_select_imply(sym, sym.rev_dep, "selected")
3758 if sym.weak_rev_dep is not sym.kconfig.n:
3759 warn_select_imply(sym, sym.weak_rev_dep, "implied")
3761 for node in sym.nodes:
3762 if node.parent.item is choice:
3764 self._warn("the choice symbol {} has no prompt"
3765 .format(_name_and_loc(sym)))
3768 self._warn("the choice symbol {} is defined with a "
3769 "prompt outside the choice"
3770 .format(_name_and_loc(sym)))
3772 def _parse_error(self, msg):
3773 raise KconfigError("{}couldn't parse '{}': {}".format(
3774 "" if self.filename is None else
3775 "{}:{}: ".format(self.filename, self.linenr),
3776 self._line.strip(), msg))
3778 def _trailing_tokens_error(self):
3779 self._parse_error("extra tokens at end of line")
3781 def _open(self, filename, mode):
3784 # - Enable universal newlines mode on Python 2 to ease
3785 # interoperability between Linux and Windows. It's already the
3786 # default on Python 3.
3788 # The "U" flag would currently work for both Python 2 and 3, but it's
3789 # deprecated on Python 3, so play it future-safe.
3791 # io.open() defaults to universal newlines on Python 2 (and is an
3792 # alias for open() on Python 3), but it returns 'unicode' strings and
3793 # slows things down:
3795 # Parsing x86 Kconfigs on Python 2
3797 # with open(..., "rU"):
3809 # There's no appreciable performance difference between "r" and
3810 # "rU" for parsing performance on Python 2.
3812 # - For Python 3, force the encoding. Forcing the encoding on Python 2
3813 # turns strings into Unicode strings, which gets messy. Python 2
3814 # doesn't decode regular strings anyway.
3815 return open(filename, "rU" if mode == "r" else mode) if _IS_PY2 else \
3816 open(filename, mode, encoding=self._encoding)
3818 def _check_undef_syms(self):
3819 # Prints warnings for all references to undefined symbols within the
3823 # Returns True if the string 's' looks like a number.
3825 # Internally, all operands in Kconfig are symbols, only undefined symbols
3826 # (which numbers usually are) get their name as their value.
3828 # Only hex numbers that start with 0x/0X are classified as numbers.
3829 # Otherwise, symbols whose names happen to contain only the letters A-F
3830 # would trigger false positives.
3835 if not s.startswith(("0x", "0X")):
3845 for sym in (self.syms.viewvalues if _IS_PY2 else self.syms.values)():
3846 # - sym.nodes empty means the symbol is undefined (has no
3847 # definition locations)
3849 # - Due to Kconfig internals, numbers show up as undefined Kconfig
3850 # symbols, but shouldn't be flagged
3852 # - The MODULES symbol always exists
3853 if not sym.nodes and not is_num(sym.name) and \
3854 sym.name != "MODULES":
3856 msg = "undefined symbol {}:".format(sym.name)
3857 for node in self.node_iter():
3858 if sym in node.referenced:
3859 msg += "\n\n- Referenced at {}:{}:\n\n{}" \
3860 .format(node.filename, node.linenr, node)
3863 def _warn(self, msg, filename=None, linenr=None):
3864 # For printing general warnings
3869 msg = "warning: " + msg
3870 if filename is not None:
3871 msg = "{}:{}: {}".format(filename, linenr, msg)
3873 self.warnings.append(msg)
3874 if self.warn_to_stderr:
3875 sys.stderr.write(msg + "\n")
3878 class Symbol(object):
3880 Represents a configuration symbol:
3885 The following attributes are available. They should be viewed as read-only,
3886 and some are implemented through @property magic (but are still efficient
3887 to access due to internal caching).
3889 Note: Prompts, help texts, and locations are stored in the Symbol's
3890 MenuNode(s) rather than in the Symbol itself. Check the MenuNode class and
3891 the Symbol.nodes attribute. This organization matches the C tools.
3894 The name of the symbol, e.g. "FOO" for 'config FOO'.
3897 The type of the symbol. One of BOOL, TRISTATE, STRING, INT, HEX, UNKNOWN.
3898 UNKNOWN is for undefined symbols, (non-special) constant symbols, and
3899 symbols defined without a type.
3901 When running without modules (MODULES having the value n), TRISTATE
3902 symbols magically change type to BOOL. This also happens for symbols
3903 within choices in "y" mode. This matches the C tools, and makes sense for
3904 menuconfig-like functionality.
3907 The type as given in the Kconfig file, without any magic applied. Used
3908 when printing the symbol.
3911 The value of the symbol as a string. Gives the value for string/int/hex
3912 symbols. For bool/tristate symbols, gives "n", "m", or "y".
3914 This is the symbol value that's used in relational expressions
3915 (A = B, A != B, etc.)
3917 Gotcha: For int/hex symbols, the exact format of the value must often be
3918 preserved (e.g., when writing a .config file), hence why you can't get it
3919 directly as an int. Do int(int_sym.str_value) or
3920 int(hex_sym.str_value, 16) to get the integer value.
3923 The tristate value of the symbol as an integer. One of 0, 1, 2,
3924 representing n, m, y. Always 0 (n) for non-bool/tristate symbols.
3926 This is the symbol value that's used outside of relation expressions
3927 (A, !A, A && B, A || B).
3930 A tuple containing the tristate user values that can currently be
3931 assigned to the symbol (that would be respected), ordered from lowest (0,
3932 representing n) to highest (2, representing y). This corresponds to the
3933 selections available in the menuconfig interface. The set of assignable
3934 values is calculated from the symbol's visibility and selects/implies.
3936 Returns the empty set for non-bool/tristate symbols and for symbols with
3937 visibility n. The other possible values are (0, 2), (0, 1, 2), (1, 2),
3938 (1,), and (2,). A (1,) or (2,) result means the symbol is visible but
3939 "locked" to m or y through a select, perhaps in combination with the
3940 visibility. menuconfig represents this as -M- and -*-, respectively.
3942 For string/hex/int symbols, check if Symbol.visibility is non-0 (non-n)
3943 instead to determine if the value can be changed.
3945 Some handy 'assignable' idioms:
3947 # Is 'sym' an assignable (visible) bool/tristate symbol?
3949 # What's the highest value it can be assigned? [-1] in Python
3950 # gives the last element.
3951 sym_high = sym.assignable[-1]
3954 sym_low = sym.assignable[0]
3956 # Can the symbol be set to at least m?
3957 if sym.assignable[-1] >= 1:
3960 # Can the symbol be set to m?
3961 if 1 in sym.assignable:
3965 The visibility of the symbol. One of 0, 1, 2, representing n, m, y. See
3966 the module documentation for an overview of symbol values and visibility.
3969 The user value of the symbol. None if no user value has been assigned
3970 (via Kconfig.load_config() or Symbol.set_value()).
3972 Holds 0, 1, or 2 for bool/tristate symbols, and a string for the other
3975 WARNING: Do not assign directly to this. It will break things. Use
3979 The .config assignment string that would get written out for the symbol
3980 by Kconfig.write_config(). Returns the empty string if no .config
3981 assignment would get written out.
3983 In general, visible symbols, symbols with (active) defaults, and selected
3984 symbols get written out. This includes all non-n-valued bool/tristate
3985 symbols, and all visible string/int/hex symbols.
3987 Symbols with the (no longer needed) 'option env=...' option generate no
3988 configuration output, and neither does the special
3989 'option defconfig_list' symbol.
3991 Tip: This field is useful when generating custom configuration output,
3992 even for non-.config-like formats. To write just the symbols that would
3993 get written out to .config files, do this:
3995 if sym.config_string:
3996 *Write symbol, e.g. by looking sym.str_value*
3998 This is a superset of the symbols written out by write_autoconf().
3999 That function skips all n-valued symbols.
4001 There usually won't be any great harm in just writing all symbols either,
4002 though you might get some special symbols and possibly some "redundant"
4003 n-valued symbol entries in there.
4006 A list of MenuNodes for this symbol. Will contain a single MenuNode for
4007 most symbols. Undefined and constant symbols have an empty nodes list.
4008 Symbols defined in multiple locations get one node for each location.
4011 Holds the parent Choice for choice symbols, and None for non-choice
4012 symbols. Doubles as a flag for whether a symbol is a choice symbol.
4015 List of (default, cond) tuples for the symbol's 'default' properties. For
4016 example, 'default A && B if C || D' is represented as
4017 ((AND, A, B), (OR, C, D)). If no condition was given, 'cond' is
4020 Note that 'depends on' and parent dependencies are propagated to
4021 'default' conditions.
4024 List of (symbol, cond) tuples for the symbol's 'select' properties. For
4025 example, 'select A if B && C' is represented as (A, (AND, B, C)). If no
4026 condition was given, 'cond' is self.kconfig.y.
4028 Note that 'depends on' and parent dependencies are propagated to 'select'
4032 Like 'selects', for imply.
4035 List of (low, high, cond) tuples for the symbol's 'range' properties. For
4036 example, 'range 1 2 if A' is represented as (1, 2, A). If there is no
4037 condition, 'cond' is self.kconfig.y.
4039 Note that 'depends on' and parent dependencies are propagated to 'range'
4042 Gotcha: 1 and 2 above will be represented as (undefined) Symbols rather
4043 than plain integers. Undefined symbols get their name as their string
4044 value, so this works out. The C tools work the same way.
4050 See the corresponding attributes on the MenuNode class.
4053 Reverse dependency expression from other symbols selecting this symbol.
4054 Multiple selections get ORed together. A condition on a select is ANDed
4055 with the selecting symbol.
4057 For example, if A has 'select FOO' and B has 'select FOO if C', then
4058 FOO's rev_dep will be (OR, A, (AND, B, C)).
4061 Like rev_dep, for imply.
4064 The direct ('depends on') dependencies for the symbol, or self.kconfig.y
4065 if there are no direct dependencies.
4067 This attribute includes any dependencies from surrounding menus and ifs.
4068 Those get propagated to the direct dependencies, and the resulting direct
4069 dependencies in turn get propagated to the conditions of all properties.
4071 If the symbol is defined in multiple locations, the dependencies from the
4072 different locations get ORed together.
4075 A set() with all symbols and choices referenced in the properties and
4076 property conditions of the symbol.
4078 Also includes dependencies from surrounding menus and ifs, because those
4079 get propagated to the symbol (see the 'Intro to symbol values' section in
4080 the module docstring).
4082 Choices appear in the dependencies of choice symbols.
4084 For the following definitions, only B and not C appears in A's
4085 'referenced'. To get transitive references, you'll have to recursively
4086 expand 'references' until no new items appear.
4099 See the Symbol.direct_dep attribute if you're only interested in the
4100 direct dependencies of the symbol (its 'depends on'). You can extract the
4101 symbols in it with the global expr_items() function.
4104 If the Symbol has an 'option env="FOO"' option, this contains the name
4105 ("FOO") of the environment variable. None for symbols without no
4108 'option env="FOO"' acts like a 'default' property whose value is the
4111 Symbols with 'option env' are never written out to .config files, even if
4112 they are visible. env_var corresponds to a flag called SYMBOL_AUTO in the
4116 True if the symbol has 'option allnoconfig_y' set on it. This has no
4117 effect internally (except when printing symbols), but can be checked by
4121 True if the symbol is a constant (quoted) symbol.
4124 The Kconfig instance this symbol is from.
4127 "_cached_assignable",
4161 See the class documentation.
4163 if self.orig_type is TRISTATE and \
4164 (self.choice and self.choice.tri_value == 2 or
4165 not self.kconfig.modules.tri_value):
4169 return self.orig_type
4172 def str_value(self):
4174 See the class documentation.
4176 if self._cached_str_val is not None:
4177 return self._cached_str_val
4179 if self.orig_type in _BOOL_TRISTATE:
4180 # Also calculates the visibility, so invalidation safe
4181 self._cached_str_val = TRI_TO_STR[self.tri_value]
4182 return self._cached_str_val
4184 # As a quirk of Kconfig, undefined symbols get their name as their
4185 # string value. This is why things like "FOO = bar" work for seeing if
4186 # FOO has the value "bar".
4187 if not self.orig_type: # UNKNOWN
4188 self._cached_str_val = self.name
4192 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
4193 # function call (property magic)
4194 vis = self.visibility
4196 self._write_to_conf = (vis != 0)
4198 if self.orig_type in _INT_HEX:
4199 # The C implementation checks the user value against the range in a
4200 # separate code path (post-processing after loading a .config).
4201 # Checking all values here instead makes more sense for us. It
4202 # requires that we check for a range first.
4204 base = _TYPE_TO_BASE[self.orig_type]
4206 # Check if a range is in effect
4207 for low_expr, high_expr, cond in self.ranges:
4208 if expr_value(cond):
4209 has_active_range = True
4211 # The zeros are from the C implementation running strtoll()
4213 low = int(low_expr.str_value, base) if \
4214 _is_base_n(low_expr.str_value, base) else 0
4215 high = int(high_expr.str_value, base) if \
4216 _is_base_n(high_expr.str_value, base) else 0
4220 has_active_range = False
4222 # Defaults are used if the symbol is invisible, lacks a user value,
4223 # or has an out-of-range user value
4226 if vis and self.user_value:
4227 user_val = int(self.user_value, base)
4228 if has_active_range and not low <= user_val <= high:
4229 num2str = str if base == 10 else hex
4231 "user value {} on the {} symbol {} ignored due to "
4232 "being outside the active range ([{}, {}]) -- falling "
4234 .format(num2str(user_val), TYPE_TO_STR[self.orig_type],
4235 _name_and_loc(self),
4236 num2str(low), num2str(high)))
4238 # If the user value is well-formed and satisfies range
4239 # contraints, it is stored in exactly the same form as
4240 # specified in the assignment (with or without "0x", etc.)
4241 val = self.user_value
4242 use_defaults = False
4245 # No user value or invalid user value. Look at defaults.
4247 # Used to implement the warning below
4250 for sym, cond in self.defaults:
4251 if expr_value(cond):
4252 has_default = self._write_to_conf = True
4256 if _is_base_n(val, base):
4257 val_num = int(val, base)
4259 val_num = 0 # strtoll() on empty string
4263 val_num = 0 # strtoll() on empty string
4265 # This clamping procedure runs even if there's no default
4266 if has_active_range:
4270 elif val_num > high:
4273 if clamp is not None:
4274 # The value is rewritten to a standard form if it is
4277 if self.orig_type is INT else \
4281 num2str = str if base == 10 else hex
4283 "default value {} on {} clamped to {} due to "
4284 "being outside the active range ([{}, {}])"
4285 .format(val_num, _name_and_loc(self),
4286 num2str(clamp), num2str(low),
4289 elif self.orig_type is STRING:
4290 if vis and self.user_value is not None:
4291 # If the symbol is visible and has a user value, use that
4292 val = self.user_value
4294 # Otherwise, look at defaults
4295 for sym, cond in self.defaults:
4296 if expr_value(cond):
4298 self._write_to_conf = True
4301 # env_var corresponds to SYMBOL_AUTO in the C implementation, and is
4302 # also set on the defconfig_list symbol there. Test for the
4303 # defconfig_list symbol explicitly instead here, to avoid a nonsensical
4304 # env_var setting and the defconfig_list symbol being printed
4305 # incorrectly. This code is pretty cold anyway.
4306 if self.env_var is not None or self is self.kconfig.defconfig_list:
4307 self._write_to_conf = False
4309 self._cached_str_val = val
4313 def tri_value(self):
4315 See the class documentation.
4317 if self._cached_tri_val is not None:
4318 return self._cached_tri_val
4320 if self.orig_type not in _BOOL_TRISTATE:
4321 if self.orig_type: # != UNKNOWN
4322 # Would take some work to give the location here
4324 "The {} symbol {} is being evaluated in a logical context "
4325 "somewhere. It will always evaluate to n."
4326 .format(TYPE_TO_STR[self.orig_type], _name_and_loc(self)))
4328 self._cached_tri_val = 0
4331 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
4332 # function call (property magic)
4333 vis = self.visibility
4334 self._write_to_conf = (vis != 0)
4341 if vis and self.user_value is not None:
4342 # If the symbol is visible and has a user value, use that
4343 val = min(self.user_value, vis)
4346 # Otherwise, look at defaults and weak reverse dependencies
4349 for default, cond in self.defaults:
4350 dep_val = expr_value(cond)
4352 val = min(expr_value(default), dep_val)
4354 self._write_to_conf = True
4357 # Weak reverse dependencies are only considered if our
4358 # direct dependencies are met
4359 dep_val = expr_value(self.weak_rev_dep)
4360 if dep_val and expr_value(self.direct_dep):
4361 val = max(dep_val, val)
4362 self._write_to_conf = True
4364 # Reverse (select-related) dependencies take precedence
4365 dep_val = expr_value(self.rev_dep)
4367 if expr_value(self.direct_dep) < dep_val:
4368 self._warn_select_unsatisfied_deps()
4370 val = max(dep_val, val)
4371 self._write_to_conf = True
4373 # m is promoted to y for (1) bool symbols and (2) symbols with a
4374 # weak_rev_dep (from imply) of y
4376 (self.type is BOOL or expr_value(self.weak_rev_dep) == 2):
4380 # Visible choice symbol in y-mode choice. The choice mode limits
4381 # the visibility of choice symbols, so it's sufficient to just
4382 # check the visibility of the choice symbols themselves.
4383 val = 2 if self.choice.selection is self else 0
4385 elif vis and self.user_value:
4386 # Visible choice symbol in m-mode choice, with set non-0 user value
4389 self._cached_tri_val = val
4393 def assignable(self):
4395 See the class documentation.
4397 if self._cached_assignable is None:
4398 self._cached_assignable = self._assignable()
4399 return self._cached_assignable
4402 def visibility(self):
4404 See the class documentation.
4406 if self._cached_vis is None:
4407 self._cached_vis = _visibility(self)
4408 return self._cached_vis
4411 def config_string(self):
4413 See the class documentation.
4415 # _write_to_conf is determined when the value is calculated. This is a
4416 # hidden function call due to property magic.
4417 val = self.str_value
4418 if not self._write_to_conf:
4421 if self.orig_type in _BOOL_TRISTATE:
4422 return "{}{}={}\n" \
4423 .format(self.kconfig.config_prefix, self.name, val) \
4424 if val != "n" else \
4425 "# {}{} is not set\n" \
4426 .format(self.kconfig.config_prefix, self.name)
4428 if self.orig_type in _INT_HEX:
4429 return "{}{}={}\n" \
4430 .format(self.kconfig.config_prefix, self.name, val)
4432 # sym.orig_type is STRING
4433 return '{}{}="{}"\n' \
4434 .format(self.kconfig.config_prefix, self.name, escape(val))
4436 def set_value(self, value):
4438 Sets the user value of the symbol.
4440 Equal in effect to assigning the value to the symbol within a .config
4441 file. For bool and tristate symbols, use the 'assignable' attribute to
4442 check which values can currently be assigned. Setting values outside
4443 'assignable' will cause Symbol.user_value to differ from
4444 Symbol.str/tri_value (be truncated down or up).
4446 Setting a choice symbol to 2 (y) sets Choice.user_selection to the
4447 choice symbol in addition to setting Symbol.user_value.
4448 Choice.user_selection is considered when the choice is in y mode (the
4451 Other symbols that depend (possibly indirectly) on this symbol are
4452 automatically recalculated to reflect the assigned value.
4455 The user value to give to the symbol. For bool and tristate symbols,
4456 n/m/y can be specified either as 0/1/2 (the usual format for tristate
4457 values in Kconfiglib) or as one of the strings "n"/"m"/"y". For other
4458 symbol types, pass a string.
4460 Note that the value for an int/hex symbol is passed as a string, e.g.
4461 "123" or "0x0123". The format of this string is preserved in the
4464 Values that are invalid for the type (such as "foo" or 1 (m) for a
4465 BOOL or "0x123" for an INT) are ignored and won't be stored in
4466 Symbol.user_value. Kconfiglib will print a warning by default for
4467 invalid assignments, and set_value() will return False.
4469 Returns True if the value is valid for the type of the symbol, and
4470 False otherwise. This only looks at the form of the value. For BOOL and
4471 TRISTATE symbols, check the Symbol.assignable attribute to see what
4472 values are currently in range and would actually be reflected in the
4473 value of the symbol. For other symbol types, check whether the
4474 visibility is non-n.
4476 if self.orig_type in _BOOL_TRISTATE and value in STR_TO_TRI:
4477 value = STR_TO_TRI[value]
4479 # If the new user value matches the old, nothing changes, and we can
4480 # avoid invalidating cached values.
4482 # This optimization is skipped for choice symbols: Setting a choice
4483 # symbol's user value to y might change the state of the choice, so it
4484 # wouldn't be safe (symbol user values always match the values set in a
4485 # .config file or via set_value(), and are never implicitly updated).
4486 if value == self.user_value and not self.choice:
4487 self._was_set = True
4490 # Check if the value is valid for our type
4491 if not (self.orig_type is BOOL and value in (2, 0) or
4492 self.orig_type is TRISTATE and value in TRI_TO_STR or
4493 value.__class__ is str and
4494 (self.orig_type is STRING or
4495 self.orig_type is INT and _is_base_n(value, 10) or
4496 self.orig_type is HEX and _is_base_n(value, 16)
4497 and int(value, 16) >= 0)):
4499 # Display tristate values as n, m, y in the warning
4501 "the value {} is invalid for {}, which has type {} -- "
4502 "assignment ignored"
4503 .format(TRI_TO_STR[value] if value in TRI_TO_STR else
4504 "'{}'".format(value),
4505 _name_and_loc(self), TYPE_TO_STR[self.orig_type]))
4509 self.user_value = value
4510 self._was_set = True
4512 if self.choice and value == 2:
4513 # Setting a choice symbol to y makes it the user selection of the
4514 # choice. Like for symbol user values, the user selection is not
4515 # guaranteed to match the actual selection of the choice, as
4516 # dependencies come into play.
4517 self.choice.user_selection = self
4518 self.choice._was_set = True
4519 self.choice._rec_invalidate()
4521 self._rec_invalidate_if_has_prompt()
4525 def unset_value(self):
4527 Removes any user value from the symbol, as if the symbol had never
4528 gotten a user value via Kconfig.load_config() or Symbol.set_value().
4530 if self.user_value is not None:
4531 self.user_value = None
4532 self._rec_invalidate_if_has_prompt()
4535 def referenced(self):
4537 See the class documentation.
4539 return {item for node in self.nodes for item in node.referenced}
4542 def orig_defaults(self):
4544 See the class documentation.
4546 return [d for node in self.nodes for d in node.orig_defaults]
4549 def orig_selects(self):
4551 See the class documentation.
4553 return [s for node in self.nodes for s in node.orig_selects]
4556 def orig_implies(self):
4558 See the class documentation.
4560 return [i for node in self.nodes for i in node.orig_implies]
4563 def orig_ranges(self):
4565 See the class documentation.
4567 return [r for node in self.nodes for r in node.orig_ranges]
4571 Returns a string with information about the symbol (including its name,
4572 value, visibility, and location(s)) when it is evaluated on e.g. the
4573 interactive Python prompt.
4575 fields = ["symbol " + self.name, TYPE_TO_STR[self.type]]
4578 for node in self.nodes:
4580 add('"{}"'.format(node.prompt[0]))
4582 # Only add quotes for non-bool/tristate symbols
4583 add("value " + (self.str_value if self.orig_type in _BOOL_TRISTATE
4584 else '"{}"'.format(self.str_value)))
4586 if not self.is_constant:
4587 # These aren't helpful to show for constant symbols
4589 if self.user_value is not None:
4590 # Only add quotes for non-bool/tristate symbols
4591 add("user value " + (TRI_TO_STR[self.user_value]
4592 if self.orig_type in _BOOL_TRISTATE
4593 else '"{}"'.format(self.user_value)))
4595 add("visibility " + TRI_TO_STR[self.visibility])
4598 add("choice symbol")
4600 if self.is_allnoconfig_y:
4601 add("allnoconfig_y")
4603 if self is self.kconfig.defconfig_list:
4604 add("is the defconfig_list symbol")
4606 if self.env_var is not None:
4607 add("from environment variable " + self.env_var)
4609 if self is self.kconfig.modules:
4610 add("is the modules symbol")
4612 add("direct deps " + TRI_TO_STR[expr_value(self.direct_dep)])
4615 for node in self.nodes:
4616 add("{}:{}".format(node.filename, node.linenr))
4618 add("constant" if self.is_constant else "undefined")
4620 return "<{}>".format(", ".join(fields))
4624 Returns a string representation of the symbol when it is printed.
4625 Matches the Kconfig format, with any parent dependencies propagated to
4626 the 'depends on' condition.
4628 The string is constructed by joining the strings returned by
4629 MenuNode.__str__() for each of the symbol's menu nodes, so symbols
4630 defined in multiple locations will return a string with all
4633 The returned string does not end in a newline. An empty string is
4634 returned for undefined and constant symbols.
4636 return self.custom_str(standard_sc_expr_str)
4638 def custom_str(self, sc_expr_str_fn):
4640 Works like Symbol.__str__(), but allows a custom format to be used for
4641 all symbol/choice references. See expr_str().
4643 return "\n\n".join(node.custom_str(sc_expr_str_fn)
4644 for node in self.nodes)
4652 Symbol constructor -- not intended to be called directly by Kconfiglib
4655 # These attributes are always set on the instance from outside and
4656 # don't need defaults:
4665 # - _visited is used during tree iteration and dep. loop detection
4666 self.orig_type = self._visited = 0
4678 self._cached_str_val = self._cached_tri_val = self._cached_vis = \
4679 self._cached_assignable = None
4681 # _write_to_conf is calculated along with the value. If True, the
4682 # Symbol gets a .config entry.
4684 self.is_allnoconfig_y = \
4686 self._write_to_conf = False
4688 # See Kconfig._build_dep()
4689 self._dependents = set()
4691 def _assignable(self):
4692 # Worker function for the 'assignable' attribute
4694 if self.orig_type not in _BOOL_TRISTATE:
4697 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
4698 # function call (property magic)
4699 vis = self.visibility
4703 rev_dep_val = expr_value(self.rev_dep)
4710 if self.type is BOOL or expr_value(self.weak_rev_dep) == 2:
4714 if rev_dep_val == 2:
4719 if self.type is BOOL or expr_value(self.weak_rev_dep) == 2:
4725 # Must be a tristate here, because bool m visibility gets promoted to y
4728 return (0, 1) if expr_value(self.weak_rev_dep) != 2 else (0, 2)
4730 if rev_dep_val == 2:
4733 # vis == rev_dep_val == 1
4737 def _invalidate(self):
4738 # Marks the symbol as needing to be recalculated
4740 self._cached_str_val = self._cached_tri_val = self._cached_vis = \
4741 self._cached_assignable = None
4743 def _rec_invalidate(self):
4744 # Invalidates the symbol and all items that (possibly) depend on it
4746 if self is self.kconfig.modules:
4747 # Invalidating MODULES has wide-ranging effects
4748 self.kconfig._invalidate_all()
4752 for item in self._dependents:
4753 # _cached_vis doubles as a flag that tells us whether 'item'
4754 # has cached values, because it's calculated as a side effect
4755 # of calculating all other (non-constant) cached values.
4757 # If item._cached_vis is None, it means there can't be cached
4758 # values on other items that depend on 'item', because if there
4759 # were, some value on 'item' would have been calculated and
4760 # item._cached_vis set as a side effect. It's therefore safe to
4761 # stop the invalidation at symbols with _cached_vis None.
4763 # This approach massively speeds up scripts that set a lot of
4764 # values, vs simply invalidating all possibly dependent symbols
4765 # (even when you already have a list of all the dependent
4766 # symbols, because some symbols get huge dependency trees).
4768 # This gracefully handles dependency loops too, which is nice
4769 # for choices, where the choice depends on the choice symbols
4771 if item._cached_vis is not None:
4772 item._rec_invalidate()
4774 def _rec_invalidate_if_has_prompt(self):
4775 # Invalidates the symbol and its dependent symbols, but only if the
4776 # symbol has a prompt. User values never have an effect on promptless
4777 # symbols, so we skip invalidation for them as an optimization.
4779 # This also prevents constant (quoted) symbols from being invalidated
4780 # if set_value() is called on them, which would make them lose their
4781 # value and break things.
4783 # Prints a warning if the symbol has no prompt. In some contexts (e.g.
4784 # when loading a .config files) assignments to promptless symbols are
4785 # normal and expected, so the warning can be disabled.
4787 for node in self.nodes:
4789 self._rec_invalidate()
4792 if self.kconfig._warn_assign_no_prompt:
4793 self.kconfig._warn(_name_and_loc(self) + " has no prompt, meaning "
4794 "user values have no effect on it")
4796 def _str_default(self):
4797 # write_min_config() helper function. Returns the value the symbol
4798 # would get from defaults if it didn't have a user value. Uses exactly
4799 # the same algorithm as the C implementation (though a bit cleaned up),
4800 # for compatibility.
4802 if self.orig_type in _BOOL_TRISTATE:
4805 # Defaults, selects, and implies do not affect choice symbols
4807 for default, cond in self.defaults:
4808 cond_val = expr_value(cond)
4810 val = min(expr_value(default), cond_val)
4813 val = max(expr_value(self.rev_dep),
4814 expr_value(self.weak_rev_dep),
4817 # Transpose mod to yes if type is bool (possibly due to modules
4819 if val == 1 and self.type is BOOL:
4822 return TRI_TO_STR[val]
4824 if self.orig_type: # STRING/INT/HEX
4825 for default, cond in self.defaults:
4826 if expr_value(cond):
4827 return default.str_value
4831 def _warn_select_unsatisfied_deps(self):
4832 # Helper for printing an informative warning when a symbol with
4833 # unsatisfied direct dependencies (dependencies from 'depends on', ifs,
4834 # and menus) is selected by some other symbol. Also warn if a symbol
4835 # whose direct dependencies evaluate to m is selected to y.
4837 msg = "{} has direct dependencies {} with value {}, but is " \
4838 "currently being {}-selected by the following symbols:" \
4839 .format(_name_and_loc(self), expr_str(self.direct_dep),
4840 TRI_TO_STR[expr_value(self.direct_dep)],
4841 TRI_TO_STR[expr_value(self.rev_dep)])
4843 # The reverse dependencies from each select are ORed together
4844 for select in split_expr(self.rev_dep, OR):
4845 if expr_value(select) <= expr_value(self.direct_dep):
4846 # Only include selects that exceed the direct dependencies
4849 # - 'select A if B' turns into A && B
4850 # - 'select A' just turns into A
4852 # In both cases, we can split on AND and pick the first operand
4853 selecting_sym = split_expr(select, AND)[0]
4855 msg += "\n - {}, with value {}, direct dependencies {} " \
4857 .format(_name_and_loc(selecting_sym),
4858 selecting_sym.str_value,
4859 expr_str(selecting_sym.direct_dep),
4860 TRI_TO_STR[expr_value(selecting_sym.direct_dep)])
4862 if select.__class__ is tuple:
4863 msg += ", and select condition {} (value: {})" \
4864 .format(expr_str(select[2]),
4865 TRI_TO_STR[expr_value(select[2])])
4867 self.kconfig._warn(msg)
4870 class Choice(object):
4872 Represents a choice statement:
4878 The following attributes are available on Choice instances. They should be
4879 treated as read-only, and some are implemented through @property magic (but
4880 are still efficient to access due to internal caching).
4882 Note: Prompts, help texts, and locations are stored in the Choice's
4883 MenuNode(s) rather than in the Choice itself. Check the MenuNode class and
4884 the Choice.nodes attribute. This organization matches the C tools.
4887 The name of the choice, e.g. "FOO" for 'choice FOO', or None if the
4891 The type of the choice. One of BOOL, TRISTATE, UNKNOWN. UNKNOWN is for
4892 choices defined without a type where none of the contained symbols have a
4893 type either (otherwise the choice inherits the type of the first symbol
4894 defined with a type).
4896 When running without modules (CONFIG_MODULES=n), TRISTATE choices
4897 magically change type to BOOL. This matches the C tools, and makes sense
4898 for menuconfig-like functionality.
4901 The type as given in the Kconfig file, without any magic applied. Used
4902 when printing the choice.
4905 The tristate value (mode) of the choice. A choice can be in one of three
4908 0 (n) - The choice is disabled and no symbols can be selected. For
4909 visible choices, this mode is only possible for choices with
4910 the 'optional' flag set (see kconfig-language.txt).
4912 1 (m) - Any number of choice symbols can be set to m, the rest will
4915 2 (y) - One symbol will be y, the rest n.
4917 Only tristate choices can be in m mode. The visibility of the choice is
4918 an upper bound on the mode, and the mode in turn is an upper bound on the
4919 visibility of the choice symbols.
4921 To change the mode, use Choice.set_value().
4923 Implementation note:
4924 The C tools internally represent choices as a type of symbol, with
4925 special-casing in many code paths. This is why there is a lot of
4926 similarity to Symbol. The value (mode) of a choice is really just a
4927 normal symbol value, and an implicit reverse dependency forces its
4928 lower bound to m for visible non-optional choices (the reverse
4929 dependency is 'm && <visibility>').
4931 Symbols within choices get the choice propagated as a dependency to
4932 their properties. This turns the mode of the choice into an upper bound
4933 on e.g. the visibility of choice symbols, and explains the gotcha
4934 related to printing choice symbols mentioned in the module docstring.
4936 Kconfiglib uses a separate Choice class only because it makes the code
4937 and interface less confusing (especially in a user-facing interface).
4938 Corresponding attributes have the same name in the Symbol and Choice
4939 classes, for consistency and compatibility.
4942 See the symbol class documentation. Gives the assignable values (modes).
4945 See the Symbol class documentation. Acts on the value (mode).
4948 The Symbol instance of the currently selected symbol. None if the Choice
4949 is not in y mode or has no selected symbol (due to unsatisfied
4950 dependencies on choice symbols).
4952 WARNING: Do not assign directly to this. It will break things. Call
4953 sym.set_value(2) on the choice symbol you want to select instead.
4956 The value (mode) selected by the user through Choice.set_value(). Either
4957 0, 1, or 2, or None if the user hasn't selected a mode. See
4960 WARNING: Do not assign directly to this. It will break things. Use
4961 Choice.set_value() instead.
4964 The symbol selected by the user (by setting it to y). Ignored if the
4965 choice is not in y mode, but still remembered so that the choice "snaps
4966 back" to the user selection if the mode is changed back to y. This might
4967 differ from 'selection' due to unsatisfied dependencies.
4969 WARNING: Do not assign directly to this. It will break things. Call
4970 sym.set_value(2) on the choice symbol to be selected instead.
4973 List of symbols contained in the choice.
4975 Obscure gotcha: If a symbol depends on the previous symbol within a
4976 choice so that an implicit menu is created, it won't be a choice symbol,
4977 and won't be included in 'syms'.
4980 A list of MenuNodes for this choice. In practice, the list will probably
4981 always contain a single MenuNode, but it is possible to give a choice a
4982 name and define it in multiple locations.
4985 List of (symbol, cond) tuples for the choice's 'defaults' properties. For
4986 example, 'default A if B && C' is represented as (A, (AND, B, C)). If
4987 there is no condition, 'cond' is self.kconfig.y.
4989 Note that 'depends on' and parent dependencies are propagated to
4990 'default' conditions.
4993 See the corresponding attribute on the MenuNode class.
4996 See Symbol.direct_dep.
4999 A set() with all symbols referenced in the properties and property
5000 conditions of the choice.
5002 Also includes dependencies from surrounding menus and ifs, because those
5003 get propagated to the choice (see the 'Intro to symbol values' section in
5004 the module docstring).
5007 True if the choice has the 'optional' flag set on it and can be in
5011 The Kconfig instance this choice is from.
5014 "_cached_assignable",
5015 "_cached_selection",
5040 Returns the type of the choice. See Symbol.type.
5042 if self.orig_type is TRISTATE and not self.kconfig.modules.tri_value:
5044 return self.orig_type
5047 def str_value(self):
5049 See the class documentation.
5051 return TRI_TO_STR[self.tri_value]
5054 def tri_value(self):
5056 See the class documentation.
5058 # This emulates a reverse dependency of 'm && visibility' for
5059 # non-optional choices, which is how the C implementation does it
5061 val = 0 if self.is_optional else 1
5063 if self.user_value is not None:
5064 val = max(val, self.user_value)
5066 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
5067 # function call (property magic)
5068 val = min(val, self.visibility)
5070 # Promote m to y for boolean choices
5071 return 2 if val == 1 and self.type is BOOL else val
5074 def assignable(self):
5076 See the class documentation.
5078 if self._cached_assignable is None:
5079 self._cached_assignable = self._assignable()
5080 return self._cached_assignable
5083 def visibility(self):
5085 See the class documentation.
5087 if self._cached_vis is None:
5088 self._cached_vis = _visibility(self)
5089 return self._cached_vis
5092 def selection(self):
5094 See the class documentation.
5096 if self._cached_selection is _NO_CACHED_SELECTION:
5097 self._cached_selection = self._selection()
5098 return self._cached_selection
5100 def set_value(self, value):
5102 Sets the user value (mode) of the choice. Like for Symbol.set_value(),
5103 the visibility might truncate the value. Choices without the 'optional'
5104 attribute (is_optional) can never be in n mode, but 0/"n" is still
5105 accepted since it's not a malformed value (though it will have no
5108 Returns True if the value is valid for the type of the choice, and
5109 False otherwise. This only looks at the form of the value. Check the
5110 Choice.assignable attribute to see what values are currently in range
5111 and would actually be reflected in the mode of the choice.
5113 if value in STR_TO_TRI:
5114 value = STR_TO_TRI[value]
5116 if value == self.user_value:
5117 # We know the value must be valid if it was successfully set
5119 self._was_set = True
5122 if not (self.orig_type is BOOL and value in (2, 0) or
5123 self.orig_type is TRISTATE and value in TRI_TO_STR):
5125 # Display tristate values as n, m, y in the warning
5127 "the value {} is invalid for {}, which has type {} -- "
5128 "assignment ignored"
5129 .format(TRI_TO_STR[value] if value in TRI_TO_STR else
5130 "'{}'".format(value),
5131 _name_and_loc(self), TYPE_TO_STR[self.orig_type]))
5135 self.user_value = value
5136 self._was_set = True
5137 self._rec_invalidate()
5141 def unset_value(self):
5143 Resets the user value (mode) and user selection of the Choice, as if
5144 the user had never touched the mode or any of the choice symbols.
5146 if self.user_value is not None or self.user_selection:
5147 self.user_value = self.user_selection = None
5148 self._rec_invalidate()
5151 def referenced(self):
5153 See the class documentation.
5155 return {item for node in self.nodes for item in node.referenced}
5158 def orig_defaults(self):
5160 See the class documentation.
5162 return [d for node in self.nodes for d in node.orig_defaults]
5166 Returns a string with information about the choice when it is evaluated
5167 on e.g. the interactive Python prompt.
5169 fields = ["choice " + self.name if self.name else "choice",
5170 TYPE_TO_STR[self.type]]
5173 for node in self.nodes:
5175 add('"{}"'.format(node.prompt[0]))
5177 add("mode " + self.str_value)
5179 if self.user_value is not None:
5180 add('user mode {}'.format(TRI_TO_STR[self.user_value]))
5183 add("{} selected".format(self.selection.name))
5185 if self.user_selection:
5186 user_sel_str = "{} selected by user" \
5187 .format(self.user_selection.name)
5189 if self.selection is not self.user_selection:
5190 user_sel_str += " (overridden)"
5194 add("visibility " + TRI_TO_STR[self.visibility])
5196 if self.is_optional:
5199 for node in self.nodes:
5200 add("{}:{}".format(node.filename, node.linenr))
5202 return "<{}>".format(", ".join(fields))
5206 Returns a string representation of the choice when it is printed.
5207 Matches the Kconfig format (though without the contained choice
5208 symbols), with any parent dependencies propagated to the 'depends on'
5211 The returned string does not end in a newline.
5213 See Symbol.__str__() as well.
5215 return self.custom_str(standard_sc_expr_str)
5217 def custom_str(self, sc_expr_str_fn):
5219 Works like Choice.__str__(), but allows a custom format to be used for
5220 all symbol/choice references. See expr_str().
5222 return "\n\n".join(node.custom_str(sc_expr_str_fn)
5223 for node in self.nodes)
5231 Choice constructor -- not intended to be called directly by Kconfiglib
5234 # These attributes are always set on the instance from outside and
5235 # don't need defaults:
5240 # - _visited is used during dep. loop detection
5241 self.orig_type = self._visited = 0
5249 self.user_value = self.user_selection = \
5250 self._cached_vis = self._cached_assignable = None
5252 self._cached_selection = _NO_CACHED_SELECTION
5254 # is_constant is checked by _make_depend_on(). Just set it to avoid
5255 # having to special-case choices.
5256 self.is_constant = self.is_optional = False
5258 # See Kconfig._build_dep()
5259 self._dependents = set()
5261 def _assignable(self):
5262 # Worker function for the 'assignable' attribute
5264 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
5265 # function call (property magic)
5266 vis = self.visibility
5272 if not self.is_optional:
5273 return (2,) if self.type is BOOL else (1, 2)
5274 return (0, 2) if self.type is BOOL else (0, 1, 2)
5278 return (0, 1) if self.is_optional else (1,)
5280 def _selection(self):
5281 # Worker function for the 'selection' attribute
5283 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
5284 # function call (property magic)
5285 if self.tri_value != 2:
5286 # Not in y mode, so no selection
5289 # Use the user selection if it's visible
5290 if self.user_selection and self.user_selection.visibility:
5291 return self.user_selection
5293 # Otherwise, check if we have a default
5294 return self._selection_from_defaults()
5296 def _selection_from_defaults(self):
5297 # Check if we have a default
5298 for sym, cond in self.defaults:
5299 # The default symbol must be visible too
5300 if expr_value(cond) and sym.visibility:
5303 # Otherwise, pick the first visible symbol, if any
5304 for sym in self.syms:
5308 # Couldn't find a selection
5311 def _invalidate(self):
5312 self._cached_vis = self._cached_assignable = None
5313 self._cached_selection = _NO_CACHED_SELECTION
5315 def _rec_invalidate(self):
5316 # See Symbol._rec_invalidate()
5320 for item in self._dependents:
5321 if item._cached_vis is not None:
5322 item._rec_invalidate()
5325 class MenuNode(object):
5327 Represents a menu node in the configuration. This corresponds to an entry
5328 in e.g. the 'make menuconfig' interface, though non-visible choices, menus,
5329 and comments also get menu nodes. If a symbol or choice is defined in
5330 multiple locations, it gets one menu node for each location.
5332 The top-level menu node, corresponding to the implicit top-level menu, is
5333 available in Kconfig.top_node.
5335 The menu nodes for a Symbol or Choice can be found in the
5336 Symbol/Choice.nodes attribute. Menus and comments are represented as plain
5337 menu nodes, with their text stored in the prompt attribute (prompt[0]).
5338 This mirrors the C implementation.
5340 The following attributes are available on MenuNode instances. They should
5341 be viewed as read-only.
5344 Either a Symbol, a Choice, or one of the constants MENU and COMMENT.
5345 Menus and comments are represented as plain menu nodes. Ifs are collapsed
5346 (matching the C implementation) and do not appear in the final menu tree.
5349 The following menu node. None if there is no following node.
5352 The first child menu node. None if there are no children.
5354 Choices and menus naturally have children, but Symbols can also have
5355 children because of menus created automatically from dependencies (see
5356 kconfig-language.txt).
5359 The parent menu node. None if there is no parent.
5362 A (string, cond) tuple with the prompt for the menu node and its
5363 conditional expression (which is self.kconfig.y if there is no
5364 condition). None if there is no prompt.
5366 For symbols and choices, the prompt is stored in the MenuNode rather than
5367 the Symbol or Choice instance. For menus and comments, the prompt holds
5371 The 'default' properties for this particular menu node. See
5374 When evaluating defaults, you should use Symbol/Choice.defaults instead,
5375 as it include properties from all menu nodes (a symbol/choice can have
5376 multiple definition locations/menu nodes). MenuNode.defaults is meant for
5377 documentation generation.
5380 Like MenuNode.defaults, for selects.
5383 Like MenuNode.defaults, for implies.
5386 Like MenuNode.defaults, for ranges.
5393 These work the like the corresponding attributes without orig_*, but omit
5394 any dependencies propagated from 'depends on' and surrounding 'if's (the
5395 direct dependencies, stored in MenuNode.dep).
5397 One use for this is generating less cluttered documentation, by only
5398 showing the direct dependencies in one place.
5401 The help text for the menu node for Symbols and Choices. None if there is
5402 no help text. Always stored in the node rather than the Symbol or Choice.
5403 It is possible to have a separate help text at each location if a symbol
5404 is defined in multiple locations.
5406 Trailing whitespace (including a final newline) is stripped from the help
5407 text. This was not the case before Kconfiglib 10.21.0, where the format
5411 The direct ('depends on') dependencies for the menu node, or
5412 self.kconfig.y if there are no direct dependencies.
5414 This attribute includes any dependencies from surrounding menus and ifs.
5415 Those get propagated to the direct dependencies, and the resulting direct
5416 dependencies in turn get propagated to the conditions of all properties.
5418 If a symbol or choice is defined in multiple locations, only the
5419 properties defined at a particular location get the corresponding
5420 MenuNode.dep dependencies propagated to them.
5423 The 'visible if' dependencies for the menu node (which must represent a
5424 menu), or self.kconfig.y if there are no 'visible if' dependencies.
5425 'visible if' dependencies are recursively propagated to the prompts of
5426 symbols and choices within the menu.
5429 A set() with all symbols and choices referenced in the properties and
5430 property conditions of the menu node.
5432 Also includes dependencies inherited from surrounding menus and ifs.
5433 Choices appear in the dependencies of choice symbols.
5436 Set to True if the children of the menu node should be displayed in a
5437 separate menu. This is the case for the following items:
5439 - Menus (node.item == MENU)
5443 - Symbols defined with the 'menuconfig' keyword. The children come from
5444 implicitly created submenus, and should be displayed in a separate
5445 menu rather than being indented.
5447 'is_menuconfig' is just a hint on how to display the menu node. It's
5448 ignored internally by Kconfiglib, except when printing symbols.
5451 The location where the menu node appears. The filename is relative to
5452 $srctree (or to the current directory if $srctree isn't set), except
5453 absolute paths are used for paths outside $srctree.
5456 A tuple of (filename, linenr) tuples, giving the locations of the
5457 'source' statements via which the Kconfig file containing this menu node
5458 was included. The first element is the location of the 'source' statement
5459 in the top-level Kconfig file passed to Kconfig.__init__(), etc.
5461 Note that the Kconfig file of the menu node itself isn't included. Check
5462 'filename' and 'linenr' for that.
5465 The Kconfig instance the menu node is from.
5490 # Properties defined on this particular menu node. A local 'depends on'
5491 # only applies to these, in case a symbol is defined in multiple
5499 def orig_prompt(self):
5501 See the class documentation.
5505 return (self.prompt[0], self._strip_dep(self.prompt[1]))
5508 def orig_defaults(self):
5510 See the class documentation.
5512 return [(default, self._strip_dep(cond))
5513 for default, cond in self.defaults]
5516 def orig_selects(self):
5518 See the class documentation.
5520 return [(select, self._strip_dep(cond))
5521 for select, cond in self.selects]
5524 def orig_implies(self):
5526 See the class documentation.
5528 return [(imply, self._strip_dep(cond))
5529 for imply, cond in self.implies]
5532 def orig_ranges(self):
5534 See the class documentation.
5536 return [(low, high, self._strip_dep(cond))
5537 for low, high, cond in self.ranges]
5540 def referenced(self):
5542 See the class documentation.
5544 # self.dep is included to catch dependencies from a lone 'depends on'
5545 # when there are no properties to propagate it to
5546 res = expr_items(self.dep)
5549 res |= expr_items(self.prompt[1])
5551 if self.item is MENU:
5552 res |= expr_items(self.visibility)
5554 for value, cond in self.defaults:
5555 res |= expr_items(value)
5556 res |= expr_items(cond)
5558 for value, cond in self.selects:
5560 res |= expr_items(cond)
5562 for value, cond in self.implies:
5564 res |= expr_items(cond)
5566 for low, high, cond in self.ranges:
5569 res |= expr_items(cond)
5575 Returns a string with information about the menu node when it is
5576 evaluated on e.g. the interactive Python prompt.
5581 if self.item.__class__ is Symbol:
5582 add("menu node for symbol " + self.item.name)
5584 elif self.item.__class__ is Choice:
5585 s = "menu node for choice"
5586 if self.item.name is not None:
5587 s += " " + self.item.name
5590 elif self.item is MENU:
5591 add("menu node for menu")
5593 else: # self.item is COMMENT
5594 add("menu node for comment")
5597 add('prompt "{}" (visibility {})'.format(
5598 self.prompt[0], TRI_TO_STR[expr_value(self.prompt[1])]))
5600 if self.item.__class__ is Symbol and self.is_menuconfig:
5601 add("is menuconfig")
5603 add("deps " + TRI_TO_STR[expr_value(self.dep)])
5605 if self.item is MENU:
5606 add("'visible if' deps " + TRI_TO_STR[expr_value(self.visibility)])
5608 if self.item.__class__ in _SYMBOL_CHOICE and self.help is not None:
5617 add("{}:{}".format(self.filename, self.linenr))
5619 return "<{}>".format(", ".join(fields))
5623 Returns a string representation of the menu node. Matches the Kconfig
5624 format, with any parent dependencies propagated to the 'depends on'
5627 The output could (almost) be fed back into a Kconfig parser to redefine
5628 the object associated with the menu node. See the module documentation
5629 for a gotcha related to choice symbols.
5631 For symbols and choices with multiple menu nodes (multiple definition
5632 locations), properties that aren't associated with a particular menu
5633 node are shown on all menu nodes ('option env=...', 'optional' for
5636 The returned string does not end in a newline.
5638 return self.custom_str(standard_sc_expr_str)
5640 def custom_str(self, sc_expr_str_fn):
5642 Works like MenuNode.__str__(), but allows a custom format to be used
5643 for all symbol/choice references. See expr_str().
5645 return self._menu_comment_node_str(sc_expr_str_fn) \
5646 if self.item in _MENU_COMMENT else \
5647 self._sym_choice_node_str(sc_expr_str_fn)
5649 def _menu_comment_node_str(self, sc_expr_str_fn):
5650 s = '{} "{}"'.format("menu" if self.item is MENU else "comment",
5653 if self.dep is not self.kconfig.y:
5654 s += "\n\tdepends on {}".format(expr_str(self.dep, sc_expr_str_fn))
5656 if self.item is MENU and self.visibility is not self.kconfig.y:
5657 s += "\n\tvisible if {}".format(expr_str(self.visibility,
5662 def _sym_choice_node_str(self, sc_expr_str_fn):
5664 lines.append("\t" + s)
5666 def indent_add_cond(s, cond):
5667 if cond is not self.kconfig.y:
5668 s += " if " + expr_str(cond, sc_expr_str_fn)
5673 if sc.__class__ is Symbol:
5674 lines = [("menuconfig " if self.is_menuconfig else "config ")
5677 lines = ["choice " + sc.name if sc.name else "choice"]
5679 if sc.orig_type and not self.prompt: # sc.orig_type != UNKNOWN
5680 # If there's a prompt, we'll use the '<type> "prompt"' shorthand
5682 indent_add(TYPE_TO_STR[sc.orig_type])
5686 prefix = TYPE_TO_STR[sc.orig_type]
5688 # Symbol defined without a type (which generates a warning)
5691 indent_add_cond(prefix + ' "{}"'.format(escape(self.prompt[0])),
5692 self.orig_prompt[1])
5694 if sc.__class__ is Symbol:
5695 if sc.is_allnoconfig_y:
5696 indent_add("option allnoconfig_y")
5698 if sc is sc.kconfig.defconfig_list:
5699 indent_add("option defconfig_list")
5701 if sc.env_var is not None:
5702 indent_add('option env="{}"'.format(sc.env_var))
5704 if sc is sc.kconfig.modules:
5705 indent_add("option modules")
5707 for low, high, cond in self.orig_ranges:
5709 "range {} {}".format(sc_expr_str_fn(low),
5710 sc_expr_str_fn(high)),
5713 for default, cond in self.orig_defaults:
5714 indent_add_cond("default " + expr_str(default, sc_expr_str_fn),
5717 if sc.__class__ is Choice and sc.is_optional:
5718 indent_add("optional")
5720 if sc.__class__ is Symbol:
5721 for select, cond in self.orig_selects:
5722 indent_add_cond("select " + sc_expr_str_fn(select), cond)
5724 for imply, cond in self.orig_implies:
5725 indent_add_cond("imply " + sc_expr_str_fn(imply), cond)
5727 if self.dep is not sc.kconfig.y:
5728 indent_add("depends on " + expr_str(self.dep, sc_expr_str_fn))
5730 if self.help is not None:
5732 for line in self.help.splitlines():
5733 indent_add(" " + line)
5735 return "\n".join(lines)
5737 def _strip_dep(self, expr):
5738 # Helper function for removing MenuNode.dep from 'expr'. Uses two
5739 # pieces of internal knowledge: (1) Expressions are reused rather than
5740 # copied, and (2) the direct dependencies always appear at the end.
5742 # ... if dep -> ... if y
5743 if self.dep is expr:
5744 return self.kconfig.y
5746 # (AND, X, dep) -> X
5747 if expr.__class__ is tuple and expr[0] is AND and expr[2] is self.dep:
5753 class Variable(object):
5755 Represents a preprocessor variable/function.
5757 The following attributes are available:
5760 The name of the variable.
5763 The unexpanded value of the variable.
5766 The expanded value of the variable. For simple variables (those defined
5767 with :=), this will equal 'value'. Accessing this property will raise a
5768 KconfigError if the expansion seems to be stuck in a loop.
5770 Accessing this field is the same as calling expanded_value_w_args() with
5771 no arguments. I hadn't considered function arguments when adding it. It
5772 is retained for backwards compatibility though.
5775 True if the variable is recursive (defined with =).
5786 def expanded_value(self):
5788 See the class documentation.
5790 return self.expanded_value_w_args()
5792 def expanded_value_w_args(self, *args):
5794 Returns the expanded value of the variable/function. Any arguments
5795 passed will be substituted for $(1), $(2), etc.
5797 Raises a KconfigError if the expansion seems to be stuck in a loop.
5799 return self.kconfig._fn_val((self.name,) + args)
5802 return "<variable {}, {}, value '{}'>" \
5804 "recursive" if self.is_recursive else "immediate",
5808 class KconfigError(Exception):
5810 Exception raised for Kconfig-related errors.
5812 KconfigError and KconfigSyntaxError are the same class. The
5813 KconfigSyntaxError alias is only maintained for backwards compatibility.
5816 KconfigSyntaxError = KconfigError # Backwards compatibility
5819 class InternalError(Exception):
5820 "Never raised. Kept around for backwards compatibility."
5825 # If 'errno' and 'strerror' are set on IOError, then __str__() always returns
5826 # "[Errno <errno>] <strerror>", ignoring any custom message passed to the
5827 # constructor. By defining our own subclass, we can use a custom message while
5828 # also providing 'errno', 'strerror', and 'filename' to scripts.
5829 class _KconfigIOError(IOError):
5830 def __init__(self, ioerror, msg):
5832 super(_KconfigIOError, self).__init__(
5833 ioerror.errno, ioerror.strerror, ioerror.filename)
5844 def expr_value(expr):
5846 Evaluates the expression 'expr' to a tristate value. Returns 0 (n), 1 (m),
5849 'expr' must be an already-parsed expression from a Symbol, Choice, or
5850 MenuNode property. To evaluate an expression represented as a string, use
5851 Kconfig.eval_string().
5853 Passing subexpressions of expressions to this function works as expected.
5855 if expr.__class__ is not tuple:
5856 return expr.tri_value
5859 v1 = expr_value(expr[1])
5860 # Short-circuit the n case as an optimization (~5% faster
5861 # allnoconfig.py and allyesconfig.py, as of writing)
5862 return 0 if not v1 else min(v1, expr_value(expr[2]))
5865 v1 = expr_value(expr[1])
5866 # Short-circuit the y case as an optimization
5867 return 2 if v1 == 2 else max(v1, expr_value(expr[2]))
5870 return 2 - expr_value(expr[1])
5874 # Implements <, <=, >, >= comparisons as well. These were added to
5875 # kconfig in 31847b67 (kconfig: allow use of relations other than
5880 # If both operands are strings...
5881 if v1.orig_type is STRING and v2.orig_type is STRING:
5882 # ...then compare them lexicographically
5883 comp = _strcmp(v1.str_value, v2.str_value)
5885 # Otherwise, try to compare them as numbers
5887 comp = _sym_to_num(v1) - _sym_to_num(v2)
5889 # Fall back on a lexicographic comparison if the operands don't
5891 comp = _strcmp(v1.str_value, v2.str_value)
5893 return 2*(comp == 0 if rel is EQUAL else
5894 comp != 0 if rel is UNEQUAL else
5895 comp < 0 if rel is LESS else
5896 comp <= 0 if rel is LESS_EQUAL else
5897 comp > 0 if rel is GREATER else
5901 def standard_sc_expr_str(sc):
5903 Standard symbol/choice printing function. Uses plain Kconfig syntax, and
5904 displays choices as <choice> (or <choice NAME>, for named choices).
5908 if sc.__class__ is Symbol:
5909 if sc.is_constant and sc.name not in STR_TO_TRI:
5910 return '"{}"'.format(escape(sc.name))
5913 return "<choice {}>".format(sc.name) if sc.name else "<choice>"
5916 def expr_str(expr, sc_expr_str_fn=standard_sc_expr_str):
5918 Returns the string representation of the expression 'expr', as in a Kconfig
5921 Passing subexpressions of expressions to this function works as expected.
5923 sc_expr_str_fn (default: standard_sc_expr_str):
5924 This function is called for every symbol/choice (hence "sc") appearing in
5925 the expression, with the symbol/choice as the argument. It is expected to
5926 return a string to be used for the symbol/choice.
5928 This can be used e.g. to turn symbols/choices into links when generating
5929 documentation, or for printing the value of each symbol/choice after it.
5931 Note that quoted values are represented as constants symbols
5932 (Symbol.is_constant == True).
5934 if expr.__class__ is not tuple:
5935 return sc_expr_str_fn(expr)
5938 return "{} && {}".format(_parenthesize(expr[1], OR, sc_expr_str_fn),
5939 _parenthesize(expr[2], OR, sc_expr_str_fn))
5942 # This turns A && B || C && D into "(A && B) || (C && D)", which is
5943 # redundant, but more readable
5944 return "{} || {}".format(_parenthesize(expr[1], AND, sc_expr_str_fn),
5945 _parenthesize(expr[2], AND, sc_expr_str_fn))
5948 if expr[1].__class__ is tuple:
5949 return "!({})".format(expr_str(expr[1], sc_expr_str_fn))
5950 return "!" + sc_expr_str_fn(expr[1]) # Symbol
5954 # Relation operands are always symbols (quoted strings are constant
5956 return "{} {} {}".format(sc_expr_str_fn(expr[1]), REL_TO_STR[expr[0]],
5957 sc_expr_str_fn(expr[2]))
5960 def expr_items(expr):
5962 Returns a set() of all items (symbols and choices) that appear in the
5965 Passing subexpressions of expressions to this function works as expected.
5970 if subexpr.__class__ is tuple:
5971 # AND, OR, NOT, or relation
5975 # NOTs only have a single operand
5976 if subexpr[0] is not NOT:
5987 def split_expr(expr, op):
5989 Returns a list containing the top-level AND or OR operands in the
5990 expression 'expr', in the same (left-to-right) order as they appear in
5993 This can be handy e.g. for splitting (weak) reverse dependencies
5994 from 'select' and 'imply' into individual selects/implies.
5997 Either AND to get AND operands, or OR to get OR operands.
5999 (Having this as an operand might be more future-safe than having two
6000 hardcoded functions.)
6003 Pseudo-code examples:
6005 split_expr( A , OR ) -> [A]
6006 split_expr( A && B , OR ) -> [A && B]
6007 split_expr( A || B , OR ) -> [A, B]
6008 split_expr( A || B , AND ) -> [A || B]
6009 split_expr( A || B || (C && D) , OR ) -> [A, B, C && D]
6011 # Second || is not at the top level
6012 split_expr( A || (B && (C || D)) , OR ) -> [A, B && (C || D)]
6014 # Parentheses don't matter as long as we stay at the top level (don't
6015 # encounter any non-'op' nodes)
6016 split_expr( (A || B) || C , OR ) -> [A, B, C]
6017 split_expr( A || (B || C) , OR ) -> [A, B, C]
6022 if subexpr.__class__ is tuple and subexpr[0] is op:
6034 Escapes the string 's' in the same fashion as is done for display in
6035 Kconfig format and when writing strings to a .config file. " and \ are
6036 replaced by \" and \\, respectively.
6038 # \ must be escaped before " to avoid double escaping
6039 return s.replace("\\", r"\\").replace('"', r'\"')
6044 Unescapes the string 's'. \ followed by any character is replaced with just
6045 that character. Used internally when reading .config files.
6047 return _unescape_sub(r"\1", s)
6050 _unescape_sub = re.compile(r"\\(.)").sub
6053 def standard_kconfig():
6055 Helper for tools. Loads the top-level Kconfig specified as the first
6056 command-line argument, or "Kconfig" if there are no command-line arguments.
6057 Returns the Kconfig instance.
6059 Exits with sys.exit() (which raises a SystemExit exception) and prints a
6060 usage note to stderr if more than one command-line argument is passed.
6062 if len(sys.argv) > 2:
6063 sys.exit("usage: {} [Kconfig]".format(sys.argv[0]))
6065 # Only show backtraces for unexpected exceptions
6067 return Kconfig("Kconfig" if len(sys.argv) < 2 else sys.argv[1])
6068 except (EnvironmentError, KconfigError) as e:
6069 # Some long exception messages have extra newlines for better
6070 # formatting when reported as an unhandled exception. Strip them here.
6071 sys.exit(str(e).strip())
6074 def standard_config_filename():
6076 Helper for tools. Returns the value of KCONFIG_CONFIG (which specifies the
6077 .config file to load/save) if it is set, and ".config" otherwise.
6079 Calling load_config() with filename=None might give the behavior you want,
6080 without having to use this function.
6082 return os.getenv("KCONFIG_CONFIG", ".config")
6085 def load_allconfig(kconf, filename):
6087 Helper for all*config. Loads (merges) the configuration file specified by
6088 KCONFIG_ALLCONFIG, if any. See Documentation/kbuild/kconfig.txt in the
6091 Disables warnings for duplicated assignments within configuration files for
6092 the duration of the call (kconf.warn_assign_override/warn_assign_redun = False),
6093 and restores the previous warning settings at the end. The
6094 KCONFIG_ALLCONFIG configuration file is expected to override symbols.
6096 Exits with sys.exit() (which raises a SystemExit exception) and prints an
6097 error to stderr if KCONFIG_ALLCONFIG is set but the configuration file
6101 Kconfig instance to load the configuration in.
6104 Command-specific configuration filename - "allyes.config",
6105 "allno.config", etc.
6107 allconfig = os.getenv("KCONFIG_ALLCONFIG")
6108 if allconfig is None:
6112 # "Upcasts" a _KconfigIOError to an IOError, removing the custom
6113 # __str__() message. The standard message is better here.
6115 # This might also convert an OSError to an IOError in obscure cases,
6116 # but it's probably not a big deal. The distinction is shaky (see
6118 return IOError(e.errno, e.strerror, e.filename)
6120 old_warn_assign_override = kconf.warn_assign_override
6121 old_warn_assign_redun = kconf.warn_assign_redun
6122 kconf.warn_assign_override = kconf.warn_assign_redun = False
6124 if allconfig in ("", "1"):
6126 print(kconf.load_config(filename, False))
6127 except EnvironmentError as e1:
6129 print(kconf.load_config("all.config", False))
6130 except EnvironmentError as e2:
6131 sys.exit("error: KCONFIG_ALLCONFIG is set, but neither {} "
6132 "nor all.config could be opened: {}, {}"
6133 .format(filename, std_msg(e1), std_msg(e2)))
6136 print(kconf.load_config(allconfig, False))
6137 except EnvironmentError as e:
6138 sys.exit("error: KCONFIG_ALLCONFIG is set to '{}', which "
6139 "could not be opened: {}"
6140 .format(allconfig, std_msg(e)))
6142 kconf.warn_assign_override = old_warn_assign_override
6143 kconf.warn_assign_redun = old_warn_assign_redun
6147 # Internal functions
6151 def _visibility(sc):
6152 # Symbols and Choices have a "visibility" that acts as an upper bound on
6153 # the values a user can set for them, corresponding to the visibility in
6154 # e.g. 'make menuconfig'. This function calculates the visibility for the
6155 # Symbol or Choice 'sc' -- the logic is nearly identical.
6159 for node in sc.nodes:
6161 vis = max(vis, expr_value(node.prompt[1]))
6163 if sc.__class__ is Symbol and sc.choice:
6164 if sc.choice.orig_type is TRISTATE and \
6165 sc.orig_type is not TRISTATE and sc.choice.tri_value != 2:
6166 # Non-tristate choice symbols are only visible in y mode
6169 if sc.orig_type is TRISTATE and vis == 1 and sc.choice.tri_value == 2:
6170 # Choice symbols with m visibility are not visible in y mode
6173 # Promote m to y if we're dealing with a non-tristate (possibly due to
6174 # modules being disabled)
6175 if vis == 1 and sc.type is not TRISTATE:
6181 def _make_depend_on(sc, expr):
6182 # Adds 'sc' (symbol or choice) as a "dependee" to all symbols in 'expr'.
6183 # Constant symbols in 'expr' are skipped as they can never change value
6186 if expr.__class__ is tuple:
6187 # AND, OR, NOT, or relation
6189 _make_depend_on(sc, expr[1])
6191 # NOTs only have a single operand
6192 if expr[0] is not NOT:
6193 _make_depend_on(sc, expr[2])
6195 elif not expr.is_constant:
6196 # Non-constant symbol, or choice
6197 expr._dependents.add(sc)
6200 def _parenthesize(expr, type_, sc_expr_str_fn):
6201 # expr_str() helper. Adds parentheses around expressions of type 'type_'.
6203 if expr.__class__ is tuple and expr[0] is type_:
6204 return "({})".format(expr_str(expr, sc_expr_str_fn))
6205 return expr_str(expr, sc_expr_str_fn)
6208 def _ordered_unique(lst):
6209 # Returns 'lst' with any duplicates removed, preserving order. This hacky
6210 # version seems to be a common idiom. It relies on short-circuit evaluation
6211 # and set.add() returning None, which is falsy.
6215 return [x for x in lst if x not in seen and not seen_add(x)]
6218 def _is_base_n(s, n):
6226 def _strcmp(s1, s2):
6227 # strcmp()-alike that returns -1, 0, or 1
6229 return (s1 > s2) - (s1 < s2)
6232 def _sym_to_num(sym):
6233 # expr_value() helper for converting a symbol to a number. Raises
6234 # ValueError for symbols that can't be converted.
6236 # For BOOL and TRISTATE, n/m/y count as 0/1/2. This mirrors 9059a3493ef
6237 # ("kconfig: fix relational operators for bool and tristate symbols") in
6238 # the C implementation.
6239 return sym.tri_value if sym.orig_type in _BOOL_TRISTATE else \
6240 int(sym.str_value, _TYPE_TO_BASE[sym.orig_type])
6243 def _touch_dep_file(path, sym_name):
6244 # If sym_name is MY_SYM_NAME, touches my/sym/name.h. See the sync_deps()
6247 sym_path = path + os.sep + sym_name.lower().replace("_", os.sep) + ".h"
6248 sym_path_dir = dirname(sym_path)
6249 if not exists(sym_path_dir):
6250 os.makedirs(sym_path_dir, 0o755)
6252 # A kind of truncating touch, mirroring the C tools
6254 sym_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644))
6257 def _save_old(path):
6258 # See write_config()
6261 # Import as needed, to save some startup time
6263 shutil.copyfile(src, dst)
6268 elif hasattr(os, "replace"):
6269 # Python 3 (3.3+) only. Best choice when available, because it
6270 # removes <filename>.old on both *nix and Windows.
6271 copy_fn = os.replace
6272 elif os.name == "posix":
6273 # Removes <filename>.old on POSIX systems
6276 # Fall back on copying
6280 copy_fn(path, path + ".old")
6282 # Ignore errors from 'path' missing as well as other errors.
6283 # <filename>.old file is usually more of a nice-to-have, and not worth
6284 # erroring out over e.g. if <filename>.old happens to be a directory or
6285 # <filename> is something like /dev/null.
6289 def _name_and_loc(sc):
6290 # Helper for giving the symbol/choice name and location(s) in e.g. warnings
6292 # Reuse the expression format. That way choices show up as
6293 # '<choice (name, if any)>'
6294 name = standard_sc_expr_str(sc)
6297 return name + " (undefined)"
6299 return "{} (defined at {})".format(
6301 ", ".join("{}:{}".format(node.filename, node.linenr)
6302 for node in sc.nodes))
6308 def _expr_depends_on(expr, sym):
6309 # Reimplementation of expr_depends_symbol() from mconf.c. Used to determine
6310 # if a submenu should be implicitly created. This also influences which
6311 # items inside choice statements are considered choice items.
6313 if expr.__class__ is not tuple:
6316 if expr[0] in _EQUAL_UNEQUAL:
6317 # Check for one of the following:
6318 # sym = m/y, m/y = sym, sym != n, n != sym
6320 left, right = expr[1:]
6323 left, right = right, left
6324 elif left is not sym:
6327 return (expr[0] is EQUAL and right is sym.kconfig.m or
6328 right is sym.kconfig.y) or \
6329 (expr[0] is UNEQUAL and right is sym.kconfig.n)
6331 return expr[0] is AND and \
6332 (_expr_depends_on(expr[1], sym) or
6333 _expr_depends_on(expr[2], sym))
6336 def _auto_menu_dep(node1, node2):
6337 # Returns True if node2 has an "automatic menu dependency" on node1. If
6338 # node2 has a prompt, we check its condition. Otherwise, we look directly
6341 return _expr_depends_on(node2.prompt[1] if node2.prompt else node2.dep,
6346 # "Flattens" menu nodes without prompts (e.g. 'if' nodes and non-visible
6347 # symbols with children from automatic menu creation) so that their
6348 # children appear after them instead. This gives a clean menu structure
6349 # with no unexpected "jumps" in the indentation.
6351 # Do not flatten promptless choices (which can appear "legitimately" if a
6352 # named choice is defined in multiple locations to add on symbols). It
6353 # looks confusing, and the menuconfig already shows all choice symbols if
6354 # you enter the choice at some location with a prompt.
6357 if node.list and not node.prompt and \
6358 node.item.__class__ is not Choice:
6360 last_node = node.list
6362 last_node.parent = node.parent
6363 if not last_node.next:
6365 last_node = last_node.next
6367 last_node.next = node.next
6368 node.next = node.list
6374 def _remove_ifs(node):
6375 # Removes 'if' nodes (which can be recognized by MenuNode.item being None),
6376 # which are assumed to already have been flattened. The C implementation
6377 # doesn't bother to do this, but we expose the menu tree directly, and it
6378 # makes it nicer to work with.
6381 while cur and not cur.item:
6388 while next and not next.item:
6396 # due to tricky Python semantics. The order matters.
6397 cur.next = cur = next
6400 def _finalize_choice(node):
6401 # Finalizes a choice, marking each symbol whose menu node has the choice as
6402 # the parent as a choice symbol, and automatically determining types if not
6409 if cur.item.__class__ is Symbol:
6410 cur.item.choice = choice
6411 choice.syms.append(cur.item)
6414 # If no type is specified for the choice, its type is that of
6415 # the first choice item with a specified type
6416 if not choice.orig_type:
6417 for item in choice.syms:
6419 choice.orig_type = item.orig_type
6422 # Each choice item of UNKNOWN type gets the type of the choice
6423 for sym in choice.syms:
6424 if not sym.orig_type:
6425 sym.orig_type = choice.orig_type
6428 def _check_dep_loop_sym(sym, ignore_choice):
6429 # Detects dependency loops using depth-first search on the dependency graph
6430 # (which is calculated earlier in Kconfig._build_dep()).
6434 # 1. Symbols/choices start out with _visited = 0, meaning unvisited.
6436 # 2. When a symbol/choice is first visited, _visited is set to 1, meaning
6437 # "visited, potentially part of a dependency loop". The recursive
6438 # search then continues from the symbol/choice.
6440 # 3. If we run into a symbol/choice X with _visited already set to 1,
6441 # there's a dependency loop. The loop is found on the call stack by
6442 # recording symbols while returning ("on the way back") until X is seen
6445 # 4. Once a symbol/choice and all its dependencies (or dependents in this
6446 # case) have been checked recursively without detecting any loops, its
6447 # _visited is set to 2, meaning "visited, not part of a dependency
6450 # This saves work if we run into the symbol/choice again in later calls
6451 # to _check_dep_loop_sym(). We just return immediately.
6453 # Choices complicate things, as every choice symbol depends on every other
6454 # choice symbol in a sense. When a choice is "entered" via a choice symbol
6455 # X, we visit all choice symbols from the choice except X, and prevent
6456 # immediately revisiting the choice with a flag (ignore_choice).
6458 # Maybe there's a better way to handle this (different flags or the
6461 if not sym._visited:
6462 # sym._visited == 0, unvisited
6466 for dep in sym._dependents:
6467 # Choices show up in Symbol._dependents when the choice has the
6468 # symbol in a 'prompt' or 'default' condition (e.g.
6469 # 'default ... if SYM').
6471 # Since we aren't entering the choice via a choice symbol, all
6472 # choice symbols need to be checked, hence the None.
6473 loop = _check_dep_loop_choice(dep, None) \
6474 if dep.__class__ is Choice \
6475 else _check_dep_loop_sym(dep, False)
6478 # Dependency loop found
6479 return _found_dep_loop(loop, sym)
6481 if sym.choice and not ignore_choice:
6482 loop = _check_dep_loop_choice(sym.choice, sym)
6484 # Dependency loop found
6485 return _found_dep_loop(loop, sym)
6487 # The symbol is not part of a dependency loop
6490 # No dependency loop found
6493 if sym._visited == 2:
6494 # The symbol was checked earlier and is already known to not be part of
6498 # sym._visited == 1, found a dependency loop. Return the symbol as the
6499 # first element in it.
6503 def _check_dep_loop_choice(choice, skip):
6504 if not choice._visited:
6505 # choice._visited == 0, unvisited
6509 # Check for loops involving choice symbols. If we came here via a
6510 # choice symbol, skip that one, as we'd get a false positive
6511 # '<sym FOO> -> <choice> -> <sym FOO>' loop otherwise.
6512 for sym in choice.syms:
6514 # Prevent the choice from being immediately re-entered via the
6515 # "is a choice symbol" path by passing True
6516 loop = _check_dep_loop_sym(sym, True)
6518 # Dependency loop found
6519 return _found_dep_loop(loop, choice)
6521 # The choice is not part of a dependency loop
6524 # No dependency loop found
6527 if choice._visited == 2:
6528 # The choice was checked earlier and is already known to not be part of
6532 # choice._visited == 1, found a dependency loop. Return the choice as the
6533 # first element in it.
6537 def _found_dep_loop(loop, cur):
6538 # Called "on the way back" when we know we have a loop
6540 # Is the symbol/choice 'cur' where the loop started?
6541 if cur is not loop[0]:
6542 # Nope, it's just a part of the loop
6543 return loop + (cur,)
6545 # Yep, we have the entire loop. Throw an exception that shows it.
6547 msg = "\nDependency loop\n" \
6548 "===============\n\n"
6551 if item is not loop[0]:
6552 msg += "...depends on "
6553 if item.__class__ is Symbol and item.choice:
6554 msg += "the choice symbol "
6556 msg += "{}, with definition...\n\n{}\n\n" \
6557 .format(_name_and_loc(item), item)
6559 # Small wart: Since we reuse the already calculated
6560 # Symbol/Choice._dependents sets for recursive dependency detection, we
6561 # lose information on whether a dependency came from a 'select'/'imply'
6562 # condition or e.g. a 'depends on'.
6564 # This might cause selecting symbols to "disappear". For example,
6565 # a symbol B having 'select A if C' gives a direct dependency from A to
6566 # C, since it corresponds to a reverse dependency of B && C.
6568 # Always print reverse dependencies for symbols that have them to make
6569 # sure information isn't lost. I wonder if there's some neat way to
6572 if item.__class__ is Symbol:
6573 if item.rev_dep is not item.kconfig.n:
6574 msg += "(select-related dependencies: {})\n\n" \
6575 .format(expr_str(item.rev_dep))
6577 if item.weak_rev_dep is not item.kconfig.n:
6578 msg += "(imply-related dependencies: {})\n\n" \
6579 .format(expr_str(item.rev_dep))
6581 msg += "...depends again on {}".format(_name_and_loc(loop[0]))
6583 raise KconfigError(msg)
6586 def _decoding_error(e, filename, macro_linenr=None):
6587 # Gives the filename and context for UnicodeDecodeError's, which are a pain
6588 # to debug otherwise. 'e' is the UnicodeDecodeError object.
6590 # If the decoding error is for the output of a $(shell,...) command,
6591 # macro_linenr holds the line number where it was run (the exact line
6592 # number isn't available for decoding errors in files).
6596 "Malformed {} in {}\n"
6598 "Problematic data: {}\n"
6599 "Reason: {}".format(
6601 "'{}'".format(filename) if macro_linenr is None else
6602 "output from macro at {}:{}".format(filename, macro_linenr),
6603 e.object[max(e.start - 40, 0):e.end + 40],
6604 e.object[e.start:e.end],
6608 def _warn_verbose_deprecated(fn_name):
6610 "Deprecation warning: {0}()'s 'verbose' argument has no effect. Since "
6611 "Kconfiglib 12.0.0, the message is returned from {0}() instead, "
6612 "and is always generated. Do e.g. print(kconf.{0}()) if you want to "
6613 "want to show a message like \"Loaded configuration '.config'\" on "
6614 "stdout. The old API required ugly hacks to reuse messages in "
6615 "configuration interfaces.\n".format(fn_name))
6618 # Predefined preprocessor functions
6621 def _filename_fn(kconf, _):
6622 return kconf.filename
6625 def _lineno_fn(kconf, _):
6626 return str(kconf.linenr)
6629 def _info_fn(kconf, _, msg):
6630 print("{}:{}: {}".format(kconf.filename, kconf.linenr, msg))
6635 def _warning_if_fn(kconf, _, cond, msg):
6637 kconf._warn(msg, kconf.filename, kconf.linenr)
6642 def _error_if_fn(kconf, _, cond, msg):
6644 raise KconfigError("{}:{}: {}".format(
6645 kconf.filename, kconf.linenr, msg))
6650 def _shell_fn(kconf, _, command):
6651 # Only import as needed, to save some startup time
6654 stdout, stderr = subprocess.Popen(
6655 command, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE
6660 stdout = stdout.decode(kconf._encoding)
6661 stderr = stderr.decode(kconf._encoding)
6662 except UnicodeDecodeError as e:
6663 _decoding_error(e, kconf.filename, kconf.linenr)
6666 kconf._warn("'{}' wrote to stderr: {}".format(
6667 command, "\n".join(stderr.splitlines())),
6668 kconf.filename, kconf.linenr)
6670 # Universal newlines with splitlines() (to prevent e.g. stray \r's in
6671 # command output on Windows), trailing newline removal, and
6672 # newline-to-space conversion.
6674 # On Python 3 versions before 3.6, it's not possible to specify the
6675 # encoding when passing universal_newlines=True to Popen() (the 'encoding'
6676 # parameter was added in 3.6), so we do this manual version instead.
6677 return "\n".join(stdout.splitlines()).rstrip("\n").replace("\n", " ")
6695 # Constant representing that there's no cached choice selection. This is
6696 # distinct from a cached None (no selection). Any object that's not None or a
6697 # Symbol will do. We test this with 'is'.
6698 _NO_CACHED_SELECTION = 0
6700 # Are we running on Python 2?
6701 _IS_PY2 = sys.version_info[0] < 3
6704 _UNAME_RELEASE = os.uname()[2]
6705 except AttributeError:
6706 # Only import as needed, to save some startup time
6708 _UNAME_RELEASE = platform.uname()[2]
6710 # The token and type constants below are safe to test with 'is', which is a bit
6711 # faster (~30% faster on my machine, and a few % faster for total parsing
6712 # time), even without assuming Python's small integer optimization (which
6713 # caches small integer objects). The constants end up pointing to unique
6714 # integer objects, and since we consistently refer to them via the names below,
6715 # we always get the same object.
6717 # Client code should use == though.
6719 # Tokens, with values 1, 2, ... . Avoiding 0 simplifies some checks by making
6720 # all tokens except empty strings truthy.
6774 # Keyword to token map, with the get() method assigned directly as a small
6777 "---help---": _T_HELP,
6778 "allnoconfig_y": _T_ALLNOCONFIG_Y,
6781 "choice": _T_CHOICE,
6782 "comment": _T_COMMENT,
6783 "config": _T_CONFIG,
6784 "def_bool": _T_DEF_BOOL,
6785 "def_hex": _T_DEF_HEX,
6786 "def_int": _T_DEF_INT,
6787 "def_string": _T_DEF_STRING,
6788 "def_tristate": _T_DEF_TRISTATE,
6789 "default": _T_DEFAULT,
6790 "defconfig_list": _T_DEFCONFIG_LIST,
6791 "depends": _T_DEPENDS,
6792 "endchoice": _T_ENDCHOICE,
6794 "endmenu": _T_ENDMENU,
6796 "grsource": _T_ORSOURCE, # Backwards compatibility
6797 "gsource": _T_OSOURCE, # Backwards compatibility
6803 "mainmenu": _T_MAINMENU,
6805 "menuconfig": _T_MENUCONFIG,
6806 "modules": _T_MODULES,
6808 "option": _T_OPTION,
6809 "optional": _T_OPTIONAL,
6810 "orsource": _T_ORSOURCE,
6811 "osource": _T_OSOURCE,
6812 "prompt": _T_PROMPT,
6814 "rsource": _T_RSOURCE,
6815 "select": _T_SELECT,
6816 "source": _T_SOURCE,
6817 "string": _T_STRING,
6818 "tristate": _T_TRISTATE,
6819 "visible": _T_VISIBLE,
6822 # The constants below match the value of the corresponding tokens to remove the
6823 # need for conversion
6827 COMMENT = _T_COMMENT
6834 UNEQUAL = _T_UNEQUAL
6836 LESS_EQUAL = _T_LESS_EQUAL
6837 GREATER = _T_GREATER
6838 GREATER_EQUAL = _T_GREATER_EQUAL
6846 GREATER_EQUAL: ">=",
6849 # Symbol/choice types. UNKNOWN is 0 (falsy) to simplify some checks.
6850 # Client code shouldn't rely on it though, as it was non-zero in
6854 TRISTATE = _T_TRISTATE
6862 TRISTATE: "tristate",
6868 # Used in comparisons. 0 means the base is inferred from the format of the
6877 # def_bool -> BOOL, etc.
6878 _DEF_TOKEN_TO_TYPE = {
6882 _T_DEF_STRING: STRING,
6883 _T_DEF_TRISTATE: TRISTATE,
6886 # Tokens after which strings are expected. This is used to tell strings from
6887 # constant symbol references during tokenization, both of which are enclosed in
6890 # Identifier-like lexemes ("missing quotes") are also treated as strings after
6891 # these tokens. _T_CHOICE is included to avoid symbols being registered for
6893 _STRING_LEX = frozenset({
6910 # Various sets for quick membership tests. Gives a single global lookup and
6911 # avoids creating temporary dicts/tuples.
6913 _TYPE_TOKENS = frozenset({
6921 _SOURCE_TOKENS = frozenset({
6928 _REL_SOURCE_TOKENS = frozenset({
6933 # Obligatory (non-optional) sources
6934 _OBL_SOURCE_TOKENS = frozenset({
6939 _BOOL_TRISTATE = frozenset({
6944 _BOOL_TRISTATE_UNKNOWN = frozenset({
6950 _INT_HEX = frozenset({
6955 _SYMBOL_CHOICE = frozenset({
6960 _MENU_COMMENT = frozenset({
6965 _EQUAL_UNEQUAL = frozenset({
6970 _RELATIONS = frozenset({
6979 # Helper functions for getting compiled regular expressions, with the needed
6980 # matching function returned directly as a small optimization.
6982 # Use ASCII regex matching on Python 3. It's already the default on Python 2.
6985 def _re_match(regex):
6986 return re.compile(regex, 0 if _IS_PY2 else re.ASCII).match
6989 def _re_search(regex):
6990 return re.compile(regex, 0 if _IS_PY2 else re.ASCII).search
6993 # Various regular expressions used during parsing
6995 # The initial token on a line. Also eats leading and trailing whitespace, so
6996 # that we can jump straight to the next token (or to the end of the line if
6997 # there is only one token).
6999 # This regex will also fail to match for empty lines and comment lines.
7001 # '$' is included to detect preprocessor variable assignments with macro
7002 # expansions in the left-hand side.
7003 _command_match = _re_match(r"\s*([A-Za-z0-9_$-]+)\s*")
7005 # An identifier/keyword after the first token. Also eats trailing whitespace.
7006 # '$' is included to detect identifiers containing macro expansions.
7007 _id_keyword_match = _re_match(r"([A-Za-z0-9_$/.-]+)\s*")
7009 # A fragment in the left-hand side of a preprocessor variable assignment. These
7010 # are the portions between macro expansions ($(foo)). Macros are supported in
7011 # the LHS (variable name).
7012 _assignment_lhs_fragment_match = _re_match("[A-Za-z0-9_-]*")
7014 # The assignment operator and value (right-hand side) in a preprocessor
7015 # variable assignment
7016 _assignment_rhs_match = _re_match(r"\s*(=|:=|\+=)\s*(.*)")
7018 # Special characters/strings while expanding a macro (')', ',', and '$(')
7019 _macro_special_search = _re_search(r"\)|,|\$\(")
7021 # Special characters/strings while expanding a string (quotes, '\', and '$(')
7022 _string_special_search = _re_search(r'"|\'|\\|\$\(')
7024 # Special characters/strings while expanding a symbol name. Also includes
7025 # end-of-line, in case the macro is the last thing on the line.
7026 _name_special_search = _re_search(r'[^A-Za-z0-9_$/.-]|\$\(|$')
7028 # A valid right-hand side for an assignment to a string symbol in a .config
7029 # file, including escaped characters. Extracts the contents.
7030 _conf_string_match = _re_match(r'"((?:[^\\"]|\\.)*)"')
projects / oweals / u-boot.git / blob