chore(kconfig_new): Add kconfig_new tools

tools/kconfig_new/confgen.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python
+#
+# Command line tool to take in ESP-IDF sdkconfig files with project
+# settings and output data in multiple formats (update config, generate
+# header file, generate .cmake include file, documentation, etc).
+#
+# Used internally by the ESP-IDF build system. But designed to be
+# non-IDF-specific.
+#
+# Copyright 2018 Espressif Systems (Shanghai) PTE LTD
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import argparse
+import sys
+import os
+import os.path
+import tempfile
+import json
+
+import gen_kconfig_doc
+import kconfiglib
+
+__version__ = "0.1"
+
+def main():
+    parser = argparse.ArgumentParser(description='confgen.py v%s - Config Generation Tool' % __version__, prog=os.path.basename(sys.argv[0]))
+
+    parser.add_argument('--config',
+                        help='Project configuration settings',
+                        nargs='?',
+                        default=None)
+
+    parser.add_argument('--defaults',
+                        help='Optional project defaults file, used if --config file doesn\'t exist',
+                        nargs='?',
+                        default=None)
+
+    parser.add_argument('--create-config-if-missing',
+                        help='If set, a new config file will be saved if the old one is not found',
+                        action='store_true')
+
+    parser.add_argument('--kconfig',
+                        help='KConfig file with config item definitions',
+                        required=True)
+
+    parser.add_argument('--output', nargs=2, action='append',
+                        help='Write output file (format and output filename)',
+                        metavar=('FORMAT', 'FILENAME'),
+                        default=[])
+
+    parser.add_argument('--env', action='append', default=[],
+                        help='Environment to set when evaluating the config file', metavar='NAME=VAL')
+
+    args = parser.parse_args()
+
+    for fmt, filename in args.output:
+        if not fmt in OUTPUT_FORMATS.keys():
+            print("Format '%s' not recognised. Known formats: %s" % (fmt, OUTPUT_FORMATS))
+            sys.exit(1)
+
+    try:
+       args.env = [ (name,value) for (name,value) in ( e.split("=",1) for e in args.env) ]
+    except ValueError:
+       print("--env arguments must each contain =. To unset an environment variable, use 'ENV='")
+       sys.exit(1)
+
+    for name, value in args.env:
+        os.environ[name] = value
+
+    config = kconfiglib.Kconfig(args.kconfig)
+
+    if args.defaults is not None:
+        # always load defaults first, so any items which are not defined in that config
+        # will have the default defined in the defaults file
+        if not os.path.exists(args.defaults):
+            raise RuntimeError("Defaults file not found: %s" % args.defaults)
+        config.load_config(args.defaults)
+
+    if args.config is not None:
+        if os.path.exists(args.config):
+            config.load_config(args.config)
+        elif args.create_config_if_missing:
+            print("Creating config file %s..." % args.config)
+            config.write_config(args.config)
+        elif args.default is None:
+            raise RuntimeError("Config file not found: %s" % args.config)
+
+        for output_type, filename in args.output:
+            temp_file = tempfile.mktemp(prefix="confgen_tmp")
+            try:
+                output_function = OUTPUT_FORMATS[output_type]
+                output_function(config, temp_file)
+                update_if_changed(temp_file, filename)
+            finally:
+                try:
+                    os.remove(temp_file)
+                except OSError:
+                    pass
+
+
+def write_config(config, filename):
+    CONFIG_HEADING = """#
+# Automatically generated file. DO NOT EDIT.
+# Espressif IoT Development Framework (ESP-IDF) Project Configuration
+#
+"""
+    config.write_config(filename, header=CONFIG_HEADING)
+
+def write_header(config, filename):
+    CONFIG_HEADING = """/*
+ * Automatically generated file. DO NOT EDIT.
+ * Espressif IoT Development Framework (ESP-IDF) Configuration Header
+ */
+#pragma once
+"""
+    config.write_autoconf(filename, header=CONFIG_HEADING)
+
+def write_cmake(config, filename):
+    with open(filename, "w") as f:
+        write = f.write
+        prefix = config.config_prefix
+
+        write("""#
+# Automatically generated file. DO NOT EDIT.
+# Espressif IoT Development Framework (ESP-IDF) Configuration cmake include file
+#
+""")
+        def write_node(node):
+            sym = node.item
+            if not isinstance(sym, kconfiglib.Symbol):
+                return
+
+            # Note: str_value calculates _write_to_conf, due to
+            # internal magic in kconfiglib...
+            val = sym.str_value
+            if sym._write_to_conf:
+                if sym.orig_type in (kconfiglib.BOOL, kconfiglib.TRISTATE) and val == "n":
+                    val = ""  # write unset values as empty variables
+                write("set({}{} \"{}\")\n".format(
+                    prefix, sym.name, val))
+        config.walk_menu(write_node)
+
+def write_json(config, filename):
+    config_dict = {}
+
+    def write_node(node):
+        sym = node.item
+        if not isinstance(sym, kconfiglib.Symbol):
+            return
+
+        val = sym.str_value  # this calculates _write_to_conf, due to kconfiglib magic
+        if sym._write_to_conf:
+            if sym.type in [ kconfiglib.BOOL, kconfiglib.TRISTATE ]:
+                val = (val != "n")
+            elif sym.type == kconfiglib.HEX:
+                val = int(val, 16)
+            elif sym.type == kconfiglib.INT:
+                val = int(val)
+            config_dict[sym.name] = val
+    config.walk_menu(write_node)
+    with open(filename, "w") as f:
+        json.dump(config_dict, f, indent=4, sort_keys=True)
+
+def update_if_changed(source, destination):
+    with open(source, "r") as f:
+        source_contents = f.read()
+    if os.path.exists(destination):
+        with open(destination, "r") as f:
+            dest_contents = f.read()
+        if source_contents == dest_contents:
+            return  # nothing to update
+
+    with open(destination, "w") as f:
+        f.write(source_contents)
+
+
+OUTPUT_FORMATS = {
+    "config" : write_config,
+    "header" : write_header,
+    "cmake" : write_cmake,
+    "docs" : gen_kconfig_doc.write_docs,
+    "json" : write_json,
+    }
+
+class FatalError(RuntimeError):
+    """
+    Class for runtime errors (not caused by bugs but by user input).
+    """
+    pass
+
+if __name__ == '__main__':
+    try:
+        main()
+    except FatalError as e:
+        print("A fatal error occurred: %s" % e)
+        sys.exit(2)

