tools/buildman/kconfiglib.py

2 # SPDX-License-Identifier:	ISC
8 # information from Kconfig-based configuration systems. To view the
15 #  $ pydoc -w kconfiglib
25 Kconfig-based configuration systems. Features include the following:
27  - Symbol values and properties can be looked up and values assigned
29  - .config files can be read and written.
30  - Expressions can be evaluated in the context of a Kconfig configuration.
31  - Relations between symbols can be quickly determined, such as finding all
33  - Highly compatible with the scripts/kconfig/*conf utilities. The test suite
41 Using the 'scriptconfig' target ensures that required environment variables
45 Linux 4.1.0-rc5, this is always "Kconfig" from the kernel top-level directory.
55 works well too, and might give a nice speedup for long-running jobs.
97     their values. Creating any number of Config objects -- including for
98     different architectures -- is safe; Kconfiglib has no global state."""
111            from the top-level directory, as environment variables will make
119            should be the top-level directory of the kernel tree. $-references
124            by the Linux makefiles to the top-level kernel directory. A default
178         # The symbol with "option defconfig_list" set, containing a list of
211         # of that line. The purpose is to avoid having to re-tokenize the line,
241         containing architecture-specific code."""
279         """Returns the text of the 'mainmenu' statement (with $-references to
287         file in the list given in a symbol having 'option defconfig_list' set.
288         $-references to symbols will be expanded ("$FOO bar" -> "foo bar" if
299         the --defconfig=<defconfig> option when calling the C implementation of
333         """Returns a list of symbols from the configuration. An alternative for
344         all_symbols (default: True): If True, all symbols -- including special
345            and undefined symbols -- will be included in the result, in an
350         return list(self.syms.values()) if all_symbols else self.kconfig_syms
366         """Returns a list containing all choice statements in the
371         """Returns a list containing all menus in the configuration, in the
376         """Returns a list containing all comments in the configuration, in the
381         """Returns a list containing the items (symbols, menus, choices, and
382         comments) at the top level of the configuration -- that is, all items
396         filename: The .config file to load. $-references to existing
399           need to refer to the top-level kernel directory with "$srctree".
404         Returns a list or warnings (hopefully empty)
431                 self.config_header = self.config_header[:-1]
466                     if len(val) < 2 or val[-1] != '"':
472                     val = val[1:-1].replace('\\"', '"').replace("\\\\", "\\")
537         """Returns the value of the expression 's' -- where 's' is represented
538         as a string -- in the context of the configuration. Raises
545         non-bool, non-tristate symbols, use Symbol.get_value().
613         """Parses the Kconfig file 'filename'. Returns a list with the Items in
621         menu, or choice statement. Returns a list with the Items in the block.
624           Kconfig language is line-based in practice.
637         res (default: None): The list to add items to. If None, a new list is
870                 # Find first non-blank (not all-space) line and get its
878                     # If the first non-empty lines has zero indent, there is no
884                 # The help text goes on till the first non-empty line with less
901                 target = tokens.get_next()
903                 stmt.referenced_syms.add(target)
904                 stmt.selected_syms.add(target)
907                     new_selects.append((target,
911                     new_selects.append((target, None))
964                                    "non-existent environment variable {1} and "
992                                    "(Note that modules are still supported -- "
1086                 new_selects = [(target, _make_and(cond_expr, depends_on_expr))
1087                                for target, cond_expr in new_selects]
1091                 for target, cond in new_selects:
1092                     target.rev_dep = _make_or(target.rev_dep,
1099         top-down approach. The result has the form
1117            'm && MODULES' -- see parse_val_and_cond().
1121         <expr> -> <symbol>
1130         # through the top-down parser in _parse_expr_rec(), which is tedious
1144             # Common case -- no need for an OR node since it's just a single
1155             # Common case -- no need for an AND node since it's just a single
1220             # command_chars = [A-Za-z0-9_]. Then
1221             #  - leading non-command_chars characters are ignored, and
1222             #  - the first token consists the following one or more
1224             # This is why things like "----help--" are accepted.
1230                 # Avoid junk after "help", e.g. "---", being registered as a
1323                         if end == -1:
1354             previous = tokens[-1]
1361         won't be added to the symbol table if it does not exist -- this is for
1400             # Non-bool/tristate symbols are always "n" in a tristate sense,
1421             # short-circuiting "n" case in the loop.
1440             # short-circuiting "y" case in the loop.
1485         #  - Any symbols whose prompts, default values, rev_dep (select
1487         #  - Any symbols that belong to the same choice statement as the symbol
1490         #  - Any symbols in a choice statement that depends on the symbol
1569         """Expands $-references to symbols in 's' to symbol values, or to the
1643         # Build additional-dependencies-from-menus-and-ifs string
1649         # Symbol-specific stuff
1687                 for target, cond_expr in sc.orig_selects:
1689                         selects_str_rows.append(" {0}".format(target.name))
1692                           " {0} if {1}".format(target.name,
1714                           "Reverse (select-related) dependencies:",
1725         # Choice-specific stuff
1803     """Represents a configuration symbol - e.g. FOO for
1830         """Returns a list of prompts defined for the symbol, in the order they
1831         appear in the configuration files. Returns the empty list for symbols
1834         This list will have a single entry for the vast majority of symbols
1852         """Returns a list of (filename, linenr) tuples, where filename (string)
1854         the vast majority of symbols this list will only contain one element.
1867         """Returns a list of (filename, linenr) tuples, where filename (string)
1912             # The visibility and mode (modules-only or single-selection) of
1950                 # Reverse (select-related) dependencies take precedence
2102         cannot be modified (see is_modifiable()), returns the empty list.
2104         Otherwise, returns a list containing the user values that can be
2130         Example (assuming we're running with modules enabled -- i.e., MODULES
2159         Having visibility be tri-valued ensures that e.g. a symbol cannot be
2297         """Symbol constructor -- not intended to be called directly by
2306         self.rev_dep = "n" # Reverse (select-related) dependencies
2342         # transitive closure) is calculated on an as-needed basis in
2352         # Caches the total list of dependent symbols. Calculated in
2494         Note that this is an internal API -- it's probably of limited
2563         """Returns a list containing the items (symbols, menus, choice
2583         """Returns a list containing the symbols in the menu, in the same order
2632         """Menu constructor -- not intended to be called directly by
2668     "n" - The choice is not visible and no symbols can be selected.
2670     "m" - Any number of symbols can be set to "m". The rest will be "n". This
2674     "y" - One symbol will be "y" while the rest are "n".
2696         as of Linux 3.7.0-rc8."""
2704         """Returns a list of prompts defined for the choice, in the order they
2705         appear in the configuration files. Returns the empty list for choices
2708         This list will have a single entry for the vast majority of choices
2727         """Returns a list of (filename, linenr) tuples, where filename (string)
2729         the vast majority of choices (all of them as of Linux 3.7.0-rc8) this
2730         list will only contain one element, but its possible for named choices
2779         """If the choice is in "y" mode and has a user-selected symbol, returns
2787         of Linux 3.7.0-rc8, in drivers/usb/gadget/Kconfig)."""
2791         """Returns a list containing the choice's symbols.
2796         choice 'depends on' the symbol preceding it, or if you put non-symbol
2799         As of Linux 3.7.0-rc8, this seems to be used intentionally in one
2847         """Choice constructor -- not intended to be called directly by
2855         self.block = None # List of contained items
2864         # Choice._determine_actual_symbols()) This list holds the "actual"
2904         complexity is to be future-proof in the event that
2918                 if item._has_auto_menu_dep_on(stack[-1]):
3014         """Comment constructor -- not intended to be called directly by
3080     """Class for working with sequences in a stream-like fashion; handy for
3137             line = line[:-2] + self.lines[self.linenr]
3148             line = line[:-2] + self.lines[linenr]
3152         self.linenr -= 1
3154             self.linenr -= 1
3157         """Removes lines up to and including the next non-blank (not all-space)
3158         line and returns it. Returns None if there are no more non-blank
3173     or Choice 'sc' -- the logic is nearly identical."""
3182         # Promote "m" to "y" if we're dealing with a non-tristate
3269     """Returns a list of .config strings for a block (list) of items."""
3271     # Collect the substrings in a list and later use join() instead of += to
3284     in lst and produces a list where op has been inserted between the
3343     return len(line) - len(line.lstrip())
3445 # Tokens after which identifier-like lexemes are treated as strings. T_CHOICE
3456 _id_keyword_re_match = re.compile(r"\s*([\w./-]+)\s*").match
3462 # Regular expression for finding $-references to symbols in strings
3463 _sym_ref_re_search = re.compile(r"\$[A-Za-z0-9_]+").search
3489 # Printing-related stuff