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
559 # pylint: disable=E1101
568 # Line length: 79 columns
576 class Kconfig(object):
578 Represents a Kconfig configuration, e.g. for x86 or ARM. This is the set of
579 symbols, choices, and menu nodes appearing in the configuration. Creating
580 any number of Kconfig objects (including for different architectures) is
581 safe. Kconfiglib doesn't keep any global state.
583 The following attributes are available. They should be treated as
584 read-only, and some are implemented through @property magic.
587 A dictionary with all symbols in the configuration, indexed by name. Also
588 includes all symbols that are referenced in expressions but never
589 defined, except for constant (quoted) symbols.
591 Undefined symbols can be recognized by Symbol.nodes being empty -- see
592 the 'Intro to the menu tree' section in the module docstring.
595 A dictionary like 'syms' for constant (quoted) symbols
598 A dictionary like 'syms' for named choices (choice FOO)
601 A list with all defined symbols, in the same order as they appear in the
602 Kconfig files. Symbols defined in multiple locations appear multiple
605 Note: You probably want to use 'unique_defined_syms' instead. This
606 attribute is mostly maintained for backwards compatibility.
609 A list like 'defined_syms', but with duplicates removed. Just the first
610 instance is kept for symbols defined in multiple locations. Kconfig order
611 is preserved otherwise.
613 Using this attribute instead of 'defined_syms' can save work, and
614 automatically gives reasonable behavior when writing configuration output
615 (symbols defined in multiple locations only generate output once, while
616 still preserving Kconfig order for readability).
619 A list with all choices, in the same order as they appear in the Kconfig
622 Note: You probably want to use 'unique_choices' instead. This attribute
623 is mostly maintained for backwards compatibility.
626 Analogous to 'unique_defined_syms', for choices. Named choices can have
627 multiple definition locations.
630 A list with all menus, in the same order as they appear in the Kconfig
634 A list with all comments, in the same order as they appear in the Kconfig
638 A list with the filenames of all Kconfig files included in the
639 configuration, relative to $srctree (or relative to the current directory
640 if $srctree isn't set), except absolute paths (e.g.
641 'source "/foo/Kconfig"') are kept as-is.
643 The files are listed in the order they are source'd, starting with the
644 top-level Kconfig file. If a file is source'd multiple times, it will
645 appear multiple times. Use set() to get unique filenames.
647 Note that Kconfig.sync_deps() already indirectly catches any file
648 modifications that change configuration output.
651 A set() with the names of all environment variables referenced in the
654 Only environment variables referenced with the preprocessor $(FOO) syntax
655 will be registered. The older $FOO syntax is only supported for backwards
658 Also note that $(FOO) won't be registered unless the environment variable
659 $FOO is actually set. If it isn't, $(FOO) is an expansion of an unset
660 preprocessor variable (which gives the empty string).
662 Another gotcha is that environment variables referenced in the values of
663 recursively expanded preprocessor variables (those defined with =) will
664 only be registered if the variable is actually used (expanded) somewhere.
666 The note from the 'kconfig_filenames' documentation applies here too.
669 The predefined constant symbols n/m/y. Also available in const_syms.
672 The Symbol instance for the modules symbol. Currently hardcoded to
673 MODULES, which is backwards compatible. Kconfiglib will warn if
674 'option modules' is set on some other symbol. Tell me if you need proper
675 'option modules' support.
677 'modules' is never None. If the MODULES symbol is not explicitly defined,
678 its tri_value will be 0 (n), as expected.
680 A simple way to enable modules is to do 'kconf.modules.set_value(2)'
681 (provided the MODULES symbol is defined and visible). Modules are
682 disabled by default in the kernel Kconfig files as of writing, though
683 nearly all defconfig files enable them (with 'CONFIG_MODULES=y').
686 The Symbol instance for the 'option defconfig_list' symbol, or None if no
687 defconfig_list symbol exists. The defconfig filename derived from this
688 symbol can be found in Kconfig.defconfig_filename.
691 The filename given by the defconfig_list symbol. This is taken from the
692 first 'default' with a satisfied condition where the specified file
693 exists (can be opened for reading). If a defconfig file foo/defconfig is
694 not found and $srctree was set when the Kconfig was created,
695 $srctree/foo/defconfig is looked up as well.
697 'defconfig_filename' is None if either no defconfig_list symbol exists,
698 or if the defconfig_list symbol has no 'default' with a satisfied
699 condition that specifies a file that exists.
701 Gotcha: scripts/kconfig/Makefile might pass --defconfig=<defconfig> to
702 scripts/kconfig/conf when running e.g. 'make defconfig'. This option
703 overrides the defconfig_list symbol, meaning defconfig_filename might not
704 always match what 'make defconfig' would use.
707 The menu node (see the MenuNode class) of the implicit top-level menu.
708 Acts as the root of the menu tree.
711 The prompt (title) of the top menu (top_node). Defaults to "Main menu".
712 Can be changed with the 'mainmenu' statement (see kconfig-language.txt).
715 A dictionary with all preprocessor variables, indexed by name. See the
719 Set this variable to True/False to enable/disable warnings. See
722 When 'warn' is False, the values of the other warning-related variables
725 This variable as well as the other warn* variables can be read to check
726 the current warning settings.
729 Set this variable to True/False to enable/disable warnings on stderr. See
733 Set this variable to True to generate warnings for assignments to
734 undefined symbols in configuration files.
736 This variable is False by default unless the KCONFIG_WARN_UNDEF_ASSIGN
737 environment variable was set to 'y' when the Kconfig instance was
740 warn_assign_override:
741 Set this variable to True to generate warnings for multiple assignments
742 to the same symbol in configuration files, where the assignments set
743 different values (e.g. CONFIG_FOO=m followed by CONFIG_FOO=y, where the
744 last value would get used).
746 This variable is True by default. Disabling it might be useful when
747 merging configurations.
750 Like warn_assign_override, but for multiple assignments setting a symbol
753 This variable is True by default. Disabling it might be useful when
754 merging configurations.
757 A list of strings containing all warnings that have been generated, for
758 cases where more flexibility is needed.
760 See the 'warn_to_stderr' parameter to Kconfig.__init__() and the
761 Kconfig.warn_to_stderr variable as well. Note that warnings still get
762 added to Kconfig.warnings when 'warn_to_stderr' is True.
764 Just as for warnings printed to stderr, only warnings that are enabled
765 will get added to Kconfig.warnings. See the various Kconfig.warn*
769 A list with (name, value) tuples for all assignments to undefined symbols
770 within the most recently loaded .config file(s). 'name' is the symbol
771 name without the 'CONFIG_' prefix. 'value' is a string that gives the
772 right-hand side of the assignment verbatim.
774 See Kconfig.load_config() as well.
777 The value the $srctree environment variable had when the Kconfig instance
778 was created, or the empty string if $srctree wasn't set. This gives nice
779 behavior with os.path.join(), which treats "" as the current directory,
782 Kconfig files are looked up relative to $srctree (unless absolute paths
783 are used), and .config files are looked up relative to $srctree if they
784 are not found in the current directory. This is used to support
785 out-of-tree builds. The C tools use this environment variable in the same
788 Changing $srctree after creating the Kconfig instance has no effect. Only
789 the value when the configuration is loaded matters. This avoids surprises
790 if multiple configurations are loaded with different values for $srctree.
793 The value the CONFIG_ environment variable had when the Kconfig instance
794 was created, or "CONFIG_" if CONFIG_ wasn't set. This is the prefix used
795 (and expected) on symbol names in .config files and C headers. Used in
796 the same way in the C tools.
799 The value the KCONFIG_CONFIG_HEADER environment variable had when the
800 Kconfig instance was created, or the empty string if
801 KCONFIG_CONFIG_HEADER wasn't set. This string is inserted verbatim at the
802 beginning of configuration files. See write_config().
805 The value the KCONFIG_AUTOHEADER_HEADER environment variable had when the
806 Kconfig instance was created, or the empty string if
807 KCONFIG_AUTOHEADER_HEADER wasn't set. This string is inserted verbatim at
808 the beginning of header files. See write_autoconf().
811 The current parsing location, for use in Python preprocessor functions.
812 See the module docstring.
820 "_warn_assign_no_prompt",
841 "unique_defined_syms",
844 "warn_assign_override",
868 def __init__(self, filename="Kconfig", warn=True, warn_to_stderr=True,
869 encoding="utf-8", suppress_traceback=False):
871 Creates a new Kconfig object by parsing Kconfig files.
872 Note that Kconfig files are not the same as .config files (which store
873 configuration symbol values).
875 See the module docstring for some environment variables that influence
876 default warning settings (KCONFIG_WARN_UNDEF and
877 KCONFIG_WARN_UNDEF_ASSIGN).
879 Raises KconfigError on syntax/semantic errors, and OSError or (possibly
880 a subclass of) IOError on IO errors ('errno', 'strerror', and
881 'filename' are available). Note that IOError is an alias for OSError on
882 Python 3, so it's enough to catch OSError there. If you need Python 2/3
883 compatibility, it's easiest to catch EnvironmentError, which is a
884 common base class of OSError/IOError on Python 2 and an alias for
887 filename (default: "Kconfig"):
888 The Kconfig file to load. For the Linux kernel, you'll want "Kconfig"
889 from the top-level directory, as environment variables will make sure
890 the right Kconfig is included from there (arch/$SRCARCH/Kconfig as of
893 If $srctree is set, 'filename' will be looked up relative to it.
894 $srctree is also used to look up source'd files within Kconfig files.
895 See the class documentation.
897 If you are using Kconfiglib via 'make scriptconfig', the filename of
898 the base base Kconfig file will be in sys.argv[1]. It's currently
899 always "Kconfig" in practice.
901 warn (default: True):
902 True if warnings related to this configuration should be generated.
903 This can be changed later by setting Kconfig.warn to True/False. It
904 is provided as a constructor argument since warnings might be
905 generated during parsing.
907 See the other Kconfig.warn_* variables as well, which enable or
908 suppress certain warnings when warnings are enabled.
910 All generated warnings are added to the Kconfig.warnings list. See
911 the class documentation.
913 warn_to_stderr (default: True):
914 True if warnings should be printed to stderr in addition to being
915 added to Kconfig.warnings.
917 This can be changed later by setting Kconfig.warn_to_stderr to
920 encoding (default: "utf-8"):
921 The encoding to use when reading and writing files, and when decoding
922 output from commands run via $(shell). If None, the encoding
923 specified in the current locale will be used.
925 The "utf-8" default avoids exceptions on systems that are configured
926 to use the C locale, which implies an ASCII encoding.
928 This parameter has no effect on Python 2, due to implementation
929 issues (regular strings turning into Unicode strings, which are
930 distinct in Python 2). Python 2 doesn't decode regular strings
933 Related PEP: https://www.python.org/dev/peps/pep-0538/
935 suppress_traceback (default: False):
936 Helper for tools. When True, any EnvironmentError or KconfigError
937 generated during parsing is caught, the exception message is printed
938 to stderr together with the command name, and sys.exit(1) is called
939 (which generates SystemExit).
941 This hides the Python traceback for "expected" errors like syntax
942 errors in Kconfig files.
944 Other exceptions besides EnvironmentError and KconfigError are still
945 propagated when suppress_traceback is True.
948 self._init(filename, warn, warn_to_stderr, encoding)
949 except (EnvironmentError, KconfigError) as e:
950 if suppress_traceback:
951 cmd = sys.argv[0] # Empty string if missing
954 # Some long exception messages have extra newlines for better
955 # formatting when reported as an unhandled exception. Strip
957 sys.exit(cmd + str(e).strip())
960 def _init(self, filename, warn, warn_to_stderr, encoding):
963 self._encoding = encoding
965 self.srctree = os.getenv("srctree", "")
966 # A prefix we can reliably strip from glob() results to get a filename
967 # relative to $srctree. relpath() can cause issues for symlinks,
968 # because it assumes symlink/../foo is the same as foo/.
969 self._srctree_prefix = realpath(self.srctree) + os.sep
972 self.warn_to_stderr = warn_to_stderr
973 self.warn_assign_undef = os.getenv("KCONFIG_WARN_UNDEF_ASSIGN") == "y"
974 self.warn_assign_override = True
975 self.warn_assign_redun = True
976 self._warn_assign_no_prompt = True
980 self.config_prefix = os.getenv("CONFIG_", "CONFIG_")
981 # Regular expressions for parsing .config files
982 self._set_match = _re_match(self.config_prefix + r"([^=]+)=(.*)")
983 self._unset_match = _re_match(r"# {}([^ ]+) is not set".format(
986 self.config_header = os.getenv("KCONFIG_CONFIG_HEADER", "")
987 self.header_header = os.getenv("KCONFIG_AUTOHEADER_HEADER", "")
991 self.defined_syms = []
992 self.missing_syms = []
993 self.named_choices = {}
998 for nmy in "n", "m", "y":
1002 sym.is_constant = True
1003 sym.orig_type = TRISTATE
1004 sym._cached_tri_val = STR_TO_TRI[nmy]
1006 self.const_syms[nmy] = sym
1008 self.n = self.const_syms["n"]
1009 self.m = self.const_syms["m"]
1010 self.y = self.const_syms["y"]
1012 # Make n/m/y well-formed symbols
1013 for nmy in "n", "m", "y":
1014 sym = self.const_syms[nmy]
1015 sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n
1017 # Maps preprocessor variables names to Variable instances
1020 # Predefined preprocessor functions, with min/max number of arguments
1022 "info": (_info_fn, 1, 1),
1023 "error-if": (_error_if_fn, 2, 2),
1024 "filename": (_filename_fn, 0, 0),
1025 "lineno": (_lineno_fn, 0, 0),
1026 "shell": (_shell_fn, 1, 1),
1027 "warning-if": (_warning_if_fn, 2, 2),
1030 # Add any user-defined preprocessor functions
1032 self._functions.update(
1033 importlib.import_module(
1034 os.getenv("KCONFIG_FUNCTIONS", "kconfigfunctions")
1039 # This determines whether previously unseen symbols are registered.
1040 # They shouldn't be if we parse expressions after parsing, as part of
1041 # Kconfig.eval_string().
1042 self._parsing_kconfigs = True
1044 self.modules = self._lookup_sym("MODULES")
1045 self.defconfig_list = None
1047 self.top_node = MenuNode()
1048 self.top_node.kconfig = self
1049 self.top_node.item = MENU
1050 self.top_node.is_menuconfig = True
1051 self.top_node.visibility = self.y
1052 self.top_node.prompt = ("Main menu", self.y)
1053 self.top_node.parent = None
1054 self.top_node.dep = self.y
1055 self.top_node.filename = filename
1056 self.top_node.linenr = 1
1057 self.top_node.include_path = ()
1059 # Parse the Kconfig files
1061 # Not used internally. Provided as a convenience.
1062 self.kconfig_filenames = [filename]
1063 self.env_vars = set()
1065 # Keeps track of the location in the parent Kconfig files. Kconfig
1066 # files usually source other Kconfig files. See _enter_file().
1067 self._filestack = []
1068 self._include_path = ()
1070 # The current parsing location
1071 self.filename = filename
1074 # Used to avoid retokenizing lines when we discover that they're not
1075 # part of the construct currently being parsed. This is kinda like an
1077 self._reuse_tokens = False
1079 # Open the top-level Kconfig file. Store the readline() method directly
1080 # as a small optimization.
1081 self._readline = self._open(join(self.srctree, filename), "r").readline
1084 # Parse the Kconfig files. Returns the last node, which we
1085 # terminate with '.next = None'.
1086 self._parse_block(None, self.top_node, self.top_node).next = None
1087 self.top_node.list = self.top_node.next
1088 self.top_node.next = None
1089 except UnicodeDecodeError as e:
1090 _decoding_error(e, self.filename)
1092 # Close the top-level Kconfig file. __self__ fetches the 'file' object
1094 self._readline.__self__.close()
1096 self._parsing_kconfigs = False
1098 # Do various menu tree post-processing
1099 self._finalize_node(self.top_node, self.y)
1101 self.unique_defined_syms = _ordered_unique(self.defined_syms)
1102 self.unique_choices = _ordered_unique(self.choices)
1104 # Do sanity checks. Some of these depend on everything being finalized.
1105 self._check_sym_sanity()
1106 self._check_choice_sanity()
1108 # KCONFIG_STRICT is an older alias for KCONFIG_WARN_UNDEF, supported
1109 # for backwards compatibility
1110 if os.getenv("KCONFIG_WARN_UNDEF") == "y" or \
1111 os.getenv("KCONFIG_STRICT") == "y":
1113 self._check_undef_syms()
1115 # Build Symbol._dependents for all symbols and choices
1118 # Check for dependency loops
1119 check_dep_loop_sym = _check_dep_loop_sym # Micro-optimization
1120 for sym in self.unique_defined_syms:
1121 check_dep_loop_sym(sym, False)
1123 # Add extra dependencies from choices to choice symbols that get
1124 # awkward during dependency loop detection
1125 self._add_choice_deps()
1128 def mainmenu_text(self):
1130 See the class documentation.
1132 return self.top_node.prompt[0]
1135 def defconfig_filename(self):
1137 See the class documentation.
1139 if self.defconfig_list:
1140 for filename, cond in self.defconfig_list.defaults:
1141 if expr_value(cond):
1143 with self._open_config(filename.str_value) as f:
1145 except EnvironmentError:
1150 def load_config(self, filename=None, replace=True, verbose=None):
1152 Loads symbol values from a file in the .config format. Equivalent to
1153 calling Symbol.set_value() to set each of the values.
1155 "# CONFIG_FOO is not set" within a .config file sets the user value of
1156 FOO to n. The C tools work the same way.
1158 For each symbol, the Symbol.user_value attribute holds the value the
1159 symbol was assigned in the .config file (if any). The user value might
1160 differ from Symbol.str/tri_value if there are unsatisfied dependencies.
1162 Calling this function also updates the Kconfig.missing_syms attribute
1163 with a list of all assignments to undefined symbols within the
1164 configuration file. Kconfig.missing_syms is cleared if 'replace' is
1165 True, and appended to otherwise. See the documentation for
1166 Kconfig.missing_syms as well.
1168 See the Kconfig.__init__() docstring for raised exceptions
1169 (OSError/IOError). KconfigError is never raised here.
1171 filename (default: None):
1172 Path to load configuration from (a string). Respects $srctree if set
1173 (see the class documentation).
1175 If 'filename' is None (the default), the configuration file to load
1176 (if any) is calculated automatically, giving the behavior you'd
1179 1. If the KCONFIG_CONFIG environment variable is set, it gives the
1180 path to the configuration file to load. Otherwise, ".config" is
1181 used. See standard_config_filename().
1183 2. If the path from (1.) doesn't exist, the configuration file
1184 given by kconf.defconfig_filename is loaded instead, which is
1185 derived from the 'option defconfig_list' symbol.
1187 3. If (1.) and (2.) fail to find a configuration file to load, no
1188 configuration file is loaded, and symbols retain their current
1189 values (e.g., their default values). This is not an error.
1191 See the return value as well.
1193 replace (default: True):
1194 If True, all existing user values will be cleared before loading the
1195 .config. Pass False to merge configurations.
1197 verbose (default: None):
1198 Limited backwards compatibility to prevent crashes. A warning is
1199 printed if anything but None is passed.
1201 Prior to Kconfiglib 12.0.0, this option enabled printing of messages
1202 to stdout when 'filename' was None. A message is (always) returned
1203 now instead, which is more flexible.
1205 Will probably be removed in some future version.
1207 Returns a string with a message saying which file got loaded (or
1208 possibly that no file got loaded, when 'filename' is None). This is
1209 meant to reduce boilerplate in tools, which can do e.g.
1210 print(kconf.load_config()). The returned message distinguishes between
1211 loading (replace == True) and merging (replace == False).
1213 if verbose is not None:
1214 _warn_verbose_deprecated("load_config")
1217 if filename is None:
1218 filename = standard_config_filename()
1219 if not exists(filename) and \
1220 not exists(join(self.srctree, filename)):
1221 defconfig = self.defconfig_filename
1222 if defconfig is None:
1223 return "Using default symbol values (no '{}')" \
1226 msg = " default configuration '{}' (no '{}')" \
1227 .format(defconfig, filename)
1228 filename = defconfig
1231 msg = " configuration '{}'".format(filename)
1233 # Disable the warning about assigning to symbols without prompts. This
1234 # is normal and expected within a .config file.
1235 self._warn_assign_no_prompt = False
1237 # This stub only exists to make sure _warn_assign_no_prompt gets
1240 self._load_config(filename, replace)
1241 except UnicodeDecodeError as e:
1242 _decoding_error(e, filename)
1244 self._warn_assign_no_prompt = True
1246 return ("Loaded" if replace else "Merged") + msg
1248 def _load_config(self, filename, replace):
1249 with self._open_config(filename) as f:
1251 self.missing_syms = []
1253 # If we're replacing the configuration, keep track of which
1254 # symbols and choices got set so that we can unset the rest
1255 # later. This avoids invalidating everything and is faster.
1256 # Another benefit is that invalidation must be rock solid for
1257 # it to work, making it a good test.
1259 for sym in self.unique_defined_syms:
1260 sym._was_set = False
1262 for choice in self.unique_choices:
1263 choice._was_set = False
1265 # Small optimizations
1266 set_match = self._set_match
1267 unset_match = self._unset_match
1268 get_sym = self.syms.get
1270 for linenr, line in enumerate(f, 1):
1271 # The C tools ignore trailing whitespace
1272 line = line.rstrip()
1274 match = set_match(line)
1276 name, val = match.groups()
1278 if not sym or not sym.nodes:
1279 self._undef_assign(name, val, filename, linenr)
1282 if sym.orig_type in _BOOL_TRISTATE:
1283 # The C implementation only checks the first character
1284 # to the right of '=', for whatever reason
1285 if not (sym.orig_type is BOOL
1286 and val.startswith(("y", "n")) or
1287 sym.orig_type is TRISTATE
1288 and val.startswith(("y", "m", "n"))):
1289 self._warn("'{}' is not a valid value for the {} "
1290 "symbol {}. Assignment ignored."
1291 .format(val, TYPE_TO_STR[sym.orig_type],
1298 if sym.choice and val != "n":
1299 # During .config loading, we infer the mode of the
1300 # choice from the kind of values that are assigned
1301 # to the choice symbols
1303 prev_mode = sym.choice.user_value
1304 if prev_mode is not None and \
1305 TRI_TO_STR[prev_mode] != val:
1307 self._warn("both m and y assigned to symbols "
1308 "within the same choice",
1311 # Set the choice's mode
1312 sym.choice.set_value(val)
1314 elif sym.orig_type is STRING:
1315 match = _conf_string_match(val)
1317 self._warn("malformed string literal in "
1318 "assignment to {}. Assignment ignored."
1319 .format(sym.name_and_loc),
1323 val = unescape(match.group(1))
1326 match = unset_match(line)
1328 # Print a warning for lines that match neither
1329 # set_match() nor unset_match() and that are not blank
1330 # lines or comments. 'line' has already been
1331 # rstrip()'d, so blank lines show up as "" here.
1332 if line and not line.lstrip().startswith("#"):
1333 self._warn("ignoring malformed line '{}'"
1339 name = match.group(1)
1341 if not sym or not sym.nodes:
1342 self._undef_assign(name, "n", filename, linenr)
1345 if sym.orig_type not in _BOOL_TRISTATE:
1350 # Done parsing the assignment. Set the value.
1353 self._assigned_twice(sym, val, filename, linenr)
1358 # If we're replacing the configuration, unset the symbols that
1361 for sym in self.unique_defined_syms:
1362 if not sym._was_set:
1365 for choice in self.unique_choices:
1366 if not choice._was_set:
1367 choice.unset_value()
1369 def _undef_assign(self, name, val, filename, linenr):
1370 # Called for assignments to undefined symbols during .config loading
1372 self.missing_syms.append((name, val))
1373 if self.warn_assign_undef:
1375 "attempt to assign the value '{}' to the undefined symbol {}"
1376 .format(val, name), filename, linenr)
1378 def _assigned_twice(self, sym, new_val, filename, linenr):
1379 # Called when a symbol is assigned more than once in a .config file
1381 # Use strings for bool/tristate user values in the warning
1382 if sym.orig_type in _BOOL_TRISTATE:
1383 user_val = TRI_TO_STR[sym.user_value]
1385 user_val = sym.user_value
1387 msg = '{} set more than once. Old value "{}", new value "{}".'.format(
1388 sym.name_and_loc, user_val, new_val)
1390 if user_val == new_val:
1391 if self.warn_assign_redun:
1392 self._warn(msg, filename, linenr)
1393 elif self.warn_assign_override:
1394 self._warn(msg, filename, linenr)
1396 def load_allconfig(self, filename):
1398 Helper for all*config. Loads (merges) the configuration file specified
1399 by KCONFIG_ALLCONFIG, if any. See Documentation/kbuild/kconfig.txt in
1402 Disables warnings for duplicated assignments within configuration files
1403 for the duration of the call
1404 (kconf.warn_assign_override/warn_assign_redun = False), and restores
1405 the previous warning settings at the end. The KCONFIG_ALLCONFIG
1406 configuration file is expected to override symbols.
1408 Exits with sys.exit() (which raises a SystemExit exception) and prints
1409 an error to stderr if KCONFIG_ALLCONFIG is set but the configuration
1410 file can't be opened.
1413 Command-specific configuration filename - "allyes.config",
1414 "allno.config", etc.
1416 load_allconfig(self, filename)
1418 def write_autoconf(self, filename=None, header=None):
1420 Writes out symbol values as a C header file, matching the format used
1421 by include/generated/autoconf.h in the kernel.
1423 The ordering of the #defines matches the one generated by
1424 write_config(). The order in the C implementation depends on the hash
1425 table implementation as of writing, and so won't match.
1427 If 'filename' exists and its contents is identical to what would get
1428 written out, it is left untouched. This avoids updating file metadata
1429 like the modification time and possibly triggering redundant work in
1432 filename (default: None):
1433 Path to write header to.
1435 If None (the default), the path in the environment variable
1436 KCONFIG_AUTOHEADER is used if set, and "include/generated/autoconf.h"
1437 otherwise. This is compatible with the C tools.
1439 header (default: None):
1440 Text inserted verbatim at the beginning of the file. You would
1441 usually want it enclosed in '/* */' to make it a C comment, and
1442 include a trailing newline.
1444 If None (the default), the value of the environment variable
1445 KCONFIG_AUTOHEADER_HEADER had when the Kconfig instance was created
1446 will be used if it was set, and no header otherwise. See the
1447 Kconfig.header_header attribute.
1449 Returns a string with a message saying that the header got saved, or
1450 that there were no changes to it. This is meant to reduce boilerplate
1451 in tools, which can do e.g. print(kconf.write_autoconf()).
1453 if filename is None:
1454 filename = os.getenv("KCONFIG_AUTOHEADER",
1455 "include/generated/autoconf.h")
1457 if self._write_if_changed(filename, self._autoconf_contents(header)):
1458 return "Kconfig header saved to '{}'".format(filename)
1459 return "No change to Kconfig header in '{}'".format(filename)
1461 def _autoconf_contents(self, header):
1462 # write_autoconf() helper. Returns the contents to write as a string,
1463 # with 'header' or KCONFIG_AUTOHEADER_HEADER at the beginning.
1466 header = self.header_header
1468 chunks = [header] # "".join()ed later
1471 for sym in self.unique_defined_syms:
1472 # _write_to_conf is determined when the value is calculated. This
1473 # is a hidden function call due to property magic.
1475 # Note: In client code, you can check if sym.config_string is empty
1476 # instead, to avoid accessing the internal _write_to_conf variable
1477 # (though it's likely to keep working).
1479 if not sym._write_to_conf:
1482 if sym.orig_type in _BOOL_TRISTATE:
1484 add("#define {}{} 1\n"
1485 .format(self.config_prefix, sym.name))
1487 add("#define {}{}_MODULE 1\n"
1488 .format(self.config_prefix, sym.name))
1490 elif sym.orig_type is STRING:
1491 add('#define {}{} "{}"\n'
1492 .format(self.config_prefix, sym.name, escape(val)))
1494 else: # sym.orig_type in _INT_HEX:
1495 if sym.orig_type is HEX and \
1496 not val.startswith(("0x", "0X")):
1499 add("#define {}{} {}\n"
1500 .format(self.config_prefix, sym.name, val))
1502 return "".join(chunks)
1504 def write_config(self, filename=None, header=None, save_old=True,
1507 Writes out symbol values in the .config format. The format matches the
1508 C implementation, including ordering.
1510 Symbols appear in the same order in generated .config files as they do
1511 in the Kconfig files. For symbols defined in multiple locations, a
1512 single assignment is written out corresponding to the first location
1513 where the symbol is defined.
1515 See the 'Intro to symbol values' section in the module docstring to
1516 understand which symbols get written out.
1518 If 'filename' exists and its contents is identical to what would get
1519 written out, it is left untouched. This avoids updating file metadata
1520 like the modification time and possibly triggering redundant work in
1523 See the Kconfig.__init__() docstring for raised exceptions
1524 (OSError/IOError). KconfigError is never raised here.
1526 filename (default: None):
1527 Path to write configuration to (a string).
1529 If None (the default), the path in the environment variable
1530 KCONFIG_CONFIG is used if set, and ".config" otherwise. See
1531 standard_config_filename().
1533 header (default: None):
1534 Text inserted verbatim at the beginning of the file. You would
1535 usually want each line to start with '#' to make it a comment, and
1536 include a trailing newline.
1538 if None (the default), the value of the environment variable
1539 KCONFIG_CONFIG_HEADER had when the Kconfig instance was created will
1540 be used if it was set, and no header otherwise. See the
1541 Kconfig.config_header attribute.
1543 save_old (default: True):
1544 If True and <filename> already exists, a copy of it will be saved to
1545 <filename>.old in the same directory before the new configuration is
1548 Errors are silently ignored if <filename>.old cannot be written (e.g.
1549 due to being a directory, or <filename> being something like
1552 verbose (default: None):
1553 Limited backwards compatibility to prevent crashes. A warning is
1554 printed if anything but None is passed.
1556 Prior to Kconfiglib 12.0.0, this option enabled printing of messages
1557 to stdout when 'filename' was None. A message is (always) returned
1558 now instead, which is more flexible.
1560 Will probably be removed in some future version.
1562 Returns a string with a message saying which file got saved. This is
1563 meant to reduce boilerplate in tools, which can do e.g.
1564 print(kconf.write_config()).
1566 if verbose is not None:
1567 _warn_verbose_deprecated("write_config")
1569 if filename is None:
1570 filename = standard_config_filename()
1572 contents = self._config_contents(header)
1573 if self._contents_eq(filename, contents):
1574 return "No change to configuration in '{}'".format(filename)
1579 with self._open(filename, "w") as f:
1582 return "Configuration saved to '{}'".format(filename)
1584 def _config_contents(self, header):
1585 # write_config() helper. Returns the contents to write as a string,
1586 # with 'header' or KCONFIG_CONFIG_HEADER at the beginning.
1588 # More memory friendly would be to 'yield' the strings and
1589 # "".join(_config_contents()), but it was a bit slower on my system.
1591 # node_iter() was used here before commit 3aea9f7 ("Add '# end of
1592 # <menu>' after menus in .config"). Those comments get tricky to
1593 # implement with it.
1595 for sym in self.unique_defined_syms:
1596 sym._visited = False
1599 header = self.config_header
1601 chunks = [header] # "".join()ed later
1604 # Did we just print an '# end of ...' comment?
1605 after_end_comment = False
1607 node = self.top_node
1609 # Jump to the next node with an iterative tree walk
1618 # Add a comment when leaving visible menus
1619 if node.item is MENU and expr_value(node.dep) and \
1620 expr_value(node.visibility) and \
1621 node is not self.top_node:
1622 add("# end of {}\n".format(node.prompt[0]))
1623 after_end_comment = True
1630 return "".join(chunks)
1632 # Generate configuration output for the node
1636 if item.__class__ is Symbol:
1639 item._visited = True
1641 conf_string = item.config_string
1645 if after_end_comment:
1646 # Add a blank line before the first symbol printed after an
1647 # '# end of ...' comment
1648 after_end_comment = False
1652 elif expr_value(node.dep) and \
1653 ((item is MENU and expr_value(node.visibility)) or
1656 add("\n#\n# {}\n#\n".format(node.prompt[0]))
1657 after_end_comment = False
1659 def write_min_config(self, filename, header=None):
1661 Writes out a "minimal" configuration file, omitting symbols whose value
1662 matches their default value. The format matches the one produced by
1663 'make savedefconfig'.
1665 The resulting configuration file is incomplete, but a complete
1666 configuration can be derived from it by loading it. Minimal
1667 configuration files can serve as a more manageable configuration format
1668 compared to a "full" .config file, especially when configurations files
1669 are merged or edited by hand.
1671 See the Kconfig.__init__() docstring for raised exceptions
1672 (OSError/IOError). KconfigError is never raised here.
1675 Path to write minimal configuration to.
1677 header (default: None):
1678 Text inserted verbatim at the beginning of the file. You would
1679 usually want each line to start with '#' to make it a comment, and
1680 include a final terminating newline.
1682 if None (the default), the value of the environment variable
1683 KCONFIG_CONFIG_HEADER had when the Kconfig instance was created will
1684 be used if it was set, and no header otherwise. See the
1685 Kconfig.config_header attribute.
1687 Returns a string with a message saying the minimal configuration got
1688 saved, or that there were no changes to it. This is meant to reduce
1689 boilerplate in tools, which can do e.g.
1690 print(kconf.write_min_config()).
1692 if self._write_if_changed(filename, self._min_config_contents(header)):
1693 return "Minimal configuration saved to '{}'".format(filename)
1694 return "No change to minimal configuration in '{}'".format(filename)
1696 def _min_config_contents(self, header):
1697 # write_min_config() helper. Returns the contents to write as a string,
1698 # with 'header' or KCONFIG_CONFIG_HEADER at the beginning.
1701 header = self.config_header
1703 chunks = [header] # "".join()ed later
1706 for sym in self.unique_defined_syms:
1707 # Skip symbols that cannot be changed. Only check
1708 # non-choice symbols, as selects don't affect choice
1710 if not sym.choice and \
1711 sym.visibility <= expr_value(sym.rev_dep):
1714 # Skip symbols whose value matches their default
1715 if sym.str_value == sym._str_default():
1718 # Skip symbols that would be selected by default in a
1719 # choice, unless the choice is optional or the symbol type
1720 # isn't bool (it might be possible to set the choice mode
1721 # to n or the symbol to m in those cases).
1723 not sym.choice.is_optional and \
1724 sym.choice._selection_from_defaults() is sym and \
1725 sym.orig_type is BOOL and \
1729 add(sym.config_string)
1731 return "".join(chunks)
1733 def sync_deps(self, path):
1735 Creates or updates a directory structure that can be used to avoid
1736 doing a full rebuild whenever the configuration is changed, mirroring
1737 include/config/ in the kernel.
1739 This function is intended to be called during each build, before
1740 compiling source files that depend on configuration symbols.
1742 See the Kconfig.__init__() docstring for raised exceptions
1743 (OSError/IOError). KconfigError is never raised here.
1748 sync_deps(path) does the following:
1750 1. If the directory <path> does not exist, it is created.
1752 2. If <path>/auto.conf exists, old symbol values are loaded from it,
1753 which are then compared against the current symbol values. If a
1754 symbol has changed value (would generate different output in
1755 autoconf.h compared to before), the change is signaled by
1756 touch'ing a file corresponding to the symbol.
1758 The first time sync_deps() is run on a directory, <path>/auto.conf
1759 won't exist, and no old symbol values will be available. This
1760 logically has the same effect as updating the entire
1763 The path to a symbol's file is calculated from the symbol's name
1764 by replacing all '_' with '/' and appending '.h'. For example, the
1765 symbol FOO_BAR_BAZ gets the file <path>/foo/bar/baz.h, and FOO
1766 gets the file <path>/foo.h.
1768 This scheme matches the C tools. The point is to avoid having a
1769 single directory with a huge number of files, which the underlying
1770 filesystem might not handle well.
1772 3. A new auto.conf with the current symbol values is written, to keep
1773 track of them for the next build.
1775 If auto.conf exists and its contents is identical to what would
1776 get written out, it is left untouched. This avoids updating file
1777 metadata like the modification time and possibly triggering
1778 redundant work in build tools.
1781 The last piece of the puzzle is knowing what symbols each source file
1782 depends on. Knowing that, dependencies can be added from source files
1783 to the files corresponding to the symbols they depends on. The source
1784 file will then get recompiled (only) when the symbol value changes
1785 (provided sync_deps() is run first during each build).
1787 The tool in the kernel that extracts symbol dependencies from source
1788 files is scripts/basic/fixdep.c. Missing symbol files also correspond
1789 to "not changed", which fixdep deals with by using the $(wildcard) Make
1790 function when adding symbol prerequisites to source files.
1792 In case you need a different scheme for your project, the sync_deps()
1793 implementation can be used as a template.
1795 if not exists(path):
1796 os.mkdir(path, 0o755)
1798 # Load old values from auto.conf, if any
1799 self._load_old_vals(path)
1801 for sym in self.unique_defined_syms:
1802 # _write_to_conf is determined when the value is calculated. This
1803 # is a hidden function call due to property magic.
1805 # Note: In client code, you can check if sym.config_string is empty
1806 # instead, to avoid accessing the internal _write_to_conf variable
1807 # (though it's likely to keep working).
1810 # n tristate values do not get written to auto.conf and autoconf.h,
1811 # making a missing symbol logically equivalent to n
1813 if sym._write_to_conf:
1814 if sym._old_val is None and \
1815 sym.orig_type in _BOOL_TRISTATE and \
1817 # No old value (the symbol was missing or n), new value n.
1821 if val == sym._old_val:
1822 # New value matches old. No change.
1825 elif sym._old_val is None:
1826 # The symbol wouldn't appear in autoconf.h (because
1827 # _write_to_conf is false), and it wouldn't have appeared in
1828 # autoconf.h previously either (because it didn't appear in
1829 # auto.conf). No change.
1832 # 'sym' has a new value. Flag it.
1833 _touch_dep_file(path, sym.name)
1835 # Remember the current values as the "new old" values.
1837 # This call could go anywhere after the call to _load_old_vals(), but
1838 # putting it last means _sync_deps() can be safely rerun if it fails
1839 # before this point.
1840 self._write_old_vals(path)
1842 def _load_old_vals(self, path):
1843 # Loads old symbol values from auto.conf into a dedicated
1844 # Symbol._old_val field. Mirrors load_config().
1846 # The extra field could be avoided with some trickery involving dumping
1847 # symbol values and restoring them later, but this is simpler and
1848 # faster. The C tools also use a dedicated field for this purpose.
1850 for sym in self.unique_defined_syms:
1854 auto_conf = self._open(join(path, "auto.conf"), "r")
1855 except EnvironmentError as e:
1856 if e.errno == errno.ENOENT:
1861 with auto_conf as f:
1863 match = self._set_match(line)
1865 # We only expect CONFIG_FOO=... (and possibly a header
1866 # comment) in auto.conf
1869 name, val = match.groups()
1870 if name in self.syms:
1871 sym = self.syms[name]
1873 if sym.orig_type is STRING:
1874 match = _conf_string_match(val)
1877 val = unescape(match.group(1))
1879 self.syms[name]._old_val = val
1881 # Flag that the symbol no longer exists, in
1882 # case something still depends on it
1883 _touch_dep_file(path, name)
1885 def _write_old_vals(self, path):
1886 # Helper for writing auto.conf. Basically just a simplified
1887 # write_config() that doesn't write any comments (including
1888 # '# CONFIG_FOO is not set' comments). The format matches the C
1889 # implementation, though the ordering is arbitrary there (depends on
1890 # the hash table implementation).
1892 # A separate helper function is neater than complicating write_config()
1893 # by passing a flag to it, plus we only need to look at symbols here.
1895 self._write_if_changed(
1896 os.path.join(path, "auto.conf"),
1897 self._old_vals_contents())
1899 def _old_vals_contents(self):
1900 # _write_old_vals() helper. Returns the contents to write as a string.
1902 # Temporary list instead of generator makes this a bit faster
1904 sym.config_string for sym in self.unique_defined_syms
1905 if not (sym.orig_type in _BOOL_TRISTATE and not sym.tri_value)
1908 def node_iter(self, unique_syms=False):
1910 Returns a generator for iterating through all MenuNode's in the Kconfig
1911 tree. The iteration is done in Kconfig definition order (each node is
1912 visited before its children, and the children of a node are visited
1913 before the next node).
1915 The Kconfig.top_node menu node is skipped. It contains an implicit menu
1916 that holds the top-level items.
1918 As an example, the following code will produce a list equal to
1919 Kconfig.defined_syms:
1921 defined_syms = [node.item for node in kconf.node_iter()
1922 if isinstance(node.item, Symbol)]
1924 unique_syms (default: False):
1925 If True, only the first MenuNode will be included for symbols defined
1926 in multiple locations.
1928 Using kconf.node_iter(True) in the example above would give a list
1929 equal to unique_defined_syms.
1932 for sym in self.unique_defined_syms:
1933 sym._visited = False
1935 node = self.top_node
1937 # Jump to the next node with an iterative tree walk
1952 if unique_syms and node.item.__class__ is Symbol:
1953 if node.item._visited:
1955 node.item._visited = True
1959 def eval_string(self, s):
1961 Returns the tristate value of the expression 's', represented as 0, 1,
1962 and 2 for n, m, and y, respectively. Raises KconfigError on syntax
1963 errors. Warns if undefined symbols are referenced.
1965 As an example, if FOO and BAR are tristate symbols at least one of
1966 which has the value y, then eval_string("y && (FOO || BAR)") returns
1969 To get the string value of non-bool/tristate symbols, use
1970 Symbol.str_value. eval_string() always returns a tristate value, and
1971 all non-bool/tristate symbols have the tristate value 0 (n).
1973 The expression parsing is consistent with how parsing works for
1974 conditional ('if ...') expressions in the configuration, and matches
1975 the C implementation. m is rewritten to 'm && MODULES', so
1976 eval_string("m") will return 0 (n) unless modules are enabled.
1978 # The parser is optimized to be fast when parsing Kconfig files (where
1979 # an expression can never appear at the beginning of a line). We have
1980 # to monkey-patch things a bit here to reuse it.
1982 self.filename = None
1984 self._tokens = self._tokenize("if " + s)
1985 # Strip "if " to avoid giving confusing error messages
1987 self._tokens_i = 1 # Skip the 'if' token
1989 return expr_value(self._expect_expr_and_eol())
1991 def unset_values(self):
1993 Removes any user values from all symbols, as if Kconfig.load_config()
1994 or Symbol.set_value() had never been called.
1996 self._warn_assign_no_prompt = False
1998 # set_value() already rejects undefined symbols, and they don't
1999 # need to be invalidated (because their value never changes), so we
2000 # can just iterate over defined symbols
2001 for sym in self.unique_defined_syms:
2004 for choice in self.unique_choices:
2005 choice.unset_value()
2007 self._warn_assign_no_prompt = True
2009 def enable_warnings(self):
2011 Do 'Kconfig.warn = True' instead. Maintained for backwards
2016 def disable_warnings(self):
2018 Do 'Kconfig.warn = False' instead. Maintained for backwards
2023 def enable_stderr_warnings(self):
2025 Do 'Kconfig.warn_to_stderr = True' instead. Maintained for backwards
2028 self.warn_to_stderr = True
2030 def disable_stderr_warnings(self):
2032 Do 'Kconfig.warn_to_stderr = False' instead. Maintained for backwards
2035 self.warn_to_stderr = False
2037 def enable_undef_warnings(self):
2039 Do 'Kconfig.warn_assign_undef = True' instead. Maintained for backwards
2042 self.warn_assign_undef = True
2044 def disable_undef_warnings(self):
2046 Do 'Kconfig.warn_assign_undef = False' instead. Maintained for
2047 backwards compatibility.
2049 self.warn_assign_undef = False
2051 def enable_override_warnings(self):
2053 Do 'Kconfig.warn_assign_override = True' instead. Maintained for
2054 backwards compatibility.
2056 self.warn_assign_override = True
2058 def disable_override_warnings(self):
2060 Do 'Kconfig.warn_assign_override = False' instead. Maintained for
2061 backwards compatibility.
2063 self.warn_assign_override = False
2065 def enable_redun_warnings(self):
2067 Do 'Kconfig.warn_assign_redun = True' instead. Maintained for backwards
2070 self.warn_assign_redun = True
2072 def disable_redun_warnings(self):
2074 Do 'Kconfig.warn_assign_redun = False' instead. Maintained for
2075 backwards compatibility.
2077 self.warn_assign_redun = False
2081 Returns a string with information about the Kconfig object when it is
2082 evaluated on e.g. the interactive Python prompt.
2085 return "enabled" if flag else "disabled"
2087 return "<{}>".format(", ".join((
2088 "configuration with {} symbols".format(len(self.syms)),
2089 'main menu prompt "{}"'.format(self.mainmenu_text),
2090 "srctree is current directory" if not self.srctree else
2091 'srctree "{}"'.format(self.srctree),
2092 'config symbol prefix "{}"'.format(self.config_prefix),
2093 "warnings " + status(self.warn),
2094 "printing of warnings to stderr " + status(self.warn_to_stderr),
2095 "undef. symbol assignment warnings " +
2096 status(self.warn_assign_undef),
2097 "overriding symbol assignment warnings " +
2098 status(self.warn_assign_override),
2099 "redundant symbol assignment warnings " +
2100 status(self.warn_assign_redun)
2112 def _open_config(self, filename):
2113 # Opens a .config file. First tries to open 'filename', then
2114 # '$srctree/filename' if $srctree was set when the configuration was
2118 return self._open(filename, "r")
2119 except EnvironmentError as e:
2120 # This will try opening the same file twice if $srctree is unset,
2121 # but it's not a big deal
2123 return self._open(join(self.srctree, filename), "r")
2124 except EnvironmentError as e2:
2125 # This is needed for Python 3, because e2 is deleted after
2128 # https://docs.python.org/3/reference/compound_stmts.html#the-try-statement
2131 raise _KconfigIOError(
2132 e, "Could not open '{}' ({}: {}). Check that the $srctree "
2133 "environment variable ({}) is set correctly."
2134 .format(filename, errno.errorcode[e.errno], e.strerror,
2135 "set to '{}'".format(self.srctree) if self.srctree
2136 else "unset or blank"))
2138 def _enter_file(self, filename):
2139 # Jumps to the beginning of a sourced Kconfig file, saving the previous
2140 # position and file object.
2143 # Absolute path to file
2145 # Path relative to $srctree, stored in e.g. self.filename (which makes
2146 # it indirectly show up in MenuNode.filename). Equals 'filename' for
2147 # absolute paths passed to 'source'.
2148 if filename.startswith(self._srctree_prefix):
2149 # Relative path (or a redundant absolute path to within $srctree,
2150 # but it's probably fine to reduce those too)
2151 rel_filename = filename[len(self._srctree_prefix):]
2154 rel_filename = filename
2156 self.kconfig_filenames.append(rel_filename)
2158 # The parent Kconfig files are represented as a list of
2159 # (<include path>, <Python 'file' object for Kconfig file>) tuples.
2161 # <include path> is immutable and holds a *tuple* of
2162 # (<filename>, <linenr>) tuples, giving the locations of the 'source'
2163 # statements in the parent Kconfig files. The current include path is
2164 # also available in Kconfig._include_path.
2166 # The point of this redundant setup is to allow Kconfig._include_path
2167 # to be assigned directly to MenuNode.include_path without having to
2168 # copy it, sharing it wherever possible.
2170 # Save include path and 'file' object (via its 'readline' function)
2171 # before entering the file
2172 self._filestack.append((self._include_path, self._readline))
2174 # _include_path is a tuple, so this rebinds the variable instead of
2175 # doing in-place modification
2176 self._include_path += ((self.filename, self.linenr),)
2178 # Check for recursive 'source'
2179 for name, _ in self._include_path:
2180 if name == rel_filename:
2182 "\n{}:{}: recursive 'source' of '{}' detected. Check that "
2183 "environment variables are set correctly.\n"
2185 .format(self.filename, self.linenr, rel_filename,
2186 "\n".join("{}:{}".format(name, linenr)
2187 for name, linenr in self._include_path)))
2190 self._readline = self._open(filename, "r").readline
2191 except EnvironmentError as e:
2192 # We already know that the file exists
2193 raise _KconfigIOError(
2194 e, "{}:{}: Could not open '{}' (in '{}') ({}: {})"
2195 .format(self.filename, self.linenr, filename,
2197 errno.errorcode[e.errno], e.strerror))
2199 self.filename = rel_filename
2202 def _leave_file(self):
2203 # Returns from a Kconfig file to the file that sourced it. See
2206 # Restore location from parent Kconfig file
2207 self.filename, self.linenr = self._include_path[-1]
2208 # Restore include path and 'file' object
2209 self._readline.__self__.close() # __self__ fetches the 'file' object
2210 self._include_path, self._readline = self._filestack.pop()
2212 def _next_line(self):
2213 # Fetches and tokenizes the next line from the current Kconfig file.
2214 # Returns False at EOF and True otherwise.
2216 # We might already have tokens from parsing a line and discovering that
2217 # it's part of a different construct
2218 if self._reuse_tokens:
2219 self._reuse_tokens = False
2220 # self._tokens_i is known to be 1 here, because _parse_props()
2221 # leaves it like that when it can't recognize a line (or parses a
2225 # readline() returns '' over and over at EOF, which we rely on for help
2226 # texts at the end of files (see _line_after_help())
2227 line = self._readline()
2232 # Handle line joining
2233 while line.endswith("\\\n"):
2234 line = line[:-2] + self._readline()
2237 self._tokens = self._tokenize(line)
2238 # Initialize to 1 instead of 0 to factor out code from _parse_block()
2239 # and _parse_props(). They immediately fetch self._tokens[0].
2244 def _line_after_help(self, line):
2245 # Tokenizes a line after a help text. This case is special in that the
2246 # line has already been fetched (to discover that it isn't part of the
2249 # An earlier version used a _saved_line variable instead that was
2250 # checked in _next_line(). This special-casing gets rid of it and makes
2251 # _reuse_tokens alone sufficient to handle unget.
2253 # Handle line joining
2254 while line.endswith("\\\n"):
2255 line = line[:-2] + self._readline()
2258 self._tokens = self._tokenize(line)
2259 self._reuse_tokens = True
2261 def _write_if_changed(self, filename, contents):
2262 # Writes 'contents' into 'filename', but only if it differs from the
2263 # current contents of the file.
2265 # Another variant would be write a temporary file on the same
2266 # filesystem, compare the files, and rename() the temporary file if it
2267 # differs, but it breaks stuff like write_config("/dev/null"), which is
2268 # used out there to force evaluation-related warnings to be generated.
2269 # This simple version is pretty failsafe and portable.
2271 # Returns True if the file has changed and is updated, and False
2274 if self._contents_eq(filename, contents):
2276 with self._open(filename, "w") as f:
2280 def _contents_eq(self, filename, contents):
2281 # Returns True if the contents of 'filename' is 'contents' (a string),
2282 # and False otherwise (including if 'filename' can't be opened/read)
2285 with self._open(filename, "r") as f:
2286 # Robust re. things like encoding and line endings (mmap()
2288 return f.read(len(contents) + 1) == contents
2289 except EnvironmentError:
2290 # If the error here would prevent writing the file as well, we'll
2298 def _lookup_sym(self, name):
2299 # Fetches the symbol 'name' from the symbol table, creating and
2300 # registering it if it does not exist. If '_parsing_kconfigs' is False,
2301 # it means we're in eval_string(), and new symbols won't be registered.
2303 if name in self.syms:
2304 return self.syms[name]
2309 sym.is_constant = False
2310 sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n
2312 if self._parsing_kconfigs:
2313 self.syms[name] = sym
2315 self._warn("no symbol {} in configuration".format(name))
2319 def _lookup_const_sym(self, name):
2320 # Like _lookup_sym(), for constant (quoted) symbols
2322 if name in self.const_syms:
2323 return self.const_syms[name]
2328 sym.is_constant = True
2329 sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n
2331 if self._parsing_kconfigs:
2332 self.const_syms[name] = sym
2336 def _tokenize(self, s):
2337 # Parses 's', returning a None-terminated list of tokens. Registers any
2338 # new symbols encountered with _lookup(_const)_sym().
2340 # Tries to be reasonably speedy by processing chunks of text via
2341 # regexes and string operations where possible. This is the biggest
2342 # hotspot during parsing.
2344 # It might be possible to rewrite this to 'yield' tokens instead,
2345 # working across multiple lines. Lookback and compatibility with old
2346 # janky versions of the C tools complicate things though.
2348 self._line = s # Used for error reporting
2350 # Initial token on the line
2351 match = _command_match(s)
2353 if s.isspace() or s.lstrip().startswith("#"):
2355 self._parse_error("unknown token at start of line")
2357 # Tricky implementation detail: While parsing a token, 'token' refers
2358 # to the previous token. See _STRING_LEX for why this is needed.
2359 token = _get_keyword(match.group(1))
2361 # Backwards compatibility with old versions of the C tools, which
2362 # (accidentally) accepted stuff like "--help--" and "-help---".
2363 # This was fixed in the C tools by commit c2264564 ("kconfig: warn
2364 # of unhandled characters in Kconfig commands"), committed in July
2365 # 2015, but it seems people still run Kconfiglib on older kernels.
2366 if s.strip(" \t\n-") == "help":
2367 return (_T_HELP, None)
2369 # If the first token is not a keyword (and not a weird help token),
2370 # we have a preprocessor variable assignment (or a bare macro on a
2372 self._parse_assignment(s)
2376 # The current index in the string being tokenized
2379 # Main tokenization loop (for tokens past the first one)
2381 # Test for an identifier/keyword first. This is the most common
2383 match = _id_keyword_match(s, i)
2385 # We have an identifier or keyword
2387 # Check what it is. lookup_sym() will take care of allocating
2388 # new symbols for us the first time we see them. Note that
2389 # 'token' still refers to the previous token.
2391 name = match.group(1)
2392 keyword = _get_keyword(name)
2399 elif token not in _STRING_LEX:
2400 # It's a non-const symbol, except we translate n, m, and y
2401 # into the corresponding constant symbols, like the C
2405 # Macro expansion within symbol name
2406 name, s, i = self._expand_name(s, i)
2410 token = self.const_syms[name] if name in STR_TO_TRI else \
2411 self._lookup_sym(name)
2414 # It's a case of missing quotes. For example, the
2415 # following is accepted:
2417 # menu unquoted_title
2420 # tristate unquoted_prompt
2424 # Named choices ('choice FOO') also end up here.
2426 if token is not _T_CHOICE:
2427 self._warn("style: quotes recommended around '{}' in '{}'"
2428 .format(name, self._line.strip()),
2429 self.filename, self.linenr)
2435 # Neither a keyword nor a non-const symbol
2437 # We always strip whitespace after tokens, so it is safe to
2438 # assume that s[i] is the start of a token here.
2442 if "$" not in s and "\\" not in s:
2443 # Fast path for lines without $ and \. Find the
2445 end_i = s.find(c, i + 1) + 1
2447 self._parse_error("unterminated string")
2448 val = s[i + 1:end_i - 1]
2452 s, end_i = self._expand_str(s, i)
2454 # os.path.expandvars() and the $UNAME_RELEASE replace()
2455 # is a backwards compatibility hack, which should be
2456 # reasonably safe as expandvars() leaves references to
2457 # undefined env. vars. as is.
2459 # The preprocessor functionality changed how
2460 # environment variables are referenced, to $(FOO).
2461 val = expandvars(s[i + 1:end_i - 1]
2462 .replace("$UNAME_RELEASE",
2467 # This is the only place where we don't survive with a
2468 # single token of lookback: 'option env="FOO"' does not
2469 # refer to a constant symbol named "FOO".
2471 val if token in _STRING_LEX or tokens[0] is _T_OPTION \
2472 else self._lookup_const_sym(val)
2474 elif s.startswith("&&", i):
2478 elif s.startswith("||", i):
2486 elif s.startswith("!=", i):
2495 token = _T_OPEN_PAREN
2499 token = _T_CLOSE_PAREN
2508 elif s.startswith("<=", i):
2509 token = _T_LESS_EQUAL
2516 elif s.startswith(">=", i):
2517 token = _T_GREATER_EQUAL
2526 self._parse_error("unknown tokens in line")
2529 # Skip trailing whitespace
2530 while i < len(s) and s[i].isspace():
2535 tokens.append(token)
2537 # None-terminating the token list makes token fetching simpler/faster
2542 # Helpers for syntax checking and token fetching. See the
2543 # 'Intro to expressions' section for what a constant symbol is.
2545 # More of these could be added, but the single-use cases are inlined as an
2548 def _expect_sym(self):
2549 token = self._tokens[self._tokens_i]
2552 if token.__class__ is not Symbol:
2553 self._parse_error("expected symbol")
2557 def _expect_nonconst_sym(self):
2558 # Used for 'select' and 'imply' only. We know the token indices.
2560 token = self._tokens[1]
2563 if token.__class__ is not Symbol or token.is_constant:
2564 self._parse_error("expected nonconstant symbol")
2568 def _expect_str_and_eol(self):
2569 token = self._tokens[self._tokens_i]
2572 if token.__class__ is not str:
2573 self._parse_error("expected string")
2575 if self._tokens[self._tokens_i] is not None:
2576 self._trailing_tokens_error()
2580 def _expect_expr_and_eol(self):
2581 expr = self._parse_expr(True)
2583 if self._tokens[self._tokens_i] is not None:
2584 self._trailing_tokens_error()
2588 def _check_token(self, token):
2589 # If the next token is 'token', removes it and returns True
2591 if self._tokens[self._tokens_i] is token:
2597 # Preprocessor logic
2600 def _parse_assignment(self, s):
2601 # Parses a preprocessor variable assignment, registering the variable
2602 # if it doesn't already exist. Also takes care of bare macros on lines
2603 # (which are allowed, and can be useful for their side effects).
2605 # Expand any macros in the left-hand side of the assignment (the
2610 i = _assignment_lhs_fragment_match(s, i).end()
2611 if s.startswith("$(", i):
2612 s, i = self._expand_macro(s, i, ())
2617 # We also accept a bare macro on a line (e.g.
2618 # $(warning-if,$(foo),ops)), provided it expands to a blank string
2625 # Extract assignment operator (=, :=, or +=) and value
2626 rhs_match = _assignment_rhs_match(s, i)
2628 self._parse_error("syntax error")
2630 op, val = rhs_match.groups()
2633 if name in self.variables:
2634 # Already seen variable
2635 var = self.variables[name]
2641 var._n_expansions = 0
2642 self.variables[name] = var
2644 # += acts like = on undefined variables (defines a recursive
2650 var.is_recursive = True
2653 var.is_recursive = False
2654 var.value = self._expand_whole(val, ())
2656 # += does immediate expansion if the variable was last set
2658 var.value += " " + (val if var.is_recursive else
2659 self._expand_whole(val, ()))
2661 def _expand_whole(self, s, args):
2662 # Expands preprocessor macros in all of 's'. Used whenever we don't
2663 # have to worry about delimiters. See _expand_macro() re. the 'args'
2666 # Returns the expanded string.
2673 s, i = self._expand_macro(s, i, args)
2676 def _expand_name(self, s, i):
2677 # Expands a symbol name starting at index 'i' in 's'.
2679 # Returns the expanded name, the expanded 's' (including the part
2680 # before the name), and the index of the first character in the next
2681 # token after the name.
2683 s, end_i = self._expand_name_iter(s, i)
2685 # isspace() is False for empty strings
2686 if not name.strip():
2687 # Avoid creating a Kconfig symbol with a blank name. It's almost
2688 # guaranteed to be an error.
2689 self._parse_error("macro expanded to blank string")
2691 # Skip trailing whitespace
2692 while end_i < len(s) and s[end_i].isspace():
2695 return name, s, end_i
2697 def _expand_name_iter(self, s, i):
2698 # Expands a symbol name starting at index 'i' in 's'.
2700 # Returns the expanded 's' (including the part before the name) and the
2701 # index of the first character after the expanded name in 's'.
2704 match = _name_special_search(s, i)
2706 if match.group() != "$(":
2707 return (s, match.start())
2708 s, i = self._expand_macro(s, match.start(), ())
2710 def _expand_str(self, s, i):
2711 # Expands a quoted string starting at index 'i' in 's'. Handles both
2712 # backslash escapes and macro expansion.
2714 # Returns the expanded 's' (including the part before the string) and
2715 # the index of the first character after the expanded string in 's'.
2718 i += 1 # Skip over initial "/'
2720 match = _string_special_search(s, i)
2722 self._parse_error("unterminated string")
2725 if match.group() == quote:
2726 # Found the end of the string
2727 return (s, match.end())
2729 elif match.group() == "\\":
2730 # Replace '\x' with 'x'. 'i' ends up pointing to the character
2731 # after 'x', which allows macros to be canceled with '\$(foo)'.
2733 s = s[:match.start()] + s[i:]
2735 elif match.group() == "$(":
2736 # A macro call within the string
2737 s, i = self._expand_macro(s, match.start(), ())
2740 # A ' quote within " quotes or vice versa
2743 def _expand_macro(self, s, i, args):
2744 # Expands a macro starting at index 'i' in 's'. If this macro resulted
2745 # from the expansion of another macro, 'args' holds the arguments
2746 # passed to that macro.
2748 # Returns the expanded 's' (including the part before the macro) and
2749 # the index of the first character after the expanded macro in 's'.
2752 i += 2 # Skip over "$("
2754 arg_start = i # Start of current macro argument
2755 new_args = [] # Arguments of this macro call
2756 nesting = 0 # Current parentheses nesting level
2759 match = _macro_special_search(s, i)
2761 self._parse_error("missing end parenthesis in macro expansion")
2764 if match.group() == "(":
2768 elif match.group() == ")":
2774 # Found the end of the macro
2776 new_args.append(s[arg_start:match.start()])
2778 # $(1) is replaced by the first argument to the function, etc.,
2779 # provided at least that many arguments were passed
2782 # Does the macro look like an integer, with a corresponding
2783 # argument? If so, expand it to the value of the argument.
2784 res += args[int(new_args[0])]
2785 except (ValueError, IndexError):
2786 # Regular variables are just functions without arguments,
2787 # and also go through the function value path
2788 res += self._fn_val(new_args)
2790 return (res + s[match.end():], len(res))
2792 elif match.group() == ",":
2797 # Found the end of a macro argument
2798 new_args.append(s[arg_start:match.start()])
2801 else: # match.group() == "$("
2802 # A nested macro call within the macro
2803 s, i = self._expand_macro(s, match.start(), args)
2805 def _fn_val(self, args):
2806 # Returns the result of calling the function args[0] with the arguments
2807 # args[1..len(args)-1]. Plain variables are treated as functions
2808 # without arguments.
2812 if fn in self.variables:
2813 var = self.variables[fn]
2817 if var._n_expansions:
2818 self._parse_error("Preprocessor variable {} recursively "
2819 "references itself".format(var.name))
2820 elif var._n_expansions > 100:
2821 # Allow functions to call themselves, but guess that functions
2822 # that are overly recursive are stuck
2823 self._parse_error("Preprocessor function {} seems stuck "
2824 "in infinite recursion".format(var.name))
2826 var._n_expansions += 1
2827 res = self._expand_whole(self.variables[fn].value, args)
2828 var._n_expansions -= 1
2831 if fn in self._functions:
2832 # Built-in or user-defined function
2834 py_fn, min_arg, max_arg = self._functions[fn]
2836 if len(args) - 1 < min_arg or \
2837 (max_arg is not None and len(args) - 1 > max_arg):
2839 if min_arg == max_arg:
2840 expected_args = min_arg
2841 elif max_arg is None:
2842 expected_args = "{} or more".format(min_arg)
2844 expected_args = "{}-{}".format(min_arg, max_arg)
2846 raise KconfigError("{}:{}: bad number of arguments in call "
2847 "to {}, expected {}, got {}"
2848 .format(self.filename, self.linenr, fn,
2849 expected_args, len(args) - 1))
2851 return py_fn(self, *args)
2853 # Environment variables are tried last
2854 if fn in os.environ:
2855 self.env_vars.add(fn)
2856 return os.environ[fn]
2864 def _make_and(self, e1, e2):
2865 # Constructs an AND (&&) expression. Performs trivial simplification.
2873 if e1 is self.n or e2 is self.n:
2876 return (AND, e1, e2)
2878 def _make_or(self, e1, e2):
2879 # Constructs an OR (||) expression. Performs trivial simplification.
2887 if e1 is self.y or e2 is self.y:
2892 def _parse_block(self, end_token, parent, prev):
2893 # Parses a block, which is the contents of either a file or an if,
2894 # menu, or choice statement.
2897 # The token that ends the block, e.g. _T_ENDIF ("endif") for ifs.
2901 # The parent menu node, corresponding to a menu, Choice, or 'if'.
2902 # 'if's are flattened after parsing.
2905 # The previous menu node. New nodes will be added after this one (by
2906 # modifying 'next' pointers).
2908 # 'prev' is reused to parse a list of child menu nodes (for a menu or
2909 # Choice): After parsing the children, the 'next' pointer is assigned
2910 # to the 'list' pointer to "tilt up" the children above the node.
2912 # Returns the final menu node in the block (or 'prev' if the block is
2913 # empty). This allows chaining.
2915 while self._next_line():
2916 t0 = self._tokens[0]
2918 if t0 is _T_CONFIG or t0 is _T_MENUCONFIG:
2919 # The tokenizer allocates Symbol objects for us
2920 sym = self._tokens[1]
2922 if sym.__class__ is not Symbol or sym.is_constant:
2923 self._parse_error("missing or bad symbol name")
2925 if self._tokens[2] is not None:
2926 self._trailing_tokens_error()
2928 self.defined_syms.append(sym)
2933 node.is_menuconfig = (t0 is _T_MENUCONFIG)
2934 node.prompt = node.help = node.list = None
2935 node.parent = parent
2936 node.filename = self.filename
2937 node.linenr = self.linenr
2938 node.include_path = self._include_path
2940 sym.nodes.append(node)
2942 self._parse_props(node)
2944 if node.is_menuconfig and not node.prompt:
2945 self._warn("the menuconfig symbol {} has no prompt"
2946 .format(sym.name_and_loc))
2953 # due to tricky Python semantics. The order matters.
2954 prev.next = prev = node
2960 elif t0 in _SOURCE_TOKENS:
2961 pattern = self._expect_str_and_eol()
2963 if t0 in _REL_SOURCE_TOKENS:
2965 pattern = join(dirname(self.filename), pattern)
2967 # - glob() doesn't support globbing relative to a directory, so
2968 # we need to prepend $srctree to 'pattern'. Use join()
2969 # instead of '+' so that an absolute path in 'pattern' is
2972 # - Sort the glob results to ensure a consistent ordering of
2973 # Kconfig symbols, which indirectly ensures a consistent
2974 # ordering in e.g. .config files
2975 filenames = sorted(iglob(join(self._srctree_prefix, pattern)))
2977 if not filenames and t0 in _OBL_SOURCE_TOKENS:
2979 "{}:{}: '{}' not found (in '{}'). Check that "
2980 "environment variables are set correctly (e.g. "
2981 "$srctree, which is {}). Also note that unset "
2982 "environment variables expand to the empty string."
2983 .format(self.filename, self.linenr, pattern,
2985 "set to '{}'".format(self.srctree)
2986 if self.srctree else "unset or blank"))
2988 for filename in filenames:
2989 self._enter_file(filename)
2990 prev = self._parse_block(None, parent, prev)
2993 elif t0 is end_token:
2994 # Reached the end of the block. Terminate the final node and
2997 if self._tokens[1] is not None:
2998 self._trailing_tokens_error()
3005 node.item = node.prompt = None
3006 node.parent = parent
3007 node.dep = self._expect_expr_and_eol()
3009 self._parse_block(_T_ENDIF, node, node)
3010 node.list = node.next
3012 prev.next = prev = node
3017 node.item = t0 # _T_MENU == MENU
3018 node.is_menuconfig = True
3019 node.prompt = (self._expect_str_and_eol(), self.y)
3020 node.visibility = self.y
3021 node.parent = parent
3022 node.filename = self.filename
3023 node.linenr = self.linenr
3024 node.include_path = self._include_path
3026 self.menus.append(node)
3028 self._parse_props(node)
3029 self._parse_block(_T_ENDMENU, node, node)
3030 node.list = node.next
3032 prev.next = prev = node
3034 elif t0 is _T_COMMENT:
3037 node.item = t0 # _T_COMMENT == COMMENT
3038 node.is_menuconfig = False
3039 node.prompt = (self._expect_str_and_eol(), self.y)
3041 node.parent = parent
3042 node.filename = self.filename
3043 node.linenr = self.linenr
3044 node.include_path = self._include_path
3046 self.comments.append(node)
3048 self._parse_props(node)
3050 prev.next = prev = node
3052 elif t0 is _T_CHOICE:
3053 if self._tokens[1] is None:
3055 choice.direct_dep = self.n
3058 name = self._expect_str_and_eol()
3059 choice = self.named_choices.get(name)
3063 choice.direct_dep = self.n
3064 self.named_choices[name] = choice
3066 self.choices.append(choice)
3069 node.kconfig = choice.kconfig = self
3071 node.is_menuconfig = True
3072 node.prompt = node.help = None
3073 node.parent = parent
3074 node.filename = self.filename
3075 node.linenr = self.linenr
3076 node.include_path = self._include_path
3078 choice.nodes.append(node)
3080 self._parse_props(node)
3081 self._parse_block(_T_ENDCHOICE, node, node)
3082 node.list = node.next
3084 prev.next = prev = node
3086 elif t0 is _T_MAINMENU:
3087 self.top_node.prompt = (self._expect_str_and_eol(), self.y)
3090 # A valid endchoice/endif/endmenu is caught by the 'end_token'
3093 "no corresponding 'choice'" if t0 is _T_ENDCHOICE else
3094 "no corresponding 'if'" if t0 is _T_ENDIF else
3095 "no corresponding 'menu'" if t0 is _T_ENDMENU else
3096 "unrecognized construct")
3098 # End of file reached. Return the last node.
3102 "error: expected '{}' at end of '{}'"
3103 .format("endchoice" if end_token is _T_ENDCHOICE else
3104 "endif" if end_token is _T_ENDIF else
3110 def _parse_cond(self):
3111 # Parses an optional 'if <expr>' construct and returns the parsed
3112 # <expr>, or self.y if the next token is not _T_IF
3114 expr = self._parse_expr(True) if self._check_token(_T_IF) else self.y
3116 if self._tokens[self._tokens_i] is not None:
3117 self._trailing_tokens_error()
3121 def _parse_props(self, node):
3122 # Parses and adds properties to the MenuNode 'node' (type, 'prompt',
3123 # 'default's, etc.) Properties are later copied up to symbols and
3124 # choices in a separate pass after parsing, in e.g.
3125 # _add_props_to_sym().
3127 # An older version of this code added properties directly to symbols
3128 # and choices instead of to their menu nodes (and handled dependency
3129 # propagation simultaneously), but that loses information on where a
3130 # property is added when a symbol or choice is defined in multiple
3131 # locations. Some Kconfig configuration systems rely heavily on such
3132 # symbols, and better docs can be generated by keeping track of where
3133 # properties are added.
3136 # The menu node we're parsing properties on
3138 # Dependencies from 'depends on'. Will get propagated to the properties
3142 while self._next_line():
3143 t0 = self._tokens[0]
3145 if t0 in _TYPE_TOKENS:
3146 # Relies on '_T_BOOL is BOOL', etc., to save a conversion
3147 self._set_type(node.item, t0)
3148 if self._tokens[1] is not None:
3149 self._parse_prompt(node)
3151 elif t0 is _T_DEPENDS:
3152 if not self._check_token(_T_ON):
3153 self._parse_error("expected 'on' after 'depends'")
3155 node.dep = self._make_and(node.dep,
3156 self._expect_expr_and_eol())
3159 self._parse_help(node)
3161 elif t0 is _T_SELECT:
3162 if node.item.__class__ is not Symbol:
3163 self._parse_error("only symbols can select")
3165 node.selects.append((self._expect_nonconst_sym(),
3166 self._parse_cond()))
3172 elif t0 is _T_DEFAULT:
3173 node.defaults.append((self._parse_expr(False),
3174 self._parse_cond()))
3176 elif t0 in _DEF_TOKEN_TO_TYPE:
3177 self._set_type(node.item, _DEF_TOKEN_TO_TYPE[t0])
3178 node.defaults.append((self._parse_expr(False),
3179 self._parse_cond()))
3181 elif t0 is _T_PROMPT:
3182 self._parse_prompt(node)
3184 elif t0 is _T_RANGE:
3185 node.ranges.append((self._expect_sym(), self._expect_sym(),
3186 self._parse_cond()))
3188 elif t0 is _T_IMPLY:
3189 if node.item.__class__ is not Symbol:
3190 self._parse_error("only symbols can imply")
3192 node.implies.append((self._expect_nonconst_sym(),
3193 self._parse_cond()))
3195 elif t0 is _T_VISIBLE:
3196 if not self._check_token(_T_IF):
3197 self._parse_error("expected 'if' after 'visible'")
3199 node.visibility = self._make_and(node.visibility,
3200 self._expect_expr_and_eol())
3202 elif t0 is _T_OPTION:
3203 if self._check_token(_T_ENV):
3204 if not self._check_token(_T_EQUAL):
3205 self._parse_error("expected '=' after 'env'")
3207 env_var = self._expect_str_and_eol()
3208 node.item.env_var = env_var
3210 if env_var in os.environ:
3211 node.defaults.append(
3212 (self._lookup_const_sym(os.environ[env_var]),
3215 self._warn("{1} has 'option env=\"{0}\"', "
3216 "but the environment variable {0} is not "
3217 "set".format(node.item.name, env_var),
3218 self.filename, self.linenr)
3220 if env_var != node.item.name:
3221 self._warn("Kconfiglib expands environment variables "
3222 "in strings directly, meaning you do not "
3223 "need 'option env=...' \"bounce\" symbols. "
3224 "For compatibility with the C tools, "
3225 "rename {} to {} (so that the symbol name "
3226 "matches the environment variable name)."
3227 .format(node.item.name, env_var),
3228 self.filename, self.linenr)
3230 elif self._check_token(_T_DEFCONFIG_LIST):
3231 if not self.defconfig_list:
3232 self.defconfig_list = node.item
3234 self._warn("'option defconfig_list' set on multiple "
3235 "symbols ({0} and {1}). Only {0} will be "
3236 "used.".format(self.defconfig_list.name,
3238 self.filename, self.linenr)
3240 elif self._check_token(_T_MODULES):
3241 # To reduce warning spam, only warn if 'option modules' is
3242 # set on some symbol that isn't MODULES, which should be
3243 # safe. I haven't run into any projects that make use
3244 # modules besides the kernel yet, and there it's likely to
3245 # keep being called "MODULES".
3246 if node.item is not self.modules:
3247 self._warn("the 'modules' option is not supported. "
3248 "Let me know if this is a problem for you, "
3249 "as it wouldn't be that hard to implement. "
3250 "Note that modules are supported -- "
3251 "Kconfiglib just assumes the symbol name "
3252 "MODULES, like older versions of the C "
3253 "implementation did when 'option modules' "
3255 self.filename, self.linenr)
3257 elif self._check_token(_T_ALLNOCONFIG_Y):
3258 if node.item.__class__ is not Symbol:
3259 self._parse_error("the 'allnoconfig_y' option is only "
3260 "valid for symbols")
3262 node.item.is_allnoconfig_y = True
3265 self._parse_error("unrecognized option")
3267 elif t0 is _T_OPTIONAL:
3268 if node.item.__class__ is not Choice:
3269 self._parse_error('"optional" is only valid for choices')
3271 node.item.is_optional = True
3274 # Reuse the tokens for the non-property line later
3275 self._reuse_tokens = True
3278 def _set_type(self, sc, new_type):
3279 # Sets the type of 'sc' (symbol or choice) to 'new_type'
3282 if sc.orig_type and sc.orig_type is not new_type:
3283 self._warn("{} defined with multiple types, {} will be used"
3284 .format(sc.name_and_loc, TYPE_TO_STR[new_type]))
3286 sc.orig_type = new_type
3288 def _parse_prompt(self, node):
3289 # 'prompt' properties override each other within a single definition of
3290 # a symbol, but additional prompts can be added by defining the symbol
3294 self._warn(node.item.name_and_loc +
3295 " defined with multiple prompts in single location")
3297 prompt = self._tokens[1]
3300 if prompt.__class__ is not str:
3301 self._parse_error("expected prompt string")
3303 if prompt != prompt.strip():
3304 self._warn(node.item.name_and_loc +
3305 " has leading or trailing whitespace in its prompt")
3307 # This avoid issues for e.g. reStructuredText documentation, where
3308 # '*prompt *' is invalid
3309 prompt = prompt.strip()
3311 node.prompt = (prompt, self._parse_cond())
3313 def _parse_help(self, node):
3314 if node.help is not None:
3315 self._warn(node.item.name_and_loc + " defined with more than "
3316 "one help text -- only the last one will be used")
3318 # Micro-optimization. This code is pretty hot.
3319 readline = self._readline
3321 # Find first non-blank (not all-space) line and get its
3328 self._empty_help(node, line)
3330 if not line.isspace():
3333 len_ = len # Micro-optimization
3335 # Use a separate 'expline' variable here and below to avoid stomping on
3336 # any tabs people might've put deliberately into the first line after
3338 expline = line.expandtabs()
3339 indent = len_(expline) - len_(expline.lstrip())
3341 self._empty_help(node, line)
3344 # The help text goes on till the first non-blank line with less indent
3345 # than the first line
3347 # Add the first line
3348 lines = [expline[indent:]]
3349 add_line = lines.append # Micro-optimization
3354 # No need to preserve the exact whitespace in these
3360 expline = line.expandtabs()
3361 if len_(expline) - len_(expline.lstrip()) < indent:
3363 add_line(expline[indent:])
3365 self.linenr += len_(lines)
3366 node.help = "".join(lines).rstrip()
3368 self._line_after_help(line)
3370 def _empty_help(self, node, line):
3371 self._warn(node.item.name_and_loc +
3372 " has 'help' but empty help text")
3375 self._line_after_help(line)
3377 def _parse_expr(self, transform_m):
3378 # Parses an expression from the tokens in Kconfig._tokens using a
3379 # simple top-down approach. See the module docstring for the expression
3383 # True if m should be rewritten to m && MODULES. See the
3384 # Kconfig.eval_string() documentation.
3388 # expr: and_expr ['||' expr]
3389 # and_expr: factor ['&&' and_expr]
3390 # factor: <symbol> ['='/'!='/'<'/... <symbol>]
3394 # It helps to think of the 'expr: and_expr' case as a single-operand OR
3395 # (no ||), and of the 'and_expr: factor' case as a single-operand AND
3396 # (no &&). Parsing code is always a bit tricky.
3398 # Mind dump: parse_factor() and two nested loops for OR and AND would
3399 # work as well. The straightforward implementation there gives a
3400 # (op, (op, (op, A, B), C), D) parse for A op B op C op D. Representing
3401 # expressions as (op, [list of operands]) instead goes nicely with that
3402 # version, but is wasteful for short expressions and complicates
3403 # expression evaluation and other code that works on expressions (more
3404 # complicated code likely offsets any performance gain from less
3405 # recursion too). If we also try to optimize the list representation by
3406 # merging lists when possible (e.g. when ANDing two AND expressions),
3407 # we end up allocating a ton of lists instead of reusing expressions,
3410 and_expr = self._parse_and_expr(transform_m)
3412 # Return 'and_expr' directly if we have a "single-operand" OR.
3413 # Otherwise, parse the expression on the right and make an OR node.
3414 # This turns A || B || C || D into (OR, A, (OR, B, (OR, C, D))).
3415 return and_expr if not self._check_token(_T_OR) else \
3416 (OR, and_expr, self._parse_expr(transform_m))
3418 def _parse_and_expr(self, transform_m):
3419 factor = self._parse_factor(transform_m)
3421 # Return 'factor' directly if we have a "single-operand" AND.
3422 # Otherwise, parse the right operand and make an AND node. This turns
3423 # A && B && C && D into (AND, A, (AND, B, (AND, C, D))).
3424 return factor if not self._check_token(_T_AND) else \
3425 (AND, factor, self._parse_and_expr(transform_m))
3427 def _parse_factor(self, transform_m):
3428 token = self._tokens[self._tokens_i]
3431 if token.__class__ is Symbol:
3432 # Plain symbol or relation
3434 if self._tokens[self._tokens_i] not in _RELATIONS:
3437 # For conditional expressions ('depends on <expr>',
3438 # '... if <expr>', etc.), m is rewritten to m && MODULES.
3439 if transform_m and token is self.m:
3440 return (AND, self.m, self.modules)
3446 # _T_EQUAL, _T_UNEQUAL, etc., deliberately have the same values as
3447 # EQUAL, UNEQUAL, etc., so we can just use the token directly
3449 return (self._tokens[self._tokens_i - 1], token,
3453 # token == _T_NOT == NOT
3454 return (token, self._parse_factor(transform_m))
3456 if token is _T_OPEN_PAREN:
3457 expr_parse = self._parse_expr(transform_m)
3458 if self._check_token(_T_CLOSE_PAREN):
3461 self._parse_error("malformed expression")
3464 # Caching and invalidation
3467 def _build_dep(self):
3468 # Populates the Symbol/Choice._dependents sets, which contain all other
3469 # items (symbols and choices) that immediately depend on the item in
3470 # the sense that changing the value of the item might affect the value
3471 # of the dependent items. This is used for caching/invalidation.
3473 # The calculated sets might be larger than necessary as we don't do any
3474 # complex analysis of the expressions.
3476 depend_on = _depend_on # Micro-optimization
3478 # Only calculate _dependents for defined symbols. Constant and
3479 # undefined symbols could theoretically be selected/implied, but it
3480 # wouldn't change their value, so it's not a true dependency.
3481 for sym in self.unique_defined_syms:
3482 # Symbols depend on the following:
3484 # The prompt conditions
3485 for node in sym.nodes:
3487 depend_on(sym, node.prompt[1])
3489 # The default values and their conditions
3490 for value, cond in sym.defaults:
3491 depend_on(sym, value)
3492 depend_on(sym, cond)
3494 # The reverse and weak reverse dependencies
3495 depend_on(sym, sym.rev_dep)
3496 depend_on(sym, sym.weak_rev_dep)
3498 # The ranges along with their conditions
3499 for low, high, cond in sym.ranges:
3501 depend_on(sym, high)
3502 depend_on(sym, cond)
3504 # The direct dependencies. This is usually redundant, as the direct
3505 # dependencies get propagated to properties, but it's needed to get
3506 # invalidation solid for 'imply', which only checks the direct
3507 # dependencies (even if there are no properties to propagate it
3509 depend_on(sym, sym.direct_dep)
3511 # In addition to the above, choice symbols depend on the choice
3512 # they're in, but that's handled automatically since the Choice is
3513 # propagated to the conditions of the properties before
3514 # _build_dep() runs.
3516 for choice in self.unique_choices:
3517 # Choices depend on the following:
3519 # The prompt conditions
3520 for node in choice.nodes:
3522 depend_on(choice, node.prompt[1])
3524 # The default symbol conditions
3525 for _, cond in choice.defaults:
3526 depend_on(choice, cond)
3528 def _add_choice_deps(self):
3529 # Choices also depend on the choice symbols themselves, because the
3530 # y-mode selection of the choice might change if a choice symbol's
3531 # visibility changes.
3533 # We add these dependencies separately after dependency loop detection.
3534 # The invalidation algorithm can handle the resulting
3535 # <choice symbol> <-> <choice> dependency loops, but they make loop
3536 # detection awkward.
3538 for choice in self.unique_choices:
3539 for sym in choice.syms:
3540 sym._dependents.add(choice)
3542 def _invalidate_all(self):
3543 # Undefined symbols never change value and don't need to be
3544 # invalidated, so we can just iterate over defined symbols.
3545 # Invalidating constant symbols would break things horribly.
3546 for sym in self.unique_defined_syms:
3549 for choice in self.unique_choices:
3550 choice._invalidate()
3553 # Post-parsing menu tree processing, including dependency propagation and
3554 # implicit submenu creation
3557 def _finalize_node(self, node, visible_if):
3558 # Finalizes a menu node and its children:
3560 # - Copies properties from menu nodes up to their contained
3563 # - Propagates dependencies from parent to child nodes
3565 # - Creates implicit menus (see kconfig-language.txt)
3567 # - Removes 'if' nodes
3569 # - Sets 'choice' types and registers choice symbols
3571 # menu_finalize() in the C implementation is similar.
3574 # The menu node to finalize. This node and its children will have
3575 # been finalized when the function returns, and any implicit menus
3576 # will have been created.
3579 # Dependencies from 'visible if' on parent menus. These are added to
3580 # the prompts of symbols and choices.
3582 if node.item.__class__ is Symbol:
3583 # Copy defaults, ranges, selects, and implies to the Symbol
3584 self._add_props_to_sym(node)
3586 # Find any items that should go in an implicit menu rooted at the
3589 while cur.next and _auto_menu_dep(node, cur.next):
3590 # This makes implicit submenu creation work recursively, with
3591 # implicit menus inside implicit menus
3592 self._finalize_node(cur.next, visible_if)
3597 # Found symbols that should go in an implicit submenu. Tilt
3599 node.list = node.next
3600 node.next = cur.next
3604 # The menu node is a choice, menu, or if. Finalize each child node.
3606 if node.item is MENU:
3607 visible_if = self._make_and(visible_if, node.visibility)
3609 # Propagate the menu node's dependencies to each child menu node.
3611 # This needs to go before the recursive _finalize_node() call so
3612 # that implicit submenu creation can look ahead at dependencies.
3613 self._propagate_deps(node, visible_if)
3615 # Finalize the children
3618 self._finalize_node(cur, visible_if)
3622 # node's children have been individually finalized. Do final steps
3623 # to finalize this "level" in the menu tree.
3627 # Empty choices (node.list None) are possible, so this needs to go
3629 if node.item.__class__ is Choice:
3630 # Add the node's non-node-specific properties to the choice, like
3631 # _add_props_to_sym() does
3633 choice.direct_dep = self._make_or(choice.direct_dep, node.dep)
3634 choice.defaults += node.defaults
3636 _finalize_choice(node)
3638 def _propagate_deps(self, node, visible_if):
3639 # Propagates 'node's dependencies to its child menu nodes
3641 # If the parent node holds a Choice, we use the Choice itself as the
3642 # parent dependency. This makes sense as the value (mode) of the choice
3643 # limits the visibility of the contained choice symbols. The C
3644 # implementation works the same way.
3646 # Due to the similar interface, Choice works as a drop-in replacement
3648 basedep = node.item if node.item.__class__ is Choice else node.dep
3652 dep = cur.dep = self._make_and(cur.dep, basedep)
3654 if cur.item.__class__ in _SYMBOL_CHOICE:
3655 # Propagate 'visible if' and dependencies to the prompt
3657 cur.prompt = (cur.prompt[0],
3660 self._make_and(visible_if, dep)))
3662 # Propagate dependencies to defaults
3664 cur.defaults = [(default, self._make_and(cond, dep))
3665 for default, cond in cur.defaults]
3667 # Propagate dependencies to ranges
3669 cur.ranges = [(low, high, self._make_and(cond, dep))
3670 for low, high, cond in cur.ranges]
3672 # Propagate dependencies to selects
3674 cur.selects = [(target, self._make_and(cond, dep))
3675 for target, cond in cur.selects]
3677 # Propagate dependencies to implies
3679 cur.implies = [(target, self._make_and(cond, dep))
3680 for target, cond in cur.implies]
3682 elif cur.prompt: # Not a symbol/choice
3683 # Propagate dependencies to the prompt. 'visible if' is only
3684 # propagated to symbols/choices.
3685 cur.prompt = (cur.prompt[0],
3686 self._make_and(cur.prompt[1], dep))
3690 def _add_props_to_sym(self, node):
3691 # Copies properties from the menu node 'node' up to its contained
3692 # symbol, and adds (weak) reverse dependencies to selected/implied
3695 # This can't be rolled into _propagate_deps(), because that function
3696 # traverses the menu tree roughly breadth-first, meaning properties on
3697 # symbols defined in multiple locations could end up in the wrong
3702 # See the Symbol class docstring
3703 sym.direct_dep = self._make_or(sym.direct_dep, node.dep)
3705 sym.defaults += node.defaults
3706 sym.ranges += node.ranges
3707 sym.selects += node.selects
3708 sym.implies += node.implies
3710 # Modify the reverse dependencies of the selected symbol
3711 for target, cond in node.selects:
3712 target.rev_dep = self._make_or(
3714 self._make_and(sym, cond))
3716 # Modify the weak reverse dependencies of the implied
3718 for target, cond in node.implies:
3719 target.weak_rev_dep = self._make_or(
3720 target.weak_rev_dep,
3721 self._make_and(sym, cond))
3727 def _check_sym_sanity(self):
3728 # Checks various symbol properties that are handiest to check after
3729 # parsing. Only generates errors and warnings.
3731 def num_ok(sym, type_):
3732 # Returns True if the (possibly constant) symbol 'sym' is valid as a value
3733 # for a symbol of type type_ (INT or HEX)
3735 # 'not sym.nodes' implies a constant or undefined symbol, e.g. a plain
3738 return _is_base_n(sym.name, _TYPE_TO_BASE[type_])
3740 return sym.orig_type is type_
3742 for sym in self.unique_defined_syms:
3743 if sym.orig_type in _BOOL_TRISTATE:
3744 # A helper function could be factored out here, but keep it
3745 # speedy/straightforward
3747 for target_sym, _ in sym.selects:
3748 if target_sym.orig_type not in _BOOL_TRISTATE_UNKNOWN:
3749 self._warn("{} selects the {} symbol {}, which is not "
3751 .format(sym.name_and_loc,
3752 TYPE_TO_STR[target_sym.orig_type],
3753 target_sym.name_and_loc))
3755 for target_sym, _ in sym.implies:
3756 if target_sym.orig_type not in _BOOL_TRISTATE_UNKNOWN:
3757 self._warn("{} implies the {} symbol {}, which is not "
3759 .format(sym.name_and_loc,
3760 TYPE_TO_STR[target_sym.orig_type],
3761 target_sym.name_and_loc))
3763 elif sym.orig_type: # STRING/INT/HEX
3764 for default, _ in sym.defaults:
3765 if default.__class__ is not Symbol:
3767 "the {} symbol {} has a malformed default {} -- "
3768 "expected a single symbol"
3769 .format(TYPE_TO_STR[sym.orig_type],
3770 sym.name_and_loc, expr_str(default)))
3772 if sym.orig_type is STRING:
3773 if not default.is_constant and not default.nodes and \
3774 not default.name.isupper():
3775 # 'default foo' on a string symbol could be either a symbol
3776 # reference or someone leaving out the quotes. Guess that
3777 # the quotes were left out if 'foo' isn't all-uppercase
3778 # (and no symbol named 'foo' exists).
3779 self._warn("style: quotes recommended around "
3780 "default value for string symbol "
3783 elif not num_ok(default, sym.orig_type): # INT/HEX
3784 self._warn("the {0} symbol {1} has a non-{0} default {2}"
3785 .format(TYPE_TO_STR[sym.orig_type],
3787 default.name_and_loc))
3789 if sym.selects or sym.implies:
3790 self._warn("the {} symbol {} has selects or implies"
3791 .format(TYPE_TO_STR[sym.orig_type],
3795 self._warn("{} defined without a type"
3796 .format(sym.name_and_loc))
3800 if sym.orig_type not in _INT_HEX:
3802 "the {} symbol {} has ranges, but is not int or hex"
3803 .format(TYPE_TO_STR[sym.orig_type],
3806 for low, high, _ in sym.ranges:
3807 if not num_ok(low, sym.orig_type) or \
3808 not num_ok(high, sym.orig_type):
3810 self._warn("the {0} symbol {1} has a non-{0} "
3812 .format(TYPE_TO_STR[sym.orig_type],
3817 def _check_choice_sanity(self):
3818 # Checks various choice properties that are handiest to check after
3819 # parsing. Only generates errors and warnings.
3821 def warn_select_imply(sym, expr, expr_type):
3822 msg = "the choice symbol {} is {} by the following symbols, but " \
3823 "select/imply has no effect on choice symbols" \
3824 .format(sym.name_and_loc, expr_type)
3827 for si in split_expr(expr, OR):
3828 msg += "\n - " + split_expr(si, AND)[0].name_and_loc
3832 for choice in self.unique_choices:
3833 if choice.orig_type not in _BOOL_TRISTATE:
3834 self._warn("{} defined with type {}"
3835 .format(choice.name_and_loc,
3836 TYPE_TO_STR[choice.orig_type]))
3838 for node in choice.nodes:
3842 self._warn(choice.name_and_loc + " defined without a prompt")
3844 for default, _ in choice.defaults:
3845 if default.__class__ is not Symbol:
3847 "{} has a malformed default {}"
3848 .format(choice.name_and_loc, expr_str(default)))
3850 if default.choice is not choice:
3851 self._warn("the default selection {} of {} is not "
3852 "contained in the choice"
3853 .format(default.name_and_loc,
3854 choice.name_and_loc))
3856 for sym in choice.syms:
3858 self._warn("default on the choice symbol {} will have "
3859 "no effect, as defaults do not affect choice "
3860 "symbols".format(sym.name_and_loc))
3862 if sym.rev_dep is not sym.kconfig.n:
3863 warn_select_imply(sym, sym.rev_dep, "selected")
3865 if sym.weak_rev_dep is not sym.kconfig.n:
3866 warn_select_imply(sym, sym.weak_rev_dep, "implied")
3868 for node in sym.nodes:
3869 if node.parent.item is choice:
3871 self._warn("the choice symbol {} has no prompt"
3872 .format(sym.name_and_loc))
3875 self._warn("the choice symbol {} is defined with a "
3876 "prompt outside the choice"
3877 .format(sym.name_and_loc))
3879 def _parse_error(self, msg):
3880 raise KconfigError("{}error: couldn't parse '{}': {}".format(
3881 "" if self.filename is None else
3882 "{}:{}: ".format(self.filename, self.linenr),
3883 self._line.strip(), msg))
3885 def _trailing_tokens_error(self):
3886 self._parse_error("extra tokens at end of line")
3888 def _open(self, filename, mode):
3891 # - Enable universal newlines mode on Python 2 to ease
3892 # interoperability between Linux and Windows. It's already the
3893 # default on Python 3.
3895 # The "U" flag would currently work for both Python 2 and 3, but it's
3896 # deprecated on Python 3, so play it future-safe.
3898 # io.open() defaults to universal newlines on Python 2 (and is an
3899 # alias for open() on Python 3), but it returns 'unicode' strings and
3900 # slows things down:
3902 # Parsing x86 Kconfigs on Python 2
3904 # with open(..., "rU"):
3916 # There's no appreciable performance difference between "r" and
3917 # "rU" for parsing performance on Python 2.
3919 # - For Python 3, force the encoding. Forcing the encoding on Python 2
3920 # turns strings into Unicode strings, which gets messy. Python 2
3921 # doesn't decode regular strings anyway.
3922 return open(filename, "rU" if mode == "r" else mode) if _IS_PY2 else \
3923 open(filename, mode, encoding=self._encoding)
3925 def _check_undef_syms(self):
3926 # Prints warnings for all references to undefined symbols within the
3930 # Returns True if the string 's' looks like a number.
3932 # Internally, all operands in Kconfig are symbols, only undefined symbols
3933 # (which numbers usually are) get their name as their value.
3935 # Only hex numbers that start with 0x/0X are classified as numbers.
3936 # Otherwise, symbols whose names happen to contain only the letters A-F
3937 # would trigger false positives.
3942 if not s.startswith(("0x", "0X")):
3952 for sym in (self.syms.viewvalues if _IS_PY2 else self.syms.values)():
3953 # - sym.nodes empty means the symbol is undefined (has no
3954 # definition locations)
3956 # - Due to Kconfig internals, numbers show up as undefined Kconfig
3957 # symbols, but shouldn't be flagged
3959 # - The MODULES symbol always exists
3960 if not sym.nodes and not is_num(sym.name) and \
3961 sym.name != "MODULES":
3963 msg = "undefined symbol {}:".format(sym.name)
3964 for node in self.node_iter():
3965 if sym in node.referenced:
3966 msg += "\n\n- Referenced at {}:{}:\n\n{}" \
3967 .format(node.filename, node.linenr, node)
3970 def _warn(self, msg, filename=None, linenr=None):
3971 # For printing general warnings
3976 msg = "warning: " + msg
3977 if filename is not None:
3978 msg = "{}:{}: {}".format(filename, linenr, msg)
3980 self.warnings.append(msg)
3981 if self.warn_to_stderr:
3982 sys.stderr.write(msg + "\n")
3985 class Symbol(object):
3987 Represents a configuration symbol:
3992 The following attributes are available. They should be viewed as read-only,
3993 and some are implemented through @property magic (but are still efficient
3994 to access due to internal caching).
3996 Note: Prompts, help texts, and locations are stored in the Symbol's
3997 MenuNode(s) rather than in the Symbol itself. Check the MenuNode class and
3998 the Symbol.nodes attribute. This organization matches the C tools.
4001 The name of the symbol, e.g. "FOO" for 'config FOO'.
4004 The type of the symbol. One of BOOL, TRISTATE, STRING, INT, HEX, UNKNOWN.
4005 UNKNOWN is for undefined symbols, (non-special) constant symbols, and
4006 symbols defined without a type.
4008 When running without modules (MODULES having the value n), TRISTATE
4009 symbols magically change type to BOOL. This also happens for symbols
4010 within choices in "y" mode. This matches the C tools, and makes sense for
4011 menuconfig-like functionality.
4014 The type as given in the Kconfig file, without any magic applied. Used
4015 when printing the symbol.
4018 The tristate value of the symbol as an integer. One of 0, 1, 2,
4019 representing n, m, y. Always 0 (n) for non-bool/tristate symbols.
4021 This is the symbol value that's used outside of relation expressions
4022 (A, !A, A && B, A || B).
4025 The value of the symbol as a string. Gives the value for string/int/hex
4026 symbols. For bool/tristate symbols, gives "n", "m", or "y".
4028 This is the symbol value that's used in relational expressions
4029 (A = B, A != B, etc.)
4031 Gotcha: For int/hex symbols, the exact format of the value is often
4032 preserved (e.g. when writing a .config file), hence why you can't get it
4033 directly as an int. Do int(int_sym.str_value) or
4034 int(hex_sym.str_value, 16) to get the integer value.
4037 The user value of the symbol. None if no user value has been assigned
4038 (via Kconfig.load_config() or Symbol.set_value()).
4040 Holds 0, 1, or 2 for bool/tristate symbols, and a string for the other
4043 WARNING: Do not assign directly to this. It will break things. Use
4047 A tuple containing the tristate user values that can currently be
4048 assigned to the symbol (that would be respected), ordered from lowest (0,
4049 representing n) to highest (2, representing y). This corresponds to the
4050 selections available in the menuconfig interface. The set of assignable
4051 values is calculated from the symbol's visibility and selects/implies.
4053 Returns the empty set for non-bool/tristate symbols and for symbols with
4054 visibility n. The other possible values are (0, 2), (0, 1, 2), (1, 2),
4055 (1,), and (2,). A (1,) or (2,) result means the symbol is visible but
4056 "locked" to m or y through a select, perhaps in combination with the
4057 visibility. menuconfig represents this as -M- and -*-, respectively.
4059 For string/hex/int symbols, check if Symbol.visibility is non-0 (non-n)
4060 instead to determine if the value can be changed.
4062 Some handy 'assignable' idioms:
4064 # Is 'sym' an assignable (visible) bool/tristate symbol?
4066 # What's the highest value it can be assigned? [-1] in Python
4067 # gives the last element.
4068 sym_high = sym.assignable[-1]
4071 sym_low = sym.assignable[0]
4073 # Can the symbol be set to at least m?
4074 if sym.assignable[-1] >= 1:
4077 # Can the symbol be set to m?
4078 if 1 in sym.assignable:
4082 The visibility of the symbol. One of 0, 1, 2, representing n, m, y. See
4083 the module documentation for an overview of symbol values and visibility.
4086 The .config assignment string that would get written out for the symbol
4087 by Kconfig.write_config(). Returns the empty string if no .config
4088 assignment would get written out.
4090 In general, visible symbols, symbols with (active) defaults, and selected
4091 symbols get written out. This includes all non-n-valued bool/tristate
4092 symbols, and all visible string/int/hex symbols.
4094 Symbols with the (no longer needed) 'option env=...' option generate no
4095 configuration output, and neither does the special
4096 'option defconfig_list' symbol.
4098 Tip: This field is useful when generating custom configuration output,
4099 even for non-.config-like formats. To write just the symbols that would
4100 get written out to .config files, do this:
4102 if sym.config_string:
4103 *Write symbol, e.g. by looking sym.str_value*
4105 This is a superset of the symbols written out by write_autoconf().
4106 That function skips all n-valued symbols.
4108 There usually won't be any great harm in just writing all symbols either,
4109 though you might get some special symbols and possibly some "redundant"
4110 n-valued symbol entries in there.
4115 "MY_SYMBOL (defined at foo/Kconfig:12, bar/Kconfig:14)"
4117 , giving the name of the symbol and its definition location(s).
4119 If the symbol is undefined, the location is given as "(undefined)".
4122 A list of MenuNodes for this symbol. Will contain a single MenuNode for
4123 most symbols. Undefined and constant symbols have an empty nodes list.
4124 Symbols defined in multiple locations get one node for each location.
4127 Holds the parent Choice for choice symbols, and None for non-choice
4128 symbols. Doubles as a flag for whether a symbol is a choice symbol.
4131 List of (default, cond) tuples for the symbol's 'default' properties. For
4132 example, 'default A && B if C || D' is represented as
4133 ((AND, A, B), (OR, C, D)). If no condition was given, 'cond' is
4136 Note that 'depends on' and parent dependencies are propagated to
4137 'default' conditions.
4140 List of (symbol, cond) tuples for the symbol's 'select' properties. For
4141 example, 'select A if B && C' is represented as (A, (AND, B, C)). If no
4142 condition was given, 'cond' is self.kconfig.y.
4144 Note that 'depends on' and parent dependencies are propagated to 'select'
4148 Like 'selects', for imply.
4151 List of (low, high, cond) tuples for the symbol's 'range' properties. For
4152 example, 'range 1 2 if A' is represented as (1, 2, A). If there is no
4153 condition, 'cond' is self.kconfig.y.
4155 Note that 'depends on' and parent dependencies are propagated to 'range'
4158 Gotcha: 1 and 2 above will be represented as (undefined) Symbols rather
4159 than plain integers. Undefined symbols get their name as their string
4160 value, so this works out. The C tools work the same way.
4166 See the corresponding attributes on the MenuNode class.
4169 Reverse dependency expression from other symbols selecting this symbol.
4170 Multiple selections get ORed together. A condition on a select is ANDed
4171 with the selecting symbol.
4173 For example, if A has 'select FOO' and B has 'select FOO if C', then
4174 FOO's rev_dep will be (OR, A, (AND, B, C)).
4177 Like rev_dep, for imply.
4180 The direct ('depends on') dependencies for the symbol, or self.kconfig.y
4181 if there are no direct dependencies.
4183 This attribute includes any dependencies from surrounding menus and ifs.
4184 Those get propagated to the direct dependencies, and the resulting direct
4185 dependencies in turn get propagated to the conditions of all properties.
4187 If the symbol is defined in multiple locations, the dependencies from the
4188 different locations get ORed together.
4191 A set() with all symbols and choices referenced in the properties and
4192 property conditions of the symbol.
4194 Also includes dependencies from surrounding menus and ifs, because those
4195 get propagated to the symbol (see the 'Intro to symbol values' section in
4196 the module docstring).
4198 Choices appear in the dependencies of choice symbols.
4200 For the following definitions, only B and not C appears in A's
4201 'referenced'. To get transitive references, you'll have to recursively
4202 expand 'references' until no new items appear.
4215 See the Symbol.direct_dep attribute if you're only interested in the
4216 direct dependencies of the symbol (its 'depends on'). You can extract the
4217 symbols in it with the global expr_items() function.
4220 If the Symbol has an 'option env="FOO"' option, this contains the name
4221 ("FOO") of the environment variable. None for symbols without no
4224 'option env="FOO"' acts like a 'default' property whose value is the
4227 Symbols with 'option env' are never written out to .config files, even if
4228 they are visible. env_var corresponds to a flag called SYMBOL_AUTO in the
4232 True if the symbol has 'option allnoconfig_y' set on it. This has no
4233 effect internally (except when printing symbols), but can be checked by
4237 True if the symbol is a constant (quoted) symbol.
4240 The Kconfig instance this symbol is from.
4243 "_cached_assignable",
4277 See the class documentation.
4279 if self.orig_type is TRISTATE and \
4280 (self.choice and self.choice.tri_value == 2 or
4281 not self.kconfig.modules.tri_value):
4285 return self.orig_type
4288 def str_value(self):
4290 See the class documentation.
4292 if self._cached_str_val is not None:
4293 return self._cached_str_val
4295 if self.orig_type in _BOOL_TRISTATE:
4296 # Also calculates the visibility, so invalidation safe
4297 self._cached_str_val = TRI_TO_STR[self.tri_value]
4298 return self._cached_str_val
4300 # As a quirk of Kconfig, undefined symbols get their name as their
4301 # string value. This is why things like "FOO = bar" work for seeing if
4302 # FOO has the value "bar".
4303 if not self.orig_type: # UNKNOWN
4304 self._cached_str_val = self.name
4308 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
4309 # function call (property magic)
4310 vis = self.visibility
4312 self._write_to_conf = (vis != 0)
4314 if self.orig_type in _INT_HEX:
4315 # The C implementation checks the user value against the range in a
4316 # separate code path (post-processing after loading a .config).
4317 # Checking all values here instead makes more sense for us. It
4318 # requires that we check for a range first.
4320 base = _TYPE_TO_BASE[self.orig_type]
4322 # Check if a range is in effect
4323 for low_expr, high_expr, cond in self.ranges:
4324 if expr_value(cond):
4325 has_active_range = True
4327 # The zeros are from the C implementation running strtoll()
4329 low = int(low_expr.str_value, base) if \
4330 _is_base_n(low_expr.str_value, base) else 0
4331 high = int(high_expr.str_value, base) if \
4332 _is_base_n(high_expr.str_value, base) else 0
4336 has_active_range = False
4338 # Defaults are used if the symbol is invisible, lacks a user value,
4339 # or has an out-of-range user value
4342 if vis and self.user_value:
4343 user_val = int(self.user_value, base)
4344 if has_active_range and not low <= user_val <= high:
4345 num2str = str if base == 10 else hex
4347 "user value {} on the {} symbol {} ignored due to "
4348 "being outside the active range ([{}, {}]) -- falling "
4350 .format(num2str(user_val), TYPE_TO_STR[self.orig_type],
4352 num2str(low), num2str(high)))
4354 # If the user value is well-formed and satisfies range
4355 # contraints, it is stored in exactly the same form as
4356 # specified in the assignment (with or without "0x", etc.)
4357 val = self.user_value
4358 use_defaults = False
4361 # No user value or invalid user value. Look at defaults.
4363 # Used to implement the warning below
4366 for sym, cond in self.defaults:
4367 if expr_value(cond):
4368 has_default = self._write_to_conf = True
4372 if _is_base_n(val, base):
4373 val_num = int(val, base)
4375 val_num = 0 # strtoll() on empty string
4379 val_num = 0 # strtoll() on empty string
4381 # This clamping procedure runs even if there's no default
4382 if has_active_range:
4386 elif val_num > high:
4389 if clamp is not None:
4390 # The value is rewritten to a standard form if it is
4393 if self.orig_type is INT else \
4397 num2str = str if base == 10 else hex
4399 "default value {} on {} clamped to {} due to "
4400 "being outside the active range ([{}, {}])"
4401 .format(val_num, self.name_and_loc,
4402 num2str(clamp), num2str(low),
4405 elif self.orig_type is STRING:
4406 if vis and self.user_value is not None:
4407 # If the symbol is visible and has a user value, use that
4408 val = self.user_value
4410 # Otherwise, look at defaults
4411 for sym, cond in self.defaults:
4412 if expr_value(cond):
4414 self._write_to_conf = True
4417 # env_var corresponds to SYMBOL_AUTO in the C implementation, and is
4418 # also set on the defconfig_list symbol there. Test for the
4419 # defconfig_list symbol explicitly instead here, to avoid a nonsensical
4420 # env_var setting and the defconfig_list symbol being printed
4421 # incorrectly. This code is pretty cold anyway.
4422 if self.env_var is not None or self is self.kconfig.defconfig_list:
4423 self._write_to_conf = False
4425 self._cached_str_val = val
4429 def tri_value(self):
4431 See the class documentation.
4433 if self._cached_tri_val is not None:
4434 return self._cached_tri_val
4436 if self.orig_type not in _BOOL_TRISTATE:
4437 if self.orig_type: # != UNKNOWN
4438 # Would take some work to give the location here
4440 "The {} symbol {} is being evaluated in a logical context "
4441 "somewhere. It will always evaluate to n."
4442 .format(TYPE_TO_STR[self.orig_type], self.name_and_loc))
4444 self._cached_tri_val = 0
4447 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
4448 # function call (property magic)
4449 vis = self.visibility
4450 self._write_to_conf = (vis != 0)
4457 if vis and self.user_value is not None:
4458 # If the symbol is visible and has a user value, use that
4459 val = min(self.user_value, vis)
4462 # Otherwise, look at defaults and weak reverse dependencies
4465 for default, cond in self.defaults:
4466 dep_val = expr_value(cond)
4468 val = min(expr_value(default), dep_val)
4470 self._write_to_conf = True
4473 # Weak reverse dependencies are only considered if our
4474 # direct dependencies are met
4475 dep_val = expr_value(self.weak_rev_dep)
4476 if dep_val and expr_value(self.direct_dep):
4477 val = max(dep_val, val)
4478 self._write_to_conf = True
4480 # Reverse (select-related) dependencies take precedence
4481 dep_val = expr_value(self.rev_dep)
4483 if expr_value(self.direct_dep) < dep_val:
4484 self._warn_select_unsatisfied_deps()
4486 val = max(dep_val, val)
4487 self._write_to_conf = True
4489 # m is promoted to y for (1) bool symbols and (2) symbols with a
4490 # weak_rev_dep (from imply) of y
4492 (self.type is BOOL or expr_value(self.weak_rev_dep) == 2):
4496 # Visible choice symbol in y-mode choice. The choice mode limits
4497 # the visibility of choice symbols, so it's sufficient to just
4498 # check the visibility of the choice symbols themselves.
4499 val = 2 if self.choice.selection is self else 0
4501 elif vis and self.user_value:
4502 # Visible choice symbol in m-mode choice, with set non-0 user value
4505 self._cached_tri_val = val
4509 def assignable(self):
4511 See the class documentation.
4513 if self._cached_assignable is None:
4514 self._cached_assignable = self._assignable()
4515 return self._cached_assignable
4518 def visibility(self):
4520 See the class documentation.
4522 if self._cached_vis is None:
4523 self._cached_vis = _visibility(self)
4524 return self._cached_vis
4527 def config_string(self):
4529 See the class documentation.
4531 # _write_to_conf is determined when the value is calculated. This is a
4532 # hidden function call due to property magic.
4533 val = self.str_value
4534 if not self._write_to_conf:
4537 if self.orig_type in _BOOL_TRISTATE:
4538 return "{}{}={}\n" \
4539 .format(self.kconfig.config_prefix, self.name, val) \
4540 if val != "n" else \
4541 "# {}{} is not set\n" \
4542 .format(self.kconfig.config_prefix, self.name)
4544 if self.orig_type in _INT_HEX:
4545 return "{}{}={}\n" \
4546 .format(self.kconfig.config_prefix, self.name, val)
4548 # sym.orig_type is STRING
4549 return '{}{}="{}"\n' \
4550 .format(self.kconfig.config_prefix, self.name, escape(val))
4553 def name_and_loc(self):
4555 See the class documentation.
4557 return self.name + " " + _locs(self)
4559 def set_value(self, value):
4561 Sets the user value of the symbol.
4563 Equal in effect to assigning the value to the symbol within a .config
4564 file. For bool and tristate symbols, use the 'assignable' attribute to
4565 check which values can currently be assigned. Setting values outside
4566 'assignable' will cause Symbol.user_value to differ from
4567 Symbol.str/tri_value (be truncated down or up).
4569 Setting a choice symbol to 2 (y) sets Choice.user_selection to the
4570 choice symbol in addition to setting Symbol.user_value.
4571 Choice.user_selection is considered when the choice is in y mode (the
4574 Other symbols that depend (possibly indirectly) on this symbol are
4575 automatically recalculated to reflect the assigned value.
4578 The user value to give to the symbol. For bool and tristate symbols,
4579 n/m/y can be specified either as 0/1/2 (the usual format for tristate
4580 values in Kconfiglib) or as one of the strings "n", "m", or "y". For
4581 other symbol types, pass a string.
4583 Note that the value for an int/hex symbol is passed as a string, e.g.
4584 "123" or "0x0123". The format of this string is preserved in the
4587 Values that are invalid for the type (such as "foo" or 1 (m) for a
4588 BOOL or "0x123" for an INT) are ignored and won't be stored in
4589 Symbol.user_value. Kconfiglib will print a warning by default for
4590 invalid assignments, and set_value() will return False.
4592 Returns True if the value is valid for the type of the symbol, and
4593 False otherwise. This only looks at the form of the value. For BOOL and
4594 TRISTATE symbols, check the Symbol.assignable attribute to see what
4595 values are currently in range and would actually be reflected in the
4596 value of the symbol. For other symbol types, check whether the
4597 visibility is non-n.
4599 if self.orig_type in _BOOL_TRISTATE and value in STR_TO_TRI:
4600 value = STR_TO_TRI[value]
4602 # If the new user value matches the old, nothing changes, and we can
4603 # avoid invalidating cached values.
4605 # This optimization is skipped for choice symbols: Setting a choice
4606 # symbol's user value to y might change the state of the choice, so it
4607 # wouldn't be safe (symbol user values always match the values set in a
4608 # .config file or via set_value(), and are never implicitly updated).
4609 if value == self.user_value and not self.choice:
4610 self._was_set = True
4613 # Check if the value is valid for our type
4614 if not (self.orig_type is BOOL and value in (2, 0) or
4615 self.orig_type is TRISTATE and value in TRI_TO_STR or
4616 value.__class__ is str and
4617 (self.orig_type is STRING or
4618 self.orig_type is INT and _is_base_n(value, 10) or
4619 self.orig_type is HEX and _is_base_n(value, 16)
4620 and int(value, 16) >= 0)):
4622 # Display tristate values as n, m, y in the warning
4624 "the value {} is invalid for {}, which has type {} -- "
4625 "assignment ignored"
4626 .format(TRI_TO_STR[value] if value in TRI_TO_STR else
4627 "'{}'".format(value),
4628 self.name_and_loc, TYPE_TO_STR[self.orig_type]))
4632 self.user_value = value
4633 self._was_set = True
4635 if self.choice and value == 2:
4636 # Setting a choice symbol to y makes it the user selection of the
4637 # choice. Like for symbol user values, the user selection is not
4638 # guaranteed to match the actual selection of the choice, as
4639 # dependencies come into play.
4640 self.choice.user_selection = self
4641 self.choice._was_set = True
4642 self.choice._rec_invalidate()
4644 self._rec_invalidate_if_has_prompt()
4648 def unset_value(self):
4650 Removes any user value from the symbol, as if the symbol had never
4651 gotten a user value via Kconfig.load_config() or Symbol.set_value().
4653 if self.user_value is not None:
4654 self.user_value = None
4655 self._rec_invalidate_if_has_prompt()
4658 def referenced(self):
4660 See the class documentation.
4662 return {item for node in self.nodes for item in node.referenced}
4665 def orig_defaults(self):
4667 See the class documentation.
4669 return [d for node in self.nodes for d in node.orig_defaults]
4672 def orig_selects(self):
4674 See the class documentation.
4676 return [s for node in self.nodes for s in node.orig_selects]
4679 def orig_implies(self):
4681 See the class documentation.
4683 return [i for node in self.nodes for i in node.orig_implies]
4686 def orig_ranges(self):
4688 See the class documentation.
4690 return [r for node in self.nodes for r in node.orig_ranges]
4694 Returns a string with information about the symbol (including its name,
4695 value, visibility, and location(s)) when it is evaluated on e.g. the
4696 interactive Python prompt.
4698 fields = ["symbol " + self.name, TYPE_TO_STR[self.type]]
4701 for node in self.nodes:
4703 add('"{}"'.format(node.prompt[0]))
4705 # Only add quotes for non-bool/tristate symbols
4706 add("value " + (self.str_value if self.orig_type in _BOOL_TRISTATE
4707 else '"{}"'.format(self.str_value)))
4709 if not self.is_constant:
4710 # These aren't helpful to show for constant symbols
4712 if self.user_value is not None:
4713 # Only add quotes for non-bool/tristate symbols
4714 add("user value " + (TRI_TO_STR[self.user_value]
4715 if self.orig_type in _BOOL_TRISTATE
4716 else '"{}"'.format(self.user_value)))
4718 add("visibility " + TRI_TO_STR[self.visibility])
4721 add("choice symbol")
4723 if self.is_allnoconfig_y:
4724 add("allnoconfig_y")
4726 if self is self.kconfig.defconfig_list:
4727 add("is the defconfig_list symbol")
4729 if self.env_var is not None:
4730 add("from environment variable " + self.env_var)
4732 if self is self.kconfig.modules:
4733 add("is the modules symbol")
4735 add("direct deps " + TRI_TO_STR[expr_value(self.direct_dep)])
4738 for node in self.nodes:
4739 add("{}:{}".format(node.filename, node.linenr))
4741 add("constant" if self.is_constant else "undefined")
4743 return "<{}>".format(", ".join(fields))
4747 Returns a string representation of the symbol when it is printed.
4748 Matches the Kconfig format, with any parent dependencies propagated to
4749 the 'depends on' condition.
4751 The string is constructed by joining the strings returned by
4752 MenuNode.__str__() for each of the symbol's menu nodes, so symbols
4753 defined in multiple locations will return a string with all
4756 The returned string does not end in a newline. An empty string is
4757 returned for undefined and constant symbols.
4759 return self.custom_str(standard_sc_expr_str)
4761 def custom_str(self, sc_expr_str_fn):
4763 Works like Symbol.__str__(), but allows a custom format to be used for
4764 all symbol/choice references. See expr_str().
4766 return "\n\n".join(node.custom_str(sc_expr_str_fn)
4767 for node in self.nodes)
4775 Symbol constructor -- not intended to be called directly by Kconfiglib
4778 # These attributes are always set on the instance from outside and
4779 # don't need defaults:
4788 # - _visited is used during tree iteration and dep. loop detection
4789 self.orig_type = self._visited = 0
4801 self._cached_str_val = self._cached_tri_val = self._cached_vis = \
4802 self._cached_assignable = None
4804 # _write_to_conf is calculated along with the value. If True, the
4805 # Symbol gets a .config entry.
4807 self.is_allnoconfig_y = \
4809 self._write_to_conf = False
4811 # See Kconfig._build_dep()
4812 self._dependents = set()
4814 def _assignable(self):
4815 # Worker function for the 'assignable' attribute
4817 if self.orig_type not in _BOOL_TRISTATE:
4820 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
4821 # function call (property magic)
4822 vis = self.visibility
4826 rev_dep_val = expr_value(self.rev_dep)
4833 if self.type is BOOL or expr_value(self.weak_rev_dep) == 2:
4837 if rev_dep_val == 2:
4842 if self.type is BOOL or expr_value(self.weak_rev_dep) == 2:
4848 # Must be a tristate here, because bool m visibility gets promoted to y
4851 return (0, 1) if expr_value(self.weak_rev_dep) != 2 else (0, 2)
4853 if rev_dep_val == 2:
4856 # vis == rev_dep_val == 1
4860 def _invalidate(self):
4861 # Marks the symbol as needing to be recalculated
4863 self._cached_str_val = self._cached_tri_val = self._cached_vis = \
4864 self._cached_assignable = None
4866 def _rec_invalidate(self):
4867 # Invalidates the symbol and all items that (possibly) depend on it
4869 if self is self.kconfig.modules:
4870 # Invalidating MODULES has wide-ranging effects
4871 self.kconfig._invalidate_all()
4875 for item in self._dependents:
4876 # _cached_vis doubles as a flag that tells us whether 'item'
4877 # has cached values, because it's calculated as a side effect
4878 # of calculating all other (non-constant) cached values.
4880 # If item._cached_vis is None, it means there can't be cached
4881 # values on other items that depend on 'item', because if there
4882 # were, some value on 'item' would have been calculated and
4883 # item._cached_vis set as a side effect. It's therefore safe to
4884 # stop the invalidation at symbols with _cached_vis None.
4886 # This approach massively speeds up scripts that set a lot of
4887 # values, vs simply invalidating all possibly dependent symbols
4888 # (even when you already have a list of all the dependent
4889 # symbols, because some symbols get huge dependency trees).
4891 # This gracefully handles dependency loops too, which is nice
4892 # for choices, where the choice depends on the choice symbols
4894 if item._cached_vis is not None:
4895 item._rec_invalidate()
4897 def _rec_invalidate_if_has_prompt(self):
4898 # Invalidates the symbol and its dependent symbols, but only if the
4899 # symbol has a prompt. User values never have an effect on promptless
4900 # symbols, so we skip invalidation for them as an optimization.
4902 # This also prevents constant (quoted) symbols from being invalidated
4903 # if set_value() is called on them, which would make them lose their
4904 # value and break things.
4906 # Prints a warning if the symbol has no prompt. In some contexts (e.g.
4907 # when loading a .config files) assignments to promptless symbols are
4908 # normal and expected, so the warning can be disabled.
4910 for node in self.nodes:
4912 self._rec_invalidate()
4915 if self.kconfig._warn_assign_no_prompt:
4916 self.kconfig._warn(self.name_and_loc + " has no prompt, meaning "
4917 "user values have no effect on it")
4919 def _str_default(self):
4920 # write_min_config() helper function. Returns the value the symbol
4921 # would get from defaults if it didn't have a user value. Uses exactly
4922 # the same algorithm as the C implementation (though a bit cleaned up),
4923 # for compatibility.
4925 if self.orig_type in _BOOL_TRISTATE:
4928 # Defaults, selects, and implies do not affect choice symbols
4930 for default, cond in self.defaults:
4931 cond_val = expr_value(cond)
4933 val = min(expr_value(default), cond_val)
4936 val = max(expr_value(self.rev_dep),
4937 expr_value(self.weak_rev_dep),
4940 # Transpose mod to yes if type is bool (possibly due to modules
4942 if val == 1 and self.type is BOOL:
4945 return TRI_TO_STR[val]
4947 if self.orig_type: # STRING/INT/HEX
4948 for default, cond in self.defaults:
4949 if expr_value(cond):
4950 return default.str_value
4954 def _warn_select_unsatisfied_deps(self):
4955 # Helper for printing an informative warning when a symbol with
4956 # unsatisfied direct dependencies (dependencies from 'depends on', ifs,
4957 # and menus) is selected by some other symbol. Also warn if a symbol
4958 # whose direct dependencies evaluate to m is selected to y.
4960 msg = "{} has direct dependencies {} with value {}, but is " \
4961 "currently being {}-selected by the following symbols:" \
4962 .format(self.name_and_loc, expr_str(self.direct_dep),
4963 TRI_TO_STR[expr_value(self.direct_dep)],
4964 TRI_TO_STR[expr_value(self.rev_dep)])
4966 # The reverse dependencies from each select are ORed together
4967 for select in split_expr(self.rev_dep, OR):
4968 if expr_value(select) <= expr_value(self.direct_dep):
4969 # Only include selects that exceed the direct dependencies
4972 # - 'select A if B' turns into A && B
4973 # - 'select A' just turns into A
4975 # In both cases, we can split on AND and pick the first operand
4976 selecting_sym = split_expr(select, AND)[0]
4978 msg += "\n - {}, with value {}, direct dependencies {} " \
4980 .format(selecting_sym.name_and_loc,
4981 selecting_sym.str_value,
4982 expr_str(selecting_sym.direct_dep),
4983 TRI_TO_STR[expr_value(selecting_sym.direct_dep)])
4985 if select.__class__ is tuple:
4986 msg += ", and select condition {} (value: {})" \
4987 .format(expr_str(select[2]),
4988 TRI_TO_STR[expr_value(select[2])])
4990 self.kconfig._warn(msg)
4993 class Choice(object):
4995 Represents a choice statement:
5001 The following attributes are available on Choice instances. They should be
5002 treated as read-only, and some are implemented through @property magic (but
5003 are still efficient to access due to internal caching).
5005 Note: Prompts, help texts, and locations are stored in the Choice's
5006 MenuNode(s) rather than in the Choice itself. Check the MenuNode class and
5007 the Choice.nodes attribute. This organization matches the C tools.
5010 The name of the choice, e.g. "FOO" for 'choice FOO', or None if the
5014 The type of the choice. One of BOOL, TRISTATE, UNKNOWN. UNKNOWN is for
5015 choices defined without a type where none of the contained symbols have a
5016 type either (otherwise the choice inherits the type of the first symbol
5017 defined with a type).
5019 When running without modules (CONFIG_MODULES=n), TRISTATE choices
5020 magically change type to BOOL. This matches the C tools, and makes sense
5021 for menuconfig-like functionality.
5024 The type as given in the Kconfig file, without any magic applied. Used
5025 when printing the choice.
5028 The tristate value (mode) of the choice. A choice can be in one of three
5031 0 (n) - The choice is disabled and no symbols can be selected. For
5032 visible choices, this mode is only possible for choices with
5033 the 'optional' flag set (see kconfig-language.txt).
5035 1 (m) - Any number of choice symbols can be set to m, the rest will
5038 2 (y) - One symbol will be y, the rest n.
5040 Only tristate choices can be in m mode. The visibility of the choice is
5041 an upper bound on the mode, and the mode in turn is an upper bound on the
5042 visibility of the choice symbols.
5044 To change the mode, use Choice.set_value().
5046 Implementation note:
5047 The C tools internally represent choices as a type of symbol, with
5048 special-casing in many code paths. This is why there is a lot of
5049 similarity to Symbol. The value (mode) of a choice is really just a
5050 normal symbol value, and an implicit reverse dependency forces its
5051 lower bound to m for visible non-optional choices (the reverse
5052 dependency is 'm && <visibility>').
5054 Symbols within choices get the choice propagated as a dependency to
5055 their properties. This turns the mode of the choice into an upper bound
5056 on e.g. the visibility of choice symbols, and explains the gotcha
5057 related to printing choice symbols mentioned in the module docstring.
5059 Kconfiglib uses a separate Choice class only because it makes the code
5060 and interface less confusing (especially in a user-facing interface).
5061 Corresponding attributes have the same name in the Symbol and Choice
5062 classes, for consistency and compatibility.
5065 Like choice.tri_value, but gives the value as one of the strings
5069 The value (mode) selected by the user through Choice.set_value(). Either
5070 0, 1, or 2, or None if the user hasn't selected a mode. See
5073 WARNING: Do not assign directly to this. It will break things. Use
5074 Choice.set_value() instead.
5077 See the symbol class documentation. Gives the assignable values (modes).
5080 The Symbol instance of the currently selected symbol. None if the Choice
5081 is not in y mode or has no selected symbol (due to unsatisfied
5082 dependencies on choice symbols).
5084 WARNING: Do not assign directly to this. It will break things. Call
5085 sym.set_value(2) on the choice symbol you want to select instead.
5088 The symbol selected by the user (by setting it to y). Ignored if the
5089 choice is not in y mode, but still remembered so that the choice "snaps
5090 back" to the user selection if the mode is changed back to y. This might
5091 differ from 'selection' due to unsatisfied dependencies.
5093 WARNING: Do not assign directly to this. It will break things. Call
5094 sym.set_value(2) on the choice symbol to be selected instead.
5097 See the Symbol class documentation. Acts on the value (mode).
5102 "<choice MY_CHOICE> (defined at foo/Kconfig:12)"
5104 , giving the name of the choice and its definition location(s). If the
5105 choice has no name (isn't defined with 'choice MY_CHOICE'), then it will
5106 be shown as "<choice>" before the list of locations (always a single one
5110 List of symbols contained in the choice.
5112 Obscure gotcha: If a symbol depends on the previous symbol within a
5113 choice so that an implicit menu is created, it won't be a choice symbol,
5114 and won't be included in 'syms'.
5117 A list of MenuNodes for this choice. In practice, the list will probably
5118 always contain a single MenuNode, but it is possible to give a choice a
5119 name and define it in multiple locations.
5122 List of (symbol, cond) tuples for the choice's 'defaults' properties. For
5123 example, 'default A if B && C' is represented as (A, (AND, B, C)). If
5124 there is no condition, 'cond' is self.kconfig.y.
5126 Note that 'depends on' and parent dependencies are propagated to
5127 'default' conditions.
5130 See the corresponding attribute on the MenuNode class.
5133 See Symbol.direct_dep.
5136 A set() with all symbols referenced in the properties and property
5137 conditions of the choice.
5139 Also includes dependencies from surrounding menus and ifs, because those
5140 get propagated to the choice (see the 'Intro to symbol values' section in
5141 the module docstring).
5144 True if the choice has the 'optional' flag set on it and can be in
5148 The Kconfig instance this choice is from.
5151 "_cached_assignable",
5152 "_cached_selection",
5177 Returns the type of the choice. See Symbol.type.
5179 if self.orig_type is TRISTATE and not self.kconfig.modules.tri_value:
5181 return self.orig_type
5184 def str_value(self):
5186 See the class documentation.
5188 return TRI_TO_STR[self.tri_value]
5191 def tri_value(self):
5193 See the class documentation.
5195 # This emulates a reverse dependency of 'm && visibility' for
5196 # non-optional choices, which is how the C implementation does it
5198 val = 0 if self.is_optional else 1
5200 if self.user_value is not None:
5201 val = max(val, self.user_value)
5203 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
5204 # function call (property magic)
5205 val = min(val, self.visibility)
5207 # Promote m to y for boolean choices
5208 return 2 if val == 1 and self.type is BOOL else val
5211 def assignable(self):
5213 See the class documentation.
5215 if self._cached_assignable is None:
5216 self._cached_assignable = self._assignable()
5217 return self._cached_assignable
5220 def visibility(self):
5222 See the class documentation.
5224 if self._cached_vis is None:
5225 self._cached_vis = _visibility(self)
5226 return self._cached_vis
5229 def name_and_loc(self):
5231 See the class documentation.
5233 # Reuse the expression format, which is '<choice (name, if any)>'.
5234 return standard_sc_expr_str(self) + " " + _locs(self)
5237 def selection(self):
5239 See the class documentation.
5241 if self._cached_selection is _NO_CACHED_SELECTION:
5242 self._cached_selection = self._selection()
5243 return self._cached_selection
5245 def set_value(self, value):
5247 Sets the user value (mode) of the choice. Like for Symbol.set_value(),
5248 the visibility might truncate the value. Choices without the 'optional'
5249 attribute (is_optional) can never be in n mode, but 0/"n" is still
5250 accepted since it's not a malformed value (though it will have no
5253 Returns True if the value is valid for the type of the choice, and
5254 False otherwise. This only looks at the form of the value. Check the
5255 Choice.assignable attribute to see what values are currently in range
5256 and would actually be reflected in the mode of the choice.
5258 if value in STR_TO_TRI:
5259 value = STR_TO_TRI[value]
5261 if value == self.user_value:
5262 # We know the value must be valid if it was successfully set
5264 self._was_set = True
5267 if not (self.orig_type is BOOL and value in (2, 0) or
5268 self.orig_type is TRISTATE and value in TRI_TO_STR):
5270 # Display tristate values as n, m, y in the warning
5272 "the value {} is invalid for {}, which has type {} -- "
5273 "assignment ignored"
5274 .format(TRI_TO_STR[value] if value in TRI_TO_STR else
5275 "'{}'".format(value),
5276 self.name_and_loc, TYPE_TO_STR[self.orig_type]))
5280 self.user_value = value
5281 self._was_set = True
5282 self._rec_invalidate()
5286 def unset_value(self):
5288 Resets the user value (mode) and user selection of the Choice, as if
5289 the user had never touched the mode or any of the choice symbols.
5291 if self.user_value is not None or self.user_selection:
5292 self.user_value = self.user_selection = None
5293 self._rec_invalidate()
5296 def referenced(self):
5298 See the class documentation.
5300 return {item for node in self.nodes for item in node.referenced}
5303 def orig_defaults(self):
5305 See the class documentation.
5307 return [d for node in self.nodes for d in node.orig_defaults]
5311 Returns a string with information about the choice when it is evaluated
5312 on e.g. the interactive Python prompt.
5314 fields = ["choice " + self.name if self.name else "choice",
5315 TYPE_TO_STR[self.type]]
5318 for node in self.nodes:
5320 add('"{}"'.format(node.prompt[0]))
5322 add("mode " + self.str_value)
5324 if self.user_value is not None:
5325 add('user mode {}'.format(TRI_TO_STR[self.user_value]))
5328 add("{} selected".format(self.selection.name))
5330 if self.user_selection:
5331 user_sel_str = "{} selected by user" \
5332 .format(self.user_selection.name)
5334 if self.selection is not self.user_selection:
5335 user_sel_str += " (overridden)"
5339 add("visibility " + TRI_TO_STR[self.visibility])
5341 if self.is_optional:
5344 for node in self.nodes:
5345 add("{}:{}".format(node.filename, node.linenr))
5347 return "<{}>".format(", ".join(fields))
5351 Returns a string representation of the choice when it is printed.
5352 Matches the Kconfig format (though without the contained choice
5353 symbols), with any parent dependencies propagated to the 'depends on'
5356 The returned string does not end in a newline.
5358 See Symbol.__str__() as well.
5360 return self.custom_str(standard_sc_expr_str)
5362 def custom_str(self, sc_expr_str_fn):
5364 Works like Choice.__str__(), but allows a custom format to be used for
5365 all symbol/choice references. See expr_str().
5367 return "\n\n".join(node.custom_str(sc_expr_str_fn)
5368 for node in self.nodes)
5376 Choice constructor -- not intended to be called directly by Kconfiglib
5379 # These attributes are always set on the instance from outside and
5380 # don't need defaults:
5385 # - _visited is used during dep. loop detection
5386 self.orig_type = self._visited = 0
5394 self.user_value = self.user_selection = \
5395 self._cached_vis = self._cached_assignable = None
5397 self._cached_selection = _NO_CACHED_SELECTION
5399 # is_constant is checked by _depend_on(). Just set it to avoid having
5400 # to special-case choices.
5401 self.is_constant = self.is_optional = False
5403 # See Kconfig._build_dep()
5404 self._dependents = set()
5406 def _assignable(self):
5407 # Worker function for the 'assignable' attribute
5409 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
5410 # function call (property magic)
5411 vis = self.visibility
5417 if not self.is_optional:
5418 return (2,) if self.type is BOOL else (1, 2)
5419 return (0, 2) if self.type is BOOL else (0, 1, 2)
5423 return (0, 1) if self.is_optional else (1,)
5425 def _selection(self):
5426 # Worker function for the 'selection' attribute
5428 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
5429 # function call (property magic)
5430 if self.tri_value != 2:
5431 # Not in y mode, so no selection
5434 # Use the user selection if it's visible
5435 if self.user_selection and self.user_selection.visibility:
5436 return self.user_selection
5438 # Otherwise, check if we have a default
5439 return self._selection_from_defaults()
5441 def _selection_from_defaults(self):
5442 # Check if we have a default
5443 for sym, cond in self.defaults:
5444 # The default symbol must be visible too
5445 if expr_value(cond) and sym.visibility:
5448 # Otherwise, pick the first visible symbol, if any
5449 for sym in self.syms:
5453 # Couldn't find a selection
5456 def _invalidate(self):
5457 self._cached_vis = self._cached_assignable = None
5458 self._cached_selection = _NO_CACHED_SELECTION
5460 def _rec_invalidate(self):
5461 # See Symbol._rec_invalidate()
5465 for item in self._dependents:
5466 if item._cached_vis is not None:
5467 item._rec_invalidate()
5470 class MenuNode(object):
5472 Represents a menu node in the configuration. This corresponds to an entry
5473 in e.g. the 'make menuconfig' interface, though non-visible choices, menus,
5474 and comments also get menu nodes. If a symbol or choice is defined in
5475 multiple locations, it gets one menu node for each location.
5477 The top-level menu node, corresponding to the implicit top-level menu, is
5478 available in Kconfig.top_node.
5480 The menu nodes for a Symbol or Choice can be found in the
5481 Symbol/Choice.nodes attribute. Menus and comments are represented as plain
5482 menu nodes, with their text stored in the prompt attribute (prompt[0]).
5483 This mirrors the C implementation.
5485 The following attributes are available on MenuNode instances. They should
5486 be viewed as read-only.
5489 Either a Symbol, a Choice, or one of the constants MENU and COMMENT.
5490 Menus and comments are represented as plain menu nodes. Ifs are collapsed
5491 (matching the C implementation) and do not appear in the final menu tree.
5494 The following menu node. None if there is no following node.
5497 The first child menu node. None if there are no children.
5499 Choices and menus naturally have children, but Symbols can also have
5500 children because of menus created automatically from dependencies (see
5501 kconfig-language.txt).
5504 The parent menu node. None if there is no parent.
5507 A (string, cond) tuple with the prompt for the menu node and its
5508 conditional expression (which is self.kconfig.y if there is no
5509 condition). None if there is no prompt.
5511 For symbols and choices, the prompt is stored in the MenuNode rather than
5512 the Symbol or Choice instance. For menus and comments, the prompt holds
5516 The 'default' properties for this particular menu node. See
5519 When evaluating defaults, you should use Symbol/Choice.defaults instead,
5520 as it include properties from all menu nodes (a symbol/choice can have
5521 multiple definition locations/menu nodes). MenuNode.defaults is meant for
5522 documentation generation.
5525 Like MenuNode.defaults, for selects.
5528 Like MenuNode.defaults, for implies.
5531 Like MenuNode.defaults, for ranges.
5538 These work the like the corresponding attributes without orig_*, but omit
5539 any dependencies propagated from 'depends on' and surrounding 'if's (the
5540 direct dependencies, stored in MenuNode.dep).
5542 One use for this is generating less cluttered documentation, by only
5543 showing the direct dependencies in one place.
5546 The help text for the menu node for Symbols and Choices. None if there is
5547 no help text. Always stored in the node rather than the Symbol or Choice.
5548 It is possible to have a separate help text at each location if a symbol
5549 is defined in multiple locations.
5551 Trailing whitespace (including a final newline) is stripped from the help
5552 text. This was not the case before Kconfiglib 10.21.0, where the format
5556 The direct ('depends on') dependencies for the menu node, or
5557 self.kconfig.y if there are no direct dependencies.
5559 This attribute includes any dependencies from surrounding menus and ifs.
5560 Those get propagated to the direct dependencies, and the resulting direct
5561 dependencies in turn get propagated to the conditions of all properties.
5563 If a symbol or choice is defined in multiple locations, only the
5564 properties defined at a particular location get the corresponding
5565 MenuNode.dep dependencies propagated to them.
5568 The 'visible if' dependencies for the menu node (which must represent a
5569 menu), or self.kconfig.y if there are no 'visible if' dependencies.
5570 'visible if' dependencies are recursively propagated to the prompts of
5571 symbols and choices within the menu.
5574 A set() with all symbols and choices referenced in the properties and
5575 property conditions of the menu node.
5577 Also includes dependencies inherited from surrounding menus and ifs.
5578 Choices appear in the dependencies of choice symbols.
5581 Set to True if the children of the menu node should be displayed in a
5582 separate menu. This is the case for the following items:
5584 - Menus (node.item == MENU)
5588 - Symbols defined with the 'menuconfig' keyword. The children come from
5589 implicitly created submenus, and should be displayed in a separate
5590 menu rather than being indented.
5592 'is_menuconfig' is just a hint on how to display the menu node. It's
5593 ignored internally by Kconfiglib, except when printing symbols.
5596 The location where the menu node appears. The filename is relative to
5597 $srctree (or to the current directory if $srctree isn't set), except
5598 absolute paths are used for paths outside $srctree.
5601 A tuple of (filename, linenr) tuples, giving the locations of the
5602 'source' statements via which the Kconfig file containing this menu node
5603 was included. The first element is the location of the 'source' statement
5604 in the top-level Kconfig file passed to Kconfig.__init__(), etc.
5606 Note that the Kconfig file of the menu node itself isn't included. Check
5607 'filename' and 'linenr' for that.
5610 The Kconfig instance the menu node is from.
5635 # Properties defined on this particular menu node. A local 'depends on'
5636 # only applies to these, in case a symbol is defined in multiple
5644 def orig_prompt(self):
5646 See the class documentation.
5650 return (self.prompt[0], self._strip_dep(self.prompt[1]))
5653 def orig_defaults(self):
5655 See the class documentation.
5657 return [(default, self._strip_dep(cond))
5658 for default, cond in self.defaults]
5661 def orig_selects(self):
5663 See the class documentation.
5665 return [(select, self._strip_dep(cond))
5666 for select, cond in self.selects]
5669 def orig_implies(self):
5671 See the class documentation.
5673 return [(imply, self._strip_dep(cond))
5674 for imply, cond in self.implies]
5677 def orig_ranges(self):
5679 See the class documentation.
5681 return [(low, high, self._strip_dep(cond))
5682 for low, high, cond in self.ranges]
5685 def referenced(self):
5687 See the class documentation.
5689 # self.dep is included to catch dependencies from a lone 'depends on'
5690 # when there are no properties to propagate it to
5691 res = expr_items(self.dep)
5694 res |= expr_items(self.prompt[1])
5696 if self.item is MENU:
5697 res |= expr_items(self.visibility)
5699 for value, cond in self.defaults:
5700 res |= expr_items(value)
5701 res |= expr_items(cond)
5703 for value, cond in self.selects:
5705 res |= expr_items(cond)
5707 for value, cond in self.implies:
5709 res |= expr_items(cond)
5711 for low, high, cond in self.ranges:
5714 res |= expr_items(cond)
5720 Returns a string with information about the menu node when it is
5721 evaluated on e.g. the interactive Python prompt.
5726 if self.item.__class__ is Symbol:
5727 add("menu node for symbol " + self.item.name)
5729 elif self.item.__class__ is Choice:
5730 s = "menu node for choice"
5731 if self.item.name is not None:
5732 s += " " + self.item.name
5735 elif self.item is MENU:
5736 add("menu node for menu")
5738 else: # self.item is COMMENT
5739 add("menu node for comment")
5742 add('prompt "{}" (visibility {})'.format(
5743 self.prompt[0], TRI_TO_STR[expr_value(self.prompt[1])]))
5745 if self.item.__class__ is Symbol and self.is_menuconfig:
5746 add("is menuconfig")
5748 add("deps " + TRI_TO_STR[expr_value(self.dep)])
5750 if self.item is MENU:
5751 add("'visible if' deps " + TRI_TO_STR[expr_value(self.visibility)])
5753 if self.item.__class__ in _SYMBOL_CHOICE and self.help is not None:
5762 add("{}:{}".format(self.filename, self.linenr))
5764 return "<{}>".format(", ".join(fields))
5768 Returns a string representation of the menu node. Matches the Kconfig
5769 format, with any parent dependencies propagated to the 'depends on'
5772 The output could (almost) be fed back into a Kconfig parser to redefine
5773 the object associated with the menu node. See the module documentation
5774 for a gotcha related to choice symbols.
5776 For symbols and choices with multiple menu nodes (multiple definition
5777 locations), properties that aren't associated with a particular menu
5778 node are shown on all menu nodes ('option env=...', 'optional' for
5781 The returned string does not end in a newline.
5783 return self.custom_str(standard_sc_expr_str)
5785 def custom_str(self, sc_expr_str_fn):
5787 Works like MenuNode.__str__(), but allows a custom format to be used
5788 for all symbol/choice references. See expr_str().
5790 return self._menu_comment_node_str(sc_expr_str_fn) \
5791 if self.item in _MENU_COMMENT else \
5792 self._sym_choice_node_str(sc_expr_str_fn)
5794 def _menu_comment_node_str(self, sc_expr_str_fn):
5795 s = '{} "{}"'.format("menu" if self.item is MENU else "comment",
5798 if self.dep is not self.kconfig.y:
5799 s += "\n\tdepends on {}".format(expr_str(self.dep, sc_expr_str_fn))
5801 if self.item is MENU and self.visibility is not self.kconfig.y:
5802 s += "\n\tvisible if {}".format(expr_str(self.visibility,
5807 def _sym_choice_node_str(self, sc_expr_str_fn):
5809 lines.append("\t" + s)
5811 def indent_add_cond(s, cond):
5812 if cond is not self.kconfig.y:
5813 s += " if " + expr_str(cond, sc_expr_str_fn)
5818 if sc.__class__ is Symbol:
5819 lines = [("menuconfig " if self.is_menuconfig else "config ")
5822 lines = ["choice " + sc.name if sc.name else "choice"]
5824 if sc.orig_type and not self.prompt: # sc.orig_type != UNKNOWN
5825 # If there's a prompt, we'll use the '<type> "prompt"' shorthand
5827 indent_add(TYPE_TO_STR[sc.orig_type])
5831 prefix = TYPE_TO_STR[sc.orig_type]
5833 # Symbol defined without a type (which generates a warning)
5836 indent_add_cond(prefix + ' "{}"'.format(escape(self.prompt[0])),
5837 self.orig_prompt[1])
5839 if sc.__class__ is Symbol:
5840 if sc.is_allnoconfig_y:
5841 indent_add("option allnoconfig_y")
5843 if sc is sc.kconfig.defconfig_list:
5844 indent_add("option defconfig_list")
5846 if sc.env_var is not None:
5847 indent_add('option env="{}"'.format(sc.env_var))
5849 if sc is sc.kconfig.modules:
5850 indent_add("option modules")
5852 for low, high, cond in self.orig_ranges:
5854 "range {} {}".format(sc_expr_str_fn(low),
5855 sc_expr_str_fn(high)),
5858 for default, cond in self.orig_defaults:
5859 indent_add_cond("default " + expr_str(default, sc_expr_str_fn),
5862 if sc.__class__ is Choice and sc.is_optional:
5863 indent_add("optional")
5865 if sc.__class__ is Symbol:
5866 for select, cond in self.orig_selects:
5867 indent_add_cond("select " + sc_expr_str_fn(select), cond)
5869 for imply, cond in self.orig_implies:
5870 indent_add_cond("imply " + sc_expr_str_fn(imply), cond)
5872 if self.dep is not sc.kconfig.y:
5873 indent_add("depends on " + expr_str(self.dep, sc_expr_str_fn))
5875 if self.help is not None:
5877 for line in self.help.splitlines():
5878 indent_add(" " + line)
5880 return "\n".join(lines)
5882 def _strip_dep(self, expr):
5883 # Helper function for removing MenuNode.dep from 'expr'. Uses two
5884 # pieces of internal knowledge: (1) Expressions are reused rather than
5885 # copied, and (2) the direct dependencies always appear at the end.
5887 # ... if dep -> ... if y
5888 if self.dep is expr:
5889 return self.kconfig.y
5891 # (AND, X, dep) -> X
5892 if expr.__class__ is tuple and expr[0] is AND and expr[2] is self.dep:
5898 class Variable(object):
5900 Represents a preprocessor variable/function.
5902 The following attributes are available:
5905 The name of the variable.
5908 The unexpanded value of the variable.
5911 The expanded value of the variable. For simple variables (those defined
5912 with :=), this will equal 'value'. Accessing this property will raise a
5913 KconfigError if the expansion seems to be stuck in a loop.
5915 Accessing this field is the same as calling expanded_value_w_args() with
5916 no arguments. I hadn't considered function arguments when adding it. It
5917 is retained for backwards compatibility though.
5920 True if the variable is recursive (defined with =).
5931 def expanded_value(self):
5933 See the class documentation.
5935 return self.expanded_value_w_args()
5937 def expanded_value_w_args(self, *args):
5939 Returns the expanded value of the variable/function. Any arguments
5940 passed will be substituted for $(1), $(2), etc.
5942 Raises a KconfigError if the expansion seems to be stuck in a loop.
5944 return self.kconfig._fn_val((self.name,) + args)
5947 return "<variable {}, {}, value '{}'>" \
5949 "recursive" if self.is_recursive else "immediate",
5953 class KconfigError(Exception):
5955 Exception raised for Kconfig-related errors.
5957 KconfigError and KconfigSyntaxError are the same class. The
5958 KconfigSyntaxError alias is only maintained for backwards compatibility.
5961 KconfigSyntaxError = KconfigError # Backwards compatibility
5964 class InternalError(Exception):
5965 "Never raised. Kept around for backwards compatibility."
5970 # If 'errno' and 'strerror' are set on IOError, then __str__() always returns
5971 # "[Errno <errno>] <strerror>", ignoring any custom message passed to the
5972 # constructor. By defining our own subclass, we can use a custom message while
5973 # also providing 'errno', 'strerror', and 'filename' to scripts.
5974 class _KconfigIOError(IOError):
5975 def __init__(self, ioerror, msg):
5977 super(_KconfigIOError, self).__init__(
5978 ioerror.errno, ioerror.strerror, ioerror.filename)
5989 def expr_value(expr):
5991 Evaluates the expression 'expr' to a tristate value. Returns 0 (n), 1 (m),
5994 'expr' must be an already-parsed expression from a Symbol, Choice, or
5995 MenuNode property. To evaluate an expression represented as a string, use
5996 Kconfig.eval_string().
5998 Passing subexpressions of expressions to this function works as expected.
6000 if expr.__class__ is not tuple:
6001 return expr.tri_value
6004 v1 = expr_value(expr[1])
6005 # Short-circuit the n case as an optimization (~5% faster
6006 # allnoconfig.py and allyesconfig.py, as of writing)
6007 return 0 if not v1 else min(v1, expr_value(expr[2]))
6010 v1 = expr_value(expr[1])
6011 # Short-circuit the y case as an optimization
6012 return 2 if v1 == 2 else max(v1, expr_value(expr[2]))
6015 return 2 - expr_value(expr[1])
6019 # Implements <, <=, >, >= comparisons as well. These were added to
6020 # kconfig in 31847b67 (kconfig: allow use of relations other than
6025 # If both operands are strings...
6026 if v1.orig_type is STRING and v2.orig_type is STRING:
6027 # ...then compare them lexicographically
6028 comp = _strcmp(v1.str_value, v2.str_value)
6030 # Otherwise, try to compare them as numbers
6032 comp = _sym_to_num(v1) - _sym_to_num(v2)
6034 # Fall back on a lexicographic comparison if the operands don't
6036 comp = _strcmp(v1.str_value, v2.str_value)
6038 return 2*(comp == 0 if rel is EQUAL else
6039 comp != 0 if rel is UNEQUAL else
6040 comp < 0 if rel is LESS else
6041 comp <= 0 if rel is LESS_EQUAL else
6042 comp > 0 if rel is GREATER else
6046 def standard_sc_expr_str(sc):
6048 Standard symbol/choice printing function. Uses plain Kconfig syntax, and
6049 displays choices as <choice> (or <choice NAME>, for named choices).
6053 if sc.__class__ is Symbol:
6054 if sc.is_constant and sc.name not in STR_TO_TRI:
6055 return '"{}"'.format(escape(sc.name))
6058 return "<choice {}>".format(sc.name) if sc.name else "<choice>"
6061 def expr_str(expr, sc_expr_str_fn=standard_sc_expr_str):
6063 Returns the string representation of the expression 'expr', as in a Kconfig
6066 Passing subexpressions of expressions to this function works as expected.
6068 sc_expr_str_fn (default: standard_sc_expr_str):
6069 This function is called for every symbol/choice (hence "sc") appearing in
6070 the expression, with the symbol/choice as the argument. It is expected to
6071 return a string to be used for the symbol/choice.
6073 This can be used e.g. to turn symbols/choices into links when generating
6074 documentation, or for printing the value of each symbol/choice after it.
6076 Note that quoted values are represented as constants symbols
6077 (Symbol.is_constant == True).
6079 if expr.__class__ is not tuple:
6080 return sc_expr_str_fn(expr)
6083 return "{} && {}".format(_parenthesize(expr[1], OR, sc_expr_str_fn),
6084 _parenthesize(expr[2], OR, sc_expr_str_fn))
6087 # This turns A && B || C && D into "(A && B) || (C && D)", which is
6088 # redundant, but more readable
6089 return "{} || {}".format(_parenthesize(expr[1], AND, sc_expr_str_fn),
6090 _parenthesize(expr[2], AND, sc_expr_str_fn))
6093 if expr[1].__class__ is tuple:
6094 return "!({})".format(expr_str(expr[1], sc_expr_str_fn))
6095 return "!" + sc_expr_str_fn(expr[1]) # Symbol
6099 # Relation operands are always symbols (quoted strings are constant
6101 return "{} {} {}".format(sc_expr_str_fn(expr[1]), REL_TO_STR[expr[0]],
6102 sc_expr_str_fn(expr[2]))
6105 def expr_items(expr):
6107 Returns a set() of all items (symbols and choices) that appear in the
6110 Passing subexpressions of expressions to this function works as expected.
6115 if subexpr.__class__ is tuple:
6116 # AND, OR, NOT, or relation
6120 # NOTs only have a single operand
6121 if subexpr[0] is not NOT:
6132 def split_expr(expr, op):
6134 Returns a list containing the top-level AND or OR operands in the
6135 expression 'expr', in the same (left-to-right) order as they appear in
6138 This can be handy e.g. for splitting (weak) reverse dependencies
6139 from 'select' and 'imply' into individual selects/implies.
6142 Either AND to get AND operands, or OR to get OR operands.
6144 (Having this as an operand might be more future-safe than having two
6145 hardcoded functions.)
6148 Pseudo-code examples:
6150 split_expr( A , OR ) -> [A]
6151 split_expr( A && B , OR ) -> [A && B]
6152 split_expr( A || B , OR ) -> [A, B]
6153 split_expr( A || B , AND ) -> [A || B]
6154 split_expr( A || B || (C && D) , OR ) -> [A, B, C && D]
6156 # Second || is not at the top level
6157 split_expr( A || (B && (C || D)) , OR ) -> [A, B && (C || D)]
6159 # Parentheses don't matter as long as we stay at the top level (don't
6160 # encounter any non-'op' nodes)
6161 split_expr( (A || B) || C , OR ) -> [A, B, C]
6162 split_expr( A || (B || C) , OR ) -> [A, B, C]
6167 if subexpr.__class__ is tuple and subexpr[0] is op:
6179 Escapes the string 's' in the same fashion as is done for display in
6180 Kconfig format and when writing strings to a .config file. " and \ are
6181 replaced by \" and \\, respectively.
6183 # \ must be escaped before " to avoid double escaping
6184 return s.replace("\\", r"\\").replace('"', r'\"')
6189 Unescapes the string 's'. \ followed by any character is replaced with just
6190 that character. Used internally when reading .config files.
6192 return _unescape_sub(r"\1", s)
6195 _unescape_sub = re.compile(r"\\(.)").sub
6198 def standard_kconfig(description=None):
6200 Argument parsing helper for tools that take a single optional Kconfig file
6201 argument (default: Kconfig). Returns the Kconfig instance for the parsed
6202 configuration. Uses argparse internally.
6204 Exits with sys.exit() (which raises SystemExit) on errors.
6206 description (default: None):
6207 The 'description' passed to argparse.ArgumentParser().
6208 argparse.RawDescriptionHelpFormatter is used, so formatting is preserved.
6212 parser = argparse.ArgumentParser(
6213 formatter_class=argparse.RawDescriptionHelpFormatter,
6214 description=description)
6216 parser.add_argument(
6221 help="Top-level Kconfig file (default: Kconfig)")
6223 return Kconfig(parser.parse_args().kconfig, suppress_traceback=True)
6226 def standard_config_filename():
6228 Helper for tools. Returns the value of KCONFIG_CONFIG (which specifies the
6229 .config file to load/save) if it is set, and ".config" otherwise.
6231 Calling load_config() with filename=None might give the behavior you want,
6232 without having to use this function.
6234 return os.getenv("KCONFIG_CONFIG", ".config")
6237 def load_allconfig(kconf, filename):
6239 Use Kconfig.load_allconfig() instead, which was added in Kconfiglib 13.4.0.
6240 Supported for backwards compatibility. Might be removed at some point after
6241 a long period of deprecation warnings.
6243 allconfig = os.getenv("KCONFIG_ALLCONFIG")
6244 if allconfig is None:
6248 # "Upcasts" a _KconfigIOError to an IOError, removing the custom
6249 # __str__() message. The standard message is better here.
6251 # This might also convert an OSError to an IOError in obscure cases,
6252 # but it's probably not a big deal. The distinction is shaky (see
6254 return IOError(e.errno, e.strerror, e.filename)
6256 old_warn_assign_override = kconf.warn_assign_override
6257 old_warn_assign_redun = kconf.warn_assign_redun
6258 kconf.warn_assign_override = kconf.warn_assign_redun = False
6260 if allconfig in ("", "1"):
6262 print(kconf.load_config(filename, False))
6263 except EnvironmentError as e1:
6265 print(kconf.load_config("all.config", False))
6266 except EnvironmentError as e2:
6267 sys.exit("error: KCONFIG_ALLCONFIG is set, but neither {} "
6268 "nor all.config could be opened: {}, {}"
6269 .format(filename, std_msg(e1), std_msg(e2)))
6272 print(kconf.load_config(allconfig, False))
6273 except EnvironmentError as e:
6274 sys.exit("error: KCONFIG_ALLCONFIG is set to '{}', which "
6275 "could not be opened: {}"
6276 .format(allconfig, std_msg(e)))
6278 kconf.warn_assign_override = old_warn_assign_override
6279 kconf.warn_assign_redun = old_warn_assign_redun
6283 # Internal functions
6287 def _visibility(sc):
6288 # Symbols and Choices have a "visibility" that acts as an upper bound on
6289 # the values a user can set for them, corresponding to the visibility in
6290 # e.g. 'make menuconfig'. This function calculates the visibility for the
6291 # Symbol or Choice 'sc' -- the logic is nearly identical.
6295 for node in sc.nodes:
6297 vis = max(vis, expr_value(node.prompt[1]))
6299 if sc.__class__ is Symbol and sc.choice:
6300 if sc.choice.orig_type is TRISTATE and \
6301 sc.orig_type is not TRISTATE and sc.choice.tri_value != 2:
6302 # Non-tristate choice symbols are only visible in y mode
6305 if sc.orig_type is TRISTATE and vis == 1 and sc.choice.tri_value == 2:
6306 # Choice symbols with m visibility are not visible in y mode
6309 # Promote m to y if we're dealing with a non-tristate (possibly due to
6310 # modules being disabled)
6311 if vis == 1 and sc.type is not TRISTATE:
6317 def _depend_on(sc, expr):
6318 # Adds 'sc' (symbol or choice) as a "dependee" to all symbols in 'expr'.
6319 # Constant symbols in 'expr' are skipped as they can never change value
6322 if expr.__class__ is tuple:
6323 # AND, OR, NOT, or relation
6325 _depend_on(sc, expr[1])
6327 # NOTs only have a single operand
6328 if expr[0] is not NOT:
6329 _depend_on(sc, expr[2])
6331 elif not expr.is_constant:
6332 # Non-constant symbol, or choice
6333 expr._dependents.add(sc)
6336 def _parenthesize(expr, type_, sc_expr_str_fn):
6337 # expr_str() helper. Adds parentheses around expressions of type 'type_'.
6339 if expr.__class__ is tuple and expr[0] is type_:
6340 return "({})".format(expr_str(expr, sc_expr_str_fn))
6341 return expr_str(expr, sc_expr_str_fn)
6344 def _ordered_unique(lst):
6345 # Returns 'lst' with any duplicates removed, preserving order. This hacky
6346 # version seems to be a common idiom. It relies on short-circuit evaluation
6347 # and set.add() returning None, which is falsy.
6351 return [x for x in lst if x not in seen and not seen_add(x)]
6354 def _is_base_n(s, n):
6362 def _strcmp(s1, s2):
6363 # strcmp()-alike that returns -1, 0, or 1
6365 return (s1 > s2) - (s1 < s2)
6368 def _sym_to_num(sym):
6369 # expr_value() helper for converting a symbol to a number. Raises
6370 # ValueError for symbols that can't be converted.
6372 # For BOOL and TRISTATE, n/m/y count as 0/1/2. This mirrors 9059a3493ef
6373 # ("kconfig: fix relational operators for bool and tristate symbols") in
6374 # the C implementation.
6375 return sym.tri_value if sym.orig_type in _BOOL_TRISTATE else \
6376 int(sym.str_value, _TYPE_TO_BASE[sym.orig_type])
6379 def _touch_dep_file(path, sym_name):
6380 # If sym_name is MY_SYM_NAME, touches my/sym/name.h. See the sync_deps()
6383 sym_path = path + os.sep + sym_name.lower().replace("_", os.sep) + ".h"
6384 sym_path_dir = dirname(sym_path)
6385 if not exists(sym_path_dir):
6386 os.makedirs(sym_path_dir, 0o755)
6388 # A kind of truncating touch, mirroring the C tools
6390 sym_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644))
6393 def _save_old(path):
6394 # See write_config()
6397 # Import as needed, to save some startup time
6399 shutil.copyfile(src, dst)
6404 elif hasattr(os, "replace"):
6405 # Python 3 (3.3+) only. Best choice when available, because it
6406 # removes <filename>.old on both *nix and Windows.
6407 copy_fn = os.replace
6408 elif os.name == "posix":
6409 # Removes <filename>.old on POSIX systems
6412 # Fall back on copying
6416 copy_fn(path, path + ".old")
6418 # Ignore errors from 'path' missing as well as other errors.
6419 # <filename>.old file is usually more of a nice-to-have, and not worth
6420 # erroring out over e.g. if <filename>.old happens to be a directory or
6421 # <filename> is something like /dev/null.
6426 # Symbol/Choice.name_and_loc helper. Returns the "(defined at ...)" part of
6427 # the string. 'sc' is a Symbol or Choice.
6430 return "(defined at {})".format(
6431 ", ".join("{0.filename}:{0.linenr}".format(node)
6432 for node in sc.nodes))
6434 return "(undefined)"
6440 def _expr_depends_on(expr, sym):
6441 # Reimplementation of expr_depends_symbol() from mconf.c. Used to determine
6442 # if a submenu should be implicitly created. This also influences which
6443 # items inside choice statements are considered choice items.
6445 if expr.__class__ is not tuple:
6448 if expr[0] in _EQUAL_UNEQUAL:
6449 # Check for one of the following:
6450 # sym = m/y, m/y = sym, sym != n, n != sym
6452 left, right = expr[1:]
6455 left, right = right, left
6456 elif left is not sym:
6459 return (expr[0] is EQUAL and right is sym.kconfig.m or
6460 right is sym.kconfig.y) or \
6461 (expr[0] is UNEQUAL and right is sym.kconfig.n)
6463 return expr[0] is AND and \
6464 (_expr_depends_on(expr[1], sym) or
6465 _expr_depends_on(expr[2], sym))
6468 def _auto_menu_dep(node1, node2):
6469 # Returns True if node2 has an "automatic menu dependency" on node1. If
6470 # node2 has a prompt, we check its condition. Otherwise, we look directly
6473 return _expr_depends_on(node2.prompt[1] if node2.prompt else node2.dep,
6478 # "Flattens" menu nodes without prompts (e.g. 'if' nodes and non-visible
6479 # symbols with children from automatic menu creation) so that their
6480 # children appear after them instead. This gives a clean menu structure
6481 # with no unexpected "jumps" in the indentation.
6483 # Do not flatten promptless choices (which can appear "legitimately" if a
6484 # named choice is defined in multiple locations to add on symbols). It
6485 # looks confusing, and the menuconfig already shows all choice symbols if
6486 # you enter the choice at some location with a prompt.
6489 if node.list and not node.prompt and \
6490 node.item.__class__ is not Choice:
6492 last_node = node.list
6494 last_node.parent = node.parent
6495 if not last_node.next:
6497 last_node = last_node.next
6499 last_node.next = node.next
6500 node.next = node.list
6506 def _remove_ifs(node):
6507 # Removes 'if' nodes (which can be recognized by MenuNode.item being None),
6508 # which are assumed to already have been flattened. The C implementation
6509 # doesn't bother to do this, but we expose the menu tree directly, and it
6510 # makes it nicer to work with.
6513 while cur and not cur.item:
6520 while next and not next.item:
6528 # due to tricky Python semantics. The order matters.
6529 cur.next = cur = next
6532 def _finalize_choice(node):
6533 # Finalizes a choice, marking each symbol whose menu node has the choice as
6534 # the parent as a choice symbol, and automatically determining types if not
6541 if cur.item.__class__ is Symbol:
6542 cur.item.choice = choice
6543 choice.syms.append(cur.item)
6546 # If no type is specified for the choice, its type is that of
6547 # the first choice item with a specified type
6548 if not choice.orig_type:
6549 for item in choice.syms:
6551 choice.orig_type = item.orig_type
6554 # Each choice item of UNKNOWN type gets the type of the choice
6555 for sym in choice.syms:
6556 if not sym.orig_type:
6557 sym.orig_type = choice.orig_type
6560 def _check_dep_loop_sym(sym, ignore_choice):
6561 # Detects dependency loops using depth-first search on the dependency graph
6562 # (which is calculated earlier in Kconfig._build_dep()).
6566 # 1. Symbols/choices start out with _visited = 0, meaning unvisited.
6568 # 2. When a symbol/choice is first visited, _visited is set to 1, meaning
6569 # "visited, potentially part of a dependency loop". The recursive
6570 # search then continues from the symbol/choice.
6572 # 3. If we run into a symbol/choice X with _visited already set to 1,
6573 # there's a dependency loop. The loop is found on the call stack by
6574 # recording symbols while returning ("on the way back") until X is seen
6577 # 4. Once a symbol/choice and all its dependencies (or dependents in this
6578 # case) have been checked recursively without detecting any loops, its
6579 # _visited is set to 2, meaning "visited, not part of a dependency
6582 # This saves work if we run into the symbol/choice again in later calls
6583 # to _check_dep_loop_sym(). We just return immediately.
6585 # Choices complicate things, as every choice symbol depends on every other
6586 # choice symbol in a sense. When a choice is "entered" via a choice symbol
6587 # X, we visit all choice symbols from the choice except X, and prevent
6588 # immediately revisiting the choice with a flag (ignore_choice).
6590 # Maybe there's a better way to handle this (different flags or the
6593 if not sym._visited:
6594 # sym._visited == 0, unvisited
6598 for dep in sym._dependents:
6599 # Choices show up in Symbol._dependents when the choice has the
6600 # symbol in a 'prompt' or 'default' condition (e.g.
6601 # 'default ... if SYM').
6603 # Since we aren't entering the choice via a choice symbol, all
6604 # choice symbols need to be checked, hence the None.
6605 loop = _check_dep_loop_choice(dep, None) \
6606 if dep.__class__ is Choice \
6607 else _check_dep_loop_sym(dep, False)
6610 # Dependency loop found
6611 return _found_dep_loop(loop, sym)
6613 if sym.choice and not ignore_choice:
6614 loop = _check_dep_loop_choice(sym.choice, sym)
6616 # Dependency loop found
6617 return _found_dep_loop(loop, sym)
6619 # The symbol is not part of a dependency loop
6622 # No dependency loop found
6625 if sym._visited == 2:
6626 # The symbol was checked earlier and is already known to not be part of
6630 # sym._visited == 1, found a dependency loop. Return the symbol as the
6631 # first element in it.
6635 def _check_dep_loop_choice(choice, skip):
6636 if not choice._visited:
6637 # choice._visited == 0, unvisited
6641 # Check for loops involving choice symbols. If we came here via a
6642 # choice symbol, skip that one, as we'd get a false positive
6643 # '<sym FOO> -> <choice> -> <sym FOO>' loop otherwise.
6644 for sym in choice.syms:
6646 # Prevent the choice from being immediately re-entered via the
6647 # "is a choice symbol" path by passing True
6648 loop = _check_dep_loop_sym(sym, True)
6650 # Dependency loop found
6651 return _found_dep_loop(loop, choice)
6653 # The choice is not part of a dependency loop
6656 # No dependency loop found
6659 if choice._visited == 2:
6660 # The choice was checked earlier and is already known to not be part of
6664 # choice._visited == 1, found a dependency loop. Return the choice as the
6665 # first element in it.
6669 def _found_dep_loop(loop, cur):
6670 # Called "on the way back" when we know we have a loop
6672 # Is the symbol/choice 'cur' where the loop started?
6673 if cur is not loop[0]:
6674 # Nope, it's just a part of the loop
6675 return loop + (cur,)
6677 # Yep, we have the entire loop. Throw an exception that shows it.
6679 msg = "\nDependency loop\n" \
6680 "===============\n\n"
6683 if item is not loop[0]:
6684 msg += "...depends on "
6685 if item.__class__ is Symbol and item.choice:
6686 msg += "the choice symbol "
6688 msg += "{}, with definition...\n\n{}\n\n" \
6689 .format(item.name_and_loc, item)
6691 # Small wart: Since we reuse the already calculated
6692 # Symbol/Choice._dependents sets for recursive dependency detection, we
6693 # lose information on whether a dependency came from a 'select'/'imply'
6694 # condition or e.g. a 'depends on'.
6696 # This might cause selecting symbols to "disappear". For example,
6697 # a symbol B having 'select A if C' gives a direct dependency from A to
6698 # C, since it corresponds to a reverse dependency of B && C.
6700 # Always print reverse dependencies for symbols that have them to make
6701 # sure information isn't lost. I wonder if there's some neat way to
6704 if item.__class__ is Symbol:
6705 if item.rev_dep is not item.kconfig.n:
6706 msg += "(select-related dependencies: {})\n\n" \
6707 .format(expr_str(item.rev_dep))
6709 if item.weak_rev_dep is not item.kconfig.n:
6710 msg += "(imply-related dependencies: {})\n\n" \
6711 .format(expr_str(item.rev_dep))
6713 msg += "...depends again on " + loop[0].name_and_loc
6715 raise KconfigError(msg)
6718 def _decoding_error(e, filename, macro_linenr=None):
6719 # Gives the filename and context for UnicodeDecodeError's, which are a pain
6720 # to debug otherwise. 'e' is the UnicodeDecodeError object.
6722 # If the decoding error is for the output of a $(shell,...) command,
6723 # macro_linenr holds the line number where it was run (the exact line
6724 # number isn't available for decoding errors in files).
6728 "Malformed {} in {}\n"
6730 "Problematic data: {}\n"
6731 "Reason: {}".format(
6733 "'{}'".format(filename) if macro_linenr is None else
6734 "output from macro at {}:{}".format(filename, macro_linenr),
6735 e.object[max(e.start - 40, 0):e.end + 40],
6736 e.object[e.start:e.end],
6740 def _warn_verbose_deprecated(fn_name):
6742 "Deprecation warning: {0}()'s 'verbose' argument has no effect. Since "
6743 "Kconfiglib 12.0.0, the message is returned from {0}() instead, "
6744 "and is always generated. Do e.g. print(kconf.{0}()) if you want to "
6745 "want to show a message like \"Loaded configuration '.config'\" on "
6746 "stdout. The old API required ugly hacks to reuse messages in "
6747 "configuration interfaces.\n".format(fn_name))
6750 # Predefined preprocessor functions
6753 def _filename_fn(kconf, _):
6754 return kconf.filename
6757 def _lineno_fn(kconf, _):
6758 return str(kconf.linenr)
6761 def _info_fn(kconf, _, msg):
6762 print("{}:{}: {}".format(kconf.filename, kconf.linenr, msg))
6767 def _warning_if_fn(kconf, _, cond, msg):
6769 kconf._warn(msg, kconf.filename, kconf.linenr)
6774 def _error_if_fn(kconf, _, cond, msg):
6776 raise KconfigError("{}:{}: {}".format(
6777 kconf.filename, kconf.linenr, msg))
6782 def _shell_fn(kconf, _, command):
6783 import subprocess # Only import as needed, to save some startup time
6785 stdout, stderr = subprocess.Popen(
6786 command, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE
6791 stdout = stdout.decode(kconf._encoding)
6792 stderr = stderr.decode(kconf._encoding)
6793 except UnicodeDecodeError as e:
6794 _decoding_error(e, kconf.filename, kconf.linenr)
6797 kconf._warn("'{}' wrote to stderr: {}".format(
6798 command, "\n".join(stderr.splitlines())),
6799 kconf.filename, kconf.linenr)
6801 # Universal newlines with splitlines() (to prevent e.g. stray \r's in
6802 # command output on Windows), trailing newline removal, and
6803 # newline-to-space conversion.
6805 # On Python 3 versions before 3.6, it's not possible to specify the
6806 # encoding when passing universal_newlines=True to Popen() (the 'encoding'
6807 # parameter was added in 3.6), so we do this manual version instead.
6808 return "\n".join(stdout.splitlines()).rstrip("\n").replace("\n", " ")
6826 # Constant representing that there's no cached choice selection. This is
6827 # distinct from a cached None (no selection). Any object that's not None or a
6828 # Symbol will do. We test this with 'is'.
6829 _NO_CACHED_SELECTION = 0
6831 # Are we running on Python 2?
6832 _IS_PY2 = sys.version_info[0] < 3
6835 _UNAME_RELEASE = os.uname()[2]
6836 except AttributeError:
6837 # Only import as needed, to save some startup time
6839 _UNAME_RELEASE = platform.uname()[2]
6841 # The token and type constants below are safe to test with 'is', which is a bit
6842 # faster (~30% faster on my machine, and a few % faster for total parsing
6843 # time), even without assuming Python's small integer optimization (which
6844 # caches small integer objects). The constants end up pointing to unique
6845 # integer objects, and since we consistently refer to them via the names below,
6846 # we always get the same object.
6848 # Client code should use == though.
6850 # Tokens, with values 1, 2, ... . Avoiding 0 simplifies some checks by making
6851 # all tokens except empty strings truthy.
6905 # Keyword to token map, with the get() method assigned directly as a small
6908 "---help---": _T_HELP,
6909 "allnoconfig_y": _T_ALLNOCONFIG_Y,
6912 "choice": _T_CHOICE,
6913 "comment": _T_COMMENT,
6914 "config": _T_CONFIG,
6915 "def_bool": _T_DEF_BOOL,
6916 "def_hex": _T_DEF_HEX,
6917 "def_int": _T_DEF_INT,
6918 "def_string": _T_DEF_STRING,
6919 "def_tristate": _T_DEF_TRISTATE,
6920 "default": _T_DEFAULT,
6921 "defconfig_list": _T_DEFCONFIG_LIST,
6922 "depends": _T_DEPENDS,
6923 "endchoice": _T_ENDCHOICE,
6925 "endmenu": _T_ENDMENU,
6927 "grsource": _T_ORSOURCE, # Backwards compatibility
6928 "gsource": _T_OSOURCE, # Backwards compatibility
6934 "mainmenu": _T_MAINMENU,
6936 "menuconfig": _T_MENUCONFIG,
6937 "modules": _T_MODULES,
6939 "option": _T_OPTION,
6940 "optional": _T_OPTIONAL,
6941 "orsource": _T_ORSOURCE,
6942 "osource": _T_OSOURCE,
6943 "prompt": _T_PROMPT,
6945 "rsource": _T_RSOURCE,
6946 "select": _T_SELECT,
6947 "source": _T_SOURCE,
6948 "string": _T_STRING,
6949 "tristate": _T_TRISTATE,
6950 "visible": _T_VISIBLE,
6953 # The constants below match the value of the corresponding tokens to remove the
6954 # need for conversion
6958 COMMENT = _T_COMMENT
6965 UNEQUAL = _T_UNEQUAL
6967 LESS_EQUAL = _T_LESS_EQUAL
6968 GREATER = _T_GREATER
6969 GREATER_EQUAL = _T_GREATER_EQUAL
6977 GREATER_EQUAL: ">=",
6980 # Symbol/choice types. UNKNOWN is 0 (falsy) to simplify some checks.
6981 # Client code shouldn't rely on it though, as it was non-zero in
6985 TRISTATE = _T_TRISTATE
6993 TRISTATE: "tristate",
6999 # Used in comparisons. 0 means the base is inferred from the format of the
7008 # def_bool -> BOOL, etc.
7009 _DEF_TOKEN_TO_TYPE = {
7013 _T_DEF_STRING: STRING,
7014 _T_DEF_TRISTATE: TRISTATE,
7017 # Tokens after which strings are expected. This is used to tell strings from
7018 # constant symbol references during tokenization, both of which are enclosed in
7021 # Identifier-like lexemes ("missing quotes") are also treated as strings after
7022 # these tokens. _T_CHOICE is included to avoid symbols being registered for
7024 _STRING_LEX = frozenset({
7041 # Various sets for quick membership tests. Gives a single global lookup and
7042 # avoids creating temporary dicts/tuples.
7044 _TYPE_TOKENS = frozenset({
7052 _SOURCE_TOKENS = frozenset({
7059 _REL_SOURCE_TOKENS = frozenset({
7064 # Obligatory (non-optional) sources
7065 _OBL_SOURCE_TOKENS = frozenset({
7070 _BOOL_TRISTATE = frozenset({
7075 _BOOL_TRISTATE_UNKNOWN = frozenset({
7081 _INT_HEX = frozenset({
7086 _SYMBOL_CHOICE = frozenset({
7091 _MENU_COMMENT = frozenset({
7096 _EQUAL_UNEQUAL = frozenset({
7101 _RELATIONS = frozenset({
7110 # Helper functions for getting compiled regular expressions, with the needed
7111 # matching function returned directly as a small optimization.
7113 # Use ASCII regex matching on Python 3. It's already the default on Python 2.
7116 def _re_match(regex):
7117 return re.compile(regex, 0 if _IS_PY2 else re.ASCII).match
7120 def _re_search(regex):
7121 return re.compile(regex, 0 if _IS_PY2 else re.ASCII).search
7124 # Various regular expressions used during parsing
7126 # The initial token on a line. Also eats leading and trailing whitespace, so
7127 # that we can jump straight to the next token (or to the end of the line if
7128 # there is only one token).
7130 # This regex will also fail to match for empty lines and comment lines.
7132 # '$' is included to detect preprocessor variable assignments with macro
7133 # expansions in the left-hand side.
7134 _command_match = _re_match(r"\s*([A-Za-z0-9_$-]+)\s*")
7136 # An identifier/keyword after the first token. Also eats trailing whitespace.
7137 # '$' is included to detect identifiers containing macro expansions.
7138 _id_keyword_match = _re_match(r"([A-Za-z0-9_$/.-]+)\s*")
7140 # A fragment in the left-hand side of a preprocessor variable assignment. These
7141 # are the portions between macro expansions ($(foo)). Macros are supported in
7142 # the LHS (variable name).
7143 _assignment_lhs_fragment_match = _re_match("[A-Za-z0-9_-]*")
7145 # The assignment operator and value (right-hand side) in a preprocessor
7146 # variable assignment
7147 _assignment_rhs_match = _re_match(r"\s*(=|:=|\+=)\s*(.*)")
7149 # Special characters/strings while expanding a macro ('(', ')', ',', and '$(')
7150 _macro_special_search = _re_search(r"\(|\)|,|\$\(")
7152 # Special characters/strings while expanding a string (quotes, '\', and '$(')
7153 _string_special_search = _re_search(r'"|\'|\\|\$\(')
7155 # Special characters/strings while expanding a symbol name. Also includes
7156 # end-of-line, in case the macro is the last thing on the line.
7157 _name_special_search = _re_search(r'[^A-Za-z0-9_$/.-]|\$\(|$')
7159 # A valid right-hand side for an assignment to a string symbol in a .config
7160 # file, including escaped characters. Extracts the contents.
7161 _conf_string_match = _re_match(r'"((?:[^\\"]|\\.)*)"')