tools/kconfig_new/gen_kconfig_doc.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# gen_kconfig_doc - confgen.py support for generating ReST markup documentation
+#
+# For each option in the loaded Kconfig (e.g. 'FOO'), CONFIG_FOO link target is
+# generated, allowing options to be referenced in other documents
+# (using :ref:`CONFIG_FOO`)
+#
+# Copyright 2017-2018 Espressif Systems (Shanghai) PTE LTD
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+import kconfiglib
+
+# Indentation to be used in the generated file
+INDENT = '    '
+
+# Characters used when underlining section heading
+HEADING_SYMBOLS = '#*=-^"+'
+
+# Keep the heading level in sync with api-reference/kconfig.rst
+INITIAL_HEADING_LEVEL = 3
+MAX_HEADING_LEVEL = len(HEADING_SYMBOLS)-1
+
+def write_docs(config, filename):
+    """ Note: writing .rst documentation ignores the current value
+    of any items. ie the --config option can be ignored.
+    (However at time of writing it still needs to be set to something...) """
+    with open(filename, "w") as f:
+        config.walk_menu(lambda node: write_menu_item(f, node))
+
+
+def get_breadcrumbs(node):
+    # this is a bit wasteful as it recalculates each time, but still...
+    result = []
+    node = node.parent
+    while node.parent:
+        if node.prompt:
+            result = [ node.prompt[0] ] + result
+        node = node.parent
+    return " > ".join(result)
+
+def get_heading_level(node):
+    # bit wasteful also
+    result = INITIAL_HEADING_LEVEL
+    node = node.parent
+    while node.parent:
+        result += 1
+        if result == MAX_HEADING_LEVEL:
+            return MAX_HEADING_LEVEL
+        node = node.parent
+    return result
+
+def format_rest_text(text, indent):
+    # Format an indented text block for use with ReST
+    text = indent + text.replace('\n', '\n' + indent)
+    # Escape some characters which are inline formatting in ReST
+    text = text.replace("*", "\\*")
+    text = text.replace("_", "\\_")
+    text += '\n'
+    return text
+
+def write_menu_item(f, node):
+    if not node.prompt:
+        return  # Don't do anything for invisible menu items
+
+    if isinstance(node.parent.item, kconfiglib.Choice):
+        return  # Skip choice nodes, they are handled as part of the parent (see below)
+
+    try:
+        name = node.item.name
+    except AttributeError:
+        name = None
+
+    try:
+        is_menu = node.item == kconfiglib.MENU or node.is_menuconfig
+    except AttributeError:
+        is_menu = False  # not all MenuNodes have is_menuconfig for some reason
+
+    ## Heading
+    if name:
+        title = name
+        # add link target so we can use :ref:`CONFIG_FOO`
+        f.write('.. _CONFIG_%s:\n\n' % name)
+    else:
+        title = node.prompt[0]
+
+    # if no symbol name, use the prompt as the heading
+    if True or is_menu:
+        f.write('%s\n' % title)
+        f.write(HEADING_SYMBOLS[get_heading_level(node)] * len(title))
+        f.write('\n\n')
+    else:
+        f.write('**%s**\n\n\n' % title)
+
+    if name:
+        f.write('%s%s\n\n' % (INDENT, node.prompt[0]))
+        f.write('%s:emphasis:`Found in: %s`\n\n' % (INDENT, get_breadcrumbs(node)))
+
+    try:
+        if node.help:
+            # Help text normally contains newlines, but spaces at the beginning of
+            # each line are stripped by kconfiglib. We need to re-indent the text
+            # to produce valid ReST.
+            f.write(format_rest_text(node.help, INDENT))
+    except AttributeError:
+        pass  # No help
+
+    if isinstance(node.item, kconfiglib.Choice):
+        f.write('%sAvailable options:\n' % INDENT)
+        choice_node = node.list
+        while choice_node:
+            # Format available options as a list
+            f.write('%s- %-20s (%s)\n' % (INDENT * 2, choice_node.prompt[0], choice_node.item.name))
+            if choice_node.help:
+                HELP_INDENT = INDENT * 2
+                fmt_help = format_rest_text(choice_node.help, '  ' + HELP_INDENT)
+                f.write('%s  \n%s\n' % (HELP_INDENT, fmt_help))
+            choice_node = choice_node.next
+
+        f.write('\n\n')
+
+
+if __name__ == '__main__':
+    print("Run this via 'confgen.py --output doc FILENAME'")
